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의 진짜 힘은 확장 기능을 조합할 때 나옵니다. 이 강의가 다룰 조각들:

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

핵심 요약

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

첫 세션 · 권한 · 플랜 모드

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

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

Claude가 파일을 수정하거나 명령을 실행하려 하면 기본적으로 멈추고 승인을 요청합니다. 권한 모드는 이 멈춤의 빈도를 조절합니다. 민감한 작업엔 감독을 늘리고, 신뢰하는 방향이면 방해를 줄이세요.

모드 전환: 프롬프트에서 Shift+Tab을 눌러 모드를 순환하거나, 실행 시 --permission-mode 플래그를 씁니다.

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

오토 모드는 별도 분류기 모델이 명령을 검토해 스코프 이탈·미지의 인프라·적대적 콘텐츠 기반 동작만 차단하고, 나머지 루틴 작업은 통과시킵니다. "방향은 맞다고 믿지만 열 번째 승인쯤 되면 사실 검토가 아니라 그냥 클릭하는" 상태를 없애 줍니다.

권한을 세밀하게 통제하려면 /permissions로 특정 도구·명령을 허용/거부 규칙에 추가하거나(npm run lint 같은 안전한 것만 허용), /sandbox로 OS 레벨 격리를 켤 수 있습니다.

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

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

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

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

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

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

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

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

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

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

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

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

핵심 요약

• 권한 모드(Shift+Tab으로 순환): default→acceptEdits→plan→auto→bypassPermissions. 민감할수록 감독을, 신뢰할수록 자율을.
• 플랜 모드로 탐색·계획을 실행과 분리해 엉뚱한 문제 풀기를 막는다(작은 변경은 건너뛰기).
• Esc·/rewind·체크포인트로 과감히 시도하고 되돌린다. 단, git을 대체하진 않는다.
• 작업 전환마다 /clear, 방향은 일찍 교정 — 컨텍스트 관리가 곧 성능이다.

모델과 성능

Claude Code는 여러 Claude 모델 위에서 돌아갑니다. 어떤 모델을, 어느 강도로 쓰느냐가 결과 품질·속도·비용을 좌우합니다. 이 챕터는 현재(2026년) 모델 라인업과, Claude Code에서 이를 통제하는 /model·/effort·/fast를 다룹니다.

현재 모델 라인업 (2026)

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

※ Sonnet 5는 2026-08-31까지 도입가 $2/$10. Opus 4.8·4.7 등은 레거시(계속 사용 가능하나 마이그레이션 권장).

모델 선택의 감: - 복잡한 코딩·에이전틱 → Opus 5 (다중 파일 기능·대규모 리팩터·엔드투엔드 작업에서 최강, 스텁 없이 끝까지 완성) - 가장 어려운·장기 자율 작업 → Fable 5 (최고 지능 티어) - 속도·비용 균형 → Sonnet 5 - 단순·빠름·저렴 → Haiku 4.5 (분류, 간단 조회, 서브에이전트 저비용 탐색)

Anthropic은 "어떤 모델을 쓸지 모르겠으면 복잡한 에이전틱 코딩엔 Opus 5부터, 최고 능력이 필요하면 Fable 5"를 권합니다.

모델 전환 — /model

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

/model            # 대화형 선택
/model opus       # 별칭으로 바로 지정 (sonnet/opus/haiku/fable)

서브에이전트는 모델을 따로 지정할 수 있습니다(7장의 model 프론트매터). 읽기 위주 탐색은 haiku로 저렴하게, 판단이 중요한 작업은 opus/fable로 — 리소스를 작업 성격에 맞추는 것이 핵심입니다.

추론 강도 — /effort

Claude 5 세대는 effort로 "얼마나 깊이 생각하고 행동할지"를 조절합니다. 단순히 사고량만이 아니라 도구 호출·검증 루프의 적극성까지 좌우합니다.

/effort xhigh

핵심(2026 최신): Opus 5·Sonnet 5의 기본 effort는 high입니다. 기본(high)에서 시작해 자신의 평가셋으로 조정하세요 — low·medium을 비용·속도의 주 레버로 적극 활용하고(품질이 유지되는 한), 어려운 코딩·에이전틱엔 xhigh로 올립니다. 이전 모델의 effort 기본값을 그대로 가져왔다면 재튜닝하세요.

• 낮은 effort에서 얕은 추론이 보이면, 프롬프트로 우회하기보다 effort를 올리는 것이 먼저입니다.
• 높은 effort + 긴 작업이면 출력 토큰 여유(max_tokens)를 넉넉히 — 사고가 예산의 큰 몫을 쓸 수 있습니다.

적응형 사고(adaptive thinking): Opus 5·Sonnet 5·Fable 5는 언제·얼마나 생각할지 스스로 정합니다(고정 "thinking budget" 개념은 폐기). Fable 5는 사고가 항상 켜져 있고, effort가 그 깊이를 조절하는 주 레버입니다. 모델별 프롬프트 튜닝은 14장 최신 모델 프롬프트 가이드에서 자세히 다룹니다.

빠른 모드 — /fast

Fast 모드는 최근 Opus 티어를 같은 지능으로 유지하면서 출력 속도를 최대 2.5배까지 올립니다(프리미엄 가격, 리서치 프리뷰). 작은 모델로 낮추는 게 아니라 같은 Opus를 더 빠르게 내보냅니다.

/fast     # 토글 — 인터랙티브하게 빠른 피드백이 필요할 때

컨텍스트·비용 함께 보기

• 컨텍스트 창: Fable 5·Opus 5·Sonnet 5는 1M 토큰(기본이자 최대), Haiku 4.5는 200K. 크다고 다 채우라는 뜻은 아닙니다 — 찰수록 성능이 떨어지므로 자동 압축·/clear와 컨텍스트 엔지니어링으로 관리하세요.
• 비용 통제: /usage로 사용량·비용 확인. 저비용이 필요하면 effort를 low/medium으로 내리거나 모델을 낮추고(Sonnet/Haiku), 반복 컨텍스트가 크면 프롬프트 캐싱이 자동으로 절감합니다.
• 모델을 세션 중간에 바꾸면 프롬프트 캐시가 무효화됩니다 — 잦은 전환보다 작업 성격에 맞춰 초반에 정하는 편이 낫습니다.

핵심 요약

• 현재 라인업: Fable 5(최고 지능) · Opus 5(복잡 코딩·에이전틱, Anthropic 권장 기본) · Sonnet 5(균형) · Haiku 4.5(빠름·저렴). Opus 4.8 등은 레거시.
• /model로 모델을, /effort로 추론 강도를 조절 — 기본은 high, 어려운 코딩·에이전틱은 xhigh, 비용 절감은 low/medium.
• /fast는 최근 Opus를 최대 2.5배 빠르게(프리미엄). 적응형 사고는 스스로 사고량을 정한다.
• 1M 컨텍스트라도 관리가 필요하고, 모델별 프롬프트 튜닝은 14장에서 다룬다.

명령어 · 슬래시 커맨드

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

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

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

명령의 세 가지 종류

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

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

자주 쓰는 내장 명령어

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

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

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

모델·성능

설정·프로젝트

진단·품질

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

커스텀 명령(스킬 포함)에서 쓰이는 핵심 문법 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로 컨텍스트를 능동적으로 관리하는 습관이 성능을 좌우한다.

CLAUDE.md · 프로젝트 지침

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

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

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

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

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

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

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

효과적인 CLAUDE.md 작성법

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

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

작성 지침 세 가지:

• 크기: 파일당 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 개발 규칙
- 모든 엔드포인트는 입력 검증을 포함한다
- 표준 에러 응답 형식을 사용한다

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

흔한 문제와 진단

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

핵심 요약

• CLAUDE.md는 당신이 쓰는 영구 지침 — 매번 다시 설명할 것을 적어 둔다.
• 위치별 스코프(관리→사용자→프로젝트→로컬)가 넓은 것부터 이어붙는다.
• 짧고 구체적으로. "지우면 실수하는가?"로 매 줄을 검증한다. 200줄이 목표.
• @임포트로 조직화, .claude/rules/의 paths로 필요할 때만 로드.
• 강제가 필요한 규칙은 CLAUDE.md가 아니라 훅으로. Claude가 스스로 축적하는 지식은 자동 기억이 담당한다.

자동 기억 (Agent Memory)

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

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

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
---

당신은 코드 리뷰어입니다. 리뷰하며 발견한 패턴·관례·반복되는 이슈를
당신의 에이전트 기억에 갱신하세요.

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

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

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

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

핵심 요약

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

서브에이전트

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

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

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

내장 서브에이전트

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

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/를 감시하므로, 파일을 추가·수정하면 몇 초 내 다음 위임부터 반영됩니다(새 디렉터리를 처음 만든 경우만 재시작 필요).

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

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

프론트매터 필드

name과 description만 필수입니다.

도구 제한 (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로 실행 중 작업을 백그라운드로 보낼 수 있습니다. 백그라운드 서브에이전트는 더 좁은 내장 도구 세트로 동작합니다.

실전 패턴

• 고출력 작업 격리: "서브에이전트로 테스트를 돌리고 실패한 테스트와 에러만 보고해줘"
• 병렬 리서치: "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 필드로 프리로드해 결합할 수 있다.

스킬

스킬(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로는 직접 호출됩니다.

어디에 두는가

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

프론트매터 레퍼런스

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

누가 호출하는가 통제

---
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 프리로드와 역방향 관계입니다.

인자와 동적 컨텍스트

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

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

문제 해결

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

핵심 요약

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

훅 (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를 돌리는 훅을 써줘"처럼 부탁하면 훅을 작성해 줍니다.

어디에 두는가

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

주요 훅 이벤트

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

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__.* 같은 정규식으로 매칭합니다. 이벤트별 매처 대상:

입력과 출력 — 훅이 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" }
}

종료 코드

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 규칙을 뚫지 못합니다. 훅은 제약을 조일 수는 있어도 느슨하게 풀 수는 없습니다.

문제 해결

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

핵심 요약

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

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로 설정 저장 위치를 정합니다.

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>.

플러그인이 제공하는 스킬·에이전트는 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·플러그인을 골라 조합하라 — 오케스트레이션에서 하나로 엮인다.

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

지금까지 배운 확장 조각들 — 명령어, 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가 읽을 수 있는 합격/불합격 신호를 주면 루프가 스스로 닫힙니다 — 작업하고, 검증하고, 통과할 때까지 반복.

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

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

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

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

• 리치 컨텍스트 제공: @파일 참조, 이미지 붙여넣기, 문서 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 워크트리로 충돌 없는 격리 체크아웃, 데스크톱 앱의 시각적 다중 세션, 에이전트 팀의 자동 조율.
• 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·/compact·서브에이전트가 핵심 무기.
• 탐색→계획→구현→커밋으로 엉뚱한 문제 풀기를 막고, 검증 수단으로 루프를 스스로 닫게 하라.
• 구체적으로 지시하고, 일찍 교정하고, 두 번 실패하면 리셋하라.
• 명령어·CLAUDE.md·서브에이전트·스킬·자동기억·훅이 하나의 오케스트레이션으로 맞물릴 때 무인 실행이 가능해진다.

컨텍스트 엔지니어링

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

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

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

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

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

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

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

4가지 큐레이션 영역

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

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

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

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

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

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

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

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

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

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

긴 작업의 3대 기법

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

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

Claude Code에서의 실천

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

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

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

핵심 요약

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

하네스 & 루프 엔지니어링

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

네 가지 엔지니어링 계층

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

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

하네스 엔지니어링

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

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

하네스의 구성요소

두 방향 — 가이드 vs 센서

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

"Skill issue 리프레임"

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

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

루프 엔지니어링

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

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

/goal — 가장 깔끔한 진입점

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

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

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

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

Planner/Evaluator 분리

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

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

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

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

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

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

핵심 요약

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

최신 모델 프롬프트 가이드

3장에서 본 최신 모델 — Opus 5·Fable 5·Sonnet 5 — 은 이전 세대보다 훨씬 똑똑하고 자율적입니다. 기존 Opus 4.8 프롬프트로도 잘 동작하지만, 더 자율적으로 행동하기 때문에 몇몇 습관은 반대로 튜닝해야 합니다. 이 챕터는 Anthropic의 Opus 5 프롬프트 가이드를 바탕으로, 실무에서 가장 자주 조정하는 패턴을 모았습니다.

큰 원칙: 모델이 좋아질수록 덜 지시해야 합니다. 예전 모델을 밀어붙이려고 넣었던 스캐폴딩(검증 강제·재확인 지시 등)이 최신 모델에선 과잉 행동을 유발해 토큰만 낭비합니다. 이런 지시는 빼는 것이 개선입니다.

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

Opus 5의 기본 사용자 응답은 이전 Opus보다 깁니다. 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.

긴 시스템 프롬프트에서는 끝부분에 짧은 리마인더를 함께 두면 효과적입니다.

<tone_preference>
Keep outputs reasonably concise.
</tone_preference>

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

에이전틱 작업 중 Opus 5는 "이제 무엇을 할지"를 자주 예고하고, 턴당 출력이 이전보다 깁니다. 소통 방식을 명시하면 조절됩니다.

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) 파일 산출물도 길어졌다 → 길이 보정

대화 장황함과 별개로, Opus 5가 디스크에 쓰는 파일(리포트·마크다운·요약)도 이전보다 깁니다. Claude가 문서를 작성하는 제품이라면 길이 기준을 명시하세요.

Match the length of written documents to what the task needs: cover the substance,
but do not pad with filler sections, redundant summaries, or boilerplate.

4) 스스로 검증한다 → 검증 지시를 빼라 + 범위 제약

Opus 5는 시키지 않아도 자기 작업을 검증합니다. 프롬프트에 "비자명한 작업엔 최종 검증 단계를 넣어라", "서브에이전트로 검증해라" 같은 지시가 있으면 제거하세요 — 최신 모델에선 과잉 검증을 유발해 토큰만 낭비합니다(하네스의 레거시 스캐폴딩도 마찬가지).

또한 Opus 5는 요청하지 않은 단계를 더하거나 범위를 넓히는 경향이 있습니다. 좁은 작업은 범위를 명시적으로 제약하세요.

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. If the request seems mistaken or a better approach exists, say so in
a sentence and continue with the task as asked rather than quietly narrowing,
widening, or transforming it. Finish the whole task, and stop short of actions that
are clearly beyond what was asked.

5) 서브에이전트를 더 적극 위임한다 → 캡을 걸어라

Opus 5는 이전보다 서브에이전트에 더 잘 위임합니다. 위임은 진짜 독립적이고 큰 작업에선 이득이지만, 작은 작업에 적용하면 비용·시간이 배가됩니다. 어떤 경우에 위임할지 명시하거나 결정론적 상한을 두세요.

Delegate to a subagent only for large tasks that are genuinely independent and
parallelizable, such as a wide multi-file investigation. Do not delegate work you can
finish yourself in a handful of tool calls, and do not use subagents to verify or
double-check your own work. If one subagent can complete the task, use one rather
than several, and keep spawn counts low.

6) 스스로 고친다 → 재확인 지시를 빼라

Opus 5는 자기 실수를 알아서 잡아 고칩니다. "답을 다시 확인해라", "응답 전 재검증해라" 같은 지시는 모델의 기존 행동과 겹쳐 비용만 늘립니다 — 넣지 마세요.

다만 이전 발언을 정정하는 내레이션이 늘어, 사용자 대면 제품에선 거슬릴 수 있습니다. 의미 있는 정정만 남기려면:

Only correct an earlier statement when the error would change the user's code,
conclusions, or decisions. State corrections plainly and briefly, then continue.
For slips that change nothing for the user, make the fix and move on without noting it.

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

Opus 5는 사고(thinking)가 기본 켜짐이고, 끄는 것은 effort high 이하에서만 가능합니다. 사고를 끄면 두 가지 아티팩트가 가끔 나타납니다.

• 도구 호출이 텍스트로 샘: 구조화된 tool_use 블록 대신 도구 호출을 사용자 텍스트에 써 버려 실제 실행되지 않음(검색 등 도구 위주 작업에서 흔함).
• 내부 XML 태그 누수: <thinking> 같은 내부 태그가 응답에 노출.

최선의 완화책은 사고를 끄지 말고, 대신 effort를 낮춰 비용을 통제하는 것입니다 — 대부분의 작업에서 "사고 켜짐 + low effort"가 "사고 꺼짐"보다 낫습니다. 꼭 꺼야 한다면 단일 지시로 두 아티팩트를 함께 완화하세요(태그를 이름으로 지목하지 마세요 — 오히려 누수가 늘어납니다).

When you use a tool, you may say a brief sentence first. If no tool can express what
the user asked for, say so instead of guessing. Do not include internal or system
XML tags in your response.

마이그레이션 노트 (Opus 4.8 → Opus 5)

• Opus 5는 기존 4.8 프롬프트로도 바로 잘 동작합니다 — 위 패턴은 "튜닝이 필요할 때"의 조정입니다.
• 사고가 기본 켜짐으로 바뀌었고, 비활성화는 effort high 이하에서만 됩니다.
• 완전한 작업 명세를 처음에 한 번에 주고 자율 실행에 맡길 때 가장 강합니다(오케스트레이션의 "구체적으로 지시하라"와 동일).
• effort 기본값을 이전 모델에서 가져왔다면 자신의 평가셋으로 재스윕하세요.

핵심 요약

• 최신 모델은 더 자율적 — 예전의 "밀어붙이는" 지시(검증 강제·재확인)는 빼는 것이 개선이다.
• 길이·내레이션·문서 길이는 effort가 아니라 명시적 프롬프트로 조절한다(긍정 예시가 효과적).
• 범위를 좁히고, 서브에이전트 위임에 캡을 걸어 과잉 행동·비용을 막는다.
• 사고는 끄지 말고 low effort로 비용을 통제한다 — 끄면 도구호출 누수·XML 태그 누수가 생긴다.

플레이그라운드

이론은 충분히 봤으니, 이제 직접 만져 볼 차례입니다. 이 챕터는 읽기만 하는 게 아니라 가지고 노는 세 가지 도구 — 터미널 놀이터, 확장 진단기, 비용 계산기 — 를 담았습니다. (모두 브라우저 안에서 도는 학습용 시뮬레이터입니다. 실제 Claude Code를 실행하지는 않습니다.)

🖥 터미널 놀이터

아래 가짜 Claude Code 터미널에 슬래시 커맨드를 쳐 보세요. /help부터 시작하면 됩니다. 4장 명령어에서 배운 것들을 손으로 익히는 코너입니다.

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

상황을 고르면 CLAUDE.md · 스킬 · 훅 · 서브에이전트 · MCP 중 무엇이 맞는지 추천해 드립니다. 11장 오케스트레이션의 선택 기준을 인터랙티브로 옮긴 것입니다.

💰 비용 계산기

모델·토큰·요청 수를 넣으면 예상 비용을 계산합니다. 3장 모델의 가격표 기반이며, 실제 요금은 프롬프트 캐싱·배치 할인 등으로 달라질 수 있습니다.

핵심 요약

• 터미널 놀이터로 슬래시 커맨드를 손에 익히고, 진단기로 확장 선택 기준을 체득하고, 계산기로 모델·effort의 비용 감을 잡으세요.
• 여기서 감을 잡았다면, 이제 진짜 설치하고 여러분의 프로젝트에 적용할 차례입니다.

부록 · 알면 좋은 것들

핵심 개념은 모두 다뤘습니다. 이 부록은 실무에서 자주 쓰이지만 앞 챕터에 자연스럽게 넣기 어려웠던 알아 두면 좋은 기능·팁을 모았습니다. 필요할 때 찾아보는 참조용으로 쓰세요.

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

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

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

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

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

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

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

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가 그대로 적용됩니다.

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

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

비용·성능 관리

• /usage로 API 사용량·비용 확인. 저비용이 필요하면 모델·effort를 낮추세요.
• 프롬프트 캐싱: 반복되는 큰 컨텍스트(예: CLAUDE.md)는 자동으로 캐시되어 최대 90% 절감. 세션 중 모델을 바꾸면 캐시가 무효화되니 잦은 전환은 피하세요.
• 릴리스 채널: 네이티브 설치는 자동 업데이트. /config의 Auto-update channel에서 latest(최신) 또는 stable(약 1주 지연, 회귀 회피)을 고를 수 있습니다.
• claude doctor로 설치·설정 상태를 언제든 진단.

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

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

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

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

핵심 요약

• 세션은 --continue·--resume·/rename·/branch로 브랜치처럼 다룬다.
• IDE·GitHub·Slack·데스크톱·웹·클라우드까지 같은 엔진 — 헤드리스 -p와 Agent SDK로 자동화·프로그래밍.
• 번들 스킬(/run·/code-review·/security-review·/batch 등)은 설치 없이 강력하다.
• 비용은 /usage·모델·effort·프롬프트 캐싱으로, 안전은 권한 모드·훅·검증·git으로 관리한다.

참고 자료 · GitHub 리소스

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

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

공식 자료 (1차 출처)

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

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

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

커뮤니티 큐레이션 (인기 리소스 모음)

실무자들이 가장 많이 참고하는 "awesome" 목록·툴킷입니다.

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

어떻게 활용하면 좋은가

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 등)은 바퀴를 다시 만들지 않게 해 주되, 도입 전 반드시 검토하라.
• 공식 문서로 사실을 확인하고, 아티클로 원리를 잡고, 커뮤니티로 자산을 찾는 순서가 안전하다.