Claude Code 완전 가이드: MCP, Hooks에서 Workflows, 기업 배포까지

이 문서는 무엇인가요?

이것은 계속 업데이트되는 참고 문서이며, 일회성 강좌 글이 아닙니다. Claude Code는 업데이트 속도가 매우 빠릅니다. 2026년 9월 중순부터 10월 중순까지 이 30일 동안에만 npm에 정식 버전이 25개 배포되었습니다.

그래서 이 문서를 통해 업데이트 과정을 계속 기록하려고 합니다. 한편으로는 제 개인 노트이기도 합니다.

이 페이지의 방식은 다음과 같습니다:

• 페이지 상단에는 항상 대응하는 CLI 버전과 최종 업데이트 날짜를 표시합니다. 날짜가 너무 오래되었다면 공식 문서를 다시 확인해야 한다는 뜻입니다.
• 각 장마다 독립된 앵커가 있어, 특정 절로 바로 링크할 수 있습니다.

출처: npm의 @anthropic-ai/claude-code 버전 배포 기록 (2026-10-15 확인, 2026-09-15부터 10-15까지의 정식 버전 집계, prerelease 제외)

60초 빠른 시작

Claude Code를 우선 실행해서 출력이 어떻게 나오는지 보고 싶다면, 아래 순서대로 진행합니다:

# 1. Install (pick one)
curl -fsSL https://claude.ai/install.sh | bash   # macOS, Linux, WSL
irm https://claude.ai/install.ps1 | iex          # Windows PowerShell
brew install --cask claude-code                  # Homebrew
winget install Anthropic.ClaudeCode              # WinGet
npm install -g @anthropic-ai/claude-code         # npm (Node.js 22+)

# 2. Verify: prints a version followed by (Claude Code)
claude --version
claude doctor                                    # optional full check

# 3. Launch in your project (first run opens a browser to log in)
cd ~/your-project && claude

# 4. Ask your first question
> what does this project do?

# Switch accounts later, inside Claude Code
/login

Claude Code는 필요한 프로젝트 파일을 스스로 읽으므로, 코드를 직접 붙여 넣어 줄 필요가 없습니다.

설치 전에 먼저 확인할 두 가지

• 시스템: macOS 13.0 이상, Windows 10 1809 이상(또는 Windows Server 2019 이상), Ubuntu 20.04 이상, Debian 10 이상, Alpine Linux 3.19 이상, 메모리 4 GB 이상
• 계정: Claude의 Pro, Max, Team, Enterprise 구독 또는 Claude Console 계정이 필요합니다

설치 방법 선택

처음 두 가지는 공식이 권장하는 네이티브 설치 방식이며, 백그라운드에서 자동으로 업데이트됩니다. Homebrew와 WinGet은 자동으로 업데이트되지 않으므로, 이후에는 brew upgrade claude-code 또는 winget upgrade Anthropic.ClaudeCode를 직접 실행해야 합니다. npm으로 설치하는 경우에는 sudo를 붙이지 마세요.

Homebrew로 설치하면 claude-code는 stable 버전을 사용하며, 보통 최신 버전보다 일주일 정도 늦지만 중대한 문제가 있는 버전은 건너뜁니다. 최신 버전을 받고 싶다면 claude-code@latest를 설치하세요.

실행한 뒤 먼저 알아둘 점: 기본값은 Auto mode

v2.1.284부터 터미널과 VS Code의 대화형 session은 권한 모드를 설정하지 않은 경우, 요금제나 플랫폼과 관계없이 기본값이 Auto mode입니다. 분류기가 동작을 대신 검토하며, 대부분의 파일 수정과 명령은 더 이상 확인을 요청하지 않습니다. 다만 설치 직후 첫 session은 여전히 Manual mode일 수 있습니다.

직접 확인하고 싶다면 Shift+Tab을 눌러 Manual로 전환할 수 있습니다. 다만 이는 이번 대화에만 적용됩니다. 매번 Manual로 시작하고 싶다면 뒤의 〈권한 시스템과 auto mode〉 장을 참고하세요.

다음 단계

먼저 프로젝트 하나를 열고 “이 프로젝트는 무엇을 하는 프로젝트인가요?”라고 물어보며, 파일을 읽고 답변할 수 있는지 확인해 보세요. 익숙해지면 그때 외부 도구를 연결하세요.

출처: Claude Code 공식 문서 〈Quickstart〉, 〈Advanced setup〉의 System requirements, Install with npm 절 (2026-09-15 확인); 〈Choose a permission mode〉의 Which mode a session starts in 절 (2026-09-15 확인); Claude Code CHANGELOG의 2.1.284 (2026-10-02 확인)

MCP(Model Context Protocol)란 무엇인가요?

Claude Code로 외부 도구를 연결해 본 적이 있다면, 아마 대부분 같은 경험을 해 보셨을 겁니다. MCP는 발전 속도가 너무 빨라서 며칠마다 새로운 것이 나오고, 도대체 어떤 것을 설치해야 할지 알기 어렵습니다.

먼저 MCP가 무엇인지 이야기해 보겠습니다. MCP는 플러그와 같습니다. 다른 사람이 도구를 만들어 통일된 규격으로 정리해 두면, 여러분은 그것을 꽂기만 하면 Claude Code가 같은 방식으로 데이터를 읽고 도구를 조작할 수 있습니다. MCP가 없던 시절에는 도구를 하나 연결할 때마다 직접 연동 작업을 해야 했습니다.

저는 개인적으로 사용할 때 보수적인 편이라, 다른 사람이 만든 것을 함부로 설치하지 않습니다. 결국 남기게 되는 MCP는 제가 대략 검토했거나 많은 사람이 추천하는 것들입니다. 새롭고 사용자가 적어 보이는 것은 한동안 지켜보는 편입니다.

그렇다면 MCP는 언제 연결해야 할까요? 공식 문서가 제시하는 기준은 실용적입니다. 다른 도구에 있는 데이터를 계속 복사해서 대화창에 붙여 넣고 있다는 것을 발견했을 때, 예를 들어 issue 추적 시스템이나 모니터링 대시보드라면 연결할 때입니다. 연결해 두면 Claude가 해당 시스템을 직접 읽고 조작할 수 있어, 더 이상 여러분이 정보를 옮겨 줄 필요가 없습니다.

MCP의 두 끝: Host, Client, Server

MCP가 작동하려면 양쪽 모두에 구성 요소가 있어야 합니다. MCP에는 세 가지 역할이 있습니다:

즉, Claude Code에 MCP를 세 개 연결해 두었다면, 그 뒤에는 각각 독립된 연결이 세 개 있는 것입니다.

연결하면 무엇을 가져올 수 있나요

Server는 세 가지를 제공할 수 있으며, Claude Code에서의 사용 방식이 각각 다릅니다:

1. Tools(도구): 실행할 수 있는 동작으로, 예를 들어 데이터베이스 조회, API 호출, 파일 조작이 있습니다. 언제 호출할지는 Claude가 스스로 판단합니다.
2. Resources(리소스): 콘텐츠를 제공하는 데이터 소스로, 예를 들어 파일 내용이나 데이터베이스 레코드가 있습니다. 프롬프트에 @를 입력하면 파일을 참조하듯이 이것을 참조할 수 있습니다.
3. Prompts(프롬프트 템플릿): 미리 작성된 프롬프트 템플릿으로, Claude Code에서는 명령어가 됩니다. /를 입력하면 보이며, 이름 형식은 /servername:promptname입니다.

다음 단계

처음 시작하신다면 한 가지만 하시기를 권합니다. 매일 사용하는 도구, 예를 들어 Notion이나 GitHub 중 하나를 골라 그 MCP를 먼저 연결하고, 잘 쓸 수 있는지 확인한 뒤에 두 번째를 추가하세요. 연결 방법은 다음 장에서 이어서 설명합니다.

출처: Claude Code 공식 문서 〈Connect Claude Code to tools via MCP〉, MCP 공식 문서 〈Architecture overview〉

Claude Code에서 MCP를 설정하는 방법

MCP를 설정했는데 다른 프로젝트로 옮기니 사라졌거나, 동료가 프로젝트를 clone했는데 영문도 모르게 내 server까지 함께 들어와 있다면, 문제는 대개 같은 곳에서 생깁니다: 스코프(작용 범위).

같은 server는 세 가지 서로 다른 위치에 저장될 수 있으며, 어디에 저장되느냐에 따라 어떤 프로젝트에서 적용되고 다른 사람과 공유되는지가 결정됩니다.

세 가지 스코프

여기서 쉽게 헷갈리는 부분이 있습니다. MCP의 local은 이름이 local이지만, 프로젝트 안의 .claude/settings.local.json에 저장되지 않고, 홈 디렉터리의 ~/.claude.json에 저장됩니다. 공식 문서도 이 점을 특별히 강조하고 있습니다.

server를 추가할 때는 --scope로 지정해야 합니다:

# local (default): only you, only this project
claude mcp add --transport http stripe https://mcp.stripe.com

# project: written to .mcp.json, shared with the team
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# user: only you, across all your projects
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

다른 사람의 프로젝트에 있는 MCP는 바로 실행되지 않습니다

앞 장에서 말씀드렸듯이, 저는 다른 사람이 만든 것을 함부로 설치하지 않습니다. Claude Code도 이 점에서 마찬가지로 보수적입니다.

project 스코프의 server는 .mcp.json에 작성되어 repo와 함께 clone됩니다. 그래서 공식적으로 보안상의 이유로, 대화형 모드에서 이러한 server를 사용하기 전에 승인할지 먼저 묻습니다.

몇 가지 주의할 세부 사항은 다음과 같습니다:

• clone한 repo는 스스로를 승인할 수 없습니다. repo의 .claude/settings.json에 enableAllProjectMcpServers가 적혀 있더라도, 이 폴더를 신뢰하기 전까지는 무시되며 server는 「⏸ Pending approval」 상태에 머무릅니다.
• 비대화형 모드에서는 바로 로드됩니다. claude -p, Agent SDK 또는 클라우드에서 실행할 때는 확인 창을 띄울 수 없어 project의 server가 바로 로드됩니다. 이런 상황에서 다른 사람의 프로젝트를 실행한다면, 먼저 .mcp.json에 무엇이 적혀 있는지 확인해야 합니다.
• 다시 선택하고 싶다면 claude mcp reset-project-choices를 실행하세요.

네 가지 연결 방식

판단 기준은 간단합니다. 원격 서비스는 먼저 HTTP를 사용하고, 로컬 프로그램을 실행하려면 stdio를 사용하며, server가 능동적으로 데이터를 보내야 할 때만 WebSocket을 고려하세요.

API key를 .mcp.json에 직접 쓰지 마세요

.mcp.json은 git에 포함됩니다. key를 그대로 써 넣으면 repo를 볼 수 있는 모든 사람에게 공개되는 것과 같습니다. 대신 환경 변수를 사용하세요:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

• ${VAR}: 환경 변수 VAR의 값으로 대체됩니다
• ${VAR:-기본값}: 설정되어 있으면 그 값을 사용하고, 설정되어 있지 않으면 기본값을 사용합니다
• command, args, env, url, headers 필드에서 사용할 수 있습니다

로그인이 필요한 원격 server

많은 클라우드 MCP는 인증이 필요하며, Claude Code는 OAuth 2.0을 지원합니다. server를 추가한 후 Claude Code에서 /mcp를 입력하고, 브라우저에 표시되는 단계에 따라 로그인하면 됩니다. 로그인 후 token은 자동으로 갱신됩니다. 권한을 취소하려면 역시 /mcp 메뉴에서 지우면 됩니다.

v2.1.288부터는 MCP server가 도구 실행 도중 추가 OAuth scope를 요구하면, Claude Code가 다시 인증하도록 안내합니다. /mcp에서 직접 지운 뒤 다시 로그인할 필요가 없습니다.

다음 단계

먼저 claude mcp add로 HTTP server 하나를 연결해 보세요. 예를 들어 Notion이라면:

claude mcp add --transport http notion https://mcp.notion.com/mcp

그다음 Claude Code에서 /mcp를 입력해 연결되었는지 확인하세요. 연결되지 않는다면 다음 장을 계속 읽어 보세요.

출처: Claude Code 공식 문서 〈Connect Claude Code to tools via MCP〉의 Installing MCP servers, MCP installation scopes, Project server approvals and workspace trust, Environment variable expansion in .mcp.json, Authenticate with remote MCP servers 절; Claude Code CHANGELOG의 2.1.288 (2026-10-03 확인)

자주 발생하는 문제 해결

MCP를 추가했는데도 Claude가 도구를 찾을 수 없다고 하나요? 바로 삭제하고 다시 설치하기 전에, 아래 순서대로 하나씩 확인해 보세요.

1. 먼저 상태 확인

claude mcp list는 각 server 옆에 상태를 표시합니다:

주의하세요: ✘가 보인다면 Claude Code가 해당 server에 연결하지 못한 것이지, list 명령 자체가 고장 난 것이 아닙니다.

여러 server가 한꺼번에 끊긴 경우(예: 네트워크를 방금 바꾼 경우), 대화 화면에서 /mcp reconnect all을 입력하면 연결되지 않았거나 로그인이 필요한 모든 server를 한 번에 다시 시도합니다(v2.1.284부터).

v2.1.287부터 Claude Code는 2025-11-25 프로토콜에 따른 MCP server의 URL 안내(예: 로그인 요청)를 지원합니다. 업데이트 후 특정 server에 연결할 수 없게 되었다면, 해당 server의 MCP 설정에 "bareElicitationCapability": true를 추가하세요(이 필드는 현재 공식 CHANGELOG에만 기록되어 있으며, MCP 문서에는 아직 설명되어 있지 않습니다).

2. 환경 변수가 설정되지 않음

설정에서 ${VAR}를 사용했는데 이 변수가 설정되어 있지 않고 기본값도 없으면, Claude Code는 그래도 server를 로드합니다. 다만 claude mcp list와 /mcp에서 어떤 변수가 누락되었는지 알려주는 경고가 표시됩니다. 이때 ${VAR}는 그대로 문자열로 취급되므로, server가 연결되지 않는 것은 당연합니다.

따라서 경고가 보이면 해당 변수를 설정하거나, ${VAR:-기본값} 형태로 바꾸세요.

3. 직접 만든 stdio server: stdout이 오염됨

server가 직접 작성한 stdio 프로그램이라면 특히 주의해야 합니다. stdio는 표준 입력과 표준 출력으로 MCP 메시지를 주고받으며, MCP 사양은 server가 MCP 메시지가 아닌 어떤 내용도 stdout에 출력하지 않도록 규정하고 있습니다. console.log 한 줄만 더 있어도 연결이 깨질 수 있습니다.

디버그 메시지는 모두 stderr에 기록하세요. 사양상 로그는 stderr로 남기는 것이 허용됩니다.

또한 v2.1.292부터 로컬(stdio) MCP server는 기본적으로 프로토콜 버전 2026-07-28로 협상하며, Bedrock, Vertex, Foundry에서도 마찬가지입니다. server가 새 버전의 프로토콜 검사를 무시한다면, 처음 연결할 때 조금 더 기다리게 됩니다. 이후 7일 동안 Claude Code가 이를 기억해 이전 방식으로 바로 연결합니다. 이전 동작으로 완전히 되돌리려면 환경 변수 MCP_PROTOCOL_NEGOTIATION=legacy를 설정하세요.

4. MCP를 많이 연결하면 context를 많이 차지하나요?

영향은 매우 작습니다. Claude Code는 기본적으로 tool search를 켜 둡니다. 처음에는 도구 이름과 server 설명만 로드하고, 전체 도구 정의는 Claude가 실제로 필요할 때 찾아 옵니다. 공식 문서에서도 설명하듯이, server마다 고정된 도구 수 상한은 없으며, 실제 제한은 context window의 용량입니다.

v2.1.296부터 MCP 도구 설명과 server instructions가 미리 context로 전달되는 글자 수 상한이 2,048자에서 4,096자로 늘어났습니다. 설명이 긴 server도 덜 잘리게 되었습니다.

각 server가 제공하는 도구 수는 /mcp 패널에서 확인할 수 있습니다.

다음 단계

문제가 생기면 먼저 claude mcp list를 한 번 실행하고, 상태를 보고 로그인이 필요한지, 승인이 필요한지, 아니면 환경 변수를 채워야 하는지 판단하세요.

출처: Claude Code 공식 문서 〈Connect Claude Code to tools via MCP〉의 Server status, Configuration warnings, Tool availability, Scale with MCP tool search 절; MCP 사양 〈stdio transport〉; Claude Code CHANGELOG의 2.1.284, 2.1.287 (2026-10-02 확인), 2.1.292 (2026-10-07 확인), 2.1.296 (2026-10-10 확인)

CLAUDE.md와 메모리 시스템

새 대화를 열 때마다 「이 프로젝트는 pnpm을 씁니다」, 「테스트 명령어는 이것입니다」라고 Claude에게 매번 다시 말해야 한다면, 문제는 Claude의 기억력이 나빠서가 아닙니다. 원래 모든 session이 새로운 context window에서 시작되기 때문입니다.

Claude가 기억하도록 하기 위해 Claude Code에는 두 가지 메커니즘이 있습니다. 신입 사원의 입사에 빗대어 생각하면 이해하기 쉽습니다. CLAUDE.md는 여러분이 Claude에게 써 주는 인수인계 매뉴얼이며, 출근할 때마다 먼저 한 번 읽습니다. auto memory는 Claude가 스스로 작성하는 업무 노트이며, 여러분이 바로잡아 준 내용을 스스로 기록합니다.

두 가지 메모리의 차이

두 가지 모두 Claude에게는 context일 뿐이며, 강제 설정이 아닙니다. Claude는 최대한 따르려고 하지만 보장되지는 않습니다. Claude가 어떻게 판단하든 반드시 막아야 하는 동작이라면 PreToolUse hook을 사용해야 합니다.

CLAUDE.md는 어디에 두나요

CLAUDE.md는 네 곳에 둘 수 있으며, 어디에 두느냐에 따라 누가 읽는지가 결정됩니다:

덮어쓰기가 아니라 겹쳐서 적용됩니다

어디에 둘지 알았다면 다음 질문은 이것입니다. 여러 파일이 동시에 있을 때 누구의 지시를 따르는가?

답은 모두 이어 붙여서 읽는다는 것입니다. 서로 덮어쓰지 않습니다:

• 위로 탐색: Claude Code를 실행한 디렉터리에서 시작해 위쪽 각 계층의 CLAUDE.md와 CLAUDE.local.md가 실행 시 모두 로드됩니다.
• 먼 곳에서 가까운 곳 순으로: 실행 위치에 가까운 파일일수록 나중에 읽힙니다. 같은 계층 안에서는 CLAUDE.local.md가 CLAUDE.md보다 뒤에 옵니다.
• 하위 디렉터리는 나중에 읽습니다: 아래쪽 하위 디렉터리의 CLAUDE.md는 처음부터 로드되지 않고, Claude가 해당 하위 디렉터리의 파일을 읽을 때 함께 불러옵니다.

여러 파일을 이어서 읽기 때문에, 두 파일이 서로 모순되는 규칙을 적어 두면 Claude가 아무 규칙이나 하나를 골라 따를 수 있습니다. 그래서 주기적으로 다시 확인하여 오래되었거나 충돌하는 지시는 삭제해야 합니다.

/init으로 시작하기

어디서부터 써야 할지 모르겠다면 프로젝트에서 /init을 실행하세요. Claude가 코드를 분석해 build 명령, 테스트 방법, 프로젝트 관례가 담긴 CLAUDE.md를 생성합니다. 이미 CLAUDE.md가 있다면 개선 제안을 하며, 바로 덮어쓰지는 않습니다.

생성된 뒤에는 Claude가 코드만으로는 알 수 없는 내용을 직접 보충하세요. 더 완전한 흐름을 원한다면 먼저 CLAUDE_CODE_NEW_INIT=1을 설정하세요. 그러면 /init이 CLAUDE.md, skills, hooks 중 무엇을 설정할지 단계별로 물어보고, 마지막에 제안서를 보여 준 뒤 확인을 받고서야 파일을 씁니다.

효과적으로 쓰는 방법

CLAUDE.md는 모든 session에서 로드되며 토큰을 차지하기 때문에, 어떻게 쓰느냐가 Claude가 따르는지 여부에 직접 영향을 줍니다. 공식 문서는 몇 가지 방향을 제시합니다:

• 길이: 파일 하나당 200줄 이내로 유지하세요. 길수록 context를 많이 차지하고 준수율도 낮아집니다.
• 구조: markdown 제목과 목록으로 묶고, 한 덩어리로 쓰지 마세요.
• 검증 가능할 만큼 구체적으로:

언제 항목을 하나 추가해야 할까요? 문서의 판단 기준이 실용적입니다. Claude가 같은 실수를 두 번 저지를 때, 또는 지난번에 했던 바로잡기를 대화에서 또 하고 있다는 것을 알아차렸을 때 적어 두세요. 반대로 여러 단계로 이루어진 절차나 코드 일부에만 관련된 규칙은 skill이나 .claude/rules/에 넣는 편이 더 적합합니다.

참고: v2.1.293부터 Claude가 Bash 도구에서 단일 파일을 cat, head, tail, sed -n 또는 grep으로 볼 때에도, 해당 경로에 적용되는 .claude/rules/ 규칙과 하위 폴더의 CLAUDE.md를 로드합니다. 이전에는 Read 도구를 사용할 때만 그렇게 했습니다.

@로 다른 파일 불러오기

CLAUDE.md는 @경로로 다른 파일을 참조할 수 있으며, 실행 시 함께 펼쳐져 로드됩니다:

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

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

• 상대 경로는 이 줄을 작성한 파일을 기준으로 해석되며, 작업 디렉터리를 기준으로 하지 않습니다.
• 참조된 파일은 또 다른 파일을 참조할 수 있으며, 최대 네 단계까지 가능합니다.
• 경로를 언급만 하고 참조하고 싶지 않다면 백틱으로 감싸세요. 예: `@README`.
• 프로젝트의 CLAUDE.md가 작업 디렉터리 밖의 파일을 참조하면 처음에 승인 창이 뜹니다. 거부하면 이 참조는 로드되지 않습니다.
• import로 나누는 것은 정리하기 위한 것일 뿐이며, context를 줄여 주지는 않습니다. 참조된 파일도 실행 시 똑같이 로드됩니다.

AGENTS.md: v2.1.277부터 기본 지원

많은 repo에는 이미 Codex, Cursor, Gemini 같은 Agent가 읽는 AGENTS.md가 있습니다. 이전에는 Claude Code가 이를 읽지 않아서, CLAUDE.md 첫 줄에 @AGENTS.md를 써서 참조하는 방법밖에 없었습니다. v2.1.277부터는 프로젝트에 CLAUDE.md(그리고 CLAUDE.local.md도)가 없을 때 Claude Code가 AGENTS.md를 바로 읽습니다.

먼저 세 가지를 구분해 두세요:

• 합치는 것이 아니라 대체합니다. 로직은 「CLAUDE.md가 없을 때만 AGENTS.md를 읽는다」입니다. 두 파일이 모두 있으면 여전히 CLAUDE.md를 읽고 AGENTS.md는 무시됩니다. CLAUDE.local.md도 같은 취급을 받는다는 점에 유의하세요. 개인 설정을 위해 하나만 추가해도 AGENTS.md는 더 이상 읽히지 않습니다.
• 두 파일을 모두 읽게 하려면 두 가지 방법이 있습니다. 하나는 /config를 입력해 Project instructions를 claude-md-and-agents-md로 설정하는 것입니다. 그러면 두 파일을 모두 읽습니다. 다른 하나는 CLAUDE.md 첫 줄에 @AGENTS.md를 참조로 쓰는 것입니다. 이때 내용은 AGENTS.md 한 파일에서만 관리하고, Claude Code 전용 규칙은 아래에 적습니다. 후자는 Claude Code의 버전이나 설정에 의존하지 않으므로 여러 Agent를 사용할 때 더 안정적입니다.
• v2.1.281부터 클라우드 벤더도 지원합니다. Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateway와 telemetry를 끈 session도 이제 AGENTS.md를 읽습니다. 팀에서 쓰는 Claude Code 버전이 제각각이라면, 구버전을 이런 플랫폼에서 사용할 때는 여전히 이 메커니즘이 적용되지 않으므로 그때는 CLAUDE.md를 남겨 두세요.

어느 파일을 읽을지는 /config의 Project instructions에서 전환하세요.

auto memory: Claude의 개인 노트

auto memory는 기본적으로 켜져 있습니다. 여러분이 Claude를 바로잡거나 어떤 방식이 맞다고 확인해 주면, Claude는 기록할 가치가 있는지 판단해 ~/.claude/projects/<project>/memory/에 저장합니다:

~/.claude/projects/<project>/memory/
├── MEMORY.md           # Index, one line per entry, loaded every session
├── user_role.md        # One memory
├── feedback_testing.md # One memory
└── ...

• 무엇을 기록하나: user(역할과 선호), feedback(바로잡아 준 내용), project(진행 중인 작업, 기한, 결정 사항), reference(외부 정보를 찾을 수 있는 위치)의 네 가지로 나뉩니다. 코드에서 알 수 있는 내용이나 CLAUDE.md에 이미 적힌 내용은 기록하지 않습니다.
• 로드 방식: 실행 시에는 MEMORY.md의 앞 200줄 또는 25KB만 읽고, 나머지 주제별 파일은 필요할 때 읽습니다.
• 이 컴퓨터에만 저장: 다른 컴퓨터나 클라우드 환경으로 동기화되지 않습니다.
• 끄는 방법: /memory에서 전환하거나, 프로젝트 설정에 "autoMemoryEnabled": false를 적으면 됩니다. 환경 변수 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1을 설정해도 됩니다.

Claude에게 「기억해 줘, 항상 pnpm을 써」라고 말하면 auto memory에 저장됩니다. CLAUDE.md에 쓰고 싶다면 「이것을 CLAUDE.md에 추가해 줘」라고 분명히 말해야 합니다.

/memory와 /context로 확인하기

• /memory: 사용자 및 프로젝트 계층의 CLAUDE.md, CLAUDE.local.md 등의 파일을 나열합니다. 파일을 선택하면 편집기로 열리며, 아직 없는 파일은 바로 생성됩니다. 여기에서 auto memory를 켜고 끄거나 auto memory 폴더를 열어 실제로 무엇을 기록했는지 확인할 수도 있습니다.
• /context: 이 session에서 실제로 로드된 파일을 확인합니다. Memory files 아래에 나열됩니다. Claude가 CLAUDE.md대로 하지 않을 때는 먼저 여기에서 파일이 제대로 읽혔는지 확인하세요.

다음 단계

프로젝트에 아직 CLAUDE.md가 없다면 한 가지만 하시기를 권합니다. 프로젝트 루트 디렉터리에서 /init을 실행하고, 생성된 파일을 열어 이해하기 어렵거나 쓰지 않을 내용은 삭제한 뒤, 가장 자주 반복해서 말하는 바로잡기 내용을 한 줄 추가하세요. 다음에 새 session을 열 때 /context를 실행해 Memory files에 해당 파일이 나타나는지 확인하세요.

출처: Claude Code 공식 문서 〈How Claude remembers your project〉의 CLAUDE.md vs auto memory, CLAUDE.md files, Auto memory, View and edit with /memory, Troubleshoot memory issues 절 (2026-09-15 확인). AGENTS.md 절의 내용은 Claude Code CHANGELOG의 2.1.277 (2026-09-19 확인)에서 가져왔습니다. Claude Code CHANGELOG의 2.1.281 (2026-10-02 확인), 2.1.293 (2026-10-08 확인)도 참고했습니다 (2026-10-15에 〈How Claude remembers your project〉의 AGENTS.md 절과 대조하여 업데이트했습니다).

권한 시스템과 auto mode

Claude Code를 한동안 쓰다 보면 대개 두 극단 중 하나에 막히게 됩니다. 명령을 하나 실행할 때마다 확인을 물어보느라 손이 아플 지경이거나, 아예 모두 허용해 두고 언젠가 지우면 안 되는 것을 지워 버릴까 걱정되는 경우입니다.

사실 이 두 가지는 따로 관리합니다. 권한 모드는 건물 경비 등급과 같아서 전체적으로 얼마나 엄격할지를 정합니다. 권한 규칙은 출입 명단과 같아서 어떤 문은 반드시 통과시키고, 어떤 문은 반드시 확인을 받고, 어떤 문은 절대 들어갈 수 없는지를 지정합니다. 먼저 모드를 고른 다음, 규칙으로 신경 쓰이는 몇 가지를 보완하세요.

여섯 가지 권한 모드

CLI에서 default는 Manual로 표시됩니다. 또한 어떤 모드에서든 항상 적용되는 규칙이 하나 있습니다. deny 규칙은 반드시 차단하며, bypassPermissions에서도 마찬가지입니다.

Shift+Tab으로 전환하기

대화 중에 Shift+Tab을 누르면 모드가 순환하며 전환됩니다. auto에서 처음 누르면 default로 돌아가고, 이어서 default → acceptEdits → plan 순서로 바뀝니다. auto mode를 사용할 수 있다면 plan 뒤에 배치되고, 다시 default로 돌아갑니다. 어떤 모드로 전환하든 상태 표시줄에 ⏸ manual mode on, ⏵⏵ accept edits on, ⏸ plan mode on 또는 ⏵⏵ auto mode on이 표시됩니다.

이 순환에 포함되지 않는 모드가 두 가지 있습니다. dontAsk는 --permission-mode dontAsk로만 시작할 수 있고, bypassPermissions는 시작할 때 활성화해야(예: --dangerously-skip-permissions) 순환에 나타납니다. 특정 모드로 바로 시작하고 싶다면 역시 인자를 붙이면 됩니다. 예: claude --permission-mode plan.

auto mode의 작동 방식

auto mode는 「확인 요청」이라는 일을 다른 모델(분류기)에게 맡겨 판단하게 하는 모드입니다. 각 동작은 다음 순서로 처리되며, 먼저 해당되는 규칙이 우선 적용됩니다:

1. 직접 작성한 allow, ask, deny 규칙에 해당하면 그 규칙을 그대로 따릅니다
2. 읽기와 작업 디렉터리 안의 파일 수정은 바로 허용합니다(.git, .claude처럼 보호되는 경로에 대한 쓰기는 제외)
3. 그 밖의 동작은 분류기가 판단합니다
4. 분류기가 차단하면 Claude는 그 이유를 받고 스스로 다른 방법을 사용합니다

분류기가 기본적으로 차단하는 예: curl | bash처럼 내려받자마자 바로 실행하는 것, 민감한 데이터를 외부로 보내는 것, 운영 환경 배포와 migration, force push, git reset --hard. 기본적으로 허용하는 예: 작업 디렉터리 안의 파일 작업, lock 파일에 선언된 패키지 설치, 읽기 전용 HTTP 요청, 작업 중인 repo의 모든 브랜치에 대한 push. 전체 목록은 claude auto-mode defaults를 실행해 확인할 수 있습니다.

먼저 알아 두어야 할 몇 가지 제한 사항이 있습니다:

• 안전을 보장하지 않습니다. 공식 설명에 따르면, 큰 방향을 신뢰할 수 있는 작업에 사용하고, 민감한 작업에 대한 검토를 대신하는 용도로 쓰지 마세요.
• 지나치게 넓은 allow 규칙은 일시적으로 무효화됩니다. auto mode에 들어가면 Bash(*), Bash(python*)처럼 임의의 프로그램 실행을 허용하는 것과 같은 규칙은 제거되며, auto mode를 벗어나면 다시 적용됩니다. Bash(npm test)처럼 범위가 좁은 규칙은 영향을 받지 않습니다.
• 대화에서 「push 하지 마」라고 말하는 것은 도움이 되지만 확실하지는 않습니다. 분류기는 이를 차단 신호로 받아들이지만, 매번 대화 기록에서 다시 읽기 때문에 context가 압축되면 그 말은 사라집니다. 확실히 막으려면 deny 규칙으로 작성하세요.
• 연속으로 차단되면 수동 모드로 되돌아갑니다. 연속 3회 또는 session 전체에서 누적 20회 차단되면 auto mode가 일시 중지되고 다시 확인을 요청하며, 이 두 숫자는 조정할 수 없습니다. 차단된 동작은 /permissions의 Recently denied 탭에 나열되며, r을 누르면 수동으로 승인해 다시 실행할 수 있습니다.
• 모델 제한이 있습니다. Anthropic API와 Claude Platform on AWS에서는 Claude Opus 4.6 이상, Sonnet 4.6 이상, Haiku 5.5 또는 Fable 모델이 필요합니다. Amazon Bedrock, Google Cloud Agent Platform, Microsoft Foundry에서는 Sonnet 5 이상, Opus 4.7 이상, Haiku 5.5(v2.1.293 이상 필요) 및 Fable만 지원하며, 그 밖의 모델 session은 Manual로 시작합니다.
• 조직에서 끌 수 있습니다. 관리자가 managed settings에서 permissions.disableAutoMode를 "disable"로 설정하면 auto는 Shift+Tab 전환 목록에서 사라집니다. permissions.disableBypassPermissionsMode 역시 bypassPermissions를 차단할 수 있습니다.
• 작업 디렉터리 밖의 파일 읽기는 이번 한 번만 허용할 수 있습니다. v2.1.284부터 이런 질문에 「Yes, but ask again next time」 옵션이 추가되었습니다. 이번 읽기는 통과되지만, 다음에 작업 디렉터리 밖의 파일을 읽을 때는 여전히 확인을 요청합니다.
• 위험한 rm은 무한정 기다리지 않습니다. --dangerously-skip-permissions와 auto mode에서 위험한 rm을 만나면 2분 동안 기다립니다. 응답이 없으면 바로 거부하고 수정 제안을 덧붙여, 아무도 지켜보지 않는 session도 계속 실행될 수 있도록 합니다(v2.1.281부터). 이 시간 제한을 원하지 않는다면 CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT=1을 설정하세요.

분류기는 내 쪽에서 실행되나요, 서버에서 실행되나요

분류기 자체도 모델 호출 한 번입니다. 로컬에서 실행하면 판단이 필요한 동작마다 토큰을 한 번 더 지불하는 셈이며, 이 비용은 이전에는 여러분이 부담했습니다.

v2.1.278부터 Claude API 및 Enterprise 사용자, 그리고 Bedrock, Vertex, Foundry, gateway는 기본적으로 서버 측 분류기를 사용하며, 이 오버헤드는 과금되지 않습니다. 실제로 과금되는 버전으로 되돌아가는 경우에는 화면에 경고가 표시되어 알려 줍니다.

• 로컬 분류기로 되돌리려면(Bedrock, Vertex, Foundry, gateway에서만 가능): CLAUDE_CODE_AUTO_MODE_SERVER=0을 설정하세요.
• 이 session이 어디에서 실행되는지 확인하려면 /status를 입력하고 Auto mode server 행을 보세요.

auto mode에서 알아 둘 추가 변경 사항 세 가지

모두 v2.1.271 이후 순차적으로 추가된 것으로, 실제로 사용하면 부딪히게 됩니다:

• 샌드박스 모드의 도메인은 명령별로 검토합니다. Bash, PowerShell, Monitor에 allowed_domains가 추가되었습니다. 한 명령이 연결해야 하는 호스트는 그 명령과 함께 검토되며, 해당 명령을 위해서만 열리고 다른 호스트는 여전히 거부됩니다. curl 한 번 때문에 도메인 전체를 영구적으로 허용할 필요가 없습니다.
• skill과 slash command에 있는 ! 명령은 더 이상 분류기에 맡기지 않습니다. 대신 default 모드의 권한 규칙으로 판단합니다. 판단할 규칙이 없으면 여러분이 직접 확인해야 하는 도구 호출이 됩니다. skill에 작성한 !`git diff HEAD`는 permissions의 관리를 받으며, 분류기의 관리를 받지 않습니다.
• subagent의 결과는 격리해서 취급합니다. subagent가 메인 대화에 결과를 보고할 때는 전용 반환 호출을 거치며, 분류기가 검토합니다. v2.1.278부터는 결과에 「이것은 subagent 출력입니다」라는 헤더가 붙고 들여쓰기도 적용됩니다. 목적은 같습니다. subagent가 가져온 텍스트가 여러분이 내린 지시인 것처럼 행세할 수 없도록 하는 것입니다.

Claude Code를 열면 어떤 모드로 시작하나요

터미널에서 새 session을 열 때 다음 순서로 결정됩니다:

1. 실행 인자 --permission-mode 또는 --dangerously-skip-permissions
2. 설정 파일의 permissions.defaultMode
3. 내장 기본값

내장 기본값: v2.1.284부터 터미널과 VS Code 확장 프로그램의 대화형 session은 요금제와 플랫폼에 관계없이 auto입니다(이전에는 Enterprise, Console API key, 서드파티 플랫폼이 default였습니다). claude -p와 Python Agent SDK도 서드파티 플랫폼을 사용하거나 telemetry를 끈 경우 v2.1.285부터 auto mode로 시작하며, 그 밖의 경우는 기존과 같습니다. 조직 정책이 auto의 기본값을 철회한 경우에는 session이 default로 시작합니다. --permission-mode로 지정한 값이 여전히 우선합니다. 또한 설치하거나 업그레이드한 직후의 첫 session은 default일 수도 있습니다.

특히 주의해야 할 점이 있습니다. "auto"를 프로젝트의 .claude/settings.json이나 .claude/settings.local.json에 써도 적용되지 않으며, ~/.claude/settings.json에 써야 합니다. 반대로 매번 Manual로 시작하고 싶다면 역시 여기에 {"permissions": {"defaultMode": "default"}}를 작성하세요.

allow, ask, deny 규칙 작성법

규칙 형식은 Tool 또는 Tool(조건)입니다. 세 목록의 의미는 다음과 같습니다. allow는 묻지 않고 실행, ask는 매번 묻기, deny는 바로 차단입니다.

판단 순서는 항상 deny → ask → allow입니다. 먼저 일치하는 규칙이 결과를 결정하며, 더 정확하게 작성하면 순서에 밀리지 않습니다. 따라서 Bash(aws *)를 deny하면, 별도로 Bash(aws s3 ls)를 allow하더라도 여전히 차단됩니다.

{
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(git commit *)"],
    "deny": ["Bash(git push *)"]
  }
}

자주 쓰는 형식:

Bash 규칙을 작성할 때는 세 가지를 주의하세요:

• *는 하위 명령 뒤에 둡니다. Bash(git log *)는 git log만 허용하고, Bash(git *)는 모든 git 명령을 허용하는 것과 같습니다.
• 연결된 명령은 나누어서 검사합니다. Bash(safe-cmd *)는 safe-cmd && other-cmd를 허용하지 않으며, 각 부분이 모두 일치해야 합니다.
• Bash 규칙은 보안 경계가 아닙니다. Bash(git push *)는 git push origin main은 막을 수 있지만, git -C . push origin main은 막지 못합니다. 확실히 막아야 한다면 공식 문서는 sandbox나 PreToolUse hook과 함께 사용할 것을 권장합니다.

Read, Edit의 경로 작성 방식도 주의해야 합니다. //로 시작해야 파일 시스템의 절대 경로이고, ~/는 홈 디렉터리이며, 단일 /로 시작하면 설정 파일이 있는 위치를 기준으로 한 상대 위치입니다. 따라서 /Users/alice/file은 절대 경로가 아니므로 //Users/alice/file로 작성해야 합니다. 규칙은 Claude Code가 실행하는 것이지, 모델이 스스로 지키는 것이 아닙니다. CLAUDE.md에 적은 「하지 말아야 할 일」은 Claude가 어떻게 행동할지에만 영향을 줄 뿐, 실제로 막아 주지는 않습니다.

규칙은 어느 설정 파일에 쓰나요

어느 계층에 작성하든, 계층 중 하나라도 deny가 있으면 다른 계층에서 허용할 수 없습니다. 예를 들어 user 설정에서 allow하고 project 설정에서 deny하면 결과는 차단입니다. 반대의 경우도 마찬가지입니다. 각 규칙이 어느 파일에서 왔는지 알고 싶다면 /permissions를 입력하면 확인할 수 있습니다.

다음 단계

먼저 Claude Code를 열고 상태 표시줄에 어떤 모드가 표시되는지 확인한 다음, /permissions를 입력해 이미 저장된 규칙이 무엇인지 살펴보세요. 그다음 절대 일어나지 않기를 바라는 일 하나를 골라 보세요. 예를 들어 .env를 읽는 것이라면, ~/.claude/settings.json의 deny에 Read(./.env)를 추가하세요. deny를 먼저 제대로 작성한 뒤에 auto mode를 안심하고 쓸지 결정하세요.

출처: Claude Code 공식 문서 〈Choose a permission mode〉의 Available modes, Which mode a session starts in, Switch permission modes, Eliminate permission prompts with auto mode 절, 그리고 〈Configure permissions〉의 Manage permissions, Permission rule syntax, Tool-specific permission rules, Settings precedence, Project allow rules and workspace trust 절 (2026-09-15 확인). 분류기가 어디에서 실행되는지, allowed_domains, ! 명령과 subagent 반환에 관한 내용은 Claude Code CHANGELOG의 2.1.271과 2.1.278 (2026-09-19 확인)에서 가져왔습니다. Claude Code CHANGELOG의 2.1.281, 2.1.284, 2.1.285 (2026-10-02 확인)도 참고했습니다 (2026-10-15에 〈Choose a permission mode〉를 다시 대조하여 auto mode의 모델 요구 사항을 업데이트했습니다).

Hooks: 결정론적인 계층

CLAUDE.md에 “파일을 수정한 뒤에는 formatter를 실행할 것”이나 “.env는 건드리지 말 것” 같은 내용을 써 본 적이 있다면, 아마 같은 경험을 하셨을 것입니다. 써 두기는 했지만 Claude가 매번 그대로 따른다는 보장이 없습니다.

Hooks는 이 문제를 해결하기 위한 기능입니다. 흐름에 달아 두는 센서와 같습니다. “Claude가 파일을 수정한 뒤”처럼 설치할 지점을 먼저 정하면, 흐름이 그 지점에 도달할 때 작성해 둔 shell 명령이 반드시 실행됩니다. Claude가 기억하고 있을 필요도 없고, 그 순간 Claude가 어떻게 판단하는지도 보지 않습니다.

왜 “결정론적”이라고 부르나요

공식 문서는 이를 분명하게 설명합니다. Hooks는 특정 동작이 반드시 일어나도록 보장하며, LLM이 그 동작을 할지 말지 스스로 고르게 두지 않습니다. CLAUDE.md에 적은 규칙은 Claude가 읽고 스스로 판단하는 것이고, hook으로 작성한 규칙은 Claude Code가 정해진 시점에 직접 실행하며, 도구가 실행되기 전에 이를 차단할 수도 있습니다. 따라서 판단 기준은 간단합니다. “매번 반드시 해야 하는 일”과 “절대 해서는 안 되는 일”은 hook에 맡기고, 상황을 보고 판단해야 하는 일은 CLAUDE.md에 남겨 둡니다.

가장 자주 쓰는 세 가지 이벤트

Hook은 특정 “이벤트”에 연결해야 합니다. 공식 문서에는 서른 개가 넘는 이벤트가 나와 있으니, 처음에는 이 세 가지만 알아 두면 됩니다:

설정 파일 작성 방법

Hook은 settings 파일의 hooks 안에 작성하며, 계층은 모두 세 단계입니다: 이벤트 → matcher(필터 조건) → 실행할 명령. 아래는 공식 예시인 “파일 수정 후 Prettier 자동 실행”입니다:

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

Claude Code는 이벤트 데이터를 JSON 형태로 stdin을 통해 명령에 전달합니다. 그래서 여기서는 jq(macOS에서는 brew install jq로 설치)로 방금 수정한 파일 경로를 추출한 다음, Prettier에 넘겨 줍니다. 설정을 어느 파일에 둘지는 다음과 같이 정합니다. ~/.claude/settings.json에 두면 모든 프로젝트에 적용됩니다. 프로젝트의 .claude/settings.json에 두면 해당 프로젝트에만 적용되며, git에 올려 팀과 공유할 수 있습니다. 공유하고 싶지 않다면 .claude/settings.local.json에 둡니다. 설정을 마친 뒤 /hooks를 입력해 목록에 나타나는지 확인합니다. 이 메뉴는 보기만 가능하고 수정은 할 수 없으므로, 수정하려면 JSON을 직접 편집하거나 Claude에게 수정을 요청합니다.

matcher: 필요할 때만 실행

matcher를 작성하지 않으면(또는 "", "*"로 작성하면) 이벤트가 발생할 때마다 실행됩니다. PreToolUse와 PostToolUse의 matcher는 도구 이름과 비교합니다:

• 영문, 숫자, _, -, |, ,만 포함된 경우: 완전 일치로 비교합니다. Edit|Write는 이 두 도구만 비교합니다.
• 그 밖의 문자가 포함된 경우: 정규 표현식으로 취급하며, 시작과 끝을 제한하지 않습니다. Edit.*는 NotebookEdit도 함께 일치시키므로, 완전히 일치시키려면 ^Edit$로 작성합니다.
• 대소문자를 구분합니다. 철자가 틀리면 hook이 실행되지 않습니다. Stop은 matcher를 지원하지 않으므로 매번 실행됩니다.
• Claude는 Bash로 명령을 실행해 파일을 수정할 수도 있습니다. Edit|Write만 비교하면 이런 경우를 놓치게 됩니다.

다음 동작을 차단하는 방법

명령은 **종료 코드(exit code)**로 Claude Code에게 다음에 무엇을 할지 알려 줍니다:

가장 자주 실수하는 부분은 셋째 줄입니다. Unix에서는 실패를 나타낼 때 exit 1을 쓰는 것이 관례이지만, hooks에서는 이 값으로 아무것도 차단하지 못합니다. 차단하려면 반드시 exit 2를 사용해야 합니다. 같은 exit 2라도 이벤트에 따라 동작이 다릅니다. PostToolUse에서는 stderr 내용을 Claude에게만 보여 줍니다. Stop에서는 Claude가 멈추지 않도록 막고, stderr 내용을 Claude가 계속 작업해야 하는 이유로 사용합니다. 더 세밀하게 제어하려면 exit 0으로 바꾸고 stdout에 JSON을 출력합니다. 예를 들어 PreToolUse에서 hookSpecificOutput에 담아 "permissionDecision": "deny"를 반환하면 거부되며, permissionDecisionReason으로 Claude에게 그 이유를 알릴 수 있습니다. 공식 권장 사항은 하나의 hook에서는 한 가지 방식만 선택하는 것입니다. 즉 exit 2를 쓰거나, exit 0과 JSON을 함께 쓰거나 둘 중 하나입니다.

hook 자체가 오류 날 때도 차단: onFailure: "block" (v2.1.295부터)

기본적으로 hook 시작에 실패하거나, 시간이 초과되거나, 예상하지 못한 종료 코드를 반환해도 동작은 그대로 실행됩니다. 이 hook이 보안 검사 역할을 하고 “고장 나면 통과시키는” 동작을 원하지 않는다면, command 또는 HTTP 유형 hook 설정에 "onFailure": "block"을 추가할 수 있습니다. hook을 시작할 수 없거나, 시간이 초과되거나, 예상하지 못한 종료 코드로 끝나면 해당 동작을 바로 차단합니다. 설정하지 않으면 기본값은 "continue"이며, 이는 평소처럼 실행된다는 뜻입니다. 이 설정은 Stop, SubagentStop, TaskCompleted, TeammateIdle 및 async hook에는 적용되지 않습니다. PermissionRequest hook이 실패하면 결과는 거부(deny)입니다.

전체 예시: Claude가 .env를 수정하지 못하게 하기

먼저 .claude/hooks/protect-files.sh를 만든 다음, chmod +x .claude/hooks/protect-files.sh를 실행해 실행 권한을 부여합니다:

#!/bin/bash
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

이어서 .claude/settings.json에 PreToolUse hook으로 등록합니다:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

$CLAUDE_PROJECT_DIR은 이번 session이 시작될 때의 프로젝트 루트 디렉터리이므로, 이 변수를 사용하면 작업 디렉터리가 바뀌어도 스크립트를 찾지 못하는 문제가 생기지 않습니다. 마지막으로 Claude에게 .env에 주석 한 줄을 추가해 달라고 요청하면, 해당 작업은 차단되고 Blocked:로 시작하는 메시지를 받게 됩니다.

보안 주의 사항

• hook은 사용자 계정의 모든 권한을 가집니다. 직접 삭제할 수 있는 파일은 hook도 삭제할 수 있습니다. 설정에 추가하기 전에 명령을 직접 확인하고 테스트해야 합니다.
• 경로를 잘못 입력하면 보호 기능이 소리 없이 작동하지 않습니다. 스크립트를 찾지 못하는 경우는 비차단 오류로만 처리되어 동작이 그대로 실행됩니다. 시간 초과로 취소된 PreToolUse hook도 마찬가지로 차단하지 못합니다. 설정한 뒤에는 반드시 한 번 실제로 트리거해 동작을 확인합니다.
• 다른 사람의 repo에서는 -p에 주의합니다. 대화형 모드에서는 이 폴더를 신뢰하기 전까지 hook이 실행되지 않습니다. 하지만 claude -p나 SDK는 이를 곧바로 신뢰하는 것으로 간주합니다. 실행하기 전에 .claude/ 안의 설정을 확인하거나, --settings '{"disableAllHooks": true}'를 추가해 hook을 끕니다.
• Hook은 제한만 강화할 수 있고, 완화할 수는 없습니다. PreToolUse가 deny를 반환하면 bypassPermissions 모드에서도 차단됩니다. 하지만 allow를 반환해도 settings에 있는 deny 규칙을 덮어쓸 수는 없습니다.

다음 단계

처음 시작하신다면 한 가지만 해 보시기를 권장합니다. “파일 수정 후 Prettier 자동 실행” 부분을 프로젝트의 .claude/settings.json에 붙여 넣고, /hooks를 입력해 목록에 나타나는지 확인한 뒤, Claude에게 JS 파일 하나를 수정하게 하고 포맷이 자동으로 정리되는지 확인합니다. 잘 작동하면 .env를 차단하는 PreToolUse hook을 추가합니다.

출처: Claude Code 공식 문서 〈Automate actions with hooks〉의 Auto-format code after edits, Block edits to protected files, How hooks work, Filter hooks with matchers, Configure hook location, Limitations and troubleshooting 항목, 그리고 〈Hooks reference〉의 Matcher patterns, Exit code 2, Exit code 2 behavior per event, Stop, Security considerations 항목(2026-09-15 확인), 및 Claude Code CHANGELOG의 2.1.295(2026-10-09 확인)

Skills의 작동 방식

Claude Code를 한동안 사용해 보셨다면 아마 이런 경험이 있으실 겁니다. 같은 체크리스트나 같은 배포 절차를 새 대화를 열 때마다 다시 붙여 넣어야 하거나, CLAUDE.md가 점점 길어져서 특정 상황에서만 필요한 절차까지 가득 차 버리는 경우입니다.

Skill은 이 문제를 해결하기 위한 기능입니다. 서가에 꽂힌 매뉴얼과 같아서, Claude는 평소에는 책등의 소개만 볼 수 있고, 필요한 상황이 되면 책 한 권을 꺼내 그대로 따릅니다. 사용자가 직접 이름을 지정해 특정 매뉴얼을 펼쳐 보게 할 수도 있습니다.

공식 문서가 제시하는 판단 기준은 실용적입니다. 같은 지시, 체크리스트 또는 여러 단계의 절차를 대화에 계속 붙여 넣고 있거나, CLAUDE.md의 특정 부분이 “사실”에서 “절차”로 바뀌었다면, 그때가 skill로 작성해야 할 시점입니다.

CLAUDE.md, slash command, subagent와의 차이

• CLAUDE.md: 내용이 항상 대화에 포함됩니다. Skill은 평소에는 설명만 두고, 전체 내용은 사용할 때 불러오므로 분량이 많은 참고 자료라도 사용하지 않을 때는 거의 비용이 들지 않습니다.
• Slash command(사용자 지정 명령): 이제 skill에 통합되었습니다. .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md 모두 /deploy를 생성하며 사용 방식도 같습니다. 기존 .claude/commands/ 파일도 그대로 사용할 수 있습니다. Skill에는 세 가지 기능이 추가되었습니다. 보조 파일을 넣을 수 있는 폴더, frontmatter로 누가 호출할 수 있는지 제어하는 기능, 관련 상황에서 Claude가 자동으로 불러오게 하는 기능입니다. 새로 작성하는 경우에는 skill을 바로 사용하기를 권장합니다.
• Subagent: skill은 기본적으로 현재 대화 안에서 실행되므로 앞서 나눈 내용을 읽을 수 있습니다. frontmatter에 context: fork를 추가하면 새 subagent를 열어 실행하도록 바뀌며, SKILL.md의 내용이 그 subagent의 작업이 됩니다. 다만 subagent는 대화 기록을 볼 수 없으므로 지시 내용이 그 자체로 완결되어야 합니다. 반대로 subagent도 skills 필드를 사용해 skill을 미리 불러올 수 있으며, 이는 참고 자료로 사용하는 방식입니다.

최소 실행 예시

아래 skill은 git에서 아직 commit하지 않은 변경 사항을 정리하고, 위험해 보이는 부분을 표시합니다. 먼저 개인 skill 위치에 폴더를 만들면 모든 프로젝트에서 사용할 수 있습니다:

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

다음 내용을 ~/.claude/skills/summarize-changes/SKILL.md로 저장합니다:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

!`git diff HEAD` 줄은 Claude Code가 먼저 명령을 실행해 그 출력 결과로 바꿔 넣는 부분입니다. 따라서 Claude가 받는 것은 추측이 아닌 실제 diff입니다.

git 프로젝트를 열고 아무 파일이나 수정한 뒤 claude를 실행하면 두 가지 방법으로 테스트할 수 있습니다. 하나는 설명과 맞는 질문, 예를 들어 What did I change?를 하여 Claude가 스스로 skill을 불러오게 하는 것입니다. 다른 하나는 /summarize-changes를 직접 입력하는 것입니다.

SKILL.md의 구조

SKILL.md는 두 부분으로 나뉩니다. 위쪽 ---로 감싼 YAML frontmatter는 Claude에게 언제 사용할지를 알려 주고, 아래쪽 markdown 내용은 실행할 때 따라야 할 지시입니다. frontmatter는 반드시 파일의 첫 줄 ---에서 시작해야 합니다. 그렇지 않으면 파일 전체가 내용으로 취급됩니다.

모든 필드는 선택 사항이며, 공식 문서는 description만 반드시 작성할 것을 권장합니다. 자주 사용되는 필드는 다음과 같습니다:

description에 따라 Claude가 자동으로 사용할지 결정됨

일반 대화에서는 모든 skill의 설명이 로드되어 Claude가 어떤 skill을 사용할 수 있는지 알 수 있습니다. 전체 내용은 호출될 때 로드됩니다. 즉 Claude가 특정 skill을 스스로 사용할지는 description만 보고 판단하므로, description을 어떻게 작성하느냐에 따라 skill이 사용될지가 결정됩니다.

• 핵심 용도는 맨 앞에 씁니다. description과 트리거 상황을 보충하는 when_to_use 필드를 합쳐 목록에서 1,536자를 넘으면 잘립니다. skill을 많이 설치하면 목록에도 전체 예산이 있어, 가장 적게 쓰는 skill의 설명부터 먼저 삭제됩니다.
• 사용자가 자연스럽게 말할 키워드를 넣습니다. 트리거되지 않으면 먼저 Claude에게 What skills are available?라고 물어 보아 skill이 보이는지 확인한 뒤, description을 수정하거나 질문 방식을 바꿉니다.
• 너무 자주 트리거된다면 설명을 더 구체적으로 쓰거나, 아예 disable-model-invocation: true를 추가합니다.

두 제어 필드의 차이는 다음과 같습니다. 배포나 commit처럼 부작용이 있는 절차에는 공식 문서가 disable-model-invocation: true를 사용하도록 권장합니다. 코드가 괜찮아 보인다고 Claude가 스스로 배포해 버리는 상황은 원하지 않을 것입니다.

저장 위치

저장 위치에 따라 어떤 session에서 불러올 수 있는지가 결정됩니다:

• 이름이 같을 때는 개인이 프로젝트보다 우선합니다(조직이 배포한 기업용 skill은 개인보다도 우선합니다). plugin의 skill에는 접두사가 붙어 다른 skill과 이름이 겹치지 않습니다.
• 개인 skill은 클라우드로 따라가지 않습니다. Cowork와 클라우드 session은 내 컴퓨터의 ~/.claude/skills/를 읽지 않습니다.
• 반대로 claude.ai에서 활성화한 항목은 동기화됩니다. v2.1.275부터 claude.ai 계정으로 로그인한 터미널 session은 계정에서 활성화한 skill과 plugin을 동기화합니다. 원하지 않으면 설정에 "syncClaudeAiSkills": false를 작성합니다(plugin 스위치는 syncClaudeAiPlugins입니다). 주의할 점은 동기화된 항목은 사본이라는 것입니다. 해당 폴더의 파일을 직접 수정해도 계정에 저장되지 않습니다.
• 수정한 뒤 재시작할 필요가 없습니다. ~/.claude/skills/ 또는 프로젝트의 .claude/skills/에서 skill을 추가, 수정, 삭제하면 현재 session에 바로 적용됩니다. 다만 원래 존재하지 않았던 최상위 skills 폴더는 처음 만들 때 Claude Code를 다시 시작해야 합니다.

수동으로 호출하는 방법

/를 입력하고 skill 이름을 붙입니다. 개인 및 프로젝트 skill의 명령 이름은 폴더 이름에서 가져오며, frontmatter의 name은 표시 이름만 바꿉니다. 뒤에 붙인 텍스트는 $ARGUMENTS로 전달되며, 단일 인자를 받으려면 $0, $1을 사용합니다:

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

/fix-issue 123을 실행하면 Claude는 “Fix GitHub issue 123 following our coding standards.”를 받습니다. 내용에 인자 위치를 지정하지 않았다면 Claude Code가 마지막에 ARGUMENTS: <입력한 텍스트>를 자동으로 덧붙이므로 누락되지 않습니다.

실제 사례: 정식 skill의 모습

위의 예시는 파일이 하나뿐입니다. 실제로 사용되는 skill이 어떤 모습인지는 Cloudflare가 오픈소스로 공개한 security-audit-skill을 보면 바로 알 수 있습니다. 이 skill은 coding agent를 보안 감사 담당자로 바꿔 주며, Cloudflare 내부 취약점 탐색 시스템을 단일 repo 시작 버전으로 옮긴 것입니다.

이 skill에서 볼 만한 부분은 이 장에서 앞서 설명한 내용과 정확히 대응됩니다:

• description에서 두 가지 모드를 직접 구분합니다. 같은 skill이라도 보안 질문에 답할 때는 참고 자료로만 사용하고, “codebase 전체 감사”를 명시적으로 요청할 때만 여섯 단계의 전체 절차를 실행합니다. skill을 불러온다고 해서 바로 실행 권한이 주어지는 것은 아니며, 이 경계는 description과 내용 시작 부분의 Operating modes에 적혀 있습니다.
• 참고 자료는 여러 파일로 나누고 필요할 때만 읽습니다. SKILL.md는 192줄로, 원칙, 용어, 절차 개요를 담고 있습니다. 메모리 안전성, AI와 LLM, HTTP와 인증, 공급망, 클라우드 배포 등 열 개 영역은 각각 별도 파일로 되어 있으며, SKILL.md가 이를 안내합니다. 감사 대상에 해당하지 않으면 로드되지 않습니다. 전체를 합하면 약 1,778줄이지만 평소에는 context를 차지하지 않습니다.
• 폴더 안에 프로그램을 넣을 수도 있습니다. markdown 외에도 JSON schema와 의존성이 없는 Node 검증 스크립트 두 개가 있으며, 절차가 특정 단계에 이르면 이를 실행해 생성된 findings.json과 커버리지 기록의 형식이 올바른지 확인합니다. skill에는 지시문만 넣을 수 있는 것이 아닙니다.
• subagent의 역할 분담을 절차에 명시합니다. 취약점을 찾는 작업과 검증하는 작업은 서로 다른 agent가 수행하도록 규정되어 있으며, 검증을 맡은 agent는 앞 단계의 결론을 뒤집을 방법을 찾는 것이 임무입니다. 이 skill은 parent, Task tool처럼 특정 도구에 종속되지 않는 중립적인 용어로 역할을 설명하므로 Claude Code에만 묶여 있지 않습니다.

설치는 Skills CLI를 사용하며, 앞의 “저장 위치” 항목에서 설명한 두 가지 위치에 각각 대응합니다:

# project-level
npx skills add https://github.com/cloudflare/security-audit-skill --skill security-audit

# personal, all projects
npx skills add https://github.com/cloudflare/security-audit-skill --skill security-audit --global

라이선스는 MIT이므로 이 SKILL.md를 그대로 템플릿으로 활용할 수 있습니다. 정식 skill이 “언제 사용할지”와 “무엇을 따라 할지”를 어떻게 나누어 작성하는지 확인해 볼 수 있습니다.

다음 단계

대화에 가장 자주 붙여 넣는 지시 하나를 골라 보시기를 권장합니다. 위의 예시를 참고해 ~/.claude/skills/에 개인 skill을 하나 만듭니다. 먼저 /skill-name으로 한 번 실행해 내용이 맞는지 확인한 뒤, 새 대화를 열어 자연스러운 질문을 해 보고 Claude가 스스로 불러오는지 확인합니다. 불러오지 않는다면 description을 다시 수정합니다.

출처: Claude Code 공식 문서 〈Extend Claude with skills〉의 Create your first skill, Choose where skills load, Frontmatter reference, Control who invokes a skill, Pass arguments to skills, Edit a skill during a session, Run skills in a subagent, Troubleshooting 항목(2026-09-15 확인). 실제 사례 항목의 내용은 cloudflare/security-audit-skill의 README와 SKILL.md에서 가져왔습니다(2026-09-19 확인). claude.ai 동기화 항목의 내용은 Claude Code CHANGELOG의 2.1.275(2026-09-19 확인)에서 가져왔습니다.

Subagents와 병렬 처리

Claude Code에게 테스트를 돌리거나 커다란 log를 훑어보게 한 적이 있다면, 아마 이런 경험이 있으실 겁니다. 작업은 끝났지만 대화가 이후에는 다시 보지 않을 출력으로 가득 차서, 뒤의 답변이 느려지고 둔해지는 경우입니다.

Subagent는 이 문제를 해결하기 위한 기능입니다. 심부름을 보내는 조수와 같습니다. 작업을 맡기면 조수가 직접 파일을 뒤지고 명령을 실행한 뒤, 요약 한 페이지만 돌아옵니다. 조수가 확인한 자료는 조수 쪽에 남으므로 여러분의 책상에는 쌓이지 않습니다.

메인 대화의 context를 아낄 수 있는 이유

각 subagent는 독립된 context window를 가지며, 자체 system prompt, 사용 가능한 도구, 권한도 따로 가집니다. 작업을 시작할 때 앞선 대화를 볼 수 없고, Claude가 이미 읽은 파일도 볼 수 없습니다. 받는 정보는 다음과 같습니다:

작업 중에 읽은 파일과 실행한 명령의 출력은 모두 subagent의 context에 남고, 메인 대화에는 마지막 결과만 돌아옵니다. 따라서 subagent가 반드시 알아야 하는 규칙, 예를 들어 “vendor/ 폴더는 건드리지 않는다” 같은 규칙이 있다면, 위임할 때 prompt에 다시 적어야 합니다.

내장된 subagent

설정하지 않아도 Claude가 적절한 때에 스스로 위임합니다:

Explore와 Plan은 빠르고 비용을 줄이기 위해 CLAUDE.md와 git status를 건너뜁니다. 또한 일회성이라 agent ID를 반환하지 않으므로 작업이 끝나면 이어서 진행할 수 없습니다. 중간에 추가로 질문해야 하는 작업에는 general-purpose 또는 사용자 지정 subagent를 사용해야 합니다.

사용자 지정 subagent: 저장 위치

Subagent는 YAML frontmatter가 있는 Markdown 파일입니다. 저장 위치에 따라 누가 사용할 수 있는지가 결정되며, 이름이 같을 때는 우선순위가 높은 쪽이 적용됩니다:

프로젝트용은 .claude/agents/에 두고 버전 관리에 포함하면 팀 전체가 사용할 수 있습니다. 개인적으로 자주 쓰는 것은 ~/.claude/agents/에 둡니다. 두 폴더 모두 하위 폴더까지 탐색하지만, subagent의 식별은 name 필드만으로 이루어지며 어느 하위 폴더에 있는지는 상관이 없습니다.

파일 모양

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

frontmatter는 설정을 담당하고, 그 아래의 본문이 이 subagent의 system prompt가 됩니다. name과 description만 필수이며, 자주 쓰는 다른 필드는 다음과 같습니다:

/agents는 더 이상 마법사를 열지 않으며, Claude에게 직접 요청

v2.1.197 이전에는 /agents를 실행하면 대화형 생성 마법사가 열렸습니다. v2.1.198부터는 실행하면 Claude에게 직접 생성을 요청하거나 .claude/agents/를 직접 편집하라는 안내만 표시됩니다. 파일 형식과 저장 위치는 바뀌지 않았습니다. 따라서 가장 빠른 방법은 Claude에게 이렇게 말하는 것입니다:

Create a personal code-improver subagent in ~/.claude/agents/ that scans files and suggests improvements. Make it read-only and have it use Sonnet.

파일을 저장하면 몇 초 안에 적용되며 재시작할 필요가 없습니다. 예외는 session이 시작될 때 agents 폴더가 아직 없었던 경우로, 이때는 Claude Code를 다시 시작해야 읽을 수 있습니다. 생성한 뒤에는 세 가지 방식으로 호출할 수 있습니다. prompt에서 이름을 직접 지정하면(위임 여부는 Claude가 결정합니다), @를 입력해 메뉴에서 고르면(예: @"code-reviewer (agent)" look at the auth changes, 이번에는 반드시 이 subagent를 사용합니다), 또는 claude --agent code-reviewer로 실행하면 session 전체가 해당 subagent의 system prompt, 도구 제한, 모델로 바뀝니다.

병렬 실행

Subagent는 포그라운드와 백그라운드로 나뉩니다. 포그라운드는 완료될 때까지 메인 대화를 멈춥니다. 백그라운드는 동시에 실행될 수 있으며, 권한이 필요한 도구 호출을 만나면 메인 대화에서 질문하고, 어느 subagent가 묻고 있는지도 표시합니다. 대화형 모드에서는 기본적으로 fork mode가 켜져 있어 Claude가 위임한 subagent가 백그라운드에서 실행됩니다. 실행 중인 작업도 Ctrl+B를 눌러 백그라운드로 보낼 수 있습니다.

서로 의존하지 않는 조사라면 여러 개를 한 번에 위임할 수 있습니다:

Research the authentication, database, and API modules in parallel using separate subagents

각 subagent는 자기 몫을 조사하고, 마지막에 Claude가 결과를 통합합니다. 다만 결과는 여전히 메인 대화로 돌아옵니다. 여러 개를 위임하고 각각 긴 결과를 반환하면 역시 context를 많이 소모하므로, 위임할 때 핵심만 보고하도록 요청할 수 있습니다. 동시에 실행되는 개수의 기본 상한은 20개이며, 이를 넘으면 Concurrent subagent limit reached가 표시됩니다. CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS로 조정할 수 있습니다.

v2.1.292부터 Agent 도구에 effort 매개변수가 추가되었습니다. Claude에게 “이 조사는 low effort로 실행해”라고 직접 말하면, 메인 대화의 effort 수준을 따르지 않고 지정한 effort 수준으로 해당 subagent를 시작합니다. 단순 검색이나 자료 정리는 낮춰서 비용을 줄이고, 깊은 추론이 필요한 검토는 높이는 방식으로 활용할 수 있습니다.

언제 사용하고 언제 사용하지 않을지

반복해서 사용하되 메인 대화에서 실행하는 절차가 필요하다면 Skills가 더 적합합니다. 대화에 이미 있는 내용에 대해 질문하고 싶을 뿐이라면 /btw를 사용하면 됩니다.

다음 단계

먼저 읽기 전용 code reviewer를 하나 만들어 봅니다. Claude에게 ~/.claude/agents/에 Read, Grep, Glob 도구만 가진 subagent를 만들어 달라고 요청하고, 코드를 수정한 뒤 @를 입력해 이를 선택하여 review를 받습니다. 보고된 내용이 쓸모 있다고 확인되면, 그다음에 여러 subagent를 한 번에 위임해 병렬로 자료를 조사하는 방법을 시도합니다.

출처: Claude Code 공식 문서 〈Create custom subagents〉의 Built-in subagents, Quickstart: create your first subagent, Configure subagents, Work with subagents 항목(2026-09-15 확인); Claude Code CHANGELOG의 2.1.292, 2.1.296(2026-10-10 확인)

비용 관리와 context 관리

Claude Code를 하루 종일 켜 두고 사용하면 이런 일을 겪게 될 수 있습니다. 질문은 한 줄뿐이었는데 사용량은 생각보다 훨씬 많이 올라갑니다.

원인은 context에 있습니다. context는 대화 노트와 같습니다. 질문을 한 번 할 때마다 Claude Code는 노트 전체를 Claude에게 다시 보여 줍니다. 노트가 두꺼울수록 매번 전달되는 비용도 커집니다. 따라서 비용을 관리한다는 것은 결국 이 노트의 두께를 잘 관리하는 것이라 할 수 있습니다.

먼저 사용량 확인하기

두께를 관리하려면 먼저 지금 얼마나 두꺼운지 알아야 합니다. 공식 문서에서 소개하는 도구는 다음과 같습니다:

/usage 맨 위의 Session 영역은 다음과 같습니다:

Total cost:            $0.55
Total duration (API):  6m 20s
Total duration (wall): 6h 33m 10s
Total code changes:    0 lines added, 0 lines removed
Usage by model:
   claude-sonnet-4-6:  1.2k input, 5.3k output, 940.0k cache read, 50.0k cache write ($0.55)

이 화면에서는 세 가지를 알아 두어야 합니다:

• 금액은 추정치입니다. Claude Code가 token 수에 가격을 곱해 로컬에서 계산한 값입니다. 정확한 청구 금액은 Claude Console의 Usage 페이지를 기준으로 합니다.
• 구독 요금제는 이 금액을 볼 필요가 없습니다. Pro와 Max의 사용량은 구독에 포함되어 있으므로, Session 금액은 청구와 관련이 없습니다. 같은 화면에는 요금제 사용량 막대, 활동 통계, 사용량 세부 내역이 별도로 표시됩니다.
• /clear를 실행하면 0으로 초기화됩니다. /clear는 새 session을 시작하며 금액은 $0부터 다시 계산됩니다. v2.1.211 이전 버전에서는 초기화되지 않고 Claude Code를 종료할 때까지 계속 누적됩니다.

Pro, Max, Team 또는 Enterprise 요금제라면 /usage의 사용량 세부 내역이 더 유용합니다. skills, subagents, plugins 및 각 MCP server가 차지하는 비율을 보여 줍니다. 긴 context, cache miss 같은 동작이 최근 사용량의 10% 이상을 차지하면 이를 표시하고 줄이기 위한 제안도 함께 제공합니다. d 또는 w를 누르면 최근 24시간과 최근 7일 기준으로 전환할 수 있습니다. v2.1.299부터 /usage는 max effort, workflows, 상시 context, 지나치게 큰 도구 결과에 대해서도 경고를 표시합니다. 이 수치는 이 컴퓨터의 session 기록에서만 가져오므로, 다른 기기와 claude.ai의 사용량은 포함되지 않습니다.

context가 소모되는 방식

사용량을 확인한 다음 떠오르는 질문은 “왜 이렇게 많을까?”입니다. 공식 문서는 session을 오래 열어 두면 사용량이 늘어나는 몇 가지 원인을 정리합니다:

첫 번째 항목이 가장 자주 간과됩니다. Claude Code에는 prompt caching이 있어 반복되는 내용은 더 저렴한 캐시 요금으로 읽힙니다. 하지만 어디까지나 저렴할 뿐 무료는 아닙니다. 하루 종일 열어 둔 session에서 한 줄짜리 질문을 해도, 전체 대화에 대한 사용량은 그대로 소모됩니다.

대화 자체 외에도 CLAUDE.md는 session이 시작되자마자 로드됩니다. MCP 도구 정의는 기본적으로 지연 로드되며, Claude가 실제로 특정 도구를 사용하기 전까지는 도구 이름과 server 설명만 context에 포함됩니다.

/clear와 /compact: 새 노트로 바꿀지, 기존 노트를 압축할지

판단 기준은 간단합니다. 앞으로 할 일에 앞선 대화가 필요한가? 필요하지 않다면 /clear를 사용합니다. 공식 문서에 따르면 API 또는 클라우드 요금제의 비용이 비정상적으로 높은 경우는 대개 session을 오랫동안 열어 두고 정리하지 않았기 때문입니다. /clear를 사용하기 전에 /rename으로 session에 이름을 붙여 두면, 나중에 돌아올 때 /resume으로 쉽게 찾을 수 있습니다.

/compact를 사용할 때 뒤에 보존할 내용을 Claude에게 알려 줄 수 있습니다:

/compact Focus on code samples and API usage

프로젝트 루트의 CLAUDE.md에 적어 두면, 요약할 때마다 이 방향을 따르게 할 수도 있습니다:

# Compact instructions

When you are using compact, please focus on test output and code changes

또한 Claude Code는 대화가 context 한도에 가까워지면 compaction을 자동으로 한 번 실행합니다. auto-compact 경고가 보인다고 해서 사용량이 한도에 도달했다는 뜻은 아니며, context가 거의 찼다는 의미입니다.

오래 방치된 긴 대화: idle compaction (v2.1.299부터)

터미널에서 200K token 이상의 대화가 약 54분 동안 유휴 상태이면, Claude Code는 1시간짜리 prompt cache가 만료되기 전에 미리 한 번 압축합니다. 그래서 돌아와서 처음 하는 말에서 전체 context를 다시 처리할 필요가 없습니다.

• 최소 기준은 기본값이 200K token이며, 환경 변수 CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS로 조정할 수 있습니다
• 이 동작을 원하지 않으면 settings.json에 "idleCompaction": false를 작성합니다
• 두 설정 모두 v2.1.290 이후 버전에서만 인식됩니다

알맞은 모델 선택하기

API 또는 클라우드 요금제의 비용이 높은 또 다른 흔한 원인은 Opus를 기본 모델로 계속 사용하는 것입니다. 공식 권장 사항은 대부분의 코딩 작업을 Sonnet에 맡기는 것입니다. Sonnet은 Opus보다 저렴합니다. Opus는 복잡한 아키텍처 결정이나 여러 단계의 추론에 남겨 둡니다.

• 대화 도중 모델 변경: /model
• 기본 모델 설정: /config
• 간단한 subagent 작업: subagent 설정에 model: haiku를 작성

extended thinking도 비용이 듭니다. thinking token은 output token 기준으로 과금되며, 기본 예산은 모델마다 다르므로 한 번의 요청에 수만 token에 이를 수 있습니다. 깊은 추론이 필요 없는 간단한 작업이라면 /effort를 사용하거나 /model에서 effort level을 낮추고, 또는 /config에서 thinking을 끌 수 있습니다. Fable 모델은 extended thinking을 항상 사용하므로 끌 수 없습니다.

token을 줄이는 구체적인 방법

다음 단계

다음에 Claude Code를 열면 먼저 두 가지를 해 봅니다. /context를 입력해 무엇이 context를 차지하고 있는지 확인하고, /model을 입력해 기본 모델이 계속 Opus로 고정되어 있지 않은지 확인합니다. 이후 관련 없는 작업으로 바꿀 때마다 /rename을 한 뒤 /clear를 실행합니다.

출처: Claude Code 공식 문서 〈Manage costs effectively〉의 Track your costs, When a developer asks about a limit, Reduce token usage, Why usage climbs in a long session 항목(2026-09-15 확인); Claude Code CHANGELOG의 2.1.299(2026-10-14 확인)

Session 관리와 Checkpoint 되돌리기

앞 장의 조언대로 작업을 바꾸기 전에 /clear를 실행했다면, 다음 질문이 떠오를 겁니다. 어제의 대화를 오늘 이어서 할 수 있을까?

이어서 할 수 있습니다. Claude Code는 대화를 하나하나 session으로 저장하며, 이는 여러분의 컴퓨터에 놓인 노트와 같습니다. 되돌아가는 방법만 알고 있으면 창을 닫아도 앞선 맥락을 잃을 걱정이 없습니다. 같은 구조를 이용해 과거 상태로 되돌아갈 수도 있습니다. Claude가 파일을 잘못 수정했다면 어느 메시지 이전의 상태로 되돌릴 수 있습니다.

session에 이름 붙이기

이름을 붙이지 않아도 이어서 할 수는 있지만, 목록에는 기계가 만든 제목만 나열되어 어느 대화가 어느 것인지 알아보기 어렵습니다. 이름을 붙이기 좋은 시점은 다음과 같습니다:

claude -n auth-refactor     # name it at startup

/rename auth-refactor

session 선택기에서 커서를 특정 대화로 옮긴 뒤 Ctrl+R을 눌러도 이름을 바꿀 수 있습니다. 또한 plan mode에서 계획을 승인할 때 이 대화에 아직 이름이 없다면, Claude Code가 자동으로 이름을 붙여 줍니다.

이름이 없는 session에는 두 가지 라벨이 붙습니다. 하나는 작업 디렉터리 이름에 두 글자 접미사를 붙인 것으로, 예를 들면 my-app-3f입니다. 이 라벨은 표시용일 뿐이며 이것으로 대화를 이어 갈 수는 없습니다(v2.1.196부터). 다른 하나는 Haiku 같은 모델이 첫 번째 메시지를 보고 만든 제목으로, 이것은 바로 이어 가는 데 사용할 수 있습니다.

이름이 겹치는 경우에도 기존 이름이 사라지지 않습니다. 같은 컴퓨터에서 같은 이름을 사용하는 다른 대화가 아직 실행 중이라면, Claude Code는 원래 대화의 이름을 유지하고 새 대화에는 두 글자 접미사를 붙인 변형 이름을 줍니다. 예를 들면 auth-refactor-graceful-unicorn입니다. 이때 Claude Code는 그 사실을 알려 줍니다.

세 가지 방법으로 이어 가기

--continue는 claude -p나 Agent SDK로 만든 session은 건너뜁니다. 첫 메시지가 /loop인 session도 건너뜁니다. 이미 끝난 백그라운드 session은 v2.1.257 이후에만 이어 갈 수 있습니다.

선택기는 기본적으로 현재 작업 트리와 /add-dir로 추가한 디렉터리만 보여 줍니다. 찾는 대화가 없으면 Ctrl+W로 이 repo의 모든 worktree까지 범위를 넓히고, Ctrl+A로 이 컴퓨터의 모든 프로젝트까지 넓힐 수 있습니다. session ID로 이어 갈 때는 v2.1.223부터 현재 프로젝트와 그 worktree를 먼저 찾고, 없으면 다른 프로젝트를 찾습니다. 그보다 이전 버전은 현재 디렉터리만 찾으므로, 대화를 만들었던 디렉터리로 돌아가야 이어 갈 수 있습니다.

평소에는 쓸 일이 없지만 알아 두면 유용한 옵션이 두 가지 더 있습니다. --session-id는 대화의 ID를 직접 지정할 수 있게 하며, 올바른 UUID 형식이어야 합니다. --fork-session은 이어 가면서 새 session ID를 만들며, 원래 대화는 그대로 둡니다. 같은 출발점에서 다른 방향을 시도하고 싶을 때 적합합니다.

이어 갈 때 복원되는 항목

몇몇 경우에는 모델이 원래대로 유지되지 않습니다. 원래 모델이 더 이상 사용할 수 없는 경우, availableModels가 허용하지 않는 경우, 시작할 때 --model이나 ANTHROPIC_MODEL로 다른 모델을 지정한 경우, 또는 Bedrock, Google Cloud, Microsoft Foundry처럼 배포 ID를 사용하는 플랫폼인 경우입니다.

모든 시작 옵션이 복원되지는 않습니다. 대화가 --mcp-config, --settings, --plugin-dir, --fallback-model에 의존하고 있었거나, --add-dir로 추가한 디렉터리를 사용했다면, 이어 갈 때 직접 다시 지정해야 합니다. 대화 도중 /add-dir로 추가한 디렉터리도 돌아오지 않습니다. settings.json과 settings.local.json 같은 설정 파일은 시작할 때마다 다시 읽습니다.

권한 모드는 7장의 표와 연결됩니다. 터미널에서 bypassPermissions 상태였던 session은 이어 갈 때 새 session의 기본 시작 모드가 됩니다. plan 모드였던 session은 이어 갈 때도 plan 모드를 유지합니다(--fork-session으로 분기한 경우는 예외입니다). auto였던 session은 계정 조건이 여전히 충족되면 auto로 유지됩니다. Manual이었던 session은 이어 갈 때도 Manual이며, 설정 파일의 defaultMode가 따로 지정하지 않는 한 그렇습니다.

원래 대화에서 --agent를 사용했는데 해당 agent를 원래 디렉터리와 현재 디렉터리 모두에서 찾을 수 없다면, Claude Code는 경고를 표시하고 기본 도구로 대화를 이어 갑니다.

또한 실행 중이던 도구 호출은 이어서 실행되지 않습니다. 중단되기 전에 실행 중이던 명령은 다시 실행되지도, 완료되지도 않습니다. Claude는 해당 출력이 없는 상태로 작업을 이어 갑니다.

너무 오래 지나서 이어 갈 때는 압축할지 물어봅니다

Pro와 Max 요금제에서는 1시간 넘게 움직이지 않았고 10만 token을 넘는 대화를 이어 갈 때, 첫 메시지를 보내기 전에 Claude Code가 대화 상자를 띄우고 세 가지 선택지를 제시합니다:

• 요약에서 복원: 즉시 /compact를 한 번 실행하는 것과 같습니다. token 비용은 훨씬 저렴하지만, 요약하면서 빠진 세부 내용은 context에 남지 않습니다.
• 전체 복원: 원래 내용을 그대로 다시 불러옵니다. 이후 모든 요청의 token은 대화의 전체 크기를 기준으로 계산됩니다.
• 다시 묻지 않기: 이번에는 전체 복원하며, 이후에는 이 대화 상자를 띄우지 않습니다.

잘못됐을 때: /rewind로 되돌리기

메시지를 보내고 새 차례가 시작될 때마다 Claude Code는 checkpoint를 하나 저장합니다. 되돌리고 싶다면 /rewind를 입력하거나, 입력창이 비어 있을 때 Esc를 두 번 누릅니다. 입력창에 글자가 있을 때 Esc를 두 번 누르면 입력이 지워지며, 지워진 글자는 입력 기록에 남아 Up으로 다시 불러올 수 있습니다.

선택 메뉴에는 여섯 가지 항목이 있습니다:

해당 checkpoint에서 추적된 파일 변경이 없다면, 메뉴에는 Restore conversation, 두 가지 요약 항목, Never mind만 표시됩니다.

요약은 디스크의 파일을 변경하지 않으며, 원래 메시지도 기록에 그대로 남습니다. 요약할 때 중점을 지정하고 싶다면, 커서를 Summarize 항목으로 옮긴 뒤 바로 입력하고 Enter를 누릅니다. 숫자 키로 선택하면 지시 없이 바로 요약합니다.

비상용 진입점도 있습니다. 같은 Claude Code 프로세스에서 이전에 /clear를 실행했다면, rewind 메뉴 맨 위에 /resume <session-id> (previous session) 항목이 추가됩니다. 이 항목을 선택하면 /clear 이전의 대화로 돌아갈 수 있습니다. 이 항목은 Claude Code를 종료하거나 다른 session에 연결하기 전까지만 유효하며, v2.1.191 이상이 필요합니다.

checkpoint로 되돌릴 수 없는 것

이 부분을 먼저 알아 두어야 checkpoint를 만능 복원 지점으로 오해하지 않습니다:

• Bash 명령으로 바뀐 파일은 포함되지 않습니다. Claude가 rm, mv, cp로 건드린 파일은 rewind로 되돌릴 수 없습니다. Claude의 파일 편집 도구로 직접 수정한 것만 추적됩니다.
• Subagent가 바꾼 파일은 보통 되돌릴 수 없습니다. context: fork이면서 포그라운드에서 실행되는 skill만 편집 내용이 그 차례 안에서 이루어져 rewind로 되돌릴 수 있습니다. 그 밖의 subagent(기본적으로 백그라운드에서 실행되는 fork skill, 백그라운드의 /code-review --fix 포함)가 바꾼 파일은 git으로 복원해야 합니다.
• 외부 변경은 포함되지 않습니다. Claude Code 바깥에서 직접 수정한 내용, 다른 대화가 동시에 수정한 내용은 보통 기록되지 않습니다.
• 끼어들어 보낸 메시지에는 checkpoint가 없습니다. Claude가 작업하는 도중에 끼워 넣은 메시지는 당시 차례에 합쳐지므로 메뉴에 나타나지 않습니다. 되돌리고 싶다면 그 차례를 연 프롬프트까지 되돌려야 하며, 그러면 해당 차례 전체가 함께 되돌려집니다.
• Symlink와 하드 링크는 건너뜁니다. Restore code를 선택하면 이런 경로는 건너뛰고 Restored the code, but skipped N files를 표시하며, 해당 파일은 현재 내용을 유지합니다. 어떤 파일을 건너뛰었는지 알고 싶다면 먼저 /debug로 디버그 기록을 켜십시오. 기록은 ~/.claude/debug/<session-id>.txt에 저장됩니다.

공식 문서도 분명히 말합니다. checkpoint는 같은 대화 안에서 빠르게 복원하기 위해 설계된 기능이며, 장기적인 버전 이력과 협업은 git에 맡겨야 합니다. 따라서 크게 바꾸는 작업이라면 시작하기 전에 먼저 commit하고, rewind는 같은 대화에서 생긴 작은 실수를 되돌리는 데 사용합니다.

저장 위치와 보관 기간

대화 기록은 기본적으로 ~/.claude/projects/<프로젝트>/<session-id>.jsonl에 저장됩니다. <프로젝트>는 작업 디렉터리 경로에서 영문자와 숫자가 아닌 문자를 모두 -로 바꾼 이름입니다. 각 줄은 JSON 객체이지만 이는 내부 형식이며 버전에 따라 바뀔 수 있습니다. 내보내려면 /export를 사용하고, 직접 파싱하는 코드를 작성하지 마십시오.

Checkpoint의 파일 스냅샷은 최근 100개까지 보관되며, 위에서 설명한 30일 보존 기간에 따라 함께 삭제됩니다. 스냅샷이 삭제된 뒤에 rewind를 실행하면 실패하고 No files were restored가 표시됩니다. 더 오래 보관해야 한다면 cleanupPeriodDays 값을 늘리십시오.

다음 단계

다음번에 작업을 시작하기 전에 한 가지만 해 봅니다. claude -n <작업 이름>으로 시작하거나, 들어간 뒤 바로 /rename을 실행합니다. 그래야 내일 claude --resume을 실행했을 때 어느 대화가 어느 것인지 알아볼 수 있습니다. 그다음 되돌리고 싶은 실수가 생기면 Esc를 두 번 눌러, rewind의 여섯 가지 항목을 한 번 살펴봅니다. 어떤 항목이 대화만 되돌리고 어떤 항목이 파일까지 함께 되돌리는지 알아 두면, 실제로 필요할 때 당황하지 않습니다.

출처: Claude Code 공식 문서 〈Sessions〉의 Resume a session, What a resumed session restores, Permission mode on resume, Resume from a summary, Name your sessions, Where transcripts are stored, Where the session picker looks 항목, 그리고 〈Checkpointing〉의 Automatic tracking, Rewind and summarize, Rewind past a cleared conversation, How checkpoints work, Limitations, Not a replacement for version control 항목(2026-09-18 확인)(2026-10-15 〈Manage sessions〉의 Permission mode on resume 항목과도 대조해 갱신했습니다.)

Plugins와 Marketplace

9장과 10장에서 skill과 subagent를 작성하고 나면 다음 문제가 생깁니다. 이 파일들은 모두 ~/.claude/ 아래에 흩어져 있어서, 컴퓨터를 바꾸거나 동료와 공유하려면 폴더를 하나씩 복사해야 합니다.

Plugin은 이것들을 하나로 묶는 방식입니다. Plugin은 독립적으로 옮겨 쓸 수 있는 패키지이며, 그 안에 skill, subagent, hook, MCP server, 기본 설정을 함께 담을 수 있습니다. marketplace는 이런 패키지를 모아 둔 목록으로, 출처 하나를 지정하면 그 안에서 설치할 항목을 고를 수 있습니다.

plugin에 담을 수 있는 것

plugin 루트 아래 다음 위치에 각 기능을 둡니다:

plugin 안의 skill에는 접두사가 붙어 /<plugin 이름>:<skill 이름> 형태로 부릅니다. plugin에 skill이 하나뿐이라면 skills/ 폴더를 만들지 않고 SKILL.md를 루트에 바로 둘 수도 있습니다.

다른 사람의 plugin 설치하기

/plugin을 입력하면 Discover, Installed, Marketplaces, Errors, Stats 탭이 있는 패널이 열리며, 클릭해서 사용할 수 있습니다. 명령어를 선호한다면 다음과 같습니다:

/plugin install github@claude-plugins-official   # install from a marketplace
/plugin list --enabled                           # what is on right now
/plugin disable <name>@<marketplace>             # turn it off, keep it installed
/plugin uninstall <name>@<marketplace>

공식 marketplace 이름은 claude-plugins-official이며, Anthropic이 관리합니다. 대화형 모드를 처음 시작할 때 자동으로 등록됩니다. 자동으로 설치되지 않았다면 직접 추가합니다:

/plugin marketplace add anthropics/claude-plugins-official
/plugin marketplace add anthropics/claude-plugins-community   # community one, add it yourself

marketplace의 출처는 GitHub의 owner/repo, Git URL, 원격 URL, 또는 로컬 경로가 될 수 있습니다. 또한 /plugin marketplace list, update <이름>, remove <이름>으로 관리할 수 있습니다.

어떤 디렉터리에서 처음 plugin을 설치하면 Claude Code가 그 디렉터리를 신뢰하는지 묻습니다. git repo에서 한 번 승인하면 repo 전체에 적용됩니다.

여기서는 조금 보수적으로 접근하는 것이 좋습니다. plugin은 hook과 MCP server를 함께 담을 수 있으므로, 설치하는 순간 여러분의 컴퓨터에서 명령이 실행될 수 있습니다. 설치하기 전에 출처를 확인하십시오. 공식 marketplace나 많은 사람이 사용해 검증된 plugin은 비교적 안전합니다. 방금 공개되었고 사용자가 많지 않은 plugin이라면, hooks/와 .mcp.json을 열어 확인한 뒤 결정합니다.

v2.1.271 이후 설치 과정의 보안이 강화되었으며, 다음 내용을 알아 두면 좋습니다:

• npm 출처의 plugin은 더 이상 설치 스크립트를 실행하지 않습니다. 대신 npm pack --ignore-scripts로 내려받은 뒤 무결성을 검증하므로, 패키지 안의 postinstall은 여러분의 컴퓨터에서 실행되지 않습니다.
• --marketplace로 한 번에 설치할 수 있습니다. /plugin install <plugin> --marketplace <출처>를 사용하면, 아직 추가되지 않은 marketplace는 추가할지 먼저 묻습니다. 따로 두 단계로 나눌 필요가 없습니다. v2.1.292부터는 명령줄의 claude plugin install --marketplace <출처>도 지원합니다. 필요하면 marketplace를 먼저 추가하며(claude plugin marketplace add와 같은 정책 검사를 거칩니다), 그다음 그 안에서 plugin을 설치합니다.
• 설치할 때 설정을 함께 입력합니다. claude plugin configure <plugin>은 plugin의 옵션과 아직 설정하지 않은 항목을 보여 줍니다. --values-stdin을 추가하면 표준 입력으로 새 값을 저장할 수 있습니다(v2.1.285부터). claude plugin install --config에서는 <server>.<key>=<value> 형식으로 plugin에 포함된 .mcpb MCP server의 매개변수를 설정할 수 있으므로, 설치한 뒤에 /plugin에서 Configure를 따로 열 필요가 없습니다.
• CI에서는 -y를 사용하지 마십시오. claude plugin install과 claude plugin update는 --accept-command <sha256>를 지원합니다. 이 옵션은 앞서 --json으로 표시된 명령만 허용하며, 내용이 바뀌면 통과하지 못합니다. 자동화 작업에 검증 절차를 하나 더 두는 셈입니다.
• claude.ai 계정에서 활성화한 plugin은 터미널에 동기화됩니다. 9장의 skill 동기화와 같은 방식이며, "syncClaudeAiPlugins": false로 끌 수 있습니다.

plugin 내용을 수정한 뒤에는 재시작하지 않아도 됩니다:

/reload-plugins            # apply changes in the current session
/reload-plugins --force    # when the cache needs rebuilding too

직접 패키지 만들기

디렉터리 구조는 다음과 같습니다:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── hello/
│       └── SKILL.md
├── agents/
├── hooks/
│   └── hooks.json
└── .mcp.json

plugin.json은 선택 파일입니다. 없으면 Claude Code가 표준 위치에서 찾을 수 있는 구성 요소를 그대로 불러옵니다. 작성하는 경우 name만 필수이며, 나머지 필드는 채워 두는 것을 권장합니다. 조금 더 완전한 예시는 다음과 같습니다:

{
  "name": "my-plugin",
  "description": "What this plugin does",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

version을 생략하면 git SHA가 버전으로 사용됩니다. name은 skill의 접두사로도 쓰이므로 짧게 짓는 것이 좋습니다.

개발 과정에서는 배포하지 않고 로컬 폴더를 바로 가리켜 테스트할 수 있습니다:

claude --plugin-dir ./my-plugin     # load one plugin for this session
claude --plugin-dir ./plugins       # v2.1.265+: load every plugin in the folder
claude plugin validate ./my-plugin  # check the structure and schema

폴더를 가리키면 Claude Code는 먼저 그 층에 plugin 구성 요소가 있는지 확인합니다. 없으면 이 폴더를 “여러 plugin을 담은 폴더”로 보고, .claude-plugin/plugin.json을 가진 하위 폴더마다 하나의 plugin으로 계산합니다.

claude plugin eval로 검증하기

skill과 hook을 작성한 뒤 가장 어려운 점은 그것이 실제로 Claude의 성능을 높이는지 판단하는 것입니다. claude plugin eval은 이 작업을 합니다. 테스트 케이스 묶음으로 plugin을 실행하며, 각 케이스는 기본적으로 세 번씩 실행됩니다. 또한 plugin을 설치하지 않은 대조군도 한 차례 실행하고, 마지막에 두 결과의 차이를 보고합니다. v2.1.269 이상이 필요합니다.

claude plugin eval init                        # interview, writes cases and graders
claude plugin eval .                           # run every case
claude plugin eval . --runs 1 --ablation none  # single arm, cheaper
claude plugin eval . --trust-plugin            # for CI, skips the trust prompt

케이스는 evals/<케이스 이름>/ 아래에 두며, 그 안의 prompt.md에 프롬프트를 작성하고 graders/ 아래에는 파일 하나당 평가기 하나를 둡니다. 평가기는 여섯 가지 종류가 있습니다:

실행이 끝나면 evals/results/<타임스탬프>/ 아래에 aggregate-result.json과 report.html이 생성됩니다. 종료 코드는 CI에 바로 연결할 수 있습니다. 0은 모든 기준 통과, 1은 기준 미달 또는 신뢰 프롬프트 거부, 2는 일부만 실행됨(예: 비용 상한 도달, 인증 실패)을 뜻합니다.

다음 사항을 미리 알아 두십시오. 모든 eval 실행과 모든 평가 모델 호출에는 비용이 발생합니다. eval은 격리된 환경에서 실행되므로 개인 설정, 다른 plugin, 메모리, MCP server는 로드되지 않으며, 측정되는 것은 해당 plugin 자체의 효과입니다.

다음 단계

먼저 하나를 설치해 보십시오. /plugin을 입력해 공식 marketplace에서 매일 사용할 만한 것(예: GitHub 관련)을 고르고, 일주일 정도 사용해 봅니다. 잘 맞는다고 판단되면 두 번째를 추가합니다. ~/.claude/skills/에 자주 쓰는 skill이 두세 개 쌓이면, 이를 plugin 폴더로 옮긴 뒤 claude --plugin-dir로 로컬에서 테스트합니다. 그다음 다른 사람에게도 제공할지 marketplace에 올릴지 결정합니다.

출처: Claude Code 공식 문서 〈Create plugins〉의 Create your first plugin 항목, 〈Discover and install prebuilt plugins〉의 설치와 marketplace 항목, 그리고 〈Test plugins with evals〉의 Requirements, Graders, Run evals 항목(2026-09-18 확인). 설치 보안 항목의 내용은 Claude Code CHANGELOG의 2.1.271과 2.1.275(2026-09-19 확인)에서 가져왔습니다. Claude Code CHANGELOG의 2.1.285(2026-10-02 확인), 2.1.292(2026-10-07 확인)(2026-10-15 〈Plugins reference〉의 Manifest 항목과도 대조해 갱신했습니다.)

모델, Effort 수준, Fast mode

앞 장에서는 plugin으로 도구를 묶는 방법을 설명했습니다. 그러나 도구가 아무리 갖춰져 있어도 답변의 품질과 청구 금액을 결정하는 것은 결국 두 가지입니다. 어떤 모델을 쓰는지, 그리고 그 모델이 얼마나 오래 생각하도록 하는지입니다.

Claude Code는 이 두 가지를 분리해 둡니다. 모델은 기본 역량을 결정하고, effort 수준은 답하기 전에 얼마나 열심히 생각할지를 결정합니다. 이 둘을 이해하는 것이 Opus와 Sonnet 사이에서 고민하는 것보다 훨씬 유용합니다.

현재 사용할 수 있는 모델

전체 model ID를 외울 필요는 없고 별칭만 기억하면 됩니다. default, best, fable, opus, sonnet, haiku, opusplan이 있으며, 긴 context 버전으로 sonnet[1m]과 opus[1m]도 있습니다.

별칭이 실제로 어떤 모델을 가리키는지는 사용하는 플랫폼에 따라 다릅니다:

fable은 플랫폼별 대응표가 없으며, 기본적으로 Fable 5.1을 가리킵니다. Claude apps gateway session만 Fable 5를 가리킵니다.

기본 모델은 요금제와 플랫폼에 따라 다릅니다. Pro, Max, Team, Enterprise, Anthropic API, 그리고 Claude Platform on AWS, Amazon Bedrock, Google Cloud Agent Platform은 기본값이 모두 Opus 5.5입니다. Microsoft Foundry의 기본값은 Sonnet 4.5입니다. Fable은 어떤 요금제나 플랫폼에서도 기본값이 아닙니다. v2.1.280부터 Pro와 Team Standard의 기본값도 Sonnet에서 Opus로 바뀌었습니다. 현재 가장 최신 모델은 Opus 5.5(claude-opus-5-5, v2.1.280)와 Sonnet 5.5(claude-sonnet-5-5, v2.1.284)이며, 둘 다 1M context를 지원합니다. API 가격은 백만 token당 Opus 5.5가 입력 $4, 출력 $20이며, Sonnet 5.5는 입력 $2, 출력 $10입니다.

또한 v2.1.285부터는 사용자 지정 ANTHROPIC_BASE_URL로 연결한 session이 1M 창을 지원하는 모델(Opus 4.7 이상, Sonnet 5 이상, Fable)의 긴 context를 바로 사용합니다. gateway가 200K까지만 지원한다면 /autocompact 200k를 입력하십시오. Bedrock, Vertex, Foundry, Claude apps gateway에서는 v2.1.287부터 Opus 4.7 이상과 Fable도 [1m]을 붙이지 않아도 기본으로 1M을 사용합니다. 200K에 머물고 싶다면 CLAUDE_CODE_DISABLE_1M_CONTEXT=1을 설정합니다. 또한 v2.1.288부터 /autocompact 설정은 모델별로 따로 저장되므로, 모델을 바꿔도 서로 덮어쓰지 않습니다.

경량 Haiku도 업데이트되었습니다. v2.1.293부터 Anthropic API에서 haiku 별칭은 Haiku 5.5(claude-haiku-5-5)를 가리키며, 1M context를 지원합니다. 가격은 백만 token당 입력 $0.10, 출력 $0.50입니다. prompt가 100K token을 넘는 요청은 그 한 번의 요청 전체가 $0.50/$2.50으로 과금되며, 넘은 부분만 그렇게 계산되지는 않습니다. 길이를 판단할 때는 캐시 읽기와 쓰기 token도 포함합니다.

모델을 바꾸는 방법은 가까운 것부터 먼 순서로 다음과 같습니다. /model <별칭>은 이번 대화에만 적용됩니다. claude --model <별칭>은 시작할 때 지정합니다. 환경 변수 ANTHROPIC_MODEL, settings.json의 model, 마지막으로 ANTHROPIC_DEFAULT_MODEL(v2.1.236부터, 새 대화의 기본값에만 영향을 줍니다)이 있습니다.

opusplan 별칭은 기억해 둘 만합니다. 계획 단계에서는 Opus를 쓰고, 구현 단계로 넘어가면 Sonnet으로 바꿉니다. 먼저 생각을 정리한 뒤 작업하는 경우에 적합합니다.

Effort 수준: 얼마나 오래 생각하게 할지

같은 모델이라도 생각하는 강도를 조절할 수 있습니다:

대부분의 모델은 기본값이 high지만, **Opus 5.5, Sonnet 5.5, Haiku 5.5는 기본값이 medium**이고, Opus 4.7은 기본값이 xhigh입니다. 전환 방법은 다음과 같습니다:

claude --effort xhigh                  # at startup
export CLAUDE_CODE_EFFORT_LEVEL=medium # environment variable

/effort          # interactive slider
/effort high     # set it directly

설정 파일에서는 effortLevel(기본값), modelSettings(모델별로 기억하는 수준), maxEffortLevel(상한)에 해당합니다.

생각하는 과정 자체에도 비용이 듭니다. thinking token은 output token 기준으로 과금됩니다. 따라서 간단한 작업은 low나 medium으로 낮추는 것이 항상 high를 쓰는 것보다 저렴하고 빠릅니다. extended thinking을 완전히 끄고 싶다면 MAX_THINKING_TOKENS=0을 설정하면 됩니다. 다만 Opus 5.5, Sonnet 5.5, Haiku 5.5와 Fable은 예외이며, 이 모델들은 thinking을 끌 수 없습니다(/config에 Thinking can't be turned off가 표시됩니다).

ultracode는 effort 수준이 아니라, Claude가 dynamic workflow를 사용해 많은 subagent를 자동으로 조율하도록 하는 스위치입니다. v2.1.284부터는 /effort에서 독립된 스위치로 제공됩니다(Tab을 누르거나 /effort ultracode on / off를 입력합니다). 더 이상 xhigh를 강제하지 않으며, 어떤 effort 수준에서도 켜 둘 수 있습니다. 다음 장에서 자세히 다룹니다.

또한 v2.1.280부터 /effort는 모델마다 각자의 수준을 기억합니다. 이전 버전에서 저장된 수준은 Opus 5.5처럼 새로 출시된 모델에는 적용되지 않으며, 이 모델들은 기본 수준에서 시작하므로 직접 다시 선택해야 합니다.

Fast mode: 같은 Opus, 2.5배 빠름

Fast mode는 모델을 바꾸는 것이 아니라, 같은 Opus를 다른 API 설정으로 실행해 속도를 비용보다 앞세우는 기능입니다. 응답은 최대 2.5배까지 빨라질 수 있습니다. Opus 5.5, Opus 5, Opus 4.8을 지원하며, Sonnet과 Haiku는 지원하지 않습니다. v2.1.280부터 기본값은 Opus 5.5입니다. Opus 4.7의 fast mode는 2026년 7월 24일에 제거되었습니다. 현재 연구 미리보기 단계이므로 기능, 가격, 제공 범위는 바뀔 수 있습니다.

가격은 백만 token당 Opus 5.5가 입력 $8, 출력 $40이며, Opus 5와 Opus 4.8은 입력 $10, 출력 $50입니다. 주의할 점은 켜는 순간 대화 전체 context가 캐시되지 않은 가격으로 한 번 입력 처리된다는 것입니다. 따라서 켤 거라면 대화를 시작할 때 켜고, 대화 도중에 켜면 비용이 더 많이 듭니다.

/fast        # toggle
/fast on     # in a cloud session

설정 파일의 fastMode는 기본적으로 켜 둘지 여부를 정하고, fastModePerSessionOptIn을 설정하면 매 대화마다 수동으로 켜도록 요구할 수 있습니다(v2.1.257부터).

Pro와 Max는 Settings의 Usage에서 사용량 한도를 먼저 켜야 하며, Team과 Enterprise는 소유자가 Admin Settings에서 켜야 합니다. Bedrock, Google Cloud Agent Platform, Microsoft Foundry, Claude Platform on AWS에서는 지원되지 않습니다.

모델 장애 시 대체 모델

주 모델이 과부하 상태이거나 일시적으로 사용할 수 없거나, 재시도하기에 적합하지 않은 서버 오류가 발생하면, 다른 모델이 자동으로 대신 처리하도록 설정할 수 있습니다:

claude --fallback-model sonnet,haiku

{ "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"] }

대체 체인은 최대 세 개의 모델까지 설정할 수 있습니다. 전환은 그 순간의 한 차례에만 적용되며, subagent에도 같이 적용됩니다. 인증, 청구, 요청 한도 초과, 요청 크기 초과 같은 오류는 대체 모델이 있어도 해결되지 않으므로 대체 모델이 실행되지 않습니다.

또 다른 방식으로는 내용에 따라 자동으로 전환하는 기능이 있습니다. Fable 5.1, Fable 5, Opus 5.5는 생물학 관련 내용이 감지되면 Opus 5로, 보안 관련 내용이 감지되면 Opus 4.8로 넘어갑니다. Sonnet 5.5는 보안 관련 내용이면 Sonnet 5로 넘어가며, 생물학 관련 내용이면 바로 거부합니다. Opus 5는 보안 관련 내용이면 Opus 4.8로 넘어가며, 생물학 관련 내용이면 마찬가지로 거부합니다. 이 동작을 원하지 않으면 /config에서 모델 전환 항목을 끄거나, "switchModelsOnFlag": false를 설정합니다.

비용을 아끼는 설정 방법

평소에는 기본 모델을 그대로 두면 되며, 자주 바꿀 필요는 없습니다. 정말로 신중하게 생각해야 하는 작업(아키텍처, 찾기 어려운 bug)에서만 opusplan으로 바꾸거나 effort를 xhigh로 올립니다. 문구를 고치거나 테스트를 돌리는 정도의 작업은 medium으로 낮춥니다. 이렇게 하면 절약되는 것은 시간이면서 동시에 비용입니다. Fast mode는 시간이 급할 때 적합하며, 대화 시작 시점에 켜야 합니다. 도중에 켜면 비용이 더 듭니다.

다음 단계

지금 한 번 점검해 보십시오. /model을 입력해 현재 모델이 무엇인지 확인하고, /effort를 입력해 현재 수준이 어디에 있는지 확인합니다. 그다음 오늘 한 작은 작업을 하나 골라 effort를 medium으로 낮춰 다시 실행하고, 결과가 나빠졌는지 비교합니다. 높은 effort가 필요 없는 작업은 낮출 수 있으며, 그러면 /context와 청구 금액 모두 더 나아집니다.

출처: Claude Code 공식 문서 〈Model configuration〉의 Model Aliases, Model Resolution by Provider, Effort Levels, Fallback Model Chains, Automatic Model Fallback 항목, 〈Fast mode〉 전문, 가격 페이지(2026-10-15 확인); Claude Code CHANGELOG의 2.1.280, 2.1.284, 2.1.285, 2.1.287(2026-10-02 확인), 2.1.288(2026-10-03 확인), 2.1.293(2026-10-08 확인)

Worktrees와 여러 session 동시 작업

10장의 subagent는 “한 가지 일을 여러 단계로 나누는” 문제를 해결합니다. 하지만 서로 무관한 두 가지 작업을 동시에 맡고 있다면, 예를 들어 한쪽에서는 로그인 흐름을 고치고 다른 쪽에서는 CI를 수정하면서 창 두 개에 각각 Claude Code를 실행하면, 두 session이 같은 작업 디렉터리를 수정하게 되어 작업 도중에 서로 충돌합니다.

Git worktree는 원래부터 있던 해법입니다. 같은 repo에서 작업 디렉터리를 여러 개 열고, 각 디렉터리가 자기 브랜치에 머무르며, 히스토리와 원격은 공유합니다. Claude Code는 이 기능을 연동했습니다. 대화마다 자신의 worktree에 머물 수 있어, 서로의 파일이 충돌하지 않습니다.

worktree를 열어 작업하기

claude --worktree auth-refactor   # create a named worktree and start there
claude -w auth-refactor           # same thing, short form
claude --worktree                 # no name: one is generated, e.g. bright-running-fox
claude --worktree "#1234"         # branch from a PR

기본적으로 repo 루트의 .claude/worktrees/<이름>/에 생성되며, 브랜치 이름은 worktree-<이름>입니다. 이 폴더는 .gitignore에 추가해야 합니다.

이미 대화 중이고 격리가 필요해졌다면, Claude에게 직접 요청해 worktree를 만들 수도 있습니다. Claude는 EnterWorktree로 생성합니다. 현재 어떤 worktree가 있는지 확인하거나 수동으로 정리하려면 기존 git 명령어를 사용합니다:

git worktree list
git worktree remove <path>

어느 브랜치에서 분기하고, 어떻게 정리하는지

기본값은 기본 브랜치에서 새로 분기하는 것입니다. 현재 HEAD에서 분기하려면 설정을 변경하세요:

{ "worktree": { "baseRef": "head" } }

세션을 종료할 때, 변경 사항이 없고 이름이 없는 worktree는 자동으로 제거됩니다. 이름이 있거나 변경 사항이 있는 경우에는 보관할지 삭제할지 묻습니다. claude -p와 같은 비대화형 모드에서는 정리가 수행되지 않으므로 git worktree remove를 직접 실행해야 합니다. subagent와 백그라운드 session이 사용한 worktree는 cleanupPeriodDays 설정에 따라 주기적으로 정리됩니다.

또 하나 유용한 파일은 .worktreeinclude입니다. worktree는 새로운 작업 디렉터리이므로 git이 무시하는 파일은 함께 복사되지 않아, .env 같은 파일이 보이지 않게 됩니다. .gitignore 문법으로 이런 파일을 나열해 두면, 새 worktree를 만들 때마다 복사됩니다:

.env
.env.local
config/secrets.json

worktree 안의 session을 다시 연결하려면 v2.1.212 이상이 필요합니다. 이전 버전에서는 트랜스크립트 위치 추적에 문제가 있습니다.

agent view로 모든 session 보기

여러 대화를 동시에 실행하다 보면 다음 질문이 생깁니다. 어느 대화가 끝났고, 어느 대화가 답변을 기다리고 있는가?

claude agents              # full-screen dashboard
claude agents --cwd <path> # only sessions under this directory
claude agents --json       # for scripts

화면에서 각 대화 앞에는 상태 기호가 표시되며, 기호의 모양은 process 상태를 나타냅니다. ✻ 또는 애니메이션 ✽는 session이 실행 중이거나 입력을 기다리는 상태이고, ∙는 process가 종료된 상태입니다(답변하거나 attach하면 저장된 대화에서 다시 시작됩니다). ✢는 /loop가 실행 사이에 휴면 중임을 나타냅니다(실행 횟수와 카운트다운이 표시됩니다). 완료, 실패, 중지는 색으로 구분합니다. 초록색은 완료, 빨간색은 실패, 회색은 중지됨, 노란색은 입력 대기이며, 아이콘이 흐리게 보이면 유휴 상태입니다. 자주 쓰는 키는 다음과 같습니다. Enter 또는 →는 해당 대화로 들어가고, Space는 미리보기를 켜고 끄며, Ctrl+R은 이름 변경, Ctrl+X는 중지(한 번 더 누르면 삭제), Ctrl+S는 그룹화 방식 전환, ?는 전체 단축키 보기입니다.

화면에 들어가지 않고도 대응하는 명령어를 사용할 수 있습니다:

claude attach <id>     # open that session in this terminal
claude logs <id>       # print its recent output
claude stop <id>       # stop it
claude rm <id>         # remove it from the list
claude daemon status   # check the supervisor process

v2.1.290부터 claude attach와 claude logs 뒤에는 전체 id 외에 session 이름의 일부만 입력해도 됩니다.

Agent teams: 여러 session 간 협업 조율

한 단계 더 나아가면 agent teams가 있습니다. 대화 하나가 팀 리더 역할을 맡아 작업을 나누고 결과를 취합하며, 나머지 팀원들은 각자 독립된 context를 가지고 서로 직접 메시지를 주고받을 수 있습니다. 이 기능은 기본적으로 꺼져 있으며, 직접 켜야 합니다:

{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }

켜고 나면 자연어로 작업과 원하는 역할을 설명하면, Claude가 팀원을 생성합니다. 작업은 공용 작업 목록에 놓이며, 대기 중, 진행 중, 완료의 세 가지 상태를 가집니다. 의존성을 설정할 수도 있습니다. 앞선 작업이 완료되지 않으면 뒤의 작업은 할당받을 수 없습니다. 파일 잠금은 같은 파일을 동시에 수정하는 것을 막는 데 사용됩니다. 작업과 메일함은 각각 ~/.claude/tasks/{team-name}/과 ~/.claude/teams/{team-name}/inboxes/에 저장됩니다.

팀원을 표시할 위치는 선택할 수 있습니다. 기본값인 in-process는 모두 같은 터미널에서 실행합니다. auto는 tmux 또는 iTerm2 아래에서 창을 자동으로 분할합니다. tmux 또는 iterm2를 직접 지정할 수도 있습니다(iTerm2는 v2.1.186 이상이 필요하며, it2와 iTerm2 Python API도 설치해야 합니다). VS Code 내장 터미널, Windows Terminal, Ghostty에서는 창 분할을 지원하지 않습니다.

제한 사항을 먼저 알아 두세요. /resume과 /rewind로는 팀원을 다시 연결할 수 없으며, 다시 연결된 대화에서는 팀원이 이미 없습니다. claude -p 아래에서 팀원은 일반 subagent로 격하됩니다. 팀원은 다시 팀원을 생성할 수 없습니다. 대화 하나에는 team을 하나만 둘 수 있습니다.

네 가지 병렬 방식, 선택 방법

비용 측면도 미리 염두에 두어야 합니다. subagent의 결과는 메인 대화로 수렴되므로 상대적으로 저렴합니다. 반면 agent teams에서는 각 팀원이 독립된 인스턴스이므로 토큰 사용량이 눈에 띄게 많아집니다.

다음 단계

다음에 동시에 두 가지 작업을 해야 할 때는, 두 번째 작업을 새 창에서 열지 말고 claude -w <이름>으로 worktree를 개설해 그 안에서 작업하세요. 먼저 .claude/worktrees/를 .gitignore에 추가하고, .worktreeinclude에 .env를 나열하는 것을 잊지 마세요. 두 작업이 모두 실행되면 다른 터미널을 열어 claude agents를 입력하고, 상태 기호를 보며 어느 쪽에 먼저 답할지 결정하세요.

출처: Claude Code 공식 문서 〈Run parallel sessions with worktrees〉의 Start Claude in a worktree, Customize worktree creation, Copy gitignored files into worktrees, Clean up worktrees 섹션, 〈Agent View〉의 Opening Agent View, Key Commands, State Icons, Keyboard Shortcuts 섹션, 그리고 〈Orchestrate teams of Claude Code sessions〉의 Enable agent teams, Assign and claim tasks, Choose a display mode, Compare with subagents, Limitations 섹션（2026-09-18 확인），그리고 Claude Code 변경 로그의 2.1.290（2026-10-06 확인）（2026-10-15 〈Agent view〉의 Read session state를 추가로 대조하여 상태 기호를 업데이트함.）

자동화: headless 모드, CI 및 예약 실행

앞에서는 여러분이 터미널 앞에 앉아 한 마디씩 대화하는 방식을 다뤘습니다. 하지만 사용자가 자리에 없어도 되는 작업도 있습니다. 매일 아침 전날의 issue를 정리하거나, PR을 열 때마다 review를 자동으로 한 차례 실행하거나, 고정된 검사를 CI에 예약해 두는 경우입니다.

이번 장에서는 Claude Code를 대화형 도구에서 호출 가능한 프로그램으로 바꾸는 방법을 다룹니다. 즉 사람이 상호작용하지 않는 상태에서 실행하는 방법, GitHub에 연동하는 방법, 시간을 정해 자동으로 실행하는 방법입니다.

headless 모드: claude -p

-p(또는 --print)를 붙이면 대화형 인터페이스에 들어가지 않고, 실행이 끝나면 결과를 바로 출력합니다. 성공하면 0을, 실패하면 0이 아닌 값을 반환하므로 shell script에 바로 연결할 수 있습니다.

claude -p "summarise today's git log" --output-format json
cat error.log | claude -p "what failed here?"   # stdin, up to 10MB

--output-format에는 text(기본값), json, stream-json 세 가지가 있습니다. 출력 형식을 고정하려면 --output-format json과 함께 --json-schema를 사용할 수 있습니다.

권한과 관련해서는 특히 주의해야 합니다. -p에서는 아무도 동의를 누를 수 없고, 권한 모드를 지정하지 않으면 내장된 시작 모드로 실행됩니다(auto일 수 있음). 그러므로 명시적으로 지정하는 것이 좋습니다. 미리 권한을 허용하거나, 묻지 말라고 명시하세요:

claude -p "run the tests" --allowedTools "Read,Bash"   # pre-approve
claude -p "..." --permission-mode dontAsk               # no prompts
claude -p "..." --permission-prompts none               # refuse everything that needs asking

CI를 더 빠르고 안정적으로 만드는 옵션도 있습니다. --bare입니다. 이 옵션은 hook, skill, 사용자 지정 명령, subagent, plugin, MCP server, auto memory, CLAUDE.md의 자동 로드를 모두 건너뜁니다. 즉 깨끗한 환경을 제공하므로 어느 머신에서 실행하든 결과가 같습니다. 다만 bare 모드에서는 OAuth 로그인과 시스템 키체인을 읽지 않으므로 ANTHROPIC_API_KEY를 직접 설정해야 합니다.

실행을 마치고 종료할 때: claude -p는 백그라운드 작업이 끝날 때까지 기다린 뒤 종료합니다. 메인 대화에서 시작한 백그라운드 명령(예: dev server)은 해당 명령이 끝나거나 시간 제한에 도달할 때까지 기다리고, subagent와 workflow는 결과가 최종 출력에 포함되므로 완료될 때까지 기다립니다. Monitor 같은 모니터링 및 유휴 대기는 최대 10분 연속으로 기다립니다(CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS로 조정할 수 있으며, 0으로 설정하면 상한이 없습니다). 이전 대화를 이어가려면 --continue와 --resume <session-id>를 -p 아래에서도 똑같이 사용할 수 있습니다.

GitHub Actions에 연결하기

더 빠른 설치 방법은 대화형 모드에서 /install-github-app을 입력하는 것입니다. 이 명령은 GitHub App을 설치하고, 인증에 필요한 secret을 추가한 뒤, workflow 파일을 추가하는 PR을 엽니다. GitHub CLI와 repo 관리 권한이 필요합니다. 수동으로 설치하려면 App을 직접 설치하고, ANTHROPIC_API_KEY 또는 CLAUDE_CODE_OAUTH_TOKEN secret을 추가한 다음, workflow 파일을 직접 복사해 넣으면 됩니다.

workflow는 두 가지 방식으로 실행할 수 있으며, 차이는 prompt를 지정했는지 여부뿐입니다:

• prompt를 지정하지 않음: 대화형 모드. 다른 사람이 issue나 PR에 @claude라고 댓글을 달 때까지 기다렸다가 동작합니다
• prompt를 지정함: 자동 모드. 이벤트가 발생하면 바로 실행하며, 사람을 기다리지 않습니다

누가 트리거할 수 있는지도 제한이 있습니다. 기본적으로 쓰기 권한이 있는 사용자만 가능하며, 그 밖의 사용자는 allowed_non_write_users에 추가해야 합니다. 봇 계정은 allowed_bots에 추가해야 합니다.

클라우드 벤더를 사용한다면 workflow에서 해당 스위치를 사용합니다. Bedrock은 use_bedrock: "true"와 OIDC용 AWS_ROLE_TO_ASSUME을 함께 사용하고, Google Cloud Agent Platform은 use_vertex: "true"와 Workload Identity Federation을 함께 사용하며, Microsoft Foundry는 use_foundry: "true"와 Entra 애플리케이션 변수 세트를 함께 사용합니다.

인증 정보는 예외 없이 GitHub Secrets를 통해 전달하고 파일에 직접 쓰지 마세요. workflow 권한은 필요한 만큼만 부여하세요. Claude가 연 변경 사항도 병합하기 전에 직접 검토해야 합니다.

예약: 정해진 시간에 자동 실행

클라우드 예약 기능은 routines라고 부르며, claude.ai/code/routines에서 만들거나 CLI에서 /schedule로 만들 수 있습니다. Anthropic이 호스팅하는 클라우드 환경(또는 조직이 직접 운영하는 환경)에서 실행되므로 여러분의 컴퓨터가 켜져 있을 필요가 없습니다. 트리거 방식은 세 가지입니다:

일회성 실행은 시간이 되면 자동으로 비활성화됩니다. 이 실행은 다른 예약 실행과 시간당 상한을 공유합니다(계정당 시간당 100회). 시간당 상한에서 제외되지 않습니다. 환경은 기본적으로 패키지 관리자, 클라우드 API 같은 일반적인 도메인을 허용하며, 사용자 지정 도메인을 추가하려면 환경 설정의 Network access에서 변경하세요.

「이 대화 안에서만」 같은 작업을 반복하고 싶다면 클라우드 예약을 만들 필요 없이 /loop를 사용하면 됩니다:

/loop 5m <prompt>   # every five minutes
/loop <prompt>      # Claude picks the interval, between 1 minute and 1 hour

「세 시에 배포를 확인하도록 알려 줘」처럼 말해도 Claude가 알림을 만듭니다. 이런 예약 작업은 7일 후에 만료되며, 대화를 다시 연결하면 만료되지 않은 작업이 함께 돌아오고, 대화가 끝나면 모두 삭제됩니다.

Channels: Telegram 같은 곳에서 작업 전달하기

Channels를 사용하면 Telegram, Discord, iMessage의 메시지를 실행 중인 대화로 보낼 수 있습니다. 즉 외출 중에도 작업을 전달할 수 있습니다. 이 기능은 연구 프리뷰이며 Bun이 필요합니다. Bedrock, Vertex, Foundry는 지원하지 않습니다.

/plugin install telegram@claude-plugins-official
/telegram:configure <token>

그다음 Claude Code를 종료하고 --channels를 붙여 다시 실행해야 bot이 메시지를 받기 시작합니다:

claude --channels plugin:telegram@claude-plugins-official

bot에 메시지를 보내 페어링 코드를 받은 뒤, 돌아와서 페어링하세요:

/telegram:access pair <code>

보안 메커니즘을 정확히 이해해야 합니다. 각 channel에는 고유한 발신자 허용 목록이 있으며, 목록에 있는 ID만 메시지를 보낼 수 있습니다. Telegram과 Discord는 페어링 코드로 사용자를 목록에 추가하고, iMessage는 자기 자신과의 대화를 자동으로 허용하며 다른 연락처는 수동으로 추가합니다. /telegram:access policy allowlist를 사용하면 목록에 있는 사용자만 사용할 수 있도록 잠글 수 있습니다. 목록에 있는 사용자는 원격으로 도구 호출을 승인할 수도 있으므로, 이 목록은 권한 목록으로 취급해야 하며 아무나 추가하지 마세요. Team과 Enterprise에서는 기본적으로 꺼져 있으며, Owner가 관리 콘솔에서 channelsEnabled를 켜야 합니다.

다음 단계

가장 작은 단계부터 시작하세요. 매일 직접 수행하는 점검을 한 줄짜리 claude -p 명령으로 작성하고, --allowedTools로 읽기 권한만 부여한 뒤 출력이 맞는지 실행해 보세요. 안정적으로 동작하는 것이 확인되면, 그다음에 CI에 넣을지 아니면 routine으로 만들어 자동 예약 실행할지 결정하세요. GitHub Actions를 건드리기 전에는 secret이 제대로 설정되었는지, 그리고 workflow 권한을 과도하게 열어 두지 않았는지 먼저 확인하세요.

출처: Claude Code 공식 문서 〈Headless mode〉의 Basic usage, Start faster with bare mode, Get structured output, Auto-approve tools, Background tasks at exit 섹션, 〈GitHub Actions〉의 Setup, Interactive and automation modes, Protect your credentials 섹션, 〈Routines〉의 Add a schedule trigger, Add an API trigger, Add a GitHub trigger, Usage and limits 섹션, 〈Scheduled tasks〉의 /loop 및 Seven-day expiry 섹션, 그리고 〈Channels〉의 Supported channels, Security, Enterprise controls 섹션（2026-09-18 확인）（2026-10-15 〈Headless mode〉, 〈Routines〉, 〈Channels〉를 대조하여 업데이트함.）

Dynamic Workflows와 ultracode

10장의 subagent는 “한 사람을 보내 조사하게 하는” 방식으로, 세다섯 개 정도면 괜찮습니다. 그러나 “500개 파일을 전부 한 번씩 훑기”나 “같은 문제를 여섯 가지 관점에서 각각 조사한 뒤 교차 검증하기”가 필요하다면, 메인 대화가 매 라운드마다 다음 단계를 결정하는 방식으로는 중간 결과가 context를 가득 채우고, 어느 한 곳이라도 잘못되면 처음부터 다시 해야 합니다.

Dynamic workflow는 다른 방식을 사용합니다. Claude가 먼저 JavaScript 스크립트를 작성하고, 이 스크립트가 몇 개의 agent를 보낼지, 누가 먼저 실행되고 누가 나중에 실행될지, 결과를 어떻게 모을지 결정합니다. 스크립트는 백그라운드에서 실행되므로 대화는 계속 사용할 수 있습니다. 중간 결과는 스크립트의 변수에 저장되므로 여러분의 context를 차지하지 않습니다.

workflow와 subagent를 언제 쓸지

수십 개의 agent를 보내야 하고 흐름이 고정된 작업에만 workflow를 사용할 가치가 있습니다.

시작하는 방법

더 간단한 방법은 문장에 ultracode 키워드를 넣는 것입니다. 그러면 Claude가 해당 작업을 위한 workflow 스크립트를 작성합니다. 다른 방법은 다음과 같습니다:

키워드는 실제 사람이 입력했을 때만 트리거됩니다(대화형 입력, IDE 확장, Remote Control, 그리고 Agent SDK에서 { kind: "human" }으로 표시된 입력). -p, webhook, PR 댓글, 예약 작업에 입력하더라도 트리거되지 않습니다(v2.1.210부터 적용). 이는 의도된 설계입니다. 다른 사람이 issue 댓글에 키워드를 넣어 여러분의 자동화가 막대한 토큰을 소모하게 되는 일을 막기 위한 것입니다.

키워드가 강조 표시되었지만 이번에는 사용하지 않으려면 Option+W(macOS) 또는 Alt+W를 눌러 취소하세요. 아예 끄려면 /config에서 Ultracode keyword trigger를 끄세요.

실행하기 전에 Claude가 먼저 계획을 제시합니다. auto 모드에서는 처음에만 묻고, manual 모드에서는 매번 묻고, bypass 모드에서는 묻지 않습니다.

스크립트의 구조

스크립트는 반드시 meta 블록으로 시작해야 하며, 순수한 객체 리터럴이어야 합니다. 여기에는 name과 description이 포함됩니다. 변수나 함수 호출로 작성하면 이 workflow는 / 자동 완성 목록에 나타나지 않습니다.

자주 쓰는 함수는 다섯 가지입니다:

Node에 익숙한 사람이 걸려 넘어질 수 있는 제한이 두 가지 있습니다. 스크립트에서는 모듈을 동적으로 로드할 수 없습니다. import()가 있으면 실행 전에 실패합니다. Date.now(), Math.random(), 인자 없이 호출한 new Date()도 바로 오류가 발생합니다. 타임스탬프가 필요하면 외부에서 args로 전달하세요. 실제 수행할 작업은 모두 agent의 태스크에 넣고, 스크립트는 스케줄링만 담당합니다.

schema 검증에 실패하면 재시도하며, 다섯 번 재시도해도 통과하지 못하면 오류를 반환합니다. 재시도 횟수는 MAX_STRUCTURED_OUTPUT_RETRIES로 조정할 수 있습니다.

규모, 비용, 중단 후 재개 방법

기본적으로 동시에 16개의 agent를 실행합니다(CPU에 따라 줄어듭니다). CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS로 1에서 256 사이로 조정할 수 있습니다(v2.1.269 이상 필요). 단일 parallel 또는 pipeline은 최대 4,096개 항목을 처리할 수 있으며, 이를 초과하면 조용히 잘라내지 않고 바로 거부합니다. 한 번의 실행당 최대 1,000개의 agent를 사용할 수 있어 반복문이 통제를 벗어나는 것을 방지합니다. 예상 사용량이 agent 25개 또는 토큰 150만 개에 도달하면 경고가 표시되지만, 실행을 막지는 않습니다.

설정 파일의 workflowSizeGuideline으로 Claude에게 규모 방향을 지정할 수 있습니다. small은 5개 미만, medium(기본값, Pro 플랜은 small)은 10개 미만, large는 50개 미만, unrestricted는 제한이 없습니다.

모든 workflow agent가 같은 모델을 사용하도록 통일하고 다른 subagent는 각자의 설정을 따르게 하려면 CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL을 설정하세요(v2.1.296부터 지원).

비용을 아끼는 핵심은 prompt cache입니다. 같은 agent 묶음이 접두사를 공유하면, 두 번째 이후 agent는 캐시를 읽을 수 있습니다. 기본적으로 5초 간격을 두어 첫 번째 agent가 먼저 캐시를 생성하도록 합니다(CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS). 캐시는 기본적으로 5분 동안 유지되며, subagentPromptCacheTtl을 1h로 설정할 수 있습니다. 다만 API 요금으로 계산되는 경우 1시간 캐시의 쓰기 요금이 더 높으므로 직접 판단해야 합니다.

실행 도중 사용량 한도에 도달하면 실행은 실패하지 않고 일시 중지되며, 한도가 초기화되면 자동으로 이어서 실행됩니다(v2.1.271 이상, 대화형 모드, autoContinueAtUsageLimit 활성화 필요). 최대 두 번까지 기다리며, 세 번째에는 실패합니다.

실행이 끝나지 않은 작업을 이어서 실행하려면, 완료된 agent는 저장된 결과를 바로 반환하고, 중단되었거나 실패한 agent는 다시 실행됩니다. 이때 그 뒤에 있는 agent도 함께 다시 실행됩니다. 결과는 ~/.claude/projects/<session>/에 저장되며, 저장 기록을 찾지 못하면 nothing to resume을 보고하고 조용히 처음부터 시작하지 않습니다.

모든 유료 플랜, API, Bedrock, Google Cloud Agent Platform, Microsoft Foundry에서 사용할 수 있습니다. Pro 플랜은 먼저 /config에서 켜야 하며, 조직 관리자는 managed settings로 기능 전체를 끌 수 있습니다.

다음 단계

처음에는 스크립트를 직접 작성하지 마세요. 평소 Claude에게 맡기지만 매번 느리다고 느끼는 큰 작업을 하나 고르세요. 예를 들어 「repo 전체를 훑어 아직 오래된 API를 쓰는 곳을 찾아줘」처럼, 문장에 ultracode를 넣고 Claude가 제시하는 계획을 확인하세요. 몇 개의 agent를 보내는지, 어떤 단계로 나뉘는지 보면 됩니다. 규모가 너무 크다고 느껴지면 먼저 workflowSizeGuideline을 small로 설정하고, 익숙해지면 범위를 넓히세요.

출처: Claude Code 공식 문서 〈Orchestrate subagents at scale with dynamic workflows〉의 When to use a workflow, Have Claude write a workflow, Let Claude decide with ultracode, Where the keyword works, What the saved script looks like, Edit a saved script, Behavior and limits, Prompt caching in a fan-out, Set a size guideline, When a run hits your usage limit, Resume after a pause 섹션（2026-09-18 확인）; Claude Code 변경 로그의 2.1.284, 2.1.296（2026-10-10 확인）

터미널 외에 어디서 사용할 수 있나

지금까지 이 문서에서 다룬 것은 모두 터미널에서 실행하는 Claude Code였습니다. 그러나 같은 계정과 같은 설정으로 IDE, 데스크톱 앱, 브라우저, 모바일, 심지어 Slack에서도 사용할 수 있으며, 각 환경에서 할 수 있는 일은 조금씩 다릅니다.

이번 장은 어떤 상황에서 어떤 환경을 사용할지 정하는 데 도움이 되는 대조표입니다.

VS Code와 JetBrains

VS Code는 1.94 이상이 필요하며, 확장 마켓플레이스에서 Claude Code를 검색하면 설치할 수 있습니다. 설치 후에는 편집기에서 인라인 diff를 확인하고, @로 파일을 언급하고, 계획을 검토하고, 여러 탭에서 각각 대화를 실행할 수 있으며, 기록된 대화도 볼 수 있습니다. 제한 사항으로는 CLI 전용 명령 일부를 사용할 수 없고(예: /plugin, /resume), 확장에 포함된 CLI는 그래픽 인터페이스용으로만 제공되므로 터미널에서는 별도로 설치해야 합니다.

JetBrains 계열(IntelliJ, PyCharm, WebStorm 등)은 먼저 CLI를 설치한 뒤, JetBrains Marketplace에서 플러그인을 설치하고 IDE를 다시 시작해야 합니다. 그다음 Cmd+Esc 또는 Ctrl+Esc로 호출합니다. IDE의 자체 diff 뷰어로 변경 사항을 표시하고, 선택한 코드를 자동으로 대화에 포함하며, IDE의 lint 및 구문 오류도 읽을 수 있습니다. 원격 개발에서는 원격 호스트에 플러그인을 설치해야 하며, WSL2의 기본 NAT 네트워크에는 방화벽 규칙을 별도로 열어야 합니다.

두 환경 모두 Pro, Max, Team, Enterprise 중 하나의 유료 플랜 또는 Claude Console 계정이 필요하며, API key는 필요하지 않습니다.

데스크톱 앱

claude.com/download에서 다운로드합니다. 작업 공간 정리와 미리보기 서버 실행 외에 특히 눈에 띄는 기능은 컴퓨터 제어입니다. 클릭, 입력, 드래그, 단축키 누르기, 네이티브 앱 실행이 가능하며, macOS에서는 백그라운드 실행도 지원합니다. Settings의 General에서 켜야 하며, macOS에서는 손쉬운 사용과 화면 기록 권한도 허용해야 합니다.

이 기능은 연구 프리뷰이며, 컴퓨터 제어는 샌드박스가 없습니다. Pro와 Max에만 열려 있으며 Team과 Enterprise는 지원하지 않습니다. 터미널에도 대응 기능이 있습니다. /mcp를 입력해 computer-use를 찾아 활성화하면 되며, macOS에서만, 대화형 모드에서만 사용할 수 있습니다(-p에서는 사용할 수 없음). 동시에 화면을 잠글 수 있는 대화는 하나뿐입니다.

클라우드 session과 Slack

클라우드 session은 Anthropic이 호스팅하는 환경(또는 조직이 직접 운영하는 환경)에서 실행되므로, 컴퓨터를 꺼도 계속 실행됩니다. 브라우저에서 claude.ai/code를 열거나, 터미널에서 claude --cloud "작업 설명"을 입력해 시작할 수 있습니다. 여러 작업을 동시에 맡기기에 적합하며, 환경에는 git, npm, Python 같은 도구가 이미 준비되어 있습니다. GitHub App을 연결하면 PR을 자동으로 수정할 수도 있습니다. 제한 사항으로는 GitHub(GitHub Enterprise Server 포함)만 지원하며 GitLab, Bitbucket은 지원하지 않습니다. 사용량은 다른 사용 내역과 할당량을 공유합니다. 조직에서 IP 허용 목록을 설정한 경우 차단될 수 있습니다.

Slack에서는 채널에서 @Claude로 작업을 전달합니다. Claude는 스레드의 맥락을 스스로 읽고 클라우드 session으로 라우팅하여 작업을 수행하며, PR을 열 수 있고 기록은 claude.ai/code에 그대로 남습니다. 제한 사항이 적지 않습니다. GitHub만 지원하고, 대화 하나당 PR은 하나만 열 수 있으며, 신뢰할 수 있는 대화에서만 사용할 수 있고, 다이렉트 메시지는 지원하지 않습니다. 또한 이 이전 버전은 Pro 및 Max 계정에만 응답하며, 워크스페이스에 Claude Tag가 이미 연결되어 있으면 안 됩니다. Team과 Enterprise는 Claude Tag를 사용해야 하며, 이미 Claude Tag가 연결된 워크스페이스에서는 이전 bot이 2026-10-05부터 비활성화됩니다.

Remote Control: 휴대폰으로 로컬에서 실행 중인 대화에 다시 연결하기

이것은 클라우드 session과 다르므로 구분해야 합니다. Remote Control은 로컬에서 실행 중인 대화를 claude.ai/code 또는 휴대폰 앱을 통해 원격으로 연결하는 기능입니다. 프로그램은 여전히 여러분의 컴퓨터에서 실행되며, 파일과 도구도 로컬에 있으므로 로컬 MCP server도 그대로 사용할 수 있습니다.

claude remote-control      # standby mode in a local terminal
claude --remote-control    # start an interactive session with it on

이미 대화 중이라면 /remote-control을 입력하면 되며, VS Code에서는 /rc를 입력합니다. 연결되면 대화 진행 상황이 기기 간에 동기화되어, 어느 기기에서든 메시지를 보낼 수 있고 파일이나 사진을 첨부하거나 git diff를 확인할 수도 있습니다. 연결이 끊어지면 자동으로 다시 연결되며, 그 사이의 메시지는 연결될 때까지 대기열에 쌓입니다. Bedrock, Vertex AI, Foundry는 지원하지 않으며, Team과 Enterprise는 기본적으로 꺼져 있어 관리자가 켜야 합니다.

Chrome 확장 프로그램

Chrome 확장 프로그램을 설치하면(Chrome, Edge, Brave, Arc, Vivaldi, Opera 모두 가능하며, 1.0.36 이상이 필요합니다), 터미널에서 claude --chrome을 실행해 브라우저를 조작할 수 있습니다. 클릭, 입력, 스크린샷, console 읽기, 양식 작성, 파일 업로드, GIF 녹화가 가능하며, 이미 로그인한 웹사이트에서도 작업할 수 있습니다. /chrome을 입력하면 상태를 확인하거나 기본으로 활성화하도록 설정할 수 있습니다. WSL은 지원하지 않으며, /login으로 로그인해야 합니다. API key 인증은 사용할 수 없습니다. Bedrock, Vertex, Foundry도 지원하지 않습니다. v2.1.290부터는 프로젝트의 설정 파일(.claude/settings.json 등)에서 Chrome을 자동으로 열 수 없으며, --chrome, /chrome 또는 개인 사용자 설정을 사용해야 합니다.

대조표

session을 플랫폼 간에 이동하는 방법: --teleport는 클라우드 session을 로컬 터미널로 가져와 이어서 실행합니다. 다만 단방향이므로 이후의 변경 사항은 클라우드로 다시 동기화되지 않습니다. --cloud는 터미널에서 새 클라우드 session을 엽니다. 데스크톱 앱의 Continue in 메뉴에서는 로컬 대화를 클라우드로 보낼 수 있습니다. VS Code에서도 클라우드 session을 다시 연결할 수 있으며, 마찬가지로 다시 연결한 뒤에는 claude.ai와 더 이상 동기화되지 않습니다.

다음 단계

모든 환경을 설치할 필요는 없습니다. 여러분의 작업 방식에 가장 가까운 것 하나만 고르세요. 하루 종일 IDE에서 작업한다면 IDE 확장을 설치하고, 자리를 자주 비워야 한다면 Remote Control을 먼저 시험해 보세요. 로컬에서 claude remote-control을 실행한 뒤 휴대폰으로 연결해 원활하게 동작하는지 확인하면 됩니다. 「컴퓨터는 꺼야 하는데 작업이 아직 끝나지 않았다」는 상황을 실제로 마주했을 때 클라우드 session을 열면 됩니다.

출처: Claude Code 공식 문서 〈VS Code〉, 〈JetBrains IDEs〉, 〈Desktop〉, 〈Claude Code on the web〉, 〈Remote control〉, 〈Claude Code with Chrome〉, 〈Computer use〉, 〈Slack〉 각 페이지의 Prerequisites, Get started, Capabilities, Limitations 섹션（2026-09-18 확인）, 그리고 Claude Code 변경 로그의 2.1.290（2026-10-06 확인）（2026-10-15 〈Claude Code in Slack〉을 대조하여 업데이트함.）

settings.json 전체 구조

앞의 여러 장에서 여기저기 여러 설정을 언급했습니다. 권한은 permissions에, hook은 hooks에, 보관 일수는 cleanupPeriodDays에 작성합니다. 그런데 같은 설정이라도 여러 파일에 적을 수 있고, 잘못된 위치에 적으면 적용되지 않습니다. 7장의 auto 예시, 즉 사용자 레벨에 작성해야만 효과가 있었던 사례가 바로 이런 경우입니다.

이번 장에서는 설정 시스템 전체를 살펴봅니다. 어떤 계층이 있는지, 어느 계층이 다른 계층을 덮어쓰는지, 자주 쓰는 키에는 무엇이 있는지 설명합니다.

다섯 계층의 설정과 우선순위

우선순위가 높은 순서대로 위쪽 설정이 아래쪽 설정을 덮어씁니다:

환경 변수는 이 스택에 포함되지 않으며, 키마다 개별적으로 적용 여부가 결정됩니다. 예를 들어 ANTHROPIC_MODEL은 설정 파일의 model을 덮어쓰고, ANTHROPIC_DEFAULT_MODEL은 설정 파일에 값이 없을 때만 적용됩니다.

파일이 생성되는 방식

세 가지 파일은 생성 방식이 서로 다릅니다. 사용자 설정은 처음으로 /config를 실행할 때 만들어집니다. 프로젝트 로컬 설정은 처음으로 영구 권한을 승인할 때 자동으로 만들어지며, Claude Code가 .gitignore에 자동으로 추가합니다. 프로젝트 공유 설정은 직접 만들어야 합니다.

형식은 엄격한 JSON이므로 // 주석을 쓸 수 없고, 불필요한 쉼표가 있어서도 안 됩니다. $schema 줄을 하나 추가하여 https://json.schemastore.org/claude-code-settings.json을 가리키게 하면 편집기가 철자를 검사해 줍니다.

자주 쓰는 키

목록형 키(예: permissions.allow)는 계층 간에 덮어쓰지 않고 병합됩니다. 단일 값 키만 상위 계층이 하위 계층을 덮어씁니다. 이 차이에 따라 규칙을 어디에 작성할지 결정해야 합니다. 팀 전체가 따라야 하는 deny 규칙은 프로젝트 공유 설정에, 개인적인 습관은 사용자 설정에 작성하세요.

설정이 적용되지 않을 때

파일부터 바로 고치지 마세요. 다음 세 명령어로 무슨 일이 일어나는지 확인할 수 있습니다:

/config    # open the config UI; also /config verbose=true for one-liners
/status    # shows which settings files were loaded (the Setting sources line)

claude doctor   # find broken or invalid settings files

/status의 Setting sources 줄이 가장 유용합니다. 이번에 실제로 로드된 파일 목록이 표시됩니다. 적용될 것이라고 생각한 파일이 목록에 없다면, 보통 경로나 계층을 잘못 적었기 때문입니다. JSON 형식이 깨졌다면 claude doctor가 이를 알려 줍니다.

세 파일에 무엇을 두는지

• ~/.claude/settings.json: 권한의 기본 모드, 모델 및 effort 기본 설정. 사용자를 따라다니는 설정입니다.
• .claude/settings.json: 이 프로젝트의 hook, deny 규칙, 모두가 동일하게 유지해야 하는 설정. 버전 관리에 포함합니다.
• .claude/settings.local.json: 이 컴퓨터에서만 사용하는 항목, 예를 들어 로컬 테스트 URL. 버전 관리에 포함하지 않습니다.

다음 단계

지금 바로 /status를 한 번 실행해 Setting sources에 어떤 파일이 나열되는지, 예상과 차이가 있는지 확인하세요. 그다음 ~/.claude/settings.json을 열고 $schema 줄을 추가하세요. 이후 철자를 잘못 입력하면 편집기가 바로 표시해 줍니다. 실제로 설정이 깨졌다면 claude doctor가 어디가 잘못되었는지 알려 줍니다.

출처: Claude Code 공식 문서 〈Settings〉의 Settings files and precedence, Find or create your settings files, Use the /config menu 섹션, 그리고 〈Settings reference〉의 각 설정 키 설명（2026-09-18 확인）; Claude Code 변경 로그의 2.1.281, 2.1.282（2026-10-02 확인）, 2.1.299（2026-10-14 확인）

기업 배포와 보안

앞 장의 다섯 계층 설정 중 가장 높은 계층은 관리형 설정입니다. 개인 사용자에게는 거의 필요하지 않지만, 기업 고객의 프로젝트를 맡고 있거나 회사가 Claude Code를 팀 전체에 배포해야 한다면 다음과 같은 질문이 생깁니다. 모두가 특정 모델만 사용하도록 규정할 수 있는가? 특정 명령을 금지할 수 있는가? 데이터가 외부로 유출되지 않는가?

이번 장에서는 관리자 측면의 내용을 정리합니다. 개인 사용자는 이러한 메커니즘이 있다는 것만 알아 두면 충분합니다.

관리형 설정의 위치

여러 파일로 나누고 싶다면 같은 위치에 managed-settings.d/ 폴더를 만들고 *.json 파일을 넣으세요. 파일 이름 순서대로 병합됩니다.

배포 방식은 네 가지가 있으며, 적용되기까지 걸리는 시간이 다릅니다. 파일을 변경하면 즉시 적용되며, MDM 또는 운영체제 정책, Windows 레지스트리는 약 30분이 걸립니다. claude.ai 관리 콘솔의 서버 측 설정은 약 60분이 걸립니다(시작할 때 한 번 읽고, 이후 매시간 폴링합니다).

여러 관리형 소스가 동시에 존재할 때는 managedSourcesBehavior가 처리 방식을 결정합니다. 기본값은 first-wins로, 우선순위가 가장 높은 소스 하나를 사용합니다. merge로 설정하면 키 단위로 병합되며, 단일 값은 상위 계층의 값을 취하고, 목록은 병합하며, 잠금 항목은 가장 엄격한 값을 취합니다. 우선순위는 높은 순서대로 서버 측, MDM, managed-settings.json 파일, Windows HKCU 레지스트리입니다.

관리자가 잠글 수 있는 항목

관리형 소스에서만 설정할 수 있어 사용자가 변경할 수 없는 설정이 있습니다:

• 권한: permissions.deny, allowManagedPermissionRulesOnly, permissions.disableBypassPermissionsMode
• MCP: allowedMcpServers, deniedMcpServers, managedMcpServers, allowManagedMcpServersOnly
• 모델: availableModels, enforceAvailableModels, modelPicker와 함께 availableModelsMatch("exact"로 설정하면 availableModels의 각 항목은 명시된 버전만 허용되며, 새 모델은 목록에 추가해야 사용할 수 있습니다. v2.1.283부터)와 deniedModels(availableModels에서 허용하더라도 차단되는 모델입니다. v2.1.283부터)
• API 공급자: allowedProviders는 이 컴퓨터에서 사용할 수 있는 공급자를 제한합니다. 예를 들어 Anthropic API, 사용자 지정 엔드포인트, Bedrock, Vertex AI, Foundry 또는 gateway가 있습니다(v2.1.285부터)
• 샌드박스: sandbox.filesystem.allowManagedReadPathsOnly, sandbox.network.allowManagedDomainsOnly
• Plugin 및 marketplace: blockedMarketplaces, strictKnownMarketplaces, allowManagedHooksOnly, allowedChannelPlugins
• 로그인 및 버전: forceLoginMethod, disableSideloadFlags, requiredMinimumVersion, requiredMaximumVersion

실무에서 가장 먼저 설정할 만한 항목은 세 가지입니다. permissions.deny로 절대 건드리면 안 되는 경로와 명령을 차단하고, disableBypassPermissionsMode로 사용자가 권한 검사를 완전히 건너뛰지 못하게 하며, requiredMinimumVersion으로 문제가 있는 이전 버전에 머무르는 사람이 없도록 합니다.

Bedrock 또는 Vertex 사용하기

기업 고객이 자주 요청하는 것은 자체 클라우드 계정을 사용하는 것입니다. 두 경우 모두 환경 변수를 설정합니다:

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=my-profile
export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-8'   # pin the version
export ANTHROPIC_DEFAULT_SONNET_MODEL='us.anthropic.claude-sonnet-4-6'

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-5'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-5'

Bedrock에 필요한 IAM 권한은 bedrock:InvokeModel, InvokeModelWithResponseStream, ListInferenceProfiles, GetInferenceProfile이며, 리소스는 inference-profile과 foundation-model의 ARN을 가리킵니다. 인증은 AWS 프로필, 환경 변수, Bedrock API 키, IAM Identity Center SSO 순서로 확인합니다. Vertex의 최소 권한은 roles/aiplatform.user이며, 인증은 Application Default Credentials, gcloud 설정 또는 서비스 계정 키를 사용합니다.

모델 버전을 고정하는 것은 의도된 설계입니다. 별칭은 플랫폼에 따라 버전이 바뀌므로, 고정해 두어야 어느 날 아침 모두의 동작이 갑자기 달라지는 일을 막을 수 있습니다.

앞의 여러 장에서 소개한 기능 중 일부는 이 두 플랫폼에서 지원되지 않으므로, 계획을 세우기 전에 확인해야 합니다. fast mode, Remote Control, Chrome 확장 프로그램, channels는 Bedrock, Vertex, Foundry를 지원하지 않습니다.

보안 관련 메커니즘

• /security-review: 현재 브랜치에 대해 보안 검사를 한 번 실행하여 안전하지 않은 코드 작성 방식을 찾아냅니다.
• /sandbox: Bash 샌드박스의 경계를 설정합니다. 파일 시스템은 기본적으로 작업 디렉터리로 제한되고, 네트워크는 특정 도메인으로 제한됩니다. 관리형 소스에서 이러한 설정을 고정할 수 있습니다.
• /permissions: 현재 적용 중인 권한 규칙을 확인하고 편집합니다.
• claude doctor: 설정 파일 문제를 진단합니다.
• cleanupPeriodDays: 로컬 트랜스크립트를 보관할 일수를 결정합니다. 클라우드 session은 격리된 가상 머신에서 실행되며, 인증은 단기 scoped 토큰을 사용합니다.

인증 정보, SOC 2, ISO 27001 같은 준수 문서는 Anthropic의 Trust Center(https://trust.anthropic.com)에 있으며, 고객이 자료를 요청하면 이 링크를 바로 전달하는 것이 더 빠릅니다.

다음 단계

회사에 도입하는 역할이라면, 먼저 한 대의 컴퓨터에 managed-settings.json을 놓고 세 가지만 작성하세요. permissions.deny의 차단 목록, disableBypassPermissionsMode, requiredMinimumVersion입니다. /status로 Setting sources에 나타나는지 확인한 뒤 다른 사람에게 배포하세요. 개인 사용자라면 이 장에서 한 가지만 기억하면 됩니다. 회사에서 지급한 컴퓨터에서는 일부 설정을 변경해도 적용되지 않을 수 있으니, 먼저 /status를 확인하고 IT 담당자에게 문의하세요.

출처: Claude Code 공식 문서 〈Managed settings〉의 Where each mechanism stores the policy, Choose a delivery mechanism, Keys only a managed source can set, How Claude Code combines managed sources 섹션, 〈Security〉의 Privacy safeguards 섹션, 〈Amazon Bedrock〉과 〈Google Vertex AI〉의 Configure Claude Code 섹션（2026-09-18 확인）; Claude Code 변경 로그의 2.1.283, 2.1.285（2026-10-02 확인）