Claude Code를
잘 쓰는 법

Claude Code를 오래 쓴 사람과 막 쓰기 시작한 사람의 차이는 프롬프트 실력이 아니다. "Claude Code가 어떤 모양의 입력을 소화하게 만들어졌는가"를 아는가다. 이 모양에 맞춰 프롬프트·메모리·세션을 짜면 같은 돈으로 두세 배의 일이 나온다.

이 책은 코드를 파는 책이 아니다. 코드 중심 버전은 같은 레포의 DEEP-DIVE.md에 따로 두었다. 이 책은 내부 구조에서 "왜 이렇게 만들었는가"를 역추적한 뒤 사용자로서 그 의도에 맞춰 쓰는 방법을 정리한 책이다.

예를 들어 이런 것들이 설명된다. 왜 긴 탐색을 서브에이전트에 넘기면 메인 대화가 훨씬 오래 버티는지. 왜 CLAUDE.md를 자주 바꾸면 비용이 늘어나는지. 왜 "이거 좀 도와줄래?"보다 "X를 고쳐라"가 결과가 좋은지. 왜 /compact를 자동보다 수동으로 치는 편이 더 안정적인지. 왜 훅이 block을 반환해도 다음 턴이 그냥 가는 경우가 있는지. 이 모두가 설계 의도의 결과다.

설계 의도

Claude Code의 한 턴은 함수 호출이 아니라 비동기 제너레이터다. 사용자 입력이 들어오면 LLM 응답 토큰 하나하나, 도구 실행 진행률, 파일 변경 알림, 스톱 훅 결과까지 모두 한 줄기 스트림으로 흐른다.

QueryEngine.ts · line 209export class QueryEngine {
  async *submitMessage(
    prompt: string | ContentBlockParam[],
    options?: { uuid?: string; isMeta?: boolean },
  ): AsyncGenerator<SDKMessage, void, unknown>
}

원작자들이 이 구조를 선택한 이유는 하나로 요약된다. LLM 응답이 길수록 사용자는 가다가 방향을 바꾸고 싶어진다. 기존 CLI들은 완성 후 표시 모델이라 끊으면 지금까지 한 일이 다 날아간다. Claude Code는 반대다. 끊어도 이미 쓴 파일은 남고, 도구 실행이 절반 된 상태면 그 절반은 디스크에 기록되어 있다.

무엇이 달라지는가

스트리밍이기 때문에 중간 개입이 공짜다. 기존 CLI에서는 한 번 실행하면 끝이라 신중하게 프롬프트를 짜야 했다. Claude Code는 반대다. 완벽한 프롬프트를 만드느라 30초 고민하느니 일단 던져놓고 첫 tool_use 두세 개를 본 뒤 판단하는 편이 빠르다. 프롬프트 엔지니어링 시간을 줄이고 관찰 시간을 늘려라.

설계 의도

도구의 모든 기본값이 보수적 쪽으로 세팅되어 있다. 새 도구를 만들면 자동으로 "읽기 전용 아님", "동시 실행 안전 아님", "파괴적 아님"으로 판정된다. 파일 편집은 반드시 Read가 선행되어야 하고, bash는 네 개의 독립된 권한 계층을 통과해야 한다.

Tool.ts · TOOL_DEFAULTSconst TOOL_DEFAULTS = {
  isEnabled:         () => true,
  // 모르면 직렬, 모르면 쓰기 가능, 모르면 비파괴 — 권한 검사가 별도로 잡는다
  isConcurrencySafe: () => false,
  isReadOnly:        () => false,
  isDestructive:     () => false,
  checkPermissions:  async () => ({ behavior: 'allow' }),
  toAutoClassifierInput: () => '',
}

BashTool은 특히 방어가 두텁다. 한 파일에 다 몰아넣지 않고 독립 파일 7개로 쪼갰다. 각 계층이 다른 계층을 몰라도 되게 해서, 하나가 뚫려도 나머지가 막는다.

무엇이 달라지는가

기본 권한 시스템을 신뢰하되, 훅으로 더 조여라. 많은 사용자가 --dangerously-skip-permissions를 기본값으로 쓰거나 acceptEdits 모드를 세션 내내 켜둔다. 이건 원작자의 의도를 역행하는 선택이다. 대신 PreToolUse 훅을 써라.

반복해서 프롬프트에 "git push --force는 하지 마"라고 쓸 필요가 없다. settings.json의 훅 한 줄로 막을 수 있다.

원작자들이 훅을 만든 이유가 바로 이것이다. 예상 못한 위험에 사용자가 직접 선을 그을 수 있게.

설계 의도

Claude Code 내부에는 토큰을 아끼기 위한 장치가 네 층이나 된다.

첫째, Deferred Tool Loading. 수십 개의 커맨드와 20개가 넘는 빌트인 도구 중 핵심만 시스템 프롬프트에 올라간다. 나머지는 모델이 ToolSearch로 검색할 때에만 스키마가 로드된다. 이 한 가지로 초기 프롬프트가 수천 토큰 가벼워진다.

둘째, 4단계 자동 압축. 가벼운 정리에서 시작해 읽기 전용 구간 축약을 거쳐 실제 LLM 요약까지, 필요한 만큼만 공격적으로 돈다. 그리고 압축 직후에는 "최근 변경 파일 5개"를 다시 밀어 넣어 방금 한 작업의 맥락을 보존한다.

셋째, Prompt Caching 할인. 같은 접두사가 반복되면 캐시 읽기는 원가의 10%, 캐시 쓰기(첫 적재)는 125%다. 첫 호출만 약간 더 비쌀 뿐, 이후부터는 매 호출이 90% 할인이라 대화가 길어질수록 실질 비용이 떨어진다.

넷째, 서브에이전트 독립 버짓. 병렬로 4개를 돌리면 비용은 4배가 되지만, 각자 독립 예산이라 메인 대화가 서브 조사 때문에 일찍 끊기는 사고가 나지 않는다.

무엇이 달라지는가

CLAUDE.md는 어떻게 짜야 하는가

캐시 효율과 실용성을 동시에 잡는 구조가 있다.

글로벌 (~/.claude/CLAUDE.md): 나에 대한 고정 사실만. 코딩 스타일, 커밋 규칙, 금지 사항. 한 달에 한 번 이하로 수정. 20줄 이내.

프로젝트 (.claude/CLAUDE.md): 이 레포에 특화된 규칙. 빌드 명령, 테스트 방법, 아키텍처 요약. 자주 바뀌어도 괜찮다 — 프로젝트 단위 캐시라서 글로벌 캐시에 영향을 주지 않는다.

~/.claude/CLAUDE.md · 글로벌 예시# 코딩 스타일
TypeScript 우선. React + Next.js + Tailwind.
함수형 컴포넌트 + hooks. class 금지.
camelCase 변수, PascalCase 컴포넌트.
주석은 "왜"만 쓴다.

# 커밋
Conventional Commits (feat/fix/refactor/docs/test/chore).
console.log 디버깅 코드를 커밋에 남기지 않는다.

# 금지
내가 물어보지 않은 것을 설명하지 마라.
package.json에 불필요한 의존성 추가하지 마라.

.claude/CLAUDE.md · 프로젝트 예시# 이 프로젝트
Next.js 15 + App Router. /src/app 기반.
DB: Supabase (Postgres). ORM: Drizzle.

# 빌드
pnpm dev → localhost:3000
pnpm test → vitest
pnpm lint → eslint + prettier

# 주의
/src/lib/auth.ts는 건드리지 마라 (인증 로직 안정화 중).
API 라우트는 /src/app/api/ 아래에만.

설계 의도

AgentTool이 서브에이전트를 만들 때 가장 흥미로운 점은 격리 방식이다. 서브에이전트는 부모의 권한과 도구는 모두 상속하지만, 메인 AppState에는 쓸 수 없다. 태스크 레지스트리 같은 인프라만 예외로 공유하고, 나머지는 "부모는 읽기 전용, 결과는 메시지로만" 원칙이다.

이게 왜 중요한가. LLM은 컨텍스트가 길어질수록 품질이 떨어진다. 모델 벤더들이 "100만 토큰 지원"을 자랑하지만, 실무에서 50만 토큰을 채운 대화는 20만 토큰일 때보다 답이 흐릿하다. 원작자들은 이걸 알고 있었다. 그래서 메인 대화를 최대한 깨끗하게 유지하는 것을 최우선으로 두고, 탐색·조사·검증 같은 "토큰을 많이 먹지만 결과는 짧은" 작업을 전부 격리된 서브에이전트로 밀어냈다.

무엇이 달라지는가

병렬로 서브에이전트를 돌리는 것을 두려워하지 마라. 격리되어 있으니 상태 충돌이 없다. 단, 파일 쓰기 범위가 겹치지 않게 에이전트별 스코프를 명시해라. "Agent A는 /services만, Agent B는 /components만." 이걸 프롬프트에 박아놓지 않으면 둘이 같은 파일을 동시에 건드려 덮어쓰는 사고가 난다.

검증은 반드시 별도 에이전트로. 구현한 에이전트에게 "네가 한 거 맞아?"를 물으면 답은 항상 "맞다"다. code-reviewer 에이전트를 별도로 띄워서 똑같은 결과물을 처음 보는 시선으로 읽게 해라. 원작자들이 AgentTool을 격리한 이유가 바로 이 새 시선이다.

설계 의도

훅 시스템은 PreToolUse, PostToolUse, SessionStart, UserPromptSubmit, Stop 같은 이벤트에 사용자가 스크립트를 걸 수 있게 한다. 가장 강력한 기능은 PreToolUse의 updatedInput이다. 모델이 호출한 도구 입력을 훅이 다시 써서 돌려줄 수 있다.

Hook 응답 스키마{
  "continue": true,
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    // 모델이 호출한 입력을 훅이 고쳐서 돌려준다
    "updatedInput": {
      "command": "git commit -m 'fix' --signoff"
    },
    "additionalContext": "자동 signoff 추가됨"
  }
}

예를 들어 모델이 git commit -m "fix"를 호출하면 훅이 그걸 받아서 git commit -m "fix" --signoff로 바꿔서 실제 실행으로 넘긴다. 모델은 자기가 쓴 명령이 통과된 줄 안다. 사용자는 자기 정책을 조용히 얹었다.

무엇이 달라지는가

프롬프트로 반복해서 주의를 주지 말고 훅으로 박아라. "git push --force 하지 마", "rm -rf 하지 마", "console.log 남기지 마" 같은 지시를 매번 프롬프트에 넣는 건 낭비다. 한 번 훅으로 만들면 영원히 작동한다. 토큰도 아끼고 실수도 막는다.

훅과 스킬·커맨드의 구분은 Chapter 10에서 다룬다. 여기서는 훅 내부 메커니즘만 집중한다.

EnterPlanModeTool은 아무 입력도 받지 않는다. 단지 세션 상태를 "plan 모드"로 바꿀 뿐이다. 이 모드에서는 파일 편집 도구가 모두 잠긴다. Read, Grep, Glob 같은 읽기 전용만 살아남는다.

왜 이걸 별도 상태로 만들었는가. 탐색 중에는 "가능한 방법을 넓게 보는" 사고가 필요하고, 변경 중에는 "정확히 한 가지를 수행하는" 사고가 필요하다. LLM도 사람도 이 둘을 동시에 하면 품질이 떨어진다.

진입 기준

다섯 개 이상 파일에 걸친 변경. 요구사항이 불명확한 상태. 비가역 작업 포함 — DB 마이그레이션, 파일 삭제, git reset 같은 것들. 프레임워크 업그레이드 같은 환경 변경. 처음 보는 코드베이스 탐색. 이 다섯 중 하나라도 해당하면 플랜 모드로 먼저 들어가는 편이 안전하다.

진입 후 흐름

넓게 읽고, 질문을 정리하고, 계획을 글로 쓰고, 계획을 비판하고, 확정되면 ExitPlanMode로 나와서 실행한다. 다섯 단계 중 어느 하나라도 건너뛰면 플랜의 의미가 없다. 특히 네 번째 "계획을 비판한다"가 핵심이다. "이 계획의 약점은?" "빠진 케이스는?"을 모델에게 한 번 더 묻는 것만으로 놓친 부분이 드러난다.

설계 의도

Claude Code의 메모리는 데이터베이스가 아니다. ~/.claude/projects/<프로젝트>/memory/ 아래에 마크다운 파일로 저장된다. MEMORY.md가 인덱스고, 상세 내용은 topics/ 아래 개별 파일이다. 인덱스는 25KB / 200줄 제한이 있고, 초과하면 경고와 함께 잘린다.

무엇이 달라지는가

타입별 기본 사용법. user 타입은 나에 대한 장기 사실 — 한 번 넣고 거의 안 고친다. feedback은 반복 실수 교정 — 실수할 때마다 늘어난다. project는 프로젝트 구조 — 자주 바뀌는 건 주의. reference는 외부 링크 모음.

git으로 버전 관리하라. ~/.claude/projects/<slug>/memory/를 git 리포로 만들어두면 "언제 어떤 메모리가 추가됐는지" 추적할 수 있다. 메모리 오염 사고(잘못된 사실 기억)가 났을 때 롤백 가능하다.

Claude Code의 시스템 프롬프트는 이미 "도구를 써서 해결해라"를 깔아놓았다. 그래서 사용자 프롬프트는 설명하는 글이 아니라 지시하는 문장이어야 한다. 대답을 구하면 도구 쓰기를 포기하고, 긴 탐구를 구하면 서브에이전트로 위임한다.

3단 구조 · 목표 + 제약 + 검증

[목표] login form의 이메일 validation을 RFC 5322로 고쳐라.
[파일] src/components/LoginForm.tsx, src/utils/validation.ts
[제약] UI 마크업은 건드리지 마라. 기존 props 시그니처 유지.
[검증] npm test가 모두 통과해야 한다. 새 케이스 3개 추가해라.
[금지] 다른 폼 컴포넌트는 건드리지 마라.

이걸 복붙 템플릿으로 만들어두면 생각하는 시간이 줄어든다. 목표만 있으면 제약을 임의로 깬다. 제약만 있으면 목표가 흐려진다. 검증이 없으면 "대충 끝났다"로 종료한다.

안 먹히는 모양

"생각해보니…" 뒤에 나오는 요청. 결정이 안 끝난 사고과정을 프롬프트에 넣으면 모델도 흐려진다. 결정을 먼저 내리고 요청해라.

여러 작업을 한 프롬프트에. "A 하고 B 하고 C 해줘"는 거의 항상 B가 대충 된다. 한 턴 한 작업.

"가능하면…". 조건부 요청은 LLM이 조건 판단을 피하는 쪽으로 움직인다. 하라면 하라, 말라면 말라.

기능 완료는 새 세션 시작. 실험적 변경은 워크트리 진입. 작은 고침 여러 개는 한 세션 여러 턴. 하루의 시작에는 어제 세션을 resume할지 새로 시작할지 먼저 결정한다.

워크트리는 언제 쓰나

기존 브랜치를 건드리지 않고 실험하고 싶을 때다. EnterWorktree를 쓰면 현재 레포의 복사본이 임시 디렉토리에 생기고, 그 안에서 자유롭게 작업한다. 결과가 마음에 들면 머지, 아니면 그냥 버린다. 메인 코드가 실험 잔해로 더러워지지 않는다.

세션을 이어갈까, 새로 시작할까

이어가는 게 나은 경우. 같은 기능의 후속 작업. 버그 수정 후 테스트 추가. 리뷰 피드백 반영. 컨텍스트가 아직 유효하다.

새로 시작하는 게 나은 경우. 다른 도메인으로 넘어갈 때. 세션이 길어져서 모델이 초반 지시를 잊기 시작할 때. /compact를 두 번 이상 쳤는데도 맥락이 흐려질 때. 이 때는 끊고 새 세션에서 “방금 X를 완료했다. 다음은 Y다”로 시작하는 편이 낫다.

판단 기준은 단순하다. “지금 이 세션이 내가 원하는 걸 알고 있나?” 아니면 새로 시작.

예시로 보는 구분

"블로그 글을 3개 플랫폼에 동시 발행해줘." 자주 쓰는 자연어 트리거다. Skill로 만든다. whenToUse에 "블로그 발행"이라고 써두면 모델이 알아서 호출한다.

"git push 전에 반드시 lint를 돌려라." 매번 자동으로 끼어들어야 한다. Hook으로 만든다. PreToolUse 이벤트에 matcher를 Bash로 걸고, 명령이 git push면 lint 먼저. 프롬프트에 매번 넣지 마라.

훅의 내부 동작(updatedInput, blocking 분기)은 Chapter 05에서 다뤘다.

"특정 프로젝트 상태 요약이 필요하다." 내가 원할 때 치는 단축이다. Command. /status를 치면 요약이 나오게.

"Notion에서 할 일을 가져와야 한다." 외부 시스템 연결이다. MCP Server. Notion의 API를 감싸는 MCP 서버를 연결한다. 스킬이나 커맨드 안에서 MCP 서버의 도구를 호출.

MCP 서버 연결하기

MCP(Model Context Protocol)는 Claude Code를 외부 시스템과 연결하는 표준이다. Notion, Gmail, Linear, Slack 같은 서비스를 도구로 쓸 수 있게 해준다.

설정은 .claude/mcp.json에 한다.

.claude/mcp.json{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    },
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

stdio vs SSE. 로컬 프로세스를 띄우는 건 stdio. 원격 서버에 연결하는 건 sse로 URL을 넣는다. 대부분의 커뮤니티 서버는 stdio다.

주의. MCP 서버가 등록되면 해당 도구들이 ToolSearch에 deferred tool로 올라간다. 모델이 필요할 때 검색해서 호출한다. 매 턴 시스템 프롬프트에 올라가지 않으므로 토큰 비용은 크지 않다.

위임 신호

파일을 3개 이상 읽어야 한다. 작업 결과가 파일 수정이 아니라 요약이나 리포트다. 같은 패턴의 작업을 독립적으로 여러 번 해야 한다. 결과물이 메인 컨텍스트에 남지 않아도 된다. 현재 컨텍스트를 오염시키고 싶지 않다. 이 중 하나라도 해당하면 서브에이전트에 넘겨라.

위임하지 말 신호

반대로 다음은 메인에서 해야 한다. 이 작업 결과가 다음 턴의 전제가 된다. 사용자와 대화하며 조정해야 한다. 인터랙티브한 결정이 필요하다. 도메인이 불명확해서 서브에이전트에 스펙을 쓸 수 없다.

병렬 위임 시 파일 스코프 분리와 에이전트 수 제한은 Chapter 04를 참고하라. 여기서는 언제 위임을 결정하는가에 집중한다.

직접 열어볼 파일들

문제가 생기면 위에서부터 차례로 연다. ~/.claude/sessions/<proj>/session-<id>.jsonl에 현재 세션 원본이 있다. ~/.claude/history.jsonl에 전역 히스토리가 있다. ~/.claude/projects/<slug>/memory/MEMORY.md가 인덱스 메모리, 그 아래 topics/에 상세 메모리. 훅·MCP·LSP 로그는 ~/.claude/logs/ 아래에 있다(있는 경우).

0~5분: 세션 세팅

새 터미널을 열고 프로젝트 루트에서 Claude Code를 시작한다. 첫 프롬프트에 목표·제약·검증 기준을 한 번에 넣는다. 이게 캐시의 접두사가 된다.

[목표] 이 레포의 아키텍처를 파악하고 README를 보강해라.
[제약] 코드를 수정하지 마라. 읽기만.
[검증] 주요 진입점, 데이터 흐름, 의존성 구조를 설명할 수 있어야 한다.

5~15분: Explore 에이전트 병렬 투입

"프로젝트 구조를 파악해라"라고 직접 시키지 않는다. 대신 3개 질문을 서브에이전트에 던진다.

1. "진입점은 어디인가? main, index, app 파일을 찾아라."
2. "핵심 데이터 모델은? 타입 정의 파일들을 찾아라."
3. "외부 의존성은 뭔가? package.json / go.mod / requirements.txt를 읽어라."

메인 스레드는 이 결과를 기다리면서 README.md와 CLAUDE.md가 있으면 먼저 읽는다. 3파일 룰 — 메인은 읽기만, 무거운 탐색은 서브가.

15~25분: 지도 그리기

서브에이전트 결과가 돌아오면 메인에서 합성한다. "진입점은 X, 데이터는 Y를 거쳐 Z로 간다, 외부 의존성은 A·B·C." 이 한 단락이 이 레포에 대한 멘탈 모델이 된다.

여기서 /compact를 한 번 친다. 탐색 결과가 컨텍스트에 쌓여 있으니 정리해야 다음 작업이 효율적이다.

25~30분: 첫 작업 착수

멘탈 모델이 잡혔으면 실제 작업(README 작성, 버그 수정, 기능 추가)을 시작한다. 이때부터는 구현 에이전트(Sonnet)를 위임하고 메인은 판단만 한다.

핵심은 첫 15분을 탐색에 쓰는 것이다. 바로 코드를 고치기 시작하면 컨텍스트가 탐색 잔해로 오염된다. 탐색을 서브에이전트에 격리하면 메인은 깨끗한 상태에서 구현에 집중할 수 있다.

세션 복구 방법(마지막 몇 줄 잘라내고 재시작)은 Chapter 09에서 다뤘다.

이 책의 핵심 주장은 한 문장이다. Claude Code를 잘 쓰는 방법은 내부 구조를 따라가는 것이다.

프롬프트 엔지니어링 팁, 치트 시트, 매직 워드. 그런 것들은 표면이다. 표면은 버전이 올라가면 바뀐다. 반면 설계 의도는 쉽게 바뀌지 않는다. 원작자들이 "스트리밍 제너레이터 하나로 모든 것을 흘리기로" 결정한 순간부터 지금까지, 그리고 앞으로도, Claude Code를 잘 쓰는 사람의 습관은 이 결정과 맞닿아 있을 것이다.

나머지는 응용이다.