claude@cli:~/docs$ cat claude-code.md

Claude Code CLI: The Definitive Technical Reference

#

words: 13332 read_time: 67m updated: 2026-02-04 02:37
$ less claude-code.md

Claude Code는 채팅 인터페이스가 아닌 에이전트 시스템으로 작동합니다. 프로그래밍 지식을 갖춘 단순한 대화형 도구가 아닙니다. CLI는 코드베이스를 읽고, 명령을 실행하고, 파일을 수정하고, git 워크플로우를 관리하고, MCP를 통해 외부 서비스에 연결하며, 복잡한 작업을 전문화된 subagent에게 위임합니다. 모든 것이 개발자의 실제 작업 방식과 통합되는 명령줄 인터페이스를 통해 이루어집니다.

Claude Code를 단순히 사용하는 것과 효과적으로 활용하는 것의 차이는 다섯 가지 핵심 시스템에 대한 이해에서 비롯됩니다. 이를 숙달하면 Claude Code는 생산성을 몇 배로 높여주는 도구가 됩니다:

  1. 설정 계층 구조 — 동작을 제어합니다
  2. 권한 시스템 — 작업을 제어합니다
  3. Hook 시스템 — 결정적 자동화를 가능하게 합니다
  4. MCP 프로토콜 — 기능을 확장합니다
  5. Subagent 시스템 — 복잡한 다단계 작업을 처리합니다

저는 수개월 동안 프로덕션 코드베이스, CI/CD 파이프라인, 엔터프라이즈 배포 환경에서 Claude Code의 한계를 시험했습니다. 이 가이드는 그 경험을 바탕으로, 제가 처음 시작할 때 있었으면 했던 종합 레퍼런스로 정리한 것입니다. 모든 기능에 대해 실제 구문, 실제 설정 예제, 그리고 숙련된 사용자도 실수하기 쉬운 엣지 케이스를 포함했습니다.


Claude Code 작동 방식: 멘탈 모델

기능을 자세히 살펴보기 전에, Claude Code의 아키텍처가 사용 방식에 어떤 영향을 미치는지 이해해야 합니다. 시스템은 세 가지 계층으로 작동합니다:

┌─────────────────────────────────────────────────────────┐
│                    CLAUDE CODE LAYERS                    │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │   MCP   │  │  Hooks  │  │ Skills  │  │ Plugins │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
│  External tools, deterministic automation, domain       │
│  expertise, packaged extensions                          │
├─────────────────────────────────────────────────────────┤
│  DELEGATION LAYER                                        │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              Subagents (up to 10 parallel)       │    │
│  │   Explore | Plan | General-purpose | Custom      │    │
│  └─────────────────────────────────────────────────────┘    │
│  Isolated contexts for focused work, returns summaries  │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │         Main Conversation Context                │    │
│  │   Tools: Read, Edit, Bash, Glob, Grep, etc.     │    │
│  └─────────────────────────────────────────────────┘    │
│  Your primary interaction; limited context; costs money │
└─────────────────────────────────────────────────────────┘

Core Layer: 메인 대화 영역입니다. 모든 메시지, 파일 읽기, 도구 출력은 공유된 200K 토큰 윈도우(프리미엄의 경우 1M)의 컨텍스트를 소비합니다. 컨텍스트가 가득 차면 Claude는 이전 결정을 추적하지 못하고 품질이 저하됩니다. 이 계층은 토큰당 비용이 발생합니다.

Delegation Layer: Subagents는 깨끗한 컨텍스트로 생성되어 집중적인 작업을 수행하고 요약을 반환합니다. 탐색 결과가 메인 대화를 비대하게 만들지 않으며, 결론만 반환됩니다. 탐색에는 Haiku subagents를 사용하고(저렴하고 빠름), 구현에는 Sonnet을 사용하세요.

Extension Layer: MCP는 외부 서비스(데이터베이스, GitHub, Sentry)를 연결합니다. Hooks는 모델 동작과 관계없이 셸 명령의 실행을 보장합니다. Skills는 Claude가 자동으로 적용하는 도메인 전문 지식을 인코딩합니다. Plugins는 이 모든 것을 배포용으로 패키징합니다.

핵심 인사이트: 대부분의 사용자는 Core Layer에서만 작업하며 컨텍스트 비대화와 비용 상승을 지켜봅니다. 파워 유저는 탐색과 전문 작업을 Delegation Layer로 넘기고, Extension Layer를 자신의 워크플로우에 맞게 설정하며, Core Layer는 오케스트레이션과 최종 결정에만 사용합니다.


목차

  1. Claude Code 설치 방법
  2. 핵심 상호작용 모드
  3. 설정 시스템 심층 분석
  4. 어떤 모델을 선택해야 할까요?
  5. 권한 시스템은 어떻게 작동하나요?
  6. Hooks는 어떻게 작동하나요?
  7. MCP (Model Context Protocol)란 무엇인가요?
  8. Subagents란 무엇인가요?
  9. Extended Thinking Mode란 무엇인가요?
  10. 출력 스타일
  11. Slash Commands
  12. Skills는 어떻게 작동하나요?
  13. Plugin System
  14. Memory는 어떻게 작동하나요?
  15. 이미지 및 멀티모달 입력
  16. Git 통합은 어떻게 작동하나요?
  17. IDE에서 Claude Code 사용 방법
  18. 고급 사용 패턴
  19. Claude Code Remote란 무엇인가요?
  20. Background Agents란 무엇인가요?
  21. Claude in Chrome
  22. Claude Code in Slack
  23. Claude Code 비용은 얼마인가요?
  24. 성능 최적화
  25. 문제 디버깅 방법
  26. 엔터프라이즈 배포
  27. 키보드 단축키 레퍼런스
  28. 모범 사례

Claude Code 설치 방법

시스템 요구사항

Claude Code는 macOS 10.15+, Ubuntu 20.04+/Debian 10+, 그리고 WSL 또는 Git Bash를 통한 Windows 10+에서 실행됩니다. 시스템은 최소 4GB RAM과 활성 인터넷 연결이 필요합니다. 셸 호환성은 Bash, Zsh, Fish에서 가장 잘 작동합니다.

Windows의 경우 WSL 1과 WSL 2 모두 작동합니다. 네이티브 Windows를 선호한다면 Git Bash도 사용 가능합니다. Alpine Linux 및 기타 musl 기반 시스템은 추가 패키지가 필요합니다:

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

설치 방법

네이티브 설치 (권장)

네이티브 바이너리는 Node.js 의존성 없이 가장 깔끔한 경험을 제공합니다:

# macOS and Linux
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew alternative
brew install --cask claude-code

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

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

특정 버전 설치:

# Install specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

# Install latest explicitly
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Windows PowerShell - specific version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

NPM 설치 (더 이상 사용되지 않음)

참고: v2.1.15부터 npm 설치 시 지원 중단 알림이 표시됩니다. 이제 네이티브 바이너리가 권장 설치 방법입니다. claude install로 마이그레이션하세요.

npm이 여전히 필요한 레거시 환경의 경우:

npm install -g @anthropic-ai/claude-code

npm 설치 시 절대 sudo를 사용하지 마세요. 이후 모든 것을 복잡하게 만드는 권한 문제가 발생합니다.

기존 설치에서 마이그레이션

이전 npm 기반 설치가 있다면 네이티브 바이너리로 마이그레이션하세요:

claude install

인증 옵션

Claude Code는 세 가지 인증 경로를 지원하며, 각각 다른 장단점이 있습니다:

Claude Console (API 과금)

platform.claude.com(이전 console.anthropic.com)을 통해 Anthropic의 API에 직접 연결합니다. 계정을 만들고, 과금을 설정하고, CLI를 통해 인증하세요. 이 방식은 전체 API 접근이 가능한 사용량 기반 과금을 제공합니다. 전용 “Claude Code” 워크스페이스가 자동으로 생성됩니다. 이 워크스페이스에서는 API 키를 생성할 수 없지만 사용량을 모니터링할 수 있습니다.

Claude Pro 또는 Max 구독

claude.ai 계정 자격 증명을 사용합니다. 구독은 웹 인터페이스와 CLI 사용을 단일 월간 플랜으로 포함합니다. 예측 가능한 비용을 원하는 개인 사용자에게 과금을 단순화합니다.

엔터프라이즈 플랫폼

AWS Bedrock, Google Vertex AI, Microsoft Foundry는 각각 기존 클라우드 과금 관계와 함께 엔터프라이즈급 접근을 제공합니다:

# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=your-profile

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project

# Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name
# Optional: API key auth (otherwise uses Entra ID)
export ANTHROPIC_FOUNDRY_API_KEY=your-key

프록시 뒤에 있는 엔터프라이즈 배포나 LLM 게이트웨이를 통한 배포의 경우:

# Corporate proxy
export HTTPS_PROXY='https://proxy.example.com:8080'

# LLM gateway (skip native auth)
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL='https://your-gateway.com/bedrock'
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

검증

claude doctor

설치 유형, 버전, 시스템 설정, 감지된 문제를 보고합니다.

업데이트

Claude Code는 기본적으로 자동 업데이트되며, 시작 시와 세션 중 주기적으로 확인합니다. 업데이트는 백그라운드에서 다운로드되고 다음 실행 시 적용됩니다.

자동 업데이트 비활성화:

export DISABLE_AUTOUPDATER=1

또는 settings.json에서:

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

수동 업데이트:

claude update

제거

네이티브 설치 (macOS/Linux/WSL):

rm -f ~/.local/bin/claude
rm -rf ~/.claude-code

네이티브 설치 (Windows PowerShell):

Remove-Item -Path "$env:LOCALAPPDATA\Programs\claude-code" -Recurse -Force
Remove-Item -Path "$env:LOCALAPPDATA\Microsoft\WindowsApps\claude.exe" -Force

설정 정리 (모든 설정 삭제):

rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json

핵심 상호작용 모드

대화형 REPL

인수 없이 Claude Code를 실행하면 대화형 read-eval-print loop에 진입합니다:

cd your-project
claude

REPL은 대화 턴 간에 컨텍스트를 유지합니다. 쿼리를 직접 입력하고, 응답을 받은 후, /exit 또는 Ctrl+D로 종료할 때까지 계속 사용할 수 있습니다.

초기 프롬프트를 지정하여 세션의 초점을 맞출 수 있습니다:

claude "explain the authentication flow in this project"

전문가 팁: REPL은 압축 이벤트 간에도 상태를 유지합니다. 컨텍스트가 너무 커지면 Claude가 자동으로 이전 대화를 요약하면서 주요 결정사항과 코드 스니펫은 보존합니다. /compact로 수동으로 실행하거나, 보존할 내용에 대한 사용자 지정 지침을 추가할 수 있습니다.

비대화형 모드

출력 모드(-p)는 단일 쿼리를 실행하고 종료합니다:

# Direct query
claude -p "list all TODO comments in this project"

# Process piped input
cat error.log | claude -p "identify the root cause of these failures"

# Chain with other tools
claude -p "generate a README" > README.md

스크립트에서 파싱하기에 적합한 구조화된 출력을 얻으려면:

claude -p "count lines by file type" --output-format json

JSON 출력에는 자동화에 필요한 모든 정보가 포함됩니다:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.0034,
  "is_error": false,
  "duration_ms": 2847,
  "duration_api_ms": 1923,
  "num_turns": 4,
  "result": "Response text here...",
  "session_id": "abc-123-def"
}

스트리밍 출력을 실시간으로 처리하려면:

claude -p "build the application" --output-format stream-json | while read line; do
  echo "$line" | jq -r '.result // empty'
done

세션 관리

세션은 이어서 작업할 수 있도록 대화 기록을 유지합니다. 이는 복잡한 멀티 세션 작업에 필수적입니다:

# Continue most recent session
claude -c

# Continue with additional prompt
claude -c -p "now add error handling"

# Resume specific session by ID
claude -r "abc123" "implement the remaining tests"

# Fork a session for parallel exploration
claude -r "base-session" --fork-session "try a different approach"

명시적 ID를 사용하여 재현 가능한 세션을 생성합니다:

claude --session-id "feature-auth-$(date +%s)"

전문가 팁: 컨텍스트를 인코딩하는 세션 ID를 사용하세요: feature-${branch}-${timestamp} 또는 bug-JIRA-123. 며칠 후 돌아왔을 때 ID만으로 해당 세션의 목적을 파악할 수 있습니다. REPL 내에서 /resume을 사용하면 사용 가능한 세션을 확인할 수 있습니다.

세션은 JSONL 트랜스크립트로 저장됩니다. 에이전트 실행에는 고유한 agentId 값이 할당되며 트랜스크립트는 agent-{agentId}.jsonl로 저장됩니다. 이전 대화의 전체 컨텍스트를 보존한 채 재개할 수 있습니다.

명명된 세션 (2025년 12월): 세션을 더 쉽게 이름 지정하고 관리할 수 있습니다:

# Name current session
> /rename my-feature-work

# Resume by name or number
> /resume 1                    # Resume first session
> /resume my-feature-work      # Resume by name
claude --resume 3              # Resume from terminal

# Fork with custom session ID
claude --session-id "new-exploration" --resume "base-session" --fork-session

설정 시스템 심층 분석

Claude Code는 계층적 설정 시스템을 사용합니다. 상위 레벨이 하위 레벨을 재정의하며, 엔터프라이즈 설정은 어떤 경우에도 우회할 수 없으므로 이 계층 구조를 이해하는 것이 중요합니다.

설정 계층 구조

레벨 위치 범위 재정의 가능
엔터프라이즈 /etc/claude-code/managed-settings.json (Linux) 모든 사용자 불가
/Library/Application Support/ClaudeCode/managed-settings.json (macOS)
C:\Program Files\ClaudeCode\managed-settings.json (Windows)
CLI 플래그 명령줄 인수 현재 세션 가능
로컬 프로젝트 .claude/settings.local.json 개인, 현재 프로젝트 가능
공유 프로젝트 .claude/settings.json git을 통한 팀 공유 가능
사용자 ~/.claude/settings.json 모든 프로젝트 가능
상태 ~/.claude.json 런타임 상태, OAuth, MCP 해당 없음

전문가 팁: 공유 프로젝트에서 개인 설정에는 .claude/settings.local.json을 사용하세요—이 파일은 .gitignore에 추가해야 합니다. 버전 관리에 커밋되는 팀 전체 설정에는 .claude/settings.json을 사용하세요.

settings.json 전체 레퍼런스

주요 옵션을 모두 보여주는 종합 설정 예시입니다:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-5-20250929",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)",
      "Bash(make:*)",
      "Edit(src/**)",
      "Write(src/**)",
      "mcp__github"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Edit(package-lock.json)",
      "Edit(.git/**)"
    ],
    "ask": [
      "WebFetch",
      "Bash(curl:*)",
      "Bash(docker:*)"
    ],
    "additionalDirectories": [
      "../shared-lib",
      "../docs"
    ],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "app:*"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30,
  "outputStyle": "Explanatory",
  "language": "en",
  "respectGitignore": true,
  "showTurnDuration": true,
  "plansDirectory": ".claude/plans",
  "spinnerVerbs": ["Thinking", "Processing", "Analyzing"]
}

환경 변수 레퍼런스

인증 및 API:

ANTHROPIC_API_KEY=sk-ant-...                    # Direct API authentication
ANTHROPIC_AUTH_TOKEN=token                      # Custom authorization header
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # Additional request headers

모델 설정:

ANTHROPIC_MODEL=claude-opus-4-5                 # Override default model
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-5-20251101
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-5-20250929-v1:0
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Model for subagents
MAX_THINKING_TOKENS=10000                       # Enable extended thinking
CLAUDE_CODE_MAX_OUTPUT_TOKENS=4000              # Limit output length

클라우드 프로바이더 설정:

CLAUDE_CODE_USE_BEDROCK=1                       # Use AWS Bedrock
CLAUDE_CODE_USE_VERTEX=1                        # Use Google Vertex AI
CLAUDE_CODE_USE_FOUNDRY=1                       # Use Microsoft Foundry
ANTHROPIC_BEDROCK_BASE_URL=https://...          # Custom Bedrock endpoint
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1                 # Skip Bedrock auth (for gateways)
CLAUDE_CODE_SKIP_VERTEX_AUTH=1                  # Skip Vertex auth
AWS_BEARER_TOKEN_BEDROCK=token                  # Bedrock bearer token
VERTEX_REGION_CLAUDE_3_7_SONNET=us-west1        # Override Vertex region

동작 제어:

DISABLE_AUTOUPDATER=1                           # Prevent automatic updates
DISABLE_TELEMETRY=1                             # Opt out of usage telemetry
DISABLE_ERROR_REPORTING=1                       # Disable Sentry
DISABLE_BUG_COMMAND=1                           # Disable /bug command
DISABLE_COST_WARNINGS=1                         # Hide cost warnings
DISABLE_PROMPT_CACHING=1                        # Disable prompt caching globally
DISABLE_PROMPT_CACHING_SONNET=1                 # Disable for Sonnet only
DISABLE_PROMPT_CACHING_OPUS=1                   # Disable for Opus only
DISABLE_NON_ESSENTIAL_MODEL_CALLS=1             # Skip non-critical API calls

도구 설정:

BASH_DEFAULT_TIMEOUT_MS=30000                   # Bash command timeout (30s)
BASH_MAX_TIMEOUT_MS=600000                      # Maximum bash timeout (10min)
BASH_MAX_OUTPUT_LENGTH=50000                    # Bash output limit
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1     # Reset CWD after each bash
MCP_TIMEOUT=5000                                # MCP server startup timeout
MCP_TOOL_TIMEOUT=30000                          # MCP tool execution timeout
MAX_MCP_OUTPUT_TOKENS=25000                     # MCP output limit
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # Slash command context limit

네트워크 및 프록시:

HTTP_PROXY=http://proxy:8080                    # HTTP proxy
HTTPS_PROXY=https://proxy:8080                  # HTTPS proxy
NO_PROXY=localhost,example.com                  # Bypass proxy for domains
CLAUDE_CODE_CLIENT_CERT=/path/to/cert           # mTLS certificate
CLAUDE_CODE_CLIENT_KEY=/path/to/key             # mTLS private key
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE=pass          # mTLS passphrase

UI 및 터미널:

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1            # Don't update terminal title
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # Skip IDE extension install
CLAUDE_CODE_SHELL=/bin/zsh                      # Override shell detection
USE_BUILTIN_RIPGREP=1                           # Use included ripgrep (default)
CLAUDE_CONFIG_DIR=~/.myconfig                   # Custom config directory
IS_DEMO=1                                       # Hide sensitive UI elements[^37]
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # Disable background tasks and Ctrl+B[^46]
CLAUDE_CODE_TMPDIR=/path/to/tmp                 # Override temp directory[^50]

디버깅:

ANTHROPIC_LOG=debug                             # Enable API request logging

어떤 모델을 선택해야 할까요?

각 작업에 적합한 모델을 선택하면 비용과 품질 모두에 큰 영향을 미칩니다. Claude Code는 여러 수준에서 유연한 모델 전환을 제공합니다.

사용 가능한 모델

별칭 모델 적합한 용도 입력/1M 출력/1M
sonnet Claude Sonnet 4.5 일상적인 코딩, 균형 잡힌 성능 $3.00 $15.00
opus Claude Opus 4.5 복잡한 추론, 아키텍처 $5.00 $25.00
haiku Claude Haiku 4.5 간단한 작업, 빠른 처리 $1.00 $5.00
default 계정에 따라 다름 일반 용도 다양함 다양함
sonnet[1m] 1M 컨텍스트의 Sonnet 대규모 코드베이스 $6.00 $22.50
opusplan Opus (계획) + Sonnet (실행) 복잡한 리팩토링 혼합 혼합

이러한 가격 차이가 중요한 이유: 일반적인 코딩 세션은 50K-200K 입력 토큰과 10K-50K 출력 토큰을 소비합니다. Haiku를 사용하면 세션당 $0.10-$0.45입니다. Opus를 사용하면 동일한 세션이 $0.50-$2.25로 5배 더 비쌉니다. Opus는 진정으로 어려운 문제에만 사용하세요.1

각 모델을 사용해야 할 때

Haiku: 탐색을 수행하는 subagent, 간단한 파일 검색, 빠른 질문에 사용하세요. Opus보다 10-20배 저렴하고 응답도 빠릅니다. 깊은 추론이 필요 없는 백그라운드 작업에 완벽합니다.

Sonnet: 일상적인 개발의 주력 모델입니다. 기능 구현, 버그 수정, 테스트 작성, 코드 리뷰 등 대부분의 코딩 작업을 잘 처리합니다. 기본 모델로 사용하세요.

Opus: 진정으로 복잡한 추론이 필요할 때 사용하세요: 아키텍처 결정, 까다로운 디버깅, 복잡한 시스템 이해, 보안 분석. 어려운 문제에서 품질 차이는 분명하지만 비용도 마찬가지입니다. Opus 4.5는 이전 버전 대비 토큰 사용량을 절반으로 줄이면서 SWE-bench Verified에서 80.9%를 달성했습니다.45 참고: Pro 구독 사용자는 이제 구독의 일부로 Opus 4.5에 접근할 수 있습니다.20

Opusplan: Opus를 계획(추론 품질이 가장 중요한 곳)에 사용하고 Sonnet을 실행(속도가 중요한 곳)에 사용하는 하이브리드 모드입니다. 최고의 계획이 필요하지만 개별 편집마다 Opus 수준의 추론이 필요하지 않은 복잡한 리팩토링에 탁월합니다.

모델 전환하기

세션 중:

> /model opus
> /model sonnet
> /model haiku

시작 시:

claude --model opus

환경 변수를 통해:

export ANTHROPIC_MODEL=opus

settings.json에서:

{
  "model": "claude-sonnet-4-5-20250929"
}

subagent 전용:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

확장 컨텍스트

대규모 코드베이스나 긴 세션의 경우 1M 토큰 컨텍스트를 활성화하세요:

claude --model sonnet[1m]

또는 세션 내에서:

> /model anthropic.claude-sonnet-4-5-20250929-v1:0[1m]

확장 컨텍스트는 토큰당 비용이 더 높습니다. 기본값이 아닌, 실제로 필요할 때 사용하세요.

현재 모델 확인

> /status

현재 모델, 계정 정보, 적용된 설정 및 기타 세션 상태를 보여줍니다.


의사결정 프레임워크

기능의 존재를 아는 것만으로는 충분하지 않습니다—각각을 언제 사용해야 하는지 알아야 합니다. 이러한 의사결정 트리는 지식을 행동으로 전환합니다.

어떤 모델을 사용해야 할까요?

시작 → 작업이 간단한가요? (파일 검색, 빠른 질문, 포맷팅)
         │
         ├── 예 → Haiku 사용
         │         비용: 작업당 ~$0.03
         │         속도: 가장 빠름
         │
         └── 아니오 → 깊은 추론이 필요한가요?
                  (아키텍처, 복잡한 디버깅, 보안 분석)
                  │
                  ├── 예 → Opus 사용
                  │         비용: 작업당 ~$2.00
                  │         품질: 최고
                  │
                  └── 아니오 → Sonnet 사용 (기본값)
                           비용: 작업당 ~$0.75
                           균형: 전반적으로 최고

경험칙: Sonnet으로 시작하세요. subagent에는 Haiku로 낮추세요. Sonnet의 답변이 피상적으로 느껴질 때만 Opus로 올리세요.

Command vs Skill vs Subagent?

실행 시점을 명시적으로 제어하고 싶나요?
│
├── 예 → Slash Command 사용
│         예시: /deploy, /test, /security-review
│         직접 호출합니다. 타이밍을 제어합니다.
│
└── 아니오 → 컨텍스트에 따라 전문 지식이 자동으로 적용되어야 하나요?
         │
         ├── 예 → Skill 사용
         │         예시: 보안 패턴, 도메인 규칙, 코드 표준
         │         Claude가 컨텍스트를 인식하고 전문 지식을 적용합니다.
         │
         └── 아니오 → 작업에 격리된 컨텍스트가 필요한가요?
                  │
                  ├── 예 → Subagent 사용
                  │         예시: 심층 탐색, 병렬 분석
                  │         메인 대화의 컨텍스트 비대화를 방지합니다.
                  │
                  └── 아니오 → 직접 프롬프트
                           모든 것에 추상화가 필요한 것은 아닙니다.

Hook vs Prompt?

Claude의 판단과 관계없이 해당 작업이 항상 실행되어야 하나요?
│
├── 예 → Hook 사용 (결정론적)
│         예시:
│         - 모든 편집 후 코드 포맷팅
│         - 모든 bash 명령 로깅
│         - .env 파일 접근 차단
│         Claude는 건너뛰거나, 잊거나, 다르게 결정할 수 없습니다.
│
└── 아니오 → Prompt 사용 (확률론적)
         예시:
         - "테스트 추가를 고려하세요"
         - "엣지 케이스에 대해 생각하세요"
         - "관련이 있다면 보안을 검토하세요"
         Claude가 컨텍스트에 따라 결정합니다.

Extended Thinking을 언제 사용해야 할까요?

이것이 진정으로 어려운 문제인가요?
│
├── 많은 트레이드오프가 있는 아키텍처 결정 → 예, thinking 사용
├── 근본 원인이 불분명한 복잡한 디버깅 → 예, thinking 사용
├── 신중한 추론이 필요한 보안 분석 → 예, thinking 사용
├── 익숙하지 않은 코드베이스 이해 → 예, thinking 사용
│
├── 일상적인 버그 수정 → 아니오, thinking 건너뛰기
├── 간단한 리팩토링 → 아니오, thinking 건너뛰기
├── 코드 포맷팅 → 아니오, thinking 건너뛰기
└── 빠른 질문 → 아니오, thinking 건너뛰기

세션 중 Tab으로 전환합니다. 더 높은 thinking 예산은 비용이 더 듭니다—최소값으로 시작하고 응답이 급하게 느껴질 때만 늘리세요.


권한 시스템은 어떻게 작동하나요?

Claude Code의 권한 시스템은 어떤 작업을 실행할 수 있는지에 대한 세밀한 제어를 제공합니다. 이를 이해하는 것은 보안과 워크플로우 효율성 모두에 필수적입니다.

권한 계층

읽기 전용 도구 (자동 승인): - Read - 파일 내용 읽기 - Glob - 패턴으로 파일 찾기 - Grep - 파일 내용 검색 - WebSearch - 웹 검색 - LSP - 코드 인텔리전스 (정의로 이동, 참조 찾기, 호버 문서)25

LSP Tool 기능 (v2.0.74+): LSP tool은 IDE와 같은 코드 인텔리전스를 제공합니다: - 정의로 이동: 심볼이 정의된 곳으로 점프 - 참조 찾기: 코드베이스 전체에서 심볼의 모든 사용처 나열 - 호버 문서: 모든 심볼에 대한 타입 정보와 문서 가져오기 - TypeScript, Python, Go, Rust 및 LSP를 지원하는 다른 언어와 함께 작동 - 언어 서버가 사용 가능해야 합니다 (일반적으로 도구 체인과 함께 설치됨)

수정 도구 (승인 필요): - Edit - 기존 파일 수정 - Write - 새 파일 생성 - Bash - 셸 명령 실행 - WebFetch - URL 내용 가져오기 - NotebookEdit - Jupyter 노트북 수정

수정 도구가 처음 실행될 때 Claude Code는 승인을 요청합니다. 승인은 명시적으로 다르게 설정하지 않는 한 세션 동안 유지됩니다.

권한 모드

모드 동작 사용 사례
default 각 도구의 첫 사용 시 프롬프트 일반 개발
acceptEdits 파일 편집 자동 승인, bash에는 프롬프트 신뢰할 수 있는 프로젝트
plan 실행이나 편집 불가 분석만
bypassPermissions 모든 프롬프트 건너뛰기 CI/CD 자동화

YOLO Mode (v2.0.68+): 완전히 자율적인 작동을 위해 --dangerously-skip-permissions 플래그를 사용하세요. 이것은 모든 것에 예라고 합니다—파일 편집, bash 명령, 모든 도구 호출. “dangerous”라는 단어는 의도적입니다. 샌드박스된 환경이나 코드베이스를 완전히 신뢰할 때 사용하세요.61

claude --dangerously-skip-permissions

CLI를 통해 모드 설정:

claude --permission-mode acceptEdits

세션 중 전환:

Shift+Tab  # 모드 순환

settings.json에서:

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

권한 규칙 구문

세밀한 규칙이 특정 작업을 제어합니다. 규칙은 순서대로 평가됩니다: 첫 번째 일치가 적용됩니다.

Bash 명령 패턴:

{
  "allow": [
    "Bash(npm run build)",
    "Bash(npm run test:*)",
    "Bash(git commit:*)",
    "Bash(make:*)"
  ],
  "deny": [
    "Bash(rm -rf:*)",
    "Bash(sudo:*)",
    "Bash(curl|wget:*)"
  ]
}

별표는 접두사 매칭을 제공합니다: Bash(npm run test:*)npm run test, npm run test:unit, npm run test:integration을 허용합니다.

중요한 제한사항: Bash 패턴은 정규식이 아닌 접두사만 일치합니다. Bash(curl http:*)와 같은 패턴은 curl -X GET http://...와 일치하지 않습니다. 옵션이 URL 앞에 오기 때문입니다. 강력한 차단을 위해서는 명령 자체를 거부하세요: Bash(curl:*).

파일 작업 패턴:

{
  "allow": [
    "Edit(src/**)",
    "Write(src/**)",
    "Read(docs/**)"
  ],
  "deny": [
    "Read(.env*)",
    "Read(secrets/**)",
    "Edit(.git/**)",
    "Edit(node_modules/**)"
  ]
}

경로 구문: - 상대 경로: Edit(src/**) - 작업 디렉토리 기준 - 설정 파일 기준 절대 경로: Edit(/build/**) - 설정 파일 위치 기준 - 진정한 절대 경로: Edit(//tmp/**) - //로 시작 - 홈 디렉토리: Read(~/.zshrc)

MCP tool 패턴:

{
  "allow": [
    "mcp__github",
    "mcp__database__query",
    "mcp__myserver__*"
  ],
  "deny": [
    "mcp__dangerous_server",
    "mcp__untrusted__*"
  ]
}

와일드카드 구문 mcp__server__*를 사용하여 특정 MCP 서버의 모든 도구를 허용하거나 거부하세요.39 이는 신뢰할 수 있는 서버의 모든 도구를 빠르게 활성화하거나 신뢰할 수 없는 소스의 전체 서버를 차단하는 데 유용합니다.

WebFetch 패턴:

{
  "allow": [
    "WebFetch(domain:github.com)",
    "WebFetch(domain:api.example.com)"
  ]
}

추가 디렉토리

현재 프로젝트 외부로 Claude의 접근을 확장하세요:

{
  "permissions": {
    "additionalDirectories": [
      "../shared-lib",
      "../docs",
      "~/reference-projects/design-system"
    ]
  }
}

이는 모노레포나 Claude가 형제 디렉토리의 코드를 참조해야 할 때 필수적입니다.

Sandbox Mode

파일 시스템 및 네트워크 격리를 활성화하세요:

> /sandbox

또는 설정에서 구성:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"],
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"],
      "allowLocalBinding": true
    }
  }
}

샌드박스 적용 시: - 파일 시스템 접근이 프로젝트 디렉토리로 제한됨 - 네트워크 접근이 제어됨 - 특정 명령이 샌드박스 제한에서 제외됨 - autoAllowBashIfSandboxed가 true면 Bash 명령이 자동 허용됨

전문가 팁: Sandbox mode는 신뢰할 수 없는 코드베이스에서 Claude를 실행할 때 탁월합니다. 익숙하지 않은 프로젝트를 탐색하거나 추가 보호 계층이 필요할 때 활성화하세요. Anthropic 내부 테스트에 따르면 샌드박싱은 권한 프롬프트를 84% 줄입니다.45


Hook은 어떻게 작동하나요?

Hook은 Claude Code 워크플로우의 특정 시점에서 결정론적 셸 명령을 실행합니다. Claude에게 작업을 수행하도록 프롬프트하는 것과 달리, Hook은 모델 동작과 관계없이 실행을 보장합니다. 팀 표준을 적용하고 반복 작업을 자동화하는 데 필수적입니다.

프롬프트 대신 Hook을 사용하는 이유: Claude에게 “파일 편집 후 항상 Prettier를 실행하세요”라고 지시하면 가끔은 작동합니다. 하지만 Claude가 잊어버리거나, 속도를 우선시하거나, 변경 사항이 “너무 작다”고 판단할 수 있습니다. Hook은 실행을 보장합니다—모든 Edit 또는 Write가 포매터를 트리거하며, 매번, 예외 없이 실행됩니다. 규정 준수, 보안, 팀 표준을 위해서는 확률적 방식보다 결정론적 방식이 더 낫습니다.7

사용 가능한 이벤트

이벤트 타이밍 차단 가능 목적
PreToolUse 도구 실행 전 작업 검증, 로깅 또는 차단
PostToolUse 도구 완료 후 아니오 출력 포맷팅, 린터 실행, 빌드 트리거
UserPromptSubmit 사용자가 프롬프트 전송 시 컨텍스트 추가, 입력 검증, 데이터 주입
Notification 알림 트리거 시 아니오 사용자 정의 알림 처리
Stop Claude가 응답 완료 시 아니오 정리, 로깅, 메트릭
SubagentStart Subagent 생성 시 아니오 에이전트 유형 로깅, additionalContext를 통한 컨텍스트 주입
SubagentStop Subagent 완료 시 아니오 작업 추적, agent_transcript_path 캡처
Setup 초기화/유지보수 실행 시 아니오 --init, --init-only, --maintenance를 통한 환경 설정
SessionStart 세션 시작 시 환경 설정, 검증
SessionEnd 세션 종료 시 아니오 정리, 최종 로깅
PreCompact 컨텍스트 압축 전 아니오 검증, 로깅
PermissionRequest 권한 대화상자 표시 시 사용자 정의 승인 로직

Hook 설정

settings.json 또는 전용 hooks.json에서 Hook을 정의합니다:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/inject-context.sh"
          }
        ]
      }
    ]
  }
}

Matcher

matcher 필드는 어떤 도구가 Hook을 트리거할지 결정합니다:

{"matcher": "*"}              // Match all tools
{"matcher": "Bash"}           // Match Bash only
{"matcher": "Edit|Write"}     // Match Edit or Write
{"matcher": "mcp__github"}    // Match MCP server tools
{"matcher": ""}               // Match for events without tools (like UserPromptSubmit)

Hook 입출력 프로토콜

Hook은 stdin으로 JSON을 받습니다:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123"
}

종료 코드가 동작을 제어합니다: - 0: 성공—작업이 진행됩니다. stdout은 verbose 모드(Ctrl+O)에서 표시됩니다. UserPromptSubmitSessionStart의 경우, stdout이 컨텍스트에 추가됩니다. - 2: 차단 오류—작업이 중단됩니다. stderr이 Claude에게 전달되는 오류 메시지가 됩니다. - 1, 3 등: 비차단 오류—작업이 계속됩니다. stderr은 verbose 모드에서 경고로 표시됩니다.

고급 제어를 위해 Hook은 JSON을 출력할 수 있습니다:

{
  "decision": "allow",
  "message": "Command validated and modified",
  "modifications": {
    "tool_input": {
      "command": "npm test -- --coverage"
    }
  }
}

ask 권한이 있는 PreToolUse Hook (v2.1.0+): PreToolUse Hook은 이제 “ask” 권한 결정을 사용할 때 updatedInput을 반환할 수 있어, Hook이 미들웨어 역할을 하면서도 사용자 동의를 요청할 수 있습니다.39

{
  "decision": "ask",
  "message": "Modified command requires approval",
  "updatedInput": {
    "command": "npm test -- --coverage --ci"
  }
}

additionalContext가 있는 PreToolUse Hook (v2.1.9+): Hook은 additionalContext를 반환하여 모델에 컨텍스트를 주입할 수 있습니다. 이는 모델이 고려해야 할 동적 정보(API 문서, 데이터베이스 스키마, 환경 상태)를 제공하는 데 유용합니다.51

{
  "decision": "allow",
  "additionalContext": "Note: This database has a 5-second query timeout. Complex joins may need optimization."
}

additionalContext 문자열은 해당 턴의 모델 컨텍스트에 추가되어, 대화를 영구적으로 수정하지 않고도 추론에 활용할 수 있습니다.

실용적인 Hook 예제

편집 후 TypeScript 파일 자동 포맷:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.ts ]] && npx prettier --write \"$FILE_PATH\" || true'"
          }
        ]
      }
    ]
  }
}

모든 bash 명령 로깅:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/bash-history.log"
          }
        ]
      }
    ]
  }
}

민감한 파일에 대한 접근 차단:

#!/bin/bash
# .claude/hooks/protect-files.sh
data=$(cat)
path=$(echo "$data" | jq -r '.tool_input.file_path // empty')

if [[ "$path" == *".env"* ]] || [[ "$path" == *"secrets/"* ]] || [[ "$path" == *".pem"* ]]; then
  echo "Blocked: Cannot access sensitive file $path" >&2
  exit 1
fi
exit 0

코드 변경 후 테스트 실행:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.test.ts ]] || npm run test:affected'"
          }
        ]
      }
    ]
  }
}

사용자 정의 알림 시스템:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Waiting for your input'"
          }
        ]
      }
    ]
  }
}

프롬프트에 동적 컨텍스트 주입:

#!/bin/bash
# .claude/hooks/inject-context.sh
# Add current git branch and recent commits to every prompt

branch=$(git branch --show-current 2>/dev/null)
commits=$(git log --oneline -3 2>/dev/null | tr '\n' ' ')

if [ -n "$branch" ]; then
  echo "[Context: Branch '$branch', Recent: $commits]"
fi
exit 0

Hook 디버깅

Hook 문제를 해결하려면 디버그 모드를 활성화하세요:

claude --debug

다음 내용이 로깅됩니다: - Hook 실행 시간 - 입출력 데이터 - 오류 메시지 및 스택 트레이스 - 결정 결과 (allow/reject/ask)

컴포넌트 범위 Hook (v2.1.0+)

Hook은 frontmatter를 사용하여 Skill, subagent, slash command에서 직접 정의할 수 있습니다. 이러한 Hook은 컴포넌트의 수명 주기로 범위가 지정되며 해당 컴포넌트가 활성화된 경우에만 실행됩니다.41

임베디드 Hook이 있는 Skill:

---
name: secure-deployment
description: Deployment skill with security validation
hooks:
  PreToolUse:
    - matcher: Bash
      command: ".claude/hooks/validate-deploy.sh"
  PostToolUse:
    - matcher: Bash
      command: ".claude/hooks/log-deploy.sh"
  Stop:
    - command: ".claude/hooks/cleanup.sh"
      once: true  # Run only once per session
---

지원되는 이벤트: PreToolUse, PostToolUse, Stop

once 옵션(Skill과 slash command에서만 사용 가능)은 Hook이 세션당 한 번만 실행되도록 보장합니다—정리 또는 마무리 작업에 유용합니다.

장시간 실행 세션 전략

야간 또는 무인 Claude Code 세션의 경우, 수동 개입 없이 Claude가 제대로 작동하도록 Hook을 설정하세요. 핵심 인사이트: 린팅 및 테스트 Hook을 가드레일로 사용하여 Claude가 계속 진행하기 전에 문제를 수정하도록 강제합니다.64

“테스트가 통과할 때까지 멈추지 않기” 패턴:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint && npm run typecheck",
            "timeout": 60000
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm test || echo 'Tests failing - Claude should fix before stopping'"
          }
        ]
      }
    ]
  }
}

야간 세션 전략:

  1. 사전 점검: Setup Hook을 사용하여 환경이 준비되었는지 확인
  2. 지속적인 검증: PostToolUse Hook이 각 변경 후 테스트 실행
  3. 완료 게이트: Stop Hook이 Claude가 “완료”를 선언하기 전에 모든 수락 기준을 확인
  4. 알림: Stop Hook이 Claude가 완료하거나 막혔을 때 Slack/Pushover를 통해 알림 가능

완전 자율 야간 실행을 위해 샌드박스 컨테이너에서 --dangerously-skip-permissions와 함께 사용하세요. Claude는 테스트가 통과하거나 옵션이 소진될 때까지 계속 반복합니다.


MCP(Model Context Protocol)란?

MCP는 표준화된 프로토콜을 통해 Claude Code에 외부 도구, 데이터베이스, API 및 서비스에 대한 접근 권한을 확장합니다. MCP 생태계는 폭발적으로 성장하여, 현재 월간 1억 회 다운로드와 MCP.so에 인덱싱된 3,000개 이상의 서버를 보유하고 있으며(2026년 1월 기준), AI를 도구 및 데이터에 연결하는 업계 표준으로 자리매김했습니다.354 Claude를 기존 도구 체인에 통합하려면 MCP에 대한 이해가 필수적입니다.

MCP가 개발자에게 중요한 이유: MCP 없이 Claude Code는 파일 읽기와 bash 명령 실행만 가능합니다. MCP를 사용하면 Claude가 프로덕션 데이터베이스를 쿼리하고, Jira 티켓을 생성하고, GitHub PR을 리뷰하고, Sentry 오류를 확인하고, 팀이 사용하는 모든 API와 상호작용할 수 있습니다—모두 자연어 요청으로 가능합니다. 이 프로토콜은 AI 도구가 외부 서비스에 연결하는 방식을 표준화하여 벤더 종속을 방지합니다.

원격 MCP 지원 (2025년 6월)

Claude Code는 이제 네이티브 OAuth 인증을 통한 원격 MCP 서버를 지원합니다.28 로컬 서버를 관리할 필요 없이 도구와 데이터 소스에 연결할 수 있으며, 한 번만 인증하면 Claude Code가 토큰 갱신을 자동으로 처리합니다.

# Connect to remote MCP server with OAuth
claude mcp add --transport http linear https://mcp.linear.app/sse
# Browser opens for OAuth flow, tokens stored securely

MCP Tool Search (v2.1.7+)

MCP 서버의 기능이 확장되면서(일부 서버는 50개 이상의 도구를 제공) 도구 설명이 과도한 컨텍스트를 소비하기 시작했습니다. MCP Tool Search는 필요할 때만 도구 설명을 동적으로 로드하여 이 문제를 해결합니다—AI 도구를 위한 일종의 지연 로딩입니다.54

성능 영향: 내부 벤치마크에서 극적인 정확도 향상을 보여줍니다: - Opus 4: MCP 평가에서 49% → 74% - Opus 4.5: MCP 평가에서 79.5% → 88.1% - 토큰 오버헤드 감소: 85%

작동 방식: MCP 도구 설명이 컨텍스트 윈도우의 10%(기본 임계값)를 초과하면, Claude Code는 실제로 필요할 때까지 전체 설명 로드를 지연합니다. Claude는 도구 이름만 확인하고 설명은 필요 시 가져옵니다.

설정:

{
  "mcpToolSearchAutoEnable": "auto:15"  // Enable when tools exceed 15% of context
}

값: - true - 항상 Tool Search 활성화 - false - 항상 비활성화 (모든 도구 설명을 미리 로드) - auto:N - 도구가 컨텍스트의 N%를 초과하면 활성화 (0-100)

전문가 팁: Tool Search를 활성화하면 컨텍스트 제한을 걱정하지 않고 더 많은 MCP 서버에 연결할 수 있습니다. 95%의 컨텍스트 감소로 인해 이전에 컨텍스트를 두고 경쟁하던 서버들이 이제 평화롭게 공존할 수 있습니다.

대화형 MCP 설정 마법사

인수 없이 claude mcp add를 실행하면 MCP 서버 추가를 위한 단계별 인터페이스가 시작됩니다. 마법사가 전송 유형 선택, 인증 및 설정을 안내합니다.15

전송 유형

HTTP (원격 서버에 권장):

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# With authentication
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer $API_TOKEN"

SSE (사용 중단 예정이지만 작동):

claude mcp add --transport sse asana https://mcp.asana.com/sse \
  --header "X-API-Key: your-key"

Stdio (로컬 서버):

# PostgreSQL
claude mcp add --transport stdio postgres \
  --env "DATABASE_URL=postgresql://user:pass@localhost/db" \
  -- npx -y @anthropic-ai/mcp-server-postgres

# Custom server
claude mcp add --transport stdio custom -- python /path/to/server.py --port 8000

Windows에서는 stdio에 cmd 래퍼가 필요합니다:

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

범위 관리

MCP 서버는 세 가지 범위에 존재하며 명확한 우선순위를 가집니다(로컬이 프로젝트를, 프로젝트가 사용자를 재정의):

범위 저장 위치 가시성 사용 사례
로컬 ~/.claude.json (프로젝트 경로) 본인만, 해당 프로젝트 개인 API 키
프로젝트 .mcp.json git을 통해 전체 팀 공유 통합
사용자 ~/.claude.json (루트) 본인, 모든 프로젝트 개인 도구

설치 시 범위를 지정할 수 있습니다:

claude mcp add --scope project --transport http github https://...
claude mcp add --scope user --transport stdio personal-tool -- ./my-tool

설정 파일 형식

.mcp.json 파일은 프로젝트 수준의 서버를 정의합니다:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${SENTRY_API_KEY}"
      }
    },
    "internal-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "X-API-Key": "${INTERNAL_API_KEY}"
      }
    }
  }
}

환경 변수는 ${VAR} 구문을 사용하여 확장되며, 선택적 기본값을 지정할 수 있습니다: ${VAR:-default}.

MCP 관리 명령어

claude mcp list                      # View all configured servers
claude mcp get github                # Get specific server details
claude mcp remove github             # Remove a server
claude mcp reset-project-choices     # Reset project-scoped approvals
claude mcp add-from-claude-desktop   # Import from Claude Desktop
claude mcp add-json weather '{"type":"http","url":"..."}'  # Add from JSON

# Within Claude Code REPL
> /mcp                               # Interactive MCP management

OAuth 인증

OAuth가 필요한 서버의 경우:

> /mcp
# Follow browser-based OAuth flow
# Tokens stored securely and auto-refreshed
# Use "Clear authentication" to revoke access

MCP 리소스 및 프롬프트 사용

리소스 참조:

@github:issue://123
@postgres:schema://users
@docs:file://api/authentication

MCP 프롬프트를 슬래시 명령으로 사용:

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug title" high

출력 제한

MCP 출력은 컨텍스트 오버플로를 방지하기 위해 제한됩니다: - 경고 임계값: 10,000 토큰 - 기본 최대값: 25,000 토큰

필요 시 증가할 수 있습니다:

export MAX_MCP_OUTPUT_TOKENS=50000

주요 MCP 서버

서버 용도 주요 기능
GitHub 저장소 관리 PR, 이슈, CI/CD, 코드 리뷰
PostgreSQL 데이터베이스 접근 쿼리, 스키마 검사, 데이터 분석
Sentry 오류 모니터링 오류 조회, 스택 트레이스, 배포 상관관계
Linear 프로젝트 관리 이슈, 프로젝트, 스프린트
Jira/Atlassian 엔터프라이즈 PM 티켓, 보드, 워크플로
Playwright 웹 자동화 E2E 테스트, 접근성 트리
Stripe 결제 거래 조회, 고객 데이터
Cloudflare 인프라 DNS, 워커, 분석
Supabase 서비스형 백엔드 데이터베이스, 인증, 스토리지
Context7 문서 실시간 버전별 라이브러리 문서
Figma Dev Mode 디자인-코드 변환 레이어 계층, 자동 레이아웃, 토큰42
Sequential Thinking 문제 해결 구조화된 추론, 반성적 프로세스43
Magic UI 컴포넌트 React + Tailwind 마케팅 컴포넌트

실전 MCP 패턴

GitHub 워크플로:

> Review PR #456
> List all open issues assigned to me
> Create a bug issue for the authentication failure we found

데이터베이스 쿼리:

> What's our total revenue this quarter?
> Show the schema for the users table
> Find customers with no purchases in 90 days

오류 모니터링:

> What errors occurred in production today?
> Show the stack trace for error ABC123
> Which deployment introduced these errors?

엔터프라이즈 MCP 설정

시스템 관리자는 managed-mcp.json을 통해 MCP 정책을 적용할 수 있습니다:

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "sentry" },
    { "serverCommand": ["npx", "-y", "@approved/server"] }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" }
  ]
}

위치: - macOS: /Library/Application Support/ClaudeCode/managed-mcp.json - Linux: /etc/claude-code/managed-mcp.json - Windows: C:\ProgramData\ClaudeCode\managed-mcp.json

거부 목록이 절대적인 우선순위를 가집니다. 명령은 인수 순서를 포함하여 정확히 일치해야 합니다.

MCP Apps (2026년 1월)

Anthropic은 Claude 인터페이스 내에서 직접 대화형 도구 UI를 구현할 수 있는 Model Context Protocol의 확장인 MCP Apps를 출시했습니다.78 MCP Apps를 사용하면 사용자가 Claude를 떠나지 않고도 외부 서비스의 콘텐츠를 보고, 편집하고, 상호작용할 수 있습니다—Asana, Box, Canva, Figma, Hex, monday.com, Slack 등을 포함합니다. 모든 MCP 서버가 Claude 내부에서 렌더링되는 대화형 UI를 제공할 수 있습니다. MCP Apps는 현재 claude.ai 웹 인터페이스에 표시되지만, 서버들이 새로운 대화형 기능을 채택함에 따라 기반이 되는 MCP 프로토콜 확장은 Claude Code의 MCP 생태계에도 관련이 있습니다.

API 플랫폼: Code Execution Tool v2 (2026년 1월)

Anthropic은 기존의 Python 전용 샌드박스를 Bash 명령 실행과 직접 파일 조작으로 대체한 Code Execution Tool v2를 퍼블릭 베타로 출시했습니다.79 주요 변경 사항: - 샌드박스 컨테이너에서 Bash 명령 실행 (Python뿐만 아니라) - 모든 언어로 코드 작성 및 실행 - 프로그래밍 방식 도구 호출 (퍼블릭 베타): Claude가 코드 실행 내에서 도구를 호출하여 다중 도구 워크플로에서 지연 시간과 토큰 사용량을 줄일 수 있습니다

이는 주로 API 사용자에게 영향을 미치지만, Claude Code의 클라우드 실행 기능의 방향성을 보여줍니다.


Subagent란 무엇인가요?

Subagent는 복잡한 작업을 독립적으로 처리하는 특화된 Claude 인스턴스입니다. Claude Code에서 가장 강력한 기능 중 하나이면서 가장 이해가 부족한 기능이기도 합니다. Subagent를 마스터하면 수행할 수 있는 작업의 범위가 크게 확장됩니다.

Subagent가 존재하는 이유: Claude Code의 메인 대화에는 단일 컨텍스트 윈도우가 있습니다. 논의하는 모든 내용, Claude가 읽는 모든 파일, 모든 도구 출력이 해당 컨텍스트를 소비합니다. 긴 세션에서는 컨텍스트가 가득 차고, Claude가 이전 결정을 놓치며, 성능이 저하됩니다. Subagent는 작업을 격리하여 이 문제를 해결합니다: 탐색 결과가 메인 대화를 비대하게 만들지 않고 요약만 반환됩니다. Claude는 또한 최대 10개의 subagent를 병렬로 실행할 수 있어, 순차적으로는 불가능한 동시 작업이 가능합니다.2

Subagent 작동 방식

Claude가 집중적인 주의가 필요한 작업—심층 탐색, 다단계 분석, 전문 작업—을 만나면 subagent를 생성할 수 있습니다. Subagent는:

  1. 깨끗한 컨텍스트로 시작합니다(메인 대화의 오염 없음)
  2. 지정된 도구에 접근할 수 있습니다
  3. 특정 모델로 작동합니다(종종 더 저렴하고 빠른 모델)
  4. 메인 대화에 결과를 반환합니다

이 아키텍처는 복잡한 워크플로우를 가능하게 하면서 컨텍스트 오버플로우를 방지합니다.

내장 Subagent 유형

Explore (빠름, 읽기 전용): - 모델: Haiku (초고속) - 모드: 엄격한 읽기 전용 - 도구: Glob, Grep, Read, 안전한 bash 명령어 (ls, git status, git log, git diff, find, cat, head, tail) - 철저함 수준: Quick, Medium, Very thorough - 용도: 코드베이스 탐색, 파일 찾기, 구조 파악

General-purpose: - 모델: Sonnet - 모드: 전체 읽기/쓰기 - 도구: 모든 사용 가능한 도구 - 용도: 복잡한 연구 + 수정 작업

Plan: - 모델: Sonnet (또는 opusplan과 함께 Opus) - 모드: 읽기 전용 - 도구: Read, Glob, Grep, Bash - 용도: 실행 전 복잡한 구현 계획

Subagent 트리거하기

Claude는 작업 유형에 따라 자동으로 subagent에 위임합니다. 명시적으로 요청할 수도 있습니다:

> Use the explore agent to find all authentication-related files

> Have a subagent analyze the database schema thoroughly

> Spawn an agent to research how error handling works in this codebase

전문가 팁: 복잡한 작업의 경우 명시적으로 subagent 위임을 요청하세요. “Use an explore agent to find…”는 메인 대화의 컨텍스트 비대화를 방지합니다.

커스텀 Subagent 만들기

.claude/agents/ (프로젝트) 또는 ~/.claude/agents/ (개인)에서 subagent를 정의하세요:

---
name: security-reviewer
description: Expert security code reviewer. Use PROACTIVELY after any code changes to authentication, authorization, or data handling.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

You are a senior security engineer reviewing code for vulnerabilities.

When invoked:
1. Identify the files that were recently changed
2. Analyze for OWASP Top 10 vulnerabilities
3. Check for secrets, hardcoded credentials, SQL injection
4. Report findings with severity levels and remediation steps

Focus on actionable security findings, not style issues.

설정 필드:

필드 필수 옵션 목적
name 소문자 + 하이픈 고유 식별자
description 자연어 언제 호출할지 (“PROACTIVELY” 포함 시 자동 위임 권장)
tools 아니오 쉼표로 구분 생략 시 모든 도구 상속
model 아니오 sonnet, opus, haiku, inherit 기본값 sonnet
permissionMode 아니오 default, acceptEdits, bypassPermissions, plan, ignore 권한 처리
skills 아니오 쉼표로 구분 Subagent 시작 시 자동 로드할 skill

Subagent 관리하기

> /agents                    # 대화형 관리
> /agents create             # 새 subagent 생성
> /agents edit               # 기존 수정
> /agents delete             # Subagent 삭제
> /agents list               # 전체 보기

백그라운드에서 Agent 실행하기

장시간 실행되는 작업의 경우:

> Run a thorough security review in the background

> /agents  # 실행 중인 agent 상태 확인

나중에 agent ID로 결과를 조회할 수 있습니다.

고급 패턴

연쇄 subagent:

> First use the code-analyzer subagent to find performance issues, then use the optimizer subagent to fix them

병렬 탐색:

> Have three explore agents search in parallel:
> 1. Authentication code
> 2. Database models
> 3. API routes

재개 가능한 agent: Agent는 ID를 사용하여 이전 작업을 계속할 수 있습니다:

> Resume agent abc123 and continue the analysis

비동기 Subagent (2025년 12월)

비동기 subagent는 대규모 프로젝트에서 멀티태스킹과 병렬 실행을 가능하게 합니다:

> Run security review in the background while I continue frontend work
> /tasks                    # 실행 중인 agent 상태 확인

비동기 agent는 통합 TaskOutputTool을 통해 결과를 반환하여 효율적인 파이프라인 스타일 워크플로우를 가능하게 합니다.

권한 거부 복원력 (v2.1.0+)

v2.1.0부터 subagent는 권한 거부 후 완전히 중단되지 않고 계속 작동합니다. Subagent가 권한 벽에 부딪히면 자동으로 대안적인 접근 방식을 시도합니다. 이를 통해 자율 워크플로우가 더 탄력적이 되고 사람의 개입 필요성이 줄어듭니다.47

Agent Skills (2025년 12월)

Agent Skills는 agent가 동적으로 발견하고 로드하는 지침, 스크립트, 리소스의 체계적인 폴더입니다.31 조합 가능하고 이식 가능한 도메인 전문 지식을 제공합니다:

.claude/skills/
├── security-review/
│   ├── skill.md           # 지침 및 프롬프트
│   ├── checklist.md       # 보안 체크리스트
│   └── common-vulns.sh    # 탐지 스크립트
└── performance-audit/
    ├── skill.md
    └── profiling-guide.md

Skill은 명령어와 다릅니다: 명령어는 명시적으로 호출되는 반면, skill은 작업 컨텍스트에 따라 자동 활성화됩니다. Claude Agent SDK (이전 Claude Code SDK)는 skill 지원이 있는 커스텀 agent를 구축하기 위한 하네스를 제공합니다.32


Extended Thinking Mode란 무엇인가요?

Extended thinking은 Claude가 응답하기 전에 복잡한 문제를 깊이 생각할 시간을 더 줍니다. 아키텍처 결정, 까다로운 이슈 디버깅, 신중한 분석이 필요한 작업에 특히 유용합니다.

현재 상태 (2026년 1월)

Extended thinking은 이제 기본적으로 활성화되어 있으며, 이전에 “ultrathink”가 트리거하던 최대 예산인 31,999 토큰의 예산이 설정되어 있습니다.70 이 변경은 extended thinking이 복잡한 계획 및 추론 작업에서 성능을 크게 향상시키기 때문에 이루어졌습니다.

중요: “think”, “think hard”, “think harder”, “ultrathink”와 같은 자연어 트리거는 더 이상 작동하지 않습니다. 이러한 키워드는 이제 일반 프롬프트 지침으로 해석되며 thinking 토큰을 할당하지 않습니다. thinking 예산은 MAX_THINKING_TOKENS 환경 변수 또는 /config를 통해서만 제어됩니다.70

지원 모델

  • Claude Opus 4.5
  • Claude Sonnet 4.5
  • Claude Haiku 4.5

Extended Thinking 제어하기

세션 중 빠른 토글:

Alt+T를 눌러 thinking 켜기/끄기 토글

참고: thinking 토글이 우발적인 트리거를 방지하기 위해 Tab에서 Alt+T로 변경되었습니다.39

/config를 통해: /config → Extended Thinking으로 이동하여 활성화/비활성화하거나 예산을 조정하세요.

환경 변수 (영구):

# 커스텀 예산 설정 (기본값 31,999)
export MAX_THINKING_TOKENS=8000
claude

# 복잡한 작업을 위해 기본값의 2배
export MAX_THINKING_TOKENS=63999
claude

비용 절감을 위해 비활성화: 깊은 추론이 필요하지 않은 간단한 작업의 경우 /config에서 thinking을 비활성화하거나 예산을 낮춰 비용을 줄일 수 있습니다:

export MAX_THINKING_TOKENS=8000  # 기본값 31,999에서 감소

Thinking 토큰 예산

예산 사용 사례
1,024 (최소) 간단한 추론 작업
8,000 대부분의 코딩 작업 (비용 효율적)
31,999 (기본값) 복잡한 추론, 아키텍처 결정
63,999 (기본값의 2배) 철저한 분석 (명시적 설정 필요)

비용 고려 사항: Thinking 토큰은 출력 토큰으로 청구됩니다. 기본값 31,999 예산은 대부분의 작업에 잘 작동하지만, 간단한 작업의 경우 예산을 줄이거나 thinking을 완전히 비활성화하여 비용을 절약할 수 있습니다.

작동 방식

thinking이 활성화되면 Claude의 응답에는 출력에 표시되지 않지만 답변에 영향을 미치는 내부 추론이 포함됩니다. thinking은 암호화되어 검증을 위한 signature 필드에 반환됩니다.

도구 사용이 있는 멀티턴 대화에서는 추론 연속성을 유지하기 위해 thinking 블록을 API에 다시 전달해야 합니다. Claude Code는 이를 자동으로 처리합니다.

비활성화/감소를 고려해야 할 때

Extended thinking이 이제 기본값이지만, 다음의 경우 예산을 줄이거나 비활성화하는 것을 고려하세요: - 간단한 파일 편집 - 일상적인 리팩토링 - 빠른 질문 - 코드 포맷팅 - 비용이 누적되는 고빈도 작업

캐시 동작

thinking 매개변수가 변경되어도 시스템 프롬프트 캐싱은 유지됩니다. 턴 사이에 thinking 예산이나 활성화 상태가 변경되면 메시지 캐싱이 무효화됩니다.


Output Styles

Output style은 Claude가 정보를 제시하는 방식을 커스터마이즈합니다—학습, 문서화, 또는 특정 팀 선호도에 유용합니다.19

내장 스타일

스타일 목적
Explanatory 추론을 포함한 상세한 설명
Learning 개념 설명이 포함된 교육용 형식
Concise 최소한의 출력, 핵심만

Output Style 설정하기

> /output-style Explanatory
> /output-style Learning

또는 설정을 통해:

{
  "outputStyle": "Explanatory"
}

커스텀 Output Style

.claude/styles/에서 생성하세요:

# my-style

## Instructions
- Always explain the WHY behind each decision
- Include relevant documentation links
- Format code examples with comments
- End with a "What to do next" section

## Format
Use markdown headers for organization.
Keep explanations under 200 words per section.

/output-style my-style로 호출하세요.


Slash Commands

Slash commands는 Claude Code 기능에 빠르게 접근하고 사용자 정의 워크플로우를 활성화하는 방법을 제공합니다. 일반적인 작업에 대해 전체 프롬프트를 입력하는 것보다 훨씬 빠릅니다.

내장 명령어 참조

명령어 용도 참고
/init CLAUDE.md로 프로젝트 초기화 프로젝트 구조가 포함된 메모리 파일 생성
/memory 메모리 파일 편집 CLAUDE.md 편집기 열기
/context 컨텍스트 윈도우 사용량 보기 시각적 분석 표시
/compact 대화 기록 압축 초점 추가: /compact focus on tests
/cost 토큰 사용량 및 비용 표시 세션 분석
/usage 현재 플랜 사용량 표시 VSCode 전용 (v2.1.14+)
/stats 사용 통계 선호 모델, 사용 그래프, 연속 사용 기록
/permissions 권한 설정 관리 대화형 인터페이스
/mcp MCP 서버 설정 /mcp enable, /mcp disable도 가능
/hooks hook 설정 보기 hooks 디버그
/config 설정 인터페이스 열기 전체 설정
/resume 명명된 세션 재개 /resume <n> 또는 /resume session-name
/rename 현재 세션 이름 지정 /rename feature-auth
/fork 대화 분기 컨텍스트를 잃지 않고 대안 탐색
/clear 대화 기록 삭제 새로 시작
/vim vim 편집 모드 활성화 모달 편집
/ide IDE에 연결 VS Code/JetBrains 통합
/sandbox sandbox 모드 활성화 격리
/status 세션 상태 보기 모델, 설정 등
/statusline 상태 표시줄 사용자 정의 표시 설정
/model AI 모델 변경 /model opus
/output-style 출력 스타일 설정 Explanatory, Learning, 사용자 정의
/agents subagents 관리 생성, 편집, 삭제
/bashes 백그라운드 작업 목록 장시간 실행 명령
/tasks 백그라운드 agents 목록 비동기 작업 모니터링
/export 대화 내보내기 대화 내용 저장
/add-dir 작업 디렉토리 추가 접근 범위 확장
/terminal-setup 터미널 설정 Kitty, Alacritty, Zed, Warp 지원25
/doctor 설치 상태 확인 상태 점검
/bug 버그 신고 Anthropic에 이슈 제출
/release-notes 릴리스 노트 보기 새로운 기능 확인
/rewind 체크포인트로 되돌리기 변경 사항 취소 (또는 Esc×2)
/theme 테마 관리 Ctrl+T로 구문 강조 토글
/plugin plugins 관리 plugins 설치, 업데이트, 제거
/passes 게스트 패스 (Max 전용) Claude Code Pro 체험판 패스 3개 공유62

사용자 정의 명령어 생성

.claude/commands/ (프로젝트) 또는 ~/.claude/commands/ (개인)에서 재사용 가능한 명령어를 생성할 수 있습니다:

---
description: Security-focused code review
allowed-tools: Read, Grep, Glob
model: claude-sonnet-4-5
---

Review this code for security vulnerabilities:

1. Injection attacks (SQL, command, XSS)
2. Authentication and authorization flaws
3. Sensitive data exposure
4. Insecure dependencies

Focus on actionable findings with specific line references.

.claude/commands/security-review.md로 저장하고 /security-review로 실행합니다.

명령어 Frontmatter 옵션

---
description: Brief description for /help
allowed-tools: Read, Edit, Bash(npm:*)
model: opus
argument-hint: [arg1] [arg2]
disable-model-invocation: false
---
옵션 용도
description 도움말 텍스트 및 자동 위임 매칭
allowed-tools 사용 가능한 도구 제한
model 이 명령어에 대한 모델 재정의
argument-hint 예상 인수 문서화
disable-model-invocation SlashCommand 도구 사용 방지

인수 보간

모든 인수를 단일 문자열로:

---
description: Fix GitHub issue
argument-hint: [issue-number]
---

Fix GitHub issue #$ARGUMENTS following our coding standards.

사용법: /fix-issue 123

번호가 매겨진 인수:

---
description: Create component
argument-hint: [name] [type]
---

Create a new $2 component named $1 in src/components/.

사용법: /create-component Button functional

인라인 Bash 실행

명령어 프롬프트 내에서 bash 명령을 실행합니다:

---
description: Git status summary
allowed-tools: Bash(git:*)
---

Current branch: !`git branch --show-current`
Recent commits: !`git log --oneline -5`
Changed files: !`git status --short`

Summarize the current state of this repository.

파일 참조

명령어에 파일 내용을 포함합니다:

---
description: Compare implementations
---

Compare these files:
@src/v1/handler.ts
@src/v2/handler.ts

Which implementation is more maintainable?

명령어 네임스페이싱

하위 디렉토리에서 명령어를 구성합니다:

.claude/commands/
├── backend/
│   ├── test.md
│   └── deploy.md
├── frontend/
│   ├── test.md
│   └── build.md
└── review.md

동일한 이름의 명령어는 도움말에서 네임스페이스를 표시합니다: /test (project:backend) vs /test (project:frontend).


Skills는 어떻게 작동하나요?

Skills는 Claude Code를 확장하는 근본적으로 다른 접근 방식을 나타냅니다. 명시적으로 호출하는 slash commands와 달리, skills는 모델이 호출합니다—Claude가 컨텍스트에 따라 자동으로 발견하고 사용합니다. 도메인 전문 지식을 skill에 내장하면, Claude는 상황이 요구할 때마다 해당 전문 지식을 활용하며, 여러분이 직접 요청할 필요가 없습니다.

Skills가 모든 것을 바꾸는 이유: 도메인 전문 지식을 생각해 보세요—결제 처리 규칙, 규정 준수 요구 사항, 팀이 수년에 걸쳐 정제한 아키텍처 패턴들. Skills 없이는 매 세션마다 이 컨텍스트를 다시 설명하거나 Claude가 코드 주석에서 추론하기를 바라야 합니다. Skills를 사용하면 한 번만 인코딩하면 됩니다. Claude는 skill 정의를 읽고 관련 상황에서 자동으로 해당 전문 지식을 적용합니다. 주니어 개발자들은 질문하지 않고도 시니어 수준의 가이드를 받습니다. 보안 패턴은 기억해서 호출할 필요 없이 적용됩니다.

이 구분이 중요합니다. Slash command는 사용자가 기억해서 사용하는 단축키입니다. Skill은 Claude가 항상 사용할 수 있는 지식입니다. 팀의 특정 취약점 패턴과 규정 준수 요구 사항이 포함된 보안 리뷰 skill을 만들면, Claude는 관련 코드를 발견할 때마다—PR 리뷰, 리팩토링 또는 보안이 중요한 모든 작업에서—해당 전문 지식을 자동으로 적용합니다. /security-review를 호출하는 것이 아니라, Claude가 컨텍스트를 인식하고 자동으로 skill을 적용합니다.

Skills vs Commands vs Subagents

각 확장 메커니즘을 언제 사용해야 하는지 이해하면 중복을 방지하고 효과를 극대화할 수 있습니다:

측면 Slash Commands Skills Subagents
호출 사용자 호출 (/command) 모델 호출 (자동) 명시적 또는 자동 위임
트리거 사용자가 기억해서 사용 Claude가 컨텍스트 인식 작업에 위임이 필요할 때
구조 단일 markdown 파일 리소스가 포함된 디렉토리 frontmatter가 있는 markdown
컨텍스트 메인 대화 메인 대화 별도의 컨텍스트 윈도우
복잡도 간단한 프롬프트 다중 파일 기능 완전한 agent 성격
적합한 용도 명시적 작업 도메인 전문 지식 복잡한 작업 위임

Slash commands 사용 시기: 명시적인 제어가 필요할 때: /deploy, /test, /review PR 456. 언제 실행할지 사용자가 결정합니다.

Skills 사용 시기: 전문 지식이 자동으로 제공되어야 할 때: 보안 패턴, 코드 스타일 적용, 도메인별 지식. Claude가 언제 적용할지 결정합니다.

Subagents 사용 시기: 작업에 격리가 필요할 때: 백그라운드 탐색, 병렬 분석, 메인 대화를 오염시키지 않아야 하는 특수한 추론.

Skill 구조 및 위치

Skills는 필수 SKILL.md 파일과 선택적 지원 리소스가 포함된 전용 디렉토리에 있습니다:

개인 skills (모든 프로젝트에서 사용 가능):

~/.claude/skills/
├── code-reviewer/
│   ├── SKILL.md
│   ├── SECURITY_PATTERNS.md
│   └── PERFORMANCE_CHECKLIST.md
├── sql-analyst/
│   ├── SKILL.md
│   └── QUERY_PATTERNS.md
└── api-designer/
    └── SKILL.md

프로젝트 skills (git을 통해 팀과 공유):

.claude/skills/
├── domain-expert/
│   ├── SKILL.md
│   ├── BUSINESS_RULES.md
│   └── DATA_MODELS.md
└── deployment/
    ├── SKILL.md
    └── RUNBOOKS.md

프로젝트 skills는 버전 관리에 커밋됩니다. 팀원들이 pull하면 설치나 설정 없이 자동으로 skills를 받습니다. 이것이 팀 전체에 전문 지식을 표준화하는 방법입니다.

SKILL.md 형식

모든 skill에는 YAML frontmatter가 포함된 SKILL.md 파일이 필요합니다:

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues, and best practice violations. Use when examining code changes, reviewing PRs, analyzing code quality, or when asked to review or audit code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Security Analysis

When reviewing code, check for:

### Input Validation
- All user input sanitized before use
- Parameterized queries for database operations
- Output encoding for rendered content

### Authentication & Authorization
- Session tokens properly validated
- Permission checks before sensitive operations
- No hardcoded credentials or API keys

### Data Exposure
- Sensitive data not logged
- PII properly masked in error messages
- API responses don't leak internal details

## Performance Patterns

### Database
- N+1 query detection
- Missing indexes on filtered columns
- Unbounded result sets

### Memory
- Large object lifecycle management
- Stream processing for big files
- Connection pool exhaustion risks

## 리뷰 출력 형식

각 발견 사항에 대해:
- **파일**: path/to/file.ts:123
- **심각도**: Critical | High | Medium | Low
- **카테고리**: Security | Performance | Maintainability
- **문제**: 문제에 대한 명확한 설명
- **권장 사항**: 코드 예제와 함께 구체적인 수정 방법
- **근거**: 이것이 중요한 이유

자세한 취약점 패턴은 [SECURITY_PATTERNS.md](SECURITY_PATTERNS.md)를 참조하세요.
최적화 가이드라인은 [PERFORMANCE_CHECKLIST.md](PERFORMANCE_CHECKLIST.md)를 참조하세요.

Frontmatter 참조

필드 필수 제약 조건 용도
name 소문자, 숫자, 하이픈; 최대 64자 고유 식별자
description 최대 1024자 검색 트리거—Claude가 이 skill을 적용할 시점을 결정하는 데 사용
allowed-tools 아니오 쉼표로 구분된 도구 이름 이 skill 사용 시 Claude의 기능 제한
context 아니오 fork 격리된 컨텍스트에서 skill 실행 (v2.1.0+). 메인 에이전트 상태에 대한 부작용 방지.47

문자열 치환 (v2.1.9+): Skills는 ${CLAUDE_SESSION_ID} 치환을 사용하여 세션 컨텍스트에 접근할 수 있습니다. 로깅, 추적 또는 세션별 출력 생성에 유용합니다.51

description 필드는 매우 중요합니다. Claude는 사용자의 요청을 skill 설명과 매칭하여 skills를 검색합니다. 모호한 설명은 Claude가 skill을 사용할 시점을 인식하지 못하게 합니다. 명확한 트리거 조건이 있는 구체적인 설명은 안정적인 활성화를 보장합니다.

잘못된 설명:

description: Helps with code

효과적인 설명:

description: Review code for security vulnerabilities, performance issues, and best practice violations. Use when examining code changes, reviewing PRs, analyzing code quality, or when asked to review, audit, or check code.

효과적인 설명에 포함된 내용: - skill이 하는 일 (특정 문제에 대한 코드 검토) - 사용 시점 (변경 사항 검토, PR, 품질 분석) - 트리거 문구 (review, audit, check)

도구 제한

allowed-tools 필드는 skill이 활성화되었을 때 Claude가 수행할 수 있는 작업을 제한합니다. 이는 읽기 전용이거나 범위가 제한되어야 하는 skills에 필수적입니다:

---
name: security-auditor
description: Audit code for security vulnerabilities without making changes
allowed-tools: Read, Grep, Glob
---

이 구성에서 Claude는 코드를 분석할 수 있지만 파일을 편집하거나, bash 명령을 실행하거나, 수정을 가할 수 없습니다. skill이 읽기 전용 동작을 강제합니다.

일반적인 제한 패턴:

패턴 도구 사용 사례
읽기 전용 분석 Read, Grep, Glob 보안 감사, 코드 리뷰
안전한 탐색 Read, Grep, Glob, Bash(git log:*), Bash(git diff:*) 히스토리 분석
문서화 Read, Grep, Glob, Write 소스 편집 없이 문서 생성
전체 접근 (필드 생략) Skill이 사용 가능한 모든 도구 상속

지원 파일

Skills는 여러 파일을 포함할 수 있습니다. Claude는 활성화 시 메인 SKILL.md를 읽은 다음 필요에 따라 지원 파일에 접근합니다—컨텍스트를 효율적으로 관리하는 점진적 공개 방식입니다.

구조 패턴:

my-skill/
├── SKILL.md           # 필수: 개요 + 빠른 참조
├── DETAILED_GUIDE.md  # 상세 문서
├── EXAMPLES.md        # 구체적인 예제
├── PATTERNS.md        # 참조 패턴
├── templates/         # 재사용 가능한 템플릿
│   └── component.tsx
└── scripts/           # 헬퍼 유틸리티
    └── validate.py

SKILL.md에서 지원 파일 참조:

For detailed security patterns, see [SECURITY_PATTERNS.md](SECURITY_PATTERNS.md).

Use this template for new components:
@templates/component.tsx

Validate configurations with:
```bash
python scripts/validate.py config.json
**전문가 팁:** 필수 정보는 SKILL.md에 직접 넣으세요. 지원 파일은 심층 참조 자료용으로 남겨두세요. Claude는 SKILL.md를 즉시 읽지만 지원 파일은 필요할 때만 접근합니다. 중요한 정보가 지원 파일에 묻혀 있으면 Claude가 찾지 못할 수 있습니다.

### 전체 예제: 도메인 전문가 Skill

핀테크 애플리케이션을 위한 프로덕션 수준의 skill입니다:

**디렉토리 구조:**

.claude/skills/payments-domain/ ├── SKILL.md ├── BUSINESS_RULES.md ├── COMPLIANCE.md └── DATA_MODELS.md

**SKILL.md:**
```markdown
---
name: payments-domain
description: Expert knowledge of payment processing domain including transaction flows, compliance requirements, and business rules. Use when working with payment code, transaction handling, refunds, disputes, or financial calculations.
---

# Payments Domain Expertise

## Core Concepts

### Transaction States

PENDING → AUTHORIZED → CAPTURED → SETTLED ↘ VOIDED AUTHORIZED → DECLINED CAPTURED → REFUNDED (partial or full) SETTLED → CHARGEBACK → REPRESENTED

### Money Handling Rules
- ALL monetary values stored as integers (cents, not dollars)
- Currency always explicitly tracked (never assume USD)
- Rounding: HALF_EVEN for calculations, HALF_UP for display
- Never use floating point for money

### Idempotency Requirements
Every payment operation MUST be idempotent:
```typescript
// Required pattern
async function processPayment(idempotencyKey: string, amount: number) {
  const existing = await findByIdempotencyKey(idempotencyKey);
  if (existing) return existing; // Return cached result

  const result = await executePayment(amount);
  await storeWithIdempotencyKey(idempotencyKey, result);
  return result;
}

Quick Reference

Fee Calculations

  • Interchange: 1.5% + $0.10 (debit), 2.1% + $0.10 (credit)
  • Platform fee: 2.9% + $0.30 (standard), 2.2% + $0.30 (enterprise)
  • International: +1% cross-border fee
  • Currency conversion: mid-market rate + 1%

Compliance Thresholds

  • $3,000: Enhanced due diligence trigger
  • $10,000: CTR filing required
  • $25,000: Additional verification required

Refund Windows

  • Full refund: 120 days from capture
  • Partial refund: 180 days from capture
  • Chargeback window: 120 days (Visa), 180 days (Mastercard)

Key Files

  • src/payments/processor.ts - Core payment logic
  • src/payments/refunds.ts - Refund handling
  • src/compliance/aml.ts - AML checks
  • src/models/transaction.ts - Transaction model

See BUSINESS_RULES.md for detailed business logic. See COMPLIANCE.md for regulatory requirements. See DATA_MODELS.md for schema documentation.

이 skill이 설정되면, 트랜잭션 코드 작업, 환불 로직 질문, 결제 흐름 디버깅 시 Claude가 자동으로 결제 도메인 전문 지식을 적용합니다. 별도로 호출할 필요 없이 전문 지식이 자연스럽게 제공됩니다.

### 효과적인 Skills 만들기

**설명부터 시작하세요.** 설명을 먼저 작성한 다음 그에 맞는 skill 콘텐츠를 구축하세요. 설명이 Claude가 skill을 사용하는 시점을 결정하므로 정확하게 작성해야 합니다:

1. skill이 제공하는 것을 명시
2. 구체적인 트리거 조건 나열
3. 관련 키워드와 문구 포함

**skills를 집중적으로 유지하세요.** 하나의 skill은 하나의 도메인 또는 기능을 다뤄야 합니다:

| 좋음 (집중적) | 나쁨 (너무 광범위) |
|----------------|-----------------|
| `security-auditor` | `code-helper` |
| `react-patterns` | `frontend-stuff` |
| `postgres-optimization` | `database-expert` |
| `api-documentation` | `docs-generator` |

skill이 너무 많은 것을 다루려고 하면 설명이 모호해지고 Claude가 사용 시점을 안정적으로 인식하지 못합니다.

**점진적 공개를 사용하세요.** 가장 중요한 정보는 SKILL.md에 직접 넣으세요. 심층 내용은 지원 파일을 참조하세요:

```markdown

## Quick Reference
[필수 패턴은 여기에 - Claude가 즉시 확인]

## Deep Dive
For comprehensive coverage, see [DETAILED_GUIDE.md](DETAILED_GUIDE.md).

구체적인 예제를 포함하세요. 추상적인 설명보다 구체적인 패턴이 더 유용합니다:

## Input Validation

### Pattern
```typescript
// Good: Explicit validation with typed errors
const validated = PaymentSchema.safeParse(input);
if (!validated.success) {
  throw new ValidationError(validated.error.issues);
}

// Bad: Implicit coercion
const amount = Number(input.amount); // Silent NaN on invalid input
**실제 요청으로 테스트하세요.** skill을 만든 후 Claude가 활성화하는지 테스트하세요:

Review this payment processing code for issues

payments-domain skill이 활성화되어야 함

How should I handle refunds?

payments-domain skill이 활성화되어야 함

What’s the weather like?

payments-domain skill이 활성화되면 안 됨

Claude가 예상대로 skill을 활성화하지 않으면 사용하는 트리거 문구를 포함하도록 설명을 수정하세요.

### 팀 공유 전략

**Git 기반 공유 (프로젝트 skills에 권장):**
```bash
# 프로젝트에 skill 추가
mkdir -p .claude/skills/team-standard
# SKILL.md 및 지원 파일 생성

# 커밋
git add .claude/skills/
git commit -m "Add team coding standards skill"
git push

# 팀원들이 자동으로 받음
git pull
claude  # 이제 Skill 사용 가능

심볼릭 링크를 통한 프로젝트 간 공유:

# 표준 skill 위치 생성
mkdir -p ~/shared-skills/security-reviewer
# SKILL.md 생성

# 프로젝트에 심볼릭 링크
ln -s ~/shared-skills/security-reviewer ~/.claude/skills/security-reviewer
# 이제 모든 프로젝트에서 사용 가능

Plugin 배포: 더 넓은 배포를 위해 skills를 plugins로 패키징하세요:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── my-skill/
        └── SKILL.md

plugins에 번들된 Skills는 사용자가 plugin을 설치하면 사용 가능해집니다.

Skills 디버깅

Skill이 활성화되지 않는 경우:

  1. 설명이 요청과 일치하는지 확인: yaml # "check this code"라고 말하는데 설명에 "review"만 있는 경우 description: Review OR check code for issues...

  2. 파일 위치 확인: ```bash # 개인용 ls ~/.claude/skills/my-skill/SKILL.md

# 프로젝트용 ls .claude/skills/my-skill/SKILL.md ```

  1. YAML frontmatter 유효성 검사:
  2. 첫 번째 줄은 정확히 ---여야 함
  3. 마크다운 콘텐츠 전에 닫는 ---
  4. YAML에 탭 없음 (공백 사용)
  5. name 필드는 소문자와 하이픈만 사용

  6. 디버그 모드로 실행: bash claude --debug # skill 로딩 메시지 확인

Skill이 예상치 않게 활성화되는 경우:

설명을 좁히세요. skill이 원하지 않을 때 활성화되면 설명이 너무 광범위한 것입니다:

# 너무 광범위 - "code" 언급 시 활성화
description: Help with code

# 구체적 - 보안 컨텍스트에서만 활성화
description: Audit code for security vulnerabilities including injection attacks, authentication flaws, and data exposure. Use when specifically asked about security, vulnerabilities, or when reviewing code for security issues.

지원 파일을 찾을 수 없는 경우:

  • SKILL.md 위치에서 상대 경로 사용
  • 슬래시만 사용 (Windows에서도)
  • 파일 존재 확인: ls .claude/skills/my-skill/REFERENCED.md

Skill을 만들어야 할 때

Skill을 만들어야 하는 경우: - 도메인 전문 지식이 자동으로 제공되어야 할 때 - 여러 팀원이 동일한 지식이 필요할 때 - 동일한 패턴이나 규칙을 반복적으로 설명하는 경우 - 명시적 호출 없이 컨텍스트가 주입되어야 할 때 - 지식이 여러 파일에 걸쳐 있고 구성이 필요할 때

Skill을 만들지 않아야 하는 경우: - 호출에 대한 명시적 제어가 필요한 경우 (slash command 사용) - 작업에 별도의 컨텍스트가 필요한 경우 (subagent 사용) - 일회성 프롬프트인 경우 (그냥 입력) - “skill”이 실제로는 단일 템플릿인 경우 (slash command 사용)

전문가 팁: 인증 코드 작업 전에 반복적으로 /security-review를 입력하고 있다면 skill로 변환하세요. 전문 지식은 명시적으로 호출되는 것이 아니라 자연스럽게 존재해야 합니다. 명시적 호출을 원한다면 command로 유지하세요.


플러그인 시스템

플러그인은 Claude Code 확장 기능을 배포용으로 패키징합니다. 플러그인에는 사용자 정의 명령, 서브에이전트, 스킬, hooks, MCP 서버가 포함될 수 있습니다. Anthropic은 2025년 12월에 36개의 큐레이션된 플러그인과 함께 공식적으로 플러그인 마켓플레이스를 출시했습니다.47

플러그인 구조

my-plugin/
├── .claude-plugin/
│   └── plugin.json              # Required: metadata
├── commands/                     # Slash commands
│   └── hello.md
├── agents/                       # Subagents
│   └── helper.md
├── skills/                       # Skills
│   └── my-skill/
│       └── SKILL.md
├── hooks/                        # Event handlers
│   └── hooks.json
└── .mcp.json                     # MCP servers

플러그인 매니페스트

최소한의 plugin.json:

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

플러그인 관리

> /plugin                              # Interactive interface
> /plugin install name@marketplace     # Install
> /plugin enable name@marketplace      # Enable
> /plugin disable name@marketplace     # Disable
> /plugin uninstall name@marketplace   # Remove
> /plugin marketplace add ./local      # Add local marketplace
> /plugin marketplace list             # View marketplaces

로컬 개발

테스트용 로컬 마켓플레이스를 생성하세요:

mkdir dev-marketplace && cd dev-marketplace
mkdir my-plugin
# Create plugin structure

cd ..
claude
> /plugin marketplace add ./dev-marketplace
> /plugin install my-plugin@dev-marketplace

플러그인 구성 요소

  • Commands: 슬래시 명령으로 사용 가능 (/plugin-command)
  • Agents: /agents 목록에 표시
  • Skills: 스킬 설정에 따라 자동 로드
  • Hooks: 사용자/프로젝트 hooks와 병합되어 병렬로 실행
  • MCP Servers: 플러그인 활성화 시 자동 시작

메모리는 어떻게 작동하나요?

Claude Code의 메모리 시스템은 세션 간 지속적인 컨텍스트를 가능하게 합니다. 효과적인 메모리 관리가 Claude가 프로젝트를 깊이 이해하는 것과 매 세션을 새롭게 시작하는 것의 차이를 만듭니다.

CLAUDE.md 계층 구조

위치 범위 공유 여부 사용 사례
/Library/Application Support/ClaudeCode/CLAUDE.md (macOS) 기업 모든 사용자 회사 표준
./CLAUDE.md 또는 ./.claude/CLAUDE.md 프로젝트 git 통해 팀 컨텍스트
~/.claude/CLAUDE.md 사용자 모든 프로젝트 개인 환경설정
./CLAUDE.local.md 프로젝트-로컬 공유 안 함 개인 프로젝트 노트

효과적인 CLAUDE.md 구조

# Project Context

## Architecture
- Monorepo with packages in /packages
- React frontend in /packages/ui
- Node.js API in /packages/api
- Shared types in /packages/types
- PostgreSQL database via Prisma

## Code Standards
- TypeScript strict mode everywhere
- ESLint + Prettier enforced (pre-commit hooks)
- No default exports
- JSDoc on all public APIs
- Tests required for all new code

## Commands
- `npm test` - Run all tests
- `npm run test:watch` - Watch mode
- `npm run lint` - Check linting
- `npm run lint:fix` - Auto-fix lint issues
- `npm run build` - Production build
- `npm run dev` - Start dev servers
- `npm run db:migrate` - Run migrations
- `npm run db:seed` - Seed database

## Patterns

### API Endpoints
Create in packages/api/src/routes/
Use Zod for request/response validation
All endpoints need OpenAPI documentation

### React Components
Create in packages/ui/src/components/
Use React Query for server state
Prefer composition over inheritance

### Database
Prisma schema in packages/api/prisma/
Always create migration for schema changes
Use transactions for multi-table operations

## Important Notes
- NEVER commit .env files
- API runs on :3000, UI on :3001
- Local DB: postgres://localhost:5432/myapp
- Feature flags in packages/api/src/flags.ts

## Recent Decisions
- 2025-12-01: Migrated to React Query v5
- 2025-11-15: Adopted Zod for all validation
- 2025-11-01: Moved to ESM modules

# Summary Instructions
When using compact, focus on:
- Recent code changes
- Test results
- Architecture decisions made this session

파일 임포트

CLAUDE.md 내에서 다른 파일을 참조하세요:

See @README.md for project overview
Coding standards: @docs/STYLE_GUIDE.md
API documentation: @docs/API.md
Personal preferences: @~/.claude/preferences.md

임포트 구문: - 상대 경로: @docs/file.md - 프로젝트 절대 경로: @/absolute/path.md - 홈 디렉토리: @~/.claude/file.md - 최대 깊이: 5단계 임포트

메모리 규칙 디렉토리

더 체계적인 메모리 관리를 위해 .claude/rules/를 사용하여 분류된 규칙 파일을 저장하세요:18

.claude/rules/
├── testing.md          # Testing conventions
├── security.md         # Security requirements
├── api-patterns.md     # API design patterns
└── deployments.md      # Deployment procedures

규칙은 자동으로 로드되며 CLAUDE.md를 복잡하게 만들지 않고 구조화된 컨텍스트를 제공합니다.

빠른 메모리 추가

세션 중 # 접두사를 사용하여 노트를 추가하세요:

# Always run tests before committing
# The payment module is especially fragile
# Use the new logger from packages/api/src/logger.ts

노트를 저장할 메모리 파일을 선택하라는 프롬프트가 표시됩니다.

컨텍스트 관리 명령

컨텍스트 사용량 보기:

> /context

시스템 프롬프트, 대화, 도구, 파일 내용에 걸친 컨텍스트 할당의 시각적 그리드를 표시합니다.

대화 압축:

> /compact
> /compact focus on the authentication changes
> /compact preserve test output and error messages

주요 정보를 보존하면서 이전 대화를 지능적으로 요약합니다.

사용자 정의 압축 지침 (CLAUDE.md에서):

# Summary Instructions
When using compact, focus on:
- Test output and failures
- Code changes made this session
- Architecture decisions

컨텍스트를 위한 확장 사고:

export MAX_THINKING_TOKENS=10000

더 많은 사고 토큰은 더 많은 추론 능력을 의미하지만 비용이 높아집니다.

컨텍스트 최적화 전략

  1. Claude에게 검색을 요청하는 대신 특정 파일 참조를 사용하세요
  2. 작업 간에 /clear관련 없는 대화를 정리하세요
  3. 긴 세션 중에 적극적으로 압축하세요
  4. 탐색 작업을 격리하기 위해 서브에이전트를 사용하세요
  5. 복잡한 작업을 집중된 상호작용으로 분할하세요
  6. 다시 설명하는 대신 진행 중인 작업에 대해 세션을 재개하세요

이미지 및 멀티모달 입력

Claude Code는 스크린샷, 다이어그램, 목업, 오류 메시지, 데이터베이스 스키마 등의 이미지를 분석할 수 있습니다.

입력 방법

  1. 드래그 앤 드롭: 이미지 파일을 Claude Code 창으로 드래그하세요
  2. 붙여넣기: Ctrl+V (Mac에서 Cmd+V 아님)로 클립보드에서 붙여넣기
  3. 경로 참조: “이 이미지를 분석해줘: /path/to/screenshot.png”

첨부된 이미지 보기

Claude가 응답에서 이미지를 참조할 때, 클릭 가능한 이미지 링크를 통해 직접 볼 수 있습니다:34

[Image #1]   # Click to open in default image viewer
[Image #2]   # Navigate attached screenshots

이는 스크린샷을 검토하거나 시각적 문제를 디버깅할 때 유용합니다—참조를 클릭하면 Claude가 분석한 내용을 정확히 볼 수 있습니다.

사용 사례

  • UI 문제 디버그: “버그의 스크린샷입니다. 원인이 뭔가요?”
  • 디자인 구현: “이 목업을 기반으로 컴포넌트를 만들어주세요”
  • 다이어그램 분석: “이 아키텍처 다이어그램을 설명해주세요”
  • 데이터베이스 스키마: “이 ERD에 맞는 Prisma 모델을 생성해주세요”
  • 오류 분석: “이 오류 스크린샷이 무슨 의미인가요?”

전문가 팁: 목업을 구현할 때 다양한 상태(기본, 호버, 로딩, 오류)를 보여주는 여러 스크린샷을 포함하세요. 시각적 컨텍스트가 많을수록 구현이 더 좋아집니다.


Git 통합은 어떻게 작동하나요?

Claude Code는 내장된 안전 프로토콜과 함께 깊은 git 통합 기능을 제공합니다.

안전 프로토콜

  • .gitignore를 자동으로 준수
  • 권한 없이 브랜치를 수정하지 않음
  • 커밋 전 diff를 표시
  • 프로젝트의 커밋 규칙을 따름
  • 명시적 요청 없이 force push하지 않음
  • 커밋 수정 전 작성자 확인

일반적인 워크플로우

커밋 생성:

> commit these changes
> create a commit with a meaningful message

Claude는 다음을 수행합니다: 1. git statusgit diff 실행 2. 변경 사항 분석 3. 컨벤셔널 커밋 메시지 생성 4. 커밋 전 승인 대기

풀 리퀘스트 생성:

> create a PR for this feature
> summarize the changes and create a PR

코드 리뷰:

> review the changes in this PR
> what could go wrong with these changes?

GitHub Actions 통합

공식 액션으로 CI/CD에서 Claude를 자동화하세요:

빠른 설정:

> /install-github-app

수동 워크플로우 파일:

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]
  issue_comment:
    types: [created]

jobs:
  claude-review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Review this PR for bugs, security issues, and performance problems"
          claude_args: "--max-turns 5"

Bedrock용 (OIDC 사용):

- name: Configure AWS
  uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
    aws-region: us-west-2

- uses: anthropics/claude-code-action@v1
  with:
    use_bedrock: "true"
    claude_args: '--model us.anthropic.claude-sonnet-4-5-20250929-v1:0'

IDE에서 Claude Code를 어떻게 사용하나요?

VS Code 확장

요구 사항: VS Code 1.98.0+

설치: 확장 마켓플레이스에서 “Claude Code” 검색

기능: - 사이드바 패널 (Spark 아이콘) - diff 미리보기가 있는 Plan 모드 - 편집 자동 수락 토글 - 확장 사고 토글 - 파일 첨부 및 이미지 붙여넣기 - 대화 기록 - 다중 동시 세션

보안 참고: WebSocket 인증 우회 취약점(CVE-2025-52882)이 IDE 확장 v1.0.24+에서 패치되었습니다. 확장이 업데이트되었는지 확인하세요—모든 취약한 버전은 확장 스토어에서 제거되었습니다.38

타사 제공자 설정 (.claude/settings.json에서):

{
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "AWS_REGION": "us-east-1",
    "AWS_PROFILE": "your-profile"
  }
}

JetBrains 플러그인

지원: IntelliJ IDEA, PyCharm, WebStorm, GoLand, PhpStorm, DataGrip

설치: Settings → Plugins → “Claude Code” 검색 → Install → 재시작

주요 단축키: - Cmd+Esc (Mac) / Ctrl+Esc (Windows): 빠른 실행 - Cmd+Option+K (Mac) / Alt+Ctrl+K (Windows): 파일 참조 추가

기능: - IDE diff 뷰어에서 diff 보기 - 선택 컨텍스트 자동 공유 - 진단 통합 - 다중 세션

WSL2 설정: Claude 명령을 다음과 같이 설정하세요:

wsl -d Ubuntu -- bash -lic "claude"

터미널 통합

외부 터미널을 IDE에 연결하세요:

> /ide

Claude Code는 VS Code, Cursor, Windsurf, JetBrains IDE를 자동 감지합니다.

Slack 통합 (2025년 12월)

Claude Code는 이제 Slack과 직접 통합되어 개발자가 채팅 스레드에서 코딩 작업을 위임할 수 있습니다.14

작동 방식: 1. Slack 채널이나 스레드에서 @Claude를 멘션 2. Claude가 메시지를 검토하여 코딩 작업인지 판단 3. Anthropic 인프라에서 Claude Code 세션이 자동으로 시작 4. Claude가 최근 채널/스레드 메시지에서 컨텍스트를 수집 5. 진행 상황 업데이트가 Slack 스레드에 게시 6. 완료 시 변경 사항 검토 및 PR 열기 링크 제공

사용 사례: - Slack에 게시된 버그 리포트에서 버그 조사 - 팀 피드백을 기반으로 한 빠른 코드 리뷰 - 기능 요청에서 소규모 기능 구현

요구 사항: - Slack App Marketplace를 통해 설치된 Claude 앱 - 유료 Slack 플랜 - 웹에서 Claude Code 액세스

개인정보 보호: Claude는 Slack의 기존 권한 구조를 준수합니다. 접근 권한이 없는 대화나 저장소에는 액세스할 수 없습니다. 대화는 모델 학습에 사용되지 않습니다.


고급 사용 패턴

Headless 및 CI 모드

스크립트와 CI 파이프라인에서 Claude Code를 실행할 수 있습니다:

#!/bin/bash
# Automated code review

result=$(claude -p "Review this code for quality issues" \
  --output-format json \
  --allowedTools "Read,Grep,Glob" \
  --permission-mode plan \
  --disable-slash-commands \
  --max-turns 5)

if echo "$result" | jq -e '.result | test("critical|high severity")' > /dev/null; then
  echo "Issues found:"
  echo "$result" | jq -r '.result'
  exit 1
fi

echo "Review passed"
exit 0

파이핑 및 체이닝

# Analyze logs
cat production.log | claude -p "summarize errors" > error-summary.md

# Process multiple files
find . -name "*.ts" -exec cat {} \; | claude -p "find security issues"

# Chain with jq
claude -p "generate config" --output-format json | jq -r '.result' > config.json

백그라운드 작업

긴 작업을 차단 없이 실행할 수 있습니다:

> start the build in the background

또는 명령 실행 중 Ctrl+B를 누르세요.

백그라운드 작업 관리:

> /bashes                    # List running tasks
> get output from task xyz   # Retrieve output

Git Worktree를 활용한 병렬 세션

# Create worktrees for parallel work
git worktree add ../project-feature-a -b feature-a
git worktree add ../project-bugfix bugfix-123

# Run Claude in each
cd ../project-feature-a && claude --session-id "feature-a"
cd ../project-bugfix && claude --session-id "bugfix-123"

각 worktree는 자체 세션을 가진 독립적인 프로젝트 디렉토리입니다.

JSON 출력 파싱

result=$(claude -p "analyze this code" --output-format json)

# Extract fields
echo "Result: $(echo $result | jq -r '.result')"
echo "Cost: $(echo $result | jq -r '.total_cost_usd')"
echo "Session: $(echo $result | jq -r '.session_id')"
echo "Duration: $(echo $result | jq -r '.duration_ms')ms"

프로그래밍 방식의 세션 관리

# Named sessions for tracking
claude --session-id "feature-$(git branch --show-current)-$(date +%s)"

# Continue previous work
claude -c "continue implementing the tests"

# Fork for parallel exploration
claude -r "main-session" --fork-session "try alternative approach"

Claude Code Remote란?

Claude Code Remote는 웹과 터미널 사이의 간극을 연결하여, 클라우드에서 작업을 시작하고 로컬에서 이어서 할 수 있게 해주며 그 반대도 가능합니다. 이 기능은 여러 기기에서 작업하는 방식을 근본적으로 변화시킵니다.

핵심 개념

claude.ai/code의 웹 인터페이스는 클라우드에서 Claude Code를 실행합니다. 터미널에서 벗어나 있는 동안에도 작업이 백그라운드에서 실행됩니다. 계속 작업할 준비가 되면, 세션을 로컬 머신으로 텔레포트하여 Claude가 중단한 지점부터 정확히 이어서 작업할 수 있습니다.

이를 통해 이전에는 불가능했던 워크플로가 가능해집니다: - 휴대폰에서 복잡한 리팩토링 작업을 시작하고, 이동 중에 실행시킨 후, 워크스테이션에서 마무리할 수 있습니다 - 웹 인터페이스에서 여러 작업을 대기열에 넣고, 자리로 돌아왔을 때 결과를 확인할 수 있습니다 - 노트북을 닫아야 할 때 장시간 실행되는 작업을 클라우드로 넘길 수 있습니다

& 접두사

Claude Code 웹에서 백그라운드로 작업을 실행하도록 전송합니다:

& Build a comprehensive REST API for user management with authentication, CRUD operations, and proper error handling

& 접두사는 프롬프트를 클라우드로 전송합니다. Claude가 비동기적으로 작업하므로, 터미널을 닫거나, 기기를 전환하거나, 다른 작업을 계속할 수 있습니다. claude.ai/code의 웹 인터페이스에서 실행 중이거나 완료된 세션을 확인할 수 있습니다.

--teleport 플래그

클라우드 세션을 로컬 터미널로 가져옵니다:

claude --teleport session_abc123

이 명령은 웹에서 세션 상태를 가져와 로컬에서 재개합니다. 전체 대화 기록, Claude가 수정한 파일을 모두 받을 수 있으며, 마치 처음부터 함께 있었던 것처럼 상호작용을 이어갈 수 있습니다.

세션 ID는 웹 인터페이스에 표시됩니다. 아무 세션이나 클릭하면 ID와 현재 상태를 확인할 수 있습니다.

요구 사항

Claude Code Remote는 Pro, Max, Team(프리미엄 시트), Enterprise(프리미엄 시트) 구독자가 사용할 수 있습니다.73 웹 인터페이스는 Anthropic의 인프라에서 실행되며, 로컬에서 사용하는 것과 동일한 Claude Code 기능—파일 작업, bash 명령, MCP 통합—을 관리형 클라우드 환경에서 실행합니다. Team 및 Enterprise 액세스는 2026년 1월에 확대되었으며, 계정 관리자가 Claude 설정에서 액세스를 전환할 수 있습니다.

iOS 앱 (2025년 11월): Claude Code는 Claude iOS 앱에서도 사용할 수 있어, 이동 중에 코딩 작업을 시작하고 휴대폰에서 에이전트 진행 상황을 모니터링할 수 있습니다.22 자리를 비운 상태에서 작업을 시작하고, 검토할 준비가 되면 터미널로 텔레포트할 수 있습니다.

실전 워크플로

출근길:

& Review all PRs assigned to me and prepare summaries with recommendations

책상에서:

# Check what completed
# Visit claude.ai/code to see session list

# Pull the session locally to review and act on recommendations
claude --teleport pr-review-session-xyz

퇴근 전:

& Run the full test suite, fix any failures, and prepare a summary of what was changed

다음 날 아침:

claude --teleport test-fixes-session-abc
# Review what Claude did overnight, make final adjustments

현재 상태

Claude Code Remote는 현재 연구 프리뷰 단계입니다. Anthropic이 피드백을 수집하면서 기능이 발전할 것으로 예상됩니다. 핵심 워크플로인 클라우드 실행과 로컬 텔레포트를 통해 지속적인 AI 개발이 가능해집니다: 키보드에서 벗어나 있는 동안 Claude가 작업하고, 중단한 지점부터 정확히 이어서 작업할 수 있습니다.

현재 제한 사항: 세션 텔레포트는 현재 단방향만 지원됩니다—웹 세션을 터미널로 가져올 수는 있지만, 기존 터미널 세션을 웹으로 푸시할 수는 없습니다. 로컬 세션을 원격 머신(예: SSH를 통한 AWS 인스턴스)에서 이어서 작업하는 것은 아직 지원되지 않습니다.


백그라운드 에이전트란?

백그라운드 에이전트는 사용자가 다른 작업을 계속하는 동안 실행되므로, 장시간 걸리는 작업이 완료될 때까지 기다릴 필요가 없습니다.17

백그라운드 에이전트의 작동 방식

Claude가 복잡한 작업을 실행하는 동안 터미널을 차단하는 대신, 백그라운드 에이전트는: 1. 별도의 프로세스에서 독립적으로 실행됩니다 2. 터미널을 닫아도 계속 작동합니다 3. 완료 시 알림을 통해 결과를 보고합니다 4. 실행 중에도 모니터링하고 관리할 수 있습니다

백그라운드 에이전트 시작하기

Ctrl+B 사용: Claude가 작업 중일 때 Ctrl+B를 누르면 현재 작업을 백그라운드로 전환할 수 있습니다. 터미널은 즉시 사용 가능한 상태가 됩니다.

& 접두사 사용:

& Run all tests and fix any failures
& Refactor the authentication module to use JWT
& Generate comprehensive API documentation

& 접두사는 Claude Code Remote(클라우드 실행)로 전송합니다. 로컬 백그라운드 실행의 경우, 이미 실행 중인 작업에서 Ctrl+B를 사용하세요.

백그라운드 작업 모니터링

> /tasks                    # List all running tasks
> /task status abc123       # Check specific task
> /task cancel abc123       # Stop a task
> /task output abc123       # View task output so far

병렬 백그라운드 워크플로

여러 에이전트를 동시에 실행할 수 있습니다:

& Fix all failing tests in src/
& Update documentation for the API module
& Run security scan on the codebase

각각 독립적으로 실행됩니다. /tasks로 진행 상황을 모니터링하고 완료되는 대로 결과를 가져올 수 있습니다.


Claude in Chrome (2025년 12월)

Claude Code는 이제 Claude in Chrome 확장 프로그램을 통해 브라우저와 통합되어, 터미널에서 직접 브라우저를 제어할 수 있습니다.24

설정

  1. https://claude.ai/chrome 에서 Chrome 확장 프로그램을 설치합니다
  2. Claude Code를 실행하면 통합이 자동으로 감지됩니다
  3. 자연어로 브라우저를 제어할 수 있습니다

기능

터미널에서 브라우저 자동화:

> Navigate to github.com and open my repositories
> Fill out this form with the test user data
> Take a screenshot of the current page
> Click the submit button and wait for the page to load

웹 스크래핑 및 테스트:

> Extract all product prices from this e-commerce page
> Run through the signup flow and report any issues
> Check if the mobile menu works correctly

사용 사례

  • E2E 테스트: Claude Code에서 직접 통합 테스트를 실행합니다
  • 웹 스크래핑: 브라우저 자동화 코드를 작성하지 않고도 페이지에서 데이터를 추출합니다
  • 폼 입력: 반복적인 웹 워크플로를 자동화합니다
  • 시각적 검증: 스크린샷을 찍고 페이지 레이아웃을 분석합니다

Chrome 통합은 기존 브라우저 세션 내에서 실행되며, 로그인 상태와 쿠키에 접근할 수 있어 인증된 플로를 테스트하는 데 유용합니다.


Claude Code in Slack (2025년 12월)

Anthropic은 Claude Code in Slack을 출시하여, 개발자가 채팅 스레드에서 직접 코딩 작업을 위임할 수 있게 했습니다.26

작동 방식

  1. Slack 채널이나 스레드에서 @Claude를 태그합니다
  2. 컨텍스트와 함께 코딩 작업을 설명합니다
  3. Claude가 Slack 메시지를 분석하여 리포지토리를 파악합니다
  4. 스레드에 진행 상황 업데이트가 표시됩니다
  5. Claude가 작업 검토 및 PR 링크를 공유합니다

예시 워크플로

@Claude The login form validation is broken on mobile devices.
Can you fix it? Check the bug report from earlier in this thread.

Claude의 작업 과정: 1. 컨텍스트를 파악하기 위해 스레드를 읽습니다 2. 관련 리포지토리를 식별합니다 3. 코드베이스를 클론하고 분석합니다 4. 진행 상황 업데이트를 게시합니다 5. 수정 사항이 포함된 PR을 생성합니다 6. 검토를 위한 PR 링크를 공유합니다

장점

  • 컨텍스트 인식: Claude가 버그 리포트, 기능 요청, 토론 등 Slack 기록을 읽습니다
  • 팀 가시성: 스레드의 진행 상황 업데이트로 모든 팀원이 정보를 공유합니다
  • 낮은 진입 장벽: 터미널이나 IDE 없이 채팅에서 바로 시작할 수 있습니다
  • GitHub 통합: 적절한 설명과 함께 PR이 자동으로 생성됩니다

요구 사항

  • Claude 통합이 활성화된 Slack 워크스페이스
  • GitHub 리포지토리가 연결되어 있어야 합니다
  • Claude가 브랜치/PR을 생성할 수 있는 적절한 권한이 필요합니다

이 기능은 현재 Pro, Max, Team, Enterprise 사용자를 위한 연구 프리뷰 단계입니다.


Claude Code 비용은 얼마인가요?

지속 가능한 Claude Code 사용을 위해서는 비용을 이해하고 관리하는 것이 필수적입니다.

비용 확인하기

> /cost

출력:

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    247 lines added, 89 lines removed

구독 플랜

플랜 가격 사용량 접근 권한
Free $0 제한됨 Claude Code 접근 불가
Pro $20/월 Free의 5배 Claude Code + Opus 4.5 접근20
Max (5x) $100/월 Pro의 5배 우선 접근, 향상된 성능
Max (20x) $200/월 Pro의 20배 최우선 접근, 추가 사용량 구매 가능

사용량 제한 (2025년 8월): Anthropic은 유료 구독자를 위한 주간 사용량 제한을 도입했습니다. Max 구독자는 사용량 제한을 초과하는 추가 사용량을 표준 API 요금으로 구매할 수 있습니다.21

API 토큰 가격 (2026년 1월)57

API 과금 사용자를 위한 백만 토큰당 가격:

모델 입력 출력 비고
Haiku 4.5 $1 $5 속도와 효율성
Sonnet 4.5 $3 $15 성능/비용 균형
Opus 4.5 $5 $25 플래그십 성능 (Opus 4/4.1 대비 66% 저렴)

프롬프트 캐싱은 반복되는 입력 비용을 크게 줄여줍니다: 캐시 쓰기는 기본 가격의 1.25배(5분 캐시) 또는 2배(1시간 캐시)가 들지만, 캐시 읽기는 0.1배에 불과해 90%를 절약할 수 있습니다. 반복되는 컨텍스트가 있는 RAG 시스템과 코드 어시스턴트의 경우, 캐싱으로 비용을 88-95% 절감할 수 있습니다.

Batch API는 야간 테스트 스위트와 같이 급하지 않은 작업에 대해 24시간 처리 기준으로 50% 할인을 제공합니다.

복수 계정 정책59

여러 개의 Claude 계정을 가질 수 있나요? 네, 합법적인 사용 목적이라면 가능합니다. Anthropic은 별개의 목적을 위한 복수 계정을 명시적으로 허용합니다.

허용되는 경우:

시나리오 예시 상태
가족 구성원 본인과 배우자가 각각 Max 계정 보유 허용
업무 + 개인 개인 계정 + 회사 관리 업무 계정 허용
개인 + 팀 개인 Pro/Max와 조직 계정 병행 허용
동일 네트워크 같은 집 WiFi에서 복수 계정 허용
동일 컴퓨터 한 기기에서 계정 전환 허용

기술적 제한: - 동일한 전화번호로 최대 3개 계정까지 인증 가능 - 동일 IP/네트워크에서의 복수 유료 구독은 명시적으로 지원됨 - 계정은 완전히 분리되어 있어 계정 간 채팅이나 프로젝트 이전 불가

금지 사항 (사용 정책 기준): - 차단된 후 차단 회피를 위한 계정 생성 - 탐지 회피를 위한 계정 간 악의적 활동 조율 - 사용량 제한 우회나 무료 크레딧 남용을 위한 복수 계정 사용

실제 사례: 2026년 1월, 파워 유저 Jeffrey Emanuel(@doodlestein)의 22개 Max 계정이 자동으로 플래그되어 일시적으로 차단되었습니다. Anthropic 직원 Thariq(@trq212)가 합법적 사용임을 확인한 후 4시간 이내에 해결했습니다. 업무와 개인 프로젝트 모두를 위해 여러 계정에서 Claude Code를 광범위하게 사용하고 있다면, 이것이 바로 서비스가 설계된 목적입니다—단, 시스템을 악용하려 하지 마세요.

확실하지 않을 때: Anthropic Support에 연락하여 귀하의 특정 설정에 대해 서면으로 확인받으세요.

비용 요소

요소 영향 최적화 방법
모델 선택 Opus >> Sonnet >> Haiku 간단한 작업에는 Haiku 사용
입력 토큰 컨텍스트가 많을수록 비용 증가 CLAUDE.md를 간결하게 유지
출력 토큰 긴 응답은 비용 증가 MAX_OUTPUT_TOKENS 설정
사고 토큰 확장된 사고는 비용 추가 필요할 때만 사용
프롬프트 캐싱 반복 입력 비용 절감 활성화 상태 유지 (기본값)

실제 비용 예시

작업 모델 입력 출력 비용
빠른 파일 검색 Haiku 20K 2K $0.03
테스트 포함 버그 수정 Sonnet 100K 30K $0.75
아키텍처 검토 Opus 150K 50K $2.00
하루 전체 세션 (Sonnet) Sonnet 500K 150K $3.75
하루 전체 세션 (혼합) Haiku+Sonnet 500K 150K ~$2.00

비용 절감 인사이트: 탐색 서브에이전트에는 Haiku를, 구현에는 Sonnet을 사용하면 모든 작업에 Sonnet을 사용하는 것보다 일반적으로 40-50% 비용이 절감됩니다.

팀 비용 관리

팀 규모별 권장 TPM/RPM:

팀 규모 사용자당 TPM 사용자당 RPM
1-5 200k-300k 5-7
5-20 100k-150k 2.5-3.5
20-50 50k-75k 1.25-1.75
50-100 25k-35k 0.62-0.87
100+ 10k-20k 0.25-0.5

숨겨진 도구 비용

토큰당 가격 외에도 일부 도구는 별도 요금이 발생합니다:16

도구 비용 비고
코드 실행 $0.05/세션-시간 월 1,550시간/조직 무료40
웹 검색 $10/1,000회 검색 토큰 비용 별도
Bash 도구 +245 입력 토큰/호출 호출당 오버헤드
텍스트 에디터 +~700 입력 토큰/호출 일반적인 오버헤드

이러한 비용은 에이전트 루프에서 누적됩니다. Bash를 사용하는 100회 반복 디버그 사이클은 오버헤드만으로 약 24,500개의 추가 입력 토큰이 필요합니다.

비용 절감 전략

  1. 서브에이전트에 Haiku 사용: 대부분의 탐색 작업에는 Sonnet이 필요하지 않음
  2. 프롬프트 캐싱 활성화: 기본값이지만 비활성화되지 않았는지 확인
  3. 최대 턴 수 설정: claude --max-turns 5로 무한 대화 방지
  4. 탐색에 plan 모드 사용: 실행 없음 = 우발적인 고비용 작업 없음
  5. 사전 압축: 더 작은 컨텍스트 = 더 적은 토큰
  6. 출력 제한: export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
  7. 급하지 않은 작업에 Batch API 사용: 입력 및 출력 토큰 모두 50% 할인

사용량 모니터링

  • Claude Console: platform.claude.com (Admin 또는 Billing 역할 필요)
  • Workspace 제한: 워크스페이스별 지출 한도 설정
  • Bedrock/Vertex: 네이티브 클라우드 비용 모니터링 사용
  • LiteLLM: 서드파티 제공업체를 통한 상세한 사용자별 추적

백그라운드 토큰 사용량

일부 작업은 백그라운드에서 토큰을 소비합니다: - /resume을 위한 대화 요약 - /cost/status 명령어 - 자동 압축

일반적으로 세션당 $0.04 미만입니다.

Claude Code Analytics API (Team/Enterprise)53

Admin API를 통해 조직의 Claude Code 사용량 분석 및 생산성 지표에 프로그래밍 방식으로 접근할 수 있습니다.

엔드포인트: GET /v1/organizations/usage_report/claude_code

요구 사항: - Admin API 키 (sk-ant-admin...) - Team 또는 Enterprise 플랜 - Admin, Billing 또는 Developer 역할

사용 가능한 지표:

지표 설명
num_sessions 시작된 고유 Claude Code 세션 수
lines_of_code.added/removed 추가/제거된 총 코드 라인 수
commits_by_claude_code 생성된 git 커밋 수
pull_requests_by_claude_code 생성된 PR 수
terminal_type 환경 (vscode, iTerm.app, tmux 등)
customer_type api (API 고객) 또는 subscription (Pro/Team)

요청 예시:

curl "https://api.anthropic.com/v1/organizations/usage_report/claude_code?starting_at=2026-01-15" \
  -H "x-api-key: sk-ant-admin..." \
  -H "anthropic-version: 2023-06-01"

활용 사례: - 개발자 생산성 분석 (세션, 커밋, PR) - 도구 사용 지표 (Edit, Write 등의 수락/거부율) - 팀 간 비용 추적 및 배분 - AI 코딩 도구의 ROI 정당화

참고: 데이터는 활동 완료 후 1시간 이내에 표시됩니다. 일관성을 위해 1시간 이상 지난 데이터만 응답에 포함됩니다.


성능 최적화

지연 시간 줄이기

모델 선택: - Haiku: 가장 빠른 응답, 가장 낮은 비용 - Sonnet: 좋은 균형 - Opus: 최고 품질, 가장 높은 지연 시간

스트리밍: 모든 응답은 기본적으로 스트리밍됩니다—생성되는 대로 출력을 볼 수 있습니다.

프롬프트 캐싱: 기본적으로 활성화되어 있습니다. 반복되는 컨텍스트(시스템 프롬프트, 도구 정의)의 지연 시간을 줄여줍니다.

캐싱 전략

시스템 프롬프트와 도구 정의는 자동으로 캐싱됩니다: - 캐시 지속 시간: 5분 (임시) - 캐시 적중: 입력 토큰 감소 및 더 빠른 응답

이전 턴의 사고 블록은 멀티턴 대화에서 캐싱됩니다.

필요한 경우 모델별로 캐싱을 비활성화할 수 있습니다:

export DISABLE_PROMPT_CACHING_SONNET=1
export DISABLE_PROMPT_CACHING_OPUS=1
export DISABLE_PROMPT_CACHING_HAIKU=1

병렬 작업

서브에이전트 병렬화: 여러 서브에이전트가 동시에 실행될 수 있습니다. 각각 독립적으로 작동하여 메인 컨텍스트를 오염시키지 않습니다.

백그라운드 bash: 장시간 실행되는 명령어가 대화를 차단하지 않습니다:

> run the full test suite in the background

Git worktrees: 별도의 브랜치에서 진정한 병렬 세션을 활성화합니다.

메모리 최적화

  • 구체적인 파일 참조: “auth 파일 찾아줘” 대신 @src/auth.ts
  • 타겟 검색: “모든 곳에서 검색” 대신 “src/api에서 검색”
  • 새로운 세션: 관련 없는 작업 사이에 /clear
  • 커스텀 압축: 보존할 내용에 대한 지침을 CLAUDE.md에 추가

문제를 어떻게 디버깅하나요?

설치 문제

WSL 경로 문제:

npm config set os linux
npm install -g @anthropic-ai/claude-code --force --no-os-check
which npm  # /mnt/c가 아닌 /usr로 시작해야 함

Node 버전 충돌 (nvm): ~/.bashrc 또는 ~/.zshrc에 추가:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

권한 오류: npm 대신 네이티브 설치 사용:

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

인증 문제

# 완전 초기화
/logout
rm -rf ~/.config/claude-code/auth.json
claude  # 새로 로그인

성능 문제

높은 CPU/메모리: - /compact을 사용하여 컨텍스트 줄이기 - 주요 작업 사이에 재시작 - 큰 디렉토리를 .gitignore에 추가 - claude doctor 실행

느린 검색: 시스템 ripgrep 설치:

# macOS
brew install ripgrep

# Windows
winget install BurntSushi.ripgrep.MSVC

# Linux
sudo apt install ripgrep

그 다음:

export USE_BUILTIN_RIPGREP=0

WSL에서 느림: - 프로젝트를 Linux 파일시스템으로 이동 (/mnt/c/가 아닌 곳) - 검색에서 특정 디렉토리 필터 사용

IDE 통합 문제

JetBrains가 감지되지 않음 (WSL2):

옵션 1 - Windows 방화벽:

wsl hostname -I  # WSL IP 확인
New-NetFirewallRule -DisplayName "Allow WSL2" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16

옵션 2 - 미러링 네트워킹 (~/.wslconfig에 추가):

[wsl2]
networkingMode=mirrored

그 다음: wsl --shutdown

JetBrains에서 Escape 키가 작동하지 않음: Settings → Tools → Terminal → “Move focus to the editor with Escape” 체크 해제

디버그 모드

claude --debug                    # 전체 디버그 출력
ANTHROPIC_LOG=debug claude       # API 요청 로깅
claude doctor                    # 상태 점검

설정 초기화

# 사용자 설정 초기화
rm ~/.claude.json
rm -rf ~/.claude/

# 프로젝트 설정 초기화
rm -rf .claude/
rm .mcp.json

일반적인 오류 메시지

오류 원인 해결 방법
“Rate limit exceeded” 요청이 너무 많음 대기하거나 빈도 줄이기
“Context length exceeded” 대화가 너무 김 /compact 또는 /clear 사용
“Authentication failed” 유효하지 않거나 만료된 토큰 /login 실행
“Tool not permitted” 권한 거부됨 settings.json 권한 확인
“MCP server failed to start” 서버 설정 오류 claude mcp get <name> 확인

엔터프라이즈 배포

클라우드 제공업체 비교

기능 Anthropic 직접 연동 AWS Bedrock Google Vertex Microsoft Foundry
인증 API 키 IAM/API 키 GCP 자격 증명 Entra ID/API 키
비용 추적 콘솔 AWS Cost Explorer GCP Billing Azure Cost Mgmt
감사 로깅 제한적 CloudTrail Cloud Audit Logs Azure Monitor
SSO 미지원 IAM IAM Entra ID

관리형 설정 배포

managed-settings.json을 통해 조직 전체 정책을 배포할 수 있습니다:

위치: - macOS: /Library/Application Support/ClaudeCode/managed-settings.json - Linux: /etc/claude-code/managed-settings.json - Windows: C:\Program Files\ClaudeCode\managed-settings.json

정책 예시:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(curl:*)",
      "Read(.env*)",
      "WebFetch"
    ],
    "defaultMode": "default"
  },
  "model": "claude-sonnet-4-5-20250929",
  "disableBypassPermissionsMode": "disable"
}

사용자는 관리형 설정을 재정의할 수 없습니다.

엔터프라이즈 CLAUDE.md

조직 전체 컨텍스트를 배포합니다:

위치: - macOS: /Library/Application Support/ClaudeCode/CLAUDE.md - Linux: /etc/claude-code/CLAUDE.md

내용:

# Company Standards

## Security Requirements
- Never commit secrets or credentials
- All external API calls require security review
- Use parameterized queries for all database access

## Code Standards
- Follow company style guide at @docs/STYLE.md
- All PRs require two approvals
- Test coverage minimum: 80%

## Approved Tools
- npm, yarn, pnpm for package management
- Jest for testing
- ESLint + Prettier for formatting

롤아웃 전략

  1. 문서화부터 시작: 배포 전에 CLAUDE.md를 제대로 작성합니다
  2. 파일럿 그룹: 5~10명의 개발자로 시작합니다
  3. Q&A 단계: 파일럿 참여자들이 Claude를 코드 탐색에 활용하도록 합니다
  4. 가이드 개발: 간단한 버그 수정으로 점진적으로 확대합니다
  5. 전체 배포: 관리형 설정과 함께 전사 배포합니다
  6. 비용 모니터링: 팀별 사용량을 추적합니다

감사 및 규정 준수

  • 세션 기록은 기본적으로 로컬에 저장됩니다
  • 엔터프라이즈 감사를 위해 클라우드 제공업체 로깅을 활용하세요
  • 상세한 사용량 추적을 위해 LiteLLM 도입을 고려하세요
  • 관리형 설정으로 규정 준수 정책을 시행합니다

Analytics API (관리자)

Enterprise 및 Team 플랜은 프로그래밍 방식의 사용량 추적을 위한 Claude Code Analytics API에 접근할 수 있습니다.

엔드포인트: GET /v1/organizations/usage_report/claude_code

인증: Admin API 키(sk-ant-admin...)가 필요하며, 조직 관리자가 콘솔에서 프로비저닝합니다.

제공 지표:

카테고리 지표
생산성 세션 수, 추가/삭제된 라인 수, 커밋 수, 사용자별 PR 수
도구 사용 도구별 수락/거부율 (Edit, Write, NotebookEdit)
비용 사용자 및 모델별 예상 비용 내역

요청 파라미터: - starting_at - 일별 집계 날짜 (YYYY-MM-DD) - 지정된 날짜의 사용자별 데이터를 반환합니다

예시:

curl -X GET "https://api.anthropic.com/v1/organizations/usage_report/claude_code?starting_at=2026-01-25" \
  -H "x-api-key: sk-ant-admin-..." \
  -H "anthropic-version: 2023-06-01"

제한 사항: - 일별 집계만 제공됩니다 (일관성을 위해 약 1시간 지연) - 실시간 모니터링이 필요한 경우 OpenTelemetry 통합을 사용하세요 - 1st party API 사용량만 추적됩니다 (Bedrock/Vertex 제외)

비용: Admin API 접근 권한이 있는 조직에 무료로 제공됩니다.


키보드 단축키 참조

일반 제어

단축키 동작
Ctrl+C 현재 작업 취소
Ctrl+D 세션 종료 (EOF)
Ctrl+L 화면 지우기 (히스토리 유지)
Ctrl+O 상세 출력 토글
Ctrl+R 명령어 히스토리 검색
Ctrl+V 클립보드에서 이미지 붙여넣기
Ctrl+B 현재 작업을 백그라운드로 전환
Ctrl+Y 킬 링에서 붙여넣기 (Yank)
Ctrl+S 프롬프트 초안 임시 저장 (현재 입력 저장)
Alt+Y 킬 링 순환 (Ctrl+Y 이후 사용)
Esc Esc 마지막 변경 되돌리기
Tab 프롬프트 제안 수락 / 확장 사고 토글
! + Tab Bash 히스토리 자동 완성 (v2.1.14+)
Shift+Tab 권한 모드 순환
Alt+P / Option+P 프롬프트 입력 중 모델 전환
Alt+T 사고 모드 토글 (더 안전한 대안)
Ctrl+T /theme에서 구문 강조 토글
Ctrl+G 외부 편집기 열기 (AskUserQuestion “Other” 입력 시)
Up/Down 명령어 히스토리 탐색
? 단축키 표시

사용자 정의 키 바인딩 (v2.1.18+): /keybindings를 실행하여 키보드 단축키를 사용자 정의할 수 있습니다. 컨텍스트별 바인딩, 코드 시퀀스(다중 키 조합), 완전한 개인화를 지원합니다. 키 바인딩은 ~/.claude/keybindings.json에 저장됩니다. 전체 설정 참조는 키 바인딩 문서를 확인하세요.77

프롬프트 제안 (2025년 12월): Claude가 워크플로우 속도를 높이기 위해 프롬프트를 제안합니다. Tab을 눌러 제안을 수락하거나 Enter를 눌러 직접 프롬프트를 입력하세요.13

여러 줄 입력

방법
이스케이프 줄바꿈 \Enter
macOS Option+Enter
기본 지원 (v2.1.0+) iTerm2, WezTerm, Ghostty, Kitty에서 Shift+Enter37
기타 터미널 Shift+Enter (먼저 /terminal-setup 실행)
제어 문자 Ctrl+J

빠른 접두사

접두사 동작 예시
# 메모리에 추가 # Always use TypeScript
/ 슬래시 명령어 /review
! 직접 bash 실행 ! git status
@ 파일 참조 @src/index.ts
& 클라우드로 전송 & Build the API

파일 참조 성능 (2026년 1월): @ 멘션이 git 저장소에서 3배 빨라졌습니다. Claude Code는 파일 완성 제안 시 .ignore.rgignore 파일도 인식합니다. 이는 빌드 산출물이나 생성된 파일을 제안에서 제외하는 데 유용합니다.35

Vim 모드

/vim으로 활성화합니다:

노멀 모드: - h/j/k/l - 이동 - w/e/b - 단어 단위 이동 - 0/$ - 줄 시작/끝 - gg/G - 버퍼 시작/끝 - dd - 줄 삭제 - cc/C - 줄 변경/끝까지 변경 - dw/de/db - 단어 삭제 변형 - x - 문자 삭제 - . - 마지막 편집 반복

입력 모드: - i/I - 커서 앞/줄 시작에 삽입 - a/A - 커서 뒤/줄 끝에 삽입 - o/O - 아래/위에 새 줄 추가 - Esc - 노멀 모드로 복귀


모범 사례

세션 전략

설명적인 세션 ID를 사용하세요:

claude --session-id "feature-$(git branch --show-current)-$(date +%s)"
claude --session-id "bug-JIRA-456"
claude --session-id "spike-new-architecture"

컨텍스트를 다시 설명하는 대신 진행 중인 작업에 대해 세션을 재개하세요.

CLAUDE.md 설계

스캔하기 쉽게 작성하세요. Claude는 매 세션마다 이 파일을 읽습니다. 장황한 산문은 컨텍스트를 낭비합니다.

명확하지 않은 것에 집중하세요. 프로젝트 고유의 패턴, 독특한 규칙, 결정 사항을 문서화하세요. Claude가 코드에서 추론할 수 있는 내용은 생략하세요.

지속적으로 업데이트하세요. 개발 중에 #으로 메모를 추가하고, 매주 검토하여 정리하세요.

명령어 참조를 포함하세요. 자주 실행하는 명령어를 문서화해야 합니다.

사용자 정의 명령어

반복적인 워크플로우를 위한 명령어를 만드세요:

---
description: Start new feature
allowed-tools: Bash(git:*), Read, Edit
---

1. Create branch: !`git checkout -b feature/$ARGUMENTS`
2. Pull latest main
3. Set up boilerplate
4. Begin implementation

효과적인 프롬프팅

구체적으로 작성하세요:

# Good
"Add email validation to LoginForm in src/components/LoginForm.tsx"

# Too vague
"Improve the login"

파일을 직접 참조하세요:

"Review @src/auth/middleware.ts for security issues"

제약 조건을 제시하세요:

"Refactor using the same pattern as @src/repositories/UserRepository.ts"

탐색에는 subagents를 활용하세요:

"Have an explore agent find all places where we handle errors"

비용 관리

  • /cost를 정기적으로 확인하세요
  • 간단한 작업과 subagents에는 Haiku를 사용하세요
  • MAX_THINKING_TOKENS는 필요한 경우에만 설정하세요
  • 자동화 스크립트에는 --max-turns를 사용하세요
  • 긴 세션에서는 사전에 컨텍스트를 압축하세요

보안

  • .claude/settings.json에 민감한 파일에 대한 거부 규칙을 설정하세요
  • 신뢰할 수 없는 프로젝트에는 샌드박스 모드를 사용하세요
  • Bash(rm -rf:*) 또는 Bash(sudo:*)를 허용하지 마세요
  • hooks를 사용하여 시크릿 접근을 차단하세요
  • 엔터프라이즈 환경에서는 관리형 설정을 배포하세요

커뮤니티 팁과 기법5658

Claude Code 커뮤니티는 공식 문서를 넘어서는 강력한 패턴들을 발견했습니다. 이 팁들은 Boris Cherny(Claude Code 개발자)와 40개 이상의 팁이 담긴 저장소의 파워 유저들로부터 나온 것입니다.

코딩 전에 Plan Mode 사용하기

하나의 팁만 기억한다면, 이것을 기억하세요. 계획에 더 많은 시간을 투자할수록 Claude가 성공할 가능성이 높아집니다. 구현을 시작하기 전에 Shift+Tab을 눌러 plan mode로 전환하세요.

2026년 1월 신규 기능: 계획을 승인하면 Claude가 이제 자동으로 컨텍스트를 초기화할 것인지 제안합니다. 이렇게 하면 계획이 새로운 컨텍스트 윈도우에서 시작됩니다. 이는 계획 준수도를 크게 향상시킵니다—이전 컨텍스트의 간섭 없이 Claude가 더 오래 제대로 진행합니다. 옵션에는 “Yes, clear context and auto-accept edits”(Shift+Tab), “Yes, and manually approve edits”, 또는 “Yes, auto-accept edits”(초기화 없이)가 있습니다.

컨텍스트를 자주 초기화하기

/clear를 자주 사용하세요. 새로운 작업을 시작할 때마다 채팅을 초기화하세요. 이전 기록이 토큰을 소비하거나 비용이 많이 드는 compaction 호출을 유발할 필요가 없습니다. 그냥 초기화하고 다음으로 넘어가세요.

이미지와 스크린샷 사용하기

Claude는 시각적 입력에 뛰어납니다. macOS에서: Cmd+Ctrl+Shift+4로 스크린샷을 클립보드에 캡처한 후, Ctrl+V로 Claude Code에 직접 붙여넣으세요. UI 목업, 오류 메시지, 디자인 참조를 공유하는 데 활용하세요.

PR 리뷰를 위한 GitHub App 설치하기

/install-github-app을 실행하면 Claude가 자동으로 PR을 리뷰합니다. AI 지원 개발로 PR 볼륨이 증가하면서 이 기능은 특히 유용합니다—Claude는 종종 인간 리뷰어가 놓치는 로직 오류와 보안 문제를 발견합니다.

컨테이너 기반 자율 운영

완전한 자율 운영을 위해 Claude Code를 Docker 컨테이너에서 tmux를 제어 레이어로 사용하여 실행하세요. 로컬 Claude Code가 컨테이너화된 인스턴스를 제어하며, 수동 승인 없이 장시간 실행되거나 실험적인 작업을 수행할 수 있습니다. 문제가 발생해도 샌드박스 내에서 격리됩니다.

# Conceptual pattern (varies by setup)
# Local Claude Code → tmux → Container Claude Code
# Results pulled back when complete

Docker Sandbox Mode (빠른 시작): Claude Code는 docker 서브커맨드를 통해 간소화된 Docker 샌드박스를 지원합니다. 이를 통해 신뢰할 수 없는 코드베이스를 탐색하거나 실험적인 프롬프트를 안전하게 실행할 수 있는 격리된 환경을 생성합니다.63

# Run Claude Code in Docker sandbox
docker sandbox run claude

# Or with specific project
docker sandbox run claude /path/to/project

다음과 같은 경우에 sandbox mode를 사용하세요: - 익숙하지 않거나 신뢰할 수 없는 코드베이스 탐색 시 - 파일을 수정할 수 있는 실험적인 프롬프트 테스트 시 - 완전히 격리하고 싶은 자율 세션 실행 시 - 실제 파일에 대한 위험 없이 Claude Code 학습 시

Gemini CLI를 대체 수단으로 활용하기

Claude Code의 WebFetch 도구는 특정 사이트(Reddit 등)에 접근할 수 없습니다. Claude에게 Gemini CLI를 대체 수단으로 사용하도록 지시하는 skill을 만드세요—Gemini는 웹 접근이 가능하며 Claude가 직접 접근할 수 없는 사이트의 콘텐츠를 가져올 수 있습니다.

Meta-Agent Factory 패턴

작업을 수행하는 에이전트를 만드는 대신, 다른 에이전트를 생성하는 에이전트를 만드세요. 이것은 단순히 재귀적인 기교가 아닙니다—복잡한 자동화 워크플로우를 위한 진정한 생산성 증폭기입니다.

Claude Squad: 멀티 에이전트 매니저

Claude Squad는 여러 Claude Code 인스턴스를 병렬로 관리하며, 각각 독립된 tmux 세션과 격리된 worktree에서 실행됩니다. 여러 에이전트를 서로 다른 작업에 동시에 실행하고, 단일 대시보드에서 진행 상황을 모니터링하며, 완료되면 결과를 가져올 수 있습니다.65

# Install
npm install -g @smtg-ai/claude-squad

# Start multiple agents
claude-squad start "Implement auth feature" --worktree auth-feature
claude-squad start "Write API tests" --worktree api-tests
claude-squad start "Update documentation" --worktree docs-update

# Monitor all agents
claude-squad status

사용 사례: - 독립적인 기능들을 여러 에이전트에 걸쳐 병렬화 - 메인 세션을 차단하지 않고 탐색적 프롬프트 실행 - 단일 컨텍스트 윈도우를 넘어 자율 코딩 확장

파워 유저 생산성 통계

Boris Cherny는 Claude Code의 잠재력을 보여주었습니다: 30일 동안 259개의 PR을 머지하고 497개의 커밋을 작성했으며—40,000줄을 추가하고 38,000줄을 삭제했습니다. 이는 Claude Code가 개발 워크플로우에 완전히 통합되었을 때 가능한 것을 보여줍니다.

팔로우할 사람들

다음 계정들을 팔로우하여 Claude Code 개발 동향을 파악하세요:

Anthropic 팀 (주요 소스)

누구 플랫폼 팔로우 이유
Boris Cherny @boris_cherny Claude Code 개발자. 기능 출시, 업데이트 발표, 밋업 주최. 주요 소스.
Cat Wu @_catwu Anthropic. Claude Code 기능 발표, subagent 업데이트.
@adocomplete X Advent of Claude 시리즈 - 포괄적인 일일 튜토리얼(hooks, plugins, prompt stashing).
Thariq @trq212 Claude Code 팀 Anthropic 엔지니어. 이슈 해결, 업데이트 게시.
Anthropic @AnthropicAI 공식 발표 및 주요 릴리스.

주요 콘텐츠 크리에이터

누구 분야 주목할 만한 콘텐츠
@dani_avila7 튜토리얼 Hooks 종합 가이드, rules 설명
@mattpocockuk MCP/팁 10개 레슨 MCP 튜토리얼, Docker sandbox, JSON 최적화
ykdojo GitHub Tips 40개 이상의 팁 저장소, status line 스크립트, 시스템 프롬프트 최적화
@ai_for_success MCP/워크플로우 Hyperbrowser MCP, 문서 캐싱 패턴
@jerryjliu0 에이전트 단계별 에이전트 구축 튜토리얼

주요 리소스

  • GitHub Releases: anthropics/claude-code/releases - 릴리스만 Watch
  • Discord: Anthropic 커뮤니티 채널
  • 전체 목록: 20개 이상의 선별된 계정은 ~/.claude/docs/following-list.md 참조

Boris와 Anthropic 팀은 기능이 출시될 때 바로 공유합니다—종종 문서가 업데이트되기 전에 새로운 기능에 대해 가장 빠르게 알 수 있는 방법입니다.


일반적인 안티패턴

무엇을 하지 말아야 하는지 배우는 것이 모범 사례보다 더 가치 있는 경우가 많습니다. 다음 패턴들은 지속적으로 문제를 일으킵니다:

비용 안티패턴

안티패턴 문제 해결책
모든 것에 Opus 사용 5배 비용, 대부분 불필요 기본은 Sonnet, 아키텍처에만 Opus
/cost 확인 안 함 예상치 못한 청구서 주요 작업 후 비용 확인
간단한 작업에 extended thinking 사용 토큰 낭비 일상 작업에는 끄기(Tab)
메인 컨텍스트에서 explore 실행 컨텍스트 비대화 대신 Explore subagent 사용

컨텍스트 안티패턴

안티패턴 문제 해결책
비대해질 때까지 컨텍스트 무시 추론 저하, 결정 망각 50% 용량에서 /compact 사전 실행
섹션만 필요한데 전체 파일 읽기 관련 없는 코드로 컨텍스트 낭비 특정 줄 범위 참조
subagents 전혀 사용 안 함 모든 것이 메인 컨텍스트를 채움 탐색과 분석은 위임
거대한 CLAUDE.md 파일 매 세션마다 컨텍스트 낭비 500줄 미만 유지, imports 사용

워크플로우 안티패턴

안티패턴 문제 해결책
중복되는 skills과 commands 생성 혼란, 예측 불가능한 동작 목적당 하나의 메커니즘
보장된 작업에 프롬프트 사용 Claude가 건너뛰거나 잊을 수 있음 반드시 실행해야 하는 작업에는 hooks 사용
포매팅용 hooks 없음 일관성 없는 코드 스타일 모든 Edit/Write에 formatter hook
기본적으로 모든 bash 허용 보안 위험 안전한 명령에 대한 명시적 허용 목록

설정 안티패턴

안티패턴 문제 해결책
모든 설정을 user settings에 팀과 아무것도 공유 안 됨 팀 표준에는 project settings
개인 선호도 커밋 팀원 설정 덮어씀 개인용은 settings.local.json 사용
deny rules 없음 Claude가 민감한 파일 접근 가능 .env, 자격 증명, 시크릿 거부
managed settings 무시 기업 정책 우회 규정 준수를 위한 managed settings

프롬프트 안티패턴

안티패턴 문제 해결책
“더 좋게 만들어” 모호함, 저조한 결과 “좋게”가 무엇을 의미하는지 정확히 명시
파일 참조 안 함 Claude가 경로 추측 @path/to/file.ts 구문 사용
Claude의 질문 무시 잘못된 가정으로 작업 진행 진행 전에 답변
스니펫이면 충분한데 전체 문서 제공 컨텍스트 낭비 관련 섹션만 추출

워크플로우 레시피

일반적인 시나리오를 위한 엔드투엔드 패턴입니다.

레시피 1: 새 프로젝트 시작하기

# 1. Initialize
cd my-project
claude

# 2. Let Claude understand the codebase
> "Explore this codebase and summarize the architecture"

# 3. Set up project configuration
> /init

# 4. Create CLAUDE.md with learned patterns
> "Create CLAUDE.md documenting the patterns you observed"

# 5. Add team commands
> "Create a /test command that runs our test suite"
> "Create a /deploy command for staging deployment"

레시피 2: 일상 개발 흐름

# 1. Continue yesterday's session
claude -c

# 2. Quick context recap
> "What did we work on yesterday?"

# 3. Check current state
> /status

# 4. Work on feature (Sonnet handles most tasks)
> "Implement the user profile endpoint"

# 5. Proactive context management
> /compact  # Before context exceeds 50%

# 6. Check spending
> /cost

# 7. End session cleanly
> "Summarize what we accomplished today"

레시피 3: 복잡한 리팩토링

# 1. Use Opus for planning, Sonnet for execution
> /model opusplan

# 2. Plan the refactoring
> "Plan refactoring our authentication from sessions to JWT"

# 3. Review the plan
# (Claude presents approach, you approve or modify)

# 4. Execute with Sonnet
> "Execute the plan"

# 5. Verify nothing broke
> "Have an explore agent verify all auth-related tests pass"

# 6. Review the diff
> !git diff

레시피 4: PR 리뷰 자동화

# In CI/CD (GitHub Actions, etc.)
claude -p "Review this PR for:" \
  --input-file pr_diff.txt \
  --output-format json \
  --permission-mode plan \
  --max-turns 5 << EOF
- Security vulnerabilities
- Performance issues
- Code style violations
- Missing test coverage
Provide findings in JSON format.
EOF

레시피 5: 프로덕션 이슈 디버깅

# 1. Configure Sentry MCP for error access
claude --add-mcp sentry

# 2. Get error context
> "Fetch the last 10 errors from Sentry for the auth service"

# 3. Deep dive with thinking
> Tab  # Enable extended thinking
> "Analyze these errors and identify the root cause"

# 4. Fix and verify
> "Implement a fix and add a regression test"
> !npm test

마이그레이션 가이드

다른 AI 코딩 도구에서 전환하시나요? 개념이 어떻게 대응되는지 알아보세요.

GitHub Copilot에서 전환

Copilot 개념 Claude Code 대응
탭 자동완성 주요 기능 아님—Claude Code는 에이전트 기반 편집 수행
채팅 패널 제안 도구 실행이 가능한 REPL 대화
인라인 제안 @file 참조 + Edit 도구 사용
파일 생성 불가 파일 직접 생성, 편집, 삭제
터미널 접근 불가 전체 bash 실행 (권한 포함)
제한된 컨텍스트 200K-1M 토큰 윈도우
IDE 전용 터미널 + IDE 확장 프로그램

얻게 되는 것: 진정한 에이전트 기능—Claude Code는 코드베이스를 읽고, 테스트를 실행하고, PR을 생성하며, 서브에이전트에 작업을 위임합니다. 단순한 제안이 아닙니다.

Cursor에서 전환

Cursor 개념 Claude Code 대응
Composer 전체 도구 접근이 가능한 세션
Chat 서브에이전트 위임이 가능한 REPL
코드베이스 인덱싱 실시간 파일 접근 (Glob, Grep, Read)
탭 자동완성 주요 기능 아님
IDE 통합 터미널 네이티브 + IDE 확장 프로그램
MCP 없음 300개 이상의 MCP 통합
Cursor rules CLAUDE.md + Skills

얻게 되는 것: MCP 통합(데이터베이스, GitHub, Sentry), 서브에이전트 위임, 자동화를 위한 hooks, 터미널 네이티브 워크플로우.

ChatGPT / Claude Web에서 전환

웹 인터페이스 Claude Code
코드 복사-붙여넣기 직접 파일 접근
수동 파일 생성 파일 직접 작성
실행 불가 전체 bash, git, npm 등
컨텍스트 초기화 세션 연속성 (-c 플래그)
코드베이스 인식 없음 Glob, Grep, Read 도구
자동화 없음 Hooks, CI/CD 통합

얻게 되는 것: 모든 것. 웹 인터페이스는 복사-붙여넣기 워크플로우가 필요하지만, Claude Code는 코드베이스에서 직접 작업합니다.

핵심 사고방식 전환

  1. 코드 복사를 멈추세요. Claude Code가 파일에 직접 작성합니다.
  2. 컨텍스트 전환을 멈추세요. MCP가 외부 도구를 세션으로 가져옵니다.
  3. 적극적으로 위임하세요. 서브에이전트가 컨텍스트를 부풀리지 않고 탐색을 처리합니다.
  4. hooks로 자동화하세요. 포매팅, 린팅, 로깅이 자동으로 실행됩니다.
  5. 세션 단위로 생각하세요. 새 대화가 아닌 -c로 작업을 계속하세요.

핵심 요약

개발자를 위해: - Haiku는 Opus보다 10-20배 저렴합니다—서브에이전트와 간단한 작업에 사용하세요 - 긴 세션에서 컨텍스트 관리를 위해 /compact를 미리 사용하세요 - 컨텍스트를 인코딩하는 세션 ID(feature-${branch}-${timestamp})가 이전 작업으로 돌아가는 데 도움이 됩니다 - 자주 사용하는 프롬프트에 #을 붙여 추가 입력 없이 영구 메모리에 추가하세요

DevOps 및 플랫폼 팀을 위해: - 헤드리스 모드(-p 플래그)는 파싱을 위한 JSON 출력과 함께 CI/CD 통합을 가능하게 합니다 - Hooks는 모델 동작과 관계없이 실행을 보장합니다—린팅, 포매팅, 보안 검사에 사용하세요 - MCP는 데이터베이스, GitHub, Sentry 및 300개 이상의 통합으로 기능을 확장합니다 - 백그라운드 작업(& 접두사)은 비동기 실행을 위해 Claude Code Remote에서 실행됩니다

보안 팀을 위해: - 권한 규칙은 first-match-wins로 평가됩니다—allow/deny 목록을 신중하게 구성하세요 - 샌드박스 모드는 신뢰할 수 없는 코드베이스를 위해 파일시스템과 네트워크를 격리합니다 - Bash 패턴은 접두사만 매칭합니다—Bash(curl:*)은 특정 URL이 아닌 모든 curl을 차단합니다 - 엔터프라이즈 관리 설정은 사용자가 재정의할 수 없습니다

팀 리더를 위해: - Skills는 컨텍스트에 따라 자동 활성화됩니다—명시적 호출 없이 도메인 전문 지식을 내장하세요 - 프로젝트 skills는 git에 커밋됩니다—팀원들이 자동으로 표준화된 전문 지식을 얻습니다 - /cost를 통한 비용 추적은 세션 분석을 보여줍니다; 팀 규모에 따라 사용자당 10k-300k TPM을 예산으로 잡으세요 - .claude/commands/의 커스텀 명령어가 재사용 가능한 워크플로우를 생성합니다

엔터프라이즈 아키텍트를 위해: - 관리 설정은 /etc/claude-code/managed-settings.json을 통해 조직 전체 정책을 배포합니다 - AWS Bedrock, Google Vertex AI, Microsoft Foundry가 기존 클라우드 빌링과 통합됩니다 - Extended thinking(Tab으로 전환)은 더 높은 비용으로 복잡한 추론을 개선합니다 - 전체 배포 전 5-10명의 개발자로 파일럿을 시작하세요


빠른 참조 카드

이것을 인쇄하세요. 모니터에 붙이세요.

╔═══════════════════════════════════════════════════════════════╗
║                    CLAUDE CODE QUICK REFERENCE                 ║
╠═══════════════════════════════════════════════════════════════╣
║  MODELS                                                        ║
║    haiku     $1/$5/M     Exploration, simple tasks            ║
║    sonnet    $3/$15/M    Daily coding (default)               ║
║    opus      $5/$25/M    Architecture, hard problems          ║
║    sonnet[1m] $6/$22.50/M Large codebases (1M context)        ║
╠═══════════════════════════════════════════════════════════════╣
║  ESSENTIAL COMMANDS                                            ║
║    /compact        Reduce context (do at 50% capacity)        ║
║    /cost           Check session spending                     ║
║    /model opus     Switch to Opus                             ║
║    /status         Show current state                         ║
║    /init           Set up project config                      ║
║    /mcp            Configure integrations                     ║
╠═══════════════════════════════════════════════════════════════╣
║  KEYBOARD SHORTCUTS                                            ║
║    Tab             Toggle extended thinking                   ║
║    Shift+Tab       Cycle permission modes                     ║
║    Ctrl+C          Interrupt current operation                ║
║    Esc → Esc       Rewind last change                         ║
║    Ctrl+L          Clear screen                               ║
╠═══════════════════════════════════════════════════════════════╣
║  PREFIXES                                                      ║
║    #message        Add to persistent memory                   ║
║    @path/file      Reference file in prompt                   ║
║    !command        Execute bash directly                      ║
║    &task           Send to cloud (async)                      ║
╠═══════════════════════════════════════════════════════════════╣
║  CONFIG FILE HIERARCHY (first found wins)                      ║
║    .claude/settings.local.json    Personal (gitignored)       ║
║    .claude/settings.json          Project (shared)            ║
║    ~/.claude/settings.json        User global                 ║
║    /etc/.../managed-settings.json Enterprise (locked)         ║
║    CLAUDE.md                      Project context             ║
╠═══════════════════════════════════════════════════════════════╣
║  DAILY WORKFLOW                                                ║
║    1. claude -c              Continue session                 ║
║    2. Work on features       Use Sonnet                       ║
║    3. /compact               Before context bloats            ║
║    4. /cost                  Check spending                   ║
║    5. Summarize              Clean exit                       ║
╠═══════════════════════════════════════════════════════════════╣
║  DECISION RULES                                                ║
║    Simple task?        → Haiku                                ║
║    Hard reasoning?     → Opus                                 ║
║    Everything else?    → Sonnet                               ║
║    Must always run?    → Hook (not prompt)                    ║
║    Auto-apply wisdom?  → Skill (not command)                  ║
║    Needs isolation?    → Subagent                             ║
╚═══════════════════════════════════════════════════════════════╝

변경 이력

이 참조 문서는 살아있는 문서입니다. Claude Code가 발전함에 따라 업데이트가 적용됩니다.

날짜 변경 사항 출처
2026-01-30 추가: v2.1.27—GitHub PR 번호/URL에 연결된 세션을 재개하는 --from-pr 플래그, gh pr create를 통해 생성된 세션이 PR에 자동 연결, 디버그 로그에 도구 호출 실패/거부 기록, VSCode Claude in Chrome 통합 활성화. 수정: 게이트웨이 사용자의 컨텍스트 관리 유효성 검사, /context 컬러 출력, 상태 표시줄에 백그라운드 작업 표시기 중복, 권한 우선순위(콘텐츠 수준 ask > 도구 수준 allow). Windows: .bashrc를 사용한 bash 실행, 콘솔 창 깜빡임. VSCode: 401 오류를 유발하는 OAuth 토큰 만료. 81
2026-01-29 추가: v2.1.25—Bedrock 및 Vertex 게이트웨이 사용자의 베타 헤더 유효성 검사 오류 수정. 임시 해결책: CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1. 80
2026-01-28 추가: v2.1.23—사용자 정의 스피너 텍스트를 위한 spinnerVerbs 설정, 기업 환경을 위한 mTLS/프록시 연결 수정, 사용자별 임시 디렉토리 격리, ripgrep 타임아웃 오류 보고(기존에는 빈 결과를 조용히 반환), 프롬프트 푸터에 병합된 PR 보라색 상태 표시기, bash 타임아웃 기간 표시. 수정: 프롬프트 캐싱 경쟁 조건, 헤드리스 모드에서 대기 중인 비동기 hooks가 취소되지 않음, 탭 완성이 입력을 업데이트하지 않음, 헤드리스 모드에서 Bedrock 리전 표시. 76
2026-01-28 추가: v2.1.22—비대화형(-p) 모드에서 구조화된 출력 수정. 75
2026-01-28 추가: v2.1.21—VSCode에서 Python venv 자동 활성화(claudeCode.usePythonEnvironment 설정), 일본어 IME 전각(全角) 숫자 입력 지원, Read/검색 진행률 표시기(“Reading…” → “Read”), Claude가 이제 bash 대신 파일 작업 도구를 선호함. 수정: 종료 시 셸 완성 캐시 잘림, 도구 실행 중 중단된 세션 재개 시 API 오류, 큰 출력 제한이 있는 모델에서 자동 압축이 너무 일찍 트리거됨, 삭제 후 작업 ID 재사용, Windows에서 VSCode 파일 검색. 74
2026-01-28 추가: MCP Apps(Asana, Figma, Slack 등을 위한 Claude 내 대화형 도구 UI). Code Execution Tool v2(Python 전용을 대체하는 Bash 실행, 프로그래매틱 도구 호출). Team/Enterprise 프리미엄 시트에 웹에서 Claude Code 확장. 737879
2026-01-27 추가: v2.1.20—추가 디렉토리에서 CLAUDE.md를 로드하는 --add-dir 플래그(CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 필요), 프롬프트 푸터에 PR 리뷰 상태 표시기(승인됨/변경 요청/대기 중/초안을 나타내는 색상 점), TaskUpdate 도구를 통한 작업 삭제, vim 화살표 키 히스토리 탐색, 모든 사용자에게 /copy 명령 사용 가능, 타임스탬프가 있는 설정 백업(순환, 최근 5개 유지). 수정: 재개 시 전체 히스토리를 로드하는 세션 압축, 작업 중 사용자 메시지를 무시하는 에이전트, 와이드 문자(이모지/CJK) 렌더링 아티팩트, MCP 응답에서 유니코드가 포함된 JSON 파싱. 72
2026-01-26 개선: Analytics API 섹션에 상세 엔드포인트 문서, 메트릭 표, curl 예제 및 제한 사항 추가. 이제 인증 요구 사항, 사용 가능한 메트릭(생산성, 도구 사용, 비용) 및 실시간 모니터링 대안을 포함. 53
2026-01-24 추가: v2.1.19—사용자 정의 명령 인수를 위한 $0, $1 약어($ARGUMENTS.0에서 $ARGUMENTS[0] 대괄호 구문으로 변경), 새 작업 시스템을 비활성화하는 CLAUDE_CODE_ENABLE_TASKS 환경 변수, 추가 권한/hooks가 없는 skills는 더 이상 승인이 필요하지 않음. VSCode: 모든 사용자에게 세션 포크 및 되감기 활성화. SDK: SDKUserMessageReplay 이벤트로서 queued_command 재생. 수정: 터미널 닫을 때 남은 프로세스, git worktrees에서 /rename//tag, 프롬프트 임시 저장(Ctrl+S)으로 붙여넣은 텍스트 손실, 에이전트 모델 표시, 백그라운드 hook 명령이 일찍 반환되지 않음, 빈 줄을 생략하는 파일 쓰기 미리보기. 71
2026-01-24 추가: v2.1.17—AVX 명령어를 지원하지 않는 프로세서에서 충돌 수정. 71
2026-01-24 호환성 변경: Extended thinking이 이제 기본적으로 31,999 토큰으로 활성화됨. 자연어 트리거(think, think hard, ultrathink)는 더 이상 사용되지 않으며 더 이상 사고 토큰을 할당하지 않음—대신 MAX_THINKING_TOKENS 환경 변수 또는 /config를 사용하세요. 현재 동작으로 Extended Thinking 섹션 업데이트. 70
2026-01-24 추가: v2.1.18—컨텍스트별 키 바인딩, 코드 시퀀스 및 /keybindings 명령을 통한 완전한 개인화가 가능한 사용자 정의 키보드 단축키. 설정은 ~/.claude/keybindings.json에 저장됨. 77
2026-01-24 추가: v2.1.16—의존성 추적이 있는 작업 관리 시스템, VSCode 네이티브 플러그인 관리 지원, OAuth 사용자는 Sessions 대화 상자에서 원격 세션을 탐색/재개할 수 있음. 수정: 서브에이전트 재개로 인한 메모리 부족 충돌, /compact 경고 표시 문제, 세션 제목 언어 설정, Windows IDE 경쟁 조건. 69
2026-01-21 추가: v2.1.15—npm 설치 지원 중단 알림(네이티브 바이너리 권장), React Compiler UI 성능 개선. 수정: /compact 경고가 지워지지 않음, MCP stdio 서버 타임아웃이 자식 프로세스를 종료하지 않음(UI 프리징 유발 가능). 68
2026-01-20 추가: v2.1.14—bash 모드에서 히스토리 기반 자동완성(! + Tab), 설치된 목록에서 플러그인 검색, git 커밋 SHA에 플러그인 고정, VSCode /usage 명령. 중요 수정: 컨텍스트 창 차단 제한(~65%→~98%), 병렬 서브에이전트로 인한 메모리 충돌, 긴 세션에서 메모리 누수, bash 모드에서 @ 기호 파일 자동완성, /feedback 잘못된 URL, /context 토큰 수 표시, 슬래시 명령 자동완성 잘못된 선택. 67
2026-01-20 추가: v2.1.12(메시지 렌더링 버그 수정). Setup hook 버전을 전체 릴리스 노트가 포함된 v2.1.10으로 수정: OAuth URL 복사를 위한 ‘c’ 키보드 단축키, 시작 키 입력 캡처 개선, 제거 가능한 첨부 파일로 파일 제안, VSCode 플러그인 설치 횟수 및 신뢰 경고. teleport 단방향 제한 참고 추가. 66
2026-01-19 문서 새로고침: 이벤트 표에 SubagentStart hook 추가, PreToolUse hooks(v2.1.9)의 additionalContext 문서 확장, LSP 도구 기능 섹션 확장, 콘텐츠 제작자 및 공식 리소스로 People to Follow 개선.
2026-01-19 추가: Setup hook 이벤트(v2.1.10)—환경 설정 작업을 위해 --init, --init-only 또는 --maintenance CLI 플래그를 통해 트리거됨. 60
2026-01-18 추가: 다중 계정 정책 섹션(허용되는 것, 기술적 제한, 금지되는 것). 커뮤니티 팁 섹션 추가(플랜 모드 자동 컨텍스트 지우기, /clear, 스크린샷, 컨테이너 패턴). People to Follow 추가(Boris Cherny, Thariq, Jeffrey Emanuel). API 토큰 가격 표 추가. 56575859
2026-01-17 추가: v2.1.11 릴리스—HTTP/SSE 전송에 대한 과도한 MCP 연결 요청 수정(대량 MCP 사용자를 위한 안정성 개선). 55
2026-01-16 추가: 벤치마크가 포함된 MCP Tool Search 섹션(Opus 4: 49%→74%, Opus 4.5: 79.5%→88.1%, 85% 토큰 오버헤드 감소). MCP 생태계 통계 업데이트(월 1억 다운로드, 3,000개 이상 서버). 54
2026-01-16 추가: Claude Code Analytics API 섹션—Admin API 엔드포인트 /v1/organizations/usage_report/claude_code를 통해 Team/Enterprise용 사용량 메트릭(세션, 커밋, PR, 코드 줄 수)에 프로그래매틱 접근. ${CLAUDE_SESSION_ID} skill 대체 문서화(v2.1.9). 5153
2026-01-15 추가: v2.1.9 MCP 도구 검색 임계값을 위한 auto:N 구문, plansDirectory 설정, AskUserQuestion에서 외부 편집기(Ctrl+G), 웹 세션 커밋/PR에 대한 세션 URL 귀속, PreToolUse hooks additionalContext. 수정: 병렬 도구 호출 API 오류, MCP 재연결 중단, Kitty에서 Ctrl+Z. Cowork(비기술 사용자를 위한 GUI 버전) 추가. 5152
2026-01-15 추가: v2.1.7 권한 피드백 기능(권한 프롬프트 수락 시 피드백 제공). GitHub Action v1.0 GA 릴리스. 마이너 문서 새로고침. 48
2026-01-14 추가: v2.1.7 기본으로 활성화된 MCP 도구 검색 자동 모드(컨텍스트의 10% 이상인 도구 지연), showTurnDuration 설정, 작업 알림에 인라인 에이전트 응답, 복합 명령 일치 와일드카드 권한 보안 수정. v2.1.6: /config 검색, /doctor 업데이트 섹션, /stats 날짜 범위 필터링, 중첩된 .claude/skills 검색, context_window.used_percentage/remaining_percentage 필드, 셸 줄 연속 권한 우회 보안 수정. v2.1.5: CLAUDE_CODE_TMPDIR 환경 변수. 484950
2026-01-13 추가: console.anthropic.com에서 platform.claude.com으로 URL 변경(v2.1.4). 격리된 컨텍스트를 위한 context: fork skill frontmatter 옵션 추가. 서브에이전트의 권한 거부 복원력 추가(v2.1.0 이상). 플러그인 마켓플레이스 출시 정보 추가(2025년 12월 36개 큐레이션된 플러그인). 47
2026-01-12 추가: v2.1.4 자동 백그라운딩 및 Ctrl+B 단축키를 포함한 모든 백그라운드 작업 기능을 비활성화하는 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS 환경 변수. “Help improve Claude” 설정에 대한 OAuth 토큰 새로고침 수정. 46
2026-01-10 추가: 샌드박싱으로 권한 프롬프트 84% 감소(Anthropic 엔지니어링 블로그에서), Opus 4.5 SWE-bench 성능(80.9%) 및 토큰 효율성 개선. 마이너 문서 새로고침. 45
2026-01-10 추가: v2.1.3 슬래시 명령과 skills 병합(통합 멘탈 모델), /config에서 릴리스 채널 토글(stable/latest), /doctor가 접근 불가능한 권한 규칙 감지, hook 실행 타임아웃이 60초에서 10분으로 증가. 버그 수정: /clear에서 플랜 파일이 유지됨, ExFAT에서 skill 중복 감지, 백그라운드 작업 수 불일치, 압축 중 잘못된 모델을 사용하는 서브에이전트. VSCode: 권한에 대한 클릭 가능한 대상 선택기. 44
2026-01-09 추가: v2.1.1(109개 CLI 개선), 컴포넌트 범위 Hooks(once 옵션이 있는 skill/명령 frontmatter의 hooks), 새 MCP 서버(Figma Dev Mode, Sequential Thinking, Magic UI, Context7). MCP 생태계 수를 3,000개 이상 서버로 업데이트. 414243
2026-01-08 추가: settings.json 참조에 languagerespectGitignore 설정. IS_DEMO 환경 변수 추가. 멀티라인 입력이 iTerm2/WezTerm/Ghostty/Kitty에서 Shift+Enter가 기본적으로 작동함을 표시하도록 업데이트. 조직당 월 1,550 무료 코드 실행 시간 추가. 3740
2026-01-08 추가: v2.1.2 도구 출력에서 클릭 가능한 파일 경로(iTerm용 OSC 8), Windows Package Manager(winget) 지원, 플랜 모드에서 “자동 편집 수락”을 위한 Shift+Tab, FORCE_AUTOUPDATE_PLUGINS 환경 변수, SessionStart hook의 agent_type 필드. 보안 수정: bash 처리의 명령 주입, tree-sitter의 메모리 누수. 사고 토글을 Alt+T로 업데이트. MCP 와일드카드 권한 구문(mcp__server__*) 추가. ask 권한이 있는 PreToolUse hooks updatedInput 추가. 39
2026-01-07 추가: v2.1.0 자동 skill 핫 리로드(~/.claude/skills 또는 .claude/skills의 skills가 재시작 없이 즉시 사용 가능). 보안: CVE-2025-52882 WebSocket 인증 우회가 IDE 확장 v1.0.24 이상에서 패치됨 3738
2026-01-06 추가: v2.0.74 클릭 가능한 이미지 링크([Image #N]), /context 그룹화된 표시, git 저장소에서 파일 @ 멘션 3배 빠름, .ignore.rgignore 지원, Claude Agent SDK v0.1.74 343536
2025-12-28 추가: 이름 있는 세션(/rename, /resume <n>), 플러그인 검색 필터링, 사용자 정의 세션 ID가 있는 --fork-session, Agent Skills 섹션, 비동기 서브에이전트, Claude Agent SDK(Claude Code SDK에서 이름 변경), Alt+Y 양크 팝, Alt+T 사고 토글, Ctrl+T 구문 강조 토글, 휴일 프로모션(12월 25-31일 2배 제한) 2930313233
2025-12-24 추가: Claude in Chrome 섹션, Claude Code in Slack 섹션, LSP 도구, 원격 MCP OAuth 지원, ‘ultrathink’ 명령, /theme/plugin 명령, Kitty/Alacritty/Zed/Warp 터미널 지원 232425262728
2025-12-14 추가: Pro 사용자 Opus 4.5 접근, 구독 플랜 표, 요금 제한(2025년 8월), iOS 앱 가용성 202122
2025-12-12 추가: Background Agents 섹션, Output Styles 섹션, 숨겨진 도구 수수료, /stats, /fork, /rename, /statusline, /tasks 명령, .claude/rules/ 메모리 디렉토리, Batch API 팁 16171819
2025-12-12 추가: Slack 통합, 프롬프트 제안, Alt+P 모델 전환, /release-notes 명령, /rewind 명령, 대화형 MCP 설정 마법사 131415
2025-12-12 초기 10.0 버전: 아키텍처 멘탈 모델, 의사결정 프레임워크, 안티패턴, 워크플로 레시피, 마이그레이션 가이드, 빠른 참조 카드

/update-cc-guide를 실행하여 최신 Claude Code 업데이트를 스캔하고 적용하세요.


참고 문헌


  1. Anthropic Pricing. “Claude API 가격 정책.” 2025년 12월. 

  2. Claude Code Subagents. “Subagents 문서.” 2025년 12월. 

  3. MCPcat. “MCP 서버 다운로드 성장 통계.” 2025년 12월. 

  4. Anthropic. “Claude Code 문서.” 2025년 12월. 

  5. Anthropic. “CLI 레퍼런스.” 2025년 12월. 

  6. Anthropic. “설정 문서.” 2025년 12월. 

  7. Anthropic. “Hooks 가이드.” 2025년 12월. 

  8. Anthropic. “MCP 문서.” 2025년 12월. 

  9. Anthropic. “Claude Code 모범 사례.” 2025년 4월. 

  10. Anthropic. “원격 MCP 지원.” 2025년 12월. 

  11. Anthropic. “Claude Agent SDK로 에이전트 구축하기.” 2025년 12월. 

  12. GitHub. “Claude Code GitHub Action.” 2025년 12월. 

  13. Claude Code CHANGELOG. “프롬프트 제안: Claude가 이제 다음에 수행할 작업을 제안합니다.” 2025년 12월 16일. 2025년 12월 기능 관련 보도는 TechCrunch도 참조하세요. 

  14. Anthropic. “Claude Slack 통합.” 2025년 12월. 

  15. Anthropic. “대화형 MCP 설정.” 2025년 12월. 

  16. Northflank. “Claude Code 숨겨진 도구 요금.” 2025년 7월. 

  17. Anthropic. “Background Agents.” 2025년 12월. 

  18. Claude Code Docs. “Memory Rules 디렉토리.” 2025년 12월. 

  19. GitHub. “출력 스타일 릴리스.” 2025년 12월. 

  20. GitHub CHANGELOG. “Pro 사용자는 이제 구독의 일부로 Opus 4.5에 접근할 수 있습니다.” 2025년 12월. 

  21. Northflank. “2025년 8월 Rate Limit 변경 사항.” 2025년 7월. 

  22. Claude Blog. “웹 및 iOS 앱의 Claude Code.” 2025년 11월. 

  23. Claude Blog. “Team 및 Enterprise 사용자를 위한 웹의 Claude Code.” 2025년 11월. 

  24. GitHub Releases. “Claude in Chrome (베타) 기능.” 2025년 12월. 

  25. GitHub Releases. “LSP 도구 및 터미널 지원 업데이트 (v2.0.74).” 2025년 12월. 

  26. TechCrunch. “Slack에서의 Claude Code 발표.” 2025년 12월. 

  27. GitHub Releases. “Thinking 모드 트리거: think, think harder, ultrathink.” 2025년 12월. 

  28. Anthropic. “OAuth를 통한 원격 MCP 지원.” 2025년 6월. 

  29. GitHub Releases. “/rename 및 /resume을 통한 이름 있는 세션.” 2025년 12월. 

  30. GitHub Releases. “플러그인 검색 필터링, –fork-session을 통한 사용자 정의 세션 ID (v2.0.73-74).” 2025년 12월. 

  31. Anthropic Engineering. “Agent Skills: 재사용 가능한 작업별 모듈.” 2025년 12월. 

  32. Anthropic Engineering. “Claude Agent SDK (Claude Code SDK에서 이름 변경).” 2025년 12월. 

  33. Apidog. “2025년 12월 25-31일 Pro/Max 구독자를 위한 Claude Code 2배 사용량 제한.” 2025년 12월. 

  34. GitHub Releases. “v2.0.73-74: 클릭 가능한 이미지 링크, /context 그룹화 표시, ctrl+t 구문 강조 토글.” 2026년 1월. 

  35. GitHub Releases. “v2.0.72: git 저장소에서 @ 멘션 파일 제안 3배 빨라짐, .ignore.rgignore 파일 지원.” 2026년 1월. 

  36. GitHub Claude Agent SDK. “Claude Agent SDK v0.1.74가 Claude Code v2.0.74와 동기화됨.” 2026년 1월. 

  37. GitHub Releases. “v2.1.0: 자동 스킬 핫 리로드, 응답 언어를 위한 language 설정, settings.json의 respectGitignore, IS_DEMO 환경 변수, iTerm2/WezTerm/Ghostty/Kitty에서 Shift+Enter 기본 작동.” 2026년 1월. 

  38. Datadog Security Labs. “CVE-2025-52882: Claude Code IDE 확장의 WebSocket 인증 우회가 v1.0.24+에서 패치됨.” 2026년 1월. 

  39. GitHub Releases. “v2.1.2: 클릭 가능한 파일 경로 (OSC 8), winget 지원, 플랜 모드에서 Shift+Tab 자동 수락, FORCE_AUTOUPDATE_PLUGINS, SessionStart hook의 agent_type, 보안 수정 (커맨드 인젝션, 메모리 누수), thinking 토글이 Alt+T로 변경, MCP 와일드카드 권한, ask를 통한 PreToolUse updatedInput.” 2026년 1월. 

  40. Anthropic Pricing. “각 조직은 월별 코드 실행 도구와 함께 1,550시간의 무료 사용량을 받습니다.” 2026년 1월. 

  41. VentureBeat. “Claude Code 2.1.0이 인프라 수준의 기능을 도입했습니다. 스코프가 지정된 PreToolUse, PostToolUse, Stop 로직을 갖춘 에이전트, 스킬, 슬래시 커맨드용 Hooks.” 2026년 1월. Medium. “Claude Code 2.1.1이 109개의 CLI 개선 사항과 함께 출시되었습니다.” 

  42. Builder.io. “Figma의 공식 Dev Mode MCP 서버는 선택한 레이어의 라이브 구조(계층 구조, 자동 레이아웃, 배리언트, 텍스트 스타일, 토큰 참조)를 노출합니다.” 2025년 12월. 

  43. Apidog. “Sequential Thinking MCP 서버는 Claude가 구조화된 반성적 사고 프로세스로 문제를 체계적으로 해결할 수 있게 합니다.” 2026년 1월. MCP.so. “3,000개 이상의 MCP 서버가 인덱싱되어 있습니다.” 

  44. GitHub Releases. “v2.1.3: 슬래시 커맨드와 스킬 병합, /config의 릴리스 채널 토글, /doctor 접근 불가 권한 감지, hook 타임아웃 10분으로 증가.” 2026년 1월. 

  45. Anthropic. “샌드박싱으로 권한 프롬프트가 84% 안전하게 감소합니다.” 2026년 1월. Anthropic. “Claude Opus 4.5는 토큰 사용량을 절반으로 줄이면서 SWE-bench Verified에서 80.9%를 달성했습니다.” 

  46. GitHub Releases. “v2.1.4: CLAUDE_CODE_DISABLE_BACKGROUND_TASKS 환경 변수 추가, ‘Help improve Claude’ 설정의 OAuth 토큰 새로고침 수정.” 2026년 1월. 

  47. VentureBeat. “Claude Code 2.1.0: 스킬 프론트매터의 context: fork를 통한 포크된 서브 에이전트 컨텍스트, 권한 거부 후에도 에이전트 계속 진행.” 2026년 1월. GitHub ykdojo/claude-code-tips. “Anthropic은 2025년 12월에 36개의 큐레이션된 플러그인으로 플러그인 마켓플레이스를 공식 출시했습니다.” 

  48. GitHub Releases. “v2.1.7: MCP 도구 검색 자동 모드 기본 활성화, showTurnDuration 설정, 작업 알림의 인라인 에이전트 응답, 와일드카드 권한 보안 수정.” 2026년 1월. 

  49. GitHub Releases. “v2.1.6: /config 검색, /doctor 업데이트 섹션, /stats 날짜 범위 필터링, 중첩 스킬 검색, context_window 백분율 필드, 셸 줄 연속 보안 수정.” 2026년 1월. 

  50. GitHub Releases. “v2.1.5: 임시 디렉토리 재정의를 위한 CLAUDE_CODE_TMPDIR 환경 변수.” 2026년 1월. 

  51. GitHub Releases. “v2.1.9: 사용자 정의 커맨드 인수를 위한 $0/$1 단축 문법, CLAUDE_CODE_ENABLE_TASKS 환경 변수, AskUserQuestion의 외부 에디터 (Ctrl+G), 커밋/PR에 대한 세션 URL 귀속, PreToolUse hooks additionalContext 추가. 병렬 도구 호출 API 오류, MCP 재연결 멈춤, Kitty에서 Ctrl+Z 수정.” 2026년 1월. 

  52. Wikipedia. “비기술 사용자를 대상으로 한 그래픽 사용자 인터페이스가 있는 ‘Cowork’라는 버전이 2026년 1월에 출시되었습니다.” 2026년 1월. 

  53. Claude Docs. “Claude Code Analytics Admin API를 사용하여 조직의 Claude Code 사용량 분석 및 생산성 지표에 프로그래밍 방식으로 접근할 수 있습니다.” 2026년 1월. 

  54. VentureBeat. “MCP Tool Search: Opus 4 정확도가 49%에서 74%로, Opus 4.5가 79.5%에서 88.1%로 향상되었습니다. Boris Cherny: ‘모든 Claude Code 사용자가 훨씬 더 많은 컨텍스트를 얻게 되었습니다.’” 2026년 1월. Anthropic. “MCP는 월간 1억 다운로드에 도달하여 업계 표준이 되었습니다.” 2026년 1월. 

  55. Claude Code v2.1.11 릴리스 노트. “HTTP/SSE 전송에 대한 과도한 MCP 연결 요청 수정.” 2026년 1월 17일. 

  56. Medium. “Boris Cherny: Claude Code를 사용하여 30일 동안 259개의 PR, 497개의 커밋, 40,000줄 추가, 38,000줄 삭제.” 2026년 1월. 

  57. Anthropic Pricing. “API 토큰 가격: Haiku 4.5 ($1/$5), Sonnet 4/4.5 ($3/$15), Opus 4 ($15/$75), Opus 4.5 ($5/$25).” 2026년 1월. 

  58. GitHub ykdojo/claude-code-tips. “커뮤니티 팁 모음: plan 모드, 자주 /clear, 스크린샷, PR용 GitHub 앱.” 2026년 1월. 

  59. Anthropic Usage Policy. 다중 계정 정책. Anthropic Support. “동일한 전화번호로 최대 3개의 계정을 인증할 수 있습니다. 동일 네트워크에서의 다중 유료 구독이 지원됩니다.” 2026년 1월. 

  60. GitHub Releases. “v2.1.10: –init, –init-only 또는 –maintenance CLI 플래그를 통해 트리거되는 Setup hook 이벤트 추가; 로그인 중 OAuth URL 복사를 위한 ‘c’ 키보드 단축키; 시작 키 입력 캡처 개선; 제거 가능한 첨부 파일로서의 파일 제안; VSCode 플러그인 설치 횟수 및 신뢰 경고.” 2026년 1월 17일. 

  61. @adocomplete. “Advent of Claude 15일차: 완전 자율 운영을 위한 –dangerously-skip-permissions 플래그 (YOLO 모드).” 2026년 1월. 

  62. @adocomplete. “Claude Max 구독자는 /passes 커맨드를 통해 다른 사람과 Claude Code Pro 체험판을 공유할 수 있는 3개의 게스트 패스를 받습니다.” 2026년 1월. 

  63. @mattpocockuk. “신뢰할 수 없는 코드베이스의 안전한 탐색을 위한 Docker 샌드박스 모드.” 2026년 1월. 

  64. Daisy Hollman. “야간 hooks 전략: 테스트가 통과할 때까지 Claude가 반복하도록 린팅 및 테스팅 hooks를 가드레일로 사용합니다.” 2026년 1월. 

  65. @moofeez. “Claude Squad: 격리된 워크트리에서 병렬 Claude Code 인스턴스를 위한 다중 에이전트 매니저.” 2026년 1월. 

  66. GitHub Releases. “v2.1.12: 메시지 렌더링 버그 수정.” 2026년 1월 17일. 

  67. GitHub Releases. “v2.1.14: bash 모드에서 히스토리 기반 자동 완성, 플러그인 검색, git SHA에 플러그인 고정, VSCode /usage 커맨드. 수정 사항: 컨텍스트 윈도우 차단 제한 (~65%→~98%), 병렬 서브에이전트의 메모리 크래시, 긴 세션의 메모리 누수, @ 심볼 파일 자동 완성, /feedback URL, /context 토큰 수, 슬래시 커맨드 자동 완성.” 2026년 1월 20일. 

  68. GitHub Releases. “v2.1.15: npm 설치 지원 중단 알림, React Compiler UI 성능 개선. 수정 사항: /compact 경고 지속성, MCP stdio 서버 타임아웃이 자식 프로세스를 종료하지 않는 문제 (UI 멈춤 수정).” 2026년 1월 21일. 

  69. GitHub Releases. “v2.1.16: 종속성 추적이 있는 작업 관리 시스템, VSCode 네이티브 플러그인 관리, OAuth 사용자가 원격 세션 탐색/재개 가능. 수정 사항: 서브에이전트 재개 시 OOM 크래시, /compact 경고 가시성, 세션 제목 언어, Windows IDE 레이스 컨디션.” 2026년 1월 22일. 

  70. GitHub Issues. “Ultrathink는 더 이상 사용되지 않습니다. Thinking 모드는 31,999 토큰으로 기본 활성화됩니다. ‘think’, ‘think hard’, ‘ultrathink’와 같은 키워드는 더 이상 thinking 토큰을 할당하지 않습니다—대신 MAX_THINKING_TOKENS 환경 변수를 사용하세요.” 2026년 1월. Decode Claude. “UltraThink는 죽었습니다. Extended Thinking 만세.” 

  71. GitHub Releases. “v2.1.19: 사용자 정의 커맨드 인수를 위한 $0/$1 단축 문법, CLAUDE_CODE_ENABLE_TASKS 환경 변수, 모든 사용자를 위한 VSCode 세션 포킹/되감기. v2.1.17: AVX 명령어를 지원하지 않는 프로세서에서의 크래시 수정.” 2026년 1월 23-24일. 

  72. Claude Code Docs. “v2.1.20: 추가 디렉토리에서 CLAUDE.md 로드를 위한 –add-dir 플래그, PR 리뷰 상태 표시기, TaskUpdate를 통한 작업 삭제, vim 화살표 키 히스토리 탐색, 모든 사용자를 위한 /copy 커맨드, 타임스탬프가 있는 설정 백업. 수정 사항: 세션 압축 문제, 사용자 메시지를 무시하는 에이전트, 넓은 문자 렌더링, Unicode가 있는 JSON 파싱.” 2026년 1월 27일. 

  73. Anthropic. “웹에서의 Claude Code는 이제 Pro 및 Max 사용자 외에도 프리미엄 시트가 있는 Team 및 Enterprise 사용자를 위해 연구 미리보기로 제공됩니다.” 2026년 1월 26일. 

  74. GitHub Releases. “v2.1.21: 일본어 IME 전각 숫자 입력, VSCode에서 Python venv 자동 활성화 (claudeCode.usePythonEnvironment), 읽기/검색 진행 표시기, Claude가 bash보다 파일 도구를 선호함. 수정 사항: 셸 완성 캐시, 세션 재개 API 오류, 자동 압축 타이밍, 작업 ID 재사용, Windows 파일 검색.” 2026년 1월 27일. 

  75. GitHub Releases. “v2.1.22: 비대화형 (-p) 모드의 구조화된 출력 수정.” 2026년 1월 27일. 

  76. GitHub Releases. “v2.1.23: spinnerVerbs 설정, mTLS/프록시 연결 수정, 사용자별 임시 디렉토리 격리, ripgrep 타임아웃 보고, 병합된 PR 보라색 표시기, bash 타임아웃 표시. 수정 사항: 프롬프트 캐싱 레이스 컨디션, 헤드리스에서 비동기 hooks, 탭 완성, Bedrock 리전 문자열.” 2026년 1월 28일. 

  77. Claude Code Docs. “v2.1.18: 컨텍스트별 키 바인딩, 코드 시퀀스, 개인화가 가능한 사용자 정의 키보드 단축키. 설정하려면 /keybindings를 실행하세요.” 2026년 1월 22일. 

  78. Help Net Security. “Anthropic은 Claude에 대화형 도구 지원 (MCP Apps)을 추가하여 사용자가 Claude 인터페이스 내에서 Asana, Box, Canva, Figma, Hex, monday.com, Slack과 직접 상호 작용할 수 있게 했습니다.” 2026년 1월 26일. 

  79. Anthropic Developer Platform. “Code Execution Tool v2 퍼블릭 베타: 코드 실행 내에서 Bash 커맨드 실행, 파일 조작, 프로그래밍 방식 도구 호출.” 2026년 1월. 

  80. GitHub Releases. “v2.1.25: Bedrock 및 Vertex의 게이트웨이 사용자에 대한 베타 헤더 유효성 검사 오류 수정. 해결 방법: CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.” 2026년 1월 29일. 

  81. GitHub Releases. “v2.1.27: PR 연결 세션을 위한 –from-pr 플래그, gh pr create를 통한 PR에 자동 연결 세션, 디버그 로그의 도구 호출 실패, VSCode Claude in Chrome 통합. 수정 사항: 컨텍스트 관리 유효성 검사, /context 색상 출력, 상태 표시줄 중복, 권한 우선순위, Windows bash/.bashrc, Windows 콘솔 깜빡임, VSCode OAuth 401 오류.” 2026년 1월 30일. 

NORMAL claude-code.md EOF