Claude Code 공식 스펙 레퍼런스

Claude Code의 Skills, Subagents, Hooks, MCP, Plugin, Agent Teams, Settings, CLI 공식 스펙을 정리합니다.

마지막 업데이트: 2026-03-24 문서 URL 이전: docs.anthropic.com/en/docs/claude-code/* → code.claude.com/docs/en/* (301 리다이렉트)

현재 모델 라인업: Opus 4.6 (1M 컨텍스트, 64-128K 출력), Sonnet 4.6 (1M beta), Haiku 4.5 RETIRED 모델: Opus 4/4.1, Sonnet 3.7, Haiku 3.5 — 더 이상 사용 불가

목차

1. Skills 작성법
2. Subagent (Custom Agent) 작성법
3. Hooks 시스템
4. MCP (Model Context Protocol)
5. Plugin 구조
6. Agent Teams
7. Settings 최적화
8. 앤트로픽 제공 스킬
9. CLI 레퍼런스
10. Channels
11. Voice Mode
12. Remote Control 상세
13. Desktop 앱 및 웹 접근
14. 통합 생태계
15. 주요 변경 이력

1. Skills 작성법

1.1 파일 위치 및 적용범위

같은 이름의 스킬이 여러 위치에 있으면 높은 우선순위가 우선합니다. Plugin 스킬은 네임스페이스로 구분: plugin-name:skill-name

자동 발견 (v2.1.76+):

• 서브디렉토리 .claude/skills/ 자동 스캔 (모노레포: packages/frontend/.claude/skills/ 등)
• --add-dir 디렉토리의 스킬 라이브 감지 — 세션 중 편집 시 자동 반영, 재시작 불필요

Skills는 Agent Skills 오픈 스탠다드를 따릅니다.

1.2 YAML Frontmatter 전체 필드

---
name: skill-name              # (선택) 고유 이름, kebab-case, 최대 64자. 미지정 시 디렉토리명 사용. /skill-name으로 호출
description: |                 # (권장) 자동 호출 매칭에 사용되는 설명. Claude가 이 텍스트로 스킬 호출 여부 결정
  Use this skill when...
  Examples: "keyword1", "keyword2"
argument-hint: "[filename]"   # (선택) 자동완성 힌트. 예: "[issue-number]", "[filename] [format]"
model: sonnet                  # (선택) 사용 모델: opus, sonnet, haiku. 미지정 시 부모 세션 모델
# color 필드는 Skills에서 제거됨. Agents frontmatter(§2.2)에서만 사용
# color: blue                  # (제거됨) 터미널 표시 색상 → Agents 전용 (§2.2 참조)
context: fork                  # (선택) fork면 별도 서브에이전트 컨텍스트에서 실행
agent: general-purpose         # (선택) context:fork일 때 서브에이전트 타입 (Explore, Plan, general-purpose)
allowed-tools: Read, Grep, Bash(npm *)  # (선택) 허용 도구 (쉼표 구분). 미지정 시 전체 허용
disable-model-invocation: false # (선택) true면 Claude 자동 호출 비활성화 (수동 /명령으로만 호출)
user-invocable: true           # (선택) false면 /메뉴에서 숨김 (다른 스킬에서만 참조 가능)
hooks: {}                      # (선택) 스킬 수명주기에 범위 지정된 hooks
effort: high                   # (선택) 스킬 활성 시 모델 노력 수준: low, medium, high, max (v2.1.80). max = Opus 4.6 전용
---

1.3 allowed-tools 구문

# 개별 도구
allowed-tools: Read, Grep, Glob, Edit, Write

# Bash 와일드카드
allowed-tools: Bash(npm *), Bash(git status)

# 모든 Bash 허용
allowed-tools: Bash(*)

# 서브에이전트 제한
allowed-tools: Agent(worker, researcher)

# WebFetch 도메인 제한
allowed-tools: WebFetch(domain:example.com)

# 스킬 호출 제한
allowed-tools: Skill(my-skill)       # 정확히 my-skill만
allowed-tools: Skill(my-skill *)     # my-skill 접두사 매칭

1.4 변수 치환

$ARGUMENTS가 스킬 본문에 없으면, 인수는 자동으로 끝에 ARGUMENTS: <value> 형태로 추가됩니다.

참고: v2.1.19에서 인덱스 구문이 $ARGUMENTS.0 → $ARGUMENTS[0]으로 변경됨.

1.5 동적 컨텍스트 주입 (Dynamic Context Injection)

!`command` 구문으로 스킬 로드 시 명령 실행 결과를 본문에 삽입합니다.

## PR 변경사항
!`gh pr diff`

## PR 코멘트
!`gh pr view --comments`

## 프로젝트 상태
!`cat docs/status/current.md 2>/dev/null || echo "상태 파일 없음"`

동작: Claude에게 전달되기 직전에 명령이 실행되고, 출력이 해당 위치를 대체합니다.

주의사항:

• 스킬 로드 시 1회 실행
• 실행 실패 시 빈 문자열
• 무거운 명령은 로드 지연 유발

1.6 context:fork (격리 실행)

---
context: fork
agent: Explore    # 선택: 서브에이전트 타입 지정
---

• 스킬이 별도 서브에이전트 프로세스에서 실행
• 메인 세션 컨텍스트 윈도우 오염 방지
• 완료 시 결과만 메인 세션으로 반환
• 대량 파일 분석, 실험적 작업에 적합

1.7 Supporting Files

my-skill/
├── SKILL.md              ← 핵심 프로세스 (<500줄)
├── references/           ← 상세 규칙, 스키마
│   ├── rules.md
│   └── schema.md
├── examples/             ← 입출력 예시
│   └── example.md
└── scripts/              ← 보조 스크립트
    └── helper.sh

skill.md에서 참조:

상세 규칙: `references/rules.md` 참조

1.8 노력 수준 제어 (Effort Level)

스킬 본문에 ultrathink 키워드를 포함하면 해당 턴에서 고노력 모드가 활성화되었으나, v2.1.72부터 /effort 명령 및 effort frontmatter 필드로 대체됨.

현재 방법:

• effort frontmatter 필드: 스킬/에이전트 활성 시 노력 수준 오버라이드 (low, medium, high, max) (v2.1.80). max는 Opus 4.6 전용
• /effort 인세션 명령: 세션 중 노력 수준 변경 (auto로 기본값 복원)
• --effort CLI 플래그: 세션 시작 시 노력 수준 설정
• effortLevel 설정: settings.json에서 기본 노력 수준 지정

참고: max 레벨은 Opus 4.6 모델에서만 사용 가능합니다. 다른 모델에서는 high가 최대.

1.9 스킬 설명 문자 예산

스킬 설명 텍스트는 컨텍스트 윈도우의 2% (폴백: 16,000자)까지 허용됩니다. SLASH_COMMAND_TOOL_CHAR_BUDGET 환경변수로 오버라이드 가능.

2. Subagent 작성법

2.1 파일 위치 및 우선순위

2.2 Frontmatter 전체 필드

---
name: agent-name               # (필수) 고유 이름, kebab-case
description: |                  # (필수) 자동 호출 트리거 설명
  Use this agent when...
  <example>...</example>
model: sonnet                   # (선택) alias: opus | sonnet | haiku | inherit (기본값). full model ID도 가능: claude-sonnet-4-6, claude-opus-4-6, claude-haiku-4-5-20251001
color: red                      # (선택) 표시 색상
tools: Read, Write, Bash        # (선택) 허용 도구 (쉼표 구분). 미지정 시 전체 상속
disallowedTools: Agent          # (선택) 상속 도구에서 제외할 도구 (거부 목록 방식)
permissionMode: default         # (선택) default | acceptEdits | dontAsk | bypassPermissions | plan
maxTurns: 30                    # (선택) 최대 에이전트 턴 수
skills:                         # (선택) 사전 로드할 스킬 (전체 내용 주입)
  - api-conventions
  - error-handling
mcpServers: tavily              # (선택) 사용 가능한 MCP 서버 (이름 또는 인라인 정의, v2.1.77+)
hooks: {}                       # (선택) 에이전트 수명주기 hooks
effort: high                    # (선택) 에이전트 활성 시 노력 수준: low, medium, high, max (v2.1.80). max = Opus 4.6 전용
memory: project                 # (선택) user | project | local — 세션 간 영속 메모리
background: false               # (선택) true면 항상 백그라운드 태스크로 실행
isolation: worktree             # (선택) "worktree"면 격리된 git worktree에서 실행
worktree:                       # (선택) worktree 격리 세부 설정
  sparsePaths: ["src/", "lib/"] # (선택) sparse-checkout 경로
  symlinkDirectories: ["node_modules/"] # (선택) 심링크할 디렉토리
---

2.3 Built-in Agent Types

Agent tool (구 Task tool, v2.1.63 리네임)에서 subagent_type으로 지정:

참고: Task(...) 구문은 Agent(...) 별칭으로 계속 동작합니다. v2.1.77: Agent tool의 resume 파라미터 제거. SendMessage({to: agentId})로 대체 — 중지된 에이전트를 백그라운드에서 자동 재개.

2.4 커스텀 에이전트 작성 패턴

---
name: my-agent
description: Use this agent when...
model: sonnet
color: blue
tools: Read, Write, Edit, Glob, Grep, Bash
---

역할 정의, 전문성 명시

## 핵심 프로세스
단계별 작업 흐름

## 출력 형식
통일된 결과 포맷

## 가이드라인
행동 규칙, 제약 조건

2.5 Skills vs Agents vs Subagents 구분

2.6 영속 메모리 (Persistent Memory)

memory 필드 설정 시 에이전트가 세션 간 정보를 유지합니다.

• MEMORY.md 파일의 처음 200줄이 자동 로드
• Read/Write/Edit 도구가 자동 활성화

2.7 백그라운드 서브에이전트

• background: true 또는 실행 중 Ctrl+B로 백그라운드 전환
• 백그라운드 시 사전 승인된 권한만 사용, 미승인 요청은 자동 거부
• 완료 시 알림

2.8 자동 압축 (Auto-Compaction)

• 컨텍스트의 ~95% 도달 시 자동 트리거
• CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 환경변수로 임계값 조정 가능

2.9 에이전트 관리 CLI

claude agents            # 설정된 모든 에이전트 목록 조회

인세션: /agents 명령으로 에이전트 생성/편집/삭제 인터랙티브 UI. "Generate with Claude" 옵션으로 자동 생성 지원.

2.10 이 저장소의 에이전트 목록

3. Hooks 시스템

3.1 전체 이벤트 타입 (22가지)

3.2 Handler 타입 (4가지)

3.3 설정 구조

{
  "hooks": {
    "<EventName>": [
      {
        "matcher": "ToolName|Pattern",
        "hooks": [
          {
            "type": "command",
            "command": "script.sh \"$TOOL_INPUT\"",
            "timeout": 30,
            "async": false,
            "statusMessage": "실행 중...",
            "once": false
          },
          {
            "type": "http",
            "url": "https://example.com/webhook",
            "headers": { "Authorization": "Bearer $API_KEY" },
            "allowedEnvVars": ["API_KEY"],
            "timeout": 30
          },
          {
            "type": "prompt",
            "prompt": "프롬프트 텍스트",
            "model": "haiku"
          },
          {
            "type": "agent",
            "prompt": "에이전트 지시",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

핸들러 공통 필드: type, timeout, statusMessage (실행 중 표시 메시지), once (스킬 hooks 전용, 1회만 실행)

3.4 Matcher 패턴 (정규식)

3.5 Command Handler Exit Code

3.6 JSON Output 필드

공통 필드 (모든 이벤트)

{
  "continue": true,              // false면 Claude 완전 중지
  "stopReason": "중지 사유",       // continue:false일 때 표시
  "suppressOutput": false,        // true면 verbose에서 숨김
  "systemMessage": "경고 메시지"    // 사용자에게 경고
}

PreToolUse 전용 필드

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",    // "allow" | "deny" | "ask"
    "permissionDecisionReason": "사유",
    "updatedInput": { "command": "수정된 명령" },
    "additionalContext": "추가 컨텍스트"
  }
}

Deprecated: 상위 레벨 decision/reason 대신 hookSpecificOutput.permissionDecision 사용 권장.

PostToolUse / Stop / SubagentStop 전용 필드

{
  "decision": "block",           // "block"이면 계속 진행 요청
  "reason": "계속해야 하는 이유",
  "additionalContext": "추가 컨텍스트"
}

SubagentStop 추가 입력 필드: agent_transcript_path, last_assistant_message

PostToolUse 추가 출력 필드: updatedMCPToolOutput (MCP 도구 결과 수정)

PermissionRequest 전용 필드

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",          // "allow" | "deny"
      "updatedInput": { },
      "updatedPermissions": [],
      "message": "메시지"
    }
  }
}

InstructionsLoaded 입력 필드

TaskCompleted 입력 필드

3.7 환경변수

공통 입력 필드 (stdin JSON): session_id, transcript_path, cwd, permission_mode, hook_event_name, agent_id (서브에이전트), agent_type (서브에이전트)

3.8 Async Hooks

{
  "type": "command",
  "command": "long-running-task.sh",
  "async": true
}

async: true면 백그라운드 실행, Claude는 결과를 기다리지 않고 진행합니다.

3.9 HTTP Hooks

{
  "type": "http",
  "url": "https://example.com/hook",
  "headers": {
    "Authorization": "Bearer $API_TOKEN",
    "X-Custom": "${CUSTOM_HEADER}"
  },
  "allowedEnvVars": ["API_TOKEN", "CUSTOM_HEADER"]
}

• URL로 JSON POST 요청 전송
• $VAR 또는 ${VAR} 구문으로 헤더에 환경변수 삽입
• allowedEnvVars에 명시된 변수만 치환됨
• Managed 설정의 allowedHttpHookUrls로 허용 URL 제한 가능

3.10 설정 파일 위치

4. MCP 연결

4.1 Transport 타입

4.2 설정 파일 (.mcp.json)

{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    },
    "remote-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    },
    "streaming-server": {
      "type": "streamable-http",
      "url": "https://stream.example.com/mcp"
    }
  }
}

4.3 Scope 및 우선순위

4.4 환경변수 확장

MCP 설정에서 ${VAR} 또는 ${VAR:-default} 구문을 지원합니다:

{
  "url": "${API_BASE_URL:-https://api.example.com}/mcp",
  "env": {
    "API_KEY": "${OPENAI_API_KEY}",
    "DB_URL": "${DATABASE_URL}"
  }
}

확장 가능 필드: command, args, env, url, headers

4.5 OAuth 지원

{
  "type": "http",
  "url": "https://api.example.com/mcp",
  "oauth": {
    "clientId": "...",
    "callbackPort": 8080,
    "authServerMetadataUrl": "https://auth.example.com/.well-known/oauth-authorization-server"
  }
}

1. --client-id, --client-secret으로 OAuth 자격 증명 설정
2. /mcp로 브라우저 인증 트리거
3. 토큰은 시스템 키체인에 안전하게 저장
4. 자동 갱신

authServerMetadataUrl 지원: v2.1.64+ v2.1.81: OAuth CIMD (Client ID Metadata Document, SEP-991) 지원 — Dynamic Client Registration 없는 서버용

4.6 MCP Elicitation (v2.1.76)

MCP 서버가 대화형 다이얼로그(폼/URL)로 사용자에게 구조화된 입력을 요청할 수 있습니다.

• Elicitation 이벤트: MCP 서버가 입력 요청 시 발생. Matcher는 MCP 서버 이름
• ElicitationResult 이벤트: 사용자 응답 후 발생
• Hook에서 action: accept/decline/cancel 결정 가능
• Notification 매처에 elicitation_dialog 추가

Elicitation 훅 입력 필드 (v2.1.76+):

• mcp_server_name: MCP 서버 이름
• message: 사용자에게 표시할 메시지
• mode: elicitation 모드
• url: 연관 URL
• requested_schema: 요청된 입력 스키마

ElicitationResult 훅 입력 필드:

• elicitation_id: elicitation 식별자
• result: 사용자 응답 결과

출처: Hooks 가이드

4.7 Tool Search

MCP 도구 설명이 컨텍스트 윈도우의 일정 비율을 초과하면 자동 활성화됩니다:

# 환경변수로 제어
ENABLE_TOOL_SEARCH=auto:5    # 5% 임계값 (기본: 10%)
ENABLE_TOOL_SEARCH=false     # 비활성화
ENABLE_TOOL_SEARCH=true      # 항상 활성화

• Sonnet 4+, Opus 4.6+ 모델에서만 지원 (tool_reference 블록)
• Haiku는 Tool Search 미지원
• 동적 도구 로딩으로 컨텍스트 절약
• disallowedTools: ["MCPSearch"]로 비활성화 가능

4.8 CLI 명령

claude mcp add <name> <url/command>              # 서버 추가
claude mcp add --transport http <name> <url>     # HTTP 서버 추가
claude mcp add-json <name> '<json>'              # JSON 설정으로 추가
claude mcp add-from-claude-desktop               # Desktop 앱에서 가져오기
claude mcp list                                   # 서버 목록
claude mcp get <name>                             # 서버 상세 정보
claude mcp remove <name>                          # 서버 제거
claude mcp reset-project-choices                  # 프로젝트 MCP 선택 초기화
claude mcp serve                                  # Claude Code를 MCP 서버로 실행

4.9 MCP Resources

리소스를 @server:protocol://resource/path 형태로 참조합니다.

4.10 MCP Prompts

MCP 서버가 제공하는 프롬프트는 /mcp__servername__promptname으로 사용 가능합니다.

4.11 출력 제한

• 10,000 토큰 경고
• 기본 최대: 25,000 토큰
• MAX_MCP_OUTPUT_TOKENS 환경변수로 조정

4.12 Managed MCP 설정

시스템 경로의 managed-mcp.json으로 조직 차원 MCP 관리:

{
  "allowedMcpServers": [{ "serverName": "approved-*" }],
  "deniedMcpServers": [{ "serverCommand": "dangerous-cmd" }]
}

매칭 기준: serverName, serverCommand, serverUrl

4.13 Claude.ai MCP 서버

Claude.ai에서 설정한 MCP 서버가 Claude Code에서 자동 사용 가능합니다. 비활성화: ENABLE_CLAUDEAI_MCP_SERVERS=false

4.14 동적 도구 업데이트

MCP 서버가 list_changed 알림을 보내면 도구 목록이 동적으로 갱신됩니다.

4.15 2026 MCP 로드맵

MCP 프로토콜의 2026년 발전 방향 4대 축:

5. Plugin 구조

5.1 매니페스트 (.claude-plugin/plugin.json)

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "설명",
  "author": { "name": "작성자", "email": "...", "url": "..." },
  "homepage": "https://...",
  "repository": "https://...",
  "license": "MIT",
  "keywords": ["..."],
  "skills": "./skills/",
  "agents": "./agents/",
  "commands": ["./custom/cmd.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "lspServers": "./.lsp.json",
  "outputStyles": "./styles/"
}

필수: name만 필수 (매니페스트가 존재할 경우). 모든 경로는 Plugin 루트 기준 상대 경로, ./로 시작.

최소 지원 버전: Claude Code v1.0.33+

5.2 번들 구성

5.3 LSP 서버 설정 (.lsp.json)

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": { ".go": "go" }
  }
}

5.4 경로 참조 (${CLAUDE_PLUGIN_ROOT})

Plugin 내부 파일 참조 시 절대 경로 변수 사용:

{
  "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
  "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
}

설치 시 실제 경로로 자동 치환됩니다.

5.5 설치/관리 CLI

claude plugin install <plugin> [--scope user|project|local]   # 설치
claude plugin uninstall <plugin> [--scope ...]                 # 제거
claude plugin enable <plugin> [--scope ...]                    # 활성화
claude plugin disable <plugin> [--scope ...]                   # 비활성화
claude plugin update <plugin> [--scope ...]                    # 업데이트
claude plugin list                                             # 목록
claude plugin get <name>                                       # 상세 정보
claude plugin validate                                         # 검증

테스트: claude --plugin-dir ./my-plugin (반복 사용 가능) 플러그인 갱신: /reload-plugins (재시작 없이 활성화)

5.6 Scope

5.7 마켓플레이스 배포

Plugin 소스 타입:

제출: claude.ai/settings/plugins/submit 또는 platform.claude.com/plugins/submit

5.8 인라인 플러그인 선언 (v2.1.80)

settings.json에서 source: 'settings'으로 플러그인 항목을 직접 정의할 수 있습니다. 별도 파일/레포 없이 설정 파일 내에서 인라인 선언.

{
  "enabledPlugins": [
    { "name": "my-inline-plugin", "source": "settings", "skills": "./skills/" }
  ]
}

6. Agent Teams

6.1 활성화

# 환경변수 (실험적 기능)
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

# 또는 settings.json에서
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

6.2 아키텍처

Lead (메인 세션)
├── Task List (공유, 영속)
├── Mailbox (에이전트 간 메시징)
└── Teammates (독립 세션):
    ├── Teammate 1: 자체 컨텍스트 윈도우
    ├── Teammate 2: 자체 컨텍스트 윈도우
    └── Teammate 3: 자체 컨텍스트 윈도우

• Lead: 조율, 작업 생성, 할당
• Teammates: 독립 세션, 작업 목록에서 자동 클레임, Lead와 이력 미공유
• 저장소: ~/.claude/tasks/{team-name}/
• 설정: ~/.claude/teams/{team-name}/config.json

6.3 Task List 시스템

TaskCreate → 작업 생성 (pending)
TaskUpdate → 상태 변경 (in_progress → completed)
TaskList   → 전체 작업 목록 조회
TaskGet    → 개별 작업 상세 조회

• 작업 의존성 자동 관리
• Teammates가 미할당/미차단 작업을 자동 클레임
• 파일 잠금으로 경쟁 조건 방지

6.4 Mailbox 통신

자동 전달: 수신자에게 즉시 알림, 폴링 불필요

6.5 Display Mode

설정: teammateMode (auto / in-process / tmux)

키보드 단축키:

• Shift+Down: teammate 순환 전환
• Ctrl+T: task list 토글
• Enter: 작업 상세 보기
• Escape: 인터럽트

6.6 제한사항

• /resume으로 in-process teammate 재개 불가
• 작업 상태가 지연될 수 있음 (수동 업데이트 필요)
• 세션당 하나의 팀만 가능
• 중첩 팀 불가 (lead만)
• Split panes는 tmux/iTerm2 필요 (VS Code, Windows Terminal, Ghostty 미지원)
• Lead는 고정 (변경 불가)
• 권한은 스폰 시점에 설정됨
• 종료가 느릴 수 있음 (현재 요청 완료 후)

7. Settings 최적화

7.1 설정 우선순위 (높은 것이 우선)

1. Managed settings               (조직 IT 배포, 최우선)
2. CLI 플래그                      (--model sonnet 등)
3. .claude/settings.local.json    (로컬, gitignored)
4. .claude/settings.json          (프로젝트, git 추적)
5. ~/.claude/settings.json        (사용자 개인)
6. 내장 기본값                     (최하위)

7.2 설정 파일 위치

7.3 주요 설정 항목

{
  "model": "sonnet",
  "permissions": {
    "allow": [
      "Read",
      "Bash(npm run *)",
      "Bash(git status)",
      "Write(src/**)",
      "WebFetch(domain:example.com)",
      "Skill(my-skill)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Read(.env)",
      "Read(secrets/**)"
    ],
    "defaultMode": "default"
  },
  "env": {
    "NODE_ENV": "development"
  },
  "hooks": { },
  "mcpServers": { },
  "agentTeams": { "enabled": false },
  "attribution": {
    "commit": true,
    "pr": true
  },
  "sandbox": {
    "network": { "allowManagedDomainsOnly": false },
    "enableWeakerNestedSandbox": false,
    "enableWeakerNetworkIsolation": false,
    "allowRead": ["/allowed/path"]
  },
  "worktree": {
    "sparsePaths": ["packages/frontend/", "libs/shared/"]
  },
  "autoMemoryDirectory": ".claude/memory",
  "modelOverrides": {
    "sonnet": "us.anthropic.claude-sonnet-4-6-20260315-v1:0"
  },
  "showClearContextOnPlanAccept": true,
  "effortLevel": "high",
  "outputStyle": "concise"
}

v2.1.76+ 신규 설정:

• worktree.sparsePaths: 대규모 모노레포에서 git sparse-checkout으로 필요 디렉토리만 체크아웃
• autoMemoryDirectory (v2.1.74): 자동 메모리 저장 경로 커스터마이즈
• modelOverrides (v2.1.73): 모델 피커 항목을 커스텀 모델 ID로 매핑 (예: Bedrock 프로파일 ARN)
• showClearContextOnPlanAccept (v2.1.81): 플랜 모드에서 "clear context" 옵션 표시 여부
• effortLevel (v2.1.76): 기본 노력 수준 설정 (low, medium, high, max). max는 Opus 4.6 전용
• outputStyle (v2.1.73): 출력 스타일 설정 (/output-style 인세션 명령 대체)
• sandbox.allowRead (v2.1.77): denyRead 영역 내에서 특정 경로 읽기 재허용 (세분화된 파일 접근 제어). 출처: Settings
• statusline.rate_limits (v2.1.80): statusline 스크립트에 rate_limits 필드 제공. 5시간/7일 윈도우별 used_percentage, resets_at 정보 포함
• 메모리 신선도 타임스탬프 (v2.1.75): 메모리 파일에 last-modified 타임스탬프 포함. 신선/오래된 메모리 판별에 활용
• 세션 이름 프롬프트 바 표시 (v2.1.79): /rename으로 설정한 세션 이름이 프롬프트 바에 표시. /config에서 턴 지속시간(turn duration) 표시 토글 가능
• managed settings 버그 수정 (v2.1.80): enabledPlugins, permissions.defaultMode, policy-set 환경변수가 캐시된 remote-settings.json으로 적용 안 되던 문제 수정
• 대규모 저장소 메모리 사용량 개선 (v2.1.80): 250k 파일 레포에서 시작 시 약 80MB 메모리 절감

Deprecated:

• includeCoAuthoredBy → attribution.commit / attribution.pr 사용
• npm 설치 방식 (npm install -g @anthropic-ai/claude-code) → 네이티브 인스톨러 사용 권장
• /output-style 인세션 명령 → outputStyle 설정 또는 /config에서 변경

7.4 Permission Mode

7.5 환경변수

Deprecated: ANTHROPIC_SMALL_FAST_MODEL → ANTHROPIC_DEFAULT_HAIKU_MODEL 사용

7.6 Managed 전용 설정

7.7 JSON Schema 검증

IDE 자동완성을 위한 스키마:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json"
}

VS Code, JetBrains 등에서 자동완성 및 검증 가능.

8. 앤트로픽 제공 스킬

Claude Code에 기본 탑재된 공식 스킬입니다. 별도 설치 없이 사용 가능합니다.

상세 레퍼런스: 03-skills/00-community-reference/anthropic-provided-skills.md

8.1 번들 스킬 (5개)

8.2 빌트인 스킬 (1개)

8.3 Document 스킬 (16개)

자동 트리거 기반. document-skills: 네임스페이스.

9. CLI 레퍼런스

9.1 기본 명령

v2.1.80 수정: --resume 시 병렬 도구 호출 결과 복원 개선. 이전에는 [Tool result missing] 표시되던 것이 모든 tool_use/tool_result 쌍이 올바르게 복원됨. | claude update | 업데이트 | | claude auth login\|logout\|status | 인증 관리 | | claude agents | 서브에이전트 목록 | | claude mcp | MCP 서버 관리 | | claude remote-control | 원격 제어 세션 |

9.2 주요 플래그

9.3 Print 모드 전용 플래그

9.4 시스템 프롬프트 플래그

9.5 인세션 명령

10. Channels (연구 프리뷰, v2.1.80)

MCP 서버가 세션에 메시지를 푸시하는 시스템. Telegram/Discord에서 세션을 원격 제어 가능.

10.1 활성화

claude --channels    # 채널 알림 수신 활성화

10.2 지원 플랫폼

10.3 활용 시나리오

• CI/CD 파이프라인 완료 알림
• 장시간 작업 모니터링
• 모바일에서 세션 상태 확인

출처: Changelog

11. Voice Mode (v2.1.71)

Push-to-Talk 기반 음성 입력. /voice 명령으로 활성화.

11.1 사용법

/voice              # 음성 모드 활성화
스페이스바 누르고 말하기   # Push-to-Talk

11.2 설정

12. Remote Control 상세

12.1 Server Mode

claude --spawn --capacity 4   # 서버 모드 (최대 4 병렬 세션)

12.2 Interactive Mode

claude --rc   # 인터랙티브 세션에서 원격 제어 활성화

모바일 지원 포함.

13. Desktop 앱 및 웹 접근

공식 데스크톱 앱 릴리즈. macOS, Windows (x64, ARM64). 멀티 세션, 예약 작업, 비주얼 diff 리뷰 지원.

웹 접근: claude.ai/code에서 브라우저 기반 Claude Code 사용 가능. --remote 플래그로 웹 세션 생성, --teleport으로 웹→로컬 이전.

14. 통합 생태계

Claude Code와 연동되는 플랫폼/서비스 통합 기능입니다.

14.1 Dispatch

모바일에서 세션을 생성하면 데스크톱에서 자동 수신하여 작업 시작. 모바일→데스크톱 핸드오프를 지원하여 이동 중에도 작업을 시작하고 데스크톱에서 이어받을 수 있습니다.

14.2 Slack 통합

@Claude 멘션으로 직접 PR 생성, 이슈 트리아지, 코드 검토 가능. Slack 워크스페이스에서 Claude Code 기능을 활용하여 팀 협업 워크플로에 통합합니다.

14.3 GitHub Code Review

PR에 대한 자동 코드 리뷰. GitHub Actions와 별도로 PR diff를 분석하여 코드 품질/보안/성능 피드백을 제공합니다.

참고: code.claude.com/docs/en/code-review

14.4 Cloud Scheduled Tasks (Remote Triggers)

크론 스케줄 기반으로 Claude Code를 원격 실행. /schedule 인세션 명령 또는 웹 UI에서 반복 작업을 생성/관리할 수 있습니다.

15. 주요 변경 이력 (v2.1.63→v2.1.81)

10. 고급 CLI 패턴 (QHDE 연구 기반)

출처: docs/intel/qhde-research/02-orchestration/02-claude-code-orch.md

10.1 헤드리스 실행 (비대화형 자동화)

# 단일 턴 실행 + JSON 출력 (파이프라인/스크립트 통합용)
claude -p "analyze this codebase" --output-format json

# 다중 턴 실행 (토큰 비용 제어)
claude -p "implement auth module" --max-turns 10

# 지출 한도 설정
claude -p "refactor entire codebase" --max-budget-usd 5.00

# 과부하 시 폴백 모델
claude -p "quick fix" --fallback-model haiku

10.2 세션 영속성 (기억을 가진 에이전트)

# 세션 이름 지정 후 시작
claude "start auth module work"    # → 세션 ID 자동 생성

# 이전 세션 재개 (컨텍스트 유지)
claude -r "session-id-or-name" -p "continue from where we left off"

# 최근 대화 이어서
claude -c

활용 시나리오: 장기 실행 작업(인프라 마이그레이션, 대규모 리팩토링)을 여러 세션에 걸쳐 연속 수행

10.3 Claude Code를 MCP 서버로 노출

# Claude Code를 MCP 서버로 실행 (타 에이전트에서 호출 가능)
claude mcp serve

# 사용 시나리오:
# - Antigravity/Cursor에서 Claude Code의 코드 분석 능력을 MCP 도구로 사용
# - 멀티 IDE 환경에서 Claude를 중앙 코딩 엔진으로 활용

10.4 트리거 아키텍처 패턴

# 패턴 1: CI/CD 파이프라인 내 자동 수정
# (GitHub Actions에서 테스트 실패 시 Claude가 수정 PR 생성)
claude -p "fix failing tests: $(cat test-output.log)" \
  --output-format json --max-turns 15

# 패턴 2: 파일 감시 기반 반응형 실행
# (지시 파일 변경 감지 → Claude 트리거)
# Linux: inotifywait, macOS: fswatch, Cross-platform: chokidar

# 패턴 3: Hooks 시스템 활용 (PostToolUse)
# settings.json에서 특정 도구 실행 후 자동 검증 스크립트 실행

10.5 비용 최적화 전략

10.6 kdyswarm 연동 고급 패턴

# 에이전트를 헤드리스 모드로 병렬 실행 (kdyswarm Phase 4)
claude -p "$AGENT_MISSION" \
  --output-format json \
  --max-turns 30 \
  --permission-mode bypassPermissions \
  -w  # 워크트리 격리

# 세션 재개로 에이전트 작업 이어받기
claude -r "$SESSION_ID" -p "resume and complete remaining tasks"

참고 자료

• Claude Code 공식 문서
• Skills 가이드
• Hooks 가이드
• MCP 가이드
• Sub-agents 가이드
• Plugins 가이드
• Agent Teams 가이드
• Settings 가이드
• CLI 레퍼런스
• Channels 가이드
• Remote Control 가이드
• 앤트로픽 제공 스킬 상세
• 커뮤니티 참조