터미널에서 자연어로 코드를 다루는 Claude Code는 단순한 자동완성 도구가 아니라, 코드베이스 전체를 이해하고 작업을 대신 수행하는 에이전트형(agentic) 코딩 도구입니다. 이 글에서는 설치 방법부터 실행 옵션, 권한 모드까지 공식 문서를 근거로 정확하게 정리했습니다.
본문에 등장하는 모든 옵션과 명령어는 Claude Code 공식 문서 기준이며, 이 글의 작성 시점은 2026년 4월입니다.
1. Claude Code란?
Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 도구입니다. 자연어로 명령하면 파일을 읽고, 수정하고, 테스트를 돌리고, Git 작업까지 처리합니다.
용어 참고
- 에이전트형(agentic) 도구: 사람이 한 줄씩 시키지 않아도 목표를 받고 스스로 단계를 나누어 실행하는 도구를 말합니다. Claude Code는 "버그를 고쳐줘"라고만 말해도 관련 파일을 찾고, 수정안을 만들고, 사용자에게 승인을 요청하는 식으로 동작합니다.
- REPL: Read-Eval-Print Loop의 줄임말로, 명령을 입력하면 즉시 평가해 결과를 보여주는 대화형 인터페이스입니다.
claude명령으로 실행되는 화면이 바로 REPL입니다.
2. 시스템 요구사항
공식 문서(Advanced setup)에 따른 요구사항입니다.
- 운영체제
- macOS 13.0 이상
- Windows 10 1809 이상 또는 Windows Server 2019 이상
- Ubuntu 20.04 이상
- Debian 10 이상
- Alpine Linux 3.19 이상
- 하드웨어: RAM 4GB 이상, x64 또는 ARM64 프로세서
- 네트워크: 인터넷 연결 필수
- 셸: Bash, Zsh, PowerShell, CMD
- 위치: Anthropic 지원 국가에서만 사용 가능
- 계정: Claude Pro, Max, Team, Enterprise 구독 또는 Anthropic Console 계정
참고: Windows에서 네이티브로 실행할 경우 Git for Windows가 필요하며, WSL을 쓰면 별도로 필요하지 않습니다.
3. 설치 방법
Claude Code 설치는 크게 다섯 가지 방법이 있습니다 (네이티브, Homebrew, WinGet, npm, Linux 패키지 매니저). 네이티브 설치(native installer)가 공식 권장 방법이며, Node.js 등 외부 의존성이 없습니다.
3-1. 네이티브 설치 (권장)
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
네이티브 설치는 백그라운드에서 자동으로 최신 버전으로 업데이트됩니다.
3-2. Homebrew (macOS)
brew install --cask claude-code
Homebrew는 두 가지 cask를 제공합니다.
claude-code: 안정(stable) 채널을 따라가며, 일반적으로 약 1주일 정도 늦지만 큰 회귀(regression)가 있는 릴리스는 건너뜁니다.claude-code@latest: 최신(latest) 채널을 따라가며 새 버전이 나오는 즉시 받아옵니다.
Homebrew는 자동 업데이트가 되지 않으므로, 직접 brew upgrade claude-code(또는 brew upgrade claude-code@latest)를 실행해야 합니다.
3-3. WinGet (Windows)
winget install Anthropic.ClaudeCode
WinGet도 자동 업데이트가 되지 않으므로 주기적으로 winget upgrade Anthropic.ClaudeCode를 실행해야 합니다.
3-4. npm (레거시)
Node.js 18 이상 환경이 있다면 npm으로도 설치할 수 있습니다.
npm install -g @anthropic-ai/claude-code
주의:
sudo npm install -g는 권한 문제와 보안 위험을 일으킬 수 있어 공식적으로 비권장됩니다. 권한 오류가 발생하면 트러블슈팅 문서를 참고하세요.
npm 패키지는 네이티브 설치와 동일한 바이너리를 가져오며, 설치된 claude 바이너리 자체는 Node를 호출하지 않습니다. 지원되는 npm 플랫폼은 darwin-arm64, darwin-x64, linux-x64, linux-arm64, linux-x64-musl, linux-arm64-musl, win32-x64, win32-arm64입니다.
3-5. Linux 패키지 매니저 (apt / dnf / apk)
Debian/Ubuntu, Fedora/RHEL, Alpine에서는 서명된 저장소를 통해 설치할 수 있습니다. 자세한 명령어와 GPG 키 검증 방법은 공식 Advanced setup 문서를 참고하세요.
3-6. 설치 확인
claude --version
좀 더 상세한 진단을 원한다면 claude doctor를 실행하세요. 인증 상태, MCP 서버 상태, 파일 권한 등을 점검해줍니다.
4. 로그인과 인증
설치 후 처음 claude 명령을 실행하면 로그인 프로세스가 시작됩니다.
claude
# 첫 실행 시 로그인 안내가 나타남
세션 안에서는 /login 슬래시 명령으로 로그인할 수 있습니다.
지원되는 계정 종류는 다음과 같습니다.
- Claude Pro, Max, Team, Enterprise 구독 (권장)
- Anthropic Console 계정 (선결제 크레딧 기반 API 사용)
- Amazon Bedrock, Google Vertex AI, Microsoft Foundry 등 엔터프라이즈 클라우드 제공자
참고: 무료 Claude.ai 계정으로는 Claude Code를 사용할 수 없습니다.
CI/CD 등 스크립트 환경에서 쓸 장기 OAuth 토큰이 필요하다면 다음 명령으로 발급받을 수 있습니다.
claude setup-token
5. 기본 실행 명령어
5-1. 대화형 세션 시작
cd /path/to/your/project
claude
프로젝트 디렉터리에서 실행하면 환영 화면과 함께 세션이 시작됩니다. /help로 명령어 목록을, /resume으로 이전 대화를 이어갈 수 있습니다.
5-2. 초기 프롬프트와 함께 시작
claude "이 프로젝트가 무엇을 하는지 설명해줘"
5-3. 일회성 쿼리(print 모드)
대화형 세션을 띄우지 않고 한 번만 답변을 받고 종료하려면 -p 또는 --print 옵션을 씁니다.
claude -p "이 함수를 설명해줘"
5-4. 파이프 입력
표준 입력으로 들어온 내용을 그대로 분석시킬 수 있습니다.
cat logs.txt | claude -p "이 로그에서 에러를 찾아줘"
5-5. 이전 대화 이어가기
claude -c: 현재 디렉터리에서 가장 최근 대화를 이어갑니다.claude -r "<세션이름 또는 ID>" "추가 질문": 특정 세션을 재개합니다.claude -r: 인터랙티브 picker로 세션을 고를 수 있습니다.
5-6. 업데이트와 설치 관리
claude update # 즉시 최신 버전으로 업데이트
claude install stable # stable 채널 바이너리 설치
claude install 2.1.118 # 특정 버전 설치
5-7. 인증 관련
claude auth login # 로그인
claude auth logout # 로그아웃
claude auth status # 인증 상태(JSON)
claude auth status --text # 사람이 읽기 쉬운 형식
claude auth status는 로그인되어 있으면 종료 코드 0, 아니면 1을 반환하므로 스크립트에서 활용하기 좋습니다.
5-8. 기타 자주 쓰는 명령
| 명령 | 설명 |
|---|---|
claude agents |
설정된 서브에이전트(subagent) 목록 보기 |
claude mcp |
MCP 서버 설정 |
claude plugin |
플러그인 관리 |
claude remote-control |
Remote Control 서버 시작 |
claude setup-token |
장기 OAuth 토큰 발급 (CI 용) |
6. 핵심 실행 옵션(플래그) 정리
여기서부터는 claude 실행 시 함께 쓰는 옵션입니다. 공식 문서의 CLI reference를 기준으로 자주 쓰이는 것 위주로 정리했습니다.
참고:
claude --help가 모든 플래그를 보여주지는 않습니다.--help에 없다고 해서 그 옵션이 없는 것은 아니므로, 정확한 목록은 항상 공식 CLI reference를 확인하는 것이 좋습니다.
6-1. 모델·세션 관련
| 옵션 | 설명 | 예시 |
|---|---|---|
--model |
사용할 모델 지정 (sonnet, opus 같은 alias 또는 정식 이름) |
claude --model claude-sonnet-4-6 |
--effort |
추론 노력 수준 (low, medium, high, xhigh, max). 모델에 따라 가능한 값이 다릅니다 |
claude --effort high |
--fallback-model |
기본 모델이 과부하일 때 대체할 모델 (print 모드 전용) | claude -p --fallback-model sonnet "..." |
--name, -n |
세션 표시 이름 지정 (/resume에서 보임) |
claude -n "auth-refactor" |
--session-id |
특정 세션 ID(UUID) 사용 | claude --session-id "550e8400-..." |
--continue, -c |
현재 디렉터리의 최근 대화 이어가기 | claude --continue |
--resume, -r |
특정 세션 재개 | claude --resume auth-refactor |
--fork-session |
재개 시 새 세션 ID로 분기 | claude --resume abc --fork-session |
6-2. 작업 디렉터리·파일
| 옵션 | 설명 |
|---|---|
--add-dir |
Claude가 읽고 수정할 수 있는 추가 디렉터리 지정 |
--worktree, -w |
격리된 git worktree 안에서 시작 |
--tmux |
worktree 세션을 tmux로 실행 (--worktree 필요) |
6-3. 시스템 프롬프트 커스터마이징
Claude Code는 기본 시스템 프롬프트를 갖고 있고, 이를 추가(append) 또는 대체(replace) 할 수 있습니다.
| 옵션 | 동작 |
|---|---|
--system-prompt |
기본 시스템 프롬프트를 통째로 대체 |
--system-prompt-file |
파일 내용으로 시스템 프롬프트 대체 |
--append-system-prompt |
기본 프롬프트 뒤에 텍스트 추가 |
--append-system-prompt-file |
기본 프롬프트 뒤에 파일 내용 추가 |
--system-prompt와 --system-prompt-file은 함께 쓸 수 없습니다. 대부분의 경우 append 계열을 쓰는 것이 안전합니다. Claude Code의 기본 능력을 유지하면서 추가 규칙만 얹을 수 있기 때문입니다.
claude --append-system-prompt "항상 TypeScript를 사용해."
6-4. 도구 제어
| 옵션 | 설명 |
|---|---|
--tools |
Claude가 쓸 수 있는 빌트인 도구 제한 (""은 전부 비활성, "default"은 전부 허용) |
--allowedTools |
권한 묻지 않고 바로 실행할 도구 지정 |
--disallowedTools |
모델 컨텍스트에서 제거할 도구 지정 |
--disable-slash-commands |
모든 슬래시 명령과 skill 비활성화 |
# Bash, Edit, Read만 허용
claude --tools "Bash,Edit,Read"
# git log, git diff는 권한 안 묻고 실행
claude --allowedTools "Bash(git log *)" "Bash(git diff *)" "Read"
6-5. 권한 모드 (실행 시 옵션)
권한 모드는 --permission-mode 플래그로 시작 시점에 지정할 수 있습니다. (자세한 내용은 7장 참고)
claude --permission-mode plan
claude --permission-mode acceptEdits
claude --permission-mode auto
claude --permission-mode dontAsk
claude --permission-mode bypassPermissions
# bypassPermissions와 동일한 단축 플래그
claude --dangerously-skip-permissions
# bypassPermissions를 cycle에는 추가하지만 시작 모드는 다른 것으로 지정
claude --permission-mode plan --allow-dangerously-skip-permissions
6-6. Print 모드 전용 옵션
-p(print) 모드와 함께 쓰는 옵션들입니다. 자동화·CI 환경에서 주로 사용됩니다.
| 옵션 | 설명 |
|---|---|
--output-format |
출력 형식 (text, json, stream-json) |
--input-format |
입력 형식 (text, stream-json) |
--max-turns |
에이전트 턴 수 제한 |
--max-budget-usd |
최대 비용(USD) 제한 |
--no-session-persistence |
세션을 디스크에 저장하지 않음 |
--json-schema |
결과를 지정한 JSON Schema에 맞춰 검증된 JSON으로 반환 |
--include-partial-messages |
스트리밍 중 부분 메시지도 포함 |
claude -p "테스트 실행하고 실패한 것만 리포트해줘" \
--output-format json \
--max-turns 5 \
--max-budget-usd 1.00
6-7. 빠른 실행을 위한 --bare
스크립트에서 빠르게 호출하기 위한 최소 모드입니다. hooks, skills, plugins, MCP 서버, 자동 메모리, CLAUDE.md 등의 자동 탐색을 모두 건너뜁니다. 이 모드에서도 Bash, 파일 읽기/쓰기 도구는 사용 가능합니다.
claude --bare -p "이 함수의 시간 복잡도는?"
6-8. 디버깅·통합 관련
| 옵션 | 설명 |
|---|---|
--debug |
디버그 모드 활성화. 카테고리 필터링 가능 (예: "api,mcp") |
--debug-file <path> |
디버그 로그를 특정 파일에 기록 |
--verbose |
상세 로깅 |
--ide |
시작 시 IDE에 자동 연결 (단일 IDE만 감지될 때) |
--chrome / --no-chrome |
Chrome 통합 켜기/끄기 |
--mcp-config |
JSON 파일/문자열에서 MCP 서버 로드 |
--strict-mcp-config |
--mcp-config로 지정한 MCP만 사용 |
--settings |
settings JSON 파일/문자열 로드 |
--setting-sources |
로드할 설정 소스 (user, project, local) |
7. 권한 모드(permission mode) 자세히 보기
Claude Code는 사용자가 매번 승인할지, 아니면 자율적으로 실행할지 선택할 수 있도록 권한 모드를 제공합니다. 공식 문서 Choose a permission mode 기준입니다.
세션 중에는 Shift+Tab 으로 모드를 순환할 수 있습니다 (default → acceptEdits → plan → auto). 단, auto는 Team/Enterprise/API 플랜과 Claude Sonnet 4.6 또는 Opus 4.6 모델이 필요하므로, 플랜이나 모델이 맞지 않으면 cycle에 나타나지 않을 수 있습니다. bypassPermissions는 --permission-mode bypassPermissions, --dangerously-skip-permissions, 또는 --allow-dangerously-skip-permissions 플래그로 시작했을 때만 cycle에 포함됩니다.
참고: CLI reference에 따르면 과거 사용되던
--enable-auto-mode플래그는 v2.1.111에서 제거되었으며, 이제는 시작부터 auto 모드를 쓰려면--permission-mode auto를 사용합니다.
| 모드 | 묻지 않고 가능한 동작 | 적합한 상황 |
|---|---|---|
default |
파일 읽기 | 처음 시작, 민감한 작업 |
acceptEdits |
파일 읽기 + 수정 | 코드 수정 반복 작업 |
plan |
파일 읽기 (수정 불가) | 코드베이스 탐색, 리팩터링 계획 |
auto |
모든 동작(분류기로 백그라운드 검사) | 장시간 작업, 프롬프트 피로 감소 |
dontAsk |
사전 허용된 도구만 | CI 등 잠긴 환경 |
bypassPermissions |
모든 동작 (검사 없음) | 격리된 컨테이너/VM에서만 |
7-1. plan 모드
Claude가 파일을 읽고 셸 명령으로 탐색하지만 소스 코드는 수정하지 않습니다. 대신 계획 파일을 작성하고 사용자의 승인을 기다립니다. 한 번의 요청에만 적용하려면 프롬프트 앞에 /plan을 붙이면 됩니다.
7-2. auto 모드 (연구 프리뷰)
별도의 분류기 모델이 각 동작을 검토해 작업 범위를 벗어나는 escalation, 의심스러운 인프라 접근, 프롬프트 인젝션 의심 동작을 차단합니다. 공식 문서는 이 모드를 research preview로 분류하며, 프롬프트 부담을 줄여주지만 안전을 보장하지는 않는다고 명시합니다.
- 이용 가능 플랜: Team, Enterprise, API 플랜에서만 사용 가능
- 모델 제한: Claude Sonnet 4.6 또는 Claude Opus 4.6 필요. Haiku, claude-3 모델, 서드파티 제공자(Bedrock, Vertex, Foundry)에서는 동작하지 않음
- 비용: 분류기 호출도 토큰 사용량에 포함됨
기본 차단 항목 예시:
curl | bash같이 외부 코드 다운로드 후 실행- 외부 엔드포인트로 민감 데이터 전송
- 프로덕션 배포 및 마이그레이션
- 클라우드 스토리지 대량 삭제
- IAM/저장소 권한 부여
main브랜치 직접 푸시, force push 같은 파괴적 소스 제어 동작
기본 허용 항목 예시:
- 작업 디렉터리 내 로컬 파일 작업
- 락 파일/매니페스트에 이미 선언된 의존성 설치
.env읽고 일치하는 API에만 자격증명 전송- 읽기 전용 HTTP 요청
7-3. dontAsk 모드
명시적으로 허용된 도구가 아니면 모두 자동 거부합니다. 완전 비대화형이라 CI 파이프라인에 적합합니다.
claude --permission-mode dontAsk
7-4. bypassPermissions 모드
모든 권한 검사를 건너뜁니다. 다만 .git, .vscode, .idea 디렉터리 쓰기는 여전히 확인을 거치고, .claude 디렉터리도 .claude/commands, .claude/agents, .claude/skills를 제외하면 확인을 거칩니다.
claude --permission-mode bypassPermissions
# 또는 동일한 의미의 단축 플래그
claude --dangerously-skip-permissions
⚠️ 주의: 이 모드는 프롬프트 인젝션이나 의도치 않은 동작에 대한 보호가 전혀 없습니다. 격리된 컨테이너, VM, 인터넷이 차단된 devcontainer에서만 사용해야 합니다. 더 안전한 자동화가 필요하면
auto모드를 검토하세요.
8. 자동 업데이트 제어
네이티브 설치본은 백그라운드에서 자동 업데이트되지만, 채널과 동작을 세밀하게 제어할 수 있습니다. 설정 파일은 settings.json이며, 자세한 키 목록은 Settings 문서를 참고하세요.
8-1. 릴리스 채널 변경
{
"autoUpdatesChannel": "stable"
}
"latest"(기본값): 새 기능 즉시 반영"stable": 약 1주일 늦지만 큰 회귀가 있는 릴리스는 건너뜀
세션 안에서 /config → Auto-update channel 메뉴로도 바꿀 수 있습니다.
8-2. 최소 버전 고정
{
"autoUpdatesChannel": "stable",
"minimumVersion": "2.1.100"
}
minimumVersion 아래로는 자동 업데이트나 claude update로도 다운그레이드되지 않습니다.
8-3. 자동 업데이트 비활성화
{
"env": {
"DISABLE_AUTOUPDATER": "1"
}
}
DISABLE_AUTOUPDATER는 백그라운드 체크만 끕니다. claude update나 claude install 같은 수동 명령까지 막으려면 DISABLE_UPDATES를 설정해야 합니다. 자세한 환경변수 목록은 Environment variables 문서를 참고하세요.
9. 실전 시나리오별 추천 실행 명령
공식 문서의 옵션을 조합해 실제 상황에 어떻게 쓰면 좋은지 예시를 정리했습니다. 상황 설명은 공식 문서에 명시된 옵션 의미를 기반으로 한 활용 예시입니다.
9-1. 처음 프로젝트 탐색
cd my-project
claude --permission-mode plan
plan 모드로 시작하면 코드베이스만 읽고 수정하지 않으므로, 안전하게 구조를 파악할 수 있습니다.
9-2. 코드 리팩터링
claude -n "auth-refactor" --permission-mode acceptEdits
세션 이름을 붙여두면 나중에 claude --resume auth-refactor로 곧장 이어갈 수 있고, acceptEdits 모드로 파일 수정은 자동 승인하되 셸 명령은 매번 확인할 수 있습니다.
9-3. CI에서 자동 검토
claude -p "이 PR의 코드 변경사항을 리뷰하고 개선점을 제안해줘" \
--output-format json \
--max-turns 5 \
--permission-mode dontAsk
dontAsk 모드로 사전 허용된 동작만 실행하고, JSON 출력으로 후속 파이프라인이 결과를 파싱할 수 있게 합니다.
9-4. 격리 환경에서 자유롭게 실행
docker run -it my-claude-image claude --dangerously-skip-permissions
컨테이너처럼 호스트가 보호되는 환경에서만 권한 우회를 허용합니다.
9-5. 병렬 작업
claude -w feature-auth
-w로 git worktree를 만들어 여러 Claude 세션을 격리해서 병렬로 돌릴 수 있습니다.
10. 자주 막히는 부분과 해결 팁
10-1. PowerShell vs CMD 헷갈림
설치 명령에서 &&가 PowerShell에서 안 먹히거나, irm이 CMD에서 안 먹힐 수 있습니다. 프롬프트가 PS C:\로 시작하면 PowerShell, 그냥 C:\이면 CMD입니다.
10-2. command not found: claude
PATH가 제대로 잡히지 않은 경우입니다. 네이티브 설치본은 보통 ~/.local/bin/claude나 ~/.claude/bin/claude에 위치하므로, 셸 설정 파일에 PATH를 추가해야 합니다. 자세한 진단은 claude doctor로 확인할 수 있습니다.
10-3. npm 설치 시 권한 오류
sudo npm install -g는 사용하지 마세요. 대신 사용자 디렉터리(~/.npm-global 등)를 npm prefix로 지정하는 방식이 공식 문서에서 권장됩니다.
10-4. 무료 계정으로 안 됨
Claude Code는 유료 계정(Pro, Max, Team, Enterprise) 또는 Console 계정이 필요합니다. 무료 Claude.ai 계정으로는 사용할 수 없습니다.
11. 마치며
Claude Code는 단순한 CLI 도구처럼 보이지만, 권한 모드와 실행 옵션을 어떻게 조합하느냐에 따라 개인 개발 보조부터 CI 자동화까지 활용 폭이 크게 달라집니다.
처음에는 default 모드로 안전하게 시작해 익숙해지면 acceptEdits, plan을 적극적으로 쓰고, 자동화가 필요한 상황에서는 -p와 dontAsk를 결합해 통제 가능한 자동 실행을 구성하는 것이 한 가지 자연스러운 흐름입니다.
새 기능과 옵션은 공식 What's New와 Changelog에서 자주 확인하시고, 막히는 부분이 있다면 세션 안에서 /help나 /bug 명령을 활용해보세요.
댓글 없음:
댓글 쓰기