효과적인 프롬프트 작성법

🎯 학습 목표

이 강을 마치면 클로드 코드에게 원하는 결과를 정확히 전달하는 프롬프트 작성법을 익힐 수 있습니다. 구체적인 요청과 모호한 요청의 차이를 이해하고, 파일 위치를 명시하는 방법과 단계적으로 요청하는 전략까지 실전에 바로 적용할 수 있게 됩니다.

💡 왜 코딩 작업에서는 구체성이 더 중요한가

이 섹션에서는 코딩 프롬프트에서 구체성이 왜 특히 중요한지 살펴보겠습니다. 클로드 코드 공식 문서는 "클로드가 여러분의 프로젝트에 대해 아무것도 모른다고 가정하라"는 원칙을 강조합니다. 일반 대화에서는 다소 모호한 요청도 문맥으로 보완되지만, 코드는 한 글자만 달라져도 동작이 완전히 바뀔 수 있기 때문에 지시가 정밀할수록 결과의 정확도가 크게 높아집니다.

예를 들어 "로그인 기능 고쳐줘"라는 요청은 어떤 파일의 어떤 부분을, 어떤 문제 때문에, 어떻게 고쳐야 하는지 전혀 알려주지 않습니다. 반면 "src/auth/login.ts의 validateEmail 함수에서, 이메일에 대문자가 섞이면 검증에 실패하는 버그를 고쳐줘"처럼 구체적으로 말하면 훨씬 정확한 수정을 받을 수 있습니다.

이런 차이는 일반 채팅형 AI 서비스에서도 마찬가지지만, 클로드 코드에서는 그 영향이 훨씬 직접적입니다. 채팅에서는 결과가 마음에 안 들면 다시 설명하고 새 답을 받으면 그만이지만, 클로드 코드는 실제 파일을 직접 수정하기 때문에 모호한 요청으로 인한 오해가 곧바로 원치 않는 코드 변경으로 이어질 수 있습니다.

💬 구체적인 요청을 만드는 핵심 요소

이 섹션에서는 구체적인 프롬프트를 만드는 요소를 정리하겠습니다.

요소	모호한 예	구체적인 예
대상 위치	"이 함수"	"src/utils/format.ts의 formatDate 함수"
문제 상황	"안 돼"	"음수를 넣으면 NaN이 반환됨"
원하는 동작	"고쳐줘"	"음수면 0을 반환하도록"
제약 조건	(없음)	"다른 함수의 동작은 그대로 유지"

특히 대상 위치를 파일경로:줄번호 형식으로 명시하는 습관이 유용합니다. "src/api/user.ts:42의 코드를 봐줘"처럼 말하면, 클로드 코드가 파일 전체를 뒤지지 않고 정확한 위치로 바로 접근해 훨씬 빠르고 정확하게 응답합니다. 이 표기법은 이후 강의에서도 계속 등장하니 지금부터 습관을 들여두면 좋습니다.

💻 실전 사례 — 모호한 요청을 구체적으로 바꾸기

이 섹션에서는 실제 개발 상황에서 요청을 어떻게 구체화하는지 살펴보겠습니다.

[모호한 요청]
회원가입 페이지에 유효성 검사 추가해줘.

[구체적인 요청]
src/pages/Signup.tsx의 회원가입 폼에 다음 유효성 검사를 추가해줘.
- 이메일: 형식이 올바른지 확인
- 비밀번호: 8자 이상, 숫자와 특수문자 각 1개 이상 포함
- 확인란: 비밀번호와 일치하는지 확인
에러 메시지는 각 입력창 아래에 빨간색 텍스트로 표시해줘.
기존 폼 제출 로직(onSubmit 함수)은 건드리지 말고 검사 로직만 추가해줘.
동일한 검증 규칙을 재사용할 수 있게 별도 함수로 분리해줘.

구체적인 요청은 대상 파일, 검증해야 할 세 가지 규칙, 표시 방식, 그리고 건드리지 말아야 할 부분까지 명시했습니다. 이렇게 하면 클로드 코드가 임의로 다른 부분까지 리팩토링하거나, 검증 규칙을 다르게 해석할 여지가 크게 줄어듭니다.

버그 수정 요청도 같은 원리로 구체화할 수 있습니다.

[모호한 요청]
장바구니 계산이 이상해요.

[구체적인 요청]
src/features/cart/calculateTotal.ts에서 할인 쿠폰을 적용하면
총액이 음수가 되는 버그가 있어. 쿠폰 할인 금액이 상품 총액보다
클 경우, 총액이 0 밑으로 내려가지 않도록 고쳐줘. 재현 방법:
상품 총액 5000원에 10000원짜리 쿠폰을 적용하면 재현됨.

구체적인 요청은 문제가 발생하는 정확한 파일, 재현 조건, 원하는 동작까지 담고 있어 클로드 코드가 곧바로 원인을 찾아 수정할 수 있게 해줍니다. "이상해요"라는 표현만으로는 어떤 조건에서 어떻게 이상한지 전혀 알 수 없다는 점과 대조적입니다.

⚠️ 자주 하는 실수 / 주의점

실수 1 — 파일이나 함수 이름 없이 "이 부분"이라고만 지칭하는 것. 여러 파일을 오가며 작업 중이라면 "이 부분"이 어디를 가리키는지 클로드 코드가 잘못 추측할 수 있습니다. 항상 구체적인 파일명이나 함수명을 언급해야 합니다. 확실하지 않다면 먼저 "이 기능은 어느 파일에 있어?"라고 물어 확인한 뒤 본격적인 요청을 이어가는 것도 좋은 방법입니다.

실수 2 — 배경 설명 없이 결과만 요구하는 것. "왜 이렇게 바꿔야 하는지"에 대한 맥락(비즈니스 요구사항, 기존 버그 상황 등)을 함께 제공하면, 단순히 요청받은 대로 코드를 짜는 것을 넘어 더 적절한 구현 방식을 제안받을 수도 있습니다. 예를 들어 "이 기능은 관리자만 접근해야 한다"는 맥락을 미리 알려주면, 권한 검사 로직을 처음부터 함께 고려한 구현을 받을 가능성이 높아집니다.

실수 3 — 한 번에 너무 많은 것을 요청하는 것. "로그인, 회원가입, 비밀번호 찾기를 한꺼번에 다 만들어줘"처럼 범위가 넓은 요청은 결과의 품질이 들쭉날쭉해지기 쉽습니다. 다음 섹션에서 다룰 단계적 요청으로 나누는 것이 훨씬 안정적입니다. 결과물이 뒤섞여 나오면 어디서부터 잘못됐는지 찾기도 어려워지므로, 처음에는 다소 답답하게 느껴지더라도 작게 나누는 습관을 들이는 것이 장기적으로 시간을 절약해줍니다.

🚀 단계적 요청과 예시 제공 기법

복잡한 작업일수록 한 번에 모두 요청하기보다, 작은 단위로 나눠 순서대로 요청하는 것이 효과적입니다. "먼저 데이터 모델부터 정의해줘" → "이제 이 모델을 기반으로 API 엔드포인트를 만들어줘" → "마지막으로 프론트엔드 폼을 연결해줘"처럼 단계를 나누면, 각 단계마다 결과를 확인하며 방향을 조정할 수 있습니다. 또한 원하는 코드 스타일이 있다면 기존 코드의 예시를 함께 보여주는 것도 효과적입니다. "src/components/Button.tsx와 같은 스타일로 새 컴포넌트를 만들어줘"처럼 참고할 기존 파일을 지정하면, 프로젝트 전체의 일관성을 유지하면서 새 코드를 작성할 수 있습니다.

단계적 요청의 효과는 특히 새로운 기능을 처음부터 만들 때 두드러집니다. "게시판 기능 만들어줘"처럼 한 번에 요청하면 데이터 모델, API, 화면까지 한꺼번에 생성되어 중간에 방향을 조정하기 어렵습니다. 반면 단계를 나누면 데이터 모델 단계에서 필드 구성이 마음에 안 들 경우 그 자리에서 바로 수정 요청을 할 수 있어, 잘못된 방향으로 너무 멀리 가기 전에 바로잡을 수 있습니다.

📝 핵심 요약

• 클로드 코드는 프로젝트에 대해 아무것도 모른다고 가정하고 구체적으로 요청해야 합니다.
• 대상 위치는 파일경로:줄번호 형식으로 명시하면 훨씬 정확하고 빠른 응답을 받을 수 있습니다.
• 배경 맥락과 제약 조건을 함께 제공하면 결과의 정확도가 크게 높아집니다.
• 복잡한 작업은 작은 단계로 나누고, 기존 코드를 예시로 참조하도록 요청하는 것이 효과적입니다.

다음 강에서는 클로드 코드가 프로젝트 맥락을 더 잘 활용하도록 돕는 컨텍스트 관리 기법을 다루겠습니다.

📚 참고 자료

• Best practices for Claude Code — Claude Code 공식 문서