2026년에 입사한 신입 엔지니어 takumi입니다. 업무에서 Claude Code를 사용하기 시작하면서, 프롬프트 작성 방식 하나로 출력의 질이 크게 달라진다는 것을 실감했기에, 실제로 시도해 본 「좋은 프롬프트」와 「나쁜 프롬프트」의 차이를 정리했습니다. 이제 막 사용을 시작하시는 분들께 참고가 된다면 좋겠습니다.

Claude Code는 파일 읽기, 명령 실행, 코드 편집을 자율적으로 수행하는 에이전트형 코딩 환경입니다. 챗봇처럼 질문에 답하고 기다리는 것이 아니라, 「무엇을 하고 싶은지」를 전달하면 Claude 스스로 조사, 계획, 구현까지 진행해 줍니다.

뒤집어 말하면, 지시가 모호하면 Claude가 잘못된 전제로 진행해 버릴 리스크도 있습니다. 그렇기 때문에 프롬프트의 질이 결과물의 질을 좌우합니다.

신입이 가장 저지르기 쉬운 실수는 다음과 같은 「두루뭉술한」 지시입니다.

• 「버그 고쳐줘」
• 「foo.py에 테스트 추가해줘」
• 「대시보드를 느낌 있게 만들어줘」
• 「ExecutionFactory의 API는 왜 그렇게 이상하게 만들어져 있어?」

이것들의 공통점은, 기대하는 목표가 구체적이지 않다, 검증 수단이 제시되지 않았다, 참조해야 할 파일이나 문맥이 지정되지 않았다는 점입니다. Claude는 문맥을 추측하여 진행하지만, 추측이 틀리면 재작업(rework)이 발생하여 결국 이쪽에서 전부 체크해야 하는 상황이 됩니다.

Anthropic 공식 베스트 프랙티스(Best Practice)에서는 좋은 프롬프트에 다음 요소가 포함되어야 한다고 명시하고 있습니다.

구체적인 파일·시나리오 지정기대하는 출력·완료 조건 명시지켜야 할 제약 사항 제시****검증 가능한 기준(테스트·에러 내용·재현 조건 등) 제공

앞서 언급한 나쁜 프롬프트를 이 관점에서 다시 쓰면 다음과 같습니다.

공통점은 「무엇을」 「어디서」 「어떻게 되면 완료되는가」라는 3가지를 반드시 포함하고 있다는 점입니다.

실제로 직접 테스트해 본 예시입니다.

나쁜 프롬프트

테스트 써줘

좋은 프롬프트

src/utils/validateEmail.ts 에 대한 테스트를 작성해 주세요.
- 정상계: user@example.com → true
- 이상계: invalid, user@.com → false
...

전자는 「테스트가 있다」는 것만 보장될 뿐, 관점이 누락되거나 구현 의도와 다른 테스트가 될 수 있습니다. 후자는 목표와 검증 조건이 명확하기 때문에, Claude가 스스로 테스트를 실행하고, 실패하면 수정까지 완료해 줍니다.

프롬프트 단독의 기교뿐만 아니라, 다음 두 가지도 출력의 질에 영향을 미칩니다.

갑자기 구현을 시키면 엉뚱한 구현이 될 수 있습니다. Plan Mode를 사용하면 Claude는 먼저 파일을 읽고 이해할 뿐, 변경은 수행하지 않습니다. 이해한 내용을 바탕으로 구현 계획을 세우게 하고, 계획을 확인한 뒤 구현 단계로 넘어감으로써 재작업을 줄일 수 있습니다.

• 차분이 1줄로 설명 가능한 작은 수정 → Plan Mode 불필요, 직접 의뢰
• 여러 파일에 영향을 주는 변경, 익숙하지 않은 코드의 변경 → Plan Mode로 계획한 뒤 구현

프로젝트마다의 명령어나 코딩 규약을 매번 프롬프트에 쓰는 것은 비효율적입니다. CLAUDE.md에 다음과 같은 정보를 적어두면 Claude가 대화 시작 시 자동으로 읽어 들입니다.

# 명령
- 테스트 실행: npm test
- Lint: npm run lint
...

공식 문서에서도 「각 줄에 대해, 이것을 지우면 Claude가 실수를 할 것인가?를 자문하고, 그렇지 않다면 삭제하라」고 권장하고 있습니다. 너무 길면 중요한 규칙이 묻혀 오히려 무시하게 되기 때문입니다.

• 나쁜 프롬프트는 「목표가 모호함」, 「검증 수단이 없음」, 「문맥(Context) 지정이 없음」
• 좋은 프롬프트는 「대상 파일」, 「완료 조건」, 「제약 사항」, 「검증 기준」을 포함
• 규모가 큰 변경은 Plan Mode를 통해 계획 단계를 거치면 재작업(rework)을 줄일 수 있음
• 반복해서 사용하는 문맥은 CLAUDE.md에 작성하여 매번 입력하는 프롬프트를 단순화함

신입으로서 아직 탐색 중인 단계이지만, 프롬프트를 「업무 지시서」로 작성한다는 의식으로 바꾸는 것만으로도 Claude Code 출력의 안정감이 확연히 달라졌습니다. 저와 비슷하게 사용을 시작하신 분들께 참고가 되기를 바랍니다.