Claude Code CLI: 완벽한 기술 레퍼런스
2025년 12월 12일 업데이트
2025년 12월 업데이트: Claude Code는 이제 에이전틱 다중 파일 편집, 300개 이상의 외부 서비스와 MCP 프로토콜 통합, 복잡한 작업을 위한 특화된 서브에이전트, CI/CD 자동화를 위한 훅 시스템을 통해 엔터프라이즈 엔지니어링 워크플로우를 지원합니다. 권한 시스템으로 세밀한 보안 제어가 가능합니다. Haiku(빠르고 저렴함)와 Opus(강력함) 간의 모델 전환으로 비용-성능 균형을 최적화할 수 있습니다.
저는 프로덕션 코드베이스, CI/CD 파이프라인, 엔터프라이즈 배포 환경에서 Claude Code의 한계를 시험하며 수개월을 보냈습니다. 이 가이드는 제가 처음 시작할 때 있었으면 하고 바랐던 종합 레퍼런스로, 그 경험을 담았습니다. 첫 설치부터 대부분의 사용자가 발견하지 못하는 고급 패턴까지 모든 것을 다룹니다.
Claude Code는 프로그래밍에 대해 알고 있는 채팅 인터페이스가 아닙니다. 코드베이스를 읽고, 명령을 실행하고, 파일을 수정하고, git 워크플로우를 관리하고, 외부 서비스에 연결하고, 복잡한 작업을 특화된 서브에이전트에게 위임하는 에이전틱 시스템입니다—이 모든 것이 개발자가 실제로 일하는 방식에 통합되는 커맨드라인 인터페이스를 통해 이루어집니다.
Claude Code를 일반적으로 사용하는 것과 효과적으로 사용하는 것의 차이는 아키텍처를 이해하는 데 있습니다: 동작을 제어하는 구성 계층, 작업을 게이팅하는 권한 시스템, 결정론적 자동화를 가능하게 하는 훅 시스템, 기능을 확장하는 MCP 프로토콜, 복잡한 다단계 작업을 처리하는 서브에이전트 시스템. 이 시스템들을 마스터하면 Claude Code는 힘의 배수가 됩니다. 놓치면 대부분의 가치를 테이블 위에 남겨두는 것입니다.
이 가이드는 커맨드라인 도구에 익숙하고 전체 그림을 원하는 분을 대상으로 합니다. 모든 기능이 실제 구문, 실제 구성 예시, 경험 많은 사용자도 걸려 넘어지는 엣지 케이스와 함께 문서화되어 있습니다. 첫 프로젝트를 설정하든 엔터프라이즈 엔지니어링 조직 전체에 배포하든, 필요한 정보가 여기 있습니다.
Claude Code 작동 방식: 멘탈 모델
기능을 살펴보기 전에, Claude Code의 아키텍처가 모든 작업에 어떻게 영향을 미치는지 이해하세요. 시스템은 세 계층으로 작동합니다:
┌─────────────────────────────────────────────────────────┐
│ CLAUDE CODE 계층 │
├─────────────────────────────────────────────────────────┤
│ 확장 계층 │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ MCP │ │ 훅 │ │ 스킬 │ │ 플러그인 │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
│ 외부 도구, 결정론적 자동화, 도메인 │
│ 전문성, 패키지화된 확장 │
├─────────────────────────────────────────────────────────┤
│ 위임 계층 │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 서브에이전트 (최대 10개 병렬) │ │
│ │ Explore | Plan | General-purpose | Custom │ │
│ └─────────────────────────────────────────────────┘ │
│ 집중된 작업을 위한 격리된 컨텍스트, 요약을 반환 │
├─────────────────────────────────────────────────────────┤
│ 코어 계층 │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 메인 대화 컨텍스트 │ │
│ │ 도구: Read, Edit, Bash, Glob, Grep 등 │ │
│ └─────────────────────────────────────────────────┘ │
│ 주요 상호작용; 제한된 컨텍스트; 비용 발생 │
└─────────────────────────────────────────────────────────┘
코어 계층: 메인 대화입니다. 모든 메시지, 파일 읽기, 도구 출력이 공유된 200K 토큰 윈도우(프리미엄의 경우 1M)에서 컨텍스트를 소비합니다. 컨텍스트가 가득 차면 Claude는 이전 결정을 추적하지 못하고 품질이 저하됩니다. 이 계층은 토큰당 비용이 발생합니다.
위임 계층: 서브에이전트는 깨끗한 컨텍스트로 생성되어 집중된 작업을 수행하고 요약을 반환합니다. 탐색 결과가 메인 대화를 부풀리지 않습니다—결론만 반환됩니다. 탐색에는 Haiku 서브에이전트(저렴하고 빠름)를, 구현에는 Sonnet을 사용하세요.
확장 계층: MCP는 외부 서비스(데이터베이스, GitHub, Sentry)를 연결합니다. 훅은 모델 동작과 관계없이 셸 명령의 실행을 보장합니다. 스킬은 Claude가 자동으로 적용하는 도메인 전문성을 인코딩합니다. 플러그인은 이 모든 것을 배포용으로 패키징합니다.
핵심 통찰: 대부분의 사용자는 코어 계층에서만 작업하며 컨텍스트가 부풀어 오르고 비용이 상승하는 것을 지켜봅니다. 파워 유저는 탐색과 특화된 작업을 위임 계층으로 밀어내고, 확장 계층을 워크플로우에 맞게 구성하며, 코어 계층은 오케스트레이션과 최종 결정에만 사용합니다.
목차
- 설치 및 인증
- 핵심 상호작용 모드
- 구성 시스템 심층 분석
- 모델 선택 및 전환
- 권한 시스템 및 보안
- 훅 시스템
- MCP (Model Context Protocol)
- 서브에이전트 및 작업 위임
- 확장 사고 모드
- 출력 스타일
- 슬래시 명령
- 스킬
- 플러그인 시스템
- 메모리 및 컨텍스트 관리
- 이미지 및 멀티모달 입력
- Git 통합 및 워크플로우
- IDE 통합
- 고급 사용 패턴
- Claude Code Remote
- 백그라운드 에이전트
- 비용 관리 및 청구
- 성능 최적화
- 문제 해결 및 디버깅
- 엔터프라이즈 배포
- 키보드 단축키 레퍼런스
- 모범 사례
설치 및 인증
시스템 요구사항
Claude Code는 macOS 10.15+, Ubuntu 20.04+/Debian 10+, Windows 10+(WSL 또는 Git Bash 사용)에서 실행됩니다. 시스템은 최소 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 및 Linux
curl -fsSL https://claude.ai/install.sh | bash
# Homebrew 대안
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
특정 버전 설치:
# 특정 버전 설치
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58
# 최신 버전 명시적 설치
curl -fsSL https://claude.ai/install.sh | bash -s latest
# Windows PowerShell - 특정 버전
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58
NPM 설치
npm이 선호되는 환경의 경우:
npm install -g @anthropic-ai/claude-code
npm 설치 시 절대 sudo를 사용하지 마세요—이후 모든 것을 복잡하게 만드는 권한 문제가 발생합니다.
기존 설치에서 마이그레이션
이전 npm 기반 설치가 있다면 네이티브 바이너리로 마이그레이션하세요:
claude install
인증 옵션
Claude Code는 세 가지 인증 경로를 지원하며, 각각 다른 트레이드오프가 있습니다:
Claude Console (API 청구)
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
# 선택사항: API 키 인증 (그렇지 않으면 Entra ID 사용)
export ANTHROPIC_FOUNDRY_API_KEY=your-key
프록시 뒤 또는 LLM 게이트웨이를 통한 엔터프라이즈 배포의 경우:
# 기업 프록시
export HTTPS_PROXY='https://proxy.example.com:8080'
# LLM 게이트웨이 (네이티브 인증 건너뛰기)
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 루프에 진입합니다:
cd your-project
claude
REPL은 턴 간에 대화 컨텍스트를 유지합니다. 쿼리를 직접 입력하고, 응답을 받고, /exit 또는 Ctrl+D로 종료할 때까지 계속합니다.
세션에 집중하기 위해 초기 프롬프트로 시작:
claude "이 프로젝트의 인증 흐름을 설명해줘"
전문가 팁: REPL은 압축 이벤트 간에도 상태를 유지합니다. 컨텍스트가 너무 커지면 Claude는 핵심 결정과 코드 스니펫을 보존하면서 이전 대화를 자동으로 요약합니다. /compact로 수동으로 트리거하거나 보존할 내용에 대한 사용자 지정 지침을 추가할 수 있습니다.
비대화형 모드
프린트 모드(-p)는 단일 쿼리를 실행하고 종료합니다:
# 직접 쿼리
claude -p "이 프로젝트의 모든 TODO 주석을 나열해줘"
# 파이프된 입력 처리
cat error.log | claude -p "이 실패의 근본 원인을 식별해줘"
# 다른 도구와 체이닝
claude -p "README 생성해줘" > README.md
스크립트에서 파싱하기 적합한 구조화된 출력:
claude -p "파일 유형별 줄 수를 세어줘" --output-format json
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": "응답 텍스트...", "session_id": "abc-123-d
[번역을 위해 내용 생략]
