Claude Code
프롬프트 전략

프롬프팅의 근본 원칙

소스 코드를 보면 Claude Code의 시스템 프롬프트에는 명확한 작업 철학이 내장되어 있습니다. 이 철학을 이해하면 프롬프트를 어떻게 써야 하는지 자연스럽게 따라옵니다.

Claude Code가 내부적으로 지키는 3대 원칙

이 원칙이 당신의 프롬프트에 미치는 영향

CLAUDE.md: 가장 강력한 프롬프트 채널

CLAUDE.md는 모든 세션에 자동으로 시스템 프롬프트에 포함되며, 코드에서 "이 지침은 기본 행동을 OVERRIDE하며 정확히 따라야 합니다"라고 명시되어 있습니다. 즉, CLAUDE.md에 적은 것은 사실상 시스템 프롬프트의 연장선입니다.

CLAUDE.md 작성 법칙

실전 예시: 좋은 CLAUDE.md vs 나쁜 CLAUDE.md

# CLAUDE.md
항상 클린 코드를 작성하세요.
에러 핸들링을 잘 하세요.
변수명은 의미 있게 지으세요.
모든 함수에 docstring을 작성하세요.
테스트를 작성하세요.
보안에 신경 쓰세요.
성능을 고려하세요.

# CLAUDE.md

## Build & Test
- `pnpm build` — TypeScript 컴파일
- `pnpm test:unit -- --run` — 단일 실행
- `pnpm test:unit -- -t "test name"` — 특정 테스트
- `pnpm lint:fix` — lint + auto-fix

## Code Style
- `type` 선호 (interface 대신)
- barrel export (index.ts) 금지
- 에러는 `AppError` 클래스만 사용

## PR Rules
- 브랜치: `feat/`, `fix/`, `chore/` 접두사
- 커밋: Conventional Commits 형식
- merge 전 `pnpm lint && pnpm test:unit` 통과 필수

파일 계층 활용하기

요청 문구의 기술

같은 의도라도 프롬프트를 어떻게 쓰느냐에 따라 결과 품질이 크게 달라집니다. Claude Code 내부 동작 원리에 맞춘 최적의 문구 패턴을 정리했습니다.

패턴 1: 구체적 위치 + 구체적 행동

Claude는 파일을 먼저 읽고 나서 수정하도록 프로그래밍되어 있습니다. 파일 경로를 명시하면 불필요한 탐색 단계를 줄일 수 있습니다.

패턴 2: 의도 설명 + 제약 조건

Claude의 최소주의 원칙 때문에, 원하는 범위를 명확히 해야 합니다.

UserService에 이메일 중복 검사를 추가해줘.
- src/services/userService.ts의 createUser 메서드에 추가
- 중복이면 DuplicateEmailError를 던져줘 (src/errors.ts에 정의)
- 기존 테스트 파일(src/services/__tests__/userService.test.ts)에 테스트 추가
- 다른 파일은 수정하지 마

이메일 검증 기능 만들어줘

패턴 3: 단계적 요청 (Step-by-step)

복잡한 작업은 한 번에 요청하기보다, 단계를 나눠서 요청하는 것이 품질이 좋습니다.

# 1단계: 현황 파악
현재 인증 시스템의 구조를 파악해줘. 관련 파일과 흐름을 정리해줘.

# 2단계: (Claude의 분석을 확인한 후)
좋아, 그러면 세션 기반 인증을 JWT로 마이그레이션하는 계획을 세워줘.
변경할 파일 목록과 각 파일에서 뭘 바꿀지 정리해줘.

# 3단계: (계획을 확인한 후)
계획대로 진행해줘. `src/auth/` 디렉토리부터 시작해.

패턴 4: 네거티브 지시 (하지 마)

Claude의 최소주의에도 불구하고, 특정 행동을 명시적으로 금지하면 더 정확해집니다.

이 함수를 리팩토링해줘.
- 기존 public API(함수 시그니처)는 바꾸지 마
- 새로운 dependency는 추가하지 마
- 테스트 파일은 건드리지 마
- 주석 추가하지 마

패턴 5: 컨텍스트 제공

에러 메시지, 로그, 스크린샷을 함께 붙여넣으면 Claude가 스스로 디버깅하는 시간을 크게 줄입니다.

이 테스트가 실패해:

$ npm test -- --run src/auth/validate.test.ts

FAIL  src/auth/validate.test.ts
  ✕ should reject expired sessions (15ms)
    TypeError: Cannot read property 'id' of undefined
      at validateSession (src/auth/validate.ts:42:15)
      at Object.<anonymous> (src/auth/validate.test.ts:28:5)

고쳐줘.

작업 범위 조절의 기술

Claude Code는 "요청한 것만 한다"가 원칙이므로, 원하는 범위를 정확히 전달하는 것이 핵심입니다.

범위 확장: 추가 작업을 명시적으로 요청

src/api/users.ts에 DELETE /users/:id 엔드포인트를 추가해줘.

추가로:
- 해당 엔드포인트의 단위 테스트도 작성해줘
- src/api/routes.ts의 라우터에도 등록해줘
- 관리자 권한 체크를 미들웨어로 넣어줘

범위 축소: 특정 영역만 제한

이 함수의 성능을 개선해줘. 

단, 이 함수의 시그니처와 반환값은 바꾸지 마.
다른 파일은 건드리지 마.

Effort 레벨 활용

Claude Code는 /effort 명령어로 응답의 깊이를 조절할 수 있습니다.

피드백 전략: "기억"에 남는 지시

Claude Code에는 자동 메모리 시스템이 있습니다. 구체적인 피드백을 주면 자동으로 저장되어 다음 세션에서도 반영됩니다.

자동 저장되는 피드백 유형

효과적 피드백 공식

[하지 마 / 이렇게 해] + [구체적 대상] + [이유]

예시들:
"테스트에서 setTimeout 모킹하지 마 — vi.useFakeTimers()를 써"
"에러 메시지를 한국어로 쓰지 마 — 이 프로젝트는 영어 에러 메시지를 쓴다"
"console.log 대신 logger.debug를 써 — 프로덕션에서 로그 레벨 제어가 필요해서"
"그래, findAll보다 findMany가 이 프로젝트에서 맞아" (긍정 피드백도 저장됨)

컨텍스트 관리 전략

Claude Code는 대화가 길어지면 자동으로 요약(Compact)합니다. 하지만 전략적으로 컨텍스트를 관리하면 더 정확한 결과를 얻을 수 있습니다.

3가지 컨텍스트 관리 도구

컨텍스트 절약 패턴

# 같은 영역의 연속 작업 → 같은 세션
"이 함수 리팩토링해줘"
→ "좋아, 이 함수의 테스트도 업데이트해줘"
→ "lint 에러도 고쳐줘"

# 인증 모듈 작업 완료 후 → /clear
"이제 결제 모듈 보자. src/payment/ 구조를 파악해줘"

## Compact Instructions
요약할 때 테스트 출력과 코드 변경 사항에 집중해줘.
에러 메시지는 전문을 포함해줘.

복합 작업 프롬프팅

큰 작업을 효과적으로 처리하는 고급 프롬프팅 기법입니다.

기법 1: Plan 모드 활용

복잡한 구현 전에 먼저 계획을 세우도록 유도합니다.

결제 시스템을 Stripe에서 Toss Payments로 마이그레이션해야 해.

먼저 계획부터 세워줘:
1. 영향받는 파일 목록
2. 각 파일에서 뭘 바꿔야 하는지
3. 마이그레이션 순서 (의존성 고려)
4. 테스트 전략

구현은 내가 계획을 확인한 다음에 시작해.

기법 2: Agent 활용 (병렬 탐색)

Claude Code는 서브에이전트를 이용해 여러 조사를 동시에 수행할 수 있습니다.

이 모노레포에서 다음 세 가지를 병렬로 조사해줘:
1. packages/api/에서 인증 관련 코드 구조
2. packages/web/에서 로그인 플로우
3. packages/shared/에서 공통 타입 정의

각각 파일 경로와 핵심 함수를 정리해줘.

기법 3: 반복 작업 자동화

비슷한 패턴의 수정을 여러 파일에 적용할 때:

src/api/routes/ 아래 모든 라우터 파일에서:
1. express의 Router를 @hono/hono의 Hono로 교체
2. req.params를 c.req.param()으로 변경
3. res.json()을 c.json()으로 변경
4. 미들웨어 형식도 Hono 호환으로 변경

먼저 users.ts 하나만 변환해서 보여줘.
내가 확인하면 나머지도 같은 패턴으로 변환해.

기법 4: /commit과 /review 활용

# 구현 완료 후 — 커밋
/commit

# 커밋 전 — 변경 사항 셀프 리뷰
/review

# 보안 관점 리뷰
/security-review

# 커밋 + 푸시 + PR 한 번에
/commit-push-pr

도구를 극대화하는 프롬프트

Claude Code의 도구 선택은 시스템 프롬프트에 의해 결정됩니다. 하지만 프롬프트 방식에 따라 도구 활용 효율을 높일 수 있습니다.

검색 효율 높이기

Bash 직접 실행 유도하기

외부 서비스 인터랙션이나 CLI 도구 실행이 필요할 때:

# Docker 컨테이너 관련
"docker compose up -d로 로컬 DB를 시작하고, 마이그레이션을 실행해줘"

# 외부 CLI 도구
"gh pr list --state open으로 열린 PR 목록을 가져와줘"

# 빌드 & 테스트
"pnpm build && pnpm test:unit -- --run 실행해서 결과 알려줘"

! 접두사로 직접 명령 실행

인터랙티브한 명령이 필요할 때 사용자가 직접 실행할 수 있습니다:

# 프롬프트에서 직접 실행 (결과가 대화에 포함됨)
! gcloud auth login
! aws sso login --profile dev
! docker compose logs api --tail 50

MCP 도구 연동

# GitHub MCP가 연결되어 있을 때
"이 커밋과 관련된 GitHub 이슈를 찾아줘"
"PR #42에 달린 리뷰 코멘트를 확인하고 반영해줘"

# DB MCP가 연결되어 있을 때
"users 테이블의 스키마를 확인하고,
 새 migration 파일을 만들어서 email_verified 컬럼을 추가해줘"

안티패턴: 이렇게 하지 마세요

Claude Code 소스를 분석해서 발견한, 프롬프팅에서 효과가 떨어지거나 역효과를 내는 패턴들입니다.

안티패턴 → 개선패턴 변환표

프롬프트 치트시트

바로 복사해서 쓸 수 있는 프롬프트 템플릿 모음입니다.

🐛 버그 수정

[파일경로]의 [줄번호] 근처에서 [증상]이 발생해.
원인은 [추정 원인]인 것 같아.
[어떻게 고쳐야 하는지] 수정해줘.
관련 테스트도 확인해줘.

✨ 새 기능 추가

[기존파일]에 [기능]을 추가해줘.

요구사항:
- [구체적 동작 1]
- [구체적 동작 2]
- 에러 시 [에러 처리 방식]

제약:
- [건드리지 말 것]
- [사용하지 말 것]

테스트도 작성해줘: [테스트파일 경로]

♻️ 리팩토링

[파일/함수]를 리팩토링해줘.

목표: [왜 리팩토링하는지]
방향: [어떤 패턴/구조로]

지키기:
- public API(함수 시그니처) 유지
- 기존 테스트 통과
- [기타 제약]

🔍 코드 분석

[디렉토리/모듈]의 구조를 분석해줘.

알고 싶은 것:
- 주요 파일과 각 역할
- 데이터 흐름 (입력 → 처리 → 출력)
- 외부 의존성
- [특정 관심사]

📋 프로젝트 초기 설정

/init

# 또는 수동으로:
이 프로젝트를 분석해서 CLAUDE.md를 작성해줘.
특히:
- 비표준 빌드/테스트 명령
- 팀 코드 스타일 규칙
- 중요한 아키텍처 결정
- 자주 하는 실수를 방지할 수 있는 규칙

🔄 Git 워크플로우

# 스테이지된 변경사항 커밋
/commit

# 변경사항 리뷰 → 커밋 → 푸시 → PR
/review
/commit-push-pr

# 특정 파일만 diff 확인
/diff src/auth/

💬 일상 대화 패턴

# 설명 요청
"이 코드가 뭐 하는 건지 설명해줘: src/auth/middleware.ts"

# 비교
"JWT와 세션 기반 인증의 장단점을 이 프로젝트 맥락에서 비교해줘"

# 환경 실행 (! 접두사)
! docker compose ps
! curl http://localhost:3000/health