코딩 에이전트용 프롬프트 작성법, 막히는 요청 줄이기: Claude Code에서 바로 먹히는 요청 구조

코딩 에이전트용 프롬프트 작성법, 막히는 요청 줄이기의 핵심은 “무엇을 만들지”보다 “어디까지 건드려도 되는지”를 먼저 알려주는 것입니다. Claude Code, Cursor, GitHub Copilot 같은 에이전트는 똑똑하지만, 범위가 흐리면 엉뚱한 파일을 수정하거나 이미 맞는 코드를 다시 갈아엎습니다.

오늘 작업 중 막힌 요청 하나를 골라 목표·현재 상태·제약·확인 방법·응답 방식 5줄로 다시 작성해 보세요.

제가 작은 Next.js 관리자 화면과 API 라우트를 고칠 때 가장 효과를 본 방식은 간단했습니다. 목표 → 현재 상태 → 제약 → 확인 방법 → 출력 형식 순서로 적는 것입니다. 이 다섯 줄만 있어도 “왜 계속 막히지?” 싶은 요청이 꽤 줄어듭니다.

에이전트가 막히는 이유는 대부분 ‘추론 부족’이 아니라 ‘작업 계약 부족’입니다

사람 개발자에게 “로그인 좀 고쳐줘”라고만 말하면 먼저 질문이 돌아옵니다. 그런데 코딩 에이전트는 질문 대신 전체 인증 로직을 훑고, 추측으로 수정안을 만듭니다. 여기서 시간과 토큰이 새기 시작합니다.

특히 Claude Code는 리포지토리를 넓게 탐색하는 능력이 좋고, Cursor는 편집 중인 파일 맥락을 빠르게 반영합니다. 둘 다 강점이 있지만, 요청이 애매하면 “필요 이상으로 큰 변경”을 만들 수 있습니다.

좋은 요청은 코드보다 먼저 ‘경계선’을 정합니다

제가 자주 쓰는 첫 문장은 이런 식입니다.

목표는 /admin/users 페이지의 검색 필터 버그를 고치는 것입니다. 이번 작업에서는 UI 레이아웃과 인증 로직은 건드리지 말고, app/admin/users/page.tsx와 관련된 쿼리 파라미터 처리만 확인해 주세요.

이렇게 쓰면 에이전트가 해야 할 일과 하지 말아야 할 일을 동시에 압니다. “수정해줘”보다 “수정하지 말아야 할 것”이 더 중요할 때가 많습니다.

제가 쓰는 5줄 프롬프트 템플릿

아래 구조는 Claude Code, Cursor, ChatGPT의 코드 해석 모드에 모두 적용하기 좋습니다. 긴 기획서가 아니라 작업 지시서에 가깝게 쓰는 것이 포인트입니다.

목표: [무엇을 고칠지/만들지 한 문장]
현재 상태: [에러 메시지, 재현 경로, 관련 파일]
제약: [건드리면 안 되는 파일, 유지해야 할 동작]
확인 방법: [npm test, pnpm build, 특정 화면에서 확인]
응답 방식: [변경 계획 먼저 / diff 중심 / 명령어 포함]

가상의 예시: Stripe 결제 성공 후 리다이렉트가 안 될 때

예를 들어 SaaS 대시보드에서 Stripe 결제는 성공했는데 /billing/success로 이동하지 않는다고 해보겠습니다. 이때 나쁜 요청은 “결제 리다이렉트 고쳐줘”입니다.

더 나은 요청은 다음과 같습니다.

목표: Stripe Checkout 결제 성공 후 /billing/success로 이동하지 않는 문제를 고쳐주세요.
현재 상태: 결제는 성공하고 Stripe Dashboard에도 결제 내역이 남습니다. 하지만 앱에서는 기존 /billing 화면에 머뭅니다. 관련 파일은 app/api/checkout/route.ts, app/billing/page.tsx입니다.
제약: 가격 플랜 UI와 webhook 검증 로직은 바꾸지 마세요.
확인 방법: 로컬에서 checkout session 생성 URL의 success_url 값을 확인하고, 변경 후 필요한 테스트 명령을 알려주세요.
응답 방식: 먼저 원인 후보 2개를 말한 뒤, 최소 수정 diff를 제안해 주세요.

이 정도만 적어도 에이전트는 “전체 결제 시스템 재작성”이 아니라 success_url, 환경 변수, 라우팅 경로를 중심으로 좁혀 봅니다. 실제 결과는 프로젝트 구조와 SDK 버전에 따라 달라질 수 있습니다.

도구별로 프롬프트를 조금 다르게 써야 합니다

같은 요청도 도구마다 잘 먹히는 형태가 다릅니다. 아래 표는 제가 코딩 에이전트를 고를 때 기준으로 삼는 차이입니다.

누구에게 어떤 작성 방식이 맞을까

혼자 만드는 빌더라면: “최소 변경”을 강하게 적으세요

1인 프로젝트에서는 속도가 중요하지만, 예상 밖의 수정이 나중에 더 큰 비용이 됩니다. “새 라이브러리 추가 금지”, “DB 스키마 변경 금지”, “기존 API 응답 형식 유지” 같은 문장을 자주 넣는 편이 안전합니다.

팀 코드베이스라면: 리뷰 가능한 출력이 먼저입니다

팀에서는 에이전트가 바로 코드를 바꾸기보다 계획을 먼저 내게 하는 편이 좋습니다. “수정 전 변경 계획을 5줄 이하로 설명하고, 승인 후 diff를 작성해줘”라고 하면 PR 리뷰가 쉬워집니다.

자주 하는 실수: 에러 메시지를 요약해서 주는 것

“빌드가 안 됨”보다 원문 로그 20줄이 낫습니다. 에이전트는 에러 코드, 파일 경로, 타입 이름에서 단서를 찾습니다. 다만 토큰을 아끼려면 전체 로그를 붙이기 전에 마지막 에러 블록과 실행한 명령어를 먼저 주세요.

또 하나는 한 번에 기능 추가, 버그 수정, 리팩터링을 모두 시키는 것입니다. 이 경우 실패 원인을 추적하기 어렵습니다. 먼저 재현 가능한 버그를 고치고, 그 다음 리팩터링을 요청하세요.

작업 전 30초 체크리스트

• 관련 파일명을 2~5개로 좁혔는가?
• 바꾸면 안 되는 영역을 적었는가?
• 성공 여부를 확인할 명령어가 있는가?
• 에이전트에게 바로 수정할지, 계획부터 낼지 정했는가?
• 새 패키지 설치가 필요한 경우 허용 여부를 밝혔는가?

FAQ

프롬프트를 영어로 써야 더 잘 되나요?

꼭 그렇지는 않습니다. 파일명, 에러 메시지, 함수명은 그대로 두고 설명은 한국어로 해도 충분히 작동합니다. 다만 라이브러리 옵션명이나 공식 문서 문구는 영어 원문을 유지하는 편이 좋습니다.

Claude Code와 Cursor 중 어디에 먼저 요청하는 게 좋나요?

리포 전체를 훑어 원인을 찾아야 하면 Claude Code가 편하고, 현재 열어둔 컴포넌트를 빠르게 고치려면 Cursor가 빠릅니다. 처음에는 분석과 계획을 Claude Code에 맡기고, 세부 편집은 Cursor에서 하는 조합도 실용적입니다.

에이전트가 계속 같은 실수를 반복하면 어떻게 하나요?

“다시 해줘”라고 하지 말고 실패한 이유를 프롬프트에 추가하세요. 예를 들어 “이전 답변은 인증 미들웨어를 수정했지만, 이번에는 라우트 파일만 확인해 주세요”처럼 방향을 좁혀야 합니다.

오늘 바로 할 다음 행동

다음 요청부터는 긴 설명을 쓰려고 애쓰기보다, 위 5줄 템플릿에 현재 작업을 끼워 넣어보세요. 특히 제약과 확인 방법을 쓰는 순간 에이전트의 답변 품질이 달라집니다.

monstereae에서는 Claude Code, Cursor, MCP를 실제 빌더 워크플로에 붙이는 글을 계속 정리할 예정입니다. 지금 쓰는 프로젝트에서 반복되는 작업 하나를 골라, 오늘은 “수정 범위가 좁은 프롬프트”로 다시 요청해 보세요.

관련 링크

• ai 코딩 구독 요금 비교: Claude Code·Cursor·Copilot, 빌드용으로 돈값 하는 조합
• claude code artifacts, 웹 미리보기 대신 파일로 남기는 실전 작업법
• claude code 모델 추천: 실제 빌드 작업에서 Sonnet과 Opus를 나눠 쓰는 기준
• 관련 태그 더 보기
• 카테고리 더 보기
• 검색 결과 더 보기
• 참고 링크