Claude Code 마스터 클래스
Master Class

Claude Code 마스터 클래스

설치부터 오케스트레이션까지 — Claude Code의 확장 기능 전반을 하나의 강의로 정리했습니다.

각 챕터는 실제 설정 예제·표·흐름도로 개념을 단계적으로 익히도록 구성되어 있습니다.

설치·시작권한·플랜모델명령어CLAUDE.md자동 기억서브에이전트스킬훅MCP·플러그인오케스트레이션컨텍스트 엔지니어링하네스·루프프롬프트 가이드플레이그라운드부록참고 자료
CHAPTER 01

Claude Code란? · 설치

이 강의는 Claude Code를 처음 켜는 순간부터 실무에서 여러 에이전트를 오케스트레이션하기까지를 다룹니다. 이 첫 챕터는 "Claude Code가 대체 무엇이고, 내 컴퓨터에 어떻게 설치해 첫 세션을 여는가"에 답합니다.

Claude Code란 무엇인가

Claude Code는 터미널에서 동작하는 에이전틱(agentic) 코딩 도구입니다. 질문에 답하고 기다리는 챗봇과 달리, Claude Code는 당신의 파일을 직접 읽고, 명령을 실행하고, 코드를 수정하며, 문제를 스스로 풀어 나갑니다. 당신은 그 과정을 지켜보거나, 방향을 바꾸거나, 아예 자리를 비울 수도 있습니다.

이것이 일하는 방식을 바꿉니다. 직접 코드를 짜서 Claude에게 리뷰를 부탁하는 대신, 원하는 것을 서술하면 Claude가 어떻게 만들지 알아냅니다 — 탐색하고, 계획하고, 구현합니다.

어디서 쓸 수 있나: 터미널 CLI가 기본이지만, 데스크톱 앱(Mac/Windows/Linux), 웹(claude.ai/code), IDE 확장(VS Code, JetBrains)에서도 동일한 엔진을 씁니다. 이 강의는 CLI 기준으로 설명하지만 개념은 모든 곳에 적용됩니다.

필요 계정: Claude Code는 Pro, Max, Team, Enterprise, 또는 Console(API) 계정이 필요합니다. 무료 Claude.ai 요금제로는 사용할 수 없습니다. Amazon Bedrock, Google Vertex AI, Microsoft Foundry 같은 제3자 API 제공자로도 사용 가능합니다.


설치하기

시스템 요구사항: macOS 13+, Windows 10(1809)+, Ubuntu 20.04+/Debian 10+, 4GB+ RAM. 인터넷 연결 필요.

방법 1 — 네이티브 설치 (권장)

가장 간단하고, 백그라운드 자동 업데이트를 지원합니다.

# macOS · Linux · WSL
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

방법 2 — 패키지 매니저

brew install --cask claude-code          # macOS (Homebrew)
winget install Anthropic.ClaudeCode      # Windows (WinGet)
npm install -g @anthropic-ai/claude-code # npm (Node.js 22+ 필요)

Homebrew·WinGet·npm 설치는 자동 업데이트되지 않습니다 — 각각 brew upgrade claude-code, winget upgrade Anthropic.ClaudeCode, npm install -g @anthropic-ai/claude-code@latest로 갱신하세요. sudo npm install -g는 권한 문제·보안 위험 때문에 금지.

설치 확인

claude --version     # 예: 2.1.211 (Claude Code)
claude doctor        # 설치·설정 진단 (세션을 열지 않고 점검만)

Windows 팁: 네이티브 Windows에서 Git for Windows를 설치하면 Bash 도구를 쓸 수 있습니다(없으면 PowerShell 사용). 리눅스 툴체인이나 샌드박싱이 필요하면 WSL 2를 권장합니다.


첫 세션 열기

작업할 프로젝트 폴더에서 터미널을 열고 실행합니다.

cd my-project
claude

인터랙티브 세션이 열리고, 최초 1회 브라우저 로그인(/login)을 거칩니다. ANTHROPIC_API_KEY 환경변수가 설정돼 있으면 브라우저 대신 키 승인만 물어봅니다.

무엇을 시켜볼까 — 온보딩 질문

새 코드베이스라면, 시니어 엔지니어에게 하듯 질문부터 던지세요. 특별한 프롬프트가 필요 없습니다.

로깅은 어떻게 동작해?
새 API 엔드포인트는 어떻게 추가해?
CustomerOnboardingFlow는 어떤 엣지케이스를 처리하지?
이 프로젝트 구조를 설명해줘

이렇게 코드베이스를 탐색하는 것만으로 온보딩 시간이 크게 줄고, 다른 엔지니어에게 물어볼 부담도 덜립니다.

첫 실전 작업

README를 읽고, 이 프로젝트가 뭘 하는지 3줄로 요약해줘
로그인 폼에 이메일 형식 검증을 추가하고, 테스트를 작성해 실행해줘

Claude Code를 강력하게 만드는 것들 — 이 강의의 지도

Claude Code의 진짜 힘은 확장 기능을 조합할 때 나옵니다. 이 강의가 다룰 조각들:

챕터 조각 한 줄 요약
2 권한·플랜 모드·되돌리기 세션을 안전하게 다루는 기본기
3 모델과 성능 Fable 5·Opus·Sonnet·Haiku, effort
4 명령어 /로 시작하는 작업 진입점
5 CLAUDE.md 프로젝트 영구 지침
6 자동 기억 Claude가 스스로 축적하는 학습
7 서브에이전트 격리된 컨텍스트의 전문 도우미
8 스킬 온디맨드 지식·절차
9 훅 결정론적 자동화
10 MCP·플러그인 외부 도구 연결·확장
11 오케스트레이션 조각들을 실전 워크플로로

가장 중요한 습관 하나: Claude Code에서 가장 귀한 자원은 컨텍스트 창입니다. 대화가 길어질수록 성능이 떨어지므로, 작업이 바뀔 때마다 /clear로 리셋하는 습관을 처음부터 들이세요. (11장에서 자세히)


핵심 요약

  • Claude Code는 터미널·데스크톱·웹·IDE에서 동작하는 에이전틱 코딩 도구 — 서술하면 탐색·계획·구현한다.
  • 설치는 네이티브(curl … | bash / irm … | iex)가 가장 간단하고 자동 업데이트된다. brew·winget·npm도 가능.
  • Pro/Max/Team/Enterprise/Console 계정 필요(무료 요금제 불가). 첫 실행 시 /login.
  • 새 코드베이스는 질문부터 던져 온보딩하고, 작업 전환마다 /clear로 컨텍스트를 관리하라.
확인 퀴즈

Q1. Claude Code를 사용하려면 어떤 계정이 필요한가요?

해설 · 무료 Claude.ai로는 사용할 수 없습니다. Pro/Max/Team/Enterprise/Console 또는 제3자 API 제공자가 필요합니다.

Q2. 자동 업데이트를 지원하는 권장 설치 방법은?

해설 · 네이티브 설치가 가장 간단하고 백그라운드 자동 업데이트됩니다. brew·winget·npm은 수동 업데이트가 필요합니다.

Q3. 새 코드베이스에 온보딩하는 가장 효과적인 방법은?

해설 · "로깅은 어떻게 동작해?" 같은 질문을 직접 던지는 것이 가장 효과적인 온보딩입니다.
CHAPTER 02

첫 세션 · 권한 · 플랜 모드

첫 세션을 열었다면, 이제 Claude를 안전하게 다루는 기본기를 익힐 차례입니다. 핵심은 세 가지 — 권한(무엇을 허용할지), 플랜 모드(먼저 계획하기), 되돌리기(실수 복구)입니다.

권한 모드 — Claude가 물어보는 빈도 조절

Claude가 파일을 수정하거나 명령을 실행할 때 어디까지 묻지 않고 진행할지를 정하는 것이 권한 모드입니다. 민감한 작업엔 감독을 늘리고, 신뢰하는 방향이면 방해를 줄이세요.

모드 물어보지 않고 실행하는 것 적합한 상황
default (화면 표시는 Manual) 읽기만 모든 행동을 직접 검토, 민감한 작업
acceptEdits 읽기 + 파일 편집 + 흔한 파일시스템 명령(mkdir·mv 등) 리뷰하며 코드 반복 작업
plan 읽기 전용 탐색 + (오토 모드를 쓸 수 있는 계정이면) 분류기가 승인한 명령 계획 먼저 세우기
auto 전부 — 대신 분류기가 뒤에서 검사 방향은 신뢰하되 매 단계 클릭하기 싫을 때
dontAsk 미리 승인해 둔 도구만 (나머지는 묻지 않고 거부) 잠가 둔 CI·스크립트
bypassPermissions 전부 (프롬프트 건너뜀) 격리 환경의 무인 실행 (주의)

2026-08-14부터 새 세션의 기본이 오토 모드입니다. Pro·Max·Team 요금제에서 터미널이나 VS Code 확장으로 세션을 열면 내장 기본값이 auto입니다(macOS·Linux·WSL은 v2.1.228+, 네이티브 Windows는 v2.1.233+). "Claude Code는 기본적으로 매번 물어본다"는 예전 상식은 이제 조건부입니다. 반대로 여전히 Manual(default)로 시작하는 경우도 많습니다 — Enterprise 요금제·Console API 키, claude -p와 Agent SDK, Bedrock·Google Cloud·Microsoft Foundry 경유 세션, 관리 설정에서 disableAutoMode를 켠 조직, 그리고 설치·업그레이드 직후 첫 세션. 스스로 정해 둔 기본 모드가 있으면 그대로 유지되고, 한 번 물어보는 전환 제안을 거절하면 바뀌지 않습니다. default의 화면 이름이 "Manual"로 바뀌었습니다(v2.1.200+). 설정값·훅·SDK가 읽는 값은 여전히 default이고, CLI에서는 manual이라고 써도 받습니다(claude --permission-mode manual).

모드 전환: 프롬프트에서 Shift+Tab을 눌러 모드를 순환하거나, 실행 시 --permission-mode 플래그를 씁니다. 순환 경로는 생각보다 좁습니다 — 오토 모드에서 처음 누르면 default로 빠지고, 그다음은 default → acceptEdits → plan → 다시 default입니다. auto와 bypassPermissions는 조건이 맞을 때만 plan 뒤에 끼어들고(둘 다면 bypassPermissions가 먼저, auto가 마지막), dontAsk는 순환에 아예 나오지 않아 --permission-mode dontAsk로만 켭니다.

claude --permission-mode plan          # 플랜 모드로 시작
claude --permission-mode auto -p "fix all lint errors"   # 오토 모드 무인 실행

오토 모드는 별도 분류기 모델이 명령을 검토해 스코프 이탈·미지의 인프라·적대적 콘텐츠 기반 동작만 차단하고, 나머지 루틴 작업은 통과시킵니다. "방향은 맞다고 믿지만 열 번째 승인쯤 되면 사실 검토가 아니라 그냥 클릭하는" 상태를 없애 줍니다. Pro·Max·Team에서는 분류기 호출이 사용량 한도에 잡히지 않습니다. 다만 모델을 가립니다 — Opus 4.6 이상·Sonnet 4.6 이상·Fable 5에서만 쓸 수 있고(클라우드 경유는 Sonnet 5·Opus 4.7 이상·Fable 5), Haiku나 구형 모델에서는 "사용 불가"가 뜹니다. 이건 일시적 장애가 아니라 요건 미충족이라는 뜻입니다.

어떤 모드도 자동 승인하지 않는 것이 있습니다. ask 규칙에 걸린 도구, 조직이 ask로 지정한 커넥터, 사용자 입력이 필요한 도구(AskUserQuestion 등), 그리고 /나 ~ 같은 크리티컬 경로를 지우는 rm·rmdir — 이들은 bypassPermissions에서도 그냥 통과하지 않습니다. 반대로 deny 규칙은 모든 모드에서 막고, bypassPermissions에서는 allow 규칙이 무의미해집니다.

권한을 세밀하게 통제하려면 /permissions로 특정 도구·명령을 허용/거부 규칙에 추가하거나(npm run lint 같은 안전한 것만 허용), /sandbox로 OS 레벨 격리를 켤 수 있습니다. 시작 모드를 고정하고 싶으면 ~/.claude/settings.json의 permissions.defaultMode에 적으세요 — "auto"만은 프로젝트 설정(.claude/settings.json·settings.local.json)에서 무시됩니다. 프로젝트 설정에 auto를 적어 놓고 "왜 계속 Manual로 시작하지?" 하며 헤매기 쉽습니다.

💡 오토 모드 분류기 진단 및 긴급 복구 모드: - 오토 모드 분류기 동작 상태나 캐시를 점검·초기화하려면 CLI에서 claude auto-mode를 실행하세요. - 잘못된 스킬이나 훅, 권한 설정으로 인해 세션 진입이 막혔을 때는 claude --safe-mode 플래그로 모든 커스터마이징을 비활성화한 순정 환경(CLAUDE_CODE_SAFE_MODE=1)에서 문제를 점검할 수 있습니다.


권한 규칙 — 모드보다 정확한 통제

모드가 "얼마나 물어볼지"라면, 규칙은 "무엇을 어떻게 다룰지"입니다. settings.json의 permissions에 세 갈래로 적습니다.

{
  "permissions": {
    "deny":  ["Bash(git push --force *)", "Read(./.env)"],
    "ask":   ["Bash(git push *)"],
    "allow": ["Bash(npm run *)", "Edit(/src/**)"]
  }
}

규칙 형식은 Tool 또는 Tool(지정자)입니다. 괄호 없는 Bash는 그 도구의 모든 사용에 맞고, Bash(*)도 같습니다. 여기서 반드시 알아야 할 것이 셋 있습니다.

1. 평가 순서는 deny → ask → allow, 먼저 맞는 것이 이깁니다. 구체적인 규칙이 이기는 게 아닙니다. 그래서 넓은 deny에는 예외를 뚫을 수 없습니다 — Bash(aws *)를 막아 두면 Bash(aws s3 ls)를 allow에 넣어도 막힙니다. ask와 allow 사이도 같아서, ask에 맞으면 더 구체적인 allow가 있어도 물어봅니다. 예외를 두고 싶다면 deny를 넓게 쓰지 말고 막을 것만 좁게 적어야 합니다.

2. * 앞의 공백이 의미를 바꿉니다. 끝에 붙은 *(공백+별표)는 단어 경계를 요구합니다 — Bash(ls *)는 ls -la에 맞지만 lsof에는 안 맞습니다. 반면 Bash(ls*)는 둘 다 맞습니다. :* 접미사는 *와 같은 뜻이라 Bash(ls:*) = Bash(ls *)인데, 끝에서만 그렇게 읽힙니다(Bash(git:* push)의 콜론은 그냥 문자).

3. 경로 규칙의 맨 앞 /는 파일시스템 루트가 아닙니다. Read·Edit은 gitignore 문법을 쓰는데, 앞머리가 넷으로 갈립니다 — //절대경로, ~/홈, /설정_파일_기준, 상대경로(또는 ./). 즉 사용자 설정(~/.claude/settings.json)에 적은 Read(/secrets/**)는 프로젝트의 secrets/가 아니라 홈의 ~/.claude/secrets/ 쪽을 막습니다. 모든 프로젝트에 걸리게 하려면 //나 ~/를 쓰세요.

Bash 규칙에는 함정이 더 있습니다.

  • 복합 명령은 조각마다 따로 맞아야 합니다. Bash(safe-cmd *)가 있어도 safe-cmd && other-cmd는 통과하지 못합니다(구분자 && || ; | & 및 줄바꿈을 인식).
  • 일부 래퍼는 벗겨진 뒤 매칭됩니다 — timeout·time·nice·nohup·stdbuf·command·builtin·noglob, 그리고 플래그 없는 xargs. 그래서 Bash(npm test *)가 timeout 30 npm test에도 맞습니다.
  • 반대로 실행기(runner)는 안 벗겨집니다. npx·docker exec·devbox run 등은 목록에 없어서 Bash(devbox run *)를 allow에 넣으면 devbox run rm -rf .까지 허용됩니다. 실행기는 내부 명령까지 못 박아 Bash(devbox run npm test)처럼 적으세요.
  • 읽기 전용 명령 세트(ls·cat·grep·head·wc·읽기용 git 등)는 모든 모드에서 규칙 없이 통과합니다. 이들을 굳이 allow에 적을 필요는 없고, 반대로 물어보게 만들려면 ask·deny에 적어야 합니다.
  • Bash(command:rm *)처럼 본문 필드를 파라미터로 적은 규칙은 무시되고 시작 시 경고가 납니다(복합 명령으로 우회되니까). Bash(rm *)로 적으세요.

deny의 두 얼굴: 이름만 적은 Bash는 그 도구를 컨텍스트에서 아예 제거해 Claude가 존재조차 모르게 하고, Bash(rm *)처럼 범위를 준 규칙은 도구를 남긴 채 맞는 호출만 막습니다. 또 Read deny는 같은 경로의 Edit·Write까지 막습니다(NotebookEdit은 예외이므로 아무 도구도 못 바꾸게 하려면 Edit deny를 따로 적으세요).

규칙은 Claude Code가 강제합니다 — 모델이 아닙니다. CLAUDE.md에 "이건 하지 마"라고 쓰는 것은 시도를 유도할 뿐 경계가 아닙니다. 실제로 막으려면 규칙·모드·훅 중 하나를 쓰세요.

16장 놀이터의 권한 규칙 시뮬레이터에 규칙과 명령을 넣어 보면, 어느 규칙이 먼저 맞았고 왜 그렇게 판정됐는지 단계별로 확인할 수 있습니다.


플랜 모드 — 탐색과 실행을 분리

바로 코딩에 뛰어들면 엉뚱한 문제를 푸는 코드가 나옵니다. 플랜 모드는 Claude를 읽기 전용으로 두어, 변경 없이 코드베이스를 이해하고 계획부터 세우게 합니다.

  1. 탐색 — 플랜 모드 진입. /src/auth를 읽고 세션·로그인 처리를 이해해줘
  2. 계획 — Google OAuth를 추가하려 해. 어떤 파일이 바뀌고 세션 흐름은? 계획을 세워줘. (Ctrl+G로 계획을 에디터에서 직접 편집)
  3. 구현 — 플랜 모드를 나와 계획대로 코딩하고 검증
  4. 커밋 — 설명적인 메시지로 커밋하고 PR을 열어줘

플랜 모드는 만능이 아닙니다. 오타 수정·로그 한 줄처럼 범위가 명확하고 작은 변경은 그냥 시키세요. 계획은 접근법이 불확실하거나, 여러 파일을 건드리거나, 낯선 코드를 만질 때 가장 유용합니다. 한 문장으로 diff를 설명할 수 있으면 계획을 건너뛰세요.


되돌리기 — 대화는 영속적이고 되돌릴 수 있다

Claude Code는 매 프롬프트마다 체크포인트를 만들고, 파일 변경 전 스냅샷을 찍습니다. 실수해도 복구할 수 있으니, 오히려 과감하게 시도하세요.

방법 하는 일
Esc Claude를 실행 중간에 중단(컨텍스트 보존 → 방향 전환)
Esc Esc 또는 /rewind 되감기 메뉴 — 대화/코드/둘 다를 이전 체크포인트로 복원
"방금 거 되돌려" Claude에게 변경 취소 요청
/clear 무관한 작업 사이 컨텍스트 완전 리셋

/rewind 메뉴에서는 대화만 / 코드만 / 둘 다 복원을 선택할 수 있습니다. 체크포인트는 대화와 함께 저장되므로, 터미널을 닫고 나중에 세션을 재개해도 되감을 수 있습니다.

주의: 체크포인트는 Claude의 편집 도구로 이뤄진 변경만 추적합니다. Bash 명령이나 외부 프로세스로 바꾼 파일은 잡히지 않습니다 — git을 대체하지 않습니다.

일찍, 자주 교정하세요. 잘못된 방향이 보이면 즉시 Esc로 멈추고 바로잡는 편이, 끝까지 두고 고치는 것보다 빠르고 낫습니다. 같은 이슈로 두 번 넘게 교정했다면 컨텍스트가 실패한 시도로 오염된 상태 — /clear 후 배운 것을 반영한 더 나은 프롬프트로 시작하세요.


컨텍스트 관리 — 처음부터 몸에 붙일 습관

Claude Code에서 성능을 좌우하는 단 하나의 자원은 컨텍스트 창입니다.

  • /context — 현재 컨텍스트 사용량을 시각화하고 최적화 제안
  • /clear — 작업 전환 시 리셋 (가장 자주 쓸 명령)
  • /compact [지시] — 대화를 요약해 공간 확보. /compact API 변경에 집중처럼 방향 지정
  • /btw — 히스토리에 남기지 않는 곁가지 질문

핵심 요약

  • 권한 모드: Pro·Max·Team의 새 세션은 2026-08-14부터 오토 모드로 시작한다. Shift+Tab 순환은 default(화면엔 Manual)→acceptEdits→plan이고, auto·bypassPermissions는 조건이 맞을 때만 뒤에 붙으며 dontAsk는 순환에 없다.
  • 권한 규칙은 deny→ask→allow 순으로 먼저 맞는 것이 이긴다(구체성 무관) — 넓은 deny에 예외를 뚫을 수 없고, Bash(ls *)와 Bash(ls*)는 다르며, 경로 규칙의 앞 /는 설정 파일 기준이다.
  • 플랜 모드로 탐색·계획을 실행과 분리해 엉뚱한 문제 풀기를 막는다(작은 변경은 건너뛰기).
  • Esc·/rewind·체크포인트로 과감히 시도하고 되돌린다. 단, git을 대체하진 않는다.
  • 작업 전환마다 /clear, 방향은 일찍 교정 — 컨텍스트 관리가 곧 성능이다.
확인 퀴즈

Q1. 권한 모드를 순환 전환하는 단축키는?

해설 · Shift+Tab으로 default(화면엔 Manual)→acceptEdits→plan을 순환합니다. auto·bypassPermissions는 조건이 맞을 때만 뒤에 끼어들고, dontAsk는 순환에 나오지 않습니다.

Q2. 변경 없이 코드베이스를 이해하고 계획만 세우는 모드는?

해설 · plan 모드는 읽기 전용 탐색으로, 엉뚱한 문제를 푸는 것을 막아 줍니다.

Q3. 실행 중인 Claude를 멈추되 컨텍스트를 보존해 방향을 바꾸는 키는?

해설 · Esc로 중단하면 컨텍스트가 보존되어 바로 방향을 재지정할 수 있습니다. Esc 두 번은 되감기 메뉴.
CHAPTER 03

모델과 성능

Claude Code는 여러 Claude 모델 위에서 돌아갑니다. 어떤 모델을, 어느 강도로 쓰느냐가 결과 품질·속도·비용을 좌우합니다. 이 챕터는 최신 모델 라인업(Opus 5.5·Fable 5.1·Sonnet 5.5)과, Claude Code에서 이를 통제하는 /model·/effort·/fast, 그리고 안전 가드레일을 다룹니다.

현재 모델 라인업 (2026)

Claude 5 세대가 핵심입니다. 티어별로 지능·속도·가격이 다릅니다.

모델 ID 컨텍스트 입력/출력 ($/1M) 캐시 읽기 ($/1M) 성격
Claude Opus 5.5 claude-opus-5-5 1M $4 / $20 $0.20 최신 플래그십 코딩·에이전틱 — Opus 5 대비 40% 저렴, 장기 자율 실행, Fable급 보안 가드레일
Claude Fable 5.1 claude-fable-5-1 1M $10 / $50 $0.25 최고 지능 프런티어 — 가장 복잡한 장기 실행 에이전트·심층 연구 (캐시 읽기 75% 인하)
Claude Sonnet 5.5 claude-sonnet-5-5 1M $2 / $10 $0.20 최신 실무·코딩 표준 — Sonnet 5 대비 30%+ 속도 가속, Terminal-Bench 4.0 70.6%, 작업당 비용 최대 30% 절감
Claude Sonnet 5 claude-sonnet-5 1M $2 / $10 $0.20 이전 세대 실무형 (Sonnet 5.5로 전환 권장)
Claude Opus 5 claude-opus-5 1M $5 / $25 $0.50 이전 세대 플래그십 (Opus 5.5로 전환 권장)
Claude Haiku 4.5 claude-haiku-4-5 200K $1 / $5 $0.10 가장 빠름 — 프런티어 근접 지능, 단순 분류·탐색 서브에이전트

Claude Sonnet 5.5(2026년 9월 28일 출시)는 Claude 5.5 패밀리의 두 번째 모델로, 이전 Sonnet 5 대비 출력 생성 속도가 30% 이상 가속되었으며 향상된 지능과 간결성 덕분에 작업 완료당 실질 토큰 소비 및 비용이 최대 30% 절감됩니다. 특히 에이전틱 코딩 벤치마크인 Terminal-Bench 4.0에서 70.6%를 기록(Sonnet 5의 10.3% 대비 비약적 향상)하며 Artificial Analysis 순위표 1위에 올랐고, 경제적 지식 작업 평가(GDPval-AA v2.1)에서도 Elo 1,844점을 기록해 플래그십인 Opus 5.5(1,846점)와 거의 동등한 수준의 일상 업무 수행력을 입증했습니다. 또한 텍스트 힌트 없이 순수 스크린샷 입력만으로 복잡한 시각 게임(Pokémon Red)을 완결하는 등 멀티모달 능력이 대폭 향상되었습니다. claude.ai의 무료 티어 기본 모델로도 탑재되었습니다.

Claude Opus 5.5(2026년 9월 22일 출시)는 기본 입력/출력 단가가 20% 인하($4/$20)되고 캐시 읽기가 60% 인하($0.20)되어, 실무 토큰 과금 기준 전체 작업 비용이 Opus 5 대비 약 40% 절감됩니다. 또한 별도의 "생각해라" 지시 없이도 적응형 사고를 수행하며, 긴 세션 자율 실행력과 소통 명확성이 대폭 향상되었습니다.

Claude Fable 5.1(2026년 9월 출시)은 최고 지능 티어로, 캐시 읽기 비용을 75% 인하($0.25/M 토큰)하여 수백 회 도구를 호출하는 에이전틱 세션의 부담을 크게 줄였습니다. 동일한 아키텍처이지만 보안 제한을 완화해 신뢰받는 보안·생명과학 연구진에게만 제한 제공되는 자매 모델로 Claude Mythos 5.1(Project Glasswing)이 있습니다.

최대 출력은 Opus 5.5·Fable 5.1·Sonnet 5.5·Opus 5·Sonnet 5가 128K, Haiku 4.5가 64K 토큰입니다. 지식 컷오프는 Opus 5.5가 2026년 8월, Sonnet 5.5 및 Fable 5.1이 2026년 6월, Opus 5가 2026년 5월, Sonnet 5가 2026년 1월, Haiku 4.5가 2025년 2월입니다 — 그 이후에 나온 라이브러리·API는 모른다고 보고 웹 검색·문서 MCP로 보완하세요.

모델 선택의 실무 가이드: - 일상적인 기능 개발·고속 피드백·에이전틱 반복 코딩 → Sonnet 5.5 (가장 빠른 반응 속도, 이전 세대 대비 압도적 코딩 성능, 작업당 30% 비용 절감) - 복잡한 코딩·대규모 리팩터·장기 에이전틱 작업 → Opus 5.5 (Anthropic 권장 플래그십. 높은 디테일 감지, 스텁 없는 완결성, 더 낮은 비용) - 최고 난도 추론·수학/하드웨어 증명·극단적 엣지케이스 → Fable 5.1 (프런티어 지능, 초저가 캐시 읽기) - 경량 서브에이전트·단순 분류·초고속 질의응답 → Haiku 4.5


모델 전환 — /model

세션 중 /model로 모델을 바꾸고 기본값으로 설정합니다.

/model            # 대화형 선택 메뉴
/model opus-5-5   # 별칭 또는 모델명으로 바로 지정 (opus-5-5/fable/sonnet/haiku)

서브에이전트는 모델을 따로 지정할 수 있습니다(7장의 model 프론트매터). 넓은 코드베이스 탐색은 haiku로 저렴하게, 핵심 기능 구현 및 아키텍처 판단은 opus-5-5나 fable로 지정하여 자원을 최적화하세요.


추론 강도 — /effort

Claude 5 세대(Opus 5.5·Fable 5.1·Sonnet 5.5·Opus 5·Sonnet 5)는 effort로 "얼마나 많은 연산과 검증을 쏟을지"를 조절합니다. 단순 사고량뿐만 아니라 자율적 도구 호출 횟수, 엣지케이스 점검 루프의 집요함을 좌우합니다.

레벨 언제 쓰는가 실무 특징
max 정확성이 비용보다 압도적으로 중요한 극난도 과제 자체 퍼저 작성, 소스코드 역추적 등 최대 검증 (긴 런타임 고려)
xhigh 숨겨진 엣지케이스가 많은 보안·하드웨어·복잡 알고리즘 반사실적 검토, 철저한 테스트 자동 생성
high 기본값 (Default) — Claude Code & API 대부분의 실무 코딩에 최적인 지능·속도·비용 균형점
medium 비용과 지연 시간을 줄이면서 준수한 품질 유지 루틴한 CRUD 기능 개발, 정형화된 코드 마이그레이션
low 짧고 범위가 명확한 작업, 빠른 프로토타입 구현 지연 시간 최소화, 사람과의 빠른 인터랙티브 반복
/effort high

벤치마크 검증: Terminal-Bench 3.0과 Effort 곡선

Anthropic 엔지니어링 팀(Thariq Shihipar)의 실측 결과, Opus 5.5와 Fable 5.1은 effort 설정에 따라 선형에 가까운 뚜렷한 성능 향상 곡선을 보입니다.

Effort 설정 Opus 5.5 성공률 Fable 5.1 성공률 핵심 행동 특성 및 리소스 사용
low 36.6% 37.8% 단일 패스 구현, 최소 도구 호출, 초고속 프로토타이핑 (지연 시간 최소)
medium 50.1% 44.5% 기본 검증 실행, 준수한 루틴 코딩 품질 (비용 절감 효과)
high 58.9% 51.2% 기본값 — Opus 5.5가 Fable 5.1 max급 성능을 절반의 토큰으로 달성
xhigh 62.4% 55.6% 적대적 자가 검토, 다중 엣지케이스 테스트 스위트 생성
max 65.7% 58.0% 파서 소스코드 분석, 무작위 퍼저(fuzzer) 작성, 극난도 과제 완결
  • Opus 5.5의 효율성: Opus 5.5의 high 레벨(58.9%)은 Fable 5.1의 max 레벨(58.0%)과 동급의 성공률을 단 절반의 토큰 소비로 달성합니다.
  • 높은 Effort가 반드시 필요한 순간: 커뮤니티 벤치마크인 Terminal-Bench 3.0의 html-js-filter(XSS 방어용 정밀 HTML 새니타이저 구현) 과제에서, Fable 5.1은 low effort에서 5회 중 1회만 통과(2분 소요)했으나, xhigh effort에서는 5회 모두 완벽 통과(33분 소요)했습니다. 고난도 effort에서는 모델이 자체 초안을 적대적으로 검토하고, 파서 소스 코드를 읽어 취약점을 찾으며, 무작위 문서 퍼저(fuzzer)를 직접 작성해 검증합니다.
  • 추천 개발 루프 (Feature Engineering Loop):
  • 요구사항 인터뷰: Claude에게 명세를 주고 질문을 유도 (AskUserQuestion 등)
  • low effort 구현: 저비용·초고속으로 핵심 뼈대 작성
  • low effort 검토 및 반복: 사람이 방향성을 확인하며 빠르게 피드백
  • high 또는 xhigh effort 검증: 회귀 테스트, 엣지케이스 검증, 보안 리뷰

effort 동작 특성 요약: - effort 지원 모델: Opus 5.5·Fable 5.1·Sonnet 5.5·Opus 5·Sonnet 5. (Haiku 4.5는 적응형 사고 미지원, 구세대 budget_tokens 방식만 지원) - 적응형 사고 상시 활성화: Opus 5.5, Sonnet 5.5, Fable 5.1은 매 응답 전 스스로 생각하며, 사고 기능을 무단으로 끌 수 없습니다. 프롬프트에 불필요하게 "think hard", "think step by step"을 넣지 마세요. - 답변 길이 레버가 아님: effort를 낮춘다고 답변 텍스트가 짧아지지 않습니다. 출력 길이는 14장의 프롬프트 지침으로 제어해야 합니다.


빠른 모드 — /fast

Fast 모드는 지능 손실 없이 Opus의 출력 속도를 최대 2.5배까지 가속합니다(리서치 프리뷰). 대화형으로 빠르게 질문을 주고받아야 하는 페어 프로그래밍 환경에 유용합니다.

/fast     # 토글 (Fast mode ON / OFF)
  • 지원 모델: Opus 5.5 및 Opus 5. (Sonnet·Haiku에서는 지원되지 않으며 실행 시 자동으로 꺼짐)
  • 비용 주의사항:
  • fast 모드는 출력 속도를 높이는 대신 토큰당 단가가 2배로 책정됩니다.
  • 구독 플랜(Pro·Max·Team)에 기본 포함되지 않으며, 플랜 한도가 남아 있더라도 추가 사용량 크레딧에서 차감됩니다.
  • 세션 중간에 켜면 해당 시점의 컨텍스트를 fast 미캐시 입력가로 1회 재청구하므로, 쓸 거라면 세션 시작 직후 켜는 것이 비용상 유리합니다.

보안 가드레일과 플래그 대응 (Safeguards & Flags)

Opus 5.5와 Sonnet 5.5는 첨단 생물학·사이버보안 가드레일이 적용되었습니다. 엔터프라이즈 환경에서 안전한 코드 작성을 보장하기 위한 메커니즘입니다.

메시지 플래그(Flag) 시 동작 원리

코드 내 보안 취약점을 탐지하고 수정하는 정당한 개발 작업은 전면 허용되지만, 악성 코드 패턴이나 위험 페이로드 분석 시 가드레일이 트리거될 수 있습니다. 1. 자동 모델 스위칭 (Fallback): Claude apps와 Claude Code에서는 메시지가 플래그되면 작업이 즉시 중단되는 대신 이전 세대 안전 모델로 세션이 자동 전환되어 흐름을 이어갑니다. 2. 복구 및 제어: - 원래 모델로 복귀하려면 /model opus-5-5 또는 /model sonnet을 입력합니다. - 직전 프롬프트가 원인이라면 Esc를 두 번 눌러 직전 입력을 수정하고 재시도합니다. - 자동 스위칭 대신 확인 창을 띄우고 싶다면 /config에서 Switch models when a message is flagged 설정을 변경합니다. - 정상적인 개발 작업이 오탐(False Positive)되었다면 /feedback 명령으로 리포트합니다.

⚠️ 보안 주의사항 — 내부 사고 과정(Internal Reasoning) 출력 요구 금지: 프롬프트에 "생각한 내부 과정을 그대로 보여달라"거나 숨겨진 추론 태그를 추출하려는 시도는 보안 정책상 단호히 거부(Decline)되며 플래그 사유가 됩니다. 추론 과정이 궁금하다면 "왜 이 방식을 선택했는지 3문장으로 설명해 달라"와 같이 명시적 설명 형식으로 요청하세요.


/advisor — 결정 지점에서만 상위 모델 자문 구하기

세션 내내 최고가 모델을 쓰는 것은 비용 낭비일 수 있습니다. /advisor는 평소에는 Sonnet 5.5 등 가벼운 모델로 작업하다가, 설계 결정이나 복잡한 디버깅 순간에만 상위 모델(Opus 5.5 또는 Fable 5.1)의 자문을 구하는 기능입니다.

/advisor              # 세션 중 어드바이저 대화형 지정
claude --advisor opus-5-5 # 세션 시작 시 지정
  • 호출 시점: Claude가 전체 대화 맥락과 도구 결과를 바탕으로 자문이 필요한 순간을 자율적으로 판단합니다.
  • 제약: 어드바이저는 메인 모델보다 지능이 낮을 수 없습니다. Sonnet 5.5 메인은 Opus 5.5/Fable 5.1을 어드바이저로 쓸 수 있지만, Opus 5.5 메인에 Sonnet을 붙일 수는 없습니다.

Sonnet 5.5 핵심 API 제약 및 마이그레이션 주의사항

Sonnet 5에서 작성된 기존 파이프라인이나 스크립트를 Sonnet 5.5(claude-sonnet-5-5)로 전환할 때 주의해야 할 브레이킹 체인지가 있습니다: 1. 사고(Thinking) 끄기 방식 변경: 이전처럼 thinking: {"type": "disabled"}를 지정하면 정상 작동하지 않거나 거부됩니다. high 이하 effort에서 도구 호출 간에 사고를 끄려면 thinking: {"type": "between_tools"}를 사용해야 합니다. 2. 강제 도구 선택(Forced tool_choice) 금지: tool_choice에 any나 특정 tool 이름을 강제 지정하면 HTTP 400 Bad Request 에러를 반환합니다. 3. 구형 컴퓨터 사용 도구 배제: 기존 computer_20251124 버전의 도구는 Claude API 및 Google Cloud에서 Sonnet 5.5 요청 시 거부됩니다. 4. 어드바이저 도구 모델 계층 검증: Sonnet 5.5를 대상으로 구형 모델(Sonnet 5, Opus 4.8, Opus 4.7)을 /advisor로 지정하는 역방향 구성은 시스템상 거부됩니다. 5. Thinking 블록의 암호학적 계정 격리: Sonnet 5.5가 생성한 thinking 블록은 생성한 계정에 암호학적으로 귀속됩니다. 멀티 테넌트 환경에서 다른 계정이 해당 블록을 전송하면 API가 이를 자동으로 드롭합니다.


컨텍스트·비용 종합 의사결정

  • 토크나이저 차이 인지: Opus 5.5·Fable 5.1·Sonnet 5.5·Sonnet 5는 구세대 모델 대비 동일 텍스트에서 토큰 수가 약 30% 증가합니다.
  • 프롬프트 캐싱 극대화: 긴 파일과 시스템 프롬프트를 재사용하는 에이전틱 작업에서는 캐시 읽기 단가가 핵심입니다. Sonnet 5.5($0.20)·Opus 5.5($0.20)·Fable 5.1($0.25) 모두 캐시 읽기 비용이 대폭 인하되어 장기 세션 총비용이 매우 저렴합니다.

핵심 요약

  • 2026 라인업의 중심: Sonnet 5.5(최신 실무·코딩 표준, 30%+ 속도 가속, 작업당 비용 30% 절감, Terminal-Bench 4.0 70.6%), Opus 5.5(권장 기본 플래그십, $4/$20, 이전 대비 40% 비용 절감) 및 Fable 5.1(최고 지능 프런티어, 캐시 읽기 $0.25).
  • 추론 강도 제어 (/effort):
  • 기본은 high.
  • Opus 5.5 high(58.9%)는 Fable 5.1 max(58.0%)와 동급 성능을 절반 토큰으로 제공, Sonnet 5.5 역시 기본 high effort로 고속 개발 지원.
  • XSS 새니타이저 등 엣지케이스가 숨겨진 고위험 작업에는 xhigh/max로 적대적 자가 검증 유도.
  • 실무 4단계 루프: 인터뷰 → low effort 프로토타입 → low 반복 → high/xhigh 검증 및 보안 감사.
  • 빠른 모드 (/fast): Opus 5.5·Opus 5에서 최대 2.5배 가속. (비용 2배, 추가 크레딧 차감 유의)
  • 보안 가드레일: 메시지 플래그 시 이전 안전 모델로 자동 폴백. 내부 사고 출력 요구는 정책 위반이므로 명시적 설명 지시문으로 대체할 것.
확인 퀴즈

Q1. 복잡한 에이전틱 코딩에 Anthropic이 권장하는 최신 기본 모델은?(2026)

해설 · 복잡한 에이전틱 코딩·엔터프라이즈엔 Opus 5.5(Opus 5 대비 40% 저렴, 장기 자율 실행 최적화), 최고 능력엔 Fable 5.1을 권합니다.

Q2. Claude 5 세대(Opus 5.5·Sonnet 5)의 기본 effort 레벨은?

해설 · 기본은 high입니다(Claude API·Claude Code). 어려운 코딩·에이전틱엔 xhigh로 올리고, 비용·속도엔 low/medium을 적극 씁니다.

Q3. 가장 강력한(최고 지능) 널리 출시된 프런티어 모델은?

해설 · 최고 지능 프런티어 티어는 Fable 5.1입니다. 복잡 코딩·에이전틱의 권장 기본은 Opus 5.5.
CHAPTER 04

명령어 · 슬래시 커맨드

Claude Code는 자연어로 대화하는 도구지만, 자주 하는 작업일수록 매번 문장으로 설명하는 건 비효율적입니다. 슬래시 커맨드(slash command)는 /로 시작하는 짧은 명령으로, 정해진 동작을 일관되게, 예측 가능하게 실행하는 진입점입니다.

카페에서 "아메리카노 주세요"라고 하면 늘 같은 레시피로 나오는 것처럼, /deploy를 입력하면 늘 같은 절차가 실행됩니다. "커피 한 잔 주세요"처럼 모호하게 말했을 때와 결과가 달라지는 것을 막아 주는 것이 명령어의 핵심 가치입니다.

2026년 중요 변경점: 예전의 커스텀 명령어(.claude/commands/)는 스킬(Skill)으로 통합되었습니다. .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md는 둘 다 /deploy를 만들고 동일하게 동작합니다. 기존 .claude/commands/ 파일은 그대로 작동하지만, 새로 만들 때는 스킬을 권장합니다. 이 챕터는 내장 명령어와 명령의 기본 문법을 다루고, 커스텀 명령 제작은 스킬 챕터에서 자세히 다룹니다.


명령의 세 가지 종류

/를 입력했을 때 뜨는 목록에는 성격이 다른 세 부류가 섞여 있습니다.

종류 예시 설명
내장 명령어(Built-in) /clear, /compact, /model Claude Code에 고정 로직으로 내장. 항상 사용 가능
번들 스킬(Bundled skill) /code-review, /security-review, /loop 프롬프트 기반으로 Claude가 도구를 써서 처리
커스텀 스킬/명령 /deploy, /fix-issue 사용자가 직접 정의 (스킬 챕터)

내장 명령어는 대부분 즉시 실행되는 고정 동작이고, 번들 스킬은 Claude에게 상세 지시를 주고 스스로 작업을 조율하게 합니다.


자주 쓰는 내장 명령어

전체 목록은 세션에서 /help로 볼 수 있습니다. 실무에서 가장 자주 손이 가는 것들만 추려 봅니다.

세션·컨텍스트 관리 (가장 중요)

명령어 하는 일
/clear 컨텍스트를 완전히 리셋. 작업이 바뀔 때마다 습관적으로 사용
/compact [지시] 대화를 요약해 컨텍스트 공간 확보. /compact API 변경에 집중처럼 힌트 가능
/context 컨텍스트 사용량을 시각화하고 최적화 제안
/rewind 코드·대화를 이전 체크포인트로 되돌리기 (Esc 두 번과 동일)
/resume, /continue 이전 대화 이어가기

컨텍스트 창은 Claude Code에서 가장 중요한 자원입니다. 창이 찰수록 성능이 떨어지고 앞선 지시를 "잊기" 시작합니다. /clear와 /compact를 아끼지 말고 쓰세요.

모델·성능

명령어 하는 일
/model 모델 전환 및 기본값 설정
/effort 추론 강도 설정 (low/medium/high/xhigh/max)
/fast 빠른 모드 토글 (Opus의 출력 속도를 높임, 모델을 낮추지 않음)

설정·프로젝트

명령어 하는 일
/init 코드베이스를 분석해 시작용 CLAUDE.md 생성
/memory CLAUDE.md 편집, 자동 기억 관리
/permissions 도구·명령 승인 규칙 설정
/config 설정 열기 또는 키-값 설정
/hooks 구성된 훅을 이벤트별로 열람(읽기 전용)
/mcp MCP 서버 연결·OAuth 관리
/agents 서브에이전트 관리
/output-style 출력 스타일(기본, 설명형, 학습형 등) 목록 열람 및 전환
/reload-skills 세션 재시작 없이 새로 추가·수정된 스킬을 즉시 다시 로드
/remote-control 웹(claude.ai)이나 모바일 앱에서 로컬 세션을 원격 제어하도록 연결

진단·품질·인터페이스

명령어 하는 일
/doctor 셋업 점검, 문제 진단·수정 제안
/status 현재 세션 상태 확인
/usage API 사용량·비용 표시 (/usage-credits로 잔여 크레딧 확인)
/focus 프롬프트와 1줄 작업 요약, 최종 응답만 남기는 초경량 포커스 뷰 토글
/code-review 변경 diff를 새 서브에이전트가 검토(번들 스킬, --fix로 수정 적용)
/security-review diff의 보안 취약점 점검(번들 스킬)
/code-review ultra 같은 리뷰를 클라우드에서 다중 에이전트로 깊게(지적마다 재현·검증). 사용량 크레딧 과금 — 17장
/advisor 결정 지점에 물어볼 더 강한 모델 지정(3장)
/btw 히스토리에 남기지 않고 빠른 곁가지 질문

터미널 밖의 CLI 전용 명령어

세션 내부의 슬래시 커맨드 외에도, 터미널 셸에서 claude 바이너리로 직접 실행하는 유용한 하위 명령들이 있습니다.

CLI 명령어 하는 일
claude agents 백그라운드(--bg)로 실행 중인 세션 목록 열람
claude attach <id> 백그라운드 세션에 터미널을 직접 연결하여 대화 재개
claude logs <id> 백그라운드 세션의 최근 콘솔 출력 확인
claude stop <id> 백그라운드 세션 중지 (대화 기록은 유지되어 나중에 재개 가능)
claude --safe-mode 모든 커스터마이징(스킬·훅·MCP 등)을 비활성화하고 순정 모드로 실행 (CLAUDE_CODE_SAFE_MODE=1)
claude auto-mode 오토 모드(Auto-mode) 분류기 설정 상태 점검 및 리셋
claude import [출처] Cursor, Codex 등 타 AI 코딩 도구의 설정·프롬프트를 Claude Code로 일괄 가져오기
claude doctor 세션 진입 전 설치 환경, Node/권한 헬스체크를 신속하게 수행

명령 문법: 인자·셸·파일 참조

커스텀 명령(스킬 포함)에서 쓰이는 핵심 문법 3가지는 그대로 알아 두면 유용합니다.

1) 인자 전달

$ARGUMENTS는 명령 뒤에 붙인 전체 텍스트로, $0·$1은 위치별 인자로 치환됩니다.

Fix GitHub issue $ARGUMENTS following our coding standards.

/fix-issue 123으로 실행하면 $ARGUMENTS가 123으로 바뀝니다. 위치 인자는 셸식 따옴표 규칙을 따릅니다 — /migrate "hello world" Vue에서 $0은 hello world, $1은 Vue.

2) 셸 명령 주입 (동적 컨텍스트)

!`명령` 는 Claude가 내용을 보기 전에 셸에서 먼저 실행되어, 그 출력이 자리표시자를 대체합니다. 실시간 데이터를 프롬프트에 그대로 넣을 수 있습니다.

## 현재 변경사항
!`git diff HEAD`

## 지시
위 변경을 3줄로 요약하고 위험 요소를 나열하라.

!는 줄 맨 앞이나 공백 뒤에 올 때만 인식됩니다. 여러 줄은 ```! 펜스 블록을 씁니다.

3) 파일 참조

@경로로 파일을 참조하면 Claude가 응답 전에 그 파일을 읽습니다. 프롬프트에서 "어디에 코드가 있는지" 설명하는 대신 @src/auth/session.ts처럼 직접 가리키세요.


실전 팁

  • 모호함을 줄이는 도구로 명령을 쓰세요. 반복 작업일수록 명령으로 고정하면 결과 편차가 사라집니다.
  • /clear는 성능 관리 도구입니다. 같은 이슈로 두 번 이상 교정했다면 컨텍스트가 실패한 시도로 오염된 상태 — /clear 후 더 구체적인 프롬프트로 다시 시작하는 편이 거의 항상 낫습니다.
  • 번들 스킬 끄기: disableBundledSkills 설정으로 /doctor를 제외한 번들 스킬을 모두 끌 수 있습니다.
  • 명령이 안 보일 때: 세션 시작 후 새로 만든 디렉터리는 감지되지 않을 수 있습니다. Claude Code를 재시작하세요.

핵심 요약

  • 슬래시 커맨드는 일관성을 주는 진입점이다.
  • 커스텀 명령어는 이제 스킬로 통합됐다 — 기존 .claude/commands/도 계속 작동한다.
  • $ARGUMENTS(인자), !`cmd`(셸 주입), @file(파일 참조)이 세 가지 문법의 핵심이다.
  • /clear·/compact·/context로 컨텍스트를 능동적으로 관리하는 습관이 성능을 좌우한다.
확인 퀴즈

Q1. 커스텀 명령어(.claude/commands/)는 2026년 현재 무엇으로 통합되었나요?

해설 · 커스텀 명령어는 스킬로 통합됐습니다. 기존 .claude/commands/ 파일도 계속 작동합니다.

Q2. 스킬·명령에서 ` !git diff ` 문법은 무엇을 하나요?

해설 · 동적 컨텍스트 주입 — 명령이 먼저 실행되어 실제 출력이 프롬프트에 인라인됩니다.

Q3. 무관한 작업으로 넘어갈 때 컨텍스트를 리셋하는 명령은?

해설 · /clear는 컨텍스트를 완전히 리셋합니다. 작업 전환 시 습관적으로 쓰세요.
CHAPTER 05

CLAUDE.md · 프로젝트 지침

모든 Claude Code 세션은 깨끗한 컨텍스트 창에서 시작합니다. 매번 "우리 프로젝트는 pnpm을 쓰고, 커밋 전 make lint를 돌리고, API 핸들러는 src/api/handlers/에 있다"를 다시 설명하는 건 낭비죠. CLAUDE.md는 당신이 직접 쓰는 영구 지침 파일로, 세션이 시작될 때마다 자동으로 컨텍스트에 로드됩니다.

CLAUDE.md에 담을 것은 한 문장으로 정리됩니다: "매번 다시 설명하게 되는 것". 다음 상황이면 추가하세요.

  • Claude가 같은 실수를 두 번째로 반복할 때
  • 코드 리뷰에서 "이 코드베이스라면 알았어야 할" 지적이 나올 때
  • 지난 세션에 입력했던 교정을 이번에도 똑같이 입력하고 있을 때
  • 새 팀원이 생산성을 내려면 알아야 할 맥락일 때

어디에 두는가 — 로드 순서와 스코프

CLAUDE.md는 여러 위치에 둘 수 있고, 넓은 스코프 → 좁은 스코프 순으로 로드되어 컨텍스트에 이어붙습니다(뒤에 오는 것이 더 나중에 읽힘).

스코프 위치 용도
관리 정책(Managed) macOS /Library/Application Support/ClaudeCode/CLAUDE.md, Linux/WSL /etc/claude-code/CLAUDE.md, Windows C:\Program Files\ClaudeCode\CLAUDE.md 조직 전체 표준·보안·컴플라이언스. 개별 설정으로 제외 불가
사용자(User) ~/.claude/CLAUDE.md 모든 프로젝트에 적용되는 개인 선호
프로젝트(Project) ./CLAUDE.md 또는 ./.claude/CLAUDE.md 팀 공유 지침(버전 관리에 커밋)
로컬(Local) ./CLAUDE.local.md 개인 프로젝트 메모(.gitignore에 추가)

작업 디렉터리에서 상위로 거슬러 올라가며 각 디렉터리의 CLAUDE.md를 모두 찾아 이어붙입니다. 하위 디렉터리의 파일은 Claude가 그 폴더의 파일을 읽을 때 필요 시점에 로드됩니다. 로드 여부를 확인하려면 세션에서 /context를 실행해 Memory files 목록을 보세요.

/init으로 시작하기: /init을 실행하면 코드베이스를 분석해 빌드 명령·테스트 방법·프로젝트 규칙이 담긴 시작용 CLAUDE.md를 만들어 줍니다. 이미 있으면 덮어쓰지 않고 개선안을 제안합니다.


효과적인 CLAUDE.md 작성법

CLAUDE.md는 시스템 프롬프트가 아니라, 시스템 프롬프트 뒤에 오는 사용자 메시지로 전달됩니다. 즉 강제 규칙이 아니라 맥락이며, 어떻게 쓰느냐가 준수율을 좌우합니다.

핵심 원칙 — 각 줄마다 자문하세요: "이 줄을 지우면 Claude가 실수하게 되는가?" 아니라면 지우세요. 비대한 CLAUDE.md는 정작 중요한 규칙을 파묻어 무시하게 만듭니다.

✅ 넣을 것 ❌ 뺄 것
Claude가 추측할 수 없는 Bash 명령 코드를 읽으면 알 수 있는 것
기본값과 다른 코드 스타일 규칙 언어의 표준 관례
테스트 방법·선호 러너 상세 API 문서(링크로 대체)
브랜치·PR 규칙 자주 바뀌는 정보
프로젝트 특유의 아키텍처 결정 파일별 코드베이스 설명
개발환경 특이사항(필수 env 변수) "깨끗한 코드 작성" 같은 자명한 것

작성 지침 세 가지:

  • 크기: 파일당 200줄 이하를 목표로. 길수록 컨텍스트를 더 먹고 준수율이 떨어집니다.
  • 구체성: "코드를 잘 포맷하라"❌ 대신 "2칸 들여쓰기를 쓴다"✅. 검증 가능할 만큼 구체적으로.
  • 강조: 잘 안 지켜지는 규칙은 IMPORTANT 또는 YOU MUST로 강조하면 준수율이 오릅니다.
# 코드 스타일
- ES 모듈(import/export) 사용, CommonJS(require) 금지
- 가능하면 구조분해 임포트 (예: import { foo } from 'bar')

# 워크플로
- 일련의 코드 변경을 끝내면 반드시 타입체크할 것
- 성능을 위해 전체 테스트보다 단일 테스트를 우선 실행

Claude가 규칙이 있는데도 계속 어긴다면 파일이 너무 길어 규칙이 묻힌 것입니다. CLAUDE.md도 코드처럼 다루세요 — 문제가 생기면 리뷰하고, 주기적으로 가지치기하고, 행동이 실제로 바뀌는지로 변경을 검증하세요.


파일 임포트 (@경로)

CLAUDE.md는 @경로/파일 문법으로 다른 파일을 끌어올 수 있습니다. 임포트된 파일은 시작 시 함께 로드됩니다(컨텍스트를 줄여 주지는 않음 — 조직화 용도).

프로젝트 개요는 @README.md, 사용 가능한 npm 명령은 @package.json 참고.

# 추가 지침
- Git 워크플로: @docs/git-instructions.md
- 개인 설정: @~/.claude/my-project-instructions.md
  • 상대·절대 경로 모두 가능하며, 상대 경로는 임포트한 파일 기준으로 해석됩니다.
  • 재귀 임포트 가능(최대 4단계).
  • 코드 스팬/펜스 블록 안의 경로는 임포트되지 않습니다. 백틱으로 감싸면(`@README`) 문자 그대로 남습니다.
  • 홈 디렉터리 등 작업 디렉터리 밖을 임포트하면 최초 1회 승인 대화가 뜹니다(공유 프로젝트가 심은 파일로부터 보호).

.claude/rules/ — 규칙 모듈화와 경로 스코프

프로젝트가 커지면 .claude/rules/ 디렉터리로 지침을 주제별 파일로 쪼갤 수 있습니다.

your-project/
└── .claude/
    ├── CLAUDE.md
    └── rules/
        ├── code-style.md
        ├── testing.md
        └── security.md

paths 프론트매터를 쓰면 특정 파일을 다룰 때만 규칙이 로드되어, 평소 컨텍스트를 아낄 수 있습니다.

---
paths:
  - "src/api/**/*.ts"
---

# API 개발 규칙
- 모든 엔드포인트는 입력 검증을 포함한다
- 표준 에러 응답 형식을 사용한다
패턴 매칭 대상
**/*.ts 모든 디렉터리의 TypeScript 파일
src/**/* src/ 아래 모든 파일
src/**/*.{ts,tsx} 브레이스 확장으로 여러 확장자

paths가 없는 규칙은 .claude/CLAUDE.md와 같은 우선순위로 항상 로드됩니다. 개인 규칙은 ~/.claude/rules/에 둡니다.


출력 스타일 — 어떻게 답할지를 바꾸는 레버

CLAUDE.md가 "무엇을 알아야 하는가"라면, 출력 스타일은 "어떤 역할·말투·형식으로 답하는가"입니다. 매 턴 같은 요구를 반복해 쓰고 있다면(“설명은 도표부터”, “초보자에게 설명하듯”) 그건 프롬프트가 아니라 스타일로 굳힐 자리입니다.

내장 스타일은 기본(Default) 외에 셋입니다.

스타일 하는 일
Proactive 멈춰 묻는 대신 합리적으로 가정하고 바로 실행. 계획보다 행동을 택합니다
Explanatory 작업하면서 구현 선택·코드베이스 패턴에 대한 "인사이트"를 곁들입니다
Learning 인사이트에 더해 TODO(human) 표식을 남겨 일부를 직접 짜게 합니다

Proactive와 오토 모드를 혼동하지 마세요. 오토 모드는 무엇이 승인 없이 실행되는가(권한)를 바꾸고, Proactive는 Claude가 얼마나 스스로 밀고 나가는가(태도)를 바꿉니다. Proactive는 권한 모드를 건드리지 않으므로, 권한 모드는 그대로 둔 채 자율성만 올리고 싶을 때 쓰는 레버입니다.

커스텀 스타일은 마크다운 파일 하나입니다. ~/.claude/output-styles/(개인) 또는 .claude/output-styles/(프로젝트)에 둡니다.

---
name: Diagrams first
description: 설명은 항상 도표부터
keep-coding-instructions: true
---

코드·아키텍처·데이터 흐름을 설명할 때는 구조를 보여 주는 Mermaid 도표를 먼저 그리고, 그다음 산문으로 설명한다.

keep-coding-instructions가 가장 중요한 한 줄입니다. 커스텀 스타일은 기본적으로 Claude Code의 소프트웨어 엔지니어링 지침을 통째로 들어냅니다(변경 범위 잡는 법·주석 쓰는 법·검증하는 법 등). 여전히 코딩을 시키면서 말하는 방식만 바꾸려는 거라면 반드시 true로 두세요. 글쓰기 도우미·데이터 분석처럼 코딩이 아예 아닐 때만 빼는 것이 맞습니다.

전환은 /output-style [이름] 명령(v2.1.269+ 복원)으로 바로 바꾸거나, /config → Output style 또는 설정 파일의 outputStyle 필드에 직접 적습니다. (과거 v2.1.91에서 잠시 제거되었다가 CLI 및 Remote Control 환경에서 재도입되었습니다.) 스타일은 시스템 프롬프트의 일부라 세션 시작 때 한 번 읽히므로, 바꾼 뒤 /clear하거나 새 세션을 열어야 적용됩니다.

그래서 지침을 어디에 적을 것인가 — 이 챕터의 도구들과 나란히 놓으면 이렇습니다.

수단 동작 방식 쓸 때
출력 스타일 시스템 프롬프트를 수정 매 턴 같은 역할·말투·형식을 원할 때
CLAUDE.md 시스템 프롬프트 뒤에 사용자 메시지로 추가 프로젝트 관례·코드베이스 맥락을 항상 알아야 할 때
--append-system-prompt 시스템 프롬프트에 덧붙이기(제거 없음) 한 번의 실행에만 얹고 싶을 때
서브에이전트 자기 시스템 프롬프트·모델·도구로 별도 실행 좁게 격리된 도우미가 필요할 때
스킬 필요할 때 불려 오는 작업별 지침 재사용하는 워크플로가 있을 때

출력 스타일은 메인 대화에만 적용됩니다 — 서브에이전트는 자기 시스템 프롬프트로 돌아 영향을 받지 않습니다(/fork는 부모 프롬프트를 물려받으므로 예외).


흔한 문제와 진단

증상 해결
지침을 안 따름 /context로 로드 여부 확인 → 더 구체적으로 → 규칙 충돌 제거
반드시 실행돼야 하는 규칙 조언에 불과한 CLAUDE.md 대신 훅으로 강제
파일이 너무 큼 paths 스코프 규칙으로 분리, /doctor가 가지치기 제안
/compact 후 지침 사라짐 프로젝트 루트 CLAUDE.md는 압축 후 다시 주입됨. 대화로만 준 지침은 CLAUDE.md에 넣어 영속화

AGENTS.md를 쓰는 저장소라면? Claude Code는 AGENTS.md가 아니라 CLAUDE.md를 읽습니다. CLAUDE.md에서 @AGENTS.md로 임포트하면 두 도구가 같은 지침을 공유합니다.


핵심 요약

  • CLAUDE.md는 당신이 쓰는 영구 지침 — 매번 다시 설명할 것을 적어 둔다.
  • 위치별 스코프(관리→사용자→프로젝트→로컬)가 넓은 것부터 이어붙는다.
  • 짧고 구체적으로. "지우면 실수하는가?"로 매 줄을 검증한다. 200줄이 목표.
  • @임포트로 조직화, .claude/rules/의 paths로 필요할 때만 로드.
  • 강제가 필요한 규칙은 CLAUDE.md가 아니라 훅으로. Claude가 스스로 축적하는 지식은 자동 기억이 담당한다.
  • 무엇을 아는가는 CLAUDE.md, 어떻게 답하는가는 출력 스타일. 커스텀 스타일에서 계속 코딩을 시킬 거면 keep-coding-instructions: true를 빠뜨리지 말 것.
확인 퀴즈

Q1. CLAUDE.md 파일의 권장 최대 길이는?

해설 · 200줄 이하가 목표입니다. 길수록 컨텍스트를 더 먹고 준수율이 떨어집니다.

Q2. 팀과 버전 관리로 공유할 프로젝트 지침은 어디에 두나요?

해설 · 프로젝트 루트의 CLAUDE.md는 커밋되어 팀과 공유됩니다. local은 개인용, ~/.claude는 사용자 전역입니다.

Q3. 반드시 특정 시점에 강제로 실행돼야 하는 규칙은 어디에 두는 게 맞나요?

해설 · CLAUDE.md는 조언(컨텍스트)일 뿐입니다. 강제가 필요하면 결정론적인 훅을 쓰세요.
CHAPTER 06

자동 기억 (Agent Memory)

CLAUDE.md가 당신이 직접 쓰는 지침이라면, 자동 기억(Auto memory)은 Claude가 스스로 쓰는 노트입니다. 당신이 아무것도 적지 않아도 Claude가 작업하며 알게 된 것 — 빌드 명령, 디버깅 통찰, 아키텍처 노트, 코드 스타일 선호, 워크플로 습관 — 을 저장해 세션을 넘어 축적합니다.

Claude Code에는 세션 간 지식을 잇는 두 가지 보완적 메커니즘이 있습니다.

CLAUDE.md 자동 기억
누가 씀 당신 Claude
담는 것 지침·규칙 학습·패턴
스코프 프로젝트·사용자·조직 저장소별(워크트리 간 공유)
로드 매 세션 전체 매 세션(MEMORY.md 앞 200줄/25KB)
쓰임새 코딩 표준·워크플로·아키텍처 빌드 명령·디버깅 통찰·발견한 선호

CLAUDE.md는 행동을 안내할 때, 자동 기억은 Claude가 당신의 교정으로부터 스스로 학습하게 하고 싶을 때 씁니다. 둘 다 강제 설정이 아니라 컨텍스트이며, 반드시 막아야 하는 동작은 PreToolUse 훅을 쓰세요.


어떻게 작동하나

Claude는 매 세션 무언가를 저장하지는 않습니다. 미래 대화에 유용할지를 스스로 판단해 저장할 가치가 있는 것만 기록합니다. 인터페이스에 "Saved 2 memories" 또는 "Recalled 2 memories"가 뜨면 Claude가 기억 디렉터리를 갱신·조회하는 중입니다.

당신이 "항상 npm 말고 pnpm 써", "API 테스트는 로컬 Redis가 필요해" 같은 걸 알려 주면 Claude는 이를 자동 기억에 저장합니다. CLAUDE.md에 넣고 싶다면 "이거 CLAUDE.md에 추가해줘"라고 명시하세요.


저장 위치와 구조

프로젝트마다 고유한 기억 디렉터리를 가집니다.

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 간결한 색인 — 매 세션 로드
├── debugging.md       # 디버깅 패턴 상세
├── api-conventions.md # API 설계 결정
└── ...                # Claude가 만드는 주제 파일들
  • <project>는 git 저장소에서 유도되므로, 같은 저장소의 모든 워크트리·하위 디렉터리가 하나의 기억 디렉터리를 공유합니다.
  • MEMORY.md는 색인 역할 — 매 세션 시작 시 앞 200줄 또는 25KB(먼저 도달하는 쪽)만 로드됩니다.
  • debugging.md 같은 주제 파일은 시작 시 로드되지 않고, Claude가 필요할 때 읽습니다.
  • 머신 로컬입니다 — 머신·클라우드 간 공유되지 않습니다.

색인 한도 관리: MEMORY.md가 200줄/25KB 한도에 가까워지면 Claude Code가 "한 항목당 한 줄로, 상세는 주제 파일로, 오래된 항목은 병합·삭제하라"고 상기시킵니다. 한도를 넘으면 쓰기는 성공하지만 초과분은 다음 로드에서 버려지므로, 색인을 다시 쓰라는 에러를 반환합니다. YAML 프론트매터와 HTML 주석은 한도 계산에서 제외됩니다.


켜고 끄기

자동 기억은 기본 켜짐입니다.

  • 세션에서 /memory를 열어 토글(사용자 설정 ~/.claude/settings.json의 autoMemoryEnabled에 저장).
  • 특정 프로젝트만 끄려면 그 프로젝트 설정에:
{
  "autoMemoryEnabled": false
}
  • 환경변수로 끄기: CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.
  • 저장 위치 변경: settings.json의 autoMemoryDirectory(절대경로 또는 ~/로 시작).

기억 파일은 편집·삭제할 수 있는 평범한 마크다운입니다. /memory로 브라우징하고, 실제로 로드된 것은 /context로 확인하세요.


서브에이전트 기억

서브에이전트도 자신만의 자동 기억을 가질 수 있습니다. memory 프론트매터로 켜면, 서브에이전트가 코드베이스 패턴·디버깅 통찰·아키텍처 결정을 시간에 걸쳐 축적합니다.

---
name: code-reviewer
description: 코드 품질과 모범 사례 검토
memory: project
---

당신은 코드 리뷰어입니다. 리뷰하며 발견한 패턴·관례·반복되는 이슈를
당신의 에이전트 기억에 갱신하세요.
스코프 위치 언제
user ~/.claude/agent-memory/<name>/ 모든 프로젝트에 걸쳐 기억
project .claude/agent-memory/<name>/ 프로젝트 특화, 버전 관리로 공유(권장 기본값)
local .claude/agent-memory-local/<name>/ 프로젝트 특화, 커밋하지 않음

메인 대화의 자동 기억은 서브에이전트에 로드되지 않으며, 서브에이전트 기억은 별도 디렉터리입니다. 자동 기억을 끄면 memory 필드도 무효화됩니다.

활용 팁: - 시작 전에 기억을 참고하게: "이 PR을 리뷰하되, 전에 본 패턴이 기억에 있는지 확인해." - 완료 후 갱신하게: "끝났으니 배운 걸 기억에 저장해." - 서브에이전트 본문에 자기 기억을 능동적으로 관리하라는 지시를 직접 넣으면, 대화를 넘어 제도적 지식이 쌓입니다.


CLAUDE.md인가 자동 기억인가 — 선택 기준

  • 내가 항상 지키게 하고 싶다 → CLAUDE.md
  • Claude가 교정·발견으로 스스로 배우게 하고 싶다 → 자동 기억
  • 반드시 특정 시점에 실행돼야 한다 → 훅
  • 가끔만 필요한 절차·지식이다 → 스킬

핵심 요약

  • 자동 기억은 Claude가 스스로 쓰는 노트 — 당신의 교정·선호로부터 세션을 넘어 학습한다.
  • ~/.claude/projects/<project>/memory/에 저장되고, MEMORY.md(앞 200줄/25KB)가 색인으로 매 세션 로드된다.
  • 기본 켜짐, /memory나 autoMemoryEnabled로 통제. 모두 편집 가능한 마크다운.
  • 서브에이전트도 memory 스코프(project 권장)로 자기 지식을 축적할 수 있다.
확인 퀴즈

Q1. 자동 기억(Auto memory)에 노트를 쓰는 주체는?

해설 · CLAUDE.md는 당신이 쓰지만, 자동 기억은 Claude가 스스로 유용하다고 판단한 것을 기록합니다.

Q2. 매 세션 시작 시 로드되는 자동 기억의 색인 파일은?

해설 · MEMORY.md가 색인 역할을 하며 앞 200줄 또는 25KB만 로드됩니다. 주제 파일은 필요 시 읽습니다.

Q3. 서브에이전트 기억의 권장 기본 스코프는? (버전 관리로 공유 가능)

해설 · project 스코프는 .claude/agent-memory/에 저장되어 버전 관리로 팀과 공유됩니다.
CHAPTER 07

서브에이전트

서브에이전트(subagent)는 특정 작업을 전담하는 별도의 AI 도우미입니다. 각자 독립된 컨텍스트 창, 고유한 시스템 프롬프트, 제한된 도구 접근, 별도 권한을 가집니다.

핵심 가치는 컨텍스트 보호입니다. 테스트를 돌리거나 코드베이스를 뒤지면 수만 토큰의 출력이 쏟아지는데, 이걸 메인 대화에 쌓으면 성능이 떨어집니다. 서브에이전트에게 맡기면 그 장황한 출력은 서브에이전트의 컨텍스트에만 남고, 요약만 메인으로 돌아옵니다.

서브에이전트가 주는 이점: - 컨텍스트 보존 — 탐색·구현을 메인 대화 밖으로 - 제약 강제 — 쓸 수 있는 도구를 제한 - 재사용 — 사용자 레벨 정의로 프로젝트 간 공유 - 전문화 — 도메인 특화 시스템 프롬프트 - 비용 절감 — Haiku 같은 빠르고 저렴한 모델로 라우팅


내장 서브에이전트

Claude가 상황에 맞게 자동으로 쓰는 내장 에이전트가 있습니다.

에이전트 모델 도구 용도
Explore 메인 상속(API에선 Opus 상한) 읽기 전용(Write·Edit 거부) 파일 검색·코드베이스 탐색
Plan 메인 상속 읽기 전용 플랜 모드에서 계획 전 리서치
general-purpose 메인 상속 서브에이전트 가용 도구 전체 탐색+수정이 필요한 복합 작업

Explore와 Plan은 CLAUDE.md와 git 상태를 건너뛰어 리서치를 가볍고 빠르게 유지합니다. 나머지 모든 에이전트는 둘 다 로드합니다.


첫 서브에이전트 만들기

서브에이전트는 YAML 프론트매터 + 마크다운 본문(시스템 프롬프트) 형식의 파일입니다. Claude에게 만들어 달라고 하거나 직접 작성합니다.

---
name: code-reviewer
description: 코드 품질과 모범 사례를 검토. 코드 작성·수정 후 사용.
tools: Read, Grep, Glob
model: sonnet
---

당신은 코드 리뷰어입니다. 호출되면 코드를 분석해
품질·보안·모범 사례에 대한 구체적이고 실행 가능한 피드백을 제공하세요.

본문은 시스템 프롬프트가 됩니다. 서브에이전트는 이 프롬프트와 작업 디렉터리 같은 기본 환경 정보만 받고, Claude Code의 전체 시스템 프롬프트는 받지 않습니다.

/agents 명령은 이제 마법사를 열지 않고, "Claude에게 부탁하거나 .claude/agents/를 직접 편집하라"는 안내를 출력합니다. Claude Code는 .claude/agents/와 ~/.claude/agents/를 감시하므로, 파일을 추가·수정하면 몇 초 내 다음 위임부터 반영됩니다(새 디렉터리를 처음 만든 경우만 재시작 필요).


어디에 두는가 — 스코프와 우선순위

위치 스코프 우선순위
관리 설정 조직 전체 1 (최고)
--agents CLI 플래그 현재 세션 2
.claude/agents/ 현재 프로젝트 3
~/.claude/agents/ 모든 프로젝트 4
플러그인 agents/ 플러그인 활성 시 5 (최저)

같은 name이 여러 곳에 있으면 우선순위 높은 쪽이 이깁니다. 정체성은 오직 name 프론트매터로 결정되므로(파일명·하위폴더 무관), 트리 전체에서 name을 고유하게 유지하세요.


프론트매터 필드

name과 description만 필수입니다.

필드 설명
name 소문자·하이픈 식별자(필수)
description 언제 위임할지(필수). 자동 위임의 트리거
tools 허용 도구 목록. 생략 시 서브에이전트 가용 도구 전체 상속
disallowedTools 제거할 도구(denylist)
model sonnet/opus/haiku/fable/전체 ID/inherit. 기본 inherit
permissionMode default/acceptEdits/auto/dontAsk/bypassPermissions/plan
skills 시작 시 컨텍스트에 프리로드할 스킬(설명이 아닌 전체 내용 주입)
mcpServers 이 서브에이전트에만 줄 MCP 서버
hooks 이 서브에이전트 생명주기에 한정된 훅
memory 지속 기억 스코프: user/project/local (자동 기억 참고)
isolation worktree 설정 시 격리된 git 워크트리에서 실행
background true면 항상 백그라운드 실행
omitClaudeMd true면 사용자·프로젝트 CLAUDE.md 로드를 건너뛰고 관리 정책만 적용 (컨텍스트 절약 및 특화 에이전트 격리, v2.1.271+)

도구 제한 (allowlist / denylist)

---
name: safe-researcher
description: 제한된 권한의 리서치 에이전트
tools: Read, Grep, Glob, Bash
---

위는 4개 도구만 허용 — 파일 수정·쓰기·MCP 사용 불가. 반대로 disallowedTools: Write, Edit는 나머지는 상속하되 쓰기만 막습니다. 둘 다 설정하면 disallowedTools를 먼저 적용한 뒤 tools를 해석합니다.

모델 선택으로 비용 관리

읽기 위주의 단순 탐색은 model: haiku로 저렴하게, 보안 리뷰처럼 판단이 중요한 작업은 model: opus로. 리소스를 작업 성격에 맞추는 것이 핵심입니다.


자동 위임 vs 명시적 호출

자동 위임: Claude는 요청 내용과 각 서브에이전트의 description을 보고 스스로 위임합니다. 적극적 위임을 유도하려면 description에 "use proactively" 같은 표현을 넣으세요.

명시적 호출 — 세 단계로 강해집니다.

# 1) 자연어: Claude가 위임 여부 판단
test-runner 서브에이전트로 실패한 테스트를 고쳐줘

# 2) @멘션: 해당 서브에이전트 실행을 보장
@"code-reviewer (agent)" 인증 변경을 봐줘
# 3) 세션 전체를 한 에이전트로 실행
claude --agent code-reviewer

.claude/settings.json에 "agent": "code-reviewer"를 넣으면 프로젝트 기본값이 됩니다.


포그라운드 vs 백그라운드

  • 포그라운드: 완료까지 메인 대화를 막음. 권한 프롬프트를 즉시 전달.
  • 백그라운드(기본값): 동시 실행되며 계속 작업 가능. 결과는 완료 시 알림으로 도착. 권한 프롬프트는 메인 세션에 표시되며, 서브에이전트 이름이 함께 뜹니다.

Ctrl+B로 실행 중 작업을 백그라운드로 보낼 수 있습니다. 백그라운드 서브에이전트는 더 좁은 내장 도구 세트로 동작합니다.

💡 백그라운드 에이전트 CLI 관리 (v2.1.280+): 세션 바깥 터미널에서도 백그라운드 작업을 직접 제어할 수 있습니다: - claude agents: 백그라운드에서 실행 중인 에이전트 세션 목록과 짧은 ID(short id) 확인 - claude attach <id>: 특정 백그라운드 세션에 터미널을 직접 연결하여 대화 재개 - claude logs <id>: 백그라운드 세션의 최근 콘솔 출력 확인 - claude stop <id>: 백그라운드 세션 중지 (대화 기록은 보존됨) - claude respawn <id>: 최신 Claude Code 버전으로 백그라운드 세션 재시작


실전 패턴

  • 고출력 작업 격리: "서브에이전트로 테스트를 돌리고 실패한 테스트와 에러만 보고해줘"
  • 병렬 리서치: "auth·database·API 모듈을 별도 서브에이전트로 병렬 조사해줘"
  • 체이닝: "code-reviewer로 성능 이슈를 찾은 다음, optimizer로 고쳐줘"
  • 적대적 리뷰(adversarial review): 구현이 끝나면 새 컨텍스트의 리뷰어가 diff만 보고 검증하게 하라 — 작업한 모델이 스스로 채점하지 않게. 단, 리뷰어에게는 "정확성·요구사항에 영향을 주는 결함만 지적하라"고 못박아 과잉 엔지니어링을 막으세요.

보안: Claude Code v2.1.210+는 서브에이전트의 최종 보고를 Claude가 읽기 전에 스캔합니다. 서브에이전트가 읽은 파일·웹페이지에 메인 대화를 노리는 지시가 숨어 있을 수 있기 때문입니다. 그래도 근본 방어는 서브에이전트가 접근할 수 있는 것을 제한하는 것(tools/permissionMode)입니다.


핵심 요약

  • 서브에이전트 = 독립 컨텍스트 + 전용 프롬프트 + 제한된 도구. 컨텍스트를 지키는 가장 강력한 수단.
  • .claude/agents/(프로젝트) 또는 ~/.claude/agents/(개인)에 name+description 프론트매터로 정의.
  • description이 자동 위임을 좌우한다. tools/model로 권한과 비용을 조절한다.
  • 고출력 격리·병렬 리서치·적대적 리뷰가 대표 패턴이다. 스킬을 skills 필드로 프리로드해 결합할 수 있다.
확인 퀴즈

Q1. 서브에이전트를 쓰는 가장 핵심적인 이유는?

해설 · 장황한 출력은 서브에이전트 컨텍스트에만 남고 요약만 메인으로 돌아옵니다 — 컨텍스트 보호가 핵심입니다.

Q2. Claude가 어떤 서브에이전트에 자동 위임할지 결정하는 프론트매터 필드는?

해설 · description이 자동 위임의 트리거입니다. "use proactively" 같은 표현으로 적극 위임을 유도할 수 있습니다.

Q3. 내장 Explore·Plan 에이전트가 속도를 위해 로드하지 않는 것은?

해설 · Explore·Plan은 CLAUDE.md와 git 상태를 건너뛰어 리서치를 가볍고 빠르게 유지합니다.
CHAPTER 08

스킬

스킬(Skill)은 Claude의 능력을 확장하는 재사용 가능한 지식·절차 묶음입니다. SKILL.md 파일에 지시를 적어 두면 Claude가 자기 도구상자에 추가하고, 관련될 때 스스로 불러오거나 /스킬이름으로 직접 호출할 수 있습니다.

언제 스킬을 만드나? 같은 지시·체크리스트·다단계 절차를 채팅에 반복해서 붙여 넣고 있을 때, 또는 CLAUDE.md의 한 섹션이 "사실"이 아니라 "절차"로 커졌을 때입니다.

스킬의 결정적 장점 — 온디맨드 로딩: CLAUDE.md는 매 세션 전체가 로드되지만, 스킬 본문은 실제로 쓰일 때만 로드됩니다. 그래서 긴 참조 자료도 필요하기 전까진 컨텍스트 비용이 거의 0입니다. "가끔만 필요한 도메인 지식·워크플로"는 CLAUDE.md가 아니라 스킬에 두세요.

스킬은 Agent Skills 오픈 표준을 따라 여러 AI 도구에서 호환됩니다.


첫 스킬 만들기

스킬은 디렉터리 + SKILL.md입니다. 디렉터리 이름이 곧 명령어(/)가 됩니다.

mkdir -p ~/.claude/skills/summarize-changes

~/.claude/skills/summarize-changes/SKILL.md:

---
description: 커밋되지 않은 변경을 요약하고 위험 요소를 표시. 사용자가 무엇이 바뀌었는지 묻거나, 커밋 메시지·diff 리뷰를 원할 때 사용.
---

## 현재 변경사항
!`git diff HEAD`

## 지시
위 변경을 2~3개 불릿으로 요약한 뒤, 누락된 에러 처리·하드코딩·수정이 필요한
테스트 같은 위험을 나열하라. diff가 비어 있으면 변경 없음이라고 답하라.

!`git diff HEAD`는 동적 컨텍스트 주입 — Claude가 스킬을 보기 전에 명령이 실행되어 실제 diff가 인라인됩니다. 이제 "뭐가 바뀌었어?"라고 물으면 자동으로, /summarize-changes로는 직접 호출됩니다.


어디에 두는가

위치 경로 적용 범위
엔터프라이즈 관리 설정 조직 전체
개인 ~/.claude/skills/<name>/SKILL.md 내 모든 프로젝트
프로젝트 .claude/skills/<name>/SKILL.md 이 프로젝트만
플러그인 <plugin>/skills/<name>/SKILL.md 플러그인 활성 시

이름이 겹치면 엔터프라이즈 > 개인 > 프로젝트 순으로 이깁니다. 스킬 디렉터리는 라이브 변경 감지 — 세션 중 추가·수정·삭제가 재시작 없이 반영됩니다(최상위 디렉터리를 새로 만든 경우만 재시작).


프론트매터 레퍼런스

description만 권장 필수입니다. 자주 쓰는 필드:

필드 설명
name 목록에 표시될 이름(기본: 디렉터리명)
description 무엇을·언제 쓰는지. Claude의 자동 호출 판단 근거. 앞부분에 핵심 용례를 두세요(목록에서 1,536자로 잘림)
disable-model-invocation true면 Claude 자동 호출 차단, 사용자만 /name으로
user-invocable false면 / 메뉴에서 숨김(Claude만 사용)
allowed-tools 호출 턴 동안 승인 없이 쓸 도구. 다음 메시지에 해제
disallowed-tools 스킬 활성 중 제거할 도구
model / effort 스킬 활성 중 모델·추론강도 오버라이드
context fork 설정 시 격리된 서브에이전트에서 실행
agent context: fork일 때 쓸 서브에이전트 타입
paths 매칭 파일을 다룰 때만 자동 활성화(글롭)

누가 호출하는가 통제

---
name: deploy
description: 애플리케이션을 프로덕션에 배포
disable-model-invocation: true
---
  • disable-model-invocation: true → 사용자만 호출. /commit·/deploy처럼 부작용이 있거나 타이밍을 통제하고 싶은 워크플로에.
  • user-invocable: false → Claude만 호출. /로 실행할 의미가 없는 배경 지식(예: legacy-system-context)에.

도구 사전 승인

---
name: commit
description: 현재 변경을 스테이징하고 커밋
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

allowed-tools에 나열된 도구는 스킬을 호출한 턴 동안 권한 프롬프트 없이 실행됩니다(다음 메시지에 해제).


지원 파일과 점진적 공개

스킬 디렉터리에는 여러 파일을 둘 수 있습니다. SKILL.md는 핵심만 담고, 상세 자료는 필요할 때만 로드하게 하세요.

my-skill/
├── SKILL.md          # 필수 — 개요·내비게이션
├── reference.md      # 상세 API(필요 시 로드)
├── examples.md       # 예시(필요 시 로드)
└── scripts/
    └── helper.py     # 실행용 스크립트(로드 아님)

SKILL.md에서 지원 파일을 참조해 Claude가 무엇이 어디 있는지 알게 하세요.

팁: SKILL.md는 500줄 이하로. 본문은 한번 로드되면 세션 내내 컨텍스트에 남아 매 턴 토큰 비용이 되므로, "왜·어떻게"를 늘어놓기보다 "무엇을 하라"를 간결히 적으세요.

스크립트 번들링

스킬은 어떤 언어의 스크립트든 번들해 실행할 수 있어, 단일 프롬프트로 불가능한 능력을 줍니다(데이터 시각화, 의존성 그래프, 커버리지 리포트 등). ${CLAUDE_SKILL_DIR} 변수로 설치 위치와 무관하게 스크립트를 참조하세요.

---
name: render-chart
description: CSV로 차트 렌더링
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---

`${CLAUDE_SKILL_DIR}/scripts/render.sh <csv-file>` 를 실행해 차트를 렌더링하라.

서브에이전트에서 실행 (context: fork)

context: fork를 넣으면 스킬이 격리된 서브에이전트에서 실행됩니다. 스킬 본문이 그 서브에이전트의 프롬프트가 되고, 메인 대화 히스토리에는 접근하지 않습니다.

---
name: deep-research
description: 주제를 철저히 리서치
context: fork
agent: Explore
---

$ARGUMENTS 를 철저히 리서치하라:
1. Glob·Grep으로 관련 파일 찾기
2. 코드 읽고 분석
3. 구체적 파일 참조와 함께 결과 요약

이는 서브에이전트의 skills 프리로드와 역방향 관계입니다.

방식 시스템 프롬프트 작업
스킬 context: fork 에이전트 타입에서 SKILL.md 내용
서브에이전트 skills 필드 서브에이전트 본문 Claude의 위임 메시지

인자와 동적 컨텍스트

  • 인자: $ARGUMENTS(전체), $0·$1(위치별). /fix-issue 123 → $ARGUMENTS가 123.
  • 동적 주입: !`명령`는 Claude가 보기 전에 실행되어 출력으로 치환. 여러 줄은 ```! 펜스.
  • 스택: 한 메시지에 여러 스킬을 앞에 쌓을 수 있음(최대 6개) — /write-tests /fix-issue 123.

스킬 vs CLAUDE.md vs 서브에이전트

언제 로드 쓰임새
CLAUDE.md 매 세션 전체 항상 필요한 사실·규칙
스킬 호출 시에만 가끔 필요한 절차·도메인 지식
서브에이전트 위임 시 격리 컨텍스트 고출력·전문 작업의 격리

문제 해결

  • 트리거가 안 됨: description에 사용자가 실제로 쓸 키워드를 넣기 → "무슨 스킬 있어?"로 목록 확인 → 직접 /name 호출.
  • 너무 자주 트리거: description을 더 구체적으로, 또는 disable-model-invocation: true.
  • 설명이 잘림: 스킬이 많으면 목록 예산에 맞춰 설명이 잘림. 핵심 용례를 앞에 두고, skillListingBudgetFraction 상향 또는 저우선 스킬을 "name-only"로.

핵심 요약

  • 스킬 = SKILL.md 기반의 온디맨드 지식·절차. 컨텍스트를 아끼면서 능력을 확장한다.
  • 디렉터리명이 명령어가 되고, description이 자동 호출을 좌우한다.
  • disable-model-invocation·allowed-tools·context: fork로 호출 주체·권한·실행 위치를 통제한다.
  • 커스텀 명령어는 이제 스킬로 통합됐다 — 명령어 챕터의 문법이 그대로 적용된다.
확인 퀴즈

Q1. 스킬 본문(SKILL.md 내용)은 언제 컨텍스트에 로드되나요?

해설 · 온디맨드 로딩이 스킬의 핵심 장점입니다. 긴 참조 자료도 쓰이기 전엔 컨텍스트 비용이 거의 0입니다.

Q2. Claude가 스킬을 자동으로 호출하지 못하게 하고 사용자만 /name으로 실행하게 하려면?

해설 · disable-model-invocation: true는 부작용이 있는 워크플로(/deploy 등)에 적합합니다.

Q3. 스킬을 격리된 서브에이전트 컨텍스트에서 실행하게 하는 프론트매터는?

해설 · context: fork를 넣으면 스킬 본문이 서브에이전트의 프롬프트가 되어 격리 실행됩니다.
CHAPTER 09

훅 (Hooks)

훅(Hook)은 Claude Code 생명주기의 특정 시점에 자동으로 실행되는 셸 명령입니다. 핵심은 결정론(determinism) 입니다. CLAUDE.md의 지침은 "따라 주길 바라는" 조언이지만, 훅은 Claude의 판단과 무관하게 반드시 실행됩니다.

"특정 시점에 예외 없이 매번 일어나야 하는 일"에는 훅을 쓰세요. 파일 편집 후 포맷팅, 위험한 명령 차단, 입력 대기 알림, 세션 시작 시 컨텍스트 주입 — 모두 훅의 영역입니다.

판단이 필요한 결정에는 셸 대신 모델을 쓰는 프롬프트 훅·에이전트 훅도 있습니다.


첫 훅 — 입력 대기 알림

설정 파일에 hooks 블록을 추가합니다. 아래는 Claude가 입력을 기다릴 때 데스크톱 알림을 띄우는 예입니다(Linux).

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

/hooks로 등록 여부를 확인합니다(이 메뉴는 읽기 전용 — 추가·수정은 설정 JSON을 직접 편집하거나 Claude에게 부탁). Claude에게 "파일 편집마다 eslint를 돌리는 훅을 써줘"처럼 부탁하면 훅을 작성해 줍니다.


어디에 두는가

위치 스코프 공유
~/.claude/settings.json 모든 프로젝트 아니오(머신 로컬)
.claude/settings.json 단일 프로젝트 예(커밋 가능)
.claude/settings.local.json 단일 프로젝트 아니오(gitignore)
관리 정책 설정 조직 전체 예(관리자)
플러그인 hooks/hooks.json 플러그인 활성 시 예
스킬·에이전트 프론트매터 그 컴포넌트 활성 중 예

모든 훅을 끄려면 "disableAllHooks": true.


주요 훅 이벤트

이벤트가 발생하면 매칭되는 훅이 병렬 실행되고, 동일 명령은 자동 중복 제거됩니다.

이벤트 발생 시점
SessionStart 세션 시작·재개
UserPromptSubmit 프롬프트 제출 직후, Claude 처리 전
PreToolUse 도구 실행 전. 차단 가능
PermissionRequest 권한 대화가 뜰 때
PostToolUse 도구 실행 성공 후
PostToolUseFailure 도구 실행 실패 후
Notification 알림 전송 시
SubagentStart / SubagentStop 서브에이전트 시작·종료
Stop Claude가 응답을 마칠 때
PreCompact / PostCompact 컨텍스트 압축 전·후
InstructionsLoaded CLAUDE.md·규칙 로드 시
SessionEnd 세션 종료

type은 대부분 "command"(셸)이며, 이 외에 "http"(URL POST), "mcp_tool"(MCP 도구 호출), "prompt"(단일턴 LLM 판단), "agent"(도구를 쓰는 다중턴 검증, 실험적)가 있습니다.


매처(matcher)로 필터링

매처가 없으면 이벤트마다 무조건 실행됩니다. 도구 이벤트는 도구 이름으로 필터합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

"Edit|Write"는 파일 편집 도구에서만 발동(,도 동일 구분자). MCP 도구는 mcp__<server>__<tool> 형식이라 mcp__github__.* 같은 정규식으로 매칭합니다. 이벤트별 매처 대상:

이벤트 매처가 거르는 것 예
PreToolUse·PostToolUse 도구 이름 Bash, Edit\|Write, mcp__.*
SessionStart 세션 시작 방식 startup, resume, clear, compact
Notification 알림 종류 permission_prompt, idle_prompt
SubagentStart/Stop 에이전트 타입 Explore, 커스텀 이름

입력과 출력 — 훅이 Claude를 통제하는 법

훅은 stdin(JSON 입력) · stdout/stderr · 종료 코드로 소통합니다. 이벤트가 발생하면 이벤트별 데이터가 JSON으로 stdin에 전달됩니다.

{
  "session_id": "abc123",
  "cwd": "/Users/sarah/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "npm test" }
}

종료 코드

코드 의미
0 이의 없음. 정상 진행. UserPromptSubmit·SessionStart는 stdout이 컨텍스트에 추가됨
2 동작 차단. stderr가 Claude에게 피드백으로 전달되어 조정하게 함
그 외 진행하되 경고 표시

PreToolUse에서 exit 0은 도구를 승인하는 게 아닙니다 — 정상 권한 흐름이 그대로 적용됩니다. 차단하려면 exit 2 또는 아래의 구조화 JSON을 쓰세요.

구조화 JSON 출력

exit 0으로 하되 stdout에 JSON을 출력하면 더 정밀하게 통제합니다. PreToolUse의 권한 결정:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "grep 대신 rg를 쓰세요(성능)"
  }
}

permissionDecision은 allow(프롬프트 건너뜀)·deny(취소+사유 전달)·ask(정상 프롬프트). UserPromptSubmit은 additionalContext로 매 프롬프트에 컨텍스트를 주입합니다.


실전 예제

보호 파일 편집 차단 (PreToolUse)

.claude/hooks/protect-files.sh:

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "차단: $FILE_PATH 는 보호 패턴 '$pattern' 에 해당" >&2
    exit 2
  fi
done
exit 0

chmod +x로 실행 권한을 주고, PreToolUse/Edit|Write로 등록합니다.

압축 후 컨텍스트 재주입 (SessionStart)

압축은 대화를 요약하며 중요 세부를 잃을 수 있습니다. SessionStart/compact 매처로 핵심을 다시 주입하세요(stdout이 컨텍스트에 추가됨).

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          { "type": "command", "command": "echo '알림: npm 아닌 Bun 사용. 커밋 전 bun test. 현재 스프린트: auth 리팩터.'" }
        ]
      }
    ]
  }
}

완료 전 테스트 검증 (프롬프트/에이전트 훅)

판단이 필요하면 Stop 훅에 모델을 씁니다. 모델은 yes/no만 반환하고, "ok": false면 사유를 Claude에게 돌려 계속 일하게 합니다.

{
  "hooks": {
    "Stop": [
      { "hooks": [ { "type": "prompt", "prompt": "모든 작업이 끝났는지 확인. 아니면 {\"ok\": false, \"reason\": \"남은 일\"} 로 응답." } ] }
    ]
  }
}

코드베이스 상태를 실제로 검증해야 하면 도구를 쓰는 "type": "agent" 훅(예: "테스트 스위트를 실행해 통과 확인")을 씁니다.


훅과 권한 모드

PreToolUse 훅은 모든 권한 모드보다 먼저 발동합니다 — bypassPermissions나 --dangerously-skip-permissions에서도 deny가 도구를 막습니다. 즉 사용자가 권한 모드를 바꿔도 우회할 수 없는 정책을 강제할 수 있습니다.

역은 성립하지 않습니다 — 훅의 allow는 설정의 deny 규칙을 뚫지 못합니다. 훅은 제약을 조일 수는 있어도 느슨하게 풀 수는 없습니다.


문제 해결

증상 확인
훅이 안 뜸 /hooks로 등록 확인, 매처는 대소문자 구분, 이벤트 타입 확인
"hook error" 샘플 JSON을 파이프해 수동 테스트, 절대경로/${CLAUDE_PROJECT_DIR} 사용, chmod +x
Stop 훅 무한 반복 8회 연속 차단 시 오버라이드됨. stop_hook_active를 파싱해 조기 종료
JSON 검증 실패 셸 프로필의 echo가 stdout을 오염 — 대화형 셸에서만 실행되게 감싸기

보안 주의: 훅은 당신 권한으로 임의 셸 명령을 실행합니다. 공유·프로덕션 환경에 배포하기 전 반드시 검토하세요.


핵심 요약

  • 훅 = 생명주기 시점에 결정론적으로 실행되는 자동화. CLAUDE.md가 조언이라면 훅은 강제.
  • 설정 파일의 hooks 블록에 이벤트·매처·명령으로 정의한다.
  • stdin(JSON)·종료코드(0/2)·구조화 JSON으로 Claude의 동작을 차단·허용·컨텍스트 주입한다.
  • 포맷팅·보호 파일 차단·압축 후 재주입·완료 전 검증이 대표 용례. 정책 강제는 훅으로, 조언은 CLAUDE.md로.
확인 퀴즈

Q1. 훅(Hook)이 CLAUDE.md와 근본적으로 다른 점은?

해설 · CLAUDE.md는 조언이지만 훅은 강제입니다 — 특정 시점에 예외 없이 실행됩니다.

Q2. PreToolUse 훅에서 도구 실행을 '차단'하려면 어떤 종료 코드를 쓰나요?

해설 · exit 2는 동작을 차단하고 stderr를 Claude에게 피드백으로 전달합니다. exit 0은 정상 진행입니다.

Q3. 파일 편집 직후 자동으로 포맷터(prettier)를 돌리려면 어느 이벤트를 쓰나요?

해설 · PostToolUse는 도구 실행 성공 후 발동합니다. Edit|Write 매처로 파일 편집 시에만 실행합니다.
CHAPTER 10

MCP · 플러그인 · 확장

지금까지 배운 명령어·CLAUDE.md·서브에이전트·스킬·훅은 모두 Claude Code 안쪽의 확장입니다. 이 챕터는 바깥으로 확장하는 두 가지 — MCP(외부 도구 연결)와 플러그인(확장 묶음 배포) — 을 다룹니다.

MCP — 외부 도구·데이터 연결

MCP(Model Context Protocol)는 AI-도구 통합을 위한 오픈 표준입니다. MCP 서버를 연결하면 Claude Code가 당신의 도구·데이터베이스·API에 직접 접근합니다.

언제 연결하나? 이슈 트래커나 모니터링 대시보드 같은 다른 도구에서 채팅으로 데이터를 복사해 붙여넣고 있다면 신호입니다. 연결하면 붙여넣는 대신 Claude가 그 시스템을 직접 읽고 다룹니다.

MCP로 할 수 있는 일 예시: - "JIRA 이슈 ENG-4521에 설명된 기능을 구현하고 GitHub에 PR을 만들어줘" - "PostgreSQL에서 이 기능을 쓴 사용자 10명의 이메일을 찾아줘" - "Slack에 올라온 새 Figma 디자인으로 이메일 템플릿을 갱신해줘"

서버 추가 — claude mcp add

세 가지 전송 방식이 있습니다.

# 1) 원격 HTTP 서버 (가장 흔함, OAuth 지원)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 2) 원격 SSE 서버
claude mcp add --transport sse asana https://mcp.asana.com/sse

# 3) 로컬 stdio 서버 (내 머신에서 프로세스로 실행)
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY airtable -- npx -y airtable-mcp-server

stdio 서버는 --(더블 대시) 뒤에 실행할 명령을 씁니다 — -- 뒤는 서버에 그대로 전달됩니다.

스코프 — 어디에 저장할지

-s/--scope로 설정 저장 위치를 정합니다.

스코프 저장 위치 공유
local (기본) ~/.claude.json 나만, 이 프로젝트
project .mcp.json (커밋) 팀 전체
user ~/.claude.json 나의 모든 프로젝트
claude mcp add --scope project --transport http github https://api.githubcopilot.com/mcp/

프로젝트 스코프 서버(.mcp.json)는 저장소를 신뢰하기 전까지 승인 대기 상태입니다 — claude를 실행해 검토·승인하세요.

관리 — /mcp

세션에서 /mcp로 서버 연결 상태를 보고 OAuth 인증을 처리합니다. HTTP/SSE 서버가 끊기면 지수 백오프로 자동 재연결(최대 5회)합니다.

보안: MCP 서버는 외부 코드입니다. 신뢰할 수 있는 서버만 연결하고, 프로젝트 .mcp.json은 저장소 신뢰 후에만 활성화하세요. Anthropic 디렉터리에서 검증된 커넥터를 찾을 수 있습니다.

CLI 도구도 잊지 마세요

MCP만이 외부 연동은 아닙니다. gh(GitHub), aws, gcloud 같은 CLI 도구는 가장 컨텍스트 효율적인 외부 서비스 접근법입니다. gh를 설치하면 Claude가 이슈·PR·코멘트를 알아서 다룹니다. Claude는 모르는 CLI도 배웁니다 — 'foo --help'로 foo를 익힌 뒤 A를 해줘.


플러그인 — 확장을 묶어 배포

플러그인은 스킬·훅·서브에이전트·MCP 서버를 하나의 설치 단위로 묶습니다. 커뮤니티와 Anthropic이 만든 것을 설정 없이 설치할 수 있습니다.

/plugin      # 마켓플레이스 브라우징·설치
  • 타입 언어를 쓴다면 코드 인텔리전스 플러그인을 설치해 정확한 심볼 내비게이션과 편집 후 자동 에러 감지를 얻으세요.
  • 플러그인은 스킬·훅·에이전트·MCP를 한 번에 제공하므로, 팀 표준 워크플로를 배포하는 데 이상적입니다.
  • 플러그인 마켓플레이스 추가: /plugin marketplace add <owner/repo>.
  • 플러그인 품질 평가(claude plugin eval): 만든 플러그인의 신뢰성을 검증하려면 eval 스위트를 구동해 채점 결과와 재현 가능한 JSON/HTML 리포트를 산출할 수 있습니다(claude plugin eval --help). 또한 CLI 자동화를 위한 --json 출력(claude plugin list --json 등)도 지원됩니다.

플러그인이 제공하는 스킬·에이전트는 plugin-name:skill-name 형태의 네임스페이스를 써서 다른 것과 충돌하지 않습니다.


언제 무엇을 쓰나 — 확장 기능 선택


핵심 요약

  • MCP는 외부 도구·DB·API를 Claude Code에 연결한다. claude mcp add --transport http|sse|stdio, 스코프(local/project/user), /mcp로 관리.
  • 다른 도구에서 데이터를 복사해 붙여넣고 있다면 MCP 연결 신호. CLI 도구(gh 등)도 강력한 대안.
  • 플러그인은 스킬·훅·에이전트·MCP를 한 단위로 묶어 배포한다. /plugin으로 설치.
  • 필요에 맞춰 CLAUDE.md·스킬·훅·서브에이전트·MCP·플러그인을 골라 조합하라 — 오케스트레이션에서 하나로 엮인다.
확인 퀴즈

Q1. 원격 HTTP MCP 서버를 추가하는 명령은?

해설 · claude mcp add --transport http notion https://mcp.notion.com/mcp 형태로 추가합니다. sse·stdio 전송도 있습니다.

Q2. 팀 전체와 공유(.mcp.json 커밋)하려면 어떤 MCP 스코프를 쓰나요?

해설 · --scope project는 .mcp.json에 저장되어 커밋을 통해 팀과 공유됩니다. local은 나만, user는 내 모든 프로젝트.

Q3. 스킬·훅·서브에이전트·MCP를 한 단위로 묶어 배포하는 것은?

해설 · 플러그인은 여러 확장을 하나의 설치 단위로 묶습니다. /plugin으로 마켓플레이스에서 설치합니다.
CHAPTER 11

오케스트레이션 & 실전 워크플로

지금까지 배운 확장 조각들 — 명령어, CLAUDE.md, 자동 기억, 서브에이전트, 스킬, 훅, MCP·플러그인 — 은 따로 쓰일 때보다 엮일 때 위력이 커집니다. 이 챕터는 그 조각들을 하나의 실전 워크플로로 조율하는 법을 다룹니다.

Claude Code는 질문에 답하고 기다리는 챗봇이 아니라 에이전틱 코딩 환경입니다. 코드를 짜서 리뷰를 부탁하는 대신, 원하는 것을 서술하면 Claude가 탐색·계획·구현합니다. 이 자율성을 잘 다루는 열쇠는 단 하나의 제약에서 나옵니다.

모든 모범 사례는 한 제약으로 수렴합니다: 컨텍스트 창은 빠르게 차고, 찰수록 성능이 떨어진다. 컨텍스트는 관리해야 할 가장 중요한 자원입니다. /context로 사용량을 계속 추적하세요.


워크플로 1 — 탐색 → 계획 → 구현 → 커밋

바로 코딩에 뛰어들면 엉뚱한 문제를 푸는 코드가 나옵니다. 플랜 모드로 탐색과 실행을 분리하세요.

  1. 탐색 — 플랜 모드 진입. 변경 없이 파일을 읽고 질문에 답. read /src/auth 하고 세션·로그인 처리 방식을 이해해줘
  2. 계획 — Google OAuth를 추가하려 해. 어떤 파일이 바뀌고 세션 흐름은? 계획을 세워줘. (Ctrl+G로 계획을 에디터에서 직접 편집)
  3. 구현 — 플랜 모드를 나와 계획대로 코딩하고 검증. 계획대로 OAuth를 구현하고, 콜백 핸들러 테스트를 작성해 실행·수정해줘.
  4. 커밋 — 설명적인 메시지로 커밋하고 PR을 열어줘.

플랜 모드는 만능이 아닙니다. 오타 수정·로그 한 줄 추가처럼 범위가 명확하고 작은 변경은 그냥 시키세요. 계획은 접근법이 불확실하거나, 여러 파일을 건드리거나, 낯선 코드를 만질 때 가장 유용합니다. 한 문장으로 diff를 설명할 수 있으면 계획을 건너뛰세요.


워크플로 2 — 검증 수단을 반드시 줘라

Claude는 작업이 끝나 보이면 멈춥니다. 검증 수단이 없으면 "끝나 보임"이 유일한 신호가 되고, 당신이 검증 루프가 됩니다. Claude가 읽을 수 있는 합격/불합격 신호를 주면 루프가 스스로 닫힙니다 — 작업하고, 검증하고, 통과할 때까지 반복.

검증은 대화에서 읽히는 신호면 무엇이든 됩니다: 테스트 스위트, 빌드 종료 코드, 린터, 출력을 픽스처와 비교하는 스크립트, 디자인과 비교하는 스크린샷.

게이트 강도 방법
한 프롬프트 "구현 후 테스트를 실행해 통과할 때까지 반복해"
세션 전체 /goal 조건 — 매 턴 후 별도 평가자가 재확인
결정론적 게이트 Stop 훅이 스크립트로 검증, 통과 전엔 턴 종료 차단
제2의 의견 검증 서브에이전트가 새 모델로 결과를 반박

주장이 아니라 증거를 보이게 하세요 — 테스트 출력, 실행한 명령과 결과, 스크린샷. 증거 리뷰가 당신이 직접 재검증하는 것보다 빠릅니다.


워크플로 3 — 구체적으로 지시하라

Claude는 의도를 추론할 수는 있어도 마음을 읽지는 못합니다. 정밀한 지시일수록 교정이 줄어듭니다.

전략 나쁨 좋음
범위 지정 "foo.py에 테스트 추가" "foo.py에 로그아웃 상태 엣지케이스를 다루는 테스트를 작성해. 목(mock) 없이."
출처 지목 "왜 이 API가 이상해?" "ExecutionFactory의 git 히스토리를 훑어 API가 어떻게 생겨났는지 요약해"
기존 패턴 참조 "캘린더 위젯 추가" "홈의 기존 위젯 구현을 봐. HotDogWidget.php가 좋은 예시야. 그 패턴을 따라..."
증상 서술 "로그인 버그 고쳐" "세션 타임아웃 후 로그인 실패. src/auth/의 토큰 갱신을 확인하고, 재현 실패 테스트를 먼저 쓴 뒤 고쳐"
  • 리치 컨텍스트 제공: @파일 참조, 이미지 붙여넣기, 문서 URL(/permissions로 도메인 허용), cat error.log | claude로 파이프.
  • 큰 기능은 Claude가 당신을 인터뷰하게: "이걸 만들고 싶어. AskUserQuestion 도구로 기술 구현·UX·엣지케이스를 인터뷰하고, 다 다루면 SPEC.md에 스펙을 써줘." → 새 세션에서 깨끗한 컨텍스트로 스펙을 실행.

워크플로 4 — 세션을 능동적으로 관리하라

대화는 영속적이고 되돌릴 수 있습니다. 이를 활용하세요.

  • 일찍, 자주 교정: Esc로 중단(컨텍스트 보존 후 방향 전환), Esc Esc//rewind로 체크포인트 복원, "방금 거 되돌려", 작업 전환 시 /clear.
  • 두 번 교정했다면 /clear: 같은 이슈로 두 번 넘게 고쳤다면 컨텍스트가 실패한 시도로 오염된 상태입니다. /clear 후 배운 것을 반영한 더 나은 프롬프트로 시작하는 편이 거의 항상 낫습니다.
  • 컨텍스트 공격적 관리: 무관한 작업 사이엔 /clear. /compact <지시>로 방향 있는 압축. 곁가지 질문은 /btw(히스토리에 안 남음).
  • 리서치는 서브에이전트로: "서브에이전트로 X를 조사해" — 별도 컨텍스트에서 탐색하고 요약만 돌려받아 메인을 깨끗이 유지.

워크플로 5 — 자동화·병렬로 확장

한 Claude에 익숙해지면 병렬 세션·비대화 모드로 출력을 배가합니다.

  • 비대화 모드: claude -p "프롬프트"를 CI·pre-commit·스크립트에. --output-format json으로 결과 파싱, --allowedTools로 무인 실행 권한 제한.
  • 병렬 세션: git 워크트리로 충돌 없는 격리 체크아웃, 데스크톱 앱의 시각적 다중 세션, 에이전트 팀의 자동 조율.
  • 세션 간 메시지(v2.1.224+, macOS·Linux): 세션끼리 직접 메시지를 주고받습니다 — ListAgents로 다른 세션을 찾고 SendMessage로 보냅니다. 한쪽에서 바뀐 사실을 다른 쪽에 여러분이 다시 설명하지 않아도 되는 것이 요점입니다. 오가는 것은 Claude가 쓴 텍스트뿐이고 대화 기록이나 파일은 넘어가지 않으며, 오토 모드에서는 보내는 메시지도 분류기가 검사합니다.
  • Writer/Reviewer 패턴: 새 컨텍스트는 리뷰 품질을 높입니다(Claude가 자기가 쓴 코드에 편향되지 않음). 한 세션이 구현하면, 다른 세션이 리뷰.
  • 파일 팬아웃: 대규모 마이그레이션은 파일 목록을 만들고 루프로 claude -p 호출.
for file in $(cat files.txt); do
  claude -p "Migrate $file from React to Vue. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)"
done
  • 오토 모드: claude --permission-mode auto -p "fix all lint errors" — 분류기 모델이 위험한 명령만 차단하며 무인 실행.

조각들이 맞물리는 그림

  • 명령어/스킬이 작업을 시작하고, 필요하면 서브에이전트에 위임한다.
  • CLAUDE.md와 자동 기억이 그 실행에 맥락과 학습을 공급한다.
  • 훅이 특정 시점마다 결정론적으로 개입해 포맷·검증·정책을 강제한다.

피해야 할 실패 패턴

패턴 처방
잡동사니 세션 — 무관한 작업이 섞여 컨텍스트가 오염 작업 사이 /clear
반복 교정 — 실패한 접근으로 컨텍스트 오염 2번 실패 후 /clear + 더 나은 프롬프트
과잉 CLAUDE.md — 길어서 규칙이 묻힘 무자비하게 가지치기, 규칙은 훅으로 전환
신뢰-검증 격차 — 그럴듯하지만 엣지케이스 미처리 항상 검증 수단(테스트·스크립트·스크린샷) 제공
무한 탐색 — 범위 없는 "조사"가 컨텍스트를 삼킴 범위를 좁히거나 서브에이전트로 격리

핵심 요약

  • 모든 것은 컨텍스트 관리로 수렴한다 — /clear·/compact·서브에이전트가 핵심 무기.
  • 탐색→계획→구현→커밋으로 엉뚱한 문제 풀기를 막고, 검증 수단으로 루프를 스스로 닫게 하라.
  • 구체적으로 지시하고, 일찍 교정하고, 두 번 실패하면 리셋하라.
  • 명령어·CLAUDE.md·서브에이전트·스킬·자동기억·훅이 하나의 오케스트레이션으로 맞물릴 때 무인 실행이 가능해진다.
확인 퀴즈

Q1. Claude Code의 거의 모든 모범 사례가 수렴하는 단 하나의 제약은?

해설 · 컨텍스트 창은 가장 중요한 자원입니다. 찰수록 성능이 떨어지므로 /clear·서브에이전트로 관리합니다.

Q2. 접근법이 불확실하거나 여러 파일을 건드릴 때 권장되는 워크플로 순서는?

해설 · 탐색(플랜 모드)→계획→구현→커밋. 단, 한 문장으로 diff를 설명할 수 있으면 계획을 건너뛰세요.

Q3. 같은 이슈로 두 번 넘게 교정했을 때 권장되는 행동은?

해설 · 두 번 교정했다면 컨텍스트가 실패한 시도로 오염된 상태입니다. 깨끗한 세션이 거의 항상 낫습니다.
CHAPTER 12

컨텍스트 엔지니어링

이 강의 내내 반복된 한 문장 — "컨텍스트 창이 가장 중요한 자원이다" — 을 이제 정면으로 다룹니다. 컨텍스트 엔지니어링(context engineering)은 2025년 이후 프롬프트 엔지니어링의 후계로 떠오른 개념으로, Anthropic은 이를 "추론 시점에 최적의 토큰 집합을 큐레이션·유지하는 전략"으로 정의합니다.

프롬프트 → 컨텍스트 엔지니어링

  • 프롬프트 엔지니어링: 한 번의 교환에서 보낼 텍스트(지시)를 최적화하는 것.
  • 컨텍스트 엔지니어링: 여러 턴에 걸쳐 모델이 받는 정보 전체를 큐레이션하는 것 — 시스템 프롬프트뿐 아니라 도구 출력, 파일 내용, 기억, 히스토리까지.

에이전트는 반복적으로 동작하며 데이터를 계속 생성합니다. 그래서 매 추론마다 "어떤 정보 구성이 원하는 행동을 가장 잘 끌어낼까"를 묻는, 순환적으로 다듬어지는 작업이 됩니다.


컨텍스트는 유한 자원 — 컨텍스트 로트

핵심 통찰: LLM에는 인간의 작업기억처럼 어텐션 예산(attention budget)이 있습니다. 토큰이 늘수록 그 예산이 소진되어, 정보를 정확히 기억·집중하는 능력이 떨어집니다. 이를 컨텍스트 로트(context rot)라 합니다.

  • 트랜스포머는 토큰 간 n² 쌍 관계를 만들어, 규모가 커질수록 어텐션이 얇게 퍼집니다.
  • 성능 저하는 절벽이 아니라 완만한 하강(gradient)입니다 — 갑자기 못 하게 되는 게 아니라 서서히 흐려집니다.
  • 즉, 1M 컨텍스트 창을 다 채운다고 더 좋아지지 않습니다. 목표는 "원하는 결과 확률을 최대화하는, 가장 작은 고신호(high-signal) 토큰 집합"을 찾는 것입니다.

4가지 큐레이션 영역

Anthropic이 제시하는 컨텍스트 엔지니어링의 실천 영역입니다.

1) 시스템 프롬프트 — "적정 고도(right altitude)"

두 실패 사이의 중간을 노립니다.

너무 낮음(brittle) 너무 높음(vague)
복잡한 if-else를 하드코딩 → 취약·유지보수 지옥 막연한 고수준 지침 → 행동을 못 이끎

스위트 스팟: 행동을 이끌 만큼 구체적이되, 강한 휴리스틱을 줄 만큼 유연한 지침. XML 태그/마크다운 헤더로 섹션을 나누고(## 도구 지침 등), 최소 프롬프트에서 시작해 실패 사례마다 명료함·예시를 더하세요. "최소"가 "짧다"는 뜻은 아닙니다 — 기대 행동을 온전히 그리는 최소 정보입니다. (CLAUDE.md 챕터의 "지우면 실수하는가?" 원칙과 동일한 정신입니다.)

2) 도구 설계 — 최소·명확·자기완결

  • 각 도구는 자기완결적이고, 에러에 강하며, 용도가 극도로 명확해야 합니다.
  • 비대한 도구 세트는 기능이 겹쳐 판단을 모호하게 만듭니다. "인간 엔지니어가 어떤 도구를 써야 할지 확정할 수 없다면, AI도 못 합니다."
  • 필요한 정보만 반환해 토큰 효율을 높이세요.

3) 예시(few-shot) — 다양한 정준 예시

"LLM에게 예시는 천 마디 말과 같은 그림"입니다. 단, 엣지케이스를 빨래 목록처럼 나열하는 것은 안티패턴 — 컨텍스트만 부풀립니다. 기대 행동의 전 범위를 대표하는 다양하고 정준적인 예시를 소수 엄선하세요(양보다 질).

4) 검색 전략 — 저스트인타임 vs 사전 검색

  • 저스트인타임: 파일 경로·URL·쿼리 같은 가벼운 식별자만 들고, 필요할 때 도구로 로드. Claude Code가 head·tail·타깃 쿼리로 대용량 데이터를 통째로 안 읽고 다루는 방식.
  • 하이브리드(권장): 속도를 위해 일부(예: CLAUDE.md)는 미리, 나머지는 glob·grep으로 자율 탐색.
  • 점진적 공개(progressive disclosure): 탐색하며 필요한 맥락을 점진적으로 발견하고, 작업기억엔 필요한 것만 유지 — 인간의 인지와 같습니다.

긴 작업의 3대 기법

컨텍스트 창을 넘길 만큼 긴 작업에서 컨텍스트를 관리하는 세 축입니다. 이 강의에서 배운 기능들이 바로 이 기법의 구현체입니다.

기법 무엇 이 강의의 구현 적합한 작업
압축(Compaction) 히스토리를 요약해 압축본+최근 맥락으로 재시작 /compact, 자동 압축 대화 흐름이 중요한 긴 왕복
구조화 노트/에이전트 기억 외부에 노트를 쓰고 필요할 때 되불러옴 자동 기억·MEMORY.md, 투두 마일스톤이 있는 반복 개발
서브에이전트 아키텍처 전문 서브에이전트가 깨끗한 컨텍스트로 처리, 요약만 반환 서브에이전트 병렬 탐색이 유리한 복합 리서치

서브에이전트의 효율: 각 서브에이전트는 수만 토큰을 탐색해도 1,000~2,000 토큰 요약만 메인에 돌려줍니다. 관심사가 깔끔히 분리되죠. 압축의 기술: 먼저 재현율(recall)을 최대화(다 담기)한 뒤, 정밀도(불필요 제거)를 높입니다. 가장 쉬운 최적화는 오래된 도구 호출 결과를 지우는 것 — 깊은 히스토리의 원시 출력은 거의 다시 쓰이지 않습니다.


Claude Code에서의 실천

컨텍스트 엔지니어링은 추상 이론이 아니라 이미 배운 도구로 실천됩니다.

  • /context로 무엇이 어텐션 예산을 먹는지 계속 관찰.
  • /clear로 작업 전환마다 리셋, /compact <지시>로 방향 있는 압축.
  • CLAUDE.md는 짧고 적정 고도로, 가끔 필요한 건 스킬로 온디맨드.
  • 고출력 탐색은 서브에이전트로 격리해 메인 컨텍스트를 지킴.
  • 도구·MCP는 최소·명확하게 — 겹치는 도구는 판단을 흐린다.

철학: 모델이 좋아질수록 세밀한 지시가 덜 필요해지고, 에이전트에 더 많은 자율을 줄 수 있습니다. 그래도 원칙은 그대로 — "작동하는 가장 단순한 것을 하라."


핵심 요약

  • 컨텍스트 엔지니어링 = 추론마다 들어갈 고신호 토큰을 큐레이션하는 규율. 프롬프트 엔지니어링의 후계.
  • 컨텍스트는 유한한 어텐션 예산 — 채울수록 컨텍스트 로트로 성능이 완만히 하강한다. 1M을 다 채우지 마라.
  • 실천 영역: 적정 고도 시스템 프롬프트 · 최소·명확 도구 · 정준 예시 · 저스트인타임/하이브리드 검색.
  • 긴 작업은 압축·에이전트 기억·서브에이전트 3대 기법으로 — 이 강의의 /compact·자동기억·서브에이전트가 그 구현이다.
확인 퀴즈

Q1. 컨텍스트 로트(context rot)란 무엇인가요?

해설 · LLM은 유한한 어텐션 예산을 가져, 토큰이 늘수록 정확히 기억·집중하기 어려워집니다. 성능은 절벽이 아니라 완만한 하강.

Q2. 1M 토큰 컨텍스트 창을 가능한 한 가득 채우면?

해설 · 창을 다 채운다고 좋아지지 않습니다. 목표는 결과 확률을 최대화하는 '가장 작은 고신호 토큰 집합'입니다.

Q3. 긴 작업에서 컨텍스트를 관리하는 3대 기법이 아닌 것은?

해설 · 압축·구조화 노트·서브에이전트가 3대 기법입니다. 이 강의의 /compact·자동기억·서브에이전트가 그 구현입니다.
CHAPTER 13

하네스 & 루프 엔지니어링

2026년 현재, AI 에이전트를 다루는 규율은 네 계층으로 정리됩니다. 이 마지막 챕터는 그중 상위 두 계층 — 하네스 엔지니어링과 루프 엔지니어링 — 그리고 커뮤니티에서 가장 많이 쓰는 기술들을 다룹니다.

네 가지 엔지니어링 계층

각 계층은 아래 계층 위에 쌓이는 누적 스택입니다.

계층 무엇 예
프롬프트 한 번의 교환 텍스트 최적화 "너는 코드 리뷰어다" 시스템 프롬프트
컨텍스트 여러 턴의 정보 큐레이션 OpenAPI 스펙 + CLAUDE.md 규칙만, 무관 레거시 제외
하네스 에이전트를 둘러싼 전체 장치 CLAUDE.md·도구·훅·테스트·리뷰 에이전트
루프 사람 개입 없이 자동 반복 Ralph 루프, /goal 자율 실행

순서가 중요합니다. "모든 계층은 아래 계층의 약점을 물려받습니다." 나쁜 컨텍스트를 루프에 넣으면 실수가 느려지는 게 아니라 증폭됩니다 — 루프는 좋은 결정도, 실수도 함께 키웁니다. 그래서 루프 레벨에선 검증(sensors)이 결정적입니다.


하네스 엔지니어링

핵심 공식 한 줄: 에이전트 = 모델 + 하네스. Viv Trivedy의 표현대로 "당신이 모델이 아니라면, 당신이 하네스다." 원시 모델은 텍스트를 생성할 뿐이지만, 하네스가 감싸면 상태를 유지하고, 도구를 실행하고, 실패에서 배우고, 제약을 강제하는 자율 에이전트가 됩니다.

인상적인 데이터 포인트: 같은 모델(Opus)을 두고, 단순한 설정에서 돌릴 때보다 Claude Code의 정교한 하네스 안에서 Terminal Bench 점수가 극적으로 올랐다고 보고됩니다 — 순위 30위권에서 5위권으로. 모델을 바꾸지 않고 하네스만 바꿔서 말이죠. 하네스가 얼마나 load-bearing인지 보여 줍니다.

하네스의 구성요소

구성요소 이 강의의 대응
지침 파일(규칙·관례) CLAUDE.md — "60줄 이하, 각 규칙은 특정 실패에서 유래"
도구·bash 미리 만든 핸들러보다 bash·코드 실행으로 동적 조합
샌드박스·격리 안전 실험 환경 (권한·샌드박스)
컨텍스트 관리 압축·도구출력 오프로딩·점진적 공개 (컨텍스트 엔지니어링)
검증·훅 훅으로 타입체크·차단·승인 강제
관찰성 비용·지연·트레이스 추적

두 방향 — 가이드 vs 센서

  • 가이드(feedforward): 생성 전에 맥락·규칙을 준다 — CLAUDE.md, 스펙, 부트스트랩 템플릿.
  • 센서(feedback): 생성 후에 결과를 검사하고 자기수정을 트리거한다 — 린트, 레이어 분리 테스트, 요구사항 검증 리뷰 에이전트.

"Skill issue 리프레임"

하네스 엔지니어링의 태도: 에이전트의 실패를 모델 한계가 아니라 "설정 문제"로 본다. 실수가 나오면 이야기로 넘기지 말고 엔지니어링하라 — 린트 훅을 추가하고, 규칙 문서를 고치고, 검증 단계를 넣어라. 이렇게 하면 실패가 일회성 일화가 아니라 영구적 신호가 되어 하네스가 계속 좋아집니다("래칫"처럼).

하네스는 사라지지 않고 이동합니다. 모델이 좋아지면 어떤 스캐폴딩(예: 예전의 "컨텍스트 불안" 완화 장치)은 불필요해지지만, 새 실패 모드가 나타나 새 제약이 필요해집니다.


루프 엔지니어링

"나는 더 이상 Claude를 프롬프트하지 않는다. Claude를 프롬프트하는 루프를 짠다." — 이 한마디가 전환의 핵심입니다(Claude Code를 이끄는 Boris Cherny가 2026년에 밝힌 취지). 통제권이 사람에서 시스템으로 넘어갑니다.

루프 엔지니어링은 영구 지침·스킬·서브에이전트·훅을 조합해 에이전트가 스스로 반복하게 만듭니다 — 맥락 수집 → 행동 → 검증 → 자기수정 → 측정 가능한 목표에 도달할 때까지.

/goal — 가장 깔끔한 진입점

완료 조건을 한 번 입력하면, 매 턴 후 Haiku급 평가자가 트랜스크립트를 읽고 "충족됐나?"를 판정해 될 때까지 반복합니다.

Ralph 루프 (빌드-테스트-검증)

자율 코드 생성 루프의 대표 패턴입니다.

  • 훅이 모델의 종료 시도를 가로채 원래 프롬프트를 새 컨텍스트에 재주입해 계속 일하게 합니다.
  • 각 반복은 깨끗하게 시작하되, 이전 상태는 파일시스템으로 읽습니다(구조화 노트).
  • 매 단계 후 훅이 테스트 스위트를 돌리고 실패를 에러 텍스트와 함께 되먹임합니다.

Planner/Evaluator 분리

생성하는 에이전트와 채점하는 에이전트를 분리하세요. 모델은 자기 작업을 낙관적으로 채점하는 경향이 있기 때문입니다. 새 컨텍스트의 검증 서브에이전트가 diff만 보고 반박하게 하는 적대적 리뷰가 이 원리입니다.

⚠️ 루프의 위험: "무인으로 도는 루프는 무인으로 실수하는 루프이기도 합니다." 그래서 루프에는 반드시 센서(검증)를 넣고, 오토 모드(2장)의 분류기·/goal 평가자·Stop 훅으로 게이트를 겁니다.


커뮤니티 인기 기술·리소스

실무자들이 가장 많이 쓰는 오픈소스 모음입니다(GitHub).

리소스 무엇
awesome-claude-code (hesreallyhim) 스킬·에이전트·상태줄·툴링·플러그인 큐레이션의 표준 목록
awesome-claude-code-subagents (VoltAgent) 10개 카테고리 100+개 전문 서브에이전트 컬렉션
awesome-claude-skills (ComposioHQ) Claude 스킬·리소스 큐레이션
Superpowers 검증된 기법·패턴의 종합 스킬 라이브러리
andrej-karpathy-skills LLM 코딩 함정 관찰을 담은 단일 CLAUDE.md
awesome-harness-engineering (ai-boost) 하네스 엔지니어링(도구·평가·기억·MCP·권한·관찰성) 목록

많이 쓰는 실전 패턴 요약 - 서브에이전트 라이브러리: 리뷰어·테스터·보안·리팩터 등 역할별 서브에이전트를 .claude/agents/에 두고 재사용. - 관찰성 훅: 툴콜·서브에이전트 시작/종료·권한 이벤트를 훅으로 로깅해 대시보드로 관측. - 스킬 라이브러리 공유: 팀 표준 절차를 스킬/플러그인으로 배포(MCP·플러그인). - 스펙 주도 개발: Claude가 AskUserQuestion으로 인터뷰 → SPEC.md 작성 → 새 세션에서 실행(11장).

주의: 커뮤니티 자산은 외부 코드입니다. 서브에이전트·스킬·플러그인·MCP를 도입하기 전 내용을 검토하고, 신뢰할 수 있는 출처만 쓰세요.


핵심 요약

  • 네 계층: 프롬프트 → 컨텍스트 → 하네스 → 루프 (누적 스택). 위 계층은 아래의 약점을 물려받는다.
  • 하네스 = 모델 + 장치. 같은 모델도 하네스만으로 성능이 크게 달라진다. 실패는 "설정 문제"로 보고 훅·규칙·검증으로 래칫하라.
  • 루프 엔지니어링은 사람 대신 시스템이 반복하게 한다 — /goal·Ralph 루프·planner/evaluator 분리. 무인 루프엔 반드시 센서(검증).
  • 커뮤니티(awesome-claude-code·VoltAgent 서브에이전트·Superpowers 등)의 검증된 자산을 검토 후 활용하라.
확인 퀴즈

Q1. 에이전트 하네스 공식 "에이전트 = ___ + 하네스"의 빈칸은?

해설 · '에이전트 = 모델 + 하네스.' 원시 모델은 텍스트만 생성하고, 하네스가 감싸야 자율 에이전트가 됩니다.

Q2. 네 가지 엔지니어링 계층의 올바른 순서(기초→고급)는?

해설 · 프롬프트→컨텍스트→하네스→루프의 누적 스택입니다. 위 계층은 아래 계층의 약점을 물려받습니다.

Q3. 사람 개입 없이 자동 반복하는 '무인 루프'에 반드시 필요한 것은?

해설 · '무인 루프는 무인으로 실수하는 루프'이기도 합니다. 검증(센서)이 결정적이며, /goal·Stop 훅·검증 에이전트로 게이트를 겁니다.
CHAPTER 14

최신 모델 프롬프트 가이드

3장에서 본 최신 모델 — Opus 5.5·Fable 5.1·Sonnet 5.5 — 은 이전 세대보다 훨씬 똑똑하고 자율적입니다. 기존 프롬프트로도 기본 동작하지만, 더 자율적으로 오래 일하기 때문에 지시하는 방식도 진화해야 합니다.

이 챕터는 Anthropic 공식 Opus 5.5 실전 활용 플레이북("Getting the most out of Opus 5.5 in Claude and Claude Code", Addy Osmani), Sonnet 5.5 에이전트 빌딩 가이드("Building with Claude Sonnet 5.5", Addy Osmani), Sonnet 5.5 공식 프롬프트 가이드("Prompting Claude Sonnet 5.5", Anthropic Official Docs), 그리고 Fable 5.1 프롬프트 가이드("Prompting Claude Fable 5.1", Thariq Shihipar)를 바탕으로, 실무 에이전틱 코딩의 핵심 패턴과 보안 지침을 집대성했습니다.

대원칙: 모델이 발전할수록 스캐폴딩(scaffolding)을 덜어내야 합니다. 예전 모델을 밀어붙이려고 넣었던 지시(과도한 검증 강제·재확인·단계별 번호 강요)는 최신 모델에서 과잉 행동과 토큰 낭비를 낳습니다. 반면 "완료의 정의(Finish line)"와 "위험 작업 전 멈춤 지점"은 명확히 못 박아야 안전하게 오랜 시간 자율 주행할 수 있습니다.


1부: 최신 모델 공통 튜닝 패턴

1) 응답이 길어졌다 → 간결하게 지시

최신 세대의 기본 사용자 응답은 이전 세대보다 깁니다. effort는 "얼마나 생각하는지"를 조절할 뿐, "얼마나 말하는지"는 아닙니다 — effort를 낮춰도 응답 텍스트가 확실히 짧아지지 않습니다. 출력 길이는 명시적으로 프롬프트하세요.

Keep responses focused, brief, and concise. Keep disclaimers and caveats short,
and spend most of the response on the main answer. When asked to explain something,
give a high-level summary unless an in-depth explanation is specifically requested.

2) 진행 상황을 많이 내레이션한다 → 소통 케이던스 지정

에이전틱 작업 중 최신 모델은 "이제 무엇을 할지"를 자주 예고하고, 턴당 출력이 길어질 수 있습니다. 소통 방식을 명시하면 조절됩니다.

Before your first tool call, say in one sentence what you're about to do.
While working, give a brief update only when you find something important or
change direction. When you finish, lead with the outcome: your first sentence
should answer "what happened" or "what did you find," with supporting detail after.

3) 스스로 검증한다 → 과잉 검증 지시를 빼라

최신 모델은 시키지 않아도 자기 작업을 검증합니다. 프롬프트에 "비자명한 작업엔 최종 검증 단계를 넣어라", "서브에이전트로 2중 검증해라" 같은 지시가 있으면 제거하세요 — 최신 모델에선 과잉 검증 루프를 유발해 토큰만 낭비합니다.

Deliver what was asked, at the scope intended. Make routine judgment calls yourself,
and check in only when different readings of the request would lead to materially
different work. Finish the whole task, and stop short of actions that are clearly
beyond what was asked.

4) thinking을 끄면 생기는 아티팩트

Opus 5.5와 Fable 5.1은 적응형 사고(adaptive thinking)가 상시 활성화되어 있으며 끄는 옵션이 제공되지 않습니다. 구세대 모델에서 사고를 강제로 끄면 도구 호출이 텍스트로 새거나 <thinking> 태그가 노출되는 문제가 발생합니다. 사고를 끄려고 하지 말고, 비용 절감이 필요하면 low 또는 medium effort를 사용하는 것이 정석입니다.


2부: Claude Opus 5.5 실전 활용 플레이북

Anthropic이 2026년 9월 22일 발표한 Claude Opus 5.5(claude-opus-5-5)는 이전 세대보다 혼자서 훨씬 더 오래 일하고, 자신이 수행한 작업을 담백하게 보고하며, 매 응답 전 스스로 생각합니다.

첫 세션에서 시도할 3가지 핵심

  1. 작업 전체를 한 번에 넘겨라: "완료된 모습(Done)"이 무엇인지, 언제 멈춰서 질문해야 하는지 한 번에 말하고 그대로 작업을 맡기세요.
  2. "깊이 생각해라" 문구를 삭제하라: Opus 5.5는 이미 매 응답 전 최적의 깊이로 생각합니다. "think carefully"를 지우면 답변이 더 빨리 시작됩니다.
  3. 작업이 끝나면 나에게 필요한 요구사항을 먼저 읽어라: Opus 5.5는 자신이 내린 결정과 사람의 승인이 필요한 항목을 명확히 구분해 보고합니다.

1. 프롬프트 작성법 (How to Ask)

① 완료의 기준(Finish Line)을 못 박고 맡겨라

Opus 5.5는 이전 Opus 5보다 다단계 작업(대규모 리포지토리 마이그레이션 등)을 훨씬 더 끈기 있게 이어갑니다. "끝이 어디인지"를 명확히 주면 몇 시간 동안 자율적으로 작업합니다.

# 실전 프롬프트: 결제 엔드포인트 마이그레이션
Migrate the payment endpoints from the old client to the new one.
Done means: every endpoint uses the new client, the old client is
deleted, and the test suite passes.
Stop and ask me only if a test fails for a reason you can't explain.
  • 전체 과업: 구 클라이언트에서 신규 클라이언트로 결제 엔드포인트 마이그레이션.
  • 완료의 정의 (Done): 모든 엔드포인트가 신규 클라이언트를 사용하고, 구 클라이언트 파일이 삭제되며, 전체 테스트가 통과할 것.
  • 멈춤 조건: 설명할 수 없는 이유로 테스트가 실패할 때만 멈추고 질문할 것.

② "think hard" 지시문 제거

"think carefully", "think step by step" 등의 프롬프트는 모두 삭제하세요. Opus 5.5는 자체적으로 생각의 양을 결정합니다. 빠른 답변이 필요하다면 "Answer directly"라고 짧게 지시하거나 effort를 low로 낮추세요.

③ 실행 중인 작업에 실시간 지시 추가 (Add to a running task)

Opus 5.5는 긴 시간 동안 도구를 연속 실행합니다. 도중에 빠뜨린 요구사항이 생각났다면 작업을 취소하고 처음부터 다시 시작할 필요 없이, 작업이 돌아가는 도중에 터미널에 메시지를 입력하고 Enter를 누르세요. - 예: 작업 도중 Also keep the old endpoint names as aliases. 입력.

④ 디자인 요청 시 "원하지 않는 스타일"을 명시 (Negative Styling Constraints)

스타일 지침이 없으면 Opus 5.5는 무난한 기본 템플릿(크림색 배경, 이탤릭 헤딩, 알약 모양 버튼 등)으로 회귀합니다. "일반적인 느낌을 피해라" 같은 막연한 지시 대신, 원하지 않는 스타일 요소를 구체적으로 나열하세요.

Build a personal website with placeholder content.
Don't use a cream or off-white background, italic accent words in
headings, numbered "01 / 02 / 03" section labels, monospace labels, or
pill-shaped buttons.

2. Claude Code에서 장기 실행 세션 조종 (Steering a Long Run)

① CLAUDE.md에 멈출 지점(Stops)을 명시하라

Opus 5.5는 보고를 매우 잘합니다. 하지만 지침이 없으면 사소한 판단마다 멈춰서 "계속할까요?"라고 묻거나 불필요한 선택지를 나열할 수 있습니다. CLAUDE.md에 연속 진행과 정지 조건을 명시하세요.

<!-- CLAUDE.md 권장 규칙 -->
When a step doesn't need my input, keep going. Put status notes in the
same message as your next action.
Stop and ask only when you can't continue without me, or before anything
destructive: deleting data, force-pushing, or changing anything outside
this repository.

⚠️ 보안 원칙: 멈춤 없이 계속 진행하게 할수록, 파괴적 작업(rm -rf, git push --force, 외부 디렉터리 접근)에 대한 사전 확인 및 Claude Code의 도구 권한 프롬프트는 반드시 켜 두어야 합니다.

② 대규모 작업은 서브에이전트에 분산 후 "증거"를 검증하라

전체 서비스 감사(audit)나 대규모 마이그레이션 시, Opus 5.5에게 작업을 여러 서브에이전트로 나누고 각 결과를 병합 전 교차 검증하도록 지시하세요.

Audit every service in services/ for the retry bug in the linked issue.
Give each service to its own subagent. When a subagent reports back,
check its evidence before you accept it.
Finish with one table: service, affected yes or no, and the evidence.

③ 작업 목록을 파일(TASKS.md)로 유지하라

긴 세션에서는 대화 컨텍스트가 가득 차면 Claude Code가 이전 턴을 자동 요약(compaction)합니다. 작업 진행 상태를 터미널 대화에만 의존하면 히스토리가 요약될 때 세부 사항이 흐려질 수 있습니다. - 지시: "Keep a checklist in TASKS.md. Tick each item when it's done, and add anything new you find." - 파일에 기록된 체크리스트는 컨텍스트 압축 후에도 디스크에 온전히 유지되어 현재 위치를 한눈에 파악할 수 있습니다.


3. 결과 확인 및 품질 점검 (Checking the Result)

① "나에게 필요한 요구사항"을 가장 먼저 읽어라

장기 작업이 끝나면 최종 요약에서 Claude가 사람의 결정이나 승인을 기다리는 항목(Blocked on me)을 가장 먼저 확인하세요. - CLAUDE.md 서식 팁: "End every run with three headings: Blocked on me, Changed, Found."

② 머지 전 Opus 5.5에게 사전 코드 리뷰 요청

Opus 5.5는 낮은 effort에서도 이전 Opus 5의 높은 effort보다 더 많은 버그를 적은 오탐(false positive)으로 잡아냅니다. 사람이 PR을 검토하기 전 먼저 돌려보세요.

Review the diff on this branch against main.
List only problems you'd block the merge for. For each one, give the
file and line, why it's wrong, and how to show it fails.

③ 확인하지 못한 부분을 명시하도록 지시

조사 및 분석 작업 시 확인되지 않은 가설을 단정 짓지 않도록 명시적 단서를 붙이세요: - "Mark anything you couldn't confirm, and say where you looked."


4. Claude 애플리케이션 및 협업 팁

  • 스크린샷/차트 원본 직접 첨부: 수치를 텍스트로 옮겨 적지 말고 다이어그램이나 스크린샷 이미지를 그대로 전달하세요. 화살표 연결 관계, 두 다이어그램 간 변경점, 캘린더 일정 위치 등 공간 정보를 탁월하게 해석합니다.
  • 문서 자기모순 검출: 긴 기획서나 슬라이드 덱 검토 시 "문서 내에서 날짜·숫자·이름이 서로 모순되는 부분을 찾아 인용하고 위치를 밝혀라"고 지시하세요.
  • 완성형 파일 직접 요구: 개요(outline) 대신 바로 공유할 수 있는 완성된 스프레드시트나 정식 문서를 요구하세요.
  • 긴 프로젝트 대화에서 이전 답변 확정 선언: 장기 프로젝트에서 사소한 후속 질문 시 이전 답변을 불필요하게 재검토하며 느려지는 것을 방지하려면 지침을 추가하세요: text Once you have answered something, treat that answer as done. Focus on what I'm asking now, and don't go back over an earlier answer unless I ask about it or point out a problem with it.

5. 보안 가드레일 및 메시지 플래그 대응

Opus 5.5는 Fable 수준의 첨단 생물학·사이버보안 가드레일을 기본 탑재했습니다.

  1. 메시지 플래그 시 자동 모델 폴백: 민감한 보안 키워드나 오탐으로 인해 메시지가 플래그되면, 작업이 튕겨 나가는 대신 이전 세대 안전 모델로 세션이 자동 전환되어 연속성을 보장합니다.
  2. 복구 절차:
  3. 원래 모델 복귀: /model opus-5-5
  4. 직전 메시지 수정: Esc 키를 두 번 눌러 프롬프트 편집 후 재전송
  5. 자동 전환 여부 제어: /config에서 Switch models when a message is flagged 옵션 조정
  6. ⚠️ 내부 추론 과정(Internal Reasoning) 출력 요구 금지:
  7. "내부 추론 과정을 그대로 보여달라"는 식의 시스템 내부 사고 추출 요청은 보안상 거부되며 플래그의 주요 원인이 됩니다.
  8. 대안: "이 방식을 선택한 이유를 3문장으로 간결하게 설명해 달라"와 같이 명시적 산출물 설명을 요구하세요.

Opus 5.5 실전 체크리스트

[ ] 1. 지시하기 (Asking)
    - 작업의 최종 완료 모습(Done)을 명시했는가?
    - "think hard", "think carefully" 같은 불필요한 수식어를 제거했는가?
    - 디자인 요청 시 원하지 않는 스타일(배경색, 폰트 등)을 나열했는가?
    - 차트와 다이어그램은 텍스트 재입력 대신 이미지 원본을 첨부했는가?

[ ] 2. 긴 세션 조종 (Steering)
    - CLAUDE.md에 불필요한 정지를 막고 파괴적 명령(삭제, force-push) 전에만 멈추도록 설정했는가?
    - 파괴적 도구 권한 프롬프트는 켜 두었는가?
    - 대규모 감사·마이그레이션 과제는 서브에이전트로 분산하고 증거를 요구했는가?
    - 진행 상황 추적을 위한 TASKS.md 체크리스트 파일 생성을 지시했는가?

[ ] 3. 결과 점검 (Checking)
    - 최종 보고서에서 'Blocked on me(내 승인이 필요한 사항)'를 가장 먼저 확인했는가?
    - 머지 전 Opus 5.5에게 머지 블로커 기준 diff 리뷰를 수행하게 했는가?
    - 조사 리포트에서 '확인하지 못한 내용과 검색 위치'를 표기하도록 했는가?

[ ] 4. 보안 및 플래그 (Flags)
    - 플래그 발생 시 /model 또는 Esc 2회 수정을 통해 복구하는 법을 숙지했는가?
    - 내부 reasoning을 출력하라는 무리한 지시를 배제했는가?

3부: Claude Sonnet 5.5 공식 프롬프트 가이드 (Anthropic Official)

Anthropic 공식 엔지니어링 문서인 "Prompting Claude Sonnet 5.5"는 Sonnet 5.5 모델 전용의 10대 실전 프롬프팅 패턴과 API 제약 회피 기법을 규정하고 있습니다. 기존 Sonnet 5 프롬프트도 기본 작동하지만, Sonnet 5.5의 재보정된 추론 강도(effort)와 자율성 특성을 이해하고 지시해야 성능과 비용 효율을 극대화할 수 있습니다.

1) Effort 재조정과 출력 토큰 한도 (Calibrate Effort)

  • Effort 레벨 재보정: Sonnet 5.5의 effort 레벨은 Sonnet 5와 동일한 사고량을 의미하지 않습니다. 기존 설정을 그대로 이관하지 말고 재평가해야 합니다.
  • API 기본값: high
  • 에이전틱 코딩 & 다단계 도구: 명세가 명확한 일상 작업은 medium에서 시작하고, 어렵거나 긴 작업은 high로 상향 권장.
  • 대화형 챗봇/지연 민감 작업: medium 또는 low에서 시작 (high 이상은 첫 토큰 생성 전 thinking으로 인해 대기 시간이 길어짐).
  • max_tokens 128,000 최대치 설정:
  • max_tokens 예산은 클라이언트에 반환되지 않는 내부 thinking 토큰까지 합산하여 차감됩니다. thinking 없는 모델 기준의 작은 한도를 두면 응답 중간에 잘립니다.
  • 코딩 세션에서는 반드시 모델 최대치인 max_tokens: 128000으로 설정하고 스트리밍(streaming)하세요.
  • output_config.effort(beta)로 프롬프트 캐시 보존:
  • 요청의 최상위 effort 값을 변경하면 시스템 프롬프트 캐시가 무효화됩니다.
  • 턴별로 추론 강도를 바꾸려면 메시지 단위 effort 변경(per-message effort change, beta)을 사용하세요. (예: 일반 대화는 low로 유지하다가 어려운 코딩 문제가 들어올 때 해당 턴만 high로 상향). 단, 이 기능은 적응형 사고(adaptive thinking)에서만 지원되며 between_tools 설정 시 400 에러를 반환합니다.

2) 자율성과 작업 범위 제어 (Steer Initiative & Scope)

Sonnet 5.5의 행동 반경은 effort 수준과 프롬프트 지시에 민감하게 반응합니다: - 조기 중단 방지 (low/medium): 낮은 effort에서는 다단계 작업 도중 불필요하게 멈춰서 계획을 확인하려 하거나 계속할지 묻는 경향이 있습니다. 다음 시스템 프롬프트로 끝까지 완수하도록 조종하세요: text Keep working until everything the user asked for is done, and only stop to ask when you can't go on without the user or before a risky step. When the work the user asked for is done and checked, stop and report. Don't add features, tests, files, docs or refactors that weren't asked for. If you think one would help, mention it at the end instead of doing it. - 요청하지 않은 추가 작업 방지: Sonnet 5.5는 코드 변경 시 저장소 관례에 맞게 테스트, 문서, 지원 파일을 알아서 추가하는 성향이 강합니다. 요청된 부분만 수정하길 원한다면 위 프롬프트의 뒷부분(When the work the user asked for is done...)만 시스템 프롬프트에 주입하세요. - xhigh/max에서 무한 자체 리뷰 루프 방지: 최상위 effort에서는 과업 완료 후 스스로 코드 리뷰와 하드닝을 시작하거나 서브에이전트를 띄워 검토를 반복하며 토큰을 소모합니다. 다음 지침을 주입하면 서브에이전트 남발을 막고 비용을 약 30% 절감할 수 있습니다: text When the work the user asked for is done and its checks pass, stop and report. Don't start extra rounds of review or hardening on your own, and don't launch reviewer sub-agents unless the user asked for a review. If you think a deeper review is worth doing, say so at the end. - 아이디어/기획 요청 시 산출물 빌드 방지: "이걸로 뭘 할 수 있는지 보여줘" 같은 열린 요청에서 모델이 즉시 앱이나 리포트를 제작하는 것을 방지합니다: text When the user asks for ideas, options or a plan, give them that and stop. Don't start building or changing anything until they say to go ahead.

3) 선행 사고 없는 실행 (between_tools와 제약사항)

  • Sonnet 5.5에서 첫 턴의 선행 사고 없이 즉시 응답하려면 thinking: {"type": "between_tools"}를 전송합니다.
  • ⚠️ 핵심 제약:
  • between_tools는 high 이하 effort에서만 허용됩니다. xhigh나 max에서 전송하면 HTTP 400 Bad Request 에러가 발생합니다.
  • "생각하지 말라(do not think)"는 프롬프트 지시는 제거해야 합니다. 모델이 보이는 출력에 내부 <thinking> XML 태그를 누출할 위험이 커집니다.
  • 도구 호출 사이에 모델이 작성한 중간 메모는 thinking 블록으로 수신되므로, 다음 턴에 원본 그대로 다시 전달(Append-only)해야 합니다.

4) 정형 JSON 출력과 추론 태스크 (Reasoning with JSON)

문서 수치 집계, 규칙 적용, 순위 매기기 등 계산/추론이 필요한 태스크에서 JSON 출력을 요구할 때: - 구조화된 출력(Structured Outputs) 사용 시: - 본문에는 스키마에 맞는 JSON만 들어가므로 모델은 오직 thinking 블록 내에서만 문제를 풀 수 있습니다. - low/medium에서는 추론을 건너뛰고 오답을 낼 수 있으므로 시스템 프롬프트 끝에 반드시 한 줄을 추가하세요: text Think the problem through before you answer. - stop_reason: "max_tokens"가 떨어지면 JSON이 유효해 보여도 실패로 간주하고 재시도하세요. - 자유 형식(Free-form) 프롬프트로 JSON을 요청할 때: - 모델이 본문에서 풀이 과정을 서술한 뒤 마지막에 JSON을 작성하므로, 전체 응답을 파싱하려 하면 실패합니다. - 파싱 원칙: { 또는 [로 시작하는 JSON 블록을 탐색하고, 가장 마지막에 완성된 JSON 블록만 추출하여 파싱하세요.

5) 사용자 진행 상황 실시간 업데이트 (Progress Updates)

  • 도구 호출 사이의 메모를 실시간으로 보여주려면 display: "updates" 헤더(thinking-display-updates-2026-08-18)를 지정하세요.
  • 긴 도구 체인에서 5턴 이상 침묵이 이어질 경우, 하네스가 일회성 턴 스코프 메시지를 주입합니다: text The user hasn't heard from you in a while — say in a few words what you're doing, then continue.
  • "도구 사용을 최소화하라"는 구형 지침을 삭제하세요.
  • 최신 규정, 요금, 지원 여부 등 지식 컷오프 이후 변경될 수 있는 내용은 내부 학습 지식 대신 검색 도구를 강제하세요: text Use the search tool to check specifics that may have changed since your training, such as what is allowed, required or charged, even when you feel confident. For researched work such as a report or a comparison, gather current sources rather than writing from your training knowledge.

7) 미드턴 사용자 메시지와 간접 인젝션 방어 (Mid-turn Messages)

Sonnet 5.5는 도구 결과나 파일 내용으로 침투하는 간접 프롬프트 인젝션(indirect prompt injection)을 강력히 방어하도록 훈련되었습니다. 잘못된 하네스 구조는 진짜 사용자의 메시지를 인젝션 공격으로 오탐하게 만듭니다. - 🚨 절대 tool_result 블록 내부에 사용자 텍스트를 넣지 마세요. - 사용자의 피드백은 반드시 도구 결과 블록이 모두 끝난 뒤 별도의 text 블록으로 메시지 끝에 추가(Append)해야 합니다. - 매 도구 호출마다 토큰 카운트다운이나 하네스 공지 텍스트를 삽입하지 마세요.

8) 코딩 실검증 강제 지침 (Verification on Coding Tasks)

Sonnet 5.5는 기본적으로 자체 검증을 수행하지만, low effort에서는 "의존성이 설치되지 않았다"는 등의 이유로 빌드나 테스트 실행을 건너뛸 수 있습니다. 다음 검증 강제 지침을 시스템 프롬프트에 추가하세요:

When you change code that can be run, built, or type-checked, run a real check that exercises the change before reporting it done: the project's tests, type-checker, or build, or the changed command itself. A syntax-only check, or a check command that failed to start, does not count; if all that is missing is the project's declared dependencies, install them with its own package manager and lockfile (e.g. npm install, pip install -r requirements.txt), never via sudo or the system package manager, unless told not to. Only if no real check can run here, say which one you did not run and why instead of reporting the change as done.

9) 관용적 도구 호출 처리 (Tolerant Tool-Call Handling)

  • Sonnet 5.5가 Bash 대신 bash로 대소문자를 다르게 호출하거나 매개변수 이름을 유사하게 넘길 때, 에러로 중단하지 마세요.
  • 하네스에서 명백한 매칭은 관용적으로 수용하거나, tool_result에 is_error: true와 함께 정확한 규격명을 안내하여 자체 교정(self-correction)을 유도하세요.

10) 복합 시각 입력 & 5대 안전 거부(Safeguard Refusals) 대응

  • 차트 및 기술 도면: effort를 올리는 것보다 이미지의 특정 영역을 자르고 확대하는 Crop/Zoom 도구를 제공하는 것이 비용을 절감하면서 판독 정확도를 비약적으로 높입니다.
  • 5대 안전 거부 카테고리(stop_details.category):
  • cyber: 악성코드 및 익스플로잇 개발 등 사이버 위협.
  • bio: 위험 생물학적 기법. (생명과학 검증 프로그램 신청 가능).
  • frontier_llm: 경쟁 AI 모델 개발 지원.
  • reasoning_extraction: 내부 추론 과정(internal reasoning) 복제 요구.
  • general_harms: 기타 사용 정책 위반.
  • 💡 주의: 시스템 프롬프트에서 모델의 내부 사고 과정을 응답에 포함하라는 지시는 reasoning_extraction 거부를 유발하므로 절대 작성하지 마세요.

4부: Claude Fable 5.1 & Mythos 5.1 공식 실전 가이드

2026년 9월 출시된 Claude Fable 5.1(claude-fable-5-1)은 엔터프라이즈 프런티어급 지능과 초저가 캐시 읽기($0.25/M)를 갖춘 장기 자율 에이전트 전용 모델입니다. 자매 모델인 Claude Mythos 5.1은 동일 아키텍처 기반에 보안 허가 조직(Project Glasswing)을 위한 완화된 가드레일을 제공합니다.

1) Multi-Effort 지출 전략과 Terminal-Bench 3.0 연구

Anthropic 엔지니어링 분석(Thariq Shihipar)에 따르면, Fable 5.1은 태스크 난이도와 엣지케이스의 유무에 따라 effort를 전략적으로 배분해야 비용 효율이 극대화됩니다.

  • html-js-filter 사례 연구:
  • low effort (약 2분 소요): 1회의 단일 패스로 필터를 작성하고 단일 테스트 페이지만 확인 → 5회 중 1회만 성공.
  • xhigh effort (약 33분 소요): 작성한 초안을 스스로 적대적(adversarial) 검토 → 설치된 HTML 파서 라이브러리의 소스코드를 직접 읽어 버그 확인 → 수많은 입력-출력 무결성 테스트 실행 → 표준 XSS 테스트 스위트 통과 → 무작위 문서 퍼저(fuzzer)를 직접 작성해 엣지케이스 전수 검증 → 5회 모두 완벽 통과.
  • 실무 4단계 기능 개발 루프:
  • 명세를 주고 누락된 부분을 질문하도록 인터뷰 유도
  • low effort로 핵심 코드베이스 구현
  • low effort로 피드백을 주며 프로토타입 반복
  • high 또는 xhigh effort로 엣지케이스 테스트 및 보안 감사

2) 독립 도구 호출의 단일 턴 병렬 배치 넛지

Fable 5.1은 독립적인 파일 읽기나 검색 도구를 순차적으로 1개씩 호출하는 경향이 있습니다. 아래 넛지를 주입해 한 턴에 병렬 호출하도록 유도하세요:

First privately list what you need next; then request every item that doesn't depend
on another's result in this one response.

3) 대화 기록은 반드시 엄격한 추가 전용(Append-only) 유지

⚠️ 가장 중요한 캐시 & 모델 제약사항: Fable 5.1의 thinking 블록은 해당 블록이 생성된 정확한 대화 컨텍스트에서만 유효합니다. - 이전 턴의 사용자 메시지나 도구 호출 결과를 임의로 편집·삭제하면 프롬프트 캐시가 무효화될 뿐만 아니라, 그 뒤에 오는 모든 thinking 블록이 거부됩니다. - 새로운 지시나 넛지는 과거 턴을 수정하지 말고 반드시 대화 끝에 새 메시지로 추가(Append)해야 합니다.

4) 전체 파일 재작성 대신 타겟 편집 강제

방대한 파일에서 몇 줄만 고칠 때도 파일 전체를 덮어쓰는 경향을 방지하세요:

Make targeted edits to existing files rather than rewriting the entire file.
Keep unchanged code and comments intact.

5) 사용자 진행 업데이트 수신

Fable 5.1은 긴 도구 호출 체인 동안 침묵할 수 있습니다. API 레벨에서 display: "updates" 헤더를 사용하고, 아래 프롬프트를 함께 제공하세요:

Before you start, say in a line what you're about to do; brief updates while you work
help the user follow along. Close with a short recap that stands on its own.

5부: 세대별 마이그레이션 노트

Sonnet 5 → Sonnet 5.5 마이그레이션

  • 모델 ID: claude-sonnet-5 → claude-sonnet-5-5
  • 속도 및 성능 도약: 30%+ 빠른 생성 속도, Terminal-Bench 4.0 70.6%(기존 10.3% 대비 비약적 발전)로 일상적인 기능 구현과 버그 수정을 최고 속도로 완결.
  • 실무 비용 절감: 기본 요율($2/$10)은 동일하나 토큰 소모 효율 향상으로 작업당 최대 30% 비용 절감.
  • Thinking 설정 변경: thinking: {"type": "disabled"} 대신 thinking: {"type": "between_tools"} 강제.
  • API 제약 준수: 강제 tool_choice(any/tool) 금지(HTTP 400 반환), 레거시 computer_20251124 배제.
  • 암호학적 계정 바인딩: Thinking 블록의 다중 테넌트 간 공유/재전송 금지.

Opus 5 → Opus 5.5 마이그레이션

  • 모델 ID: claude-opus-5 → claude-opus-5-5
  • 단가 인하: 입력 $4/M, 출력 $20/M, 캐시 읽기 $0.20/M (실제 세션 비용 약 40% 절감).
  • 소통 개선: "think carefully"를 제거하고, CLAUDE.md에 비차단 작업의 연속 진행 규칙을 등록하세요.
  • 안전 가드레일: Fable급 보안 탑재. 메시지 플래그 시 자동 모델 폴백 대응 숙지.

Fable 5 → Fable 5.1 마이그레이션

  • 모델 ID: claude-fable-5 → claude-fable-5-1
  • 캐시 읽기 단가 75% 인하: $1.00/M → $0.25/M (에이전틱 반복 세션 비용 급감).
  • 컨텍스트 무결성: 과거 턴 수정을 금지하고 Append-only 메시지 파이프라인 준수.
  • 지식 컷오프: 2026년 6월.

핵심 요약

  • Sonnet 5.5 공식 프롬프트 가이드 (Anthropic Official):
  • 추론 강도 재조정: 에이전틱 코딩은 medium에서 시작 권장, max_tokens는 thinking을 포함하므로 128,000 설정.
  • 자율성 제어: low/medium에서는 조기 중단 방지 프롬프트, xhigh/max에서는 불필요한 자체 리뷰 및 서브에이전트 남발 방지 프롬프트 주입.
  • 즉각 실행 제약: 선행 사고 끄기는 thinking: {"type": "between_tools"}(high 이하만 유효, 400 방지).
  • JSON 태스크: 구조화 출력 시 "Think the problem through before you answer" 추가, 자유 형식 시 마지막 JSON 블록 파싱.
  • 간접 인젝션 방어: tool_result 내부에 사용자 텍스트 삽입 절대 금지, 별도 text 블록으로 Append.
  • 코딩 실검증 강제: 의존성 미비 핑계 방지 및 실제 빌드/테스트 수행 명령 프롬프트 주입.
  • Opus 5.5 핵심 플레이북:
  • 완료 기준(Done)을 명시하고 전체 과업을 한 번에 위임.
  • "think hard" 지시를 프롬프트에서 삭제 (적응형 사고 상시 가동).
  • CLAUDE.md로 비파괴 작업은 멈춤 없이 계속 진행하도록 조종.
  • 대규모 작업은 서브에이전트 병렬화 후 증거(evidence)를 검증.
  • 컨텍스트 압축에 대비해 작업 상태는 TASKS.md 파일로 관리.
  • 사람 검토 전 PR 머지 블로커 코드 리뷰를 선행.
  • Fable 5.1 핵심 가이드:
  • Terminal-Bench 3.0 실증 연구에 기반한 4단계 Multi-Effort 개발 루프 도입.
  • 독립 도구 호출 병렬 배치 넛지 제공.
  • thinking 블록 유효성을 위한 대화 히스토리 Append-only 준수.
  • 보안 및 가드레일:
  • 생물학/사이버 가드레일 플래그 시 안전 모델로 자동 폴백.
  • 시스템 내부 추론 과정(internal reasoning) 직접 출력 요구 금지 (reasoning_extraction 거부 차단).

💡 직접 프롬프트를 진단해 보세요: 16장 플레이그라운드의 프롬프트 튜너에 내 프롬프트를 입력하면, Opus 5.5 완료 기준 정의, Sonnet 5.5 고속 반복 설정, Fable 5.1 병렬 호출 넛지 등 실전 지침에 맞춰 최적화된 프롬프트를 추천합니다.

확인 퀴즈

Q1. 최신 모델(Opus 5.5 등)에서, 예전 프롬프트의 '최종 검증 단계를 넣어라' 같은 지시는?

해설 · 최신 모델은 시키지 않아도 자기 작업을 검증합니다. 검증 강제 지시는 과잉 검증을 유발해 토큰만 낭비하므로 빼는 게 낫습니다.

Q2. Opus 5.5의 길어진 응답(장황함)을 줄이는 올바른 방법은?

해설 · effort는 '얼마나 생각하는지'를 조절할 뿐 응답 길이가 아닙니다. 길이는 명시적 지시로 조절하세요.

Q3. Opus 5.5에서 'think carefully'나 'think step by step' 같은 지시문은?

해설 · Opus 5.5는 적응형 사고가 매 응답 전 스스로 작동하므로 'think carefully'를 지우면 품질 저하 없이 답변이 더 빨리 시작됩니다.
CHAPTER 15

터미널 밖의 Claude Code

지금까지는 터미널 안의 Claude Code였습니다. 그런데 같은 엔진이 IDE·데스크톱 앱·브라우저·폰·클라우드에서도 돕니다. 이 챕터는 "어디서 돌릴 것인가"를 정리합니다 — 내 컴퓨터에서 돌리되 다른 기기로 이어받을지, 아예 클라우드에서 돌릴지, 결과를 어떻게 남에게 보여 줄지.


통합 — IDE · GitHub · Slack · 데스크톱 · 모바일

명령 하는 일
/ide VS Code·JetBrains IDE 통합 관리
/install-github-app Claude GitHub App 설치(PR 자동 리뷰 등)
/install-slack-app Claude Slack 앱 설치
/desktop 데스크톱 앱으로 이어가기
/mobile 모바일 앱 연결용 QR 표시
/chrome Chrome 확장 연결(브라우저 자동화)

Claude Code는 CLI·데스크톱 앱(Mac/Win/Linux)·웹·IDE 확장 어디서나 같은 엔진으로 동작합니다. GUI를 선호하면 데스크톱 앱으로 터미널 없이도 쓸 수 있습니다.

Chrome 연동은 "코드를 고치고 → 브라우저에서 확인"을 한 세션 안에서 잇습니다. Claude in Chrome 확장을 붙이면 콘솔 에러·DOM을 직접 읽어 원인 코드를 고치고, UI가 시안대로 나왔는지 열어서 확인하고, 폼 검증·사용자 흐름을 눌러 봅니다. 여러분의 로그인 상태를 그대로 쓰므로 이미 로그인한 사이트(Notion·Gmail 등)에 커넥터 없이 접근하고, 로그인 화면이나 CAPTCHA를 만나면 멈추고 사람에게 넘깁니다. Chrome·Edge에서 동작하고 Brave·Arc 같은 크로미움 계열도 감지하지만, WSL에서는 지원하지 않습니다.



Remote Control — 폰·브라우저로 내 컴퓨터의 세션 이어가기

책상에서 시작한 작업을 소파에서 폰으로, 또는 다른 컴퓨터의 브라우저로 이어받는 기능입니다(리서치 프리뷰). 핵심은 세션이 계속 내 컴퓨터에서 돈다는 것 — 폰·웹은 그 로컬 세션을 들여다보는 창일 뿐이라 파일시스템·MCP 서버·프로젝트 설정이 그대로 살아 있습니다.

claude remote-control          # 서버 모드 — 접속을 기다리며 세션 URL·QR 표시(스페이스바)
claude --remote-control        # 평소 인터랙티브 세션에 원격 접속만 켜기 (--rc)
/remote-control                # 세션 도중에 켜기 (VS Code 확장도 이 명령)

접속은 세션 URL 열기 / QR 스캔 / claude.ai/code·모바일 앱의 세션 목록에서 이름으로 찾기 셋 중 하나입니다. 터미널·브라우저·폰에서 동시에 메시지를 보낼 수 있고 서브에이전트·워크플로 진행 상황도 함께 동기화됩니다. 노트북이 잠들거나 네트워크가 끊겨도 돌아오면 자동 재연결하고, 그동안 밀린 알림을 몰아서 전달합니다.

구분 Remote Control Claude Code on the web (아래 절)
세션이 도는 곳 내 컴퓨터 Anthropic이 관리하는 클라우드 VM
로컬 파일·MCP·설정 그대로 사용 사용 불가(저장소를 클론)
언제 쓰나 하던 로컬 작업을 다른 기기에서 이어갈 때 로컬 준비 없이 바로 시작하거나, 안 받아 둔 저장소·병렬 작업

알아 둘 제약이 몇 가지 있습니다. - 로컬 프로세스가 살아 있어야 합니다. 터미널을 닫으면 세션은 오프라인이 됩니다. SSH로 붙은 원격 머신이라면 tmux·screen 안에서 띄우세요. - API 키로는 안 되고 구독(Pro·Max·Team·Enterprise) 로그인이 필요합니다. Bedrock·Google Cloud·Foundry에서는 쓸 수 없고, ANTHROPIC_BASE_URL이 api.anthropic.com이 아닌 곳을 가리켜도 꺼집니다. - DISABLE_TELEMETRY·DO_NOT_TRACK 등을 켜 두면 조용히 못 씁니다 — 기능 플래그 평가가 막혀서입니다. 원인을 짚기 어려운 실패이니 기억해 두세요. - 일부 명령은 로컬 전용입니다(/plugin·/resume 등). 폰·웹에서는 /model sonnet·/effort high처럼 값을 인수로 붙여 씁니다(피커가 없으므로). - 처음 쓰는 프로젝트라면 그 디렉터리에서 claude를 한 번 실행해 신뢰 대화를 통과시켜 두어야 합니다. 홈 디렉터리에서는 신뢰가 저장되지 않습니다.

모바일 푸시 알림은 Remote Control이 켜져 있을 때 동작합니다. 긴 작업이 끝나거나 결정이 필요할 때 Claude가 알아서 보내고, 프롬프트에 테스트 끝나면 알려줘처럼 요청할 수도 있습니다.



아티팩트 — 세션 산출물을 볼 수 있는 페이지로

터미널 텍스트가 매체로 안 맞는 결과물이 있습니다. 주석 단 diff, 대시보드, 나란히 놓고 고르는 선택지, 긴 작업 동안 채워지는 조사 타임라인 같은 것들 — 읽는 것보다 보는 게 빠른 출력입니다. 아티팩트는 이런 결과물을 claude.ai의 비공개 URL에 살아 있는 페이지로 발행하고, 세션이 계속되면 그 자리에서 갱신됩니다. 링크를 공유하면 남도 볼 수 있습니다.

이 PR을 diff에 주석을 달아 훑어 주는 아티팩트를 만들어 줘.
지난주 배포 실패를 서비스별 대시보드 아티팩트로 만들고, 조사하면서 계속 갱신해 줘.

Claude가 프로젝트에 HTML(또는 마크다운) 파일을 쓴 뒤 발행하며, 새 아티팩트를 처음 발행할 때는 허락을 구합니다(이미 승인한 것을 다시 발행할 때는 안 묻습니다).

아티팩트는 앱이 아닙니다. 백엔드 없는 자체 완결 페이지 한 장이라 폼 입력을 저장하거나 여러 경로를 서비스할 수 없고, 외부 요청도 막혀 있습니다(CSS·JS는 인라인, 이미지는 data URI, 예외는 Google Fonts와 MCP 커넥터 호출뿐). 백엔드가 필요한 사내 도구라면 직접 배포하세요. 또 스타일 입힌 페이지는 같은 내용의 터미널 출력보다 출력 토큰을 많이 씁니다 — 특히 data URI로 박은 이미지가 그렇습니다. 쓰려면 claude.ai 계정 로그인(/login)이 필요합니다 — API 키·게이트웨이 토큰·클라우드 제공자 자격증명 세션은 발행할 수 없고, Bedrock·GCP·Foundry에서도 안 됩니다.



Claude Code on the web · 클라우드 세션 · 예약 실행

  • 웹/클라우드 세션: Anthropic이 관리하는 격리 VM에서 세션을 돌릴 수 있습니다. 저장소를 클론해 원격에서 작업.
  • 루틴(routines)·예약 작업: 크론처럼 예약된 클라우드 에이전트를 돌려 "매일 밤 배포 점검" 같은 반복 작업을 자동화.
  • 데스크톱 예약 작업은 로컬 머신에서 돌아, ~/.claude/skills/의 개인 스킬을 그대로 씁니다(클라우드 세션은 저장소에 커밋된 스킬만).

주의: 클라우드/웹 세션은 로컬 ~/.claude/skills/ 를 읽지 않습니다. 개인 스킬을 원격에서 쓰려면 저장소 .claude/skills/에 커밋하거나 플러그인으로 배포하세요.



자동화·프로그래밍

  • 헤드리스(비대화) 모드: claude -p "프롬프트" — CI·pre-commit·스크립트에 통합. --output-format json으로 파싱, --allowedTools로 권한 제한(11장).
  • Claude Agent SDK: Claude Code를 라이브러리로 패키징한 것(@anthropic-ai/claude-agent-sdk / claude-agent-sdk). 내장 도구·에이전트 루프·컨텍스트 관리·훅·서브에이전트를 그대로 코드에서 씁니다. 자체 인프라에 에이전트를 얹을 때.
  • Claude API: 직접 모델을 호출하는 저수준 경로. 모델 챕터의 모델 ID·effort가 그대로 적용됩니다.


핵심 요약

  • 같은 엔진이 CLI·IDE 확장·데스크톱 앱·웹·모바일에서 돈다. GUI를 원하면 데스크톱 앱, 브라우저를 직접 눌러야 하면 Chrome 연동(단 WSL 미지원).
  • 어디서 도는가로 갈린다 — Remote Control은 내 컴퓨터의 세션을 폰·웹으로 이어받는 것(로컬 파일·MCP 그대로), 웹/클라우드 세션은 아예 클라우드 VM에서 도는 것(로컬 준비 없이 시작, 안 받아 둔 저장소·병렬 작업).
  • 아티팩트는 "읽는 것보다 보는 게 빠른" 산출물을 살아 있는 페이지로 공유한다 — 백엔드 없는 한 장짜리라는 한계를 함께 기억할 것.
  • 사람이 안 보는 자리로 넘어가면 헤드리스 -p와 Agent SDK, 그리고 예약 루틴이 받는다.
확인 퀴즈

Q1. Remote Control과 Claude Code on the web의 가장 큰 차이는?

해설 · Remote Control은 내 컴퓨터에서 세션이 돌고 폰·웹은 그것을 들여다보는 창이라 로컬 파일·MCP·설정이 그대로 살아 있습니다. 웹/클라우드 세션은 클라우드 VM에서 돌아 로컬 준비가 필요 없는 대신 로컬 환경을 못 씁니다.

Q2. 아티팩트로 만들 수 없는 것은?

해설 · 아티팩트는 백엔드 없는 자체 완결 페이지 한 장입니다. 폼 입력 저장·다중 경로·자체 API 호출이 안 됩니다(외부 데이터 경로는 MCP 커넥터뿐). 백엔드가 필요하면 직접 배포하세요.

Q3. Chrome 연동을 쓸 수 없는 환경은?

해설 · Chrome·Edge와 Brave·Arc 같은 크로미움 계열에서 동작하지만 WSL에서는 지원하지 않습니다. Claude는 여러분의 브라우저 로그인 상태를 그대로 쓰고, 로그인 화면·CAPTCHA를 만나면 멈추고 사람에게 넘깁니다.
CHAPTER 16

플레이그라운드

이론은 충분히 봤으니, 이제 직접 만져 볼 차례입니다. 이 챕터는 읽기만 하는 게 아니라 가지고 노는 여덟 가지 도구 — 터미널 놀이터, 확장 진단기, 비용 계산기, CLAUDE.md 검사기, 프롬프트 튜너, 컨텍스트 예산, 권한 규칙 시뮬레이터, 에이전트 하네스 시뮬레이터 — 을 담았습니다. (모두 브라우저 안에서 도는 학습용 시뮬레이터입니다. 실제 Claude Code를 실행하지는 않습니다.)


🖥 터미널 놀이터

아래 가짜 Claude Code 터미널에 슬래시 커맨드를 쳐 보세요. 미션이 상황을 하나씩 던져 주니, 명령을 외우는 대신 상황에서 떠올리는 연습이 됩니다. 실제 터미널처럼 Tab 자동완성 · ↑ ↓ 히스토리 · Ctrl+L도 동작합니다. 4장 명령어에서 배운 것들을 손으로 익히는 코너입니다.


🧭 어떤 확장을 쓸까? — 진단기

상황을 고르면 CLAUDE.md · 스킬 · 훅 · 서브에이전트 · MCP 중 무엇이 맞는지 추천하고, 바로 복사해 쓸 수 있는 설정 조각까지 같이 드립니다. 11장 오케스트레이션의 선택 기준을 인터랙티브로 옮긴 것입니다. 가장 헷갈리는 갈림길인 MCP냐 스킬이냐는 질문 세 개까지 파고들어 갈라 줍니다 — 10장에서 봤듯 쓸 만한 CLI가 이미 있는 도구라면 답은 MCP가 아닙니다.


💰 비용 계산기

모델·토큰·요청 수를 넣으면 예상 비용을 계산합니다. 프롬프트 캐싱 적중률과 배치 API 할인을 켜 보면 왜 이 둘이 비용의 핵심 레버인지 숫자로 보이고, 아래 막대에서 같은 조건의 모델 4개 값을 나란히 비교할 수 있습니다. 맨 아래에는 정액 요금제(Pro·Max)와 종량 과금 중 어느 쪽이 싼지를 지금 설정 기준으로 환산해 보여 줍니다 — 다만 둘은 같은 것을 사는 게 아니라서, 그 차이도 함께 적어 뒀습니다. 3장 모델의 가격표 기반입니다.


📋 내 CLAUDE.md 검사기

쓰고 있는 CLAUDE.md를 붙여 넣으면 줄 단위로 검사합니다. 5장이 "지우라"고 한 것 — 자명한 지침, 검증할 수 없는 표현, 코드를 읽으면 알 수 있는 파일 설명 — 을 찾아 표시하고, 200줄 목표 대비 크기와 대략의 토큰 수를 같이 보여 줍니다. 예시 두 개(나쁜 예·좋은 예)를 불러와 무엇이 걸리고 무엇이 안 걸리는지 먼저 비교해 보세요.


🪄 프롬프트 튜너 (Opus 5.5 & Fable 5.1)

14장 최신 모델 프롬프트 가이드의 원칙을 내 프롬프트에 직접 적용해 보는 코너입니다. 프롬프트를 입력하면 최신 모델(Opus 5.5·Fable 5.1)의 실전 지침 — 완료 기준(Done) 명시, 과잉 검증 및 "think hard" 지시 제거, thinking 유지, 독립 도구 병렬 호출 넛지, 장기 루프 진행 상황 보고, 타겟 편집 명시, 밀도 높은 글쓰기 — 에 맞춰 실시간으로 검사하고, 최적화된 튜닝 프롬프트 조각을 만들어 줍니다. 위의 샘플 버튼 4개로 흔히 저지르는 프롬프트 실수 패턴을 먼저 확인해 보세요.


🧮 컨텍스트 예산

12장의 "컨텍스트는 유한 자원"을 눈으로 보는 코너입니다. 시스템 프롬프트·CLAUDE.md·MCP 도구 정의·파일 출력·대화 기록이 창을 어떻게 나눠 쓰는지 막대로 보여 주고, 무엇이 가장 많이 먹는지 짚어 줍니다. 아래 레버 세 개(/compact, 서브에이전트 격리, MCP→CLI)는 12장의 3대 기법과 10장의 권고를 그대로 눌러 보는 것입니다 — 각각 얼마나 돌려주는지 숫자로 확인하세요.


🔐 권한 규칙 시뮬레이터

2장의 권한 규칙은 글로만 읽으면 반드시 한 번 틀립니다. 규칙과 명령을 넣으면 deny→ask→allow를 실제 순서대로 훑어 어느 규칙이 먼저 맞았는지와 그 이유를 보여 줍니다. 프리셋 네 개는 각각 사람들이 실제로 밟는 함정입니다 — 넓은 deny에 예외를 뚫으려는 시도, *의 단어 경계, 복합 명령·래퍼, 그리고 경로 앞 /가 설정 파일 기준이라는 것. 규칙을 고쳐 가며 판정이 어떻게 뒤집히는지 확인해 보세요.


🤖 에이전트 하네스 & 오케스트레이션 시뮬레이터

11장 오케스트레이션과 13장 하네스 & 루프의 자율 에이전트 루프를 직접 돌려보는 시뮬레이터입니다. 루프 토폴로지(단일 선형 루프 · 병렬 팬아웃 · 2단계 계획-구현 하네스)를 고르고, 1스텝 실행 또는 자동 완주를 눌러 보세요. 장애 주입 토글(테스트 실패 Exit 1 · 컨텍스트 누출)을 켜면 하네스가 실패를 감지해 어떻게 자체 교정 루프(Self-Correction)를 돌고 컨텍스트 격리를 지켜내는지 시각적으로 확인할 수 있습니다.


핵심 요약

  • 터미널 놀이터의 미션 6개로 슬래시 커맨드를 손에 익히고, 진단기로 확장 선택 기준을 체득한 뒤 나온 설정 조각을 실제 저장소에 붙여 보고, 계산기로 캐싱·배치가 비용을 얼마나 바꾸는지 확인하세요.
  • 검사기에는 지금 쓰는 CLAUDE.md를 그대로 붙여 넣어 지울 줄부터 찾고, 프롬프트 튜너로 14장의 16대 실전 지침에 맞춘 최적화 프롬프트 조각을 뽑아 보세요.
  • 예산에서는 레버를 눌러 무엇이 컨텍스트를 가장 많이 돌려주는지 확인하고, 권한 규칙 시뮬레이터에는 실제로 쓰는 settings.json의 permissions를 붙여 넣어 보세요 — 의도대로 막히는지, 혹시 넓은 deny가 필요한 allow까지 삼키고 있는지 여기서 먼저 드러납니다.
  • 에이전트 하네스 시뮬레이터를 통해 서브에이전트 병렬화 시의 컨텍스트 격리 원리와 테스트 게이트 실패 시의 자체 교정 루프 동작을 직접 조작해 보세요.
  • 여기서 감을 잡았다면, 이제 진짜 설치하고 여러분의 프로젝트에 적용할 차례입니다.
확인 퀴즈

Q1. 권한 규칙에서 deny에 Bash(aws *), allow에 Bash(aws s3 ls)를 같이 적으면 aws s3 ls는?

해설 · 평가는 deny→ask→allow 순이고 먼저 맞는 것이 이깁니다. 구체성은 순서를 바꾸지 않으므로 넓은 deny에는 예외를 뚫을 수 없습니다 — 막을 것만 좁게 적으세요.

Q2. Bash(ls *)와 Bash(ls*)의 차이는?

해설 · 끝에 붙은 *(공백+별표)는 단어 경계를 요구합니다. Bash(ls *)는 ls -la에만 맞고 lsof에는 안 맞지만, 공백 없는 Bash(ls*)는 둘 다 맞습니다.

Q3. 프롬프트 캐시가 적중(hit)했을 때 입력 토큰 요금은 기본가의 몇 배인가요?

해설 · 캐시 읽기는 기본 입력가의 0.1배입니다(5분 캐시 쓰기 1.25배, 1시간 2배). 그래서 5분 캐시는 한 번만 재사용해도 이득입니다. 계산기 위젯의 캐시 슬라이더가 이 배수로 계산합니다.

Q4. 컨텍스트 예산에서 서브에이전트로 작업을 격리하면 무엇이 줄어드나요?

해설 · 서브에이전트는 자기 컨텍스트에서 일하고 요약만 돌려줍니다. 그래서 탐색처럼 출력이 큰 작업을 격리하면 메인 컨텍스트에 쌓이는 도구 출력이 크게 줄어듭니다.
CHAPTER 17

부록 · 알면 좋은 것들

핵심 개념은 모두 다뤘습니다. 이 부록은 실무에서 자주 쓰이지만 앞 챕터에 자연스럽게 넣기 어려웠던 알아 두면 좋은 기능·팁을 모았습니다.


세션 관리 — 대화를 브랜치처럼

Claude Code는 대화를 로컬에 저장합니다. 작업이 여러 번에 걸치면 매번 맥락을 다시 설명할 필요가 없습니다.

명령/플래그 하는 일
claude --continue 가장 최근 세션 이어가기
claude --resume 목록에서 골라 재개
/rename 세션에 이름 부여(예: oauth-migration) — 나중에 찾기 쉽게
/branch 다른 방향을 시도하려 대화를 분기
/fork 대화를 새 백그라운드 세션으로 복제
claude --remote-control · /remote-control 웹(claude.ai)이나 모바일 앱에서 이 세션을 원격 제어하도록 연결 (원격 /fork 지원, v2.1.270+)

세션을 브랜치처럼 다루세요 — 워크스트림마다 이름 붙은 고유 컨텍스트를 갖게 하면 병렬 작업이 깔끔해집니다.



인터페이스·워크플로 소소한 도구들

명령 하는 일
/focus 작업 중 프롬프트, 1줄 진행 요약, 최종 응답만 남기는 초경량 포커스 뷰 토글 (v2.1.270+)
/output-style [이름] 출력 스타일(기본, 설명형, 학습형 등) 열람 및 즉시 전환 (v2.1.270+)
/reload-skills 세션 재시작 없이 새로 추가·수정된 스킬 즉시 다시 로드 (v2.1.270+)
/diff 커밋 안 된 변경을 인터랙티브 diff 뷰어로
/copy 마지막 응답을 클립보드로 복사
/export 대화를 평문으로 내보내기
/statusline 상태줄 커스터마이즈(컨텍스트 사용량 등 표시)
/keybindings 키보드 단축키 파일 열기
/config 설정 열기·키값 지정(테마·모델 등, 전체 화면에서 마우스 휠·클릭 지원)
/color 프롬프트 바 색상
Ctrl+O 트랜스크립트 뷰 토글(훅 실행 등 상세)
Ctrl+B 실행 중 작업을 백그라운드로

상태줄 팁: 컨텍스트가 가장 중요한 자원이므로, /statusline으로 컨텍스트 사용량을 상태줄에 띄워 두면 언제 /clear·/compact할지 감이 잡힙니다.



번들 스킬 — 이미 들어 있는 강력한 도구들

/로 바로 쓰는 번들 스킬들. 설치 없이 사용 가능합니다.

스킬 하는 일
/run · /verify 앱을 실제로 띄워 변경이 동작하는지 확인(테스트만이 아니라 실행으로)
/code-review diff를 새 서브에이전트가 리뷰(--fix로 수정 적용)
/security-review diff의 보안 취약점 점검
/batch 대규모 코드베이스 변경을 병렬로 오케스트레이션
/deep-research 웹 검색을 팬아웃해 리포트로 종합
/loop 프롬프트를 주기적으로 반복 실행(루프 엔지니어링)
/doctor 셋업 점검·진단

/code-review ultra(= ultrareview)는 같은 리뷰의 "깊은 판"입니다(리서치 프리뷰). 로컬 대신 클라우드 샌드박스에서 리뷰어 에이전트 여러 대를 띄워 브랜치나 PR을 훑고, 보고하는 지적마다 독립적으로 재현·검증합니다 — 그래서 스타일 훈수가 아니라 진짜 버그 위주로 남습니다. 터미널은 그동안 비어 있습니다. 대신 비싼 기능입니다. 요금제 사용량이 아니라 사용량 크레딧에서 빠지고, Pro·Max에 평생 3회 무료(Team·Enterprise는 없음), 그 뒤로는 변경 크기에 따라 보통 회당 $5~25입니다. 실행 전 대화상자가 범위·남은 무료 횟수·예상 비용을 보여 주고, 중간에 멈춰도 무료 1회는 소모됩니다. 여러분이 /code-review ultra를 직접 칠 때만 돌아가고 Claude가 알아서 시작하지 않습니다.

저장소 전체를 훑는 보안 점검이 필요하면 Claude Security 플러그인을 설치하세요(플러그인).

/plugin install claude-security@claude-plugins-official
/claude-security          # 전체 스캔 · 변경분 스캔 · 패치 제안 메뉴

에이전트 팀이 아키텍처를 파악해 위협 모델을 세우고, 취약점을 찾은 뒤 모든 지적을 독립적으로 재검토해 리포트를 냅니다. 고른 지적은 패치로 바꿔 주되 적용은 여러분이 검토해서 합니다. 스캔은 로컬 세션에서 돌고 요금제 사용량을 씁니다.

보안 도구는 층으로 쌓입니다 — 하나로 다 하려 들지 마세요.

시점 도구 커버 범위
코드를 쓰는 중 보안 가이던스 플러그인 Claude가 쓰는 코드의 흔한 취약점을 그 세션에서 바로
필요할 때 한 번 /security-review 현재 브랜치 1회 점검
필요할 때 깊게 Claude Security 플러그인 저장소·diff 다중 에이전트 스캔 + 검증된 지적 + 패치
PR에서 Code Review(Team·Enterprise) 코드베이스 전체 맥락의 정확성·보안 리뷰


비용·성능 관리

  • /usage로 API 사용량·비용 확인. 저비용이 필요하면 모델·effort를 낮추세요.
  • 프롬프트 캐싱: 반복되는 큰 컨텍스트(예: CLAUDE.md)는 자동으로 캐시되어 최대 90% 절감. 세션 중 모델을 바꾸면 캐시가 무효화되니 잦은 전환은 피하세요.
  • 릴리스 채널: 네이티브 설치는 자동 업데이트. /config의 Auto-update channel에서 latest(최신) 또는 stable(약 1주 지연, 회귀 회피)을 고를 수 있습니다.
  • 사용량 한도에 걸려도 세션은 이어집니다(v2.1.234+, v2.1.274에서 워크플로 일시정지 및 자동복구 안정화): claude.ai 사용량 한도가 리셋되면 Claude Code가 자동으로 이어서 진행합니다. 원치 않으면 /config의 "Continue automatically at usage limit"에서 끄세요.
  • claude doctor로 설치·설정 상태를 언제든 진단.


최신 환경 변수·설정 플래그 (v2.1.270 ~ v2.1.274)

최근 릴리스에서 대규모 프로젝트와 파이프라인 자동화를 위해 추가된 주요 옵션들입니다.

설정 / 환경 변수 기본값 / 설명 실무 활용
omitClaudeMd: true 에이전트 프론트매터 설정 서브에이전트 실행 시 불필요한 프로젝트 CLAUDE.md 로드를 건너뛰어 컨텍스트 토큰을 절약하고 특화 지침만 주입 (7장)
bashEditDiffEnabled settings.json (기본 false) Bash 명령어가 파일 수정(sed, awk, 리다이렉션 등)을 일으켰을 때 변경 diff를 도구 결과에 함께 반환
permissions.blockReadsOutsideWorkingDirectories settings.json (기본 false) 작업 디렉터리 외부의 파일 읽기 시도를 차단해 민감한 시스템 경로 유출 방지 (2장)
CLAUDE_CODE_MCP_STARTUP_WAIT_MS 환경 변수 (기본 비동기 대기) 비대화형/헤드리스 턴에서 MCP 서버 연결 대기 상한(ms). 0 지정 시 연결 대기 없이 즉시 시작
claude plugin eval CLI 서브커맨드 플러그인의 eval 테스트 스위트를 구동해 재현 가능한 점수 및 JSON/HTML 리포트 산출 (10장)


더 배우기 — Anthropic 공식 무료 강좌

Anthropic Academy의 Claude Code in Action(무료)은 "단일 프롬프트를 넘어 더 길고, 덜 감독하고, 팀 단위 워크플로로" 나아가려는 개발자를 위한 실습 강좌입니다 — 플랜 모드·되감기, CLAUDE.md·스킬·권한, 예약 루틴·GitHub Actions, 무인 실행 검증까지. 이 강의를 마쳤다면 다음 단계로 좋습니다. 전체 리소스 지도는 참고 자료 챕터를 보세요.



안전하게 쓰기 — 빠른 체크리스트

  • 민감 작업은 Manual(default)/plan 모드로, 신뢰 작업은 auto 모드로(2장). Pro·Max·Team의 새 세션은 이제 auto로 시작하니, 민감한 저장소에서는 시작 모드를 직접 확인하세요.
  • 반드시 막아야 하는 동작은 CLAUDE.md 조언이 아니라 훅으로 강제.
  • 무인 실행(루프)에는 검증(테스트·/goal·검증 서브에이전트)을 반드시 게이트로.
  • 외부 자산(서브에이전트·스킬·플러그인·MCP)은 도입 전 내용 검토.
  • 되돌리기는 /rewind·체크포인트로, 단 Bash·외부 변경은 안 잡히니 git이 최종 안전망.


핵심 요약

  • 세션은 --continue·--resume·/rename·/branch로 브랜치처럼 다룬다.
  • 번들 스킬(/run·/code-review·/security-review·/batch 등)은 설치 없이 강력하다. 더 깊게 봐야 하면 /code-review ultra(클라우드 다중 에이전트, 사용량 크레딧)와 Claude Security 플러그인이 있다.
  • 보안 도구는 층으로 쌓인다 — 쓰는 중(가이던스) · 1회 점검(/security-review) · 깊은 스캔(Claude Security 플러그인) · PR(Code Review).
  • 비용은 /usage·모델·effort·프롬프트 캐싱으로, 안전은 권한 모드·훅·검증·git으로 관리한다.
확인 퀴즈

Q1. 가장 최근 세션을 이어서 여는 방법은?

해설 · claude --continue는 최근 세션을, claude --resume은 목록에서 골라 재개합니다. /rename으로 이름을 붙여 두면 찾기 쉽습니다.

Q2. Claude Code를 라이브러리로 패키징해 자체 인프라에서 에이전트를 만드는 것은?

해설 · Claude Agent SDK는 내장 도구·에이전트 루프·훅·서브에이전트를 코드에서 그대로 씁니다. 헤드리스 -p는 CLI 자동화용입니다.

Q3. 클라우드/웹 세션에서 개인 스킬을 쓰려면?

해설 · 클라우드/웹 세션은 로컬 ~/.claude/skills/를 읽지 않습니다. 저장소에 커밋하거나 플러그인으로 배포해야 합니다.
CHAPTER 18

참고 자료 · GitHub 리소스

이 강의는 Claude Code 공식 문서와 여러 엔지니어링 아티클, 그리고 커뮤니티가 큐레이션한 오픈소스 저장소들을 바탕으로 집필했습니다. 더 깊이 파고들고 싶을 때 찾아갈 참고 자료 지도입니다.

먼저 한 가지: 아래 커뮤니티 자산은 외부 코드입니다. 서브에이전트·스킬·플러그인·MCP 서버를 도입하기 전 반드시 내용을 검토하고, 신뢰할 수 있는 출처만 쓰세요. 공식 문서 외의 링크는 시점에 따라 바뀔 수 있습니다.


공식 자료 (1차 출처)

강의의 사실관계는 대부분 여기서 확인했습니다.

자료 설명
Claude Code 공식 문서 — code.claude.com/docs 명령어·CLAUDE.md·서브에이전트·스킬·훅·MCP·권한·설치 등 모든 기능의 1차 레퍼런스
Building with Claude Sonnet 5.5 — claude.dev/blog Addy Osmani 저. Sonnet 5.5의 30%+ 생성 가속, Terminal-Bench 4.0 70.6% 실측치, 에이전트 빌딩 패턴 및 API 마이그레이션 제약 (3장·14장 핵심 출처)
Claude Sonnet 5.5 발표 및 시스템 카드 — anthropic.com Anthropic 공식 릴리즈 블로그, 벤치마크 평가, 3단계 사이버보안 가드레일 및 모델 사양 (3장 출처)
Getting the most out of Opus 5.5 in Claude and Claude Code — claude.dev/blog Addy Osmani 저. Opus 5.5 프롬프트 작성법, 완료 기준(Done) 정의, 긴 실행 세션 조종(CLAUDE.md 스톱 규칙, TASKS.md), 서브에이전트 팬아웃 및 결과 검증, 보안 플래그 대응 플레이북 (14장의 핵심 출처)
Using Claude Code: Spending your effort — claude.dev/blog Thariq Shihipar 저. Terminal-Bench 3.0 벤치마크 기반 Opus 5.5 & Fable 5.1의 Effort 곡선 실측, html-js-filter XSS 방어 사례, 4단계 기능 개발 루프 (3장·14장 출처)
What a task costs on Opus 5.5 — claude.dev/blog Addy Osmani 저. Opus 5.5의 토큰 인하 및 캐시 읽기 60% 인하($0.20/M)에 따른 실무 작업 비용 40% 절감 분석
Anthropic Academy — Claude Code in Action ⭐ 무료 — anthropic.skilljar.com Anthropic 공식 무료 강좌. 플랜 모드·되감기로 긴 세션 조종, CLAUDE.md·스킬·권한 설정, 예약 루틴·GitHub Actions 자동화, 무인 실행 검증·플러그인 배포까지. "몇 시간짜리 작업을 맡기고 자리를 비운 뒤 결과를 확신 있게 확인"하는 것이 목표
Prompting Claude Sonnet 5.5 — platform.claude.com/docs Anthropic 공식 Sonnet 5.5 프롬프트 엔지니어링 가이드. 추론 강도(effort) 재조정, 자율성/작업 범위 제어, between_tools 제약, JSON 출력 추론 유도, 간접 인젝션 방어, 코딩 실검증 강제 지침 등 10대 핵심 실전 패턴 (14장 3부 핵심 출처)
최신 모델 프롬프트 가이드 — platform.claude.com/docs Opus 5.5 및 최신 Fable 5.1(Prompting Claude Fable 5.1) 공식 가이드(14장의 출처)
anthropics/claude-code — github.com/anthropics/claude-code Claude Code 이슈 트래커·릴리스·예제(examples/hooks 등)
Anthropic Engineering 블로그 — anthropic.com/engineering "Effective context engineering", "Claude Code best practices" 등 원리 아티클
공식 플러그인 마켓플레이스 — anthropics/claude-plugins-official skill-creator·mcp-server-dev 등 Anthropic 공식 플러그인
Anthropic 커넥터 디렉터리 — claude.ai/directory 검증된 원격 MCP 커넥터 모음 (claude mcp add로 연결)
Agent Skills 오픈 표준 — agentskills.io SKILL.md 포맷의 개방 표준(여러 AI 도구 호환)

개념 아티클 (신규 개념의 출처)

컨텍스트 엔지니어링·하네스·루프 엔지니어링 챕터가 참고한 글들입니다.

자료 설명
Effective context engineering for AI agents — anthropic.com 컨텍스트 로트·어텐션 예산·압축/노트/서브에이전트를 정의한 Anthropic 원문
Agent Harness Engineering — addyosmani.com "에이전트 = 모델 + 하네스", Skill issue 리프레임, 하네스 구성요소
Loop · Harness · Context Engineering Explained — codecentric.de 네 계층(프롬프트→컨텍스트→하네스→루프)의 명확한 정의·관계

커뮤니티 큐레이션 & 벤치마크 (인기 리소스 모음)

실무자들이 가장 많이 참고하는 "awesome" 목록·툴킷 및 에이전트 평가 벤치마크입니다.

저장소 설명
harbor-framework/terminal-bench — github.com Terminal-Bench 3.0 공식 저장소. 소프트웨어·보안·하드웨어·과학 분야의 커뮤니티 기여형 실제 터미널 에이전트 벤치마크 과제 스위트
hesreallyhim/awesome-claude-code — github.com 스킬·에이전트·상태줄·툴링·플러그인의 사실상 표준 큐레이션
rohitg00/awesome-claude-code-toolkit — github.com 에이전트·스킬·명령·플러그인·훅·MCP를 대량 묶은 종합 툴킷
jqueryscript/awesome-claude-code — github.com 도구·IDE 통합·프레임워크 중심 큐레이션
VoltAgent/awesome-claude-code-subagents — github.com 10개 카테고리 100+개 전문 서브에이전트 컬렉션
ComposioHQ/awesome-claude-skills — github.com Claude 스킬·리소스·도구 큐레이션
ai-boost/awesome-harness-engineering — github.com 하네스 엔지니어링(도구·평가·기억·MCP·권한·관찰성) 목록
The-Pocket/PocketFlow-Tutorial-Codebase-Knowledge — github.com 복잡한 코드베이스를 자동 크롤링하고 핵심 추상화와 상호작용 다이어그램을 초보자용 튜토리얼로 생성하는 AI 지식 빌더 도구 (claude-code-best-practice 한국어 분석 수록)

바로 쓸 만한 자산 (스킬·CLAUDE.md 예시)

자산 설명
Superpowers 검증된 기법·패턴을 담은 종합 스킬 라이브러리 — Claude Code에 "초능력"을 더한다
andrej-karpathy-skills LLM 코딩 함정 관찰을 정리한 단일 CLAUDE.md — CLAUDE.md 챕터의 좋은 참고 예시
관찰성(observability) 훅·대시보드 툴콜·서브에이전트 시작/종료·권한 이벤트를 훅으로 로깅해 세션을 관측

어떻게 활용하면 좋은가

  1. 막히면 공식 문서부터 — 기능의 정확한 동작은 code.claude.com이 최종 근거.
  2. 왜 이렇게 하나 궁금하면 개념 아티클로 원리를 잡는다.
  3. 바퀴를 다시 만들지 말고 커뮤니티 목록에서 서브에이전트·스킬·플러그인을 찾는다.
  4. 반드시 검토 후 도입한다 — 외부 코드는 당신 권한으로 실행된다.

마치며

여기까지, 설치부터 루프 엔지니어링까지 Claude Code의 확장 기능 전반을 한 바퀴 돌았습니다. 핵심을 한 문장으로 남긴다면:

컨텍스트를 아끼고, 검증 수단을 주고, 실패는 설정으로 고쳐라.

명령어·CLAUDE.md·기억·서브에이전트·스킬·훅·MCP가 오케스트레이션으로 맞물리고, 그 위에 컨텍스트·하네스·루프 엔지니어링이 얹힐 때, Claude Code는 지켜보는 도구에서 맡기고 자리를 비울 수 있는 시스템으로 바뀝니다. 이제 직접 만들어 볼 차례입니다.


🎓 수료증 만들기

강의를 끝까지 읽으셨다면, 이름을 넣어 나만의 수료증을 만들어 PNG 이미지로 저장하세요. 진행하며 푼 퀴즈 성적도 함께 반영됩니다. 저장은 브라우저 기본 방식(다운로드 폴더 저장 · 이미지 우클릭/길게 눌러 저장)을 그대로 사용하며, 아래에 방법을 안내해 드립니다.


핵심 요약

  • 1차 출처는 공식 문서(code.claude.com)·Anthropic 엔지니어링 블로그·공식 저장소.
  • 신규 개념(컨텍스트·하네스·루프)은 Anthropic 원문·Addy Osmani·codecentric 아티클에서.
  • 커뮤니티 자산(awesome-claude-code·VoltAgent 서브에이전트·Superpowers 등)은 바퀴를 다시 만들지 않게 해 주되, 도입 전 반드시 검토하라.
  • 공식 문서로 사실을 확인하고, 아티클로 원리를 잡고, 커뮤니티로 자산을 찾는 순서가 안전하다.