클로드코드 완전가이드

0.1이 가이드를 읽는 법

이 시리즈는 공식 문서를 대체하려고 만든 것이 아닙니다. 공식 문서는 기능별로 배열돼 있어서 무엇이 있는지 찾기에는 좋지만, 지금 내 수준에서 다음에 무엇을 배워야 하는지는 알려주지 않습니다. 여기서 한 일은 같은 내용을 능력 단계 순으로 다시 깔아 놓은 것입니다. 어떤 사실이 의심스러우면 각 문단 끝의 각주를 눌러 원문을 확인하시면 됩니다. 정본은 항상 공식 문서입니다.

실전기준으로 삼은 공식 문서는 185편입니다. 본문 136편, Agent SDK 32편, 주간 릴리스 다이제스트 17편입니다. 이 숫자는 공식 문서 색인 두 곳을 각각 받아 대조해 얻었고, 두 목록은 185편에서 정확히 일치했습니다. 아래 명령으로 같은 값을 다시 확인할 수 있습니다.

# 문서 목록 두 곳을 받아 편수를 센다(2026-08-11 기준 양쪽 모두 185)
curl -s https://code.claude.com/docs/llms.txt | grep -c '^- \[.*](https://code.claude.com/docs/'
curl -s https://code.claude.com/docs/sitemap.xml | grep -o '<loc>[^<]*/docs/en/[^<]*' | wc -l

각 편은 완료 기준을 하나씩 갖고 있습니다. 그 일을 실제로 해 봤으면 그 편은 끝난 것이고, 못 했으면 다음 편으로 넘어가도 겉핥기가 됩니다.

여덟 편 모두 발행돼 있습니다. 화면 맨 위 고정 바에서 어느 편으로든 바로 갈 수 있고, 그 목록은 각 편의 본문 유무로 자동 생성되므로 이 본문보다 항상 최신입니다.

출처 라벨 3종

이 시리즈의 모든 실질 주장은 세 라벨 중 하나로 시작합니다. 근거의 등급을 문장 단위로 드러내려는 것입니다. 무엇을 그대로 믿고 무엇을 자기 환경에서 다시 확인해야 하는지가 읽는 중에 바로 보입니다.

실전이 규격이 실제로 어떻게 지켜지고 있는지도 재 봤습니다. 지금 발행된 네 편(L0부터 L3)의 본문에는 라벨이 617건 붙어 있고, 그중 공식 564건, 관행 19건, 실전 34건입니다. 인용한 공식 문서는 고유 61편으로, 전체 185편의 33퍼센트입니다. 분포가 공식 쪽으로 크게 기울어 있다는 뜻이고, 이는 약점입니다. 현장 관행과 직접 실행 근거가 더 필요합니다. 같은 값은 아래 명령으로 셀 수 있습니다.

# 발행된 편의 본문에서 라벨 종류별 개수와 인용 문서 수를 센다
grep -o 'class="src \(official\|field\|own\)"' L*/index.html | sort | uniq -c
grep -o 'https://code.claude.com/docs/en/[a-z-]*' L*/index.html | sort -u | wc -l

안 읽어도 되는 편

7편을 다 읽어야 하는 사람은 없습니다. 아래는 건너뛰어도 되는 경우입니다.

• 혼자 쓰고 팀에 배포할 일이 없다면 L6은 넘어갑니다.
• CI나 스크립트에서 부를 계획이 없다면 L5는 필요할 때 옵니다.
• 한 작업이 한 세션 안에서 끝나는 규모라면 L4도 미뤄도 됩니다.
• 반대로 L1과 L2는 건너뛰지 않는 편이 좋습니다. 이 두 편을 비우고 L3의 확장 기능을 배우면, 잘못된 지시와 넓은 권한을 그대로 증폭하게 됩니다.

0.2역할별 3트랙

레벨은 순서지만, 어디까지 갈지는 역할이 정합니다. 세 갈래로 나눠 두었습니다. 자기 역할이 둘에 걸쳐 있으면 더 넓은 쪽을 고르면 됩니다.

관리자 트랙만 순서가 다릅니다. L1을 뒤로 미루는 이유는 관리자가 결정해야 하는 것이 손놀림이 아니라 경계이기 때문입니다. 다만 L0은 건너뛰지 않는 편이 좋습니다. 한 번도 세션을 열어 보지 않고 정책을 정하면, 실제로 아무도 쓰지 못하는 규칙이 나옵니다.

공식관리자 트랙이 실무자 트랙과 갈리는 실제 이유는 가용 기능이 인증 방식과 플랜에 따라 달라진다는 점입니다. 클로드코드 CLI와 로컬에서 도는 것은 모든 공급자에서 동작하지만, 웹과 모바일, 데스크톱, Slack 연동, 리모트 컨트롤, 컴퓨터 조작, 아티팩트는 claude.ai 계정 로그인을 요구합니다. API 키나 제3자 공급자로는 닿지 않습니다. feature-availability

공식플랜 안에서도 갈립니다. 컴퓨터 조작과 디스패치는 Pro와 Max에만 있고 Team과 Enterprise에는 없습니다. 반대로 코드 리뷰와 사용량 분석 대시보드, 서버 관리형 설정은 Team과 Enterprise에만 있습니다. 리모트 컨트롤과 채널은 Team과 Enterprise에서 관리자가 켜야 열립니다. feature-availability

왜 확장보다 손놀림이 먼저인가

실전이 순서가 취향이 아니라는 근거를 하나 두겠습니다. 필자가 클로드코드로 운영하는 작업 볼트의 로그를 재 봤습니다. 2026-07-07부터 2026-08-11까지 기록된 응답 턴 1,858건에서, 도구 호출은 Bash 12,154회, Edit 7,028회, Read 3,586회, Write 2,132회로 기본 도구가 압도적입니다. 반면 스킬이 발동한 턴은 73건(3.9퍼센트), 서브에이전트를 쓴 턴은 93건(5.0퍼센트)입니다. 스킬과 훅과 서브에이전트를 갖춰 놓은 환경에서도 실제 시간의 대부분은 읽고 고치고 돌리는 기본 동작에 쓰입니다.

읽는 방식이 여기서 나옵니다. 확장을 먼저 배우면 3.9퍼센트를 다듬으면서 96퍼센트를 방치하게 됩니다. L1과 L2가 그 96퍼센트를 다룹니다. L3의 확장은 그 기본 동작 중 반복이 확인된 것을 도구로 옮기는 작업이고, 반복이 확인되기 전에는 옮길 대상 자체가 없습니다.

0.35분 자기진단

6문항입니다. 각 문항은 "안다"가 아니라 "해 봤다"를 묻습니다. 읽어서 아는 것과 손으로 해 본 것은 다음 편에서 갈립니다. 솔직하게 세면 5분 안에 끝납니다.

3번과 4번이 함께 묶인 이유가 있습니다. 지침 파일을 만들어 두는 것과 그것을 줄여 본 것은 다른 능력입니다. 권한도 같습니다. 승인 버튼을 누르는 것과 규칙을 적는 것은 다른 일이고, 규칙을 적기 시작하면 자기가 무엇을 허용하고 있었는지 처음 보게 됩니다.

진단을 자기 프로젝트에 적용하기

기억에 의존하지 않고 파일로 확인할 수 있습니다. 아래 명령이 3번부터 6번까지의 답을 대신 냅니다.

# 3번: 지침 파일이 있는가
ls CLAUDE.md .claude/CLAUDE.md ~/.claude/CLAUDE.md 2>/dev/null

# 4번: 권한 규칙을 적어 뒀는가(빈 결과면 규칙이 없다)
grep -o '"\(allow\|deny\|ask\)"' .claude/settings*.json ~/.claude/settings.json 2>/dev/null

# 5번: 스킬·훅·서브에이전트가 있는가
ls .claude/skills/*/SKILL.md .claude/agents/* 2>/dev/null
grep -o '"\(PreToolUse\|PostToolUse\|Stop\|SessionStart\|UserPromptSubmit\)"' \
  .claude/settings.json ~/.claude/settings.json 2>/dev/null | sort -u

# 6번: 워크트리로 병렬 세션을 돌린 적이 있는가
ls .claude/worktrees 2>/dev/null

실전같은 진단을 필자의 작업 볼트에 돌린 결과를 그대로 적어 둡니다. 지침 파일 9개(그중 계층 거버넌스로 실제 동작하는 것 6개), 훅 핸들러 10개(SessionStart 7, Stop 2, UserPromptSubmit 1), 스킬 2개, 서브에이전트 1개, 활성 플러그인 2개, MCP 서버는 사용자 스코프 1개이고 프로젝트 .mcp.json은 없습니다. 워크트리와 워크플로 정의는 0개입니다. 진단 결과는 L3 진행 중, L4 미착수입니다.

실전같은 측정에서 드러난 결함도 함께 적습니다. 권한 규칙이 프로젝트 설정에는 0건이고, 로컬 설정에 allow만 16건 쌓여 있으며 deny와 ask는 각각 0건입니다. 이것은 권한을 설계한 상태가 아니라 승인할 때마다 자동으로 누적된 상태입니다. 4번 문항에 "예"라고 답할 뻔했지만, 파일을 열어 보니 아니었습니다. 진단을 파일로 하라고 쓴 이유가 이것입니다.

0.4표면 선택 요약

공식클로드코드는 어디서 실행하든 같은 엔진을 씁니다. 표면이 다른 것은 작업 방식에 맞춘 껍데기입니다. 실행 위치는 6곳입니다. platforms

공식같은 프로젝트에서 표면을 섞어 쓸 수 있습니다. 로컬 표면끼리는 설정과 프로젝트 메모리, MCP 서버가 공유됩니다. 다만 클라우드 세션은 저장소를 새로 클론한 상태에서 시작하고 내 기기의 ~/.claude/를 읽지 않습니다. platforms glossary

공식Slack과 Chrome은 표면이 아니라 표면에 붙는 연동입니다. 연동은 여섯 종이 정리돼 있습니다. Chrome(로그인된 브라우저 조작), GitHub Actions, GitLab CI/CD, 코드 리뷰(모든 PR 자동 검토), Slack(@Claude 멘션 응답), Claude Tag(조직 공용 신원으로 동작)입니다. platforms

표면별로 어떤 기능이 있고 없는지는 부록 C의 대조표에 정리해 두었습니다. 설치와 표면 고르기를 실제로 해 보는 것은 L0 2장과 3장입니다.

0.5무엇이 최근에 바뀌었나

클로드코드는 주 단위로 바뀝니다. 그래서 이 가이드에서 가장 빨리 낡는 부분이 기능 목록이고, 독자가 직접 최신을 확인하는 방법을 아는 것이 그 목록을 외우는 것보다 오래 쓰입니다. 공식 갱신 창구는 두 개인데 역할이 다릅니다.

공식주간 다이제스트는 각 주 항목에 버전 범위가 붙어 있습니다. 예를 들어 29주 항목은 v2.1.207부터 v2.1.212까지에 해당합니다. 자기 버전보다 나중 범위의 기능은 아직 없는 것이므로, 안 되는 기능을 붙잡고 설정을 뒤지기 전에 이 범위를 먼저 봅니다. whats-new

공식changelog는 GitHub의 CHANGELOG.md에서 생성됩니다. 자기 버전은 claude --version으로 확인합니다. changelog

claude --version

공식이 가이드가 기준으로 삼은 시점의 최신 버전은 2026-08-08 배포된 v2.1.226입니다. 최근 세 주의 굵은 변화는 이렇습니다. 29주에는 발행한 아티팩트가 보는 사람 각자의 MCP 커넥터로 실시간 데이터를 끌어오게 됐고, 스크린 리더 모드가 추가됐습니다. 28주에는 데스크톱에 내장 브라우저가 들어오고 /doctor가 진단에서 수정 제안까지 하는 설정 점검으로 확장됐습니다. 27주에는 Claude Sonnet 5가 기본 모델이 되고, Chrome 연동이 정식 출시되고, 서브에이전트가 기본으로 백그라운드에서 돌게 됐습니다. changelog whats-new

이 가이드 자체를 어떻게 최신으로 유지하는지, 그리고 독자가 직접 대조하는 절차는 부록 G에 적어 두었습니다.

1.1챗봇이 아니라 에이전트

공식클로드코드는 파일을 읽고, 코드를 고치고, 명령을 실행하고, 개발 도구와 연동하는 에이전틱 코딩 도구입니다. 터미널, IDE, 데스크톱 앱, 브라우저에서 쓸 수 있습니다. overview

공식일반 AI 채팅과 갈리는 지점은 도구입니다. 도구가 없으면 모델은 텍스트로만 답할 수 있고, 도구가 있으면 직접 행동할 수 있습니다. 공식 문서는 이 차이를 "당신이 직접 적용해야 하는 텍스트만 돌려주는 채팅형 보조"와 "스스로 파일을 읽고 명령을 실행하며 변경하는 방식"의 대비로 설명합니다. glossary

공식기본 도구는 크게 다섯 갈래입니다. how-claude-code-works

1.2에이전트 루프

공식클로드는 모든 작업을 세 국면으로 돌립니다. 맥락 수집, 행동, 결과 검증. 그리고 끝날 때까지 반복합니다. 국면은 뚜렷이 나뉘지 않고 섞이며, 도구 사용 결과가 다음 판단의 재료가 됩니다. how-claude-code-works

공식"실패하는 테스트를 고쳐 주세요"라고 하면 실제로는 이런 순서가 돕니다. how-claude-code-works

1. 테스트를 돌려 무엇이 실패하는지 봅니다.
2. 오류 출력을 읽습니다.
3. 관련 소스 파일을 찾습니다.
4. 그 파일들을 읽어 코드를 이해합니다.
5. 파일을 고쳐 문제를 해결합니다.
6. 테스트를 다시 돌려 확인합니다.

공식사용자도 이 루프의 일부입니다. 언제든 끼어들어 방향을 틀 수 있습니다. Esc를 누르면 즉시 멈추고 실행 중이던 도구 호출이 취소됩니다. 멈추지 않고 교정만 주고 싶으면 정정 문장을 입력해 Enter를 누르면, 클로드가 현재 동작을 마친 직후 그것을 읽고 다음 판단을 바꿉니다. how-claude-code-works

1.3잘하는 일과 못하는 일

공식코딩에 강하지만 코딩 전용은 아닙니다. 공식 문서는 "명령줄에서 할 수 있는 일이라면 무엇이든" 도울 수 있다고 적습니다. 문서 작성, 빌드 실행, 파일 검색, 주제 조사가 모두 여기 들어갑니다. how-claude-code-works

공식여러 파일에 걸친 작업이 특히 다릅니다. 현재 파일만 보는 인라인 코드 보조와 달리, 프로젝트 전체를 보기 때문에 관련 파일을 검색해 여러 개를 읽고 조율된 수정을 한 뒤 테스트로 확인하고, 요청하면 커밋까지 합니다. how-claude-code-works

반대로 처음 쓰는 사람이 자주 부딪히는 한계는 세 가지입니다. 셋 다 공식 문서가 명시한 동작이고, 뒤 레벨에서 다루는 기능들이 대부분 이 셋을 다루기 위한 것입니다.

1.4용어는 다섯 개면 충분합니다

공식 용어집에는 수십 개가 있지만, 첫날 필요한 것은 다섯 개입니다. 나머지는 그 기능을 쓸 때 그 자리에서 배우면 됩니다.

정의 출처: glossary

2.1어디서 쓸 수 있나

공식어디서 쓰든 같은 엔진이 돕니다. 다른 것은 코드가 실행되는 위치와 조작 방식입니다. 로컬 표면끼리는 설정, 프로젝트 메모리, MCP 서버를 공유하므로 한 프로젝트에서 여러 표면을 섞어 쓸 수 있습니다. platforms

공식표면과 별개로 외부 서비스를 붙이는 통합이 있습니다. 브라우저를 조작하는 Chrome, CI에서 도는 GitHub Actions와 GitLab CI/CD, 모든 PR을 자동 리뷰하는 Code Review, 팀 채팅에서 @Claude를 부르는 Slack입니다. 공식 문서는 Slack과 Chrome 확장을 표면이 아니라 표면에 연결되는 통합으로 분류합니다. platforms

2.2처음이면 무엇으로 시작할까

공식공식 권고는 간단합니다. 어디서 시작할지 모르겠으면 CLI를 깔아 프로젝트 폴더에서 실행하고, 터미널을 쓰고 싶지 않다면 데스크톱 앱을 쓰라고 안내합니다. 데스크톱 앱은 같은 엔진을 그래픽 화면으로 제공합니다. platforms

관행실제로 갈리는 기준은 직무보다 터미널에 대한 거부감입니다. 터미널 창을 열어 명령을 한 줄 치는 것이 부담이 아니라면 CLI가 낫습니다. 기능이 가장 많고, 이후 자동화로 넘어갈 때 그대로 이어집니다. 반대로 터미널 자체가 진입 장벽이면 데스크톱 앱에서 시작해도 됩니다. 나중에 CLI를 깔아도 설정과 지침 파일을 공유하므로 다시 배우는 것이 아닙니다.

2.3계정과 요금제

공식클로드코드는 계정이 있어야 씁니다. Pro, Max, Team, Enterprise 구독이나 Claude Console 계정이 필요하고, 무료 Claude.ai 플랜에는 클로드코드 접근이 포함되지 않습니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 같은 서드파티 제공자를 쓸 수도 있습니다. setup

공식Console 계정으로 처음 로그인하면 비용 추적을 위해 Console에 "Claude Code" 워크스페이스가 자동으로 만들어집니다. quickstart

공식표면에 따라 요금제 조건이 붙는 기능이 있습니다. 데스크톱 앱은 유료 구독이 필요하고, 컴퓨터 조작과 Dispatch는 Pro와 Max에서 제공됩니다. platforms

3.1터미널: macOS, Linux, WSL

공식먼저 시스템 요구사항입니다. setup

공식권장 설치는 네이티브 설치 스크립트입니다. setup

macOS, Linux, WSL

curl -fsSL https://claude.ai/install.sh | bash

공식Homebrew로도 깔 수 있습니다. 캐스크가 두 개이고 받는 버전이 다릅니다. claude-code는 안정 채널로 보통 1주 정도 뒤처지며 큰 회귀가 있는 릴리스를 건너뜁니다. claude-code@latest는 최신 채널로 나오는 즉시 받습니다. setup

brew install --cask claude-code

공식Debian, Fedora, RHEL, Alpine에서는 서명된 apt, dnf, apk 저장소로도 설치할 수 있습니다. setup

설치 확인

claude --version

공식정상이면 2.1.211 (Claude Code)처럼 버전 번호와 (Claude Code)가 출력됩니다. setup

3.2터미널: Windows

공식Windows는 설치 명령이 셸에 따라 다릅니다. PowerShell과 CMD는 문법이 달라 서로의 명령이 듣지 않습니다. setup

Windows PowerShell

irm https://claude.ai/install.ps1 | iex

Windows CMD

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

공식WinGet도 지원합니다. 자동 업데이트는 되지 않으므로 winget upgrade Anthropic.ClaudeCode를 주기적으로 실행합니다. setup

winget install Anthropic.ClaudeCode

공식Windows에서는 네이티브로 돌릴지 WSL 안에서 돌릴지 고를 수 있습니다. 프로젝트가 어디 있는지와 어떤 기능이 필요한지로 결정합니다. setup

공식네이티브 Windows에서는 관리자 권한이 필요하지 않습니다. Git for Windows는 필수가 아니지만 설치하면 Git Bash를 제공해 Bash 도구가 켜집니다. 없으면 클로드코드가 PowerShell 도구로 셸 명령을 실행합니다. WSL 환경은 Git for Windows가 필요하지 않습니다. setup

화면을 그대로 따라가며 설치하고 싶다면 실제 캡처로 만든 별도 가이드가 있습니다.

• Windows에서 Claude Code 설치하기: 데스크톱 앱 기준, 실제 화면 11장

3.3데스크톱 앱

공식데스크톱 앱에는 탭이 세 개 있습니다. Chat은 파일 접근이 없는 일반 대화, Cowork는 샌드박스 가상 머신에서 독립적으로 일하는 자율 백그라운드 에이전트, Code는 로컬 파일에 직접 접근하며 변경을 실시간으로 검토하고 승인하는 코딩 화면입니다. 클로드코드로 코딩하려면 Code 탭입니다. desktop-quickstart

공식첫 세션은 이 순서로 시작합니다. desktop-quickstart

1. 설치하고 로그인한 뒤 상단 가운데 Code 탭을 누릅니다. 업그레이드 안내가 나오면 유료 플랜이 필요한 상태입니다.
2. 실행 환경을 고릅니다. Local은 내 컴퓨터에서 내 파일로 돌립니다. 그 밖에 Cloud(앱을 닫아도 계속됨), SSH(원격 머신), Windows의 WSL이 있습니다.
3. Select folder를 눌러 프로젝트 폴더를 고릅니다. 공식 문서는 잘 아는 작은 프로젝트로 시작하기를 권합니다.
4. 보내기 버튼 옆 드롭다운에서 모델을 고릅니다. 나중에 같은 드롭다운에서 바꿀 수 있습니다.
5. 할 일을 적습니다. 예: Find a TODO comment and fix it

공식Code 탭은 기본적으로 Manual 모드로 시작합니다. 클로드가 변경을 제안하고 승인을 기다리며, 어느 파일이 어떻게 바뀌는지 보여주는 변경 비교 화면과 Accept/Reject 버튼이 나옵니다. 승인하기 전까지 파일은 바뀌지 않습니다. 거부하면 클로드가 어떻게 다르게 진행할지 되묻습니다. desktop-quickstart

3.4VS Code와 JetBrains

공식VS Code 확장은 인라인 변경 비교, @멘션, 계획 검토, 대화 이력을 편집기 안에서 제공합니다. 확장 뷰에서 "Claude Code"를 검색해 설치하고(Cmd Shift X 또는 Ctrl Shift X), 명령 팔레트에서 "Claude Code"를 입력해 Open in New Tab을 고릅니다. overview

공식JetBrains 플러그인은 IntelliJ IDEA, PyCharm, WebStorm 등에서 변경 비교와 선택 영역 공유를 제공합니다. 이 플러그인은 클로드코드 CLI를 필요로 하며 CLI는 따로 설치합니다. overview

3.5웹과 모바일

공식웹은 로컬 설치 없이 브라우저에서 돌립니다. claude.ai/code에서 시작하며, 오래 걸리는 작업을 던져 두고 나중에 확인하거나, 로컬에 없는 저장소를 다루거나, 여러 작업을 병렬로 돌리는 데 맞습니다. iOS와 안드로이드 클로드 앱에서도 쓸 수 있습니다. overview

공식모바일은 그 클라우드 세션이나 원격 조작 중인 로컬 세션으로 들어가는 얇은 클라이언트입니다. platforms

3.6로그인

공식설치 후 claude를 실행하면 첫 실행에서 브라우저 창이 열립니다. 브라우저가 자동으로 열리지 않으면 c를 눌러 로그인 주소를 클립보드에 복사한 뒤 붙여 넣습니다. 로그인이 끝나면 터미널에 Login successful이 표시되고 Enter를 누르라는 안내가 나옵니다. authentication

공식계정을 바꾸거나 다시 인증하려면 세션 안에서 /login, 로그아웃은 /logout입니다. 로그아웃은 첫 실행 설정 상태도 초기화하므로 다음 실행에서 로그인과 초기 설정을 다시 안내합니다. authentication

공식자격 증명 저장 위치는 운영체제마다 다릅니다. macOS는 암호화된 키체인, Linux는 ~/.claude/.credentials.json(파일 모드 0600), Windows는 %USERPROFILE%\.claude\.credentials.json이며 사용자 프로필 디렉터리의 접근 제어를 따릅니다. authentication

3.7설치가 막힐 때

공식먼저 진단 명령 두 개입니다. claude --version이 버전을 찍는지 보고, 더 자세히 보려면 claude doctor를 실행합니다. 세션을 시작하지 않고 설치 상태, 설정 파일 검증 오류, 경고와 권장 조치를 읽기 전용으로 출력합니다. setup

claude doctor

공식공식 문서에 증상별 대응표가 있습니다. 처음 설치에서 자주 나오는 것만 옮기면 다음과 같습니다. troubleshoot-install

전체 표와 각 항목의 해결 절차는 공식 문서에 있습니다: troubleshoot-install

3.8터미널 다듬기

공식클로드코드는 설정 없이 어느 터미널에서나 돕니다. 이 절은 특정 동작이 기대와 다를 때만 필요합니다. terminal-config

줄바꿈이 안 될 때

공식Enter는 전송입니다. 줄바꿈은 Ctrl J를 누르거나 \를 입력한 뒤 Enter를 누르면 되고, 이 둘은 모든 터미널에서 설정 없이 동작합니다. Shift Enter는 터미널에 따라 다릅니다. terminal-config

작업이 끝난 것을 소리로 알고 싶을 때

공식기본적으로 데스크톱 알림은 Ghostty, Kitty, iTerm2에서만 나갑니다. 다른 터미널에서는 설정으로 터미널 벨을 켤 수 있습니다. terminal-config

~/.claude/settings.json

{
  "preferredNotifChannel": "terminal_bell"
}

tmux 안에서 쓸 때

공식tmux 안에서는 두 가지가 기본적으로 깨집니다. Shift Enter가 줄바꿈 대신 전송되고, 데스크톱 알림과 진행 표시가 바깥 터미널에 닿지 않습니다. ~/.tmux.conf에 아래를 넣고 tmux source-file ~/.tmux.conf로 적용합니다. terminal-config

~/.tmux.conf

set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

그 밖에

• 공식macOS에서 Option 키 단축키가 먹지 않으면 터미널의 "Use Option as Meta Key" 설정을 켭니다(iTerm2는 Left/Right Option을 "Esc+"로).
• 공식화면이 깜박이거나 스크롤이 튀면 /tui fullscreen으로 전체화면 렌더링으로 바꿉니다. 설정이 저장되고 이후 세션도 그 모드로 시작합니다.
• 공식색 테마는 /theme로 고릅니다. 자동 옵션은 터미널의 밝은·어두운 배경을 감지합니다.
• 공식800자 또는 두 줄을 넘겨 붙여 넣으면 입력창이 [Pasted text #1 +120 lines]처럼 접힙니다. 전체 내용은 전송될 때 그대로 들어갑니다. 파일 전체나 긴 로그처럼 아주 큰 입력은 붙여 넣지 말고 파일로 저장한 뒤 읽으라고 하는 편이 낫습니다.

출처: terminal-config

4.1첫 질문에서 첫 수정까지

공식작업할 프로젝트 폴더로 이동해 실행합니다. quickstart

cd /path/to/your/project
claude

공식프롬프트 위에 버전, 현재 모델, 작업 디렉터리가 표시됩니다. /help로 쓸 수 있는 명령을 보고, /resume으로 이전 대화를 이어갈 수 있습니다. quickstart

공식첫 질문은 코드베이스 파악으로 시작하는 것이 좋습니다. 공식 문서가 제시하는 예시는 이런 것들입니다. 클로드코드는 필요한 만큼 프로젝트 파일을 알아서 읽으므로 맥락을 직접 넣어 줄 필요가 없습니다. quickstart

what does this project do?
what technologies does this project use?
where is the main entry point?
explain the folder structure

관행한국어로 물어도 됩니다. 지시 언어와 응답 언어는 설정으로 바꿀 수 있고, 위 예시는 공식 문서 원문이라 영어로 옮겼습니다.

공식다음은 실제 수정입니다. 이렇게 지시하면 클로드코드는 적절한 파일을 찾고, 제안할 변경을 보여주고, 권한 모드에 따라 승인을 요청한 뒤, 수정합니다. quickstart

add a hello world function to the main file

4.2승인 화면 읽는 법

공식클로드가 파일을 바꾸기 전에 물어보는지는 권한 모드가 정합니다. 터미널에서는 Shift Tab으로 모드를 순환합니다. how-claude-code-works

모드 설명 출처: how-claude-code-works, glossary

공식승인을 매번 받지 않으려면 .claude/settings.json에 특정 명령을 허용해 둘 수도 있습니다. npm test나 git status처럼 신뢰하는 명령에 유용합니다. how-claude-code-works

4.3첫 커밋

공식git 작업은 대화로 합니다. 공식 문서의 예시는 다음과 같습니다. quickstart

what files have I changed?
commit my changes with a descriptive message
create a new branch called feature/quickstart
show me the last 5 commits
help me resolve merge conflicts

공식클로드코드는 현재 브랜치, 커밋되지 않은 변경, 최근 커밋 이력을 볼 수 있습니다. 그래서 무엇이 바뀌었는지 묻는 것부터 커밋과 PR 생성까지 이어집니다. how-claude-code-works

4.4되돌리기

공식클로드가 파일을 고치기 전에 그 파일의 현재 내용을 저장해 둡니다. 잘못됐으면 Esc를 두 번 누르거나 /rewind를 실행해 이전 상태로 돌아갈 수 있습니다. 체크포인트는 프롬프트를 보낼 때마다 하나씩 만들어집니다. checkpointing

공식메뉴는 그 세션에서 보낸 프롬프트 목록을 보여주고, 지점을 고르면 아래 중에서 선택합니다. checkpointing

공식체크포인트는 대화와 함께 저장되므로 세션을 다시 열어도 /rewind가 됩니다. 한 세션에서 가장 최근 100개의 체크포인트를 유지하고, 세션과 함께 30일 후에 삭제됩니다. checkpointing

공식세션을 끝내는 것은 /exit 또는 Ctrl D 두 번, 대화 이력을 비우는 것은 /clear입니다. /clear는 새 세션을 시작하며 이전 세션은 저장돼 /resume으로 다시 열 수 있습니다. quickstart, glossary

4.5화면 읽기와 음성 입력

공식스크린 리더로 쓰는 모드가 따로 있습니다. 그 모드에서는 클로드코드가 전체화면 렌더링 대신 항상 평범한 스크롤 텍스트로 출력합니다. accessibility, terminal-config

공식타이핑 대신 말로 입력할 수도 있습니다. /voice로 켜고, 키를 누르고 있는 동안 녹음하는 hold 방식과 한 번 눌러 시작하고 다시 눌러 전송하는 tap 방식이 있습니다. 기본은 hold이고 기본 키는 Space입니다. voice-dictation

/voice        켜기와 끄기를 번갈아, 현재 방식 유지
/voice hold   누르고 있는 동안 녹음
/voice tap    한 번 눌러 시작, 다시 눌러 전송
/voice off    끄기

공식한국어를 지원합니다(언어 코드 ko). 받아쓰기 언어는 클로드의 응답 언어를 정하는 language 설정을 함께 씁니다. 비어 있으면 영어로 동작하므로, 한국어로 말하려면 /config에서 언어를 먼저 지정합니다. voice-dictation

5.1좋은 지시의 구성요소

공식가장 중요한 하나는 검증 수단입니다. 공식 문서는 이렇게 적습니다. 클로드는 일이 다 된 것처럼 보이면 멈춥니다. 직접 돌려 볼 수 있는 검사가 없으면 "다 된 것처럼 보인다"가 유일한 신호이고, 사용자가 검증 루프가 됩니다. 통과와 실패를 내는 것을 주면 루프가 스스로 닫힙니다. best-practices

공식검사는 대화에서 클로드가 읽을 수 있는 신호를 내는 것이면 무엇이든 됩니다. 테스트 스위트, 빌드 종료 코드, 린터, 출력을 픽스처와 대조하는 스크립트, 디자인과 비교할 브라우저 스크린샷. best-practices

정리하면 지시에 네 가지가 들어갑니다.

공식검사를 만든 뒤에는 그것이 얼마나 강하게 종료를 막을지 고를 수 있습니다. 한 프롬프트 안에서 검사를 돌리고 반복하라고 적는 것이 가장 가볍고, 세션 전체에 걸어 두는 것이 /goal이며(5.5), 결정적으로 막는 것이 Stop 훅입니다. 뒤로 갈수록 설정 비용이 늘고 주의 비용이 줄어듭니다. best-practices

5.2같은 작업, 두 가지 지시

공식공식 문서가 제시하는 전후 대조입니다. 왼쪽이 흔한 지시이고 오른쪽이 같은 목적을 정확하게 적은 것입니다. 원문이 영어라 그대로 옮깁니다. best-practices

공식다만 모호한 지시가 늘 나쁜 것은 아닙니다. 탐색 중이고 방향을 틀 여유가 있을 때는 what would you improve in this file? 같은 질문이 물어볼 생각조차 못 했던 것을 끌어냅니다. best-practices

5.3작업을 쪼개는 기준

공식큰 작업은 탐색, 계획, 구현, 커밋 네 국면으로 나누는 것이 권장 흐름입니다. 플랜 모드로 들어가 파일을 읽히고, 계획을 만들게 하고, 승인한 뒤 구현하게 하고, 마지막에 커밋합니다. best-practices

플랜 모드로 시작하기

claude --permission-mode plan

공식세션 중에는 Shift Tab으로 플랜 모드로 순환합니다. 플랜 모드가 켜져 있으면 상태 표시줄에 plan mode on이 보입니다. 계획을 편집기에서 직접 고치려면 Ctrl G를 누릅니다. best-practices

공식더 큰 기능이라면 클로드에게 먼저 나를 인터뷰하게 하는 방법도 있습니다. 최소한의 설명으로 시작해 기술 구현, 화면, 예외 상황, 트레이드오프를 캐묻게 하고 그 결과를 명세 파일로 쓰게 합니다. 그다음 새 세션에서 그 명세를 실행합니다. 새 세션은 구현에만 집중된 깨끗한 맥락을 갖습니다. best-practices

5.4중간 개입

공식가장 좋은 결과는 짧은 피드백 루프에서 나옵니다. 어긋나는 것이 보이면 즉시 교정하는 편이 더 나은 답을 더 빨리 만듭니다. best-practices

공식맥락에 남기고 싶지 않은 짧은 질문은 /btw로 물어볼 수 있습니다. 답은 닫을 수 있는 오버레이로 표시되고 대화 이력에 들어가지 않습니다. best-practices

5.5목표를 붙잡아 두기

공식/goal은 완료 조건을 걸어 두는 명령입니다. 매 턴이 끝날 때마다 작고 빠른 모델이 조건이 충족됐는지 확인하고, 아니면 사용자에게 제어를 돌려주는 대신 클로드가 다음 턴을 시작합니다. 조건이 충족되면 목표는 자동으로 해제됩니다. goal

/goal all tests in test/auth pass and the lint step is clean

공식목표를 설정하면 그 조건 자체를 지시로 삼아 바로 한 턴이 시작됩니다. 별도 프롬프트가 필요 없습니다. 세션당 하나만 활성화되고, 인자 없이 /goal을 실행하면 조건, 경과 시간, 평가된 턴 수, 토큰 소비, 평가자의 최근 판단 이유를 보여줍니다. /goal clear로 해제합니다. goal

공식오래 버티는 조건에는 보통 세 가지가 들어갑니다. 측정 가능한 하나의 종료 상태(테스트 결과, 빌드 종료 코드, 파일 개수, 빈 대기열), 증명 방법의 명시(npm test가 0으로 끝난다), 그리고 도중에 바뀌면 안 되는 제약. 조건은 4,000자까지이고, or stop after 20 turns처럼 턴이나 시간 제한을 조건에 넣어 실행 길이를 묶을 수 있습니다. goal

공식목표는 권한을 바꾸지 않습니다. 기본 모드에서는 허용되지 않은 도구 호출마다 여전히 물어봅니다. goal

5.6판단이 어려울 때

공식어드바이저 도구는 클로드가 작업 중요 지점에서 두 번째, 보통 더 강한 모델에게 자문하게 합니다. 접근 방식을 확정하기 전, 같은 오류가 반복될 때, 작업을 완료로 선언하기 전이 그 지점입니다. 어드바이저는 모든 도구 호출과 결과를 포함한 전체 대화를 받고, 클로드는 받은 지침을 반영해 계속합니다. advisor

/advisor opus     어드바이저 모델 지정(설정에 저장됨)
/advisor          선택 목록 열기
/advisor off      끄기

공식어드바이저는 메인 모델과 같거나 더 강해야 합니다. 대표적인 조합은 Sonnet을 메인으로 두고 Opus를 어드바이저로 붙이는 것입니다. 루틴 작업은 Sonnet이 처리하고, 계획과 애매한 실패와 완료 판정만 Opus로 올립니다. advisor

6.1입력창 접두어

공식입력창의 첫 글자가 그 입력의 종류를 정합니다. interactive-mode

공식@는 파일뿐 아니라 디렉터리와 MCP 리소스도 받습니다. 디렉터리는 목록을 주고 내용을 주지 않으며, MCP 리소스는 @server:resource 형식입니다. 한 메시지에 여러 개를 참조할 수 있습니다. common-workflows

6.2핵심 단축키

공식전체 표는 공식 문서에 있고, 매일 쓰는 것만 옮깁니다. interactive-mode

공식키를 직접 바꾸려면 /keybindings로 키바인딩 파일을 엽니다. 위 표는 터미널이 클로드코드에 보내는 신호를 전제하므로, 터미널 쪽 설정이 필요한 경우와 클로드코드 쪽 재정의가 필요한 경우가 다릅니다. terminal-config

6.3여러 줄 입력과 편집 모드

공식Enter는 전송입니다. 줄바꿈 방법은 네 가지이고 터미널 지원이 다릅니다. interactive-mode

공식프롬프트 입력에 Vim 방식 편집 모드가 있습니다. /config의 Editor mode에서 켜거나 설정 파일에서 editorMode를 "vim"으로 둡니다. NORMAL과 VISUAL 모드의 일부 이동과 연산자를 지원합니다(hjkl, v/V, d/c/y). 표준 Vim과 달리 INSERT 모드에서 Enter는 여전히 전송이므로, 줄바꿈은 NORMAL 모드의 o나 Ctrl J를 씁니다. terminal-config

6.4이미지 입력

공식이미지를 넣는 방법은 세 가지입니다. 창에 끌어다 놓기, 복사한 뒤 Ctrl V로 붙이기(macOS iTerm2는 Cmd V도 가능), 경로를 알려 주기. 붙이면 커서 위치에 [Image #N] 칩이 들어가 프롬프트 안에서 위치를 지정해 참조할 수 있습니다. common-workflows

공식쓰임새는 오류 화면, 화면 설계, 도표입니다. 디자인 시안을 붙여 CSS를 만들게 하거나, 구현 결과를 스크린샷으로 찍어 원본과 비교해 차이를 나열하고 고치게 하는 방식이 공식 문서의 검증 예시로 나옵니다. best-practices

[스크린샷 붙여넣기] implement this design. take a screenshot of the result
and compare it to the original. list differences and fix them

6.5상태줄 읽기

공식상태줄은 화면 아래쪽의 사용자 설정 가능한 줄이고, 설정한 셸 스크립트를 실행해 그 출력을 표시합니다. 스크립트는 표준 입력으로 세션 데이터를 JSON으로 받습니다. 기본 푸터 배지를 대체하지 않고 그 위 자기 줄에 그려집니다. statusline

공식스크립트가 받는 데이터에는 현재 모델(model.display_name), 세션 식별자(session_id), 맥락 사용량(context_window.current_usage), 최근 응답의 총 토큰이 20만을 넘는지(exceeds_200k_tokens) 같은 필드가 있습니다. statusline

7.1명령 체계 개관

공식/로 부르는 것은 세 종류가 섞여 있습니다. 내장 명령은 고정된 로직을 실행하고, 번들 스킬은 클로드에게 상세한 프롬프트를 주고 알아서 조율하게 합니다(그래서 에이전트를 띄우고 파일을 읽고 코드베이스에 맞춰 적응할 수 있습니다). 사용자 스킬과 플러그인 스킬은 직접 만들거나 설치한 것입니다. glossary

아래 7.2부터 7.6까지는 일상에서 실제로 손이 가는 순서로 묶었습니다. 전량은 7.7에 있습니다.

7.2세션과 맥락

출처: commands

7.3설정과 진단

출처: commands, best-practices

7.4모델과 속도

7.5품질

출처: commands

7.6병렬과 자동화

이 계열은 이 편의 범위를 넘습니다. 무엇이 있는지만 알아 두고, 쓰는 법은 뒤 레벨에서 다룹니다.

출처: commands

7.7전체 표

공식내장 명령 전량입니다. 공식 문서의 알파벳 목록을 옮기고, 이 시리즈에서 어디서 다루는지를 덧붙였습니다. 세션에서 /help를 치면 현재 버전에서 실제로 쓸 수 있는 목록이 나오므로, 이 표와 어긋나면 그쪽이 정답입니다. commands

/add-dir <path>        파일 접근용 작업 디렉터리 추가
/advisor [model|off]   어드바이저 도구 켜기·끄기
/agents                서브에이전트 설정 관리
/autocompact           자동 압축 시점 설정
/autofix-pr [prompt]   PR을 지켜보며 CI 실패 시 수정 푸시
/background [prompt]   백그라운드 에이전트로 분리
/batch <instruction>   대규모 변경을 병렬 조율
/branch [name]         대화 분기 생성
/btw [question]        맥락에 안 남는 곁질문
/bug [report]          버그 신고 또는 대화 공유
/cd <path>             작업 디렉터리 이동
/chrome                Chrome 연동 설정
/claude-api            Claude API 레퍼런스 로드
/clear [name]          새 대화 시작
/code-review           변경분 버그 리뷰
/color [color]         프롬프트 바 색상
/compact [instr]       대화 요약 압축
/config [key=value]    설정 화면
/context [all]         맥락 사용량 시각화
/copy [N]              마지막 응답 복사
/cost                  /usage 별칭
/dataviz [request]     차트 설계 지침
/debug [description]   디버그 로깅
/deep-research <q>     웹 검색 팬아웃 후 보고서
/design-login          디자인 시스템 접근 인증
/design-sync [hint]    디자인 시스템 변환·업로드
/desktop               데스크톱 앱에서 계속
/diff                  변경 비교 화면
/doctor                설치·설정 점검
/effort [level|auto]   추론 노력 수준
/exit                  종료
/export [filename]     대화 평문 내보내기
/fast [on|off]         빠른 모드 토글
/feedback [report]     제품 피드백
/fewer-permission-prompts  승인 창 줄이기
/focus                 포커스 뷰 토글
/fork [prompt]         대화를 새 백그라운드 세션으로 복사
/goal [condition|clear]  완료 조건 설정
/heapdump              메모리 진단용 힙 스냅샷
/help                  도움말과 명령 목록
/hooks                 훅 설정 보기
/ide                   IDE 연동 관리
/import [codex|gemini] 다른 에이전트 설정 가져오기
/init                  CLAUDE.md 생성
/insights              세션 분석 보고서
/install-github-app    GitHub 앱 설치
/install-slack-app     Slack 앱 설치
/keybindings           단축키 파일 열기
/list-agents           서브에이전트·세션 목록
/login                 로그인
/logout                로그아웃
/loop [interval] [p]   프롬프트 주기 반복
/mcp                   MCP 서버 관리
/memory                메모리 파일 편집
/mobile                모바일 앱 QR 코드
/model [model]         모델 전환
/permissions           승인 규칙 설정
/plan                  플랜 모드
/resume [id]           이전 대화로
/rewind                코드·대화 되돌리기
/security-review       변경분 보안 점검
/settings              /config 별칭
/simplify [--fix]      코드 정리
/status                세션 상태
/subtask [prompt]      곁작업을 서브에이전트에
/tasks                 백그라운드 작업 목록
/teleport              웹 세션을 터미널로
/test                  테스트 실행
/usage                 토큰 사용량과 비용
/verify [--fix]        코드 정합성 확인
/web                   브라우저에서 claude.ai/code 열기

8.1코드 탐색 시키기

공식낯선 코드베이스에서는 넓은 질문으로 시작해 좁혀 갑니다. 공식 문서의 예시 순서입니다. common-workflows

give me an overview of this codebase
explain the main architecture patterns used here
what are the key data models?
how is authentication handled?

공식특정 기능을 찾을 때는 파일을 찾게 하고, 그 파일들이 어떻게 맞물리는지 묻고, 실행 흐름을 추적하게 하는 세 단계가 권장됩니다. common-workflows

find the files that handle user authentication
how do these authentication files work together?
trace the login process from front-end to database

공식공식 문서는 이것을 온보딩 방법으로 명시합니다. 다른 엔지니어에게 물을 질문을 그대로 물으면 되고, 특별한 프롬프트 기법이 필요하지 않습니다. 램프업 시간을 줄이고 다른 엔지니어의 부담을 낮춥니다. best-practices

use subagents to investigate how our authentication system handles token
refresh, and whether we have any existing OAuth utilities I should reuse.

8.2파일 참조와 변경 검토

공식어디에 코드가 있는지 설명하는 대신 @로 참조합니다. 클로드가 답하기 전에 그 파일을 읽습니다. 그 밖에 이미지 붙여넣기, 문서 URL 주기(/permissions로 자주 쓰는 도메인을 허용 목록에 넣을 수 있습니다), 파이프로 데이터 넣기(cat error.log | claude), 필요한 것을 클로드가 직접 가져오게 하기가 있습니다. best-practices

공식변경을 검토하는 화면은 /diff로 엽니다. 승인 화면에서 무엇이 바뀌는지 보고 통과시키는 흐름은 L0에서 다뤘습니다. commands

8.3셸 명령 실행

공식클로드는 명령줄에서 할 수 있는 것을 할 수 있습니다. 빌드 도구, git, 패키지 관리자, 시스템 유틸리티, 스크립트가 여기 들어갑니다. 사용자가 직접 실행하고 싶으면 입력창에서 ! 접두어를 씁니다. how-claude-code-works

공식외부 서비스를 다룰 때는 CLI 도구를 쓰라고 지시하는 편이 맥락 효율이 가장 좋습니다. gh, aws, gcloud, sentry-cli가 예입니다. GitHub를 쓴다면 gh CLI를 깔아 두는 것이 권장되는데, 없으면 클로드가 인증 없는 API 요청을 쓰다가 속도 제한에 걸립니다. best-practices

8.4도구가 무엇인지 알아 두기

공식승인 화면에 뜨는 이름이 도구 이름입니다. 무엇을 승인하는지 알려면 이름을 알아 두는 편이 낫습니다. 자주 보이는 것만 옮깁니다. 승인 필요 여부는 권한 모드와 규칙에 따라 달라집니다. tools-reference

전체 목록(40개 이상)은 tools-reference에 있습니다.

8.5큰 코드베이스에서

공식큰 저장소에서는 작은 프로젝트에 맞춘 기본값이 맥락을 지금 작업과 무관한 지침과 파일 읽기로 채웁니다. 가장 먼저 결정할 것은 어디서 claude를 실행할지입니다. large-codebases

공식그 밖에 이 편 수준에서 바로 쓸 수 있는 것은 두 가지입니다. 첫째, 클로드의 내용 검색은 기본적으로 .gitignore를 존중하므로 node_modules/, dist/, build/는 별도 설정 없이 검색 결과에서 빠집니다. 둘째, 타입 있는 언어라면 코드 인텔리전스 플러그인이 파일을 훑는 대신 언어 서버로 정의와 참조를 찾게 해 파일 읽기를 줄입니다. large-codebases

공식여러 패키지에 걸친 변경에는 두 가지가 도움이 됩니다. 공유 코드 수정과 그 호출처들을 한 세션에서 함께 넘기면 각 수정의 판단이 일관되게 유지됩니다. 그리고 계획을 저장소의 마크다운 파일로 쓰게 해 두면, 긴 세션이 맥락을 압축하는 동안에도 계획이 살아남습니다. large-codebases

9.1커밋, 브랜치, PR

공식PR은 create a pr for my changes처럼 바로 요청해도 되고, 단계로 나눠도 됩니다. 변경을 요약하게 하고, PR을 만들게 하고, 설명을 다듬게 하는 순서입니다. common-workflows

summarize the changes I've made to the authentication module
create a pr
enhance the PR description with more context about the security improvements

공식gh pr create로 PR을 만들면 그 세션이 해당 PR에 자동으로 연결됩니다. 나중에 claude --from-pr 1234로 그 PR에 연결된 세션만 걸러 볼 수 있고, /resume 선택 화면 검색창에 PR 주소를 붙여 넣어도 찾힙니다. common-workflows

9.2코드 리뷰 받기

공식/code-review는 GitHub 앱 없이 터미널에서 변경분을 리뷰합니다. 정확성 버그와 함께 재사용, 단순화, 효율 관점의 정리 지점을 보고합니다. 기본 대상은 업스트림보다 앞선 브랜치 커밋 + 커밋되지 않은 변경이고, 파일 경로, PR 번호, 브랜치 이름, main...my-feature 같은 범위를 인자로 줄 수 있습니다. code-review

/code-review                   현재 브랜치와 작업 트리
/code-review high              노력 수준을 올려 커버리지 확대
/code-review --fix             리뷰 후 작업 트리에 반영
/code-review main...my-feature 범위 지정

공식리뷰는 기본적으로 자기 맥락 창을 가진 백그라운드 서브에이전트로 돌기 때문에 대화를 채우지 않습니다. 결과는 끝났을 때 대화에 도착합니다. code-review

공식노력 수준이 커버리지와 확신을 교환합니다. low와 medium에서는 가장 확신하는 것만 보고해 오탐이 적고, high부터 max까지는 범위가 넓어지는 대신 덜 확실한 것도 들어옵니다. 수준을 적지 않으면 이전에 입력한 수준을 재사용합니다. code-review

관행리뷰어를 다른 세션으로 분리하는 방법도 있습니다. 공식 문서는 이것을 Writer/Reviewer 패턴으로 소개하며, 새 맥락이 코드 리뷰의 질을 높이는 이유를 클로드가 방금 쓴 코드에 편향되지 않기 때문이라고 적습니다. best-practices

9.3더 깊은 버그 찾기

공식/code-review ultra는 클라우드 샌드박스에서 리뷰어 에이전트 함대를 띄웁니다. 로컬 리뷰와 비교해 세 가지가 다릅니다. 보고된 모든 발견을 독립적으로 재현하고 검증하므로 신호가 높고, 더 큰 함대가 병렬로 탐색하므로 커버리지가 넓고, 원격에서 돌아 터미널이 비어 있습니다. ultrareview

공식기본 범위는 현재 브랜치와 기본 브랜치의 차이이고 커밋되지 않은 변경과 스테이지된 변경을 포함합니다. 다른 기준으로 비교하려면 브랜치 이름을, PR을 리뷰하려면 번호를 넘깁니다. 브랜치 리뷰는 파일 500개와 변경 줄 8,000줄까지가 기본 상한입니다. ultrareview

/code-review ultra          현재 브랜치 대 기본 브랜치
/code-review ultra develop  다른 기준 브랜치와 비교
/code-review ultra 1234     PR 번호로
/code-review ultra --fix    발견을 작업 트리에 반영

공식진행 중인 리뷰는 /tasks에서 보고 멈출 수 있습니다. 백그라운드 작업이므로 계속 일하거나 터미널을 닫아도 됩니다. ultrareview

9.4보안 점검

공식단계마다 다른 도구가 있습니다. 공식 문서가 정리한 방어 층입니다. security-guidance

공식이 편 수준에서 바로 쓸 수 있는 것은 /security-review입니다. 현재 브랜치의 변경분만 덮는다는 점을 알아 두세요. 이미 가진 코드에서 문제를 찾으려면 특정 파일이나 디렉터리를 리뷰해 달라고 세션에서 직접 요청하거나 더 깊은 스캔을 씁니다. 어느 쪽이든 리뷰는 체크아웃의 소스 코드를 읽고, 돌아가는 사이트나 배포된 서비스를 보지 않습니다. security-guidance

9.5테스트와 디버깅 루프

공식버그를 고칠 때의 권장 순서는 오류를 공유하고, 수정 방향을 몇 가지 받고, 고르게 한 뒤 적용하는 것입니다. 재현 명령과 스택 트레이스를 함께 주고, 재현 절차를 알려 주고, 간헐적인지 일관적인지 밝히는 것이 권장됩니다. common-workflows

I'm seeing an error when I run npm test
suggest a few ways to fix the @ts-ignore in user.ts
update user.ts to add the null check you suggested

공식테스트는 덮이지 않은 코드를 찾고, 뼈대를 만들고, 경계 조건을 더하고, 돌려서 실패를 고치는 네 단계입니다. 클로드는 기존 테스트 파일을 살펴 이미 쓰이는 스타일, 프레임워크, 단정 패턴에 맞춥니다. common-workflows

find functions in NotificationsService.swift that are not covered by tests
add tests for the notification service
add test cases for edge conditions in the notification service
run the new tests and fix any failures

10.1세션이란 무엇인가

공식세션은 프로젝트 디렉터리에 묶인 저장된 대화입니다. 작업하는 동안 계속 로컬 기록 파일에 저장되므로, 나가거나 /clear한 뒤에도 돌아올 수 있습니다. 기록은 기본적으로 ~/.claude/projects/<project>/<session-id>.jsonl에 JSONL로 저장됩니다. sessions

공식세션은 서로 독립입니다. 새 세션은 이전 세션의 대화 없이 빈 맥락 창에서 시작합니다. 세션을 넘겨 지식을 남기는 것은 자동 메모리와 CLAUDE.md의 몫입니다. how-claude-code-works

10.2이어가기, 이름, 분기

공식여러 작업을 병행할 때는 이름을 붙여 두는 것이 가장 실용적입니다. 시작할 때 claude -n auth-refactor, 세션 중에는 /rename auth-refactor, 선택 화면에서는 Ctrl R입니다. 이름을 안 붙이면 첫 프롬프트를 요약한 제목이 자동으로 붙지만, 그 자동 제목은 이어가기 손잡이가 아닙니다. --resume <name>은 직접 지정한 이름만 찾습니다. sessions

공식선택 화면 단축키입니다. sessions

공식분기는 지금까지의 대화를 복사해 그쪽으로 옮겨 타는 것이고, 원본은 그대로 남습니다. 다른 접근을 시도하면서 지금 경로를 잃지 않으려는 용도입니다. 세션 안에서는 /branch [name], 명령줄에서는 claude --continue --fork-session입니다. sessions

10.3되돌리기를 전략으로 쓰기

되돌리기 메뉴의 사용법은 L0에서 다뤘습니다. 여기서는 그것을 작업 방식으로 쓰는 이야기입니다.

공식공식 문서의 권고는 이렇습니다. 모든 수를 조심스럽게 계획하는 대신, 위험한 것을 시도하라고 시키세요. 안 되면 되돌리고 다른 접근을 시도합니다. 체크포인트는 대화와 함께 저장되므로 터미널을 닫고 나중에 세션을 이어가서도 되돌릴 수 있습니다. best-practices

공식맥락 관리 수단으로도 씁니다. 되돌리기 메뉴에는 코드 복원 말고 요약 선택지가 두 개 있습니다. Summarize from here는 그 지점부터 뒤를 압축해 앞의 맥락을 온전히 남기고, Summarize up to here는 앞을 압축해 최근 것을 온전히 남깁니다. 장황한 디버깅 세션을 중간부터 압축하면서 초기 지시를 살리는 것이 대표 용례입니다. checkpointing

출처: prompt-caching, checkpointing

10.4표면 사이 이동

공식세션은 한 표면에 묶여 있지 않습니다. 상황이 바뀌면 옮길 수 있습니다. overview

출처: overview, platforms

10.5결과 공유

공식대화 자체를 넘기려면 /export로 클립보드에 복사하거나 평문 파일로 저장합니다. 메시지와 도구 출력이 읽을 수 있는 텍스트로 렌더링됩니다. sessions

공식터미널 텍스트가 매체로 맞지 않을 때는 아티팩트를 씁니다. 아티팩트는 세션에서 claude.ai의 비공개 주소로 발행하는 살아 있는 대화형 웹 페이지이고, 세션이 계속되면 같은 자리에서 갱신됩니다. 주석 달린 diff로 리뷰어를 안내하기, 세션이 이미 가져온 데이터로 대시보드 만들기, 선택지 여럿을 나란히 놓기, 긴 작업 중 채워지는 조사 타임라인 같은 용도입니다. artifacts

Make an artifact that walks through this PR with the diff annotated inline.

공식아티팩트는 애플리케이션이 아닙니다. 백엔드가 없는 자기완결 단일 페이지라서 폼 입력을 저장하거나 여러 경로를 서비스할 수 없습니다. 다른 세션에서 갱신하려면 그 아티팩트의 주소를 주고 고쳐 달라고 해야 하며, 주소가 없으면 새 아티팩트가 만들어집니다. artifacts

10.6링크로 세션 열기

공식딥 링크는 claude-cli:// 주소이고, 클릭하면 새 터미널 창에서 클로드코드가 열립니다. 주소에 작업 디렉터리와 미리 채울 프롬프트를 담을 수 있습니다. 런북 단계, 모니터링 알림, README, CI 실패 통지에 넣어 한 번의 클릭으로 시작점을 공유하는 용도입니다. deep-links

claude-cli://open?repo=acme/payments&q=review%20open%20PRs

공식핸들러는 대화형 세션에서 첫 프롬프트를 보낼 때 운영체제에 등록됩니다. 세션을 시작하고 아무것도 보내지 않고 나가면 등록되지 않습니다. 그래서 클릭해도 아무 일이 없으면 그 컴퓨터에서 세션을 열어 프롬프트를 한 번 보낸 뒤 다시 시도합니다. GitHub이 렌더링하는 마크다운은 claude-cli:// 같은 스킴을 제거하므로 README나 이슈에서는 코드 블록에 주소를 넣는 편이 낫습니다. deep-links

11.1무엇이 돈을 쓰는가

공식토큰 비용은 맥락 크기에 비례합니다. 클로드코드는 매 요청에 대화 전체를 보내고, 클로드가 도구를 쓸 때마다 그 결과를 담은 요청을 또 보냅니다. 그래서 하루 종일 열어 둔 세션에서 한 줄짜리 질문을 해도 대화 전체에 대한 사용량이 발생합니다. costs

공식현재 세션 사용량은 /usage로 봅니다(/cost가 별칭). 구독 요금제에서는 여기에 무엇이 한도를 쓰는지도 나옵니다. 스킬, 서브에이전트, 플러그인, 개별 MCP 서버별 귀속이 각각 비율로 표시되고, 최근 사용량의 10퍼센트 이상을 차지하는 행동 신호(긴 맥락, 캐시 미스 등)에 표시가 붙습니다. d와 w로 24시간과 7일을 전환합니다. costs

공식긴 세션에서 사용량이 활동량보다 크게 오르는 이유는 정해져 있습니다. 긴 맥락, 캐시 미스, 예약 작업이 유휴 중에도 발동하는 것, 다른 세션에서 온 메시지, 활성 상태로 남은 에이전트 팀원, 그리고 압축 자체가 큰 요청이라는 것. costs

11.2프롬프트 캐시

공식캐시가 없으면 API는 매 턴 전체 이력을 다시 처리합니다. 캐시가 있으면 이미 처리한 것을 재사용하고 그 재읽기를 캐시 요금으로 청구하며 바뀐 부분만 온전히 처리합니다. 클로드코드가 알아서 관리합니다. prompt-caching

공식핵심은 앞부분 일치입니다. API는 각 요청의 시작 부분을 최근 처리한 것과 대조하는데, 일치는 정확히 이뤄지므로 앞부분의 어딘가가 바뀌면 그 뒤가 전부 다시 계산됩니다. 파일별이나 구간별 캐시는 없습니다. 그래서 클로드코드는 잘 바뀌지 않는 것을 앞에 둡니다. prompt-caching

공식캐시를 깨는 것과 지키는 것이 명확하게 갈립니다. 이 편에서 알아 둘 만한 것만 옮깁니다. prompt-caching

공식캐시 수명은 인증 방식에 따라 다릅니다. 구독에서는 한 시간 TTL을 자동으로 요청하므로 한 시간까지의 공백을 견딥니다. 사용 크레딧을 쓰는 상태에서는 비용 때문에 자동으로 5분으로 내려가며, 한 시간을 유지하려면 ENABLE_PROMPT_CACHING_1H=1을 설정합니다. API 키나 서드파티 제공자에서는 기본이 5분입니다. prompt-caching

11.3모델 선택 기준

공식정확한 버전 번호를 기억하지 않아도 되게 별칭이 있습니다. model-config

공식선택 기준은 단순합니다. Sonnet이 대부분의 코딩 작업을 잘 처리하고 Opus보다 저렴합니다. Opus는 복잡한 구조 결정이나 다단계 추론에 남겨 둡니다. 세션 중 전환은 /model이고 기본값은 /config에서 정합니다. costs

공식노력 수준은 적응형 추론을 조절합니다. 지원 모델에서 기본값은 high이고, low, medium, high, xhigh, max가 있습니다(모델에 따라 지원 범위가 다릅니다). 낮으면 간단한 작업에서 빠르고 싸고, 높으면 복잡한 문제에 깊은 추론을 씁니다. /effort로 바꿉니다. model-config

11.4빠른 모드

공식빠른 모드는 Claude Opus를 최대 2.5배 빠르게 만드는 고속 구성이고, 토큰당 비용이 더 높습니다. 다른 모델이 아닙니다. 같은 Opus에 속도를 우선하는 API 구성을 쓰는 것이라 품질과 능력은 동일합니다. Opus 5와 Opus 4.8에서 지원하고 Sonnet이나 Haiku에서는 쓸 수 없습니다. fast-mode

/fast          토글(켜면 다른 모델이었어도 Opus로 전환됩니다)
/fast on
/fast off

공식켜지면 Fast mode ON 확인 메시지가 나오고 프롬프트 옆에 작은 표시가 붙습니다. 끄더라도 모델은 Opus에 남으므로 다른 모델로 가려면 /model을 씁니다. fast-mode

공식구독 요금제에서 빠른 모드는 사용 크레딧으로만 제공되며 구독의 포함 사용량에 들어가지 않습니다. 계정에 사용 크레딧이 켜져 있어야 하고, Team과 Enterprise에서는 기본으로 꺼져 있어 Owner가 켜야 합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서는 쓸 수 없습니다. fast-mode

출처: fast-mode

11.5절약 수칙

관행아래는 공식 문서가 Anthropic 내부 팀과 여러 코드베이스의 실사용에서 효과가 확인된 것으로 기록한 수칙입니다. 출처가 공식이지만 성질은 현장 관행이라 그렇게 표시했습니다. best-practices

• 작업 사이에 /clear. 관련 없는 일로 넘어갈 때 맥락을 비웁니다. 남은 맥락은 이후 모든 메시지에서 토큰을 낭비합니다. 나중에 찾을 수 있게 /rename을 먼저 하고 비웁니다.
• 구체적으로 지시합니다. "이 코드베이스를 개선해 줘" 같은 요청은 넓은 스캔을 유발하고, "auth.ts의 로그인 함수에 입력 검증을 추가해 줘"는 최소한의 파일 읽기로 처리됩니다.
• 복잡한 작업에는 플랜 모드를 먼저. 처음 방향이 틀렸을 때의 비싼 재작업을 막습니다.
• 일찍 방향을 틉니다. 어긋나면 Esc로 즉시 멈추고, /rewind로 이전 체크포인트로 돌립니다.
• 검증 목표를 줍니다. 클로드가 스스로 확인할 수 있으면 사용자가 수정을 요청하기 전에 문제를 잡습니다.
• 점진적으로 테스트합니다. 파일 하나 쓰고 테스트하고 다음으로. 문제를 싸게 고칠 수 있는 시점에 잡습니다.
• CLI 도구를 MCP보다 먼저. gh, aws 같은 도구는 도구 목록을 맥락에 추가하지 않아 더 효율적입니다.
• 장황한 작업은 서브에이전트에 넘깁니다. 테스트 실행, 문서 조회, 로그 처리의 장황한 출력이 서브에이전트 맥락에 남고 요약만 돌아옵니다.
• 지침 파일은 짧게. 세션마다 로드되므로 특정 워크플로의 상세 지침은 스킬로 옮깁니다. 공식 문서의 목표치는 200줄 미만입니다.

12.1무엇이 컨텍스트를 먹는가

공식세션을 열고 아무것도 입력하지 않은 상태에서 이미 여러 가지가 로드돼 있습니다. 공식 문서는 대표값이 붙은 예시 세션으로 그 구성을 보여줍니다. 아래 숫자는 그 예시의 값이고, 실제 값은 설정에 따라 달라집니다. context-window

공식MCP 도구는 기본적으로 이름만 올라가고 전체 스키마는 필요할 때 도구 검색으로 불러옵니다. ENABLE_TOOL_SEARCH=auto로 두면 컨텍스트 윈도우의 10퍼센트 안에 들어갈 때 스키마를 미리 올리고, ENABLE_TOOL_SEARCH=false로 두면 전부 올립니다. context-window

공식작업이 시작되면 여기에 계속 쌓입니다. 파일을 한 번 읽으면 그 파일 전체가 들어가고(예시에서는 2,400 · 1,800 · 1,600 토큰), 경로 범위 규칙은 해당 파일을 읽는 순간 함께 올라가고(예시 380 · 290), 편집 뒤에 도는 훅의 출력도 들어갑니다(예시 120 · 100). 셸 명령을 ! 접두어로 직접 실행하면 명령과 출력이 모두 내 메시지의 일부로 들어갑니다. context-window

공식지금 세션의 실제 사용량은 /context로 봅니다. 범주별 분해와 최적화 제안, 그리고 어떤 CLAUDE.md와 자동 메모리 파일이 로드됐는지를 함께 보여줍니다. context-window

12.2자동 압축

공식컨텍스트가 한계에 가까워지면 클로드코드가 대화 기록을 요약으로 바꿉니다. 창이 꽉 차도 세션이 끝나지는 않습니다. 압축은 자동으로 돌기도 하고 /compact로 직접 돌릴 수도 있습니다. context-window

공식중요한 것은 무엇이 살아남는지입니다. 로드 경로에 따라 결과가 다릅니다. context-window

공식스킬 본문은 잘릴 때 앞부분이 남습니다. 그래서 SKILL.md의 가장 중요한 지시는 파일 위쪽에 둡니다. context-window

공식압축이 도는 시점은 조절할 수 있습니다. 설정 위치는 세 곳이고 우선순위가 정해져 있습니다. context-window

/autocompact 500k        이 세션과 이후 세션에 적용(autoCompactWindow 설정에 저장)
/autocompact auto        모델에 맞춰 조정된 기본값으로 복귀
claude --autocompact 500k 이번 실행에만 적용(저장된 설정을 건드리지 않음)

공식명령과 플래그는 100K에서 1M 사이의 값을 받고, 표기는 200000처럼 그냥 숫자, 500k·1M처럼 접미어, 또는 100에서 1000 사이의 맨숫자(200은 200,000)를 씁니다. 스크립트와 클라우드 환경에서는 환경 변수 CLAUDE_CODE_AUTO_COMPACT_WINDOW를 쓰며, 이 변수가 설정돼 있으면 명령·플래그·설정보다 앞섭니다. 환경 변수는 맨숫자만 받습니다. context-window

12.3압축을 덜 겪는 작업 설계

공식자동 압축이 돌기 전에 손쓸 수 있는 방법이 네 가지 있습니다. 초점을 지정해 압축하기(/compact focus on the auth bug fix), 압축 시점을 앞당기기(/autocompact), 무관한 작업으로 넘어갈 때 /clear로 비우기, 큰 읽기를 서브에이전트에 위임하기입니다. context-window

관행이 넷 중 실제로 효과가 큰 것은 세션 경계를 긋는 습관입니다. 압축은 정보를 잃는 작업이므로, 압축을 잘 견디는 설계보다 압축까지 가지 않는 설계가 낫습니다. 작업 하나가 끝나면 결과를 파일로 남기고 /clear하는 편이, 하나의 긴 세션에서 여러 주제를 굴리다 요약을 두 번 겪는 것보다 안정적입니다.

실전지침 파일도 압축과 무관하게 매 세션 비용입니다. 이 문서를 쓰는 볼트에서 실제로 재어 보면, 루트 CLAUDE.md는 115줄인데 23,663자입니다. 같은 볼트의 208줄짜리 개발 규칙 문서가 20,680자였습니다. 줄 수는 분량의 대리 지표일 뿐이므로, 줄만 세면 실제 비용을 과소평가합니다. 측정은 맥에서 wc로 했습니다.

wc -l CLAUDE.md    줄 수
wc -m CLAUDE.md    문자 수(한글은 바이트보다 문자로 재는 편이 실제 분량에 가깝습니다)

13.1두 기억 메커니즘

공식세션은 매번 빈 컨텍스트에서 시작합니다. 세션을 넘어 지식을 옮기는 장치는 두 개이며, 둘 다 매 대화 시작 시 로드됩니다. memory

공식CLAUDE.md 내용은 시스템 프롬프트의 일부가 아니라 시스템 프롬프트 뒤의 사용자 메시지로 전달됩니다. 그래서 엄격한 준수가 보장되지 않으며, 애매하거나 서로 충돌하는 지시에서 특히 그렇습니다. memory

13.2계층과 로드 순서

공식CLAUDE.md는 네 자리에 놓을 수 있습니다. 아래 표는 로드 순서대로, 범위가 넓은 것부터입니다. 프로젝트 지시가 사용자 지시보다 뒤에 들어갑니다. memory

공식탐색 방식은 디렉터리 트리를 위로 걸어 올라가는 것입니다. foo/bar/에서 실행하면 foo/bar/CLAUDE.md와 foo/CLAUDE.md, 그리고 그 옆의 CLAUDE.local.md를 모두 찾습니다. 찾은 파일들은 서로를 덮어쓰지 않고 이어 붙습니다. 순서는 파일시스템 루트에서 작업 디렉터리 방향이라, 실행한 자리에 가까운 지시가 나중에 읽힙니다. 같은 디렉터리 안에서는 CLAUDE.local.md가 CLAUDE.md 뒤에 붙습니다. memory

공식큰 모노레포에서 다른 팀의 CLAUDE.md까지 딸려 올라온다면 claudeMdExcludes로 건너뜁니다. 절대 경로에 글로브 문법으로 매칭하며, 어느 설정 계층에도 둘 수 있고 배열은 계층 간에 병합됩니다. 관리형 정책 CLAUDE.md는 제외할 수 없습니다. memory

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

공식지시를 주제별로 쪼개려면 .claude/rules/를 씁니다. .md 파일을 재귀적으로 찾으므로 frontend/·backend/ 같은 하위 폴더로 정리할 수 있습니다. paths 프론트매터가 없는 규칙은 시작 시 .claude/CLAUDE.md와 같은 우선순위로 로드됩니다. 사용자 수준 규칙은 ~/.claude/rules/에 두며, 프로젝트 규칙보다 먼저 로드돼 프로젝트 규칙이 더 높은 우선순위를 갖습니다. memory

공식경로 범위 규칙은 프론트매터 paths로 지정합니다. 클로드가 매칭 패턴의 파일을 읽을 때만 로드되며, 매 도구 호출마다 도는 것이 아닙니다. memory

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

# API 개발 규칙

- 모든 API 엔드포인트는 입력 검증을 포함합니다
- 표준 오류 응답 형식을 씁니다

공식중괄호 확장으로 여러 확장자를 한 패턴에 담을 수 있습니다(src/**/*.{ts,tsx}). 다만 중괄호 그룹마다 패턴 수가 곱해지므로 한 규칙의 paths 목록 전체가 확장 패턴 1,000개와 4MiB의 예산을 공유합니다. 예산을 넘길 패턴은 확장하지 않고 그대로 쓰이며, 그 경우 중괄호가 리터럴이 되어 아무 파일도 매칭하지 않습니다. memory

13.3임포트와 경로 규칙

공식CLAUDE.md는 @path/to/import 문법으로 다른 파일을 불러올 수 있습니다. 임포트된 파일은 시작 시 함께 펼쳐져 컨텍스트에 들어갑니다. 상대 경로와 절대 경로 모두 되고, 상대 경로는 작업 디렉터리가 아니라 임포트를 쓴 파일을 기준으로 풀립니다. 임포트는 재귀적이며 최대 4단계까지입니다. memory

공식임포트 파싱은 마크다운 코드 스팬과 코드 블록을 건너뜁니다. 경로를 임포트하지 않고 언급만 하려면 백틱으로 감쌉니다. memory

See @README for project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md

공식여러 워크트리를 쓴다면 .gitignore된 CLAUDE.local.md는 만든 워크트리에만 존재합니다. 개인 지시를 워크트리 전체에 공유하려면 홈 디렉터리의 파일을 임포트합니다. memory

# Individual Preferences
- @~/.claude/my-project-instructions.md

공식클로드코드는 AGENTS.md가 아니라 CLAUDE.md를 읽습니다. 저장소가 이미 AGENTS.md를 쓴다면 그것을 임포트하는 CLAUDE.md를 만들어 중복 없이 같은 지시를 읽게 합니다. 심링크(ln -s AGENTS.md CLAUDE.md)도 되지만, 윈도우에서 심링크 생성은 관리자 권한이나 개발자 모드가 필요하므로 임포트 쪽이 안전합니다. memory

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

공식--add-dir로 추가한 디렉터리의 메모리 파일은 기본적으로 로드되지 않습니다. 로드하려면 환경 변수를 켭니다. 이때 CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md, CLAUDE.local.md가 함께 들어옵니다. memory

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

13.4잘 쓰인 CLAUDE.md의 조건

공식공식 문서가 제시하는 기준은 네 가지입니다. 분량은 파일당 200줄 미만을 목표로 합니다. 길면 컨텍스트를 더 쓰고 준수율이 떨어집니다. 구조는 마크다운 헤더와 불릿으로 관련 지시를 묶습니다. 구체성은 검증 가능한 수준으로 씁니다. 일관성은 서로 모순되는 규칙을 없애는 것입니다. 두 규칙이 충돌하면 클로드가 임의로 하나를 고를 수 있습니다. memory

공식무엇을 넣을지의 판정 기준도 문서에 있습니다. 같은 실수를 두 번째로 할 때, 코드 리뷰가 클로드가 알았어야 할 것을 잡았을 때, 지난 세션에 입력한 교정을 또 입력할 때, 새 팀원이 같은 맥락을 필요로 할 때입니다. 반대로 여러 단계짜리 절차이거나 코드베이스의 일부에서만 의미가 있는 항목은 스킬이나 경로 범위 규칙으로 옮깁니다. memory

공식블록 수준 HTML 주석은 컨텍스트에 주입되기 전에 제거됩니다. 사람 관리자용 메모를 토큰 비용 없이 남길 수 있습니다. 코드 블록 안의 주석은 보존되고, Read 도구로 파일을 직접 열면 주석이 그대로 보입니다. memory

공식임포트로 쪼개는 것은 정리에는 도움이 되지만 컨텍스트를 줄이지는 않습니다. 임포트된 파일도 시작 시 로드됩니다. 실제로 줄이려면 경로 범위 규칙을 쓰거나 매 세션 필요 없는 내용을 지웁니다. memory

실전200줄 기준은 자기 볼트에 대보면 바로 걸립니다. 이 가이드를 쓰는 볼트에서 CLAUDE.md 9개를 재어 보니 두 개가 기준을 넘었습니다. 개발 도메인 규칙이 208줄, 지식베이스 규칙이 224줄입니다. 루트는 115줄로 기준 안이지만 12.3절에서 본 것처럼 문자 수로는 가장 큽니다. 어느 쪽도 자동으로 경고되지 않으므로, 아래 한 줄을 주기적으로 돌려 스스로 재는 편이 확실합니다.

find . -name "CLAUDE.md" -not -path "./.git/*" -exec wc -l {} \;

13.5자동 메모리 관리

공식자동 메모리는 클로드가 스스로 메모를 남기는 장치입니다. 빌드 명령, 디버깅 통찰, 아키텍처 메모, 코드 스타일 취향, 작업 습관이 대상입니다. 매 세션 무언가를 저장하는 것은 아니고, 나중 대화에서 쓸모가 있을지를 기준으로 판단합니다. 기본값은 켜짐입니다. memory

공식저장 위치는 프로젝트별로 ~/.claude/projects/<project>/memory/입니다. <project>는 git 저장소에서 파생되므로 같은 저장소의 모든 워크트리와 하위 디렉터리가 하나의 자동 메모리 디렉터리를 공유합니다. git 저장소 밖에서는 프로젝트 루트를 씁니다. 자동 메모리는 기기 로컬이며 기기나 클라우드 환경 사이에 공유되지 않습니다. memory

~/.claude/projects/<project>/memory/
├── MEMORY.md          간결한 색인. 매 세션 로드됨
├── debugging.md       디버깅 패턴 상세 메모
├── api-conventions.md API 설계 결정
└── ...                클로드가 만드는 다른 주제 파일

공식매 대화 시작 시 로드되는 것은 MEMORY.md의 첫 200줄, 또는 첫 25KB 중 먼저 닿는 쪽까지입니다. 그 뒤 내용은 시작 시 로드되지 않습니다. 클로드가 MEMORY.md에 쓴 뒤 클로드코드가 파일을 두 한계에 대조합니다. 한계에 가까우면 짧게 줄이라고 상기시키고, 한계를 넘으면 쓰기는 성공하지만 색인을 다시 쓰라는 오류를 돌려줍니다. 넘긴 부분은 다음 로드에서 버려지기 때문입니다. memory

공식끄고 켜는 방법은 세 가지입니다. 세션에서 /memory를 열어 토글하면 ~/.claude/settings.json에 autoMemoryEnabled로 저장됩니다. 프로젝트 하나만 끄려면 그 프로젝트 설정에 "autoMemoryEnabled": false를 둡니다. 환경 변수로 끄려면 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1입니다. 저장 위치를 바꾸려면 autoMemoryDirectory에 절대 경로나 ~/로 시작하는 경로를 씁니다. 프로젝트나 로컬 설정에 두면 그 폴더의 워크스페이스 신뢰 대화를 수락한 뒤에만 적용됩니다. memory

공식메모리 파일은 그냥 마크다운이라 언제든 열어 고치거나 지울 수 있습니다. /memory로 목록을 보고 편집기로 엽니다. 프론트매터가 있는 파일에 클로드가 쓸 때는 modified 필드에 ISO 8601 타임스탬프가 기록되어 그 사실이 얼마나 최신인지 알 수 있습니다. 프론트매터가 없는 파일에는 클로드코드가 프론트매터를 새로 붙이지 않습니다. memory

실전200줄과 25KB 중 어느 쪽에 먼저 닿는지는 언어에 달렸습니다. 이 볼트의 MEMORY.md는 148줄에 20,720바이트로, 줄 기준으로는 74퍼센트인데 바이트 기준으로는 83퍼센트입니다. 한글 색인은 바이트 한계에 먼저 닿습니다. 같은 디렉터리에 시작 시 로드되지 않는 주제 파일이 145개 있었고, 색인 한 줄이 그 파일 하나를 가리키는 구조였습니다. 확인은 아래 두 줄로 합니다.

wc -l ~/.claude/projects/<project>/memory/MEMORY.md
wc -c ~/.claude/projects/<project>/memory/MEMORY.md

13.6무엇을 어디에 둘까

지침을 놓을 자리가 다섯 개나 되면 결정 자체가 비용입니다. 판정은 두 질문으로 끝납니다. 매 세션 필요한가, 그리고 보장이 필요한가.

공식조직 배포에서는 이 갈림이 더 분명합니다. 도구·명령·경로 차단은 관리형 설정의 permissions.deny, 샌드박스 강제는 sandbox.enabled, 환경 변수와 API 라우팅은 env, 인증 방식과 조직 고정은 forceLoginMethod·forceLoginOrgUUID입니다. 코드 스타일, 데이터 취급 안내, 행동 지시는 관리형 CLAUDE.md입니다. memory

실전이 볼트는 그 갈림을 한쪽으로 몰아 쓰고 있었습니다. .claude/settings.json에는 권한 규칙이 하나도 없고 hooks만 있습니다. 이벤트 3종에 핸들러 10개(UserPromptSubmit 1, Stop 2, SessionStart 7)입니다. 즉 "반드시 도는 것"은 전부 훅으로 보장하고, 권한은 규칙으로 설계하지 않은 상태였습니다. 나쁜 선택은 아니지만, 훅은 동작을 추가하는 장치이고 권한은 동작을 막는 장치라 서로를 대신하지 못합니다. 자기 프로젝트가 어느 쪽으로 기울었는지는 아래로 바로 확인됩니다.

python3 -c "import json;d=json.load(open('.claude/settings.json'));print(list(d.keys()))"

13.7.claude 디렉터리 해부

공식설정은 두 자리에 삽니다. 프로젝트 것은 저장소의 .claude/ 아래(CLAUDE.md·.mcp.json·.worktreeinclude는 루트), 전역 것은 ~/.claude/ 아래이며 모든 프로젝트에 적용됩니다. claude-directory

공식내가 쓰는 설정 외에 클로드코드가 작업하며 남기는 데이터도 ~/.claude에 쌓입니다. 이 파일들은 평문입니다. 도구를 통과한 것은 무엇이든 디스크의 전사에 남습니다. 파일 내용, 명령 출력, 붙여넣은 텍스트가 그렇습니다. claude-directory

공식위 표의 앞쪽 항목들은 cleanupPeriodDays보다 오래되면 시작할 때 삭제됩니다. 기본값은 30일, 최솟값은 1이고 0은 검증 오류로 실패합니다. 반면 history.jsonl은 자동 정리 대상이 아니어서 지울 때까지 남습니다. 클로드코드가 설정 파일을 읽거나 파싱하지 못하면 정리 스윕을 멈추고 /status에 경고를 띄웁니다. claude-directory

공식노출을 줄이는 방법은 세 가지입니다. cleanupPeriodDays를 낮춰 보관 기간을 줄이기, CLAUDE_CODE_SKIP_PROMPT_HISTORY를 설정해 전사와 프롬프트 기록 자체를 남기지 않기, 그리고 권한 규칙으로 자격증명 파일 읽기를 거부하기입니다. claude-directory

공식프로젝트 하나의 로컬 상태를 통째로 지우려면 claude project purge입니다. 전사와 자동 메모리, 세션별 tasks/·debug/·file-history/ 항목, history.jsonl의 해당 프롬프트 줄, ~/.claude.json의 프로젝트 항목을 지웁니다. 삭제 전에 전체 계획을 출력하고 확인을 받습니다. claude-directory

claude project purge ~/work/my-repo --dry-run   지우지 않고 계획만 확인
claude project purge ~/work/my-repo             계획 출력 후 확인 한 번
claude project purge ~/work/my-repo --yes       확인 생략(스크립트용)

실전전사가 얼마나 쌓이는지는 직접 세어 보면 감이 옵니다. 이 볼트 프로젝트의 전사 디렉터리에는 세션 .jsonl 파일이 126개 있었습니다. 기본 보관 기간 30일 안에서 그만큼이 평문으로 남아 있다는 뜻입니다.

ls ~/.claude/projects/<project>/*.jsonl | wc -l
du -sh ~/.claude/projects/<project>

14.1권한 모드 여섯 가지

공식모드는 물어보는 빈도의 기준선입니다. 아래 표는 각 모드에서 승인 없이 도는 것입니다. permission-modes

공식매 동작을 검토하는 모드는 CLI·claude --help·VS Code와 젯브레인즈 확장·데스크톱 앱에서 Manual이라는 이름으로 표시됩니다. 설정값은 default이고, 훅과 SDK 통합이 쓰는 값도 그것입니다. CLI는 어디서든 manual을 별칭으로 받습니다(claude --permission-mode manual). permission-modes

공식전환은 세 갈래입니다. 세션 중에는 Shift Tab으로 default → acceptEdits → plan을 순환합니다. 시작할 때는 플래그로 지정하고, 기본값으로 굳히려면 설정 파일에 defaultMode를 씁니다. permission-modes

claude --permission-mode plan

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

공식모든 모드가 기본 순환에 들어 있지는 않습니다. auto는 계정이 자동 모드 요건을 만족할 때 나타나고, 순환으로 들어갈 때 확인 프롬프트가 없습니다. bypassPermissions는 --permission-mode bypassPermissions·--dangerously-skip-permissions·--allow-dangerously-skip-permissions로 시작했거나 설정에 defaultMode로 지정했을 때만 나타납니다(--allow- 변형은 활성화 없이 순환에만 추가합니다). dontAsk는 순환에 절대 나타나지 않고 --permission-mode dontAsk로만 켭니다. permission-modes

공식상태 표시줄에 지금 모드가 보입니다. ⏸ plan mode on, ⏵⏵ accept edits on, ⏵⏵ auto mode on, ⏵⏵ don't ask on, ⏵⏵ bypass permissions on이고 Manual은 회색 ⏸ manual mode on입니다. permission-modes

공식acceptEdits가 자동 승인하는 파일시스템 명령은 mkdir touch rm rmdir mv cp sed입니다. LANG=C처럼 안전한 환경 변수 접두어나 timeout·nice·nohup 같은 프로세스 래퍼가 붙은 형태도 포함합니다. 다만 자동 승인은 작업 디렉터리나 additionalDirectories 안의 경로에만 적용되고, 범위 밖 경로와 보호 경로 쓰기, 그리고 내장 읽기 전용 집합을 뺀 다른 Bash 명령은 여전히 물어봅니다. permission-modes

공식플랜 모드는 클로드가 조사하고 변경안을 제안하되 실제로 고치지는 않게 합니다. Shift Tab으로 들어가거나 프롬프트 하나에만 적용하려면 /plan을 접두어로 씁니다. 계획이 준비되면 세 갈래로 답합니다. 자동 모드로 승인, 편집을 하나씩 승인, 또는 계속 계획하기입니다. 승인하면 플랜 모드를 벗어나 그 선택에 해당하는 모드로 세션이 바뀝니다. Ctrl G로 계획을 편집기에서 직접 고칠 수 있습니다. permission-modes

공식dontAsk는 물어봐야 할 모든 도구 호출을 자동 거부합니다. permissions.allow에 매칭되는 동작, 읽기 전용 Bash 명령, PreToolUse 훅이 승인한 호출만 돕니다. 세션이 입력을 기다리는 일이 없으므로 CI 파이프라인에 맞습니다. 명시적 ask 규칙에 걸리는 호출은 물어보는 대신 거부하고, 내장 AskUserQuestion 도구도 거부합니다. permission-modes

공식이 모드에서도 남아 있는 프롬프트가 있습니다. 명시적 ask 규칙, 조직이 ask로 설정한 커넥터 도구, requiresUserInteraction 표시가 붙은 MCP 도구입니다. 그리고 파일시스템 루트나 홈 디렉터리를 지우는 명령(rm -rf /, rm -rf ~)은 모델 오류에 대한 차단기로 여전히 물어봅니다. 명령이 $(...)·백틱 명령 치환이나 <(...) 프로세스 치환을 포함할 때도 마찬가지입니다. permission-modes

공식관리자는 permissions.disableBypassPermissionsMode나 permissions.disableAutoMode를 "disable"로 두어 해당 모드를 막을 수 있습니다. 관리형 설정에 두면 덮어쓸 수 없지만, 어느 스코프에서도 동작하므로 사용자가 자기 설정에 넣어 스스로를 잠글 수도 있습니다. permissions

공식세션이 어느 모드로 시작하는지는 2026-08-14에 바뀌었습니다. Pro·Max·Team 플랜에서 새 세션의 내장 시작 모드가 auto가 됐습니다. 그 전에는 default(Manual)였습니다. 직접 기본 모드를 정해 둔 사용자는 일회성 전환 안내를 수락하기 전까지 그 설정이 유지되고, 조직이 관리하는 기본값은 바뀌지 않습니다. 모드는 언제든 다시 바꿀 수 있습니다. 같은 플랜에서 자동 모드 분류기 호출은 사용 한도에 계산되지 않습니다. permission-modes

14.2허용·거부·확인 규칙

공식규칙은 세 종류입니다. allow는 수동 승인 없이 쓰게 하고, ask는 매번 확인을 띄우고, deny는 아예 막습니다. 평가 순서는 deny → ask → allow이며, 그 순서에서 처음 매칭된 것이 결과를 정합니다. 규칙이 얼마나 구체적인지는 순서를 바꾸지 않습니다. permissions

공식deny 규칙은 도구 이름만 쓸 때와 패턴을 씌울 때 동작이 다릅니다. Bash처럼 이름만 쓰면 그 도구를 클로드의 컨텍스트에서 아예 제거해 클로드가 도구의 존재를 보지 못합니다. Bash(rm *)처럼 범위를 씌우면 도구는 남고 매칭되는 호출만 막힙니다. Bash(*)는 Bash와 같으며 deny로 쓰면 두 형태 모두 도구를 제거합니다. permissions

공식Bash 규칙은 * 와일드카드를 어느 위치에서든 씁니다. 하나의 *가 공백을 포함한 임의 문자열에 매칭되므로 와일드카드 하나가 여러 인자를 덮습니다. permissions

공식클로드코드는 셸 연산자를 인식합니다. Bash(safe-cmd *) 규칙이 safe-cmd && other-cmd를 허용하지 않습니다. 인식되는 구분자는 && || ; | |& & 그리고 개행이며, 규칙은 각 하위 명령에 독립적으로 매칭돼야 합니다. 복합 명령을 "다시 묻지 않기"로 승인하면 승인이 필요한 하위 명령마다 별도 규칙이 저장됩니다. 한 복합 명령에서 최대 5개까지입니다. permissions

공식Bash 규칙 매칭 전에 정해진 래퍼 집합이 벗겨집니다. 그래서 Bash(npm test *)가 timeout 30 npm test에도 매칭됩니다. 벗겨지는 래퍼는 timeout time nice nohup stdbuf, 셸 빌트인 command와 builtin, zsh의 noglob입니다. 플래그 없는 xargs도 벗겨집니다. 조회 형태인 command -v와 zsh의 nocorrect는 벗겨지지 않습니다. permissions

공식내장 읽기 전용 명령 집합은 모든 모드에서 프롬프트 없이 돕니다. ls cat echo pwd head tail grep find wc which diff stat du cd와 git의 읽기 전용 형태입니다. 이 집합은 구성할 수 없고, 그중 하나에 확인을 받고 싶다면 ask나 deny 규칙을 추가합니다. permissions

공식다만 이 집합도 몇 경우에는 물어봅니다. 쓰기·실행 가능 플래그를 가진 명령(find sort sed git)에 인용되지 않은 글로브가 있을 때(글로브가 -delete 같은 플래그로 확장될 수 있으므로), docker가 다른 데몬을 가리키는 플래그를 달았을 때, file이 경로를 여는 플래그를 쓸 때, 윈도우에서 인자에 UNC 네트워크 경로가 있을 때, 그리고 클로드코드가 명령을 완전히 파싱하지 못할 때입니다. 1만 자를 넘는 명령은 항상 물어봅니다. permissions

공식Read와 Edit 규칙은 gitignore 패턴 문법을 쓰며 앵커가 네 종류입니다. 여기서 실수가 가장 많이 납니다. permissions

공식매칭 깊이는 패턴 모양에 따라 다르고, 단일 세그먼트 디렉터리 패턴에서는 규칙 종류에 따라서도 다릅니다. allow에서 Edit(src/**)는 <cwd>/src만 매칭하지만, deny와 ask에서 Read(secrets/**)는 현재 디렉터리 아래 어느 깊이의 secrets 디렉터리에도 매칭합니다. 맨 파일명은 gitignore 의미를 따라 어느 깊이에서든 매칭하므로 Read(.env)와 Read(**/.env)는 같습니다. permissions

공식파일 권한은 Edit(path)와 Read(path) 규칙으로만 검사됩니다. Write, NotebookEdit, Glob, 구형 MultiEdit에 경로 규칙을 쓰면 규칙은 받아들여지지만 조회되지 않고 시작 시 경고가 뜹니다. Write(docs/**) 대신 Edit(docs/**)를, Glob(docs/**) 대신 Read(docs/**)를 씁니다. Read deny 규칙은 같은 경로의 Edit 도구까지 막고, 거기에 새 파일을 만드는 것도 막습니다. permissions

공식심링크는 두 경로로 검사됩니다. 링크 자신과 링크가 가리키는 파일입니다. allow 규칙은 둘 다 매칭될 때만 적용되고, 하나라도 어긋나면 물어봅니다. deny 규칙은 둘 중 하나만 매칭돼도 막습니다. permissions

공식WebFetch 규칙은 domain: 접두어로 호스트명에 매칭합니다. WebFetch(domain:*.example.com)은 어느 깊이의 서브도메인에도 매칭하지만 example.com 자체에는 매칭하지 않습니다. 앞의 *.이나 단독 * 외의 위치에서 와일드카드는 점 사이의 텍스트에만 매칭하므로, example.*는 example.org에 매칭하고 example.evil.com에는 매칭하지 않습니다. permissions

공식MCP 규칙은 서버 이름을 씁니다. mcp__puppeteer는 그 서버의 모든 도구에, mcp__puppeteer__puppeteer_navigate는 특정 도구에 매칭합니다. 서브에이전트는 Agent(Explore)처럼 이름으로 통제합니다. /cd가 옮길 수 있는 디렉터리는 Cd 규칙으로 정하며, Cd allow 규칙을 하나라도 추가하면 /cd가 허용목록 모드로 바뀝니다. permissions

공식"예, 다시 묻지 않기"로 저장되는 위치도 알아 두면 좋습니다. Bash 명령처럼 영구 저장되는 승인은 git 저장소 루트의 .claude/settings.local.json에 저장되며, 워크트리를 거쳐 메인 체크아웃으로 해석됩니다. 그래서 그 저장소 어디에서 시작한 세션에도, 하위 디렉터리와 워크트리에도 적용됩니다. 파일 수정 승인은 파일에 저장되지 않고 세션이 끝날 때까지만 유지됩니다. permissions

공식Bash나 PowerShell 권한 프롬프트에서 Ctrl E를 누르면 그 명령이 무엇을 하는지, 왜 실행하는지, 무엇이 잘못될 수 있는지를 Low risk·Med risk·High risk 라벨과 함께 설명합니다. 설명 생성 요청은 Ctrl E를 누를 때만 나가고, 설명을 봐도 명령이 실행되지는 않습니다. permissions

14.3자동 모드 구성

공식자동 모드는 별도 분류기 모델이 실행 전에 동작을 검토해, 요청 범위를 넘어서거나 알려지지 않은 인프라를 향하거나 클로드가 읽은 적대적 콘텐츠에 이끌린 것처럼 보이는 동작을 막습니다. 명시적 ask 규칙은 여전히 프롬프트를 띄웁니다. permission-modes

공식판정 순서는 정해져 있고 처음 매칭된 단계가 이깁니다. 1) allow·ask·deny 규칙에 매칭되는 동작은 즉시 결정됩니다. 다만 보호 경로 쓰기는 allow 규칙에 매칭돼도 분류기로 넘어갑니다. 2) 작업 디렉터리 안의 읽기 전용 동작과 파일 편집은 자동 승인됩니다(보호 경로 쓰기 제외). 3) 나머지는 분류기로 갑니다. 4) 분류기가 막으면 클로드가 이유를 받고 대안을 시도합니다. permission-modes

공식자동 모드로 들어갈 때 임의 코드 실행을 부여하는 넓은 allow 규칙은 버려집니다. Bash(*)·PowerShell(*), Bash(python*)처럼 와일드카드가 붙은 인터프리터, 패키지 매니저 실행 명령, Agent allow 규칙입니다. Bash(npm test) 같은 좁은 규칙은 그대로 넘어가며, 버려진 규칙은 자동 모드를 벗어나면 복구됩니다. permission-modes

공식기본 신뢰 범위는 좁습니다. 분류기는 작업 디렉터리와 세션 시작 시 설정돼 있던 원격만 신뢰합니다. 세션 중에 git remote add나 git remote set-url로 추가·변경한 원격은 신뢰하지 않고, 그 밖의 모든 것은 외부로 취급합니다. permission-modes

공식기본 차단 목록에서 자주 걸리는 것들입니다. permission-modes

공식push 관련 기본값은 한 번 정리해 둘 만합니다. 작업 중인 저장소의 어느 브랜치로든, 기본 브랜치를 포함해 push가 허용되고 풀 리퀘스트 생성도 기본 허용입니다. 다만 production·release·gh-pages처럼 이름이 배포·공개 대상임을 나타내는 비기본 브랜치는 그 기본값에 포함되지 않고 분류기가 따로 판정합니다. push의 내용도 여전히 검사되므로 force push, 커밋에 비밀이 들어가는 경우, CI나 배포 파이프라인이 그것을 실행할 때 비밀이 저장소 밖으로 나가게 되는 변경은 막힙니다. auto-mode-config

공식매번 사람 체크포인트를 원한다면 permissions.ask가 가장 직접적입니다. 내용 범위 ask 규칙은 분류기보다 먼저 평가되며 자동 모드에서도 항상 프롬프트를 강제합니다. auto-mode-config

{
  "permissions": {
    "ask": [
      "Bash(git push *)",
      "Bash(gh pr create *)"
    ]
  }
}

공식분류기가 조직 인프라를 몰라서 막는 경우에는 autoMode.environment에 신뢰 대상을 알려 줍니다. 항목은 정규식이나 도구 패턴이 아니라 산문이며, 분류기가 자연어 규칙으로 읽습니다. 배열에 "$defaults" 문자열을 넣으면 그 자리에 기본 항목이 끼워지고, 넣지 않으면 그 섹션의 기본 목록을 통째로 버립니다. auto-mode-config

{
  "autoMode": {
    "environment": [
      "$defaults",
      "Source control: github.example.com/acme-corp and all repos under it",
      "Trusted cloud buckets: s3://acme-build-artifacts",
      "Trusted internal domains: *.corp.example.com",
      "Key internal services: Jenkins at ci.example.com"
    ]
  }
}

공식분류기 내부의 우선순위는 네 단계입니다. hard_deny는 무조건 차단하고 사용자 의도와 allow 예외가 적용되지 않습니다. soft_deny는 그다음이며 사용자 의도와 allow가 뒤집을 수 있습니다. allow는 매칭되는 soft_deny를 예외로 덮습니다. 마지막으로 명시적 사용자 의도가 남은 소프트 차단을 덮는데, 사용자 메시지가 클로드가 하려는 정확한 동작을 직접적이고 구체적으로 서술한 경우에만입니다. "저장소를 정리해 줘"는 force push를 승인하지 않고, "이 브랜치를 force push 해 줘"는 승인합니다. auto-mode-config

공식분류기는 .claude/settings.json과 .claude/settings.local.json에서 autoMode를 읽지 않습니다. 두 파일 모두 저장소 디렉터리에 있어서, 커밋된 저장소나 빌드 단계가 자기 허용 규칙을 주입할 수 있기 때문입니다. 읽는 곳은 ~/.claude/settings.json, 관리형 설정, --settings 플래그입니다. auto-mode-config

공식같은 이유로 defaultMode: "auto"도 프로젝트·로컬 설정에서는 무시됩니다. 설정했는데 세션이 default로 시작하고 오류가 없으면 대개 그 설정이 프로젝트 파일에 있는 것이니 ~/.claude/settings.json으로 옮깁니다. permission-modes

공식구성을 확인하는 명령이 넷 있습니다. auto-mode-config

claude auto-mode defaults    내장 environment·allow·soft_deny·hard_deny를 JSON으로 출력
claude auto-mode config      내 설정이 반영된 실제 유효 규칙을 출력
claude auto-mode critique    내가 쓴 커스텀 규칙에 대한 피드백
claude auto-mode reset       사용자 설정의 autoMode 섹션을 제거하고 기본값으로

공식거부된 동작은 /permissions의 Recently denied 탭에 남습니다. 거부된 항목에서 r을 누르면 재시도로 표시되고, 대화를 닫을 때 클로드코드가 그 도구 호출을 재시도해도 된다는 메시지를 보내며 대화를 재개합니다. 같은 목적지에서 반복 거부가 나오면 대개 분류기가 맥락을 모르는 것이니 autoMode.environment에 그 목적지를 추가하고 claude auto-mode config로 반영을 확인합니다. auto-mode-config

공식비용도 알아 둡니다. 분류기는 기본적으로 Claude Sonnet 5에서 돌며 /model 선택과 무관합니다. 엔터프라이즈 플랜과 API·Bedrock·Agent Platform·Foundry 계정에서는 분류기 호출이 토큰 사용량에 포함됩니다. 매 검사가 전사의 일부와 대기 중인 동작을 보내므로 실행 전에 왕복이 한 번 늘어납니다. 읽기와 보호 경로 밖 작업 디렉터리 편집은 분류기를 건너뛰므로, 오버헤드는 주로 셸 명령과 네트워크 작업에서 발생합니다. permission-modes

14.4위험 경계

공식일부 경로는 쓰기가 절대 자동 승인되지 않습니다. bypassPermissions 모드와 bypass 권한이 가용한 계획 세션만 예외입니다. 저장소 상태와 클로드 자신의 설정이 사고로 망가지는 것을 막는 장치입니다. permission-modes

공식보호 디렉터리는 .git, .config/git, .vscode, .idea, .husky, .cargo, .devcontainer, .yarn, .mvn, 그리고 .claude입니다(.claude/worktrees는 예외). 보호 파일에는 .gitconfig·.gitmodules, 셸 시작 파일(.bashrc .zshrc .profile .envrc 등), 패키지 매니저 설정(.npmrc .yarnrc .pnpmfile.cjs bunfig.toml 등), .pre-commit-config.yaml과 lefthook 설정, 래퍼 프로퍼티 파일, .mcp.json과 .claude.json이 있습니다. permission-modes

공식훅으로 권한을 확장할 수도 있습니다. PreToolUse 훅은 권한 프롬프트보다 먼저 돌고, 출력으로 호출을 거부하거나 프롬프트를 강제하거나 프롬프트를 건너뛰게 할 수 있습니다. 다만 훅 결정이 권한 규칙을 우회하지는 않습니다. 매칭되는 deny 규칙은 훅이 "allow"를 돌려줘도 차단하고, 매칭되는 ask 규칙은 여전히 프롬프트를 띄웁니다. 반대로 종료 코드 2로 끝나는 차단 훅은 권한 규칙 평가 전에 호출을 멈추므로 allow 규칙이 있어도 막힙니다. permissions

공식인자를 제약하려는 Bash 패턴은 깨지기 쉽습니다. Bash(curl http://github.com/ *)는 URL 앞의 옵션(curl -X GET ...), 다른 프로토콜(https), 리다이렉트, 변수(URL=... && curl $URL), 공백 두 칸에 모두 매칭하지 못합니다. 더 확실한 URL 필터링은 curl·wget을 deny로 막고 WebFetch 도구에 도메인 허용 규칙을 주는 것, PreToolUse 훅으로 URL을 검증하는 것입니다. WebFetch만 쓰는 것으로 네트워크 접근이 막히지는 않습니다. Bash가 허용돼 있으면 클로드는 여전히 curl로 어느 URL이든 갈 수 있습니다. permissions

실전이 볼트의 .claude/settings.local.json에는 allow 규칙 16개가 있고 deny와 ask는 0개입니다. 전부 "예, 항상 허용"을 누른 결과가 쌓인 것입니다. 문제는 그 내용이었습니다. 특정 파일명이 박힌 rm 명령, 리터럴 절대 경로가 박힌 find처럼 다시 쓰일 리 없는 일회성 문자열이 대부분입니다. 승인 버튼으로 만든 규칙은 그 순간의 명령을 기록할 뿐이므로, 권한 설계가 아니라 로그에 가까워집니다.

관행처음 쓰는 deny 규칙으로 값을 하는 것은 대개 자격증명 읽기와 되돌릴 수 없는 원격 작업입니다. 공식 예시 설정도 같은 모양을 씁니다.

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(curl *)"
    ],
    "ask": [
      "Bash(git push *)"
    ]
  }
}

15.1격리 방식 고르기

공식격리 선택지는 여섯 가지이고, 무엇이 경계 안에 들어가는지가 다릅니다. 앞의 두 개는 컨테이너 없이 호스트 OS에서 돌고, 나머지는 클로드코드를 컨테이너나 가상 머신 안에 넣습니다. sandbox-environments

공식목적별 선택은 이렇습니다. 내 기계에서 일상 작업의 프롬프트를 줄이려면 샌드박스 Bash 도구를 /sandbox로 구성합니다. --dangerously-skip-permissions나 자동 모드로 무인 실행을 하려면 개발 컨테이너, 임의 컨테이너·VM, 또는 샌드박스 런타임입니다. 도커 없이 MCP 서버와 훅까지 격리하려면 샌드박스 런타임입니다. 신뢰할 수 없는 저장소를 다루려면 전용 가상 머신이나 클로드코드 웹입니다. 네이티브 윈도우 호스트에서는 컨테이너·VM이거나 WSL2 안의 Bash 샌드박스입니다. sandbox-environments

공식권한 모드와 격리의 관계도 분명합니다. 권한 모드는 도구 호출이 실행될지와 먼저 물어볼지를 정하고, 격리는 실행된 뒤 그 명령이 무엇에 닿을 수 있는지를 제한합니다. --dangerously-skip-permissions는 실수를 잡아 줄 프롬프트가 없으니 내가 고른 격리 경계가 시스템을 지키는 전부입니다. 그래서 이 플래그를 쓰는 세션은 항상 컨테이너·VM·샌드박스 런타임 안에서 돌립니다. 자동 모드의 분류기는 동작별 통제이지 격리 경계가 아니므로, 무인 실행에서는 격리를 겹쳐 놓는 편이 낫습니다. sandbox-environments

15.2샌드박스 Bash 구성

공식샌드박스는 클로드코드에 내장돼 있고 맥·리눅스·WSL2에서 돕니다. 네이티브 윈도우는 지원하지 않으므로 윈도우에서는 WSL2 안에서 실행합니다. 맥은 내장 Seatbelt를 쓰므로 설치할 것이 없습니다. 리눅스와 WSL2는 bubblewrap(파일시스템 격리 강제)과 socat(샌드박스 프록시로 트래픽 중계)이 필요합니다. WSL1은 bubblewrap이 요구하는 커널 기능이 없어 지원되지 않습니다. sandboxing

sudo apt-get install bubblewrap socat   Ubuntu·Debian
sudo dnf install bubblewrap socat       Fedora

공식구성은 /sandbox 명령으로 엽니다. 탭이 세 개(Mode·Overrides·나머지)이고, 리눅스에서 선택적 seccomp 필터가 없으면 Dependencies 탭이 추가로 나타납니다. 의존성 검사는 시작 시 돌기 때문에 패키지를 설치한 뒤에는 클로드코드를 다시 시작해야 감지됩니다. sandboxing

공식모드는 두 가지입니다. 자동 허용 모드는 샌드박스로 감쌀 수 있는 명령을 샌드박스 안에서 돌리고 승인을 자동으로 처리합니다. 샌드박스로 감쌀 수 없는 명령(허용되지 않은 호스트로 네트워크가 필요한 경우 등)은 일반 권한 흐름으로 내려갑니다. 일반 권한 모드는 샌드박스 안에서 돌더라도 모든 Bash 명령을 권한 흐름에 태웁니다. 두 모드에서 샌드박스가 강제하는 파일시스템·네트워크 제약은 같고, 차이는 자동 승인 여부뿐입니다. sandboxing

공식자동 허용 모드에서도 남는 것이 넷 있습니다. 명시적 deny 규칙, /·홈 디렉터리·기타 핵심 시스템 경로를 향한 rm·rmdir, Bash(git push *) 같은 내용 범위 ask 규칙, 그리고 샌드박스로 돌지 못해 일반 흐름으로 내려간 명령에 대한 맨 Bash ask 규칙입니다. 맨 Bash ask 규칙은 샌드박스로 도는 명령에는 건너뛰어집니다. 샌드박스 경계가 그 도구 전체 프롬프트를 대신하기 때문입니다. 단 플랜 모드에서는 건너뛰지 않습니다. sandboxing

공식기본 경계는 이렇습니다. 쓰기는 현재 작업 디렉터리와 그 하위, 그리고 $TMPDIR이 가리키는 세션 임시 디렉터리입니다. 읽기는 몇몇 거부 디렉터리를 뺀 컴퓨터 전체입니다. 이 기본값은 ~/.aws/credentials나 ~/.ssh/ 같은 자격증명 파일 읽기를 여전히 허용합니다. 차단되는 것은 작업 디렉터리와 세션 임시 디렉터리 밖 파일 수정이며, ~/.bashrc 같은 셸 설정과 /bin/의 시스템 바이너리가 여기 들어갑니다. sandboxing

공식경로를 넓히려면 sandbox.filesystem.allowWrite입니다. OS 수준에서 강제되므로 자식 프로세스까지 따릅니다. 도구를 샌드박스에서 아예 빼는 excludedCommands보다 이쪽이 권장되는 방식입니다. 같은 배열이 여러 설정 스코프에 있으면 대체되지 않고 병합됩니다. sandboxing

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

공식읽기 규칙이 겹칠 때는 더 구체적인 경로가 이깁니다. denyRead: ["~/"]에 allowRead: ["~/projects"]를 두면 그 하위만 읽히고 나머지 홈은 막힙니다. 반대로 allowRead: ["~/"]에 denyRead: ["~/.env"]를 두면 그 파일만 막히고 나머지는 읽힙니다. 넓은 allow가 비밀을 조용히 다시 노출하지 못하게 하는 설계입니다. sandboxing

공식네트워크는 샌드박스 밖에서 도는 프록시 서버로 통제됩니다. 기본적으로 미리 허용된 도메인이 없어서, 명령이 새 도메인을 필요로 할 때마다 승인을 물어봅니다. 승인하면 그 호스트가 현재 세션 동안 허용됩니다. 프롬프트 자체를 없애려면 allowedDomains로 미리 허용합니다. WebFetch allow 규칙도 도메인을 미리 허용합니다. sandboxing

공식샌드박스에서 아예 못 도는 명령도 있습니다. 그때 클로드코드는 작업을 실패시키거나 샌드박스를 끄게 하는 대신, 실패를 분석해 dangerouslyDisableSandbox 파라미터로 재시도할 수 있습니다. 재시도된 명령은 샌드박스 밖에서 돌기 때문에 일반 권한 흐름을 타며, 기본 모드에서는 확인 프롬프트가, 자동 모드에서는 분류기 판정이 붙습니다. 자동 모드에서도 매번 물어보게 하려면 Bash(dangerouslyDisableSandbox:true) ask 규칙을 추가합니다. 이 탈출구를 끄려면 "allowUnsandboxedCommands": false입니다. sandboxing

공식실제로 자주 걸리는 비호환 사례가 정리돼 있습니다. jest는 watchman이 비호환이라 jest --no-watchman으로 돌립니다. 맥에서 gh·gcloud·terraform 같은 Go 기반 CLI는 Seatbelt에서 TLS 검증에 실패할 수 있어 excludedCommands에 넣습니다. docker는 비호환이라 docker *를 excludedCommands에 넣습니다. 맥에서 open·osascript나 브라우저 인증 흐름이 -600 오류로 실패하면 Apple Events가 기본 차단된 것이며, allowAppleEvents로 허용할 수 있지만 코드 실행 격리가 사라집니다. sandboxing

공식조직 강제는 관리형 설정으로 합니다. 아래 세 키는 샌드박스를 켜고, 초기화에 실패하면 시작을 막고, 모델이 샌드박스 밖에서 재시도하는 것을 금지합니다. 불리언 키는 관리형 값이 이기지만 excludedCommands·allowRead 같은 배열 키는 스코프 간 병합이라 개발자가 항목을 덧붙여 정책을 넓힐 수 있습니다. 읽기 경로를 잠그려면 allowManagedReadPathsOnly, 네트워크 도메인을 잠그려면 allowManagedDomainsOnly를 관리형 설정에 둡니다. excludedCommands에는 대응하는 잠금이 없으니 관리형 목록을 좁게 유지합니다. sandboxing

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

15.3개발 컨테이너

공식개발 컨테이너는 팀 전원이 같은 격리 환경을 돌리게 하는 방식입니다. 클로드가 실행하는 명령은 호스트가 아니라 컨테이너 안에서 돌고, 프로젝트 파일 편집은 로컬 저장소에 그대로 나타납니다. 설치는 Dev Container Feature 한 줄로 됩니다. devcontainer

{
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}
  }
}

공식끝의 :1.0 태그는 feature의 설치 스크립트를 고정하는 것이고 클로드코드 릴리스를 고정하지 않습니다. feature는 최신 클로드코드를 설치하며, 컨테이너 안에서 클로드코드가 기본적으로 자동 업데이트합니다. 버전을 고정하려면 feature 대신 Dockerfile에서 npm install -g @anthropic-ai/claude-code@X.Y.Z로 설치하고 DISABLE_AUTOUPDATER를 설정합니다. devcontainer

"mounts": [
  "source=claude-code-config,target=/home/node/.claude,type=volume"
],
"containerEnv": {
  "CLAUDE_CONFIG_DIR": "/home/node/.claude"
}

공식조직 정책을 컨테이너에 넣기도 좋습니다. 클로드코드는 리눅스에서 /etc/claude-code/managed-settings.json을 읽고 설정 계층의 최상단으로 적용하므로, Dockerfile에서 그 자리에 복사하면 됩니다. 다만 Dockerfile이 저장소에 있으니 쓰기 권한이 있는 사람이 그 단계를 바꾸거나 지울 수 있습니다. 개발자가 저장소 파일 편집으로 우회할 수 없는 정책은 서버 관리형 설정이나 MDM으로 배포합니다. devcontainer

공식참조 구성은 anthropics/claude-code 저장소의 .devcontainer/에 있고 파일 세 개입니다. devcontainer.json(볼륨 마운트·runArgs 권한·확장·containerEnv), Dockerfile(베이스 이미지·개발 도구·클로드코드 설치), init-firewall.sh(허용 도메인 외 모든 아웃바운드 차단)입니다. 컨테이너 안에서 방화벽을 돌리려면 추가 권한이 필요해 참조 구성은 runArgs로 NET_ADMIN과 NET_RAW를 붙입니다. 이 방화벽과 권한은 클로드코드 자체에는 필요하지 않으므로 자체 네트워크 통제가 있으면 빼도 됩니다. 유지 관리되는 베이스 이미지가 아니라 조합 예시로 제공되는 것입니다. devcontainer

15.4워크트리 격리 맛보기

공식git 워크트리는 자체 파일과 브랜치를 가진 별도 작업 디렉터리이며, 저장소 히스토리와 원격은 메인 체크아웃과 공유합니다. 세션마다 워크트리를 하나씩 쓰면 한 세션의 편집이 다른 세션의 파일에 닿지 않습니다. worktrees

claude --worktree feature-auth

공식기본적으로 워크트리는 저장소 루트의 .claude/worktrees/<name>/에 만들어지고 worktree-<name>이라는 새 브랜치에 놓입니다. 이름을 생략하면 클로드가 하나 생성합니다. .claude/worktrees/를 .gitignore에 넣어 메인 체크아웃에서 untracked 파일로 보이지 않게 합니다. worktrees

공식L2에서 알아 둘 것은 워크트리가 메인 체크아웃과 무엇을 공유하는지입니다. 세 가지입니다. 저장소의 .git 디렉터리(그래서 샌드박스를 켜도 워크트리 안에서 git commit이 됩니다), 프로젝트 스코프로 설치한 플러그인, 그리고 저장된 권한 승인입니다. 워크트리 세션에서 "예, 다시 묻지 않기"를 누르면 규칙이 메인 체크아웃의 .claude/settings.local.json에 저장되어 메인과 다른 모든 워크트리에 적용되고, 그 워크트리가 삭제돼도 남습니다. worktrees

공식워크트리는 새 체크아웃이라 .env 같은 gitignore된 파일이 없습니다. 새 워크트리마다 자동으로 복사하려면 프로젝트 루트에 .worktreeinclude를 둡니다. .gitignore 문법을 쓰며, 패턴에 매칭되고 또한 gitignore된 파일만 복사되므로 추적되는 파일은 중복되지 않습니다. worktrees

.env
.env.local
config/secrets.json

공식정리는 대화형 세션을 나갈 때 처리됩니다. 워크트리가 깨끗하면 이름 없는 세션은 워크트리와 브랜치를 자동으로 지우고, 이름 붙인 세션은 먼저 물어봅니다. 작업이 남아 있으면 유지할지 지울지 묻습니다. -p 비대화 실행은 종료 프롬프트가 없어 정리되지 않으므로 git worktree remove로 지웁니다. 서브에이전트와 백그라운드 세션의 워크트리는 cleanupPeriodDays보다 오래되면 주기적 스윕이 지우지만, 변경·untracked 파일이나 push되지 않은 커밋이 있으면 건너뜁니다. --worktree로 내가 만든 워크트리는 스윕이 절대 지우지 않습니다. worktrees

16.1스코프와 우선순위

공식설정 스코프는 네 개입니다. 어디에 두는지가 누구에게 적용되는지를 정합니다. settings

공식같은 설정이 여러 스코프에 있으면 아래 순서로 적용됩니다. settings

1. 관리형        가장 높음. 다른 어떤 스코프도 덮어쓸 수 없음(정해진 예외 제외)
2. 명령줄 인자   임시 세션 오버라이드
3. 로컬          프로젝트와 사용자를 덮어씀
4. 프로젝트      사용자를 덮어씀
5. 사용자        가장 낮음. 아무것도 지정하지 않았을 때 적용

공식관리형 설정 배포 경로는 여러 가지입니다. 사인인 시 원격으로 전달되는 서버 관리형 설정, MDM과 OS 정책(맥 com.anthropic.claudecode 관리 환경설정 도메인, 윈도우 HKLM\SOFTWARE\Policies\ClaudeCode 또는 사용자 수준 HKCU), 그리고 파일 배포입니다. 파일 위치는 맥 /Library/Application Support/ClaudeCode/, 리눅스와 WSL /etc/claude-code/, 윈도우 C:\Program Files\ClaudeCode\입니다. settings

공식일부 설정은 관리형 설정에서만 읽힙니다. 사용자·프로젝트 파일에 넣어도 효과가 없습니다. 자주 쓰이는 것으로 allowManagedPermissionRulesOnly(사용자·프로젝트가 권한 규칙을 정의하지 못하게), allowManagedHooksOnly(관리형 훅만 로드), allowManagedMcpServersOnly, strictPluginOnlyCustomization(스킬·에이전트·훅·MCP를 플러그인과 관리형 설정으로만 제한), disableSideloadFlags, claudeMd가 있습니다. permissions

공식편집이 언제 반영되는지도 중요합니다. 클로드코드는 설정 파일을 감시해 바뀌면 다시 읽으므로 대부분의 키는 재시작 없이 도는 세션에 적용됩니다. permissions, hooks, apiKeyHelper 같은 자격증명 헬퍼가 여기 포함되고, 사용자·프로젝트·로컬·관리형 설정 모두 대상이며 감지된 변경마다 ConfigChange 훅이 돕니다. 반면 세션 시작 시 한 번만 읽는 키가 둘 있습니다. model(세션 중 전환은 /model)과 outputStyle(시스템 프롬프트의 일부라 /clear나 재시작에서 재구성)입니다. settings

16.2settings.json 주요 항목

설정 키는 100개를 넘습니다. 아래 표는 이 편의 주제(맥락과 통제)에 직접 쓰이는 키만 목적별로 묶은 것입니다. 전체 목록은 공식 settings 문서가 정본입니다. 나머지 영역의 키는 그 기능을 다루는 편에서 함께 봅니다. 훅과 스킬 관련 키는 L3, 서브에이전트와 워크플로 키는 L4, 텔레메트리와 조직 정책 키는 L6입니다.

공식설정 파일 맨 위에 $schema를 넣으면 편집기가 키 이름과 값을 검증해 줍니다. 오타로 인한 무시를 줄이는 가장 값싼 방법입니다. settings

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "deny": ["Bash(curl *)", "Read(./.env)", "Read(./secrets/**)"]
  }
}

16.3환경 변수

공식설정 파일의 env 블록과 셸에 같은 변수가 있으면 설정 파일 값이 적용됩니다. 클로드코드가 시작 시, 그리고 파일이 바뀔 때마다 각 env 항목을 프로세스 환경에 써서 셸에서 물려받은 값을 대체합니다. 여러 설정 파일에 걸쳐 있으면 설정 우선순위를 따르므로 관리형 설정 항목이 사용자·프로젝트를 덮습니다. env-vars

이 편의 주제와 관련된 변수만 모았습니다. 전체 목록은 공식 env-vars 문서에 있습니다.

16.4설정이 안 먹을 때

공식진단은 무엇이 실제로 로드됐는지 보는 것부터 시작합니다. /context가 지금 컨텍스트를 범주별로 보여주므로 CLAUDE.md·규칙·스킬 설명이 아예 들어왔는지를 먼저 확인합니다. 그다음 범주별 전용 명령으로 내려갑니다. debug-your-config

공식터미널에서 세션을 열지 않고 보려면 claude doctor가 설치와 설정 진단을 읽기 전용으로 출력합니다. debug-your-config

공식아래는 공식 문서의 증상별 대조표에서 이 편의 주제에 해당하는 항목입니다. debug-your-config

공식훅 스키마 오류는 파급이 큽니다. matcher에 배열을 쓰면 클로드코드가 설정 오류 알림을 띄우고 사용자·프로젝트·로컬 설정 파일 전체를 거부하므로, 그 파일의 다른 훅도 /hooks에 나타나지 않습니다. claude doctor가 검증 실패를 보고합니다. debug-your-config

공식어느 표면이 원인인지 좁히는 방법은 두 단계입니다. 먼저 claude --safe-mode로 모든 커스터마이징을 끈 세션을 엽니다. CLAUDE.md·스킬·플러그인·훅·MCP 서버·커스텀 명령과 에이전트가 전부 비활성이고, 인증·모델 선택·내장 도구·권한은 정상 동작합니다. 안전 모드에서도 조직의 관리형 훅과 설정 정책은 적용됩니다. 문제가 사라지면 그 표면들 중 하나가 원인입니다. debug-your-config

공식그래도 남거나 설정 자체가 의심되면 아무것도 로드하지 않는 세션과 비교합니다. CLAUDE_CONFIG_DIR을 빈 디렉터리로 가리키고, .claude·.mcp.json·CLAUDE.md가 없는 디렉터리에서 실행합니다. debug-your-config

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

공식첫 실행에서는 테마 선택부터 시작하는 초기 설정 화면이 뜹니다. 그 화면이 보이면 깨끗한 설정 디렉터리가 실제로 적용된 것입니다. 리눅스와 윈도우에서는 자격증명이 설정 디렉터리 아래에 있어 다시 로그인을 요청받고, 맥에서는 키체인에 있어 그대로 넘어갑니다. 조직이 관리형 설정을 배포한다면 그것은 ~/.claude 밖 시스템 경로에 있으므로 여전히 적용됩니다. debug-your-config

16.5내 설정을 여러 기기에서 같게 유지하기

실전맥과 윈도우를 번갈아 쓰면 설정 동기화가 실제 문제가 됩니다. 이 볼트를 쓰는 환경에서 실패했던 방식과 남은 방식을 그대로 적습니다.

실전먼저 하지 말아야 할 것입니다. ~/.claude 디렉터리 전체를 클라우드 드라이브에 심링크하거나 동기화하지 않습니다. 이 디렉터리에는 설정만 있는 것이 아니라 세션 전사, 프롬프트 기록, 파일 스냅숏, 자격증명이 함께 들어 있습니다(13.7절). 전사는 평문이고 계속 쓰이므로 동기화 충돌이 잦고, 자격증명까지 클라우드에 올라갑니다.

실전대신 동기화 대상을 세 종류로 나눠 취급하는 편이 안정적이었습니다. 첫째, 팀·프로젝트에 속하는 것은 저장소에 커밋합니다. CLAUDE.md, .claude/settings.json, .claude/rules/, .claude/skills/가 여기 해당합니다. 이러면 기기 간 동기화 문제가 애초에 git 문제로 환원됩니다. 둘째, 개인 것 중 기기와 무관한 것만 따로 관리합니다. ~/.claude/CLAUDE.md, ~/.claude/rules/, ~/.claude/settings.json이 대상입니다. 셋째, 기기에 묶인 것은 동기화하지 않습니다. 자격증명, 전사, 자동 메모리(기기 로컬이라고 공식 문서가 명시), ~/.claude.json입니다.

공식설정 디렉터리 자체를 옮길 수 있다는 것도 알아 둘 만합니다. CLAUDE_CONFIG_DIR은 홈을 여러 기기에서 공유할 때나 컨테이너화할 때 쓰라고 문서에 명시된 용도입니다. 개발 컨테이너에서 로그인을 유지하는 방법이 바로 이 변수를 볼륨 경로로 지정하는 것입니다(15.3절). env-vars

17.1위협 모델

공식기본 구조는 읽기 전용 권한에서 출발하는 것입니다. 파일 편집, 테스트 실행, 명령 실행처럼 추가 동작이 필요하면 명시적 승인을 요청합니다. 그리고 작업 디렉터리 경계가 있습니다. 클로드코드는 시작한 폴더와 그 하위에만 쓸 수 있고, 상위 디렉터리 파일은 명시적 권한 없이 수정하지 못합니다. Read·Grep·Glob으로 경계 밖을 읽는 것은 승인 프롬프트 뒤에 가능합니다. security

공식인젝션에 대한 방어층은 여러 개입니다. 핵심 방어로 권한 시스템, 요청 전체를 분석하는 맥락 인식, 입력 살균, 그리고 네트워크 명령 승인이 있습니다. curl과 wget처럼 웹에서 내용을 가져오는 명령은 기본적으로 자동 승인되지 않고 다른 비읽기 명령처럼 물어봅니다. security

공식추가 안전장치도 목록으로 명시돼 있습니다. 네트워크 요청 도구는 기본적으로 사용자 승인이 필요하고, 웹 페치는 격리된 별도 컨텍스트 윈도우를 써서 악의적 프롬프트가 주 대화에 주입되는 것을 피합니다. 처음 실행하는 코드베이스와 새 MCP 서버는 신뢰 확인을 요구합니다. 의심스러운 bash 명령은 이전에 허용목록에 있었더라도 수동 승인을 요구하고, 매칭되지 않는 명령은 수동 승인으로 떨어집니다(fail-closed). 복잡한 bash 명령에는 자연어 설명이 붙습니다. API 키와 토큰은 가능하면 맥 키체인에, 윈도우와 리눅스에서는 파일 권한으로 보호됩니다. security

공식자동 모드가 켜진 세션에서는 분류기가 무엇을 보는지도 위협 모델의 일부입니다. 분류기는 사용자 메시지, 도구 호출, CLAUDE.md 내용을 봅니다. 도구 결과는 제거됩니다. 그래서 파일이나 웹 페이지의 적대적 콘텐츠가 분류기를 직접 조종할 수 없습니다. 별도의 서버 측 프로브가 들어오는 도구 결과를 훑어 의심스러운 콘텐츠를 클로드가 읽기 전에 표시합니다. permission-modes

공식MCP는 별도로 봐야 합니다. Anthropic은 커넥터를 디렉터리에 추가하기 전에 등재 기준에 대해 검토하지만, 어떤 MCP 서버도 보안 감사하거나 관리하지 않습니다. 직접 만든 서버나 신뢰하는 제공자의 서버를 쓰고, MCP 서버에 대한 권한을 설정합니다. security

17.2안전 운영 수칙

공식민감한 코드를 다룰 때의 권고는 네 가지입니다. 제안된 모든 변경을 승인 전에 검토하기, 민감한 저장소에는 프로젝트별 권한 설정을 쓰기, 추가 격리가 필요하면 개발 컨테이너를 고려하기, 그리고 /permissions로 권한 설정을 주기적으로 감사하기입니다. security

공식팀 단위에서는 관리형 설정으로 조직 표준을 강제하고, 승인된 권한 구성을 버전 관리로 공유하고, OpenTelemetry 메트릭으로 사용을 모니터링하고, ConfigChange 훅으로 세션 중 설정 변경을 감사하거나 차단합니다. security

관행자격증명 파일 읽기를 규칙으로 막는 것과 값이 애초에 저장소 안에 없게 하는 것은 다른 층입니다. deny 규칙은 클로드의 내장 도구와 인식되는 파일 명령만 막고, 파이썬 스크립트가 스스로 파일을 여는 것은 막지 못합니다(14.2절). 그래서 두 가지를 함께 씁니다. 규칙으로 흔한 경로를 막고, 실제 값은 저장소 밖에 둡니다.

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(~/.aws/**)",
      "Read(~/.ssh/**)",
      "Edit(~/.ssh/**)"
    ]
  }
}

공식샌드박스를 쓴다면 sandbox.credentials로 한 층을 더 얹을 수 있습니다. 기본 읽기 정책이 ~/.aws/credentials와 ~/.ssh/를 여전히 허용하기 때문에, 조직 배포에서는 그 디렉터리와 비밀 환경 변수를 이 키로 명시하라고 문서가 권합니다(15.2절). sandboxing

공식보안 취약점을 발견했을 때의 절차도 정해져 있습니다. 공개하지 않고 HackerOne 프로그램으로 보고하며, 재현 단계를 포함하고, 공개 전에 수정할 시간을 줍니다. security

17.3데이터 취급

공식클로드코드는 로컬에서 돌지만 모델과 상호작용하려면 네트워크로 데이터를 보냅니다. 여기에는 모든 사용자 프롬프트와 모델 출력이 포함되며 TLS 1.2 이상으로 전송 중 암호화됩니다. 저장 시 암호화는 모델 프로바이더에 달렸고, Anthropic API는 인프라 수준 디스크 암호화(AES-256)입니다. data-usage

공식학습 정책은 계정 종류로 갈립니다. 무료·Pro·Max 소비자 계정은 데이터를 모델 개선에 쓸지 선택할 수 있고, 그 설정이 켜져 있으면 클로드코드 사용분을 포함해 학습에 씁니다. Team·Enterprise·API·서드파티 플랫폼·Claude Gov 같은 상업 계정은 고객이 명시적으로 제공을 선택한 경우(예: Development Partner Program)를 제외하고 클로드코드로 보낸 코드나 프롬프트로 생성 모델을 학습하지 않습니다. data-usage

공식보관 기간도 계정 종류로 갈립니다. data-usage

공식운영 텔레메트리는 두 종류이고 각각 따로 끕니다. 메트릭은 지연·신뢰성·사용 패턴이며 코드·프롬프트·파일 경로를 절대 포함하지 않고, DISABLE_TELEMETRY=1로 끕니다. 오류 보고는 클로드코드 내부의 오류 메시지와 스택 트레이스이며, 알려진 비밀·파일 경로·이메일·개인정보 패턴을 기기에서 나가기 전에 제거하고, DISABLE_ERROR_REPORTING=1로 끕니다. 둘을 한꺼번에 끄려면 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC입니다. data-usage

공식기본값은 프로바이더에 따라 다릅니다. Claude API에서는 메트릭이 기본 켜짐, /feedback 보고도 기본 켜짐이며, 오류 보고는 Pro·Max 사인인에 v2.1.198 이상일 때 켜집니다. Amazon Bedrock, Google Cloud Agent Platform, Microsoft Foundry, Claude Platform on AWS에서는 오류 보고·텔레메트리·버그 보고가 기본으로 꺼져 있습니다. data-usage

공식/feedback을 실행하면 코드를 포함한 대화 기록 사본이 Anthropic으로 갑니다. /bug와 /share도 같은 경로입니다. 제출 전에 얼마나 포함할지 고를 수 있으며, 기본값은 현재 세션만이고 같은 프로젝트의 지난 24시간이나 7일 세션도 선택할 수 있습니다. 끄려면 DISABLE_FEEDBACK_COMMAND=1입니다. 서드파티 프로바이더를 쓰거나 Anthropic 자격증명이 없으면 전송 대신 ~/.claude/feedback-bundles/에 로컬 아카이브로 씁니다. data-usage

공식세션 품질 설문("How is Claude doing this session?")은 별개입니다. 평점만 기록하며 대화 전사·입력·출력을 수집하거나 저장하지 않습니다. 그 뒤에 전사 공유를 묻는 후속 질문이 따로 나오는데, Yes를 명시적으로 고르기 전에는 아무것도 업로드되지 않습니다. 끄려면 CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1입니다. data-usage

여기까지 하면 새 프로젝트를 받았을 때 30분 안에 세팅할 수 있는 상태가 됩니다. 다음 편에서는 없는 기능을 직접 만드는 쪽으로 넘어갑니다. 스킬, 서브에이전트, 훅, MCP입니다. 이 편에서 "그건 훅으로 하는 게 맞다"고 판정만 하고 넘긴 것들을 실제로 만듭니다.

18.1확장 수단 전량

공식내장 도구가 대부분의 코딩 작업을 덮습니다. 확장은 그 위에 얹는 층이며, 각 수단이 에이전트 루프의 다른 지점에 끼워집니다. features-overview

공식플러그인은 그 위의 포장 층입니다. 스킬·훅·서브에이전트·MCP 서버를 하나의 설치 단위로 묶습니다. 플러그인 스킬은 /my-plugin:review처럼 이름공간을 쓰므로 여러 플러그인이 충돌 없이 공존합니다. 같은 세팅을 여러 저장소에서 재사용하거나 마켓플레이스로 남에게 배포할 때 씁니다. features-overview

공식맥락 비용은 수단마다 다릅니다. 이것이 무엇을 어디에 둘지 정하는 실질 기준입니다. features-overview

공식계층이 겹칠 때의 규칙도 수단마다 다릅니다. CLAUDE.md는 더해집니다(모든 계층이 동시에 기여). 스킬과 서브에이전트는 이름으로 덮습니다(스킬은 관리형 > 사용자 > 프로젝트, 서브에이전트는 관리형 > CLI 플래그 > 프로젝트 > 사용자 > 플러그인). MCP 서버도 이름으로 덮습니다(로컬 > 프로젝트 > 사용자). 훅은 병합됩니다(출처와 무관하게 매칭되는 모든 훅이 발동). features-overview

18.2무엇을 언제 쓰나

공식처음부터 전부 세팅할 필요는 없습니다. 각 수단에는 알아볼 수 있는 계기가 있고, 대부분의 팀이 대략 아래 순서로 더해 갑니다. features-overview

공식같은 계기가 이미 있는 것을 언제 고칠지도 알려 줍니다. 반복되는 실수나 재발하는 리뷰 코멘트는 대화에서의 일회성 교정이 아니라 CLAUDE.md 수정입니다. 손으로 계속 조정하는 워크플로는 개정이 필요한 스킬입니다. features-overview

헷갈리기 쉬운 짝이 넷 있습니다. 각각의 갈림은 공식 문서가 표로 정리해 둔 것입니다.

공식이 둘은 서로 다른 문제를 풀고 함께 잘 돕니다. MCP 서버가 클로드를 데이터베이스에 연결하고, 스킬이 데이터 모델과 흔한 질의 패턴, 작업별로 어느 표를 쓸지를 가르칩니다. features-overview

공식실제 세팅은 조합입니다. 공식 문서가 드는 조합 넷입니다. 스킬 + MCP(연결은 MCP, 잘 쓰는 법은 스킬), 스킬 + 서브에이전트(스킬이 병렬 서브에이전트를 띄운다), CLAUDE.md + 스킬(항상 켜진 규칙과 온디맨드 참조 자료), 훅 + MCP(훅이 MCP를 통해 외부 동작을 발생시킨다). features-overview

실전이 판정을 실제로 해 보면 한쪽으로 기울기 쉽습니다. 이 가이드를 쓰는 볼트를 세어 보니 훅 핸들러가 12개(프로젝트 10 + 사용자 2)인데 스킬은 2개, 서브에이전트는 1개, MCP 서버는 1개였습니다. 훅으로 보장할 것을 훅에 둔 것은 맞지만, 반복 절차를 스킬로 옮기지 않아 같은 지시를 계속 입력하는 상태이기도 했습니다. 자기 프로젝트의 기울기는 아래로 한 번에 확인됩니다.

ls .claude/skills ~/.claude/skills 2>/dev/null | wc -l      스킬 수
ls .claude/agents ~/.claude/agents 2>/dev/null | wc -l      서브에이전트 수
python3 -c "import json;d=json.load(open('.claude/settings.json'));print(sum(len(m.get('hooks',[])) for v in d.get('hooks',{}).values() for m in v))"

19.1스킬이란

공식스킬은 지시가 담긴 SKILL.md 파일 하나이고, 그것을 만들면 클로드의 도구 모음에 추가됩니다. 클로드가 관련 있을 때 쓰거나 내가 /skill-name으로 직접 부릅니다. 만들 시점은 두 가지입니다. 같은 지시·체크리스트·다단계 절차를 대화에 계속 붙여넣을 때, 또는 CLAUDE.md의 한 섹션이 사실이 아니라 절차로 자라났을 때입니다. skills

공식CLAUDE.md 내용과 달리 스킬 본문은 쓸 때만 로드됩니다. 그래서 긴 참조 자료를 담아도 필요할 때까지 비용이 거의 없습니다. skills

공식어디에 두는지가 누가 쓸 수 있는지를 정합니다. skills

공식이름이 겹치면 조직이 개인을, 개인이 프로젝트를 덮습니다. 어느 계층의 스킬이든 같은 이름의 내장 스킬을 덮으므로, 프로젝트의 code-review 스킬이 내장 /code-review를 대체합니다. 플러그인 스킬은 plugin-name:skill-name 이름공간을 쓰므로 충돌하지 않습니다. skills

공식프로젝트 스킬은 클로드코드를 시작한 디렉터리와 저장소 루트까지의 모든 상위 디렉터리에서 로드됩니다. 시작 디렉터리 아래의 중첩 .claude/skills/는 시작 시 로드되지 않고, 클로드가 그 하위 디렉터리의 파일을 처음 읽거나 편집할 때 로드되어 세션 내내 남습니다. 그때까지는 자동완성에 나타나지도, 이름으로 호출되지도 않습니다. skills

19.2정의 파일 구조

공식스킬은 디렉터리이고 SKILL.md가 진입점입니다. 나머지 파일은 선택이며, 템플릿·예시 출력·클로드가 실행할 스크립트·상세 참조 문서를 담습니다. skills

my-skill/
├── SKILL.md           메인 지시(필수)
├── reference.md       상세 API 문서(필요할 때 로드)
├── examples.md        사용 예시(필요할 때 로드)
└── scripts/
    └── helper.py      유틸리티 스크립트(로드가 아니라 실행)

공식내용은 성격에 따라 두 갈래입니다. 참조 내용은 클로드가 지금 작업에 적용하는 지식입니다(관례·패턴·스타일 가이드·도메인 지식). 대화 맥락과 나란히 쓸 수 있도록 인라인으로 돕니다. 작업 내용은 배포·커밋·코드 생성처럼 특정 동작의 단계별 지시입니다. 보통 클로드가 판단하게 두지 않고 /skill-name으로 직접 부릅니다. skills

공식프론트매터 필드는 모두 선택이고 description만 권장입니다. 자주 쓰는 것부터 봅니다. skills

공식불리언 필드는 true·false 외에 yes·no·on·off·1·0도 대소문자 구분 없이 받습니다. skills

공식호출된 스킬의 내용은 렌더된 상태로 대화에 하나의 메시지로 들어가 세션 내내 남습니다. 클로드코드는 이후 턴에서 스킬 파일을 다시 읽지 않으므로, 작업 전체에 적용돼야 하는 안내는 일회성 단계가 아니라 상시 지시로 씁니다. 같은 내용으로 재호출하면 사본을 또 붙이지 않고 이미 로드됐다는 짧은 메모만 답니다. 인자나 동적 맥락이 달라져 렌더 결과가 다르면 전문을 다시 붙입니다. skills

공식자동 압축은 호출된 스킬을 토큰 예산 안에서 이어 갑니다. 각 스킬의 가장 최근 호출을 요약 뒤에 다시 붙이며 스킬당 첫 5,000 토큰을 유지하고, 합계 25,000 토큰을 가장 최근 호출부터 채웁니다. 한 세션에서 많이 호출했다면 오래된 스킬은 압축 후 통째로 사라질 수 있습니다. skills

19.3트리거 설계

공식클로드는 내 작업을 스킬 설명과 대조해 어느 것이 관련 있는지 판단합니다. 설명이 모호하거나 서로 겹치면 엉뚱한 스킬을 로드하거나 도움이 될 스킬을 놓칩니다. 특정 스킬을 쓰게 하려면 /name으로 직접 부릅니다. skills

공식누가 호출할 수 있는지는 두 필드가 정하고, 그것이 맥락 비용도 바꿉니다. skills

공식스킬이 많아지면 설명이 잘립니다. 클로드코드는 스킬 이름과 설명 목록을 맥락에 로드하는데, 목록에는 항상 모든 이름이 들어가지만 문자 예산을 넘기면 설명을 줄입니다. 예산은 모델 컨텍스트 윈도우의 1퍼센트로 스케일되고, 넘칠 때는 가장 덜 호출하는 스킬부터 설명을 버리므로 자주 쓰는 스킬은 전문을 유지합니다. skills

공식예산을 올리려면 skillListingBudgetFraction(예: 0.02는 2퍼센트)이나 환경 변수 SLASH_COMMAND_TOOL_CHAR_BUDGET을 씁니다. 다른 스킬에 예산을 넘겨주려면 낮은 우선순위 항목을 skillOverrides에서 "name-only"로 둡니다. 원본에서 줄이는 방법도 있습니다. 항목별 합계가 예산과 무관하게 1,536자로 잘리므로 핵심 용도를 앞에 씁니다. 이 상한은 skillListingMaxDescChars로 조정합니다. skills

실전설명이 발화를 결정한다는 말의 무게는 실제 파일을 재 보면 드러납니다. 이 볼트의 스킬 두 개를 재어 보니 description이 각각 789자와 514자였고, 본문은 3,148자(50줄)와 3,841자(62줄)였습니다. 즉 설명이 본문의 4분의 1 분량입니다. 발화 조건이 그 안에 다 들어가야 해서 그렇게 됐습니다. 한 스킬의 설명에는 한국어 트리거("PPT 만들어줘", "슬라이드 만들어줘", "발표자료 만들어")와 영어 트리거를 나란히 넣었고, 마지막에 쓰지 말아야 할 경우도 한 줄 넣었습니다("장문 강의 코스에는 쓰지 말 것"). 오발화를 줄이는 데 이 한 줄이 실제로 효과가 있었습니다.

python3 - <<'EOF'
import re, glob
for f in glob.glob(".claude/skills/*/SKILL.md") + glob.glob("~/.claude/skills/*/SKILL.md"):
    t = open(f, encoding="utf-8").read()
    m = re.search(r"^---\n(.*?)\n---\n", t, re.S)
    d = re.search(r"^description:\s*(.*)$", m.group(1), re.M)
    print(len(d.group(1)) if d else 0, "자 |", f)
EOF

19.4인자와 파일 참조

공식나와 클로드 모두 스킬을 호출할 때 인자를 넘길 수 있습니다. 본문에서 쓸 수 있는 치환은 아래와 같습니다. skills

---
name: render-chart
description: Render a chart from a CSV file
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---

Run `${CLAUDE_SKILL_DIR}/scripts/render.sh <csv-file>` to render the chart.

공식위치 인자는 셸 방식 인용을 씁니다. /my-skill "hello world" second는 $0을 hello world로, $1을 second로 확장합니다. 대응 인자가 없는 위치 자리(예: 하나만 넘겼을 때의 $2)는 본문에 그대로 남고, 이름 붙은 자리는 빈 문자열이 됩니다. 숫자나 ARGUMENTS 앞의 리터럴 $는 백슬래시로 이스케이프합니다(\$1.00). skills

공식메시지 앞에 스킬 여러 개를 쌓을 수 있습니다. /write-tests /fix-issue 123은 둘을 모두 로드하고 뒤의 123을 양쪽 $ARGUMENTS로 넘깁니다. 첫 스킬 뒤로 최대 5개까지 확장하며, 인라인 사용자 호출 스킬이 아닌 첫 토큰에서 확장이 멈춥니다. 포크 서브에이전트로 도는 스킬(/code-review)이나 인자가 슬래시로 시작할 수 있는 스킬(/loop)도 거기서 끝냅니다. skills

공식보조 파일은 SKILL.md에서 참조해 클로드가 각 파일에 무엇이 있고 언제 로드할지 알게 합니다. 이렇게 하면 큰 참조 문서가 매번 맥락에 들어오지 않습니다. skills

## Additional resources

- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

공식실행 결과를 미리 넣는 방법도 있습니다. !`<command>` 문법은 스킬 내용이 클로드에게 전달되기 전에 셸 명령을 돌리고 그 출력으로 자리를 대체합니다. 클로드가 실행하는 것이 아니라 전처리이고, 클로드는 최종 결과만 봅니다. 여러 줄이면 ```!로 여는 코드 블록을 씁니다. skills

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

19.5첫 스킬 만들기

mkdir -p .claude/skills/release-notes
cat > .claude/skills/release-notes/SKILL.md <<'EOF'
---
name: release-notes
description: 마지막 태그 이후의 커밋으로 릴리스 노트를 쓴다. "릴리스 노트 써줘", "변경사항 정리해줘" 같은 요청에 쓴다.
allowed-tools: Bash(git log *) Bash(git tag *)
---

마지막 태그 이후 커밋을 모아 릴리스 노트를 씁니다.

1. `git describe --tags --abbrev=0` 으로 마지막 태그를 찾습니다.
2. 그 태그 이후 커밋을 `git log --oneline` 으로 읽습니다.
3. 사용자에게 보이는 변경만 남기고 내부 리팩토링은 뺍니다.
4. 기능 · 수정 · 주의 세 갈래로 묶어 씁니다.
EOF

공식스킬이 발동하는 것을 봤다고 해서 의도한 일을 했다는 뜻은 아닙니다. 두 가지를 따로 재야 합니다. 발동해야 할 프롬프트에서 실제로 발동하는지, 그리고 발동했을 때 출력이 기대와 맞는지입니다. 둘 다의 검사는 기준선 비교입니다. 현실적인 프롬프트 몇 개를 모아 스킬이 있는 새 세션과 끈 세션에서 각각 돌려 비교합니다. 새 세션이 중요한데, 스킬을 만들며 쌓인 맥락이 지시문의 결손을 가려 주기 때문입니다. skills

/plugin install skill-creator@claude-plugins-official

공식설치가 실패하면 메시지를 봅니다. Marketplace "claude-plugins-official" not found면 /plugin marketplace add anthropics/claude-plugins-official로 마켓플레이스를 추가한 뒤 다시 설치합니다. 설치 요약에 Run /reload-plugins to activate.가 나오면 그 명령으로 현재 세션에 반영합니다. skills

19.6스킬 안티패턴

공식공식 문서가 드는 두 가지 고장부터 봅니다. 발동하지 않을 때는 설명에 사용자가 자연스럽게 말할 키워드가 들어 있는지 확인하고, 스킬이 목록에 보이는지 확인하고, 요청 문구를 설명에 가깝게 바꿔 보고, 사용자 호출이 가능하면 /name으로 직접 부릅니다. 너무 자주 발동할 때는 설명을 더 구체적으로 만들고, 수동 호출만 원하면 disable-model-invocation: true를 답니다. skills

공식첫 응답 이후 스킬이 영향을 못 미치는 것처럼 보이는 경우도 있습니다. 대개 내용은 여전히 맥락에 있고 모델이 다른 도구나 접근을 고르는 것입니다. 설명과 지시를 강화해 모델이 계속 그것을 선호하게 하거나, 결정론적으로 강제하려면 훅을 씁니다. 스킬이 크거나 그 뒤에 여럿을 호출했다면 압축 후 다시 호출해 전문을 복구합니다. skills

관행세 번째 안티패턴은 자리가 틀린 스킬입니다. 스킬은 때때로 필요한 것을 담는 자리인데, 매 세션 필요한 사실을 스킬에 넣으면 클로드가 그 스킬을 부르지 않은 세션에서 그 사실을 모릅니다. 반대로 반드시 지켜져야 하는 금지를 스킬에 적으면 강제력이 없습니다(18.2절). 매 세션 필요한 것은 CLAUDE.md, 반드시 도는 것은 훅입니다.

실전네 번째는 승인되지 않은 프로젝트 스킬입니다. 프로젝트 .claude/skills/의 allowed-tools는 그 폴더의 워크스페이스 신뢰 대화를 수락한 뒤에 적용됩니다. 이 볼트에서 확인해 보니 신뢰 수락 상태가 ~/.claude.json의 프로젝트 항목에 hasTrustDialogAccepted로 기록돼 있었습니다. 즉 남의 저장소를 클론해 열면 그 저장소의 스킬이 스스로에게 넓은 도구 권한을 부여할 수 있으므로, 신뢰하기 전에 프로젝트 스킬을 읽어 보는 것이 맞습니다.

grep -l "allowed-tools" .claude/skills/*/SKILL.md   신뢰 전에 읽어 볼 대상

공식남이 쓴 스킬을 파일을 고치지 않고 통제하려면 skillOverrides 설정을 씁니다. /skills 메뉴에서 항목을 고르고 Space로 상태를 순환한 뒤 Enter로 저장하면 .claude/settings.local.json에 기록됩니다. skills

공식클로드가 부를 수 있는 스킬을 권한으로 통제할 수도 있습니다. /permissions의 deny에 Skill을 넣으면 전부 막고, Skill(commit)은 정확히 일치, Skill(review-pr *)은 접두어 일치입니다. 플러그인 스킬은 skillOverrides의 영향을 받지 않으므로 /plugin으로 관리합니다. skills

20.1컨텍스트 분리의 이점

공식서브에이전트는 특정 종류의 작업을 맡는 전문 조수입니다. 부수 작업이 다시 볼 일 없는 검색 결과·로그·파일 내용으로 메인 대화를 채울 때 씁니다. 그 작업을 자기 맥락에서 하고 요약만 돌려줍니다. 각 서브에이전트는 자체 컨텍스트 윈도우, 커스텀 시스템 프롬프트, 특정 도구 접근, 독립 권한으로 돕니다. sub-agents

공식이득은 다섯입니다. 탐색과 구현을 메인 대화 밖에 두어 맥락 보존, 쓸 수 있는 도구를 제한해 제약 강제, 사용자 수준 서브에이전트로 프로젝트 간 구성 재사용, 도메인별 집중 시스템 프롬프트로 동작 특화, Haiku 같은 빠르고 싼 모델로 작업을 돌려 비용 통제입니다. sub-agents

공식비포크 서브에이전트의 초기 맥락에 들어가는 것은 셋입니다. 에이전트 자신의 시스템 프롬프트(전체 클로드코드 시스템 프롬프트가 아니라 여기에 환경 정보가 붙은 것), 클로드가 작성한 위임 프롬프트, 그리고 메인 대화가 로드한 CLAUDE.md 계층 전체입니다. 대화 기록, 이미 호출한 스킬, 클로드가 이미 읽은 파일은 보이지 않습니다. sub-agents

공식내장 서브에이전트는 대화형 세션에서 기본 등록됩니다. sub-agents

공식Explore를 부를 때 클로드는 철저도를 함께 지정합니다. 표적 조회는 quick, 균형 탐색은 medium, 포괄 분석은 very thorough입니다. 사용자나 프로젝트 스코프에 Explore라는 이름의 서브에이전트를 정의하면 내장을 덮고 자기 model 필드를 유지하므로, model: haiku로 탐색을 싼 모델에 고정할 수 있습니다. sub-agents

공식실행 방식도 알아 둡니다. v2.1.198부터 서브에이전트는 기본적으로 백그라운드에서 돕니다. 클로드는 결과가 계속 진행에 필요할 때만 포그라운드로 돌립니다. 백그라운드 서브에이전트는 포그라운드보다 작은 내장 도구 집합으로 돌고, 권한 프롬프트는 메인 세션에 어느 서브에이전트가 묻는지와 함께 표시됩니다. 승인하면 계속 진행하고 Esc를 누르면 그 도구 호출 하나만 거부하며 서브에이전트는 멈추지 않습니다. Ctrl B로 도는 작업을 백그라운드로 보낼 수 있습니다. sub-agents

공식한계도 둘 있습니다. 한 세션에서 20개가 돌고 있으면 추가 생성이 Concurrent subagent limit reached로 실패하고, 오류가 클로드에게 재시도하지 말라고 알립니다(CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS로 변경). 중첩은 메인 대화 아래 3층까지이며, 한계에 닿은 서브에이전트에서는 Agent 도구가 회수되어 위임받은 일을 스스로 하고 요약 하나를 돌려줍니다(CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH로 변경, 1이면 중첩 없음). 세션 전체의 총 개수 제한은 없습니다. sub-agents

20.2정의와 도구 제한

공식서브에이전트는 YAML 프론트매터가 붙은 마크다운 파일입니다. 프론트매터가 메타데이터와 구성을, 본문이 시스템 프롬프트를 정합니다. name과 description만 필수입니다. sub-agents

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

공식자주 쓰는 프론트매터 필드입니다. sub-agents

공식같은 이름이 여러 곳에 있으면 우선순위가 높은 쪽을 씁니다. sub-agents

공식.claude/agents/와 ~/.claude/agents/는 재귀 스캔되므로 agents/review/처럼 하위 폴더로 정리할 수 있습니다. 하위 경로는 식별과 호출에 영향을 주지 않습니다. 정체성은 name 프론트매터에서만 옵니다. 그래서 name은 트리 전체에서 유일해야 합니다. 같은 디렉터리 아래 두 파일이 같은 이름을 선언하면 클로드코드는 파일시스템 읽기 순서로 하나만 로드하며, 문서화된 우선순위가 없습니다. /doctor가 이 중복을 보고합니다. sub-agents

공식도구 상속에는 두 겹의 필터가 걸립니다. 첫 필터는 모든 서브에이전트에서 몇 개를 제거하는데, tools에 적어도 제거됩니다. AskUserQuestion, EndConversation, EnterPlanMode, ScheduleWakeup, 그리고 깊이 한계에 닿았을 때의 Agent가 여기 해당합니다(ExitPlanMode는 permissionMode가 plan일 때만 남습니다). 둘째 필터는 백그라운드 서브에이전트의 내장 도구 집합을 줄입니다. 포크는 두 필터를 모두 건너뛰고 메인 대화의 도구 풀을 그대로 받습니다. sub-agents

실전이 볼트에는 서브에이전트가 하나 있습니다(~/.claude/agents/youtube-article.md). 프론트매터는 name·description·tools·model 네 개뿐이고 나머지는 기본값에 맡겼습니다. tools는 Bash, Read, Write, Edit, Glob, Grep, WebFetch 일곱 개로 명시했고 model: inherit입니다. 본문(시스템 프롬프트)은 5,529자입니다. 흥미로운 것은 비율입니다. description이 308자로 스킬(789자·514자)보다 짧은데, 서브에이전트는 위임 판단만 하면 되고 절차는 본문에 있기 때문입니다. 스킬은 반대로 발화 조건이 설명에 다 들어가야 합니다.

20.3위임 지시 설계

공식공식 문서가 드는 패턴 셋입니다. 대용량 작업 격리는 테스트 실행·문서 수집·로그 처리처럼 출력이 많은 것을 위임해 상세는 서브에이전트 맥락에 두고 요약만 받는 것입니다. 병렬 조사는 독립적인 조사 여러 개를 동시에 띄우고 클로드가 종합하는 것으로, 조사 경로가 서로 의존하지 않을 때 가장 잘 됩니다. 연쇄는 다단계 작업에서 순서대로 쓰는 것입니다. sub-agents

서브에이전트로 테스트를 돌리고 실패한 테스트와 오류 메시지만 보고해 줘

인증·데이터베이스·API 모듈을 각각 별도 서브에이전트로 병렬 조사해 줘

code-reviewer 서브에이전트로 성능 문제를 찾고, 그다음 optimizer 서브에이전트로 고쳐 줘

공식반환값의 신뢰도에 대한 장치도 있습니다. 클로드코드는 각 서브에이전트의 최종 보고를 클로드가 읽기 전에 스캔합니다. 서브에이전트가 내가 검토하지 않은 파일·웹 페이지·명령 출력을 읽었을 수 있고, 그 텍스트가 메인 대화를 겨냥한 지시를 담을 수 있기 때문입니다. 스캔은 아무것도 제거하거나 바꿔 쓰지 않고 두 가지만 합니다. 클로드코드 자신의 출력을 모방한 텍스트(<system-reminder> 태그나 Human:으로 시작하는 줄)에 백슬래시를 넣어 평문으로 읽히게 하고, 그런 모방이나 권한 설정 언급이 있으면 [harness: subagent output matched instruction-shaped pattern(s):로 시작하는 표시 줄을 앞에 붙입니다. sub-agents

관행반환값을 데이터로 받으려면 위임 프롬프트에 형식을 지정하는 편이 낫습니다. "조사해 줘"는 산문 보고를 돌려주고, "파일 경로와 줄 번호, 한 줄 근거를 목록으로만 돌려 줘"는 그다음 단계에서 바로 쓸 수 있는 형태를 돌려줍니다. 서브에이전트는 대화 기록을 못 보므로, 내가 이미 아는 맥락은 프롬프트에 다시 적어야 합니다.

20.4위임하면 안 되는 일

공식공식 문서는 메인 대화를 쓸 네 경우를 명시합니다. 잦은 왕복이나 반복 정련이 필요할 때, 계획·구현·테스트처럼 여러 단계가 상당한 맥락을 공유할 때, 빠르고 표적화된 변경일 때, 그리고 지연이 중요할 때입니다. 서브에이전트는 새로 시작하므로 맥락을 모으는 데 시간이 듭니다. sub-agents

공식반대로 서브에이전트를 쓸 세 경우는 메인 맥락에 필요 없는 장황한 출력이 나올 때, 특정 도구 제한이나 권한을 강제하고 싶을 때, 작업이 자기완결적이라 요약을 돌려줄 수 있을 때입니다. 메인 대화 맥락에서 도는 재사용 프롬프트나 워크플로가 필요하면 서브에이전트가 아니라 스킬을 고려합니다. sub-agents

관행위임이 손해가 되는 지점은 대개 판단이 왕복을 필요로 할 때입니다. 서브에이전트는 중간에 나에게 물을 수 없습니다(AskUserQuestion이 도구 목록에서 제거됩니다). 그래서 요구사항이 모호한 작업을 위임하면 서브에이전트가 자기 해석으로 끝까지 밀고 나간 결과가 돌아옵니다. 모호한 것은 메인 대화에서 좁힌 뒤에 위임합니다.

관행또 하나는 맥락 자체가 산출물인 작업입니다. 리팩토링 대상을 함께 읽어 가며 판단해야 하는 작업을 위임하면, 위임한 쪽에는 요약만 남아 다음 결정의 근거가 사라집니다. 이때는 파일을 읽는 비용을 감수하고 메인에서 하는 편이 낫습니다.

21.1훅이 발동하는 시점

공식이벤트는 주기로 셋으로 갈립니다. 세션당 한 번(SessionStart·SessionEnd), 턴당 한 번(UserPromptSubmit·Stop·StopFailure), 그리고 도구 호출마다(PreToolUse·PostToolUse, EndConversation은 제외)입니다. 이벤트가 발동하면 매칭되는 모든 훅이 병렬로 돕니다. hooks

21.2설정 위치와 형식

공식훅은 JSON 설정 파일에 세 겹으로 정의합니다. 1) 이벤트를 고르고, 2) 언제 발동할지 걸러 줄 매처 그룹을 더하고, 3) 매칭됐을 때 돌 핸들러를 하나 이상 정의합니다. hooks

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

공식어디에 두는지가 범위를 정합니다. hooks-guide

공식matcher 필드의 해석 규칙은 세 가지입니다. hooks

공식이벤트마다 매처가 무엇을 거르는지가 다릅니다. 도구 이벤트는 도구 이름, SessionStart는 시작 방식(startup·resume·clear·compact·fork), SessionEnd는 종료 이유, SubagentStart·SubagentStop은 에이전트 종류, ConfigChange는 설정 출처, FileChanged는 감시할 파일명입니다. UserPromptSubmit·Stop·PostToolBatch·TaskCreated 등은 매처를 지원하지 않고 항상 발동합니다. hooks

공식핸들러 종류는 다섯입니다. 대부분은 "command"(셸 명령)를 씁니다. "http"는 URL로 이벤트 데이터를 POST하고, "mcp_tool"은 이미 연결된 MCP 서버의 도구를 부르고, "prompt"는 단일 턴 LLM 판정이고, "agent"는 도구 접근이 있는 다중 턴 검증입니다(실험 기능). hooks-guide

공식모든 핸들러가 공유하는 필드가 넷 있습니다. type(필수), if(권한 규칙 문법으로 조건을 좁힘. 도구 이벤트에서만), timeout(초), statusMessage(도는 동안 보일 문구)입니다. 기본 타임아웃은 command·http·mcp_tool이 10분, prompt가 30초, agent가 60초입니다. 단 UserPromptSubmit은 앞의 셋을 30초로, MessageDisplay는 10초로 낮추고, SessionEnd 훅은 종류와 무관하게 1.5초 예산을 공유합니다. hooks-guide

공식스크립트 경로는 플레이스홀더로 씁니다. ${CLAUDE_PROJECT_DIR}는 프로젝트 루트, ${CLAUDE_PLUGIN_ROOT}는 플러그인 설치 디렉터리, ${CLAUDE_PLUGIN_DATA}는 플러그인의 영속 데이터 디렉터리입니다. hooks

실전이 볼트의 훅은 그 플레이스홀더를 절반만 씁니다. 로깅과 문체 점검 훅 4개는 $CLAUDE_PROJECT_DIR로 스크립트를 찾는데, SessionStart의 나머지 6개는 절대 경로를 리터럴로 담고 있습니다(윈도우용 3개는 K:\ 경로의 .ps1, 맥용 3개는 /Users/... 경로의 .sh). 의도는 OS별 쌍이고 각 기기가 자기 절반만 돌리는 구조입니다. 이 맥에서 확인하니 pwsh가 없고 K:도 없어 윈도우 3개는 실행되지 않았고, bash 3개는 정상 동작했습니다. 동작은 하지만 볼트 경로나 계정명이 바뀌면 조용히 깨지는 구조이고, 훅 실패는 눈에 잘 띄지 않습니다. 플레이스홀더로 바꾸면 쌍을 유지하면서 경로 의존이 사라집니다.

python3 -c "
import json
d = json.load(open('.claude/settings.json'))
for ev, ms in d.get('hooks', {}).items():
    for m in ms:
        for h in m.get('hooks', []):
            s = h.get('command', '') + ' ' + ' '.join(map(str, h.get('args') or []))
            if '/Users/' in s or ':\\\\' in s:
                print('절대경로 발견:', ev, '|', s[:80])
"

21.3입출력 계약

공식훅은 stdin·stdout·stderr·종료 코드로 클로드코드와 통신합니다. 이벤트가 발동하면 이벤트별 데이터가 JSON으로 스크립트의 stdin에 들어옵니다. 스크립트가 그 데이터를 읽고 일을 하고, 종료 코드로 다음에 무엇을 할지 알립니다. hooks-guide

공식모든 이벤트가 공유하는 입력 필드입니다. hooks

공식도구 이벤트는 여기에 tool_name과 tool_input이 붙습니다. Bash라면 tool_input.command에 셸 명령이 담깁니다. UserPromptSubmit은 대신 prompt 텍스트를, SessionStart는 source를 받습니다. hooks-guide

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

공식종료 코드가 결과를 정합니다. hooks

공식종료 코드 2가 무엇을 막는지는 이벤트마다 다릅니다. 막을 수 있는 것은 PreToolUse(도구 호출), PermissionRequest(권한 거부), UserPromptSubmit(프롬프트 처리를 막고 프롬프트를 지운다), UserPromptExpansion, Stop(클로드가 멈추지 못하게 하고 대화를 계속한다), SubagentStop, TaskCreated(생성을 되돌린다), TaskCompleted, ConfigChange, PreCompact, PostToolBatch, WorktreeCreate, Elicitation입니다. PostToolUse는 막지 못하지만 stderr를 클로드에게 보여 줍니다. hooks

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  # stderr가 클로드에게 가는 피드백
  exit 2                                               # 2 = 동작 차단
fi

exit 0  # 0 = 판정 없음. 정상 권한 흐름 적용

공식종료 코드 0으로 JSON을 출력하면 더 세밀하게 통제할 수 있습니다. 한 훅에서 둘을 섞지 말고 종료 코드만 쓰거나 JSON만 씁니다. 출력 상한은 1만 자이고 넘치면 파일로 저장되며 미리보기와 경로가 표시됩니다. 공용 필드는 continue(false면 클로드가 처리를 완전히 멈춘다), stopReason, suppressOutput, systemMessage, terminalSequence입니다. hooks

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "This file is generated. Edit src/schema.ts and run `bun generate` instead."
  }
}

공식문장 형태에도 주의가 필요합니다. "배포 대상은 production이다", "이 저장소는 bun test를 쓴다"처럼 사실 서술로 씁니다. 시스템 명령처럼 쓰면 클로드의 프롬프트 인젝션 방어를 발동시킬 수 있습니다. 그리고 주입된 텍스트는 전사에 저장되므로, --continue나 --resume으로 재개하면 훅을 다시 돌리지 않고 저장된 텍스트를 재생합니다. 타임스탬프나 커밋 SHA가 오래된 값으로 남습니다. SessionStart 훅은 재개 시 다시 돌므로 맥락을 갱신할 수 있습니다. hooks

공식여러 훅이 같은 이벤트에 매칭되면 모든 훅의 명령이 끝까지 돈 다음 결과가 병합됩니다. 한 훅이 deny를 돌려줘도 형제 훅의 실행은 멈추지 않습니다. PreToolUse 권한 결정은 가장 제한적인 답이 이기며 순서는 deny → defer → ask → allow입니다. additionalContext 텍스트는 모든 훅에서 수집되어 함께 전달됩니다. hooks-guide

21.4실전 훅 5종

공식 문서의 예제 둘과 이 볼트에서 실제로 도는 것 셋을 함께 봅니다. 붙여 쓸 수 있는 형태로 옮겼습니다.

공식1) 편집 후 자동 포맷. PostToolUse에 Edit|Write 매처를 걸어 편집된 파일 경로를 jq로 뽑아 포매터에 넘깁니다. 성공하면 대화에 아무것도 표시되지 않으므로, 확인은 파일이 재포맷됐는지로 합니다. hooks-guide

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

공식2) 보호 파일 편집 차단. 스크립트가 대상 경로를 보호 패턴 목록과 대조하고 종료 코드 2로 편집을 막습니다. 클로드는 stderr를 피드백으로 받아 접근을 바꿉니다. 맥과 리눅스에서는 chmod +x로 실행 권한을 줘야 합니다. hooks-guide

#!/bin/bash
# .claude/hooks/protect-files.sh
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
FILE_PATH="${FILE_PATH//\\//}"   # 윈도우 백슬래시 정규화

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")
for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done
exit 0

실전3) 대화 전량 적재. 이 볼트는 질문과 응답을 전부 디스크에 남깁니다. 같은 스크립트를 세 이벤트에 다른 인자로 걸었습니다. UserPromptSubmit에 --질문(타임아웃 10초), Stop에 --응답(20초), SessionStart에 --백필(60초)입니다. 핵심은 두 가지 방어입니다. 파이썬 실행기를 command -v로 확인해 python3 → python 순으로 폴백하고, 출력을 전부 버린 뒤 exit 0을 명시해 무슨 일이 있어도 세션을 막지 않게 했습니다. 로깅 훅이 세션을 깨뜨리면 로그의 가치보다 손해가 큽니다.

p="$CLAUDE_PROJECT_DIR/00_시스템/_대화로그/로그_적재.py"
if [ -f "$p" ]; then
  { command -v python3 >/dev/null 2>&1 && python3 "$p" --질문; } ||
  { command -v python  >/dev/null 2>&1 && python  "$p" --질문; }
fi >/dev/null 2>&1; exit 0

실전4) 문체 규칙 강제. Stop 훅이 그 턴의 최종 답변을 스캔해 금지 패턴이 걸리면 종료 코드 2로 재작성을 요구합니다. 패턴은 12종이고 각각 임계값을 갖습니다. em dash·원형숫자·이모지처럼 한 번이라도 나오면 위반인 것(임계 1)과, 한 번은 정당하고 반복이 문제인 것(예: 같은 대구 반복은 임계 3, 굵은 용어 + 콜론 불릿은 임계 4)을 나눴습니다. 임계값은 이 볼트의 응답 300건을 실측해 정했습니다.

실전이 훅에서 배운 것 둘이 있습니다. 첫째, 루프 방지가 필수입니다. 스크립트가 stop_hook_active 필드를 읽어 이미 이 훅으로 이어진 턴이면 즉시 통과시킵니다. 이것이 없으면 훅이 계속 차단해 턴이 끝나지 않습니다. 둘째, 훅 자신의 실패는 조용해야 합니다. 스캔 자체가 예외로 죽으면 종료 코드 0으로 통과시킵니다. 문체 점검기가 고장 났다고 세션을 못 쓰게 되는 것은 과한 대가입니다.

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # 이미 이 훅으로 이어붙인 턴 = 루프 차단
fi
# ... 나머지 훅 로직

실전5) 세션 시작 점검 3종. 백업·메모리 정리·구조 최적화 점검을 SessionStart에 걸었습니다. 여기서 쓴 설계 둘이 유용했습니다. 셋 중 둘은 async: true로 백그라운드에서 돌려 세션 시작을 늦추지 않고, 결과를 바로 봐야 하는 하나만 async: false로 대기합니다. 그리고 args를 쓴 exec 형이라 한글이 든 경로를 셸 인용 없이 그대로 넘깁니다. 셸 형으로 한글 경로를 넘기면 인용 처리에서 깨지기 쉽습니다.

공식판단이 필요한 검사는 prompt·agent 훅이 맡습니다. prompt 훅은 프롬프트와 훅 입력을 모델(기본 Haiku)에 보내 {"ok": true|false, "reason": "..."}만 받습니다. agent 훅은 서브에이전트를 띄워 파일을 읽고 명령을 돌려 실제 상태를 확인한 뒤 같은 형식으로 답합니다(기본 60초, 최대 50 도구 턴). 훅 입력 데이터만으로 판단이 되면 prompt, 코드베이스의 실제 상태를 확인해야 하면 agent입니다. hooks-guide

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "agent",
          "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
          "timeout": 120 }] }
    ]
  }
}

21.5훅 디버깅

공식훅이 아예 안 돌 때 확인할 것 넷입니다. /hooks로 올바른 이벤트 아래 나타나는지 보고, 매처 패턴이 도구 이름과 정확히 맞는지 보고(대소문자를 구분합니다), 이벤트 종류가 맞는지 보고, 비대화 모드라면 PermissionRequest 대신 PreToolUse를 써야 하는지 봅니다. hooks-guide

공식/hooks에 아무 훅도 안 보이면 원인은 셋입니다. 파일 변경이 감시기에 잡히지 않았거나(몇 초 뒤에도 없으면 세션 재시작), JSON이 유효하지 않거나(뒤따르는 쉼표와 주석은 허용되지 않습니다), 설정 파일 위치가 틀린 것입니다. hooks-guide

공식전사에 훅 오류가 보일 때는 스크립트를 직접 돌려 봅니다. hooks-guide

echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
echo $?   # 종료 코드 확인

공식메시지별 처방이 있습니다. command not found면 절대 경로나 ${CLAUDE_PROJECT_DIR}를 쓰거나, 셸 인용을 아예 피하려면 "args": []로 exec 형으로 바꿉니다. jq: command not found면 jq를 설치하거나 파이썬·노드로 JSON을 파싱합니다. 스크립트가 아예 안 돌면 chmod +x를 확인합니다. hooks-guide

# ~/.zshrc 또는 ~/.bashrc
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

공식결과 확인은 Ctrl O로 전사 뷰를 엽니다. 종료 코드 0으로 성공한 뒤에는 아무것도 보이지 않습니다. 그래서 돌았는지 확인하려면 효과(재포맷된 파일 등)를 보거나 디버그 로깅을 켭니다. 차단 오류(2)에서는 stderr가 보이고, 비차단 오류에서는 <hook name> hook error 알림과 Failed with non-blocking status code:가 붙은 stderr 첫 줄이 보입니다. hooks-guide

claude --debug-file /tmp/claude.log     알려진 경로로 디버그 로그 기록
tail -f /tmp/claude.log                 다른 터미널에서 따라 보기

실전디버깅에서 가장 자주 쓴 것은 위 두 줄이 아니라 훅 스크립트에 직접 로그를 남기는 것이었습니다. 훅은 성공하면 침묵하므로, 개발 중에는 스크립트 첫 줄에서 입력 JSON을 파일에 통째로 덤프해 두면 어떤 필드가 실제로 오는지 바로 보입니다. 문서의 스키마와 실제 입력이 다른 것은 아니지만, 어느 이벤트에서 어떤 필드가 비어 있는지는 실물을 봐야 알 수 있습니다.

INPUT=$(cat)
echo "$INPUT" >> /tmp/hook-input.jsonl   # 개발 중에만
# ... 나머지 로직

21.6훅으로 규칙을 강제한다는 것

공식공식 문서의 문장이 이 절의 전제입니다. CLAUDE.md나 스킬에 적은 지시는 요청이고, 그 동작을 막는 PreToolUse 훅이 강제입니다. 어떤 규칙이 매번 지켜져야 한다면 프롬프트 지시가 아니라 훅으로 만듭니다. features-overview

실전이 차이를 이 볼트에서 실제로 겪었습니다. 문체 규칙(em dash 금지, 원형숫자 금지, 상투구 금지)은 원래 규칙 문서에 적혀 있었습니다. 문서로만 있을 때는 지켜지는 비율이 일정하지 않았고, 어겨도 아무 일도 일어나지 않아서 어겼다는 사실 자체를 나중에야 알았습니다. 같은 규칙을 Stop 훅으로 옮긴 뒤에는 위반이 그 턴에서 즉시 되돌려집니다. 규칙 텍스트는 한 글자도 바뀌지 않았고 발화 지점만 바뀌었습니다.

실전다만 옮기면서 규칙을 줄여야 했습니다. 문서의 전수 목록은 사람 판단용이라 오탐이 많았고, 기계로 강제할 수 있는 것은 고정밀 부분집합뿐이었습니다. 그래서 훅에는 12개만 넣고 나머지는 문서에 남겼습니다. 훅 스크립트의 주석에 그 경계를 명시해 뒀습니다. "규격 정본은 문체 규격 문서이고, 이 파일은 그 목록의 고정밀 부분집합을 기계로 강제한다. 전수 목록은 사람 판단용이라 여기 옮기지 않는다." 훅으로 강제할 수 있는 것과 문서로 남길 것을 나누는 이 판단이 실제 작업의 대부분이었습니다.

관행그래서 훅을 만들 때 같이 만들 것이 하나 있습니다. 그 훅이 돌았다는 증거입니다. 로그 파일 한 줄이든, 카운터든, 주기적으로 확인할 명령 한 줄이든 상관없습니다. 이 볼트는 대화 로그 자체가 그 증거 역할을 합니다. 적재가 멈추면 로그가 늘지 않으므로 바로 드러납니다.

공식마지막으로 끄는 방법도 알아 둡니다. 설정 파일에 "disableAllHooks": true를 두면 훅과 커스텀 상태줄이 모두 꺼집니다. 관리형 설정에 있는 훅은 관리형 설정에도 이 값이 있어야 꺼집니다. 개별 훅을 없애려면 설정 JSON에서 그 항목을 지웁니다. hooks

22.1출력 스타일

공식출력 스타일은 클로드가 무엇을 아는지가 아니라 어떻게 답하는지를 바꿉니다. 시스템 프롬프트를 수정해 역할·어조·출력 형식을 정합니다. 매 턴 같은 목소리나 형식을 다시 요청하고 있을 때, 또는 클로드가 소프트웨어 엔지니어가 아닌 다른 역할을 하기를 원할 때 씁니다. 프로젝트·관례·코드베이스에 대한 지시는 CLAUDE.md가 맞습니다. output-styles

공식기본 스타일 외에 내장 스타일이 셋 있습니다. Proactive는 즉시 실행하고 루틴한 결정에서 멈추지 않고 합리적 가정을 세우며 계획보다 행동을 선호합니다. 자동 모드보다 강한 자율 실행 지침이면서 권한 모드를 바꾸지 않으므로 권한 프롬프트는 그대로 뜹니다. Explanatory는 작업 사이에 교육적인 "Insights"를 넣습니다. Learning은 협업 학습 모드로, 통찰을 공유하는 데 그치지 않고 작지만 전략적인 코드 조각을 직접 쓰게 하며 코드에 TODO(human) 마커를 남깁니다. output-styles

공식바꾸는 방법은 /config에서 Output style을 고르는 것입니다. 선택은 .claude/settings.local.json에 저장됩니다. 메뉴 없이 하려면 설정 파일의 outputStyle 필드를 직접 고칩니다. 독립 /output-style 명령은 v2.1.73에서 폐기되고 v2.1.91에서 제거됐습니다. output-styles

{
  "outputStyle": "Explanatory"
}

공식커스텀 스타일은 프론트매터가 붙은 마크다운 파일입니다. 파일명이 스타일 이름이 되고(name을 지정하면 그것을 씁니다), 위치는 세 곳입니다. 사용자 ~/.claude/output-styles, 프로젝트 .claude/output-styles, 그리고 관리형 설정 디렉터리 안의 같은 경로입니다. output-styles

---
name: Diagrams first
description: Lead every explanation with a diagram
keep-coding-instructions: true
---

When explaining code, architecture, or data flow, start with a Mermaid diagram
showing the structure, then explain in prose.

## Diagram conventions

Use `flowchart TD` for control flow and `sequenceDiagram` for request paths.
Keep diagrams under 15 nodes.

공식적용 범위도 알아 둡니다. 출력 스타일은 메인 대화에만 적용됩니다. 서브에이전트는 자기 시스템 프롬프트로 돌기 때문입니다. 예외는 포크로, 부모의 전체 시스템 프롬프트를 상속합니다. 토큰 비용은 스타일에 따라 다릅니다. 시스템 프롬프트에 지시를 더하면 입력 토큰이 늘지만 프롬프트 캐싱이 첫 요청 이후 비용을 줄입니다. 내장 Explanatory와 Learning은 설계상 기본보다 긴 응답을 내므로 출력 토큰이 늘어납니다. output-styles

공식비슷한 기능과의 갈림입니다. 출력 스타일은 시스템 프롬프트를 직접 수정하고 모든 응답에 적용됩니다. 나머지는 기본 시스템 프롬프트를 바꾸지 않고 지시를 더하거나, 특정 작업으로 범위를 좁힙니다. output-styles

22.2상태줄

공식상태줄은 클로드코드 하단의 바이며 내가 구성한 아무 셸 스크립트나 실행합니다. stdin으로 JSON 세션 데이터를 받고 스크립트가 출력한 것을 그대로 표시합니다. 컨텍스트 사용량·비용·git 상태를 상시로 보는 데 씁니다. 내장 푸터 배지 위의 자기 줄에 렌더되며 배지를 대체하지 않습니다. 다만 커스텀 상태줄을 두면 esc to interrupt 같은 대부분의 키보드 힌트가 사라집니다. statusline

공식가장 쉬운 방법은 /statusline에 자연어로 원하는 것을 말하는 것입니다. 클로드코드가 ~/.claude/에 스크립트 파일을 만들고 설정을 자동으로 갱신합니다. statusline

/statusline show model name and context percentage with a progress bar

공식직접 구성하려면 statusLine 필드를 씁니다. type을 "command"로 두고 command에 스크립트 경로나 인라인 셸 명령을 지정합니다. statusline

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 2
  }
}

공식선택 필드가 셋 있습니다. padding은 가로 여백을 문자 수로 더합니다(기본 0). refreshInterval은 이벤트 기반 갱신에 더해 N초마다 다시 돌립니다(최소 1). 시계처럼 시간 기반 데이터를 보일 때, 또는 메인 세션이 유휴인 동안 백그라운드 서브에이전트가 git 상태를 바꿀 때 씁니다. hideVimModeIndicator는 내장 -- INSERT -- 표시를 숨깁니다. statusline

공식갱신 시점은 정해져 있습니다. 세션이 시작될 때(재개 포함) 한 번 돌고, 그 뒤에는 새 어시스턴트 메시지가 도착할 때, /compact가 끝날 때, 권한 모드가 바뀔 때, vim 모드가 토글될 때, 그리고 refreshInterval 타이머가 지날 때입니다. 갱신은 300밀리초로 디바운스되며, 스크립트가 도는 중에 새 갱신이 발생하면 진행 중인 스크립트를 취소합니다. statusline

공식stdin으로 오는 JSON에서 자주 쓰는 필드입니다. statusline

#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)

echo "[$MODEL] ${DIR##*/} | ${PCT}% context"

공식출력에 쓸 수 있는 것은 셋입니다. 여러 줄(각 echo가 한 행), 색(ANSI 이스케이프 코드), 링크(OSC 8 시퀀스, iTerm2·Kitty·WezTerm 같은 지원 터미널에서 클릭 가능)입니다. 터미널 폭에 맞추려면 tput cols가 아니라 환경 변수 COLUMNS와 LINES를 읽습니다. 클로드코드가 스크립트 출력을 캡처하므로 스크립트 안에서는 터미널 크기를 직접 읽을 수 없습니다. statusline

관행상태줄에 넣을 것을 고를 때 기준이 하나 있습니다. 그 값을 보고 지금 행동을 바꿀 수 있는가입니다. 컨텍스트 사용률은 세션을 나눌 판단을 바꾸므로 값을 합니다(12장). 반면 누적 비용은 보고 나서 할 수 있는 일이 없으면 자리만 차지합니다. 이 편의 다른 것과 달리 상태줄은 상시 보이는 표면이라 넣은 만큼 매번 읽게 됩니다.

22.3키바인딩

공식/keybindings를 실행하면 ~/.claude/keybindings.json을 만들거나 엽니다. 파일은 bindings 배열을 가진 객체이고, 각 블록이 컨텍스트와 키 조합 대 동작의 맵을 지정합니다. 파일 변경은 재시작 없이 자동 감지됩니다. keybindings

{
  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+e": "chat:externalEditor",
        "ctrl+u": null
      }
    }
  ]
}

공식컨텍스트는 그 바인딩이 적용되는 자리입니다. Global(앱 전역), Chat(메인 입력창), Autocomplete, Settings, Confirmation(권한·확인 대화), Tabs, Help, Transcript, HistorySearch, Task, ThemePicker, Attachments, Footer, MessageSelector, DiffDialog, ModelPicker, Select, Plugin, Scroll이 있습니다. keybindings

공식동작은 namespace:action 형식입니다. 자주 손대는 것 몇 개입니다. keybindings

공식키 표기법은 +로 수정자를 잇습니다. ctrl, shift, alt(opt·option·meta), cmd(command·super·win)입니다. 다만 cmd 계열은 Super 수정자를 보고하는 터미널에서만 감지되므로, 어디서나 되게 하려면 ctrl이나 meta를 씁니다. 단독 대문자는 Shift를 함의하므로 K는 shift+k와 같지만, 수정자가 붙은 대문자는 함의하지 않아 ctrl+K는 ctrl+k와 같습니다. 공백으로 구분하면 코드가 됩니다(ctrl+k ctrl+s). keybindings

공식기본 단축키를 해제하려면 동작 자리에 null을 둡니다. 코드 바인딩도 같습니다. 어떤 접두어를 단독 키로 되찾으려면 그 접두어를 공유하는 코드를 전부 해제해야 하며, 활성 컨텍스트에 코드가 하나라도 남아 있으면 접두어가 예약된 상태로 유지됩니다. keybindings

공식vim 모드와는 독립적으로 동작합니다. vim 모드는 텍스트 입력 수준(커서 이동·모드·모션)을, 키바인딩은 컴포넌트 수준(할 일 전환·전송)을 다룹니다. vim 모드의 Escape는 INSERT에서 NORMAL로 바꾸며 chat:cancel을 발동시키지 않습니다. vim 키는 이 파일로 재매핑할 수 없고, INSERT 모드의 jj 같은 두 키 시퀀스를 Escape에 매핑하려면 vimInsertModeRemaps 설정을 씁니다. keybindings

실전이 볼트는 키바인딩 파일을 두지 않았습니다(~/.claude/keybindings.json 없음). 이 편의 다른 수단과 달리 키바인딩은 없어도 마찰이 없으면 만들 이유가 없는 쪽입니다. 실제로 손이 가는 것은 대개 하나뿐입니다. tmux를 쓰면 Ctrl+B가 겹치므로 task:background를 코드 형태(Ctrl+X Ctrl+B)로 쓰거나 다른 키로 옮기는 것입니다. 그것도 이제 기본값에 코드가 함께 들어 있어 손댈 일이 줄었습니다.

23.1플러그인이 담는 것

공식플러그인은 포장 층입니다. 스킬·에이전트·훅·MCP 서버를 하나의 설치 단위로 묶어 프로젝트와 팀에 걸쳐 공유합니다. 독립 구성(.claude/ 디렉터리)과의 갈림은 목적입니다. plugins

공식공식 권고는 .claude/에서 빠르게 반복하다가 공유할 준비가 됐을 때 플러그인으로 바꾸는 것입니다. plugins

공식플러그인 루트에 둘 수 있는 디렉터리 전량입니다. plugins

공식매니페스트의 필수 필드는 사실상 name과 description입니다. name은 고유 식별자이자 스킬 이름공간이고, version은 선택인데 설정하면 이 필드를 올릴 때만 사용자에게 갱신이 갑니다. plugins

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

공식스킬 하나만 담는 플러그인은 skills/를 만들지 않고 SKILL.md를 플러그인 루트에 바로 둘 수 있습니다. 그때는 프론트매터 name이 호출 이름이 됩니다. 두 개 이상으로 자랄 가능성이 있으면 skills/ 배치를 씁니다. plugins

23.2설치와 마켓플레이스

공식마켓플레이스는 남이 만들어 공유한 플러그인 카탈로그입니다. 쓰는 절차는 두 단계입니다. 마켓플레이스를 추가해 카탈로그를 등록하고(이때 아무것도 설치되지 않습니다), 그다음 원하는 플러그인을 설치합니다. discover-plugins

공식공식 Anthropic 마켓플레이스(claude-plugins-official)는 처음 대화형으로 시작할 때 자동 추가됩니다. 추가되지 않았다면 직접 추가합니다. discover-plugins

/plugin marketplace add anthropics/claude-plugins-official
/plugin install github@claude-plugins-official

공식추가 소스는 네 종류입니다. GitHub 저장소(owner/repo), git URL(GitLab·Bitbucket·자체 호스팅 포함), 로컬 경로, 그리고 호스팅된 marketplace.json의 원격 URL입니다. git URL은 .git 접미어와 https:// 접두어를 붙입니다. 접두어 없이 쓰면 GitHub owner/repo 약칭으로 잘못 읽혀 거부됩니다. 특정 브랜치나 태그는 # 뒤에 붙입니다. discover-plugins

/plugin marketplace add anthropics/claude-code                       GitHub
/plugin marketplace add https://gitlab.com/company/plugins.git       git URL
/plugin marketplace add https://gitlab.com/company/plugins.git#v1.0.0 태그 지정
/plugin marketplace add ./my-marketplace                             로컬 경로
/plugin marketplace add https://example.com/marketplace.json         원격 URL

공식/plugin은 탭 네 개짜리 패널을 엽니다. Discover(모든 마켓플레이스의 플러그인 탐색), Installed(설치된 것 관리), Marketplaces(추가·제거·갱신), Errors(로딩 오류)입니다. 상세 창은 설치 전에 세 가지를 보여 줍니다. 매 턴 컨텍스트에 더할 토큰의 Context cost 추정, Last updated 날짜, 그리고 무엇이 추가되는지 열거하는 Will install 섹션입니다. discover-plugins

공식설치 범위는 셋입니다. 사용자(모든 프로젝트에서 나만), 프로젝트(이 저장소의 모든 협업자, .claude/settings.json에 추가됨), 로컬(이 저장소에서 나만). 관리자가 관리형 설정으로 설치한 managed 범위도 있으며 수정할 수 없습니다. discover-plugins

공식설치 요약이 세션 반영 여부를 알려 줍니다. Plugin is now active.면 이미 활성이고, Run /reload-plugins to activate.면 활성화가 프롬프트 캐시를 무효화하거나 시도가 실패한 것이니 그 명령을 돌립니다. 재적용이 캐시를 무효화하는 경우에는 경고와 함께 건너뛰므로 --force로 다시 돌립니다. discover-plugins

/plugin list                          설치 목록(--enabled·--disabled로 필터)
/plugin disable name@marketplace      제거하지 않고 끄기
/plugin enable name@marketplace       다시 켜기
/plugin uninstall name@marketplace    완전 제거
/plugin marketplace update <name>     카탈로그 갱신
/reload-plugins                       재시작 없이 변경 적용

공식자동 갱신은 마켓플레이스별로 켜고 끕니다. 켜져 있으면 세션 시작 후 최대 10분의 무작위 지연을 두고 카탈로그와 설치된 플러그인을 갱신하므로, 도는 세션은 시작 시 로드한 버전을 계속 씁니다. 갱신되면 /reload-plugins를 권하는 알림이 뜨거나 다음 실행에서 새 버전이 로드됩니다. 공식 마켓플레이스는 기본 켜짐, 서드파티와 로컬 개발 마켓플레이스는 기본 꺼짐입니다. discover-plugins

공식마켓플레이스를 제거하면 그것으로 설치한 플러그인이 모두 제거됩니다. 플러그인 스킬이 안 보이면 rm -rf ~/.claude/plugins/cache로 캐시를 비우고 재시작한 뒤 다시 설치합니다. discover-plugins

실전이 볼트에는 플러그인 2개가 사용자 범위로 설치돼 있습니다. 공식 마켓플레이스의 하나와, 직접 만든 git 마켓플레이스의 하나입니다. 설치 대장(~/.claude/plugins/installed_plugins.json)에 버전·설치 시각·gitCommitSha가 함께 기록돼 있어 무엇이 언제 어느 커밋으로 들어왔는지가 남습니다. 활성화는 별도로 ~/.claude/settings.json의 enabledPlugins에 "name@marketplace": true 형태로 기록됩니다. 즉 설치와 활성화가 다른 파일이고, 설치돼 있는데 꺼져 있는 상태가 가능합니다.

python3 -c "
import json, os
p = os.path.expanduser('~/.claude/plugins/installed_plugins.json')
d = json.load(open(p))
for name, vs in d['plugins'].items():
    for v in vs:
        print(name, '|', v['version'], '|', v['scope'], '|', v['installedAt'][:10])
"

23.3직접 만들기

공식매번 --plugin-dir를 붙이는 대신 스킬 디렉터리에서 개발할 수도 있습니다. claude plugin init my-tool이 ~/.claude/skills/my-tool/에 매니페스트와 시작용 SKILL.md를 만들고, 다음 세션에서 마켓플레이스나 설치 단계 없이 my-tool@skills-dir로 로드됩니다. plugins

공식테스트 플래그가 셋 있습니다. --plugin-dir는 디렉터리나 .zip 아카이브를 받고 여러 번 반복해 여러 플러그인을 로드합니다. 설치된 마켓플레이스 플러그인과 이름이 같으면 그 세션에서는 로컬 사본이 우선하므로 설치를 지우지 않고 변경을 테스트할 수 있습니다(관리형 설정이 강제한 플러그인은 예외). URL에 호스팅된 .zip은 --plugin-url로 그 세션 동안만 로드합니다. plugins

claude --plugin-dir ./my-plugin
claude --plugin-dir ./my-plugin.zip
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two
claude plugin validate ./my-plugin

공식이미 .claude/에 있는 것을 플러그인으로 옮기는 절차도 정해져 있습니다. 매니페스트를 만들고, commands·agents·skills 디렉터리를 플러그인 루트로 복사하고, 훅은 settings.json의 hooks 객체를 그대로 hooks/hooks.json으로 옮깁니다(형식이 같습니다). 옮긴 뒤에는 원본을 지워 중복을 없앱니다. plugins

공식디버깅은 셋입니다. 디렉터리가 .claude-plugin/ 안이 아니라 플러그인 루트에 있는지 확인하고, 스킬·에이전트·훅을 개별로 시험하고, 검증·디버깅 도구를 씁니다. 에이전트는 /context의 Custom Agents에 나타나는지로 확인하고, 훅은 그 이벤트를 실제로 발생시켜 효과를 확인합니다. plugins

23.4마켓플레이스 운영

공식마켓플레이스는 .claude-plugin/marketplace.json 하나입니다. 필수 필드는 셋입니다. plugin-marketplaces

공식선택 필드 중 실무에 쓸 만한 것이 넷 있습니다. metadata.pluginRoot는 상대 소스 경로에 붙는 기본 디렉터리라 "./plugins"로 두면 항목마다 "source": "formatter"로 짧게 쓸 수 있습니다. renames는 옛 플러그인 이름을 현재 이름(또는 제거됐으면 null)으로 매핑해 기존 사용자를 자동 이전시킵니다. allowCrossMarketplaceDependenciesOn은 이 마켓플레이스의 플러그인이 의존할 수 있는 다른 마켓플레이스를 열거하며, 목록에 없는 곳의 의존은 설치 시 차단됩니다. $schema는 편집기 자동완성용이고 로드 시 무시됩니다. plugin-marketplaces

공식플러그인 항목에는 매니페스트 스키마의 아무 필드나 넣을 수 있고, 여기에 마켓플레이스 전용 필드가 더해집니다. source, category, tags, strict, relevance입니다. 그 밖에 displayName(UI 표시명), defaultEnabled(false면 설치 후 꺼진 상태로 두고 사용자가 켜게 함), version(설정하면 그 문자열로 고정되고 값이 바뀔 때만 갱신이 전달됨)이 자주 쓰입니다. plugin-marketplaces

공식팀 단위로는 프로젝트 .claude/settings.json에 extraKnownMarketplaces를 두면 팀원이 저장소 폴더를 신뢰할 때 설치를 권합니다. 관리자는 각 항목에 "autoUpdate": true를 둬서 사용자마다 토글하지 않아도 자동 갱신을 켤 수 있습니다. discover-plugins

{
  "extraKnownMarketplaces": {
    "my-team-tools": {
      "source": { "source": "github", "repo": "your-org/claude-plugins" }
    }
  }
}

실전이 볼트는 실제로 자체 마켓플레이스를 하나 운영하고 있습니다. 사용자 설정의 extraKnownMarketplaces에 git 소스로 등록해 두고, 거기서 플러그인 하나를 설치해 씁니다. 그 marketplace.json을 열어 보면 실제로 쓰이는 필드가 많지 않았습니다. 최상위는 name·description·owner{name,url}·plugins 넷이고, 각 항목은 name·description·source·category·tags 다섯입니다. source는 전부 "./plugins/<이름>" 상대 경로이고 version은 항목에 없습니다.

{
  "name": "<마켓플레이스 이름>",
  "description": "...",
  "owner": { "name": "...", "url": "https://github.com/..." },
  "plugins": [
    {
      "name": "docs-guide",
      "description": "...",
      "source": "./plugins/docs-guide",
      "category": "development",
      "tags": ["documentation", "llms-txt", "official-docs", "guide"]
    }
  ]
}

실전여기서 배운 것 둘입니다. 첫째, 항목에 version을 안 쓰면 갱신 시점을 내가 통제하지 못합니다. 설치 대장에는 gitCommitSha가 기록되므로 커밋을 밀면 갱신 대상이 됩니다. 릴리스 단위로 배포하고 싶으면 version을 명시하는 편이 낫습니다. 둘째, 서드파티 마켓플레이스는 자동 갱신이 기본 꺼짐이라(공식만 켜짐) 내가 커밋을 밀어도 사용자 쪽은 /plugin marketplace update를 돌릴 때까지 예전 것을 씁니다. 내 마켓플레이스를 남에게 쓰게 하려면 이 사실을 README에 적어 두는 것이 필요했습니다.

실전설치된 플러그인의 구조도 실제로 열어 봤습니다. 스킬만 제공하는 플러그인이라 skills/와 설치용 setup/, 그리고 언어별 README 다섯 개만 있었습니다. 훅도 MCP도 없습니다. 즉 플러그인이라고 해서 전부를 담을 필요가 없습니다. 스킬 하나를 여러 프로젝트에서 쓰고 싶다는 이유만으로 플러그인이 될 수 있습니다.

24.1MCP가 무엇을 해결하나

공식공식 문서가 드는 용례입니다. 이슈 트래커의 기능을 구현하고 PR을 만들기, 모니터링 데이터를 분석하기, 데이터베이스를 질의하기, 피그마 디자인을 반영하기, 메일 초안을 만들기, 그리고 외부 이벤트에 반응하기입니다. 마지막 것은 MCP 서버가 채널로 동작해 텔레그램·디스코드 메시지나 웹훅 이벤트를 세션에 밀어 넣는 형태입니다. mcp

공식18장의 갈림을 다시 확인해 둡니다. MCP는 연결이고 스킬은 그 연결을 잘 쓰는 법입니다. MCP 서버가 데이터베이스에 연결하고, 스킬이 데이터 모델과 흔한 질의 패턴을 가르칩니다. 둘은 함께 씁니다. features-overview

24.2서버 붙이기

공식전송 방식은 네 가지입니다. 원격 서버에는 HTTP가 권장이고 클라우드 서비스에서 가장 널리 지원됩니다. SSE는 폐기됐지만 일부 서비스가 아직 그것만 노출합니다. stdio는 로컬 프로세스로 도는 방식이라 시스템 접근이나 커스텀 스크립트가 필요한 도구에 맞습니다. WebSocket은 지속 양방향 연결로 서버가 먼저 이벤트를 밀어야 할 때 쓰며, OAuth와 --transport 플래그를 지원하지 않아 헤더 인증만 가능합니다. mcp

claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"
claude mcp add --transport sse asana https://mcp.asana.com/sse
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server