- Claude Code는 '작업 위임'보다 '구조화된 지시'가 아웃풋 품질을 3배 이상 높인다.
- CLAUDE.md를 통한 컨텍스트 상주화, 서브 에이전트 분할, 차분(diff) 리뷰의 세 가지가 특히 효과적이다.
- 본 기사에서는 실무에서 반복적으로 사용할 수 있는 프롬프트 패턴 7가지를 체계화했다.
Anthropic이 2025년에 GA한 Claude Code는 터미널 상에서 작동하는 자율 AI 코딩 에이전트다. VS Code 확장이나 Cursor와 달리, 셸(Shell), Git, 파일 시스템에 직접 접근하면서 작업을 완수하도록 설계되었다.
하지만 '굉장해 보이는데 지시 방법을 모르겠다', '기대한 아웃풋과 다른 결과가 나온다'는 의견을 자주 듣는다. 이에 본 기사에서는 실무 수준에서 여러 번 사용하며 정확도가 높아진 프롬프트 패턴 7가지를 정리했다.
대상 독자는 Claude Code를 이미 도입하여 더 잘 활용하고 싶은 중급~고급 엔지니어이다. 기본 세팅 설명은 생략한다.
문제: '○○을 구현해 달라'와 같이만 지시하면 Claude Code가 해석 범위를 너무 넓혀 불필요한 의존성을 추가하거나 기존 코드를 대폭 수정하는 경향이 있다.
패턴:
## Goal
<1줄로 무엇을 달성할지>
## Constraints
...
효과적인 이유: Claude Code는 '할 수 있는 것'보다 '하면 안 되는 것(Do NOT)'을 먼저 파악했을 때 변경 범위를 좁히려는 경향이 있다. 특히 Do NOT 섹션은 제로샷(zero-shot) 방식보다 일관되게 정확도가 높아진다.
Claude Code는 리포지토리 루트에 CLAUDE.md가 있으면 세션 시작 시 자동으로 읽어 들인다. 여기에 프로젝트 고유의 지식을 작성해 두면, 매번 '이 프로젝트는 ~'라고 설명하는 수고를 덜 수 있다.
CLAUDE.md 최소 구성 템플릿:
# Project Overview
<프로젝트 목적을 3줄로>
# Architecture
...
포인트: CLAUDE.md는 50줄 이내를 기준으로 유지하는 것이 좋다. 길어질수록 중요한 부분이 묻히기 쉽다. 상세한 사양은 별 파일로 분리하여 @import로 참조하는 것이 효과적이다.
코드 생성 후 '검토해 달라'고 지시하기보다, diff를 전달하여 검토시키는 것이 정확도가 높다.
# 먼저 diff를 만들어 둔다
git diff main HEAD > /tmp/review.patch
# Claude Code에 전달한다
...
팁: '전반적으로 문제없는지 봐달라'는 모호한 요청보다, 관점(Viewpoint)을 명시하는 것이 실행 가능한 피드백(actionable feedback)을 받는다.
큰 작업을 한 번에 던지면 Claude Code가 도중에 헤매기 쉽다. 작업을 명시적으로 분할하여 순서를 지정하면 품질이 안정된다.
다음 작업을 순서대로 실행해 주세요.
각 단계 완료 후 'Step N 완료'라고 보고한 뒤 다음으로 넘어가 주세요.
Step 1: src/lib/payment.ts의 기존 코드를 읽고,
...
효과적인 이유: Claude Code는 컨텍스트 창의 후반부로 갈수록 초기 지시를 '잊어버리기' 쉽다. 단계 보고를 삽입하여 **중간 체크포인트(Intermediate Checkpoint)**를 만들면 이탈을 막을 수 있다.
'구현한 후에 테스트 코드를 작성해 달라'보다 '테스트 코드를 먼저 작성하게 한 후 구현시키기'가 Claude Code의 사양 이해도를 높인다.
다음 사양에 기반하여, 우선 Vitest의 테스트 케이스만 작성해 주세요.
구현은 하지 말아 주세요.
사양:
...
테스트가 준비되면 다음 프롬프트로 구현을 요청한다:
방금 작성한 테스트가 모두 통과하도록 calculateDiscount를 구현해 주세요.
`pnpm test src/lib/discount.test.ts`를 실행하여 모든 항목이 green이 되면 완료입니다.
에러 설명을 직접 요약해서 전달하는 것보다, 로그를 그대로 붙여넣는 것이 진단 정확도가 훨씬 높다.
다음 에러가 운영 환경에서 발생하고 있습니다.
원인을 특정하여 수정안을 제시해 주세요.
---
...
포인트: '우선 가설을 세워보고'라는 문구를 추가하면, Claude Code가 스스로 추론 단계를 거치기 때문에 수정할 부분이 예상 밖의 곳에서 나오는 것을 줄일 수 있다.
기존 코드를 리팩토링(refactoring)하도록 요청할 경우, 의도치 않게 인터페이스나 타입이 변경될 수 있습니다. 이를 방지하는 패턴:
다음 코드를 리팩토링해 주세요.
## 수정해도 되는 부분
- 함수 내부의 구현 상세
...
| # | 패턴명 | 주요 효과 |
|---|
| 1 | 목표 → 제약 → 금지 사항 | 변경 범위 제한 |
| ... | | |
| 이 패턴들은 단독으로도 효과를 발휘하지만, 결합함으로써 시너지 효과가 납니다. 예를 들어, "CLAUDE.md (Pattern 2) + 서브태스크 분할 (Pattern 4) + TDD (Pattern 5)"는 대규모 기능 추가를 안전하게 진행할 수 있는 검증된 조합입니다. | | |
Claude Code는 '자율 에이전트(autonomous agent)'라는 특성상, 좋은 지시를 내릴수록 좋은 결과를 반환한다는 강한 양의 상관관계를 보입니다. 본 기사의 패턴을 기반으로 자신의 프로젝트나 팀의 관습에 맞춰 커스터마이징해 주시면 좋겠습니다.
댓글란에 "이 패턴도 효과가 있었다", "잘 되지 않았다" 등 지식을 공유해 주시면 감사하겠습니다.
✍️ 본 기사 작성자: 合同会社ジモラボ
지모라보는 하치오지에 거점을 두고 AI를 활용한 SaaS를 다수 개발하고 있습니다. 본 기사의 기술 검증 역시 그러한 개발 과정의 부산물입니다.
관심을 가져주신다면, 각 SNS 팔로우도 부탁드립니다!
