Claude Code 완전 정복

Claude Code는 npm 패키지로 배포된다. Node.js 18 이상이 필요하다.

# 전역 설치
npm install -g @anthropic-ai/claude-code

# 설치 확인
claude --version

설치 시 sudo npm install -g는 피하라. 권한 문제로 깨지기 쉽다. npm 전역 prefix를 홈 디렉터리로 잡거나(npm config set prefix ~/.npm-global) nvm을 쓰는 게 정석이다.

설치가 끝나면 프로젝트 디렉터리로 들어가 실행한다.

cd ~/my-project
claude

첫 실행 시 인증을 묻는다. 두 가지 경로가 있고, 이걸 헷갈리면 비용/할당량 문제가 생긴다.

인증 방식	어떻게	과금	적합한 경우
구독 로그인	브라우저로 Claude.ai 계정(Pro/Max) 로그인	구독 요금제 한도 내	개인 인터랙티브 작업, 비용 예측 가능
API 키	ANTHROPIC_API_KEY 환경변수	토큰당 종량제	CI/자동화, 팀 빌링, 헤드리스

# API 키 방식 (CI·자동화에 적합)
export ANTHROPIC_API_KEY="sk-ant-..."
claude

핵심 함정 — 인증 소스 충돌: API 키와 구독 로그인이 동시에 있으면 우선순위가 꼬일 수 있다. 환경변수 ANTHROPIC_API_KEY가 설정돼 있으면 그게 구독 로그인을 덮어쓴다. "내 Max 구독으로 돌리고 싶은데 왜 API 청구가 나오지?" 의 90%는 셸 프로필에 박혀 있는 ANTHROPIC_API_KEY 때문이다. 한 번에 하나만 쓰고, 의심되면 env | grep ANTHROPIC으로 확인하라.

모델 선택: 세션 안에서 /model 슬래시 커맨드로 바꾼다. 기본은 작업에 따라 Opus/Sonnet을 자동 선택하지만, 명시할 수도 있다.

/model opus      # 최고 성능 (복잡한 리팩터·아키텍처)
/model sonnet    # 속도·비용 균형 (대부분의 일상 작업)

실행 시 플래그로도 지정 가능하다:

claude --model claude-opus-4-8

비용에 민감하면 일상 작업은 Sonnet, 어려운 디버깅·대규모 리팩터만 Opus로 올리는 게 합리적이다. 모델을 세션 중간에 바꾸면 프롬프트 캐시가 무효화되니, 자주 토글하지 말고 작업 단위로 결정하라.

Claude Code를 띄우면 프롬프트가 뜬다. 그냥 자연어로 지시하면 된다.

> src/auth 디렉터리의 로그인 핸들러를 읽고, 세션 만료 처리가 어디서 되는지 설명해줘

모델이 알아서 glob로 파일을 찾고 grep으로 패턴을 뒤지고 관련 파일을 읽은 뒤 답한다. 당신이 파일을 첨부할 필요가 없다는 게 핵심이다.

자주 쓰는 슬래시 커맨드

커맨드	역할
/help	사용 가능한 커맨드 목록
/clear	대화 컨텍스트 초기화 (새 작업 시작 시 필수)
/compact	대화를 요약해 컨텍스트 압축 (긴 세션에서)
/model	모델 전환
/init	코드베이스를 분석해 CLAUDE.md 생성
/review	PR/diff 리뷰
/agents	서브에이전트 정의 관리
/mcp	MCP 서버 상태 확인
/config	설정 (테마·모델 등)
/cost	현재 세션의 토큰 사용량/비용

작업 루프와 컨텍스트 위생

에이전틱 코딩에서 가장 흔한 실수는 한 세션에서 여러 무관한 작업을 섞는 것이다. 컨텍스트가 오염되면 모델이 앞선 작업의 잔재를 끌고 와 엉뚱한 판단을 한다.

원칙:

1. 새 작업 = /clear — 버그 수정이 끝났으면 다음 기능 작업 전에 컨텍스트를 비운다.
2. 긴 작업 = /compact — 디버깅이 길어져 컨텍스트가 차오르면 압축한다. /compact는 대화를 요약본으로 대체해 핵심만 남긴다.
3. 계획부터 시키기 — 복잡한 작업은 "바로 고치지 말고 먼저 계획을 세워줘"라고 분리하면 품질이 올라간다. 모델이 코드를 읽고 접근법을 제시한 뒤, 당신이 승인하면 실행한다.

> 결제 모듈에 환불 기능을 추가하려고 해. 바로 코드 짜지 말고,
  먼저 관련 파일들을 읽고 어디를 어떻게 바꿔야 하는지 계획만 세워줘.

함정 — 컨텍스트 윈도우 착각: Claude Code는 대용량 컨텍스트를 다루지만 무한하지 않다. 거대한 로그나 전체 빌드 출력을 통째로 붙이면 컨텍스트를 잡아먹고 정작 코드 추론 여력이 줄어든다. 긴 출력은 파일로 저장하고 "이 파일에서 에러 라인만 찾아봐"라고 시키는 게 낫다.

CLAUDE.md는 Claude Code가 세션 시작 시 자동으로 읽는 프로젝트 메모리 파일이다. 코딩 규약, 빌드 명령어, 아키텍처 노트, 하지 말아야 할 것을 여기 적어두면 매번 설명할 필요가 없다.

자동 생성

빈 프로젝트라면 /init이 코드베이스를 분석해 초안을 만든다.

/init

그 다음 직접 다듬는다. 좋은 CLAUDE.md의 구성:

# 프로젝트: payments-api

## 빌드 / 테스트
- 설치: `pnpm install`
- 개발 서버: `pnpm dev`
- 테스트: `pnpm test` (변경 후 반드시 실행)
- 린트: `pnpm lint --fix`

## 아키텍처
- `src/routes/` — Express 라우트
- `src/services/` — 비즈니스 로직 (라우트에 로직 넣지 말 것)
- `src/db/` — Prisma. 스키마 변경 시 `pnpm prisma migrate dev` 필수

## 규약
- 금액은 항상 정수(센트) 단위. float 금지
- 에러는 `lib/api-error.ts`의 AppError만 사용. throw new Error 금지
- 커밋 메시지는 conventional commits (feat/fix/docs)

## 하지 말 것
- 운영 DB 직접 수정 금지
- 새 의존성 추가 전 반드시 물어볼 것

파일 위치와 계층

Claude Code는 여러 위치의 메모리 파일을 합쳐서 읽는다:

위치	범위	용도
./CLAUDE.md	프로젝트 (git에 커밋)	팀 전체가 공유하는 규약
./CLAUDE.local.md	프로젝트 (git 무시)	개인 로컬 설정
~/.claude/CLAUDE.md	전역 (모든 프로젝트)	개인의 보편적 선호

상위 디렉터리의 CLAUDE.md도 거슬러 올라가며 읽으므로, 모노레포라면 루트에 공통 규약을, 각 패키지에 세부 규약을 둘 수 있다.

베스트 프랙티스

• 명령형으로, 간결하게. "코드는 깔끔하게" 같은 추상적 문장은 효과가 약하다. "금액은 정수 센트"처럼 검증 가능한 규칙을 쓴다.
• "하지 말 것" 섹션을 둬라. 모델이 반복하는 실수가 있으면 즉시 여기 추가한다. 이게 누적되면 _복리 효과_가 난다 — 같은 실수를 두 번 설명하지 않는다.
• 빌드/테스트 명령어를 꼭 적어라. 모델이 변경 후 스스로 검증하려면 어떤 명령을 돌릴지 알아야 한다.
• 너무 길게 쓰지 마라. CLAUDE.md는 매 세션 컨텍스트에 주입된다. 1000줄짜리는 비용이자 노이즈다. 핵심만 남기고 세부는 별도 문서로 링크한다.

실전 팁: 작업 중 모델이 규약을 어기면 "방금 그거 CLAUDE.md에 규칙으로 추가해줘"라고 시킬 수 있다. 메모리가 살아 있는 문서가 된다.

Claude Code는 파일을 수정하고 명령을 실행할 수 있으므로, 권한 게이트가 안전장치다. 기본적으로 위험한 동작(파일 쓰기, 명령 실행)은 실행 전에 당신에게 묻는다.

Claude wants to run: pnpm test
  [y] yes  [a] yes, and don't ask again for pnpm test  [n] no

매번 y를 누르는 게 번거로우면 **허용 목록(allowlist)**을 설정에 박아둔다. 설정 파일은 .claude/settings.json(프로젝트, git 커밋) 또는 ~/.claude/settings.json(전역)이다.

{
  "permissions": {
    "allow": [
      "Bash(pnpm test)",
      "Bash(pnpm lint:*)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Read(./src/**)",
      "Edit(./src/**)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  }
}

• allow — 묻지 않고 바로 실행
• deny — 절대 실행 안 함 (allow보다 우선)
• 패턴: Bash(pnpm lint:*)의 :*는 pnpm lint 뒤에 무엇이 붙어도 매칭

deny로 비밀을 보호하라

.env, 키 파일, 토큰이 든 디렉터리는 deny의 Read로 막는 게 좋다. 모델이 실수로 읽어 컨텍스트(그리고 로그)에 비밀이 섞이는 걸 막는다.

"deny": [
  "Read(./.env)",
  "Read(./.env.*)",
  "Read(**/credentials.json)"
]

위험한 단축 — --dangerously-skip-permissions

모든 권한 확인을 건너뛰는 플래그가 있다. 헤드리스/CI에서 신뢰된 환경(격리된 컨테이너)일 때만 쓴다.

# 격리된 CI 컨테이너 안에서만!
claude -p "테스트 통과시켜줘" --dangerously-skip-permissions

절대 로컬 개발 머신에서 일상적으로 쓰지 마라. 모델이 잘못된 rm이나 git reset --hard를 돌리면 복구 불가다. 이름이 dangerously인 데는 이유가 있다.

베스트 프랙티스

• 읽기 전용·테스트·린트 같은 안전하고 반복적인 명령만 allowlist에 올린다.
• 파괴적 동작(force, reset --hard, rm, 배포)은 절대 allowlist에 넣지 않는다.
• 팀 공유 규칙은 .claude/settings.json(커밋), 개인 규칙은 .claude/settings.local.json(git 무시)으로 분리한다.

MCP(Model Context Protocol)는 Claude Code에 외부 도구·데이터 소스를 붙이는 표준이다. 이걸로 모델이 Notion에 페이지를 만들고, Slack 메시지를 읽고, Supabase에서 SQL을 돌리고, GitHub PR을 다룰 수 있다. MCP 서버는 "도구 묶음을 노출하는 작은 프로세스"라고 보면 된다.

MCP 서버 추가

claude mcp add 명령으로 등록한다. 두 가지 전송 방식이 있다:

# 로컬 stdio 서버 (로컬에서 프로세스로 실행)
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/projects

# 원격 HTTP/SSE 서버
claude mcp add --transport sse linear https://mcp.linear.app/sse

등록하면 .mcp.json(프로젝트 범위) 또는 사용자 설정에 기록된다. 프로젝트 .mcp.json은 팀이 공유할 수 있다.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

비밀은 .mcp.json에 평문으로 박지 말고 ${ENV_VAR} 참조로 두고 환경변수로 주입하라. 이 파일을 git에 커밋한다면 더더욱.

상태 확인과 사용

/mcp

로 연결 상태를 본다. 연결되면 모델이 해당 도구를 자동으로 인식해, "이 버그를 Linear에 이슈로 등록해줘" 같은 지시에 MCP 도구를 호출한다.

인증

Notion·Slack 같은 원격 MCP 서버는 보통 OAuth를 쓴다. 처음 도구를 호출할 때 브라우저 인증 흐름이 뜬다. 일부는 짧은 수명의 토큰을 쓰므로 세션 중 끊겼다 자가 복구되기도 한다 — 이게 정상 동작이다.

함정

• MCP 서버 = 외부 코드. 신뢰할 수 있는 서버만 붙여라. 도구는 임의의 동작을 할 수 있다.
• 도구 과다. 서버를 10개 붙이면 도구 수십 개가 컨텍스트에 올라가 모델이 혼란스러워진다. 작업에 필요한 것만 활성화하라.
• MCP 도구도 권한 게이트를 탄다. 쓰기 동작(메시지 발송, 레코드 삭제)은 확인을 받도록 설정에서 관리하라. 외부로 나가는·되돌릴 수 없는 동작일수록 게이트가 중요하다.
• .mcp.json 커밋 주의. 환경에 따라 MCP 설정 형식이 다를 수 있어 무턱대고 커밋하면 다른 팀원 환경에서 깨질 수 있다. 토큰이 들어가는 경우 특히 신중하게.

서브에이전트는 특정 역할에 특화된 별도 에이전트다. 메인 세션이 작업을 서브에이전트에 위임하면, 서브에이전트는 _자기만의 컨텍스트 윈도우_에서 일하고 결과만 돌려준다. 두 가지 이점이 있다:

1. 컨텍스트 격리 — 코드 리뷰 같은 토큰 많이 먹는 작업이 메인 대화를 오염시키지 않는다.
2. 전문화 — 리뷰어·테스터·리서처를 각각 다른 시스템 프롬프트와 도구 권한으로 정의할 수 있다.

정의 위치

서브에이전트는 마크다운 파일로 정의한다:

위치	범위
.claude/agents/	프로젝트 (팀 공유)
~/.claude/agents/	전역 (모든 프로젝트)

/agents 커맨드로 대화형으로 만들거나 직접 파일을 쓴다. 형식은 YAML frontmatter + 시스템 프롬프트다:

---
name: security-reviewer
description: 보안 관점에서 코드 변경을 리뷰한다. 인증·인가·입력 검증·비밀 노출에 집중.
tools: Read, Grep, Glob
model: opus
---

당신은 시니어 보안 엔지니어다. 주어진 diff나 파일을 다음 관점에서만 검토한다:

- 인증/인가 우회 가능성
- SQL 인젝션, XSS, 경로 순회
- 하드코딩된 비밀, 로그에 찍히는 민감정보
- 입력 검증 누락

각 발견을 [치명적/중요/경미]로 분류하고, 정확한 파일·라인과 수정 제안을 제시하라.
구현은 하지 말고 발견과 권고만 반환하라.

• name — 호출 식별자
• description — 이게 중요하다. 메인 에이전트가 언제 이 서브에이전트를 부를지 판단하는 근거다. "~할 때" 식으로 트리거 조건을 명확히 써라.
• tools — 이 서브에이전트가 쓸 수 있는 도구를 제한. 리뷰어는 읽기 도구만 줘서 실수로 코드를 못 고치게 한다.
• model — 작업 난이도에 맞춰 모델 지정 (단순 작업은 sonnet으로 비용 절감)

사용

명시적으로 부르거나:

> security-reviewer 서브에이전트로 방금 변경한 인증 코드를 검토해줘

또는 메인 에이전트가 description을 보고 자동으로 위임한다. 여러 서브에이전트를 병렬로 띄워 다관점 리뷰(보안·성능·과설계)를 동시에 돌릴 수도 있다.

베스트 프랙티스

• 도구를 최소로. 리뷰어·리서처에는 쓰기 도구를 주지 않는다. 권한을 좁히면 사고 반경이 줄어든다.
• description에 트리거를 명시. 모호하면 자동 위임이 안 일어난다.
• 읽기 전용 탐색은 서브에이전트로. 거대한 코드베이스를 뒤지는 작업을 sonnet 서브에이전트에 맡기면 메인 컨텍스트와 비용을 아낀다.
• 자기검수 금지. 코드를 짠 에이전트가 자기 코드를 리뷰하면 편향된다. 별도 리뷰어 서브에이전트를 둬라.

서브에이전트와 메모리는 "모델에게 부탁"하는 것이라 100% 보장이 안 된다. Hooks는 다르다 — 특정 이벤트에서 하니스가 직접 셸 명령을 실행한다. 모델의 판단이 개입하지 않으므로 결정적이다.

"수정할 때마다 prettier를 돌려라", "커밋 전 반드시 테스트를 통과시켜라" 같은 반드시 매번 일어나야 하는 규칙은 메모리가 아니라 Hook으로 구현해야 한다.

설정 위치와 이벤트

Hook은 .claude/settings.json에 정의한다. 주요 이벤트:

이벤트	발화 시점
PreToolUse	도구 실행 전 (차단 가능)
PostToolUse	도구 실행 후 (예: 파일 수정 후 포맷)
UserPromptSubmit	사용자가 프롬프트를 제출할 때
Stop	에이전트가 응답을 마칠 때
SessionStart	세션 시작 시 (컨텍스트 주입 등)

예시 — 수정 후 자동 포맷

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm prettier --write \"$CLAUDE_FILE_PATHS\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

Edit나 Write 도구가 돈 직후, 수정된 파일에 prettier가 자동으로 돈다. 모델은 이걸 "잊을" 수 없다 — 하니스가 강제한다.

예시 — 위험한 명령 차단

PreToolUse Hook은 종료 코드로 동작을 통제한다. 0이 아닌 종료 코드(특히 2)는 도구 실행을 막는다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|git push --force' && echo 'blocked' >&2 && exit 2 || exit 0"
          }
        ]
      }
    ]
  }
}

함정과 베스트 프랙티스

• Hook은 _당신_의 권한으로 돈다. 임의 셸 명령이므로, 신뢰할 수 없는 입력을 그대로 명령에 끼워 넣으면 인젝션 위험이 있다. 입력을 인용·검증하라.
• 조용히 실패하지 않게. Hook이 깨지면 자동화가 무음으로 안 돌 수 있다. 중요한 Hook은 로그를 남겨라.
• 메모리 vs Hook 구분. "~하는 게 좋다"는 권고는 CLAUDE.md로, "매번 반드시 ~한다"는 강제는 Hook으로. 자동화 규칙("~할 때마다 X해라")은 모델 기억이 아니라 하니스가 실행해야 하므로 Hook이 정답이다.
• /config 또는 전용 설정 스킬로 관리. 손으로 JSON을 편집하다 문법 오류 나면 Hook 전체가 무시될 수 있다.

Claude Code는 대화형뿐 아니라 **헤드리스(비대화형)**로도 돈다. -p(print) 플래그로 한 번 실행하고 결과를 stdout으로 받는다. 이게 CI·cron·스크립트 통합의 출발점이다.

# 한 번 실행하고 결과 출력
claude -p "CHANGELOG.md를 최근 git 커밋 기준으로 업데이트해줘"

JSON 출력으로 파이프라인 구성

--output-format json을 쓰면 결과를 구조화해서 받아 다른 도구로 넘길 수 있다.

claude -p "이 PR diff에 보안 이슈가 있는지 검토하고 발견 사항만 보고해" \
  --output-format json | jq -r '.result'

실전 — CI에서 자동 리뷰

# .github/workflows/ai-review.yml (개념 예시)
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
      - name: Run review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          git diff origin/main...HEAD > /tmp/pr.diff
          claude -p "$(cat /tmp/pr.diff) — 이 diff를 리뷰하고 버그·보안 이슈를 마크다운으로 정리해" \
            --output-format text > review.md
      - name: Post review
        run: gh pr comment ${{ github.event.number }} --body-file review.md

권한과 격리

헤드리스는 권한 확인 프롬프트에 응답할 사람이 없다. 그래서 두 가지 선택지가 있다:

1. 설정 allowlist — 필요한 도구만 미리 허용 (안전, 권장)
2. --dangerously-skip-permissions — 모든 확인 생략 (격리된 컨테이너에서만)

CI는 일회성 격리 컨테이너이므로 후자가 쓰일 수 있지만, 그래도 deny 목록으로 비밀 파일 읽기와 파괴적 명령은 막아두는 게 안전하다.

베스트 프랙티스

• API 키 인증을 써라. 헤드리스/CI에서는 구독 로그인의 브라우저 흐름이 불가능하다. ANTHROPIC_API_KEY를 시크릿으로 주입한다.
• 예산을 의식하라. 종량제이므로 무한 루프나 거대 입력은 비용 폭탄이 된다. 입력을 제한하고 작업 범위를 좁게 잡아라.
• 결과를 검증하라. 헤드리스 출력을 그대로 믿고 자동 머지하지 마라. 리뷰·요약은 사람이 확인하는 단계로 남겨두는 게 안전하다.
• 모델을 명시. CI에서는 작업 성격에 따라 --model을 고정해 비용/품질을 예측 가능하게 한다.

Claude Code의 진가는 탐색하고 검증하는 능력에 있다. 단순 코드 생성이 아니라 다음 같은 루프를 자동으로 돈다.

버그 디버깅 루프

> 결제 후 영수증 이메일이 가끔 안 나가. 관련 코드를 찾아서
  원인을 추적하고, 고친 다음 테스트로 검증해줘

모델이 하는 일:

1. grep/glob로 이메일 발송 코드 탐색
2. 관련 파일들을 읽고 흐름 추적
3. 원인 가설 수립 (예: fire-and-forget 비동기 호출이 응답 전에 종료됨)
4. 수정
5. CLAUDE.md에 적힌 테스트 명령으로 검증
6. 결과 보고

핵심은 5번이다 — 빌드/테스트 명령을 CLAUDE.md에 적어두면 모델이 스스로 검증한다. 안 적어두면 "고쳤습니다"라고만 하고 실제 동작은 확인 안 한 채 끝난다.

코드 탐색·온보딩

새 코드베이스에 들어갈 때:

> 이 프로젝트의 전체 구조를 설명하고, 요청이 들어와서 응답이 나가기까지의
  주요 경로를 파일 단위로 짚어줘

거대한 탐색은 서브에이전트(sonnet)에 맡기면 메인 컨텍스트와 비용을 아낀다.

이미지·스크린샷 활용

Claude Code는 이미지를 읽을 수 있다. UI 버그 스크린샷이나 디자인 목업을 보여주고 "이 레이아웃처럼 만들어줘" 또는 "이 에러 화면의 원인을 코드에서 찾아줘"라고 할 수 있다. 터미널에 이미지 경로를 드래그하거나 붙여 넣는다.

자가 검증을 시스템화하기

중요한 검증은 모델에게 부탁하지 말고 강제하라:

• PostToolUse Hook으로 수정 후 자동 테스트/린트
• CLAUDE.md의 "변경 후 반드시 pnpm test 실행" 규칙
• 복잡한 작업은 별도 리뷰어 서브에이전트로 교차 검증

베스트 프랙티스: "고쳤다"는 주장을 그대로 믿지 마라. 모델이 테스트를 실제로 돌렸는지, 출력이 통과를 보여주는지 확인하라. 특히 빈 상태(신규 사용자, 빈 DB)에서 핵심 플로우가 진짜로 도는지는 사람이 검증해야 하는 영역이다.

에이전틱 코딩은 토큰을 많이 쓴다. 파일을 읽고·도구를 호출하고·추론하는 매 턴이 비용이다. 관리 안 하면 종량제 청구가 빠르게 불어난다.

비용을 확인하는 법

/cost

로 현재 세션의 토큰 사용량과 비용을 본다. 헤드리스에서는 --output-format json 결과에 사용량 정보가 포함된다.

비용을 줄이는 레버

레버	방법
모델 선택	일상 작업은 Sonnet, 어려운 것만 Opus. /model로 작업별 전환
컨텍스트 위생	새 작업마다 /clear. 긴 세션은 /compact로 압축
서브에이전트	토큰 많이 먹는 탐색/리뷰를 격리해 메인 컨텍스트 오염 방지
CLAUDE.md 다이어트	매 세션 주입되므로 1000줄짜리는 매번 비용. 핵심만
입력 제한	거대 로그/빌드 출력을 통째로 붙이지 말고 파일로 저장 후 필요 부분만
프롬프트 캐시 보존	세션 중 모델·도구 세트를 자주 바꾸지 말 것 (캐시 무효화)

프롬프트 캐시를 깨뜨리지 마라

Claude Code는 내부적으로 프롬프트 캐싱을 활용해 반복되는 컨텍스트(시스템 프롬프트, CLAUDE.md, 도구 정의)를 싸게 재사용한다. 캐시는 _접두사 매칭_이라, 앞쪽이 바뀌면 뒤가 전부 무효화된다. 실무적으로:

• 세션 중 모델 전환을 남발하지 마라. 모델이 바뀌면 캐시가 전부 새로 써진다.
• MCP 도구를 세션 중간에 자주 켰다 껐다 하지 마라. 도구 세트가 바뀌면 캐시가 깨진다.
• 작업 단위로 결정하라. "이 작업은 Opus + GitHub MCP"로 고정하고 끝까지 그 구성으로 간다.

베스트 프랙티스 요약

1. 작업 범위를 좁게. "전체 코드베이스 리팩터"보다 "이 모듈 하나"가 싸고 정확하다.
2. 계획 → 실행 분리. 계획 단계에서 접근법을 합의하면 헛도는 토큰을 줄인다.
3. 검증은 Hook으로. 모델에게 테스트를 부탁하느라 토큰 쓰지 말고 PostToolUse Hook으로 자동화한다.
4. 자주 /clear. 컨텍스트 오염은 비용이자 품질 저하다.
5. /cost로 주기적 점검. 비용 감각이 있어야 모델·범위 결정이 합리적이 된다.

마지막 원칙: Claude Code는 _도구_지 마법이 아니다. CLAUDE.md로 규약을 명문화하고, Hook으로 검증을 강제하고, 서브에이전트로 역할을 나누고, 권한으로 사고를 막을수록 — 매 작업이 다음 작업을 더 쉽고 싸게 만든다. 이 복리 구조를 세팅하는 데 들인 시간이 가장 높은 ROI를 낸다.