Claude Code CLI: 완벽한 기술 가이드

콘텐츠 버전: 2026년 10월
출처: Anthropic의 공식 문서(code.claude.com/docs 및 support.claude.com). 전체 목록은 공식 출처에 있습니다.
주의사항: Claude Code는 자주 업데이트됩니다. 이 자료를 참고하기 전에 /release-notes와 claude --help로 변경 사항을 확인하십시오.

📑 목차

Claude Code CLI란 무엇인가
설치 및 인증
입력 명령어(Command)
키보드 단축키 및 접두사(Prefix)
필수 슬래시 명령어(Slash commands)
권한 모드(Permission modes)
메모리: CLAUDE.md 및 자동 메모리(auto memory)
설정: settings.json
훅(Hooks)
서브 에이전트(Subagents)
스킬, 명령어 및 플러그인(Skills, commands and plugins)
터미널에서의 MCP
체크포인트 및 컨텍스트 관리(Checkpoints e gestão de contexto)
비대화형 모드(-p) 및 CI
병렬 세션(Sessões em paralelo)
예약 자동화(Automação agendada)
원격 및 장치 간 작업(Trabalho remoto e entre dispositivos)
✅ CLI만 가능한 것
❌ CLI가 할 수 없는 것
🤫 잘 알려지지 않은 기능
🏆 권장 워크플로우
⚠️ 주의사항 및 제한 사항
📚 공식 출처

1. 🧠 Claude Code CLI란 무엇인가

Claude Code는 Anthropic의 에이전트 프로그래밍 도구입니다. 이 도구는 사용자의 코드를 읽고, 파일을 편집하며, 명령을 실행하고, 개발 도구에 통합됩니다. CLI(Command Line Interface)는 터미널 버전입니다: 프로젝트 폴더 내에서 claude를 실행하고, 해당 프로젝트에서 작업하는 에이전트와 대화합니다.

이는 자동 완성 기능(autocomplete)이 아닙니다. 이 에이전트는 다음 사이클로 작동합니다:

🔍 탐색(Explora): 저장소(repository)를 읽고 검색합니다.
🗺️ 계획(Planeja): 접근 방식을 제안합니다.
✏️ 편집(Edita): 파일을 수정합니다.
▶️ 실행(Executa): 테스트, 빌드 및 git을 실행합니다.
✅ 검증(Verifica): 결과가 올바를 때까지 반복합니다.

공식 문서에 따르면 이 도구가 하는 일:

테스트 작성, 린트 오류 수정, 병합 충돌 해결, 종속성 업데이트 및 릴리스 노트 작성.
자연어 설명이나 에러 메시지를 기반으로 기능 구현 및 버그 수정.
git과 직접 연동: 스테이징(stage), 커밋 메시지 작성, 브랜치 생성 및 풀 리퀘스트 열기.
MCP를 통해 외부 도구와 연결: Google Drive, Jira, Slack 또는 내부 도구.
Unix 파이프라인, 스크립트 및 CI에서 작동.

동일한 엔진이 구동되는 곳: 터미널(CLI), VS Code/Cursor, JetBrains, 데스크톱 앱의 코드 탭, 웹(claude.ai/code), 모바일 앱 및 Slack. 리포지토리의 CLAUDE.md, 설정 및 MCP 서버는 이 모든 표면에서 유효합니다.

공식 플랫폼 페이지에서는 CLI를 터미널 작업에 가장 완벽한 인터페이스로 설명하며, 스크립팅과 Agent SDK가 오직 여기에만 존재한다고 언급합니다.

2. 📦 설치 및 인증

요구 사항

운영 체제: macOS 13.0+, Windows 10 1809+ 또는 Windows Server 2019+, Ubuntu 20.04+, Debian 10+, Alpine Linux 3.19+
하드웨어: RAM 4 GB 이상, x64 또는 ARM64 프로세서
계정: Pro, Max, Team, Enterprise 또는 Console. claude.ai의 Free 플랜은 Claude Code를 포함하지 않습니다.
대안: 타사 제공업체 (Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry)

설치하기

# 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

# 대안
brew install --cask claude-code          # Homebrew (stable 채널)
brew install --cask claude-code@latest   # Homebrew (latest 채널)
...

apt, dnf, 및 apk를 위한 서명된 리포지토리도 있습니다 (Debian, Fedora, RHEL, Alpine).

확인하기

claude --version # 버전을 출력합니다. 예: 2.1.211 (Claude Code)
claude doctor # 세션 없이 설치 및 설정을 진단합니다.

업데이트

설치 방법	자동 업데이트?	업데이트 방법
네이티브 인스톨러	✅ 예, 백그라운드에서	`claude update`로 강제 실행
...
O 업데이트 채널(`latest` 또는 `stable`)은 설정 `autoUpdatesChannel`, 또는 `/config`에서 정의합니다. `stable`은 보통 일주일 전 버전이며 심각한 회귀(regressions)가 있는 버전은 건너뜁니다.

3. 🚪 입력 명령어(Input Commands)

명령어	기능
`claude`	대화형 세션을 시작합니다.
...

4. ⌨️ 키보드 단축키 및 접두사(Prefixes)

주요 단축키

단축키	기능
`Esc`	Claude를 중단하거나 대화 상자를 닫습니다.
...

macOS: Option 키가 필요한 일부 단축키(예: Option+P)는 터미널에서 Option을 Meta로 설정해야 합니다. Option+T는 이 설정 없이 작동합니다.

줄 시작 접두사

접두사	효과
`/`	명령어 또는 스킬입니다.
...
쉘 모드 예시:

! npm test

테스트가 실행되고 Claude는 사용자가 두 번째 프롬프트를 입력할 필요 없이 실패 이유를 설명합니다.

5. ⚡ 필수 슬래시 명령어(Slash commands)

전체 목록을 보거나 필터링하려면 /를 입력하세요.

카테고리	명령어	용도
🏗️ Setup	`/init`, `/memory`, `/permissions`, `/config`, `/doctor`	CLAUDE.md 생성, 메모리 및 규칙 편집, 진단하기
...

/init은 리포지토리를 분석하고 빌드, 테스트 및 컨벤션 명령을 포함하는 초기 CLAUDE.md를 생성합니다. 파일이 이미 존재하는 경우 개선 사항을 제안합니다.
/effort는 low, medium, high, xhigh, max 또는 auto를 받습니다.
/simplify는 변경된 코드를 네 개의 에이전트가 병렬로 검토합니다.
/ultrareview는 클라우드 상의 샌드박스에서 여러 에이전트를 이용한 심층적인 검토를 수행합니다.
/usage는 세션 비용과 플랜 제한을 보여줍니다. /cost는 별칭입니다.

6. 🔐 권한 모드 (Permission Modes)

모드	질문 없이 실행하는 작업	적합한 경우
`auto` ⚡	읽기 및 쓰기는 작업 디렉토리에서 바로 진행되며, 나머지 작업은 보안 분류기를 거칩니다.	장시간의 작업, 중단이 적을 때
...
모드 변경 방법:

세션 중: Shift+Tab. auto부터 순환하는 사이클은 auto → default → acceptEdits → plan입니다.
시작 시: claude --permission-mode plan을 사용합니다.
단일 프롬프트로 Plan 모드 진입: 프롬프트를 /plan으로 시작합니다.
기본값: settings.json의 permissions.defaultMode에서 설정합니다.
dontAsk는 Shift+Tab 사이클에 포함되지 않습니다. --permission-mode dontAsk로 활성화할 수 있습니다.

아는 사람만 아는 사실: v2.1.283 버전부터 auto가 터미널과 VS Code의 대화형 세션 기본 모드가 되었습니다. 그리고 deny 규칙은 bypassPermissions를 포함한 모든 모드에서 차단합니다.

7. 📄 메모리: CLAUDE.md 및 자동 메모리 (Auto memory)

Claude Code는 두 가지 메모리 시스템을 가지고 있으며, 둘 다 필수 설정이 아닌 **컨텍스트(context)**로 로드됩니다.

	`CLAUDE.md`	Auto memory
작성자	사용자 (당신)	Claude
...

CLAUDE.md 위치

위치	범위
`~/.claude/CLAUDE.md`	모든 프로젝트의 사용자 설정
...
리포지토리에 `AGENTS.md`가 있고 `CLAUDE.md` (또는 `CLAUDE.local.md`)가 없는 경우, Claude Code는 대신 `AGENTS.md`를 읽습니다.

예시

# 프로젝트
- Build: ./gradlew build
- Testes: ./gradlew test
...

공식 문서의 모범 사례:

각 파일은 200줄 미만으로 유지하세요. 긴 파일은 컨텍스트를 소모하고 준수도를 떨어뜨립니다.
검증 가능한 지침을 작성하세요: '2칸 들여쓰기 사용' 대신 '잘 포맷하라'와 같이 쓰지 마세요.
@경로/파일은 최대 4단계까지 다른 파일을 가져옵니다.
Claude가 같은 실수를 두 번째 저지를 때 한 줄 추가하세요.
코드의 일부에만 적용되는 규칙의 경우, 경로별 범위 지정이 가능한 .claude/rules/를 사용하세요.

유용한 명령어:

/memory: CLAUDE.md를 편집하고, 자동 메모리(auto memory)를 켜거나 끄고, Claude가 기록한 내용을 보여줍니다.
/doctor prompt-audit: 오래되거나 모순되거나 존재하지 않는 파일을 언급하는 지침을 찾습니다.

주의사항: CLAUDE.md는 규칙이 아닌 컨텍스트입니다. 실제로 어떤 행동을 막으려면, 권한 deny 규칙이나 훅(hooks)을 사용하세요.

8. ⚖️ 설정: settings.json

우선순위 (가장 강한 것부터 가장 약한 순)

레벨	파일	영향을 받는 주체
1. Managed	`managed-settings.json`, MDM 또는 claude.ai 콘솔	조직
...

일반적으로, 가장 높은 레벨이 승리합니다. 하지만 permissions.allow와 permissions.deny 같은 목록은 서로 대체하는 것이 아니라 합산됩니다.

예시: linter 및 테스트 허용, .env 파일 차단

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

차이를 만드는 세부 사항:

이 파일은 엄격한 JSON입니다: 주석이나 여분의 쉼표는 설정 오류를 발생시킵니다.
* 앞의 공백도 중요합니다: Bash(git diff *)는 git diff와 인수를 일치시키고; 공백이 없으면 git diff-index와도 일치시킬 수 있습니다.
JSON 편집을 피하고 싶다면? /permissions를 열면 메뉴가 나타나며, /fewer-permission-prompts는 사용 패턴을 분석하여 허용 목록(allowlist)을 제안합니다.

9. 🪝 Hooks

무엇인가요: 세션 수명 주기(life cycle)의 고정된 지점에서 실행되는 사용자 명령어(또는 HTTP 호출, MCP 도구, 프롬프트 또는 에이전트)입니다. 이는 Claude가 실행하기로 결정하는 것에 의존하지 않습니다.

사용 목적: 편집 후 코드 형식 지정, 위험한 명령어 차단, 실행된 모든 명령어 기록, 팀원에게 알림, 세션 시작 시 컨텍스트 로드.

가장 많이 사용되는 이벤트

SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, Stop, PreCompact, PostCompact (문서에는 수십 개의 이벤트가 나열되어 있습니다).

예시: 편집 후 형식 지정

{
  "hooks": {
    "PostToolUse": [
...

종료 코드

코드	효과
`0`	성공; 동작이 진행됨 (출력 JSON에서 차단되지 않는 한)
...
핸들러 유형: `command`, `http`, `mcp_tool`, `prompt`, 그리고 `agent` (실험적입니다).

팁:

/hooks는 구성된 훅을 보여줍니다 (읽기 전용). 설정은 settings.json에 있습니다.
대부분의 이벤트에서 훅이 실패하거나 시간 초과되면 동작은 진행됩니다. 이 경우 차단하려면 command 또는 http 훅에 `
자동(Automático): description을 기반으로 Claude가 위임합니다.
명시적(Explícito): 프롬프트에 서브 에이전트를 언급하거나 @를 사용하여 명시합니다.
세션 전체: claude --agent code-reviewer.
일시적인 정의, 세션 동안만 유효:

claude --agents '{"debugger": {"description": "Debugs errors", "prompt": "You are an expert debugger."}}'

추가 기능(Recursos extras):

/subtask <작업>은 전체 대화를 상속받아 백그라운드에서 작업하는