ClaudeCode한테 어떻게 시켜야하지?

Posted on | In

AI 믿지 마라 = 예측 가능한 동작 + 사용자가 제어권


2.1 효과적인 프롬프팅 전략

핵심 개념

같은 요청이라도 프롬프트를 어떻게 쓰느냐에 따라 결과가 완전히 달라진다. CLAUDE.md가 잘 되어있으면 프롬프트가 짧아진다.

좋은 프롬프트의 4요소 (WHCR)

1
2
3
4
5
6
7
8
┌────────────────────────────────────────────┐
│         좋은 프롬프트 = W.H.C.R            │
│                                            │
│  W - What    무엇을 (구체적 목표)           │
│  H - How     어떻게 (패턴, 기술 제약)       │
│  C - Context 맥락 (관련 파일, 위치)         │
│  R - Result  결과물 (기대하는 산출물)        │
└────────────────────────────────────────────┘

CLAUDE.md와의 관계

1
2
CLAUDE.md 없음 → 매번 W + H + C + R 다 써야 함 (길고 반복적)
CLAUDE.md 있음 → W만 쓰면 됨 (H, C는 CLAUDE.md가 제공)

CLAUDE.md = 반복되는 프롬프트를 한 번만 쓰는 것

언제 길게 써야 하나?

1
2
3
4
5
6
7
8
짧아도 OK (CLAUDE.md가 커버):
  "캘린더에 주간 뷰 추가해줘"

길게 써야 (특수 요구사항):
  "캘린더에 주간 뷰를 추가하는데,
   기존 CalendarView 수정하지 말고 새로 만들어.
   LazyVStack 쓰고, 현재 주 ± 2주만 로딩해"
   ↑ CLAUDE.md에 없는 특수 지시

멀티턴 전략: 큰 작업 = 반드시 분해

1
2
3
4
5
방법 A: 한 번에 다     방법 B: 나눠서
─────────────────     ─────────────────
❌ 컨텍스트 길어짐      ✅ 각 단계 짧고 명확
❌ 하나 틀리면 전체 롤백 ✅ 단계별 검토/수정
❌ 끼어들기 어려움       ✅ 잘못되면 그 단계만 /rewind

실전 패턴: Plan → 분리 구현 → 마무리

1
2
3
[1] Plan 모드: "설정 화면 구조를 설계해줘"     → 검토/첨삭
[2] 기능별:   "알림 시간 변경부터 구현해줘"     → 확인 → 다음
[3] 마무리:   "전체 통합 테스트하고 빠진 거 확인" → 완료

입력 프리픽스

프리픽스 기능 예시
/ 커맨드/스킬 실행 /compact, /clear, /help
! bash 직접 실행 (결과가 컨텍스트에 추가) !git diff, !swift build
@ 파일 경로 자동완성 @src/Core/PhotoManager.swift

! vs Bash 도구

1
2
3
4
5
6
!git log     → 내가 직접 실행, 결과가 컨텍스트에 바로 추가
Bash 도구    → Claude가 판단해서 실행, 같은 효과

활용: Claude에게 맥락을 빠르게 줄 때
  !git diff        → "이 변경사항 리뷰해줘"
  !cat package.json → "이 의존성 분석해줘"

핵심 정리

  1. WHCR 공식 = What + How + Context + Result. 구체적일수록 정확한 결과
  2. CLAUDE.md 있으면 W만 써도 됨 = 반복 프롬프트의 자동화
  3. 큰 작업 = 분해 = Plan → 기능별 구현 → 마무리 (Explore-Plan-Act)
  4. ! 프리픽스 = bash 결과를 컨텍스트에 빠르게 주입


2.2 코드 리뷰 & 리팩토링 워크플로우

핵심 개념

코드 리뷰와 리팩토링은 Permission Mode 전환이 핵심. Plan(읽기) → acceptEdits(수정) 패턴.

코드 리뷰 워크플로우

1
2
3
4
5
6
7
8
9
10
[1] Plan 모드 (Shift+Tab → plan)
    "이 PR의 변경사항을 리뷰해줘"
    → 읽기 전용, 실수로 코드 수정 방지

[2] 파일별 멀티턴
    "CalendarView.swift 리뷰해줘" → 피드백 확인
    "PhotoManager.swift 리뷰해줘" → 피드백 확인

[3] 종합 의견
    "전체 PR 문제점 정리해줘"

! 프리픽스 조합

1
2
3
!git diff main...HEAD                       → "이 변경사항 리뷰해줘"
!git diff main...HEAD -- CalendarView.swift → "이 파일만 리뷰해줘"
!git log --oneline main...HEAD              → "커밋 히스토리도 봐줘"

리팩토링 워크플로우

1
2
3
4
5
6
7
8
9
10
[1] Plan 모드: "이 코드의 문제점을 분석해줘"
    → 문제 목록 확인, 첨삭

[2] acceptEdits 전환 (Shift+Tab)
    "1번 문제부터 수정해줘"
    → 파일별 자동 수정

[3] 검증
    !swift build    → 빌드 확인
    !git diff       → 변경사항 확인

패턴 요약

1
2
리뷰:      Plan(읽기전용) → 파일별 분석 → 종합
리팩토링:  Plan(분석)     → acceptEdits(수정) → 검증

핵심 정리

  1. 리뷰 = Plan 모드 — 실수로 코드 수정 방지
  2. 파일별 멀티턴 — 한꺼번에 하지 않고 하나씩
  3. 모드 전환이 워크플로우의 뼈대 — Plan → acceptEdits
  4. ! + git diff 조합 — 빠르게 맥락 제공


2.3 & 2.4 테스트 작성 & 디버깅 워크플로우

핵심 개념

테스트와 디버깅 모두 “바로 시키지 말고 분석 먼저”가 원칙. Plan → Act → 검증 패턴.

2.3 테스트 작성

구현을 보고 만든 테스트의 함정

1
2
3
4
Claude가 구현 코드를 보고 테스트 작성:
  → 구현에 있는 것만 테스트
  → 구현에 없는 엣지케이스 누락
  → 버그가 있어도 테스트 "통과" 😱

효과적인 테스트 프롬프팅

1
2
3
4
5
6
7
8
9
10
11
❌ "PhotoManager의 테스트를 작성해줘"
   → 구현 보고 만듦 → 엣지케이스 누락

✅ "구현을 보지 말고, 함수 시그니처와 요구사항만 보고
    엣지케이스를 포함해서 작성해"
   → 사양 기반 테스트

✅✅ 멀티턴:
   "fetchPhotos의 엣지케이스를 먼저 나열해줘"
   → 검토/추가
   "이 케이스들에 대한 테스트를 작성해줘"

TDD with Claude Code

1
2
3
[1] 테스트 먼저 작성 (나 또는 Claude)
[2] Claude가 구현
[3] 테스트 실행으로 자동 검증

2.4 디버깅 워크플로우

나쁜 디버깅 vs 좋은 디버깅

1
2
3
4
5
6
7
8
9
❌ "이 에러 고쳐줘"
   → 증상만 보고 떼움 → 근본 원인 안 고침 → 또 터짐

✅ 3단계 디버깅:
   [1] 증상 공유:  !swift build 2>&1 | tail -20
   [2] 원인 분석:  Plan 모드 → "왜 이런 에러가 나는지 분석해줘"
                   → Claude가 가설 A, B, C 제시
   [3] 수정 지시:  "A가 맞는 것 같아. 수정해줘"
                   → acceptEdits → !swift build 검증

크래시 디버깅

1
2
3
4
5
[1] !cat crash.log       → "이 크래시 로그 분석해줘"
[2] Plan 모드            → 원인 가설 3개
[3] "가설 A를 확인해봐"   → Grep/Read로 탐색
[4] 원인 확정            → acceptEdits로 수정
[5] !swift test          → 검증

핵심 정리

  1. 테스트 프롬프팅 = “구현 보지 말고 요구사항 기반으로” + 엣지케이스 먼저 나열
  2. 디버깅 3단계 = 증상 → 분석(Plan) → 수정(acceptEdits) → 검증
  3. 공통 원칙 = “고쳐줘” ❌ → “분석해줘” 먼저 ✅
  4. 모든 워크플로우 = Plan → Act → 검증


2.5 Git 통합 워크플로우

핵심 개념

Claude Code는 Git과 긴밀하게 통합되어 있다. 커밋 메시지 자동 작성, PR 생성, 충돌 해결까지 가능. 단, 되돌릴 수 없는 작업은 스스로 하지 않는다.

커밋 워크플로우

1
2
3
4
5
6
7
8
"변경사항을 확인하고 적절한 커밋 메시지로 커밋해줘"

Claude가 하는 것:
  [1] git status      → 변경된 파일 확인
  [2] git diff        → 실제 변경 내용 분석
  [3] git log         → 기존 커밋 메시지 스타일 파악
  [4] 커밋 메시지 작성  → 기존 스타일 + CLAUDE.md 규칙 반영
  [5] git add + commit → 실행

Git 워크플로우 전체

1
2
3
4
커밋:      "변경사항 커밋해줘"       → 분석 + 메시지 작성 + 커밋
PR 생성:   "PR 만들어줘"            → gh pr create + 제목/본문 자동
브랜치:    "새 기능 브랜치 만들어줘"  → git checkout -b feature/...
충돌:      "이 충돌 해결해줘"        → diff 분석 + 해결

Claude가 스스로 하지 않는 Git 작업

1
2
3
4
5
6
7
8
9
🚫 되돌릴 수 없는 작업:
  git push --force     → 원격 히스토리 파괴
  git reset --hard     → 로컬 변경 전부 삭제
  git checkout .       → 작업 중인 코드 날림
  기존 커밋 amend       → 새 커밋 생성 선호
  hooks 스킵 --no-verify

✅ 되돌릴 수 있는 작업:
  git add / commit / branch → 자유롭게

하네스 철학: 안전한 건 자동, 되돌릴 수 없는 건 차단

핵심 정리

  1. 커밋 메시지 자동 작성 = diff 분석 + 기존 스타일 파악 + CLAUDE.md 반영
  2. 되돌릴 수 없는 작업 차단 = force push, hard reset, checkout 등
  3. 원칙 = 예측 불가능하고 영향도 큰 작업은 안 함


2.6 슬래시 커맨드 & 스킬 시스템

핵심 개념

반복되는 워크플로우를 커스텀 커맨드로 자동화. 파일 이름 = 커맨드 이름.

커맨드 위치와 구조

1
2
3
4
.claude/commands/
├── learn.md       → /learn
├── review.md      → /review
└── progress.md    → /progress

커맨드 파일 구조

1
2
3
4
5
6
7
8
9
10
---
description: 이 커맨드가 뭐하는지 한 줄 설명    ← 프론트매터
---

## Context
- 현재 브랜치: !`git branch --show-current`    ← 동적 컨텍스트 주입
- 변경 파일: !`git diff main --name-only`

## Your Task
Claude에게 뭘 하라는 지시...                    ← 프롬프트 본문

동적 컨텍스트 주입

!`command` 문법: 커맨드 실행 시 셸 명령 결과가 자동 삽입

1
2
3
커맨드 파일에: !`ls .learning/`
실행 시:       claude-code    ← 실제 결과로 치환됨
→ Claude가 "아, claude-code 토픽이 있구나" 파악

2.1의 ! 프리픽스와 같은 원리, 커맨드 파일 안에서 자동 실행

실전 예시: /review-pr 커맨드

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
---
description: PR 코드 리뷰 커맨드
---

## Context
- 현재 브랜치: !`git branch --show-current`
- 변경된 파일: !`git diff main --name-only`
- 최근 커밋들: !`git log --oneline main..HEAD`

## Your Task
위 변경된 파일을 하나씩 분석해서 코드 리뷰해줘.
각 파일마다:
1. 변경 내용 요약
2. 잠재적 문제점
3. 개선 제안
전체 리뷰 결과를 review-result.md에 저장해줘.

스킬 (Skills) — 커맨드의 진화형

커맨드와 스킬은 통합됨. 스킬은 더 많은 설정 가능:

1
2
3
4
5
6
7
8
---
name: my-command
description: 설명
allowed-tools: [Read, Bash]    # 권한 없이 사용 가능한 도구
model: opus                     # 모델 오버라이드
effort: high                    # 노력 수준
context: fork                   # 서브에이전트에서 실행
---

핵심 정리

  1. 파일 이름 = 커맨드 이름 — review-pr.md → /review-pr
  2. 동적 컨텍스트 — !`git명령`으로 현재 상태 자동 수집
  3. Context 없으면 — Claude가 뭘 해야 할지 모름
  4. 반복 워크플로우 → 커맨드로 — 매번 타이핑 안 해도 됨


2.7 에이전트 장애 대응 & 트러블슈팅

핵심 개념

에이전트는 반드시 실패한다. 실패를 빠르게 인지하고 복구하는 능력이 Expert의 핵심. 실패가 반복되면 하네스를 엔지니어링해서 재발 방지.

실패 감지 시그널

1
2
3
4
5
6
7
8
9
10
🚨 즉시 개입:
  - 같은 도구 3회+ 연속 실패
  - "I apologize" + 동일 접근 반복
  - 존재하지 않는 파일/함수 참조
  - 요청하지 않은 대규모 변경 시작

⚠️ 주의 관찰:
  - 응답이 점점 길어지며 반복적
  - "Let me try a different approach" 3회+
  - 이전 합의 사항을 다시 논의

4단계 대응 전략

1
2
3
4
5
6
7
8
9
경미 ──────────────────────── 심각

Level 1        Level 2        Level 3        Level 4
스턱           환각            파일 파괴       대규모 파괴
같은 실패 반복  없는 것 참조    코드 망가짐     여러 파일 파괴
   │              │              │              │
Ctrl+C         /rewind         /clear         /clear
+구체적 재지시  +체크포인트복원  +git checkout   +git reset
                                              +CLAUDE.md 규칙

/rewind vs /clear

1
2
3
4
5
6
7
8
9
/rewind                          /clear
──────                           ──────
"여기까지는 좋았는데..."           "전부 다 엉망..."
→ 좋았던 체크포인트로 복원         → 완전 리셋
→ 코드 + 대화 선택 복원 가능       → git checkout으로 파일도 복원
→ 기존 맥락 유지                  → 깨끗한 새 시작

코드는 괜찮고 대화만 꼬임 → /rewind
파일도 대화도 다 엉망    → /clear + git

하네스 엔지니어링 (재발 방지)

실패 반복 → CLAUDE.md에 방지 규칙 추가 → 다시는 안 일어나게

1
2
3
4
5
6
## CLAUDE.md 방지 규칙 예시

IMPORTANT:
- 같은 접근법이 2회 실패하면 멈추고 다른 전략을 제안해
- Edit 실패 시 old_string의 주변 코드를 더 포함해서 유일하게 만들어
- 대규모 리팩토링 전에 반드시 Plan 모드에서 계획을 보여줘

“에이전트가 실수하면, 그 실수를 다시는 하지 않도록 하네스를 엔지니어링하라”

핵심 정리

  1. 4단계 대응 = 스턱(재지시) → 환각(rewind) → 파괴(clear+git) → 대규모(clear+reset+규칙)
  2. /rewind = 코드 괜찮고 대화만 꼬임, /clear = 전부 엉망
  3. 최종 방어선 = CLAUDE.md에 방지 규칙 추가 (하네스 엔지니어링)
  4. 감지가 핵심 = 3회 반복, “I apologize”, 없는 것 참조 → 즉시 개입


2.8 토큰 사용량 모니터링 & 비용 최적화

핵심 개념

턴이 쌓일수록 비용이 눈덩이처럼 증가한다. Prefix Caching으로 이전 부분은 할인되지만, 컨텍스트 팽창은 막아야 한다. 작업 전환 시 /clear가 핵심.

왜 턴이 쌓이면 비싸지나?

1
2
3
4
5
턴 1:  [시스템 + CLAUDE.md + 프롬프트] → 응답
       입력: ████ (작음)

턴 20: [시스템 + CLAUDE.md + 턴1~19 전체 + 프롬프트] → 응답
       입력: ████████████████████████████ (매우 큼)

매 턴마다 이전 대화 전체를 다시 전송 → 입력 토큰 누적 증가

Prefix Caching

1
2
3
4
5
6
7
캐시 = "자주 쓰는 걸 미리 저장해두고 빠르게 재사용"

턴 2 전송: [시스템 + CLAUDE.md + 턴1 대화 + 새 프롬프트]
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
           턴1과 동일한 부분 → 캐시 히트 → 90% 할인

히트율 92% = 입력의 92%가 할인됨

/clear의 딜레마

1
2
3
4
5
6
7
/clear 안 하면:
  ✅ 캐시 히트로 이전 부분 할인
  ❌ 컨텍스트 커져서 총 입력 증가

/clear 하면:
  ✅ 깨끗한 컨텍스트, 입력 작음
  ❌ 캐시 리셋, 처음부터 정가

정답: 다른 작업으로 전환할 때 /clear

1
2
같은 작업 계속 → /clear 하지 마 (캐시 + 맥락 유지)
다른 작업 시작 → /clear 해 (불필요한 컨텍스트 제거)

비용 최적화 7원칙

# 원칙 효과
1 작업 전환 시 /clear 🟢🟢🟢
2 같은 작업은 세션 유지 🟢🟢🟢
3 큰 작업은 멀티턴 분해 🟢🟢
4 서브에이전트로 탐색 🟢🟢
5 CLAUDE.md 간결하게 🟢
6 –max-budget-usd 🟢
7 멀티모델 라우팅 🟢🟢🟢

멀티모델 라우팅 (Alt+P)

1
2
3
코드 탐색/분석 → Haiku   (저렴, 빠름)
일반 구현      → Sonnet  (균형)
복잡한 설계    → Opus    (비싸지만 정확)

핵심 정리

  1. 턴 쌓임 = 비용 증가 — 매 턴마다 이전 대화 전체 재전송
  2. Prefix Caching = 이전과 동일한 부분 90% 할인 (히트율 92%)
  3. /clear 타이밍 = 다른 작업으로 전환할 때
  4. 멀티모델 라우팅 = 작업에 맞는 모델 선택이 가장 큰 절감