Ch1. 플랜 & 환경 설정

플랜 선택 가이드

Claude Code는 Pro/Max 개인 플랜과 Team Premium 좌석, Enterprise, Claude Console(API 빌링) 계정에서 쓸 수 있습니다. 무료 Claude.ai 플랜에는 Claude Code 접근이 빠져 있습니다. 가격과 포함 기능은 수시로 바뀌니 구매 전에 공식 페이지를 확인하세요.

설치 & 업데이트

시스템 요구사항

• OS: macOS 13.0+, Windows 10 1809+/Windows Server 2019+, Ubuntu 20.04+, Debian 10+, Alpine Linux 3.19+
• 하드웨어: 4GB 이상 RAM, x64 또는 ARM64 프로세서
• 네트워크: 인터넷 연결 필요
• 셸: Bash, Zsh, PowerShell, 또는 CMD
• ripgrep은 보통 Claude Code에 포함됩니다. 검색이 실패하면 별도 설치가 필요할 수 있습니다.

권장 설치 (네이티브 인스톨러)

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

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

대안 설치: Homebrew / WinGet / Linux 패키지 매니저

brew install --cask claude-code

winget install Anthropic.ClaudeCode

Homebrew는 cask를 두 개 제공합니다. claude-code는 stable 채널(보통 약 1주일 늦고 큰 회귀가 있는 릴리스는 건너뜀), claude-code@latest는 latest 채널(릴리스 즉시 받음)을 추적합니다.

Debian/Fedora/RHEL/Alpine에서는 서명된 apt/dnf/apk 리포지토리로도 설치합니다.

npm 설치 (지원되지만 비권장)

npm 글로벌 패키지로도 설치할 수 있는데, 이때도 standalone 인스톨러와 똑같은 네이티브 바이너리가 깔립니다. npm은 플랫폼별 optional dependency(예: @anthropic-ai/claude-code-darwin-arm64)로 바이너리를 가져온 뒤 postinstall 단계에서 링크합니다. 설치된 claude 바이너리 자체는 Node를 호출하지 않습니다.

npm 패키지는 Node.js 18 이상이 필요합니다. 신규 배포나 팀 표준 환경이라면 npm 글로벌 패키지보다 네이티브 인스톨러/Homebrew/WinGet 기준으로 맞추는 편이 낫습니다.

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

업그레이드할 때는 npm install -g @anthropic-ai/claude-code@latest를 씁니다. npm update -g는 최초 설치 시점의 semver 범위를 지키므로 최신 릴리스로 넘어가지 못할 수 있어 피하세요.

설치 검증

# 기본 확인
claude --version

# 설치/설정 상세 진단 (가장 최근 업데이트 시도 결과 포함)
claude doctor

업데이트

• 네이티브 설치는 기본적으로 백그라운드 자동 업데이트됩니다. 시작 시 및 실행 중 주기적으로 업데이트를 확인하고, 다운로드/설치는 백그라운드에서 진행되며 다음 실행 시 적용됩니다.
• Homebrew / WinGet / Linux 패키지 매니저 설치는 기본적으로 자동 업데이트되지 않으므로 brew upgrade claude-code, brew upgrade claude-code@latest, winget upgrade Anthropic.ClaudeCode를 주기적으로 실행해야 합니다.
• CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1로 설정하면 Homebrew/WinGet에서도 Claude Code가 새 버전이 있을 때 백그라운드로 업그레이드 명령을 실행하고 재시작을 안내합니다. (WinGet은 실행 중 잠금 때문에 실패하면 수동 명령을 안내)
• 채널 변경: /config → Auto-update channel 또는 autoUpdatesChannel 설정
• latest가 기본 채널이며, stable은 보통 약 1주일 늦고 큰 회귀가 있는 릴리스를 건너뜁니다.
• minimumVersion 설정으로 하한선을 정합니다. 자동 업데이트와 claude update는 이 값보다 낮은 버전을 설치하지 않으므로, 이미 더 최신인 latest 빌드에 있을 때 stable로 바꿔도 다운그레이드되지 않습니다.
• 수동 업데이트: claude update
• 특정 버전/채널 설치: claude install <version|stable|latest> (예: claude install stable)
• 자동 업데이트 백그라운드 확인만 비활성화: DISABLE_AUTOUPDATER=1 (이 경우에도 claude update/claude install은 동작). 수동 업데이트까지 포함해 모든 경로를 막으려면 DISABLE_UPDATES를 사용합니다.

API 빌링 인증

claude auth login --console 명령으로 Anthropic Console(API 빌링) 계정 인증을 합니다. --email로 이메일을 미리 채우거나 --sso로 SSO 인증을 강제합니다. (v2.1.79)

구독 계정은 claude 실행 후 브라우저 프롬프트로 로그인하고, 세션 안에서 /login//logout으로 전환합니다. CI나 스크립트처럼 브라우저 로그인이 안 되는 환경에서는 claude setup-token으로 1년짜리 OAuth 토큰을 발급해 CLAUDE_CODE_OAUTH_TOKEN으로 씁니다.

AWS Bedrock 로그인 마법사 (v2.1.92)

로그인 화면에서 **"3rd-party platform"**을 고르면 Bedrock 설정 마법사가 열립니다. AWS 인증 방식, 리전 선택, 자격증명 검증, 모델 pinning까지 순서대로 안내하므로, Bedrock을 처음 붙이는 팀이 초기 설정에서 저지르는 실수를 줄여줍니다.

모델 선택

• 세션 중 /model로 모델을 전환할 수 있습니다.
• 기본 모델은 settings.json의 model로 지정할 수 있습니다.
• Fable 5는 2026-06-09 공개된 Claude Code v2.1.170에서 추가된 최고 난도 코딩 모델입니다. Claude Code v2.1.170 이상과 조직 접근 권한이 필요하며, 기본 모델은 아닙니다. /model fable, model 설정, 또는 접근 권한이 있는 조직의 best alias로 선택합니다.
• Opus 4.8은 Fable을 쓸 수 없거나 비용이 맞지 않을 때 쓰는 최신 고성능 Opus 경로입니다. 복잡한 multi-step 작업, 아키텍처 판단, 장기 agentic task에 배정하고, Claude Code에서는 v2.1.154 이상이 필요합니다.
• Anthropic API alias: fable은 Fable 5, opus는 Opus 4.8, sonnet은 Sonnet 4.6으로 해석됩니다. best는 Fable 접근 권한이 있으면 Fable 5, 아니면 최신 Opus로 해석됩니다.
• Provider별 alias 차이: Claude Platform on AWS는 opus가 Opus 4.7, sonnet이 Sonnet 4.6입니다. Bedrock/Vertex/Foundry는 opus가 Opus 4.6, sonnet이 Sonnet 4.5이므로 최신 모델을 원하면 full model name 또는 ANTHROPIC_DEFAULT_*_MODEL pinning을 사용하세요.
• Alias는 움직입니다: fable, best, opus, sonnet, haiku는 provider별 권장 버전을 가리키고 시간이 지나면 바뀝니다. 재현성이 중요한 CI, 벤치마크, 고객 재현 세션은 full model name(예: claude-fable-5, claude-opus-4-8)으로 pinning하세요.
• default alias: 모델 오버라이드를 지우고 계정 유형에 맞는 권장 모델로 되돌리는 특수 값입니다. Fable 5는 어느 계정 유형에서도 기본값이 아닙니다. Max/Team Premium/Enterprise pay-as-you-go/Anthropic API는 Opus 4.8, Claude Platform on AWS는 Opus 4.7, Pro/Team Standard/Enterprise 구독 좌석은 Sonnet 4.6, Bedrock/Vertex/Foundry는 Sonnet 4.5로 해석됩니다.
• /model 저장 동작: v2.1.153부터 /model에서 Enter 또는 /model <name>을 쓰면 사용자 settings의 model 기본값으로 저장됩니다. 현재 세션에만 바꾸려면 picker에서 s를 사용합니다. (v2.1.144~v2.1.152에서는 /model이 현재 세션에만 적용되었고 picker의 d가 기본값을 저장했습니다.)
• --model 플래그와 ANTHROPIC_MODEL: 시작한 세션에만 적용됩니다. 여러 터미널에서 동시에 다른 모델을 쓰려면 각각 --model로 실행합니다.
• Resume 모델 보존: claude --resume, --continue, /resume으로 이어받은 세션은 transcript에 저장된 모델을 유지합니다. 그 모델이 retired된 경우에만 일반 precedence로 fallback됩니다.
• Fable 데이터/추론 특성: Fable 5는 기본 1M context, 최대 128k output token, $10/MTok input·$50/MTok output 단가를 갖습니다. Covered Model로 30일 데이터 보존이 적용되며 ZDR(Zero Data Retention)에서는 사용할 수 없습니다. adaptive thinking이 항상 켜져 있어 MAX_THINKING_TOKENS=0, 세션 thinking toggle, alwaysThinkingEnabled로 thinking을 끌 수 없고 effort로 깊이를 조절합니다.
• Fable 자동 fallback: Fable 5 요청이 사이버보안·생물학 등 안전 분류기에 걸리면 Claude Code가 기본 Opus 모델로 요청을 다시 실행하고 알림을 띄웁니다. 프롬프트가 평범한데도 이런 일이 생기면 CLAUDE.md, hook, plugin 같은 workspace customization을 확인하고 claude --safe-mode로 설정 요인을 가려냅니다. 단, git status와 디렉토리명은 safe mode에서도 포함됩니다.
• 모델 fallback chain: overload나 availability failure가 장기 세션을 끊지 않도록 fallbackModel 설정 또는 --fallback-model opus,sonnet을 사용합니다. 이 fallback은 안전 분류 fallback과 별개이며, 최대 3개 모델까지 둡니다.
• 1M 컨텍스트 alias: fable[1m], sonnet[1m], opus[1m]은 긴 세션용 1M context 경로입니다. full model name에도 [1m]을 붙일 수 있습니다(예: claude-fable-5[1m], claude-opus-4-8[1m]). Fable 5는 Anthropic API에서 1M context를 기본 지원하지만, 비용과 latency가 커지므로 긴 조사·문서화·대규모 리뷰에만 한정해 쓰세요. CLAUDE_CODE_DISABLE_1M_CONTEXT=1로 1M 변형을 picker에서 뺄 수 있습니다.
• opusplan: plan mode에서는 opus, 실행 단계에서는 sonnet으로 전환하는 특수 설정입니다. 설계 판단은 깊게 하고 구현 반복 비용은 낮추고 싶을 때 잘 맞습니다. (plan 단계 Opus는 표준 200K 컨텍스트로 동작하며, opus의 자동 1M 업그레이드는 opusplan에 적용되지 않습니다.)
• 모델 제한: Enterprise 관리자는 managed/policy settings의 availableModels로 사용자가 고를 수 있는 모델을 제한합니다.
• 최신 모델 제한/경고: v2.1.184 이후 Haiku는 메인 대화 모델로 제한되지만 서브에이전트 모델로는 계속 사용할 수 있습니다. 최신 릴리스는 deprecated/retired 모델을 선택하면 더 명확한 경고를 표시하므로, CI·문서 예시는 full model name을 정기적으로 재검증하세요.
• modelOverrides 설정으로 개별 Anthropic 모델 ID를 커스텀 provider 모델 ID에 매핑합니다. Bedrock 추론 프로필 ARN, Vertex version name, Foundry deployment name을 팀 표준으로 고정할 때 씁니다.
• ANTHROPIC_CUSTOM_MODEL_OPTION 환경변수로 /model 피커에 커스텀 모델 항목을 추가할 수 있습니다. (_NAME, _DESCRIPTION 옵션 동반) (v2.1.78)
• ANTHROPIC_DEFAULT_FABLE_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL로 alias별 기본 모델을 pinning할 수 있습니다.
• Fable만 prompt caching을 끄려면 DISABLE_PROMPT_CACHING_FABLE=1을 씁니다. 전체 비활성화(DISABLE_PROMPT_CACHING=1)보다 범위가 좁습니다.
• 이전 기준: Opus 4/4.1은 first-party API에서 제거되어 Opus 4.6으로 자동 마이그레이션되었고, Opus 4.6은 64k 기본 출력 토큰(상한 128k)과 1M context 기본화 흐름을 만들었습니다. 현재 문서에서는 이를 최신 모델 기준이 아니라 호환성 이력으로 취급합니다.

추론 강도(Effort) 조절

• /effort 명령으로 추론 강도를 조절할 수 있습니다: low (○), medium (◐), high (●), 그리고 그 이상으로 xhigh, max가 있습니다. (v2.1.72)
• 쓸 수 있는 레벨은 모델마다 다릅니다. Fable 5/Opus 4.8/Opus 4.7은 low/medium/high/xhigh/max, Opus 4.6/Sonnet 4.6은 low/medium/high/max를 지원합니다. 지원하지 않는 레벨을 지정하면 그 아래에서 가장 높은 지원 레벨로 fallback됩니다.
• Claude Code에서 기본 effort는 Fable 5/Opus 4.8/Opus 4.6/Sonnet 4.6에서 high, **Opus 4.7에서 xhigh**입니다. 가장 어려운 작업에는 /effort max(현재 세션 한정, 토큰 상한 없음)를 쓸 수 있습니다. (v2.1.170)
• /effort 메뉴에는 ultracode도 있습니다. 이건 모델 effort 레벨이 아니라 Claude Code 설정으로, xhigh를 보내면서 실제 작업에 맞춰 dynamic workflow를 오케스트레이션합니다(현재 세션 한정).
• "ultrathink" 키워드를 프롬프트에 포함하면 그 턴에 더 깊은 추론이 요청됩니다(세션 effort 설정은 변경하지 않으며, API로 보내는 effort 레벨도 그대로). "think", "think hard" 같은 다른 문구는 일반 프롬프트 텍스트로 처리됩니다. (v2.1.68)
• /effort 명령에서 "auto"가 현재 어떤 값으로 해석되는지 표시됩니다. (v2.1.80)
• /effort를 인수 없이 실행하면 인터랙티브 슬라이더가 열려 화살표 키로 레벨을 바꾸고 Enter로 확정합니다. /model picker에서도 좌우 화살표로 effort 슬라이더를 조절할 수 있습니다. (v2.1.111)
• 스킬과 서브에이전트의 frontmatter에 effort 필드를 지정해 effort 레벨을 오버라이드합니다. 환경변수 CLAUDE_CODE_EFFORT_LEVEL, settings의 effortLevel, --effort 플래그로도 설정합니다. (v2.1.80)

모델 선택 운영 원칙

# 현재 모델/버전 확인
/status
/model

# Fable 또는 Opus 경로로 시작
claude --model fable
claude --model opus

# availability failure 대비 fallback chain 지정
claude --fallback-model opus,sonnet

# 세션 중 Sonnet으로 전환하고 기본값으로 저장
/model sonnet

퍼미션 모드 이해

defaultMode 설정(또는 --permission-mode 플래그)으로 시작 모드를 지정합니다. 세션 중에는 Shift+Tab으로 모드를 순환할 수도 있습니다.

Auto 모드

Auto 모드는 백그라운드 안전성 검사가 각 도구 호출이 사용자 요청과 맞는지 확인해, 안전한 작업은 프롬프트 없이 진행하고 위험한 작업은 막습니다. default와 bypassPermissions의 중간이며, 현재 research preview 단계입니다.

• OS 수준 샌드박스와 결합된 다층 방어 구조
• 거부된 명령은 /permissions → Recent 탭에 기록되고, r로 재시도 가능 (v2.1.89)
• PermissionDenied 훅으로 거부 이벤트를 커스텀 처리 가능 (v2.1.88)
• --enable-auto-mode 플래그는 v2.1.111에서 제거되었습니다. 이제 auto 모드는 기본적으로 Shift+Tab 순환에 들어가며, 시작할 때 바로 들어가려면 --permission-mode auto를 씁니다.
• 최신 릴리스에서는 Auto mode classifier가 repository bulk transfer 같은 data exfiltration 탐지를 강화했습니다. 안전한 기본값을 지키려면 auto를 쓰더라도 network allowlist, deniedDomains, permission rules를 함께 관리하세요. (v2.1.154)

claude --permission-mode auto

자동 메모리 저장 디렉토리

autoMemoryDirectory 설정으로 자동 메모리가 저장되는 디렉토리를 바꿀 수 있습니다. 절대 경로 또는 ~/ 접두 경로를 받습니다. (v2.1.74)

세션 이름 지정

-n / --name CLI 플래그로 세션에 표시 이름을 붙일 수 있습니다. 이름은 /resume과 터미널 제목에 뜨고, claude --resume <name>으로 이어받습니다. 세션 중에 /rename으로 바꾸면 프롬프트 바에도 표시됩니다. (v2.1.76)

턴 소요 시간 표시

/config 메뉴의 "Show turn duration" 토글로 각 턴의 소요 시간을 띄울 수 있습니다. (v2.1.79)

Managed Settings (기업 관리)

macOS에서는 com.anthropic.claudecode managed preferences 도메인(plist, Jamf/Kandji 등으로 배포)이나 /Library/Application Support/ClaudeCode/managed-settings.json을, Windows에서는 Registry(HKLM\SOFTWARE\Policies\ClaudeCode)나 C:\Program Files\ClaudeCode\managed-settings.json을, Linux/WSL에서는 /etc/claude-code/managed-settings.json을 통해 Managed settings를 설정할 수 있습니다. managed settings는 사용자나 프로젝트 설정으로 덮어쓸 수 없어서, 조직 전체에 일관된 정책을 배포할 때 유용합니다. (v2.1.51)

managed-settings.d/ 드롭인 디렉토리 (v2.1.83)

managed-settings.d/ 디렉토리에 개별 JSON 파일을 드롭인해 managed settings를 조합할 수 있습니다. base managed-settings.json을 먼저 병합한 뒤 *.json 파일을 알파벳 순으로 병합하므로(숫자 접두사로 순서를 제어), MDM 도구로 부분 정책 파일을 배포하거나 여러 팀의 설정을 합칠 때 유용합니다.

forceRemoteSettingsRefresh fail-closed 정책 (v2.1.92)

원격 managed settings를 쓰는 조직은 forceRemoteSettingsRefresh 정책으로 최신 정책을 다시 받아오기 전에는 CLI가 시작되지 않도록 강제합니다. fetch에 실패하면 그대로 종료되니, 캐시된 옛 정책으로 실행되면 안 되는 환경에 적합합니다.

샌드박스 설정

sandbox.failIfUnavailable (v2.1.83)

샌드박스를 쓸 수 없는 환경에서 Claude Code가 실행을 거부하도록 강제할 수 있습니다. 보안 정책이 엄격한 조직에서 샌드박스 없는 실행을 막습니다.

{
  "sandbox": {
    "failIfUnavailable": true
  }
}

sandbox.network.deniedDomains (v2.1.113)

넓은 allowedDomains allowlist를 쓰더라도, 특정 목적지 도메인만 예외로 차단할 수 있습니다. deniedDomains는 같은 wildcard 문법을 쓰며, allowedDomains보다 먼저 적용됩니다.

{
  "sandbox": {
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "deniedDomains": ["uploads.github.com"]
    }
  }
}

• 배포나 CI 환경에서 넓은 네트워크 허용이 필요하지만 업로드·외부 전송 엔드포인트만 막고 싶을 때 유용합니다.
• 공식 설정 문서 기준으로, managed settings의 sandbox.network.allowManagedDomainsOnly를 true로 두면 allowedDomains allow 규칙은 managed settings의 것만 적용되지만 deniedDomains는 그와 상관없이 모든 settings source에서 병합됩니다.

sandbox.credentials

v2.1.181~v2.1.190 릴리스에서는 샌드박스에서 자격증명 전달을 제어하는 sandbox.credentials 설정과, 샌드박스 내부 destructive command의 자동 승인 동작이 보강되었습니다. 보안 기준이 높은 조직은 sandbox.failIfUnavailable와 함께 이 값을 managed settings로 고정하고, 로컬 예외를 허용하지 않는 방향으로 운영하세요.

Windows PowerShell 도구를 쓰는 팀은 v2.1.181~v2.1.190의 PowerShell sandbox 보강을 전제로 문서를 갱신했습니다. 네이티브 Windows runner에서 샌드박스 정책을 검증할 때는 Bash와 PowerShell 양쪽 명령 경로를 각각 테스트하세요.

서브프로세스 환경 정리 (v2.1.83)

CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 환경변수를 설정하면 서브프로세스에서 자격증명 관련 환경변수를 제거합니다. CI/CD에서 API 키가 하위 프로세스로 새는 것을 막습니다.

상태 표시줄 커스터마이징

/statusline 명령으로 커스텀 상태 표시줄을 설정합니다. 설정 파일에 statusLine을 직접 넣는 방식도 지원합니다(예: {"type": "command", "command": "~/.claude/statusline.sh"}).

• statusline 스크립트에서 rate_limits 필드로 5시간/7일 윈도우의 rate limit 사용량(used_percentage, resets_at)을 표시합니다. (v2.1.80)

Thinking Summaries 기본 비활성화 (v2.1.88)

모델의 thinking(추론 과정) 요약이 기본적으로 생성되지 않습니다. 예전에는 각 턴마다 thinking summary가 떴지만, 이제는 showThinkingSummaries: true 설정으로 되살려야 합니다.

렌더링 최적화 (v2.1.88)

CLAUDE_CODE_NO_FLICKER=1 환경변수를 설정하면 alt-screen 렌더링에 가상 스크롤백을 써서 화면 깜빡임이 사라집니다. 스크롤이 많은 작업에서 화면이 더 안정적입니다.

유휴 복귀 프롬프트 (v2.1.84)

세션이 75분 이상 유휴 상태면 /clear를 제안하는 프롬프트가 뜹니다. 오래 방치된 세션의 컨텍스트를 정리하도록 유도하는 것입니다.

참고 문서

• Claude 요금제(개인/팀): https://claude.com/ko-kr/pricing (한국어)

• 설치/업데이트: https://code.claude.com/docs/ko/setup (한국어)

• 빠른 시작: https://code.claude.com/docs/ko/quickstart (한국어)

• 인증/로그인: https://code.claude.com/docs/en/authentication (영어)

• 모델 설정: https://code.claude.com/docs/en/model-config (영어)

• 설정 파일과 /config: https://code.claude.com/docs/ko/settings (한국어)

• /statusline 설정: https://code.claude.com/docs/en/statusline (영어)

• /model 명령: https://code.claude.com/docs/ko/slash-commands (한국어)

• Max 플랜(Claude Code 포함): https://support.claude.com/en/articles/11049741-what-is-the-max-plan (영어)

• 퍼미션 모드: https://code.claude.com/docs/en/permission-modes (영어)