# 1. Claude Code 사용법 — 실무 개발자용 참조 문서

2026-04-18

2. 이 문서에 대하여

2.1 -1. 작성 조건과 한계 공개

• 작성 시점: 2026-04-18. Claude Code는 분기 단위로 기능이 추가되므로 수개월 안에 일부 서술이 낡을 수 있다. 각 절 말미에 관련 공식 문서 경로를 표기했다.
• 작성자의 관점: 이 문서는 Claude Code 내부에서 동작하는 LLM 관점에서 관찰 가능한 도구 호출·컨텍스트 동역학을 반영한다. 반면 MCP 서버 직접 설치, IDE 확장의 UX, 데스크톱 앱 전용 기능 등은 외부 관찰이 제한적이어서 공식 문서와 플러그인 저장소를 2차 자료로 사용했다.
• Anthropic 공식 문서와의 차별점: 한국어화, 실제 도구 호출 패턴과 흔한 실패 양상, 워크플로우 사례, 선택 기준과 안티패턴.
• 범위 밖: Claude API(Anthropic SDK)로 직접 에이전트를 구축하는 방법은 별도 문서 주제. 본문은 CLI·IDE·Web·Mobile 사용자 관점에 집중한다.

2.2 -2. 작성 방법론

1. 1차 출처: code.claude.com/docs의 공식 문서, 공식 changelog.
2. 2차 관찰: 실제 도구 호출 순서, 컨텍스트 압축 시점, 권한 흐름.
3. 교차 검증: 하위 에이전트(claude-code-guide)로 사실 점검.
4. 불확실성 표기: 확실하지 않은 서술은 본문에 “확인 필요“로 명시.

3. 서문 — Claude Code의 위치

3.1 -1. Claude Code란

Claude Code는 Anthropic이 제공하는 에이전트형 코딩 환경이다. 단순한 LLM 코드 완성기가 아니라, 자체 도구 집합으로 파일을 읽고 쓰고 셸 명령을 실행하며 여러 단계를 스스로 계획·실행한다. 사람이 상호작용하는 계층은 대화형 REPL이지만, 그 뒤에서는 도구 호출 루프가 돌아간다.

3.2 -2. 배포 채널

CLI가 기준 환경이다. 다른 채널은 CLI 기능의 상위 집합이 아니라 부분 집합에 가깝다. 고급 자동화(Hooks, MCP)를 쓸 때는 CLI가 가장 안전하다.

3.3 -3. 다른 AI 코딩 도구와의 차이

• Copilot 계열과의 차이: Copilot은 에디터 내 인라인 완성이 주(主), Claude Code는 에이전트 실행이 주. 범위·책임·위험도가 다르다.
• Cursor와의 차이: Cursor는 에디터 자체를 대체하며 UX 주도, Claude Code는 CLI 주도로 IDE 독립적. 워크플로우 자동화(Hooks, Cron, Loop)가 더 깊다.
• Aider/Goose와의 차이: Aider는 git 기반 페어 프로그래밍, Goose는 오픈 자동화 에이전트. Claude Code는 Anthropic의 SDK/모델 생태계와 수직 통합된다.

3.4 -4. 이 문서의 구성

2부는 도입, 3–4부는 일상 사용, 5–6부는 확장과 자동화, 7부는 통합, 8부는 설정, 9부는 실무 패턴·안티패턴을 다룬다. 급히 써야 한다면 2 → 3 → 9부만 읽어도 대부분의 일이 굴러간다.

4. 설치와 초기 설정

4.1 -1. 설치

공식 설치 스크립트 (macOS/Linux/WSL):

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

• 자동 업데이트가 포함된다. 주기적으로 최신 버전으로 올라간다.
• 시스템에 Node.js 의존이 없는 네이티브 바이너리로 배포된다(과거의 npm 기반 설치는 레거시).
• Windows는 별도 설치 프로그램. WSL에서 쓰는 편이 터미널 행동이 더 일관적이다.

4.2 -2. 인증

• 시작 시 claude 실행 → 브라우저 로그인 프롬프트.
• 계정은 Pro / Max / Team / Enterprise 구독 또는 Anthropic Console 키. Console 키는 개별 과금이 적용된다.
• 기업 환경에서 클라우드 제공자를 쓰고 싶다면 Amazon Bedrock, Google Vertex AI, Microsoft Foundry를 지원한다. 환경 변수로 전환한다.

4.3 -3. 모델 선택

• 세션 중에는 /model로 전환.
• 영구 설정은 settings.json의 model 필드(예: "claude-sonnet-4-6").
• 고속 모드(/fast)는 Opus 4.6 전용이다. Opus 4.7에서 /fast를 켜면 4.6으로 자동 전환된다. 2.5배 빠르지만 토큰 단가가 6배(입력 $30 / 출력 $150 per 1M, 200K 초과 컨텍스트는 $60 / $225). 비용 민감 작업에는 부적합, 긴급한 디버깅·빠른 반복에만 사용.
• Thinking effort(추론 강도)는 /effort 슬라이더로 조절한다. xhigh는 Opus 4.7의 high와 max 사이 절충 옵션.

4.4 -4. 환경 변수

4.5 -5. 첫 실행 체크리스트

1. claude --version으로 설치 확인.
2. 프로젝트 루트에서 claude를 실행하고 /help로 명령어 개관.
3. 프로젝트에 CLAUDE.md를 두고 팀 공용 지시를 기록.
4. ~/.claude/CLAUDE.md에 개인 선호를 기록(톤, 코딩 스타일, 자주 쓰는 언어).
5. /permissions로 기본 권한 모드를 점검.

5. 기본 상호작용

5.1 -1. 대화의 구조

입력은 세 종류다.

• 일반 텍스트: 사용자의 요청. 자연어.
• / 시작: 슬래시 커맨드(내장 또는 커스텀 스킬).
• ! 시작: 쉘 명령을 사용자 세션에서 직접 실행(CLI 내). 출력은 대화에 포함된다. gcloud auth login 같은 대화형 로그인에 유용.
• @파일경로: 파일을 컨텍스트에 첨부.

5.2 -2. 파일 조작 도구군

Claude가 사용자 편에서 호출하는 핵심 도구들이다. 사용자가 직접 호출하는 API는 아니지만, 동작을 이해하면 Claude의 행동을 예측할 수 있다.

실무 주의: 파일 삭제는 Bash의 rm으로 처리된다. Write는 덮어쓰기지만 삭제 도구는 없다. 안전한 설계.

5.3 -3. Bash 실행

• 쉘은 상태를 유지하는 세션이 아니다. 각 호출은 독립 실행이며 cd의 효과는 유지되지 않는다. 지속이 필요하면 절대 경로 사용.
• 긴 명령은 run_in_background: true로 백그라운드 실행. Monitor로 관찰 가능.
• 타임아웃은 기본 2분(최대 10분). 빌드·테스트는 백그라운드로 돌리는 편이 안전.
• find, grep, cat, sed 같은 전통 도구 대신 Glob/Grep/Read/Edit를 쓰도록 프롬프트에 이미 가이드가 내장돼 있다. 강제 덮어쓰기는 하지 않지만 권장 이유는 권한·출력 관리.

5.4 -4. 편집 모드

모드는 세션의 기본 행동 강도를 결정한다.

Shift+Tab 순환 토글. 진입 시 현재 모드가 상단에 표시된다.

5.5 -5. Plan mode 상세

• EnterPlanMode 도구로 진입. 종료는 ExitPlanMode에 계획 본문을 실어 호출.
• Plan mode에서는 쓰기 계열 도구가 잠긴다(실제 도구 목록이 필터링됨). Read, Grep, Glob, WebFetch 등은 사용 가능.
• 사용자가 계획을 수락하면 자동으로 기본 모드로 복귀.
• 실무 효용: 대규모 리팩터링, 신규 기능 설계, 마이그레이션처럼 방향 결정 비용 > 실행 비용인 작업에 적합.
• 실패 양상: 계획을 지나치게 세분화하여 실행 단계에서 이미 맥락이 낡은 경우가 있다. 큰 줄기만 합의하고 실행 중 세부를 조정하는 편이 현실적이다.

5.6 -6. 체크포인트와 /rewind

• Claude의 응답 직후마다 Edit/Write 도구로 변경된 파일의 스냅샷이 자동 저장된다.
• 복구: Esc를 두 번 누르거나 /rewind 명령. 메뉴에서 파일·대화·양쪽 중 무엇을 되돌릴지 선택.
• 보존 기간: 30일 자동 정리. 세션 재시작 이후에도 그동안은 유지되므로 이전 세션의 변경을 복구할 수 있다.
• 추적하지 않는 것:
• Bash 명령으로 생긴 파일 변경(rm, mv, cp 등). rm은 체크포인트로 되살릴 수 없다.
• Claude Code 밖에서 사람이 직접 편집한 변경.
• 다른 동시 세션의 편집.
• 세션 컨텍스트는 복구되지 않는다: 체크포인트는 파일 상태만 복구할 뿐, 새 세션은 이전 대화 맥락을 잃는다. 대형 다파일 디버깅은 git 커밋·메모와 병행.
• 한계: 버전 관리 시스템의 대체가 아니다. 장기 보존·공유·검토가 필요한 변경은 반드시 git 커밋으로 남긴다.

6. 프로젝트 컨텍스트 관리

Claude Code의 성능은 **“무엇을 알고 있느냐”**에 크게 좌우된다. 컨텍스트 설계는 프롬프트 엔지니어링의 한 축이다.

6.1 -1. CLAUDE.md 메모리 계층

로딩되는 파일과 우선순위:

작성 원칙:

• 짧고 구체적. 원칙론은 무시되기 쉽다. “테스트는 항상 npm test로 실행” 같은 단답형이 먹힌다.
• 이유(Why)를 덧붙이라. 규칙만 있으면 엣지 케이스에서 판단 실패. “X 하지 마. 왜냐하면 Y였기 때문“이 최소 단위.
• 도메인 용어 정의. 팀 내부 용어는 매번 물어보게 된다.
• 자주 실수하는 지점 명시. 예: “이 프로젝트의 utils/db.py는 절대 직접 import하지 말 것. services/ 를 통해 접근.”

6.2 -2. 자동 메모리

• ~/.claude/projects/.../memory/ 디렉터리 아래에 MEMORY.md(색인)와 개별 메모리 파일이 쌓인다.
• Claude가 사용자 선호·프로젝트 맥락·피드백을 포착해 스스로 저장한다.
• MEMORY.md는 매 세션 로드되므로 200줄 이내로 짧게 유지해야 함.
• 메모리는 이따금 낡는다. /memory로 편집 또는 “이 메모리 지워” 같은 명시 요청으로 정리.

6.3 -3. 프로젝트별 설정

• .claude/settings.json (팀 공유) vs .claude/settings.local.json (개인).
• 공유 설정에는 팀 전체가 동의할 권한·훅·스킬만. 개인 취향(모델 선택, 키바인딩)은 로컬에.

6.4 -4. 컨텍스트 예산 관리

• /context로 현재 사용량을 시각화.
• 자동 압축이 걸리는 임계치에 가까워지면 중요한 초반 맥락이 요약으로 밀려난다. 중요한 결정은 대화 초반에 또는 CLAUDE.md에 고정.
• 큰 파일을 반복적으로 Read하면 쉽게 컨텍스트가 찬다. 필요한 부분만 offset/limit 또는 Grep으로 발췌.
• 1M 컨텍스트 모델(Max/Team/Enterprise에서 Opus)은 긴 로그 분석이나 대규모 코드베이스 스캔에 적합하지만, 모델 지연과 비용이 증가한다. 기본은 표준 컨텍스트.

7. 확장성

7.1 -1. Slash Commands 개요

내장 명령과 스킬(커스텀 명령)을 통칭. 자주 쓰는 것:

7.2 -2. Skills (커스텀 스킬)

스킬은 재사용 가능한 지침 묶음이다. Slash command가 단순 문자열 매크로라면, 스킬은 frontmatter로 동작 조건·도구·컨텍스트를 기술한다.

저장 위치:

• 개인: ~/.claude/skills/<skill-name>/SKILL.md
• 프로젝트: .claude/skills/<skill-name>/SKILL.md
• 플러그인 번들: 설치된 플러그인의 skills/

SKILL.md 구조:

---
name: review
description: PR 리뷰 시 자동 호출. Diff를 읽고 버그·스타일·성능 관점에서 평가
disable-model-invocation: false  # false면 Claude가 조건 맞을 때 자동 호출
allowed-tools: "Read Grep Bash(git:*)"
---

# 지침 본문

1. `gh pr diff`로 변경 가져오기
2. 각 파일을 Read로 검토
3. 보안·성능·가독성 관점의 체크리스트 적용
4. 결과를 마크다운으로 요약

호출 방식:

• 사용자가 /review 입력 시 직접 호출.
• disable-model-invocation: false면 Claude가 description을 근거로 자동 호출(본인 판단).
• 플러그인 스킬은 plugin:skill 형태로 네임스페이스 충돌 방지.

실무 팁:

• 자주 반복되는 체크리스트(PR 리뷰, 보안 검사, 명세 작성)는 스킬로 뽑는 편이 효율적이다.
• allowed-tools로 스킬이 파괴적 작업을 못 하도록 제한.
• description은 Claude가 스킬 선택을 결정하는 유일한 근거다. 간결하지만 정확하게.

7.3 -3. Subagents

메인 세션에서 격리된 하위 에이전트를 호출한다.

기본 제공 subagent_type:

커스텀 subagent 정의 (~/.claude/agents/security-reviewer.md):

---
description: 보안 관점의 독립 리뷰
prompt: |
  당신은 보안 전문가입니다. OWASP Top 10 기준으로
  코드를 검토하고 취약점을 식별합니다.
tools: [Read, Grep, Glob]
model: sonnet
isolation: worktree  # 별도 git worktree에서 실행 (선택)
---

실무 이점:

• 컨텍스트 격리: 하위 에이전트의 탐색 과정이 메인 세션 컨텍스트를 먹지 않는다.
• 병렬 실행: 여러 subagent를 한 메시지에서 동시 호출 가능.
• 독립 판단: “독립 의견“이 필요할 때(코드 리뷰, 마이그레이션 안전성 2차 확인).

실패 양상:

• 서브에이전트는 메인 대화 내용을 모른다. 프롬프트에 자족적 맥락을 주지 않으면 부적절한 탐색을 한다.
• 과사용 시 오히려 시간이 늘어난다. 단일 쿼리로 충분한 작업은 Grep/Glob를 직접 쓰는 편이 빠르다.
• isolation: worktree는 파일 변경을 격리하지만 clean up/머지 책임이 사용자 몫.

7.4 -4. Output Styles

• outputStyle 설정으로 응답의 톤·길이·포맷 변경.
• 대표 값: "Explanatory"(설명 강화), "Learning"(학습 중심). 구체 목록은 /output-style 또는 settings.json에서 선택.
• 실무적으로 팀 전체가 같은 스타일을 쓰면 diff 리뷰가 수월하다.

7.5 -5. Plugins

플러그인은 스킬 + 서브에이전트 + 훅 + MCP + LSP 설정 + 모니터를 하나로 묶은 재사용 번들이다. 개인 .claude/가 한 프로젝트 한정이라면, 플러그인은 팀·커뮤니티 배포를 전제한다.

디렉터리 구조:

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 필수 메타데이터(name, version, description)
├── skills/<skill-name>/SKILL.md
├── agents/<agent-name>.md
├── hooks/hooks.json
├── .mcp.json
├── .lsp.json
├── monitors/monitors.json
├── bin/                     # 함께 배포할 실행 파일
├── settings.json            # 플러그인 기본 설정
└── README.md

설치·관리 명령:

네임스페이스: 플러그인이 제공하는 스킬은 /<plugin-name>:<skill-name>으로 호출된다. 독립 스킬(.claude/skills/)은 /<skill-name>. 이 접두 차이로 이름 충돌을 방지.

배포:

• 공식 마켓플레이스: claude.ai/settings/plugins/submit에서 제출.
• 팀 프라이빗: git 리포지토리에 플러그인 디렉터리 커밋, 팀원은 --plugin-dir나 사내 설정으로 로드.
• npm/git clone 설치 흐름은 공식 문서에 명시 없음(확인 필요).

실무 팁:

• 같은 프로젝트에서 반복되는 훅·스킬 조합은 플러그인으로 추출하면 타 프로젝트에서도 재사용된다.
• .claude-plugin/ 아래에 commands/, skills/, agents/, hooks/를 넣으면 인식되지 않는다. 이들은 플러그인 루트에 둬야 함.
• 신뢰하지 않는 플러그인 설치는 MCP와 마찬가지로 prompt injection 경로. 훅·MCP 정의를 설치 전에 검토.

8. 자동화

8.1 -1. Hooks

라이프사이클 이벤트에 외부 명령을 꽂는 메커니즘.

지원 이벤트(주요):

settings.json 예시 (Bash(rm *) 차단 + 편집 후 자동 포맷):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": ".claude/hooks/block-rm.sh",
          "if": "Bash(rm *)",
          "timeout": 5
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "npx prettier --write"
        }]
      }
    ]
  }
}

훅 스크립트 응답:

• exit 0 + JSON on stdout: permissionDecision(allow|deny|ask|defer), additionalContext, updatedInput.
• PostToolUse는 decision: "block"으로 후처리 중단 가능.
• exit 비-0: 훅 실패로 처리, 사용자에게 노출.

matcher: 정확 문자열(Bash), 파이프(Edit|Write), 정규식(mcp__.*). 비어 있으면 모든 이벤트.

실무 활용:

• 안전 레일: 파괴 명령 차단, .env 등 민감 파일 읽기 금지.
• 자동 포매팅: 편집 후 prettier/black 등.
• 감사 로그: 모든 도구 호출을 기록.
• 알림: 장시간 작업 완료 시 Slack/데스크톱 알림.

주의:

• 훅은 쉘 명령 실행이다. 경로·인코딩·타임아웃을 확실히 제어.
• 모든 도구 호출을 가로채면 지연이 눈에 띈다. matcher로 범위를 좁히라.
• “자동화 습관”(사용자가 매번 X 할 때마다 Y 실행)은 메모리/프롬프트가 아니라 훅으로 구현해야 한다. LLM은 “다음에 하겠다“고 약속해도 보장이 없다.

8.2 -2. /loop 반복

• /loop <interval> <prompt>: 주기적으로 프롬프트 실행.
• /loop <prompt>: 모델이 스스로 호흡을 조절(dynamic mode).
• 실패 감시·배포 대기·반복 폴링에 적합.
• 비용: 루프는 매 실행마다 컨텍스트를 재적재. 장시간 돌리기 전에 캐시 정책과 비용을 계산.

8.3 -3. 스케줄 (CronCreate, /schedule)

• 세션 내 스케줄: CronCreate 도구로 세션 동안 돌아가는 정기 작업.
• 영속 스케줄: /schedule 스킬로 원격 에이전트 트리거(클라우드 실행).
• 배포 후 모니터링, 일일 리포트, 의존성 업데이트 검사 등에 씀.

8.4 -4. Background tasks

• TaskCreate 도구로 장시간 작업을 백그라운드 에이전트에 위임.
• TaskList/TaskGet/TaskOutput으로 상태 조회.
• TaskStop으로 중단.
• 긴 빌드·테스트·정적 분석을 메인 세션에서 분리해 컨텍스트를 보호.

8.5 -5. Monitor

• Monitor 도구로 파일·프로세스 출력·로그를 스트림 감시.
• /loop와 조합해 “상태 변화시에만 반응“하도록 설계 가능.
• 폴링 대신 이벤트 구동으로 전환할 때 유용.

9. 통합

9.1 -1. MCP (Model Context Protocol)

외부 시스템을 Claude가 쓰는 도구로 노출하는 표준 프로토콜. 예: Google Drive, Linear, Jira, 사내 DB.

등록 위치:

• 프로젝트: .mcp.json
• 사용자: ~/.claude/mcp_servers.json 또는 settings.json의 mcpServers.

등록 예시:

{
  "mcpServers": {
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {"GITHUB_TOKEN": "${GITHUB_TOKEN}"}
    },
    "internal-api": {
      "transport": "http",
      "url": "https://mcp.example.internal/"
    }
  }
}

Transport:

• stdio: 로컬 프로세스 실행. 가장 일반적.
• http: HTTP 엔드포인트. 원격·사내 서버.
• sse: Server-Sent Events 스트리밍. 대량 데이터.

도구 이름 규칙: mcp__<server>__<tool>. 권한 지정도 이 이름으로.

권한 부여:

• OAuth가 필요한 서버는 초기 인증 단계가 있다(mcp__<server>__authenticate 등).
• 민감 MCP는 permissions.ask에 등록해 매 호출 확인.

실무 권고:

• 신뢰하지 않는 MCP 서버를 임의로 등록하지 마라. 도구 이름을 사칭하는 prompt injection 위험이 있다.
• enableAllProjectMcpServers: false로 기본을 닫고, 개별 허용이 안전하다.

9.2 -2. IDE 확장

• VS Code: 공식 확장. 인라인 diff·파일 선택·모델 전환.
• JetBrains: IntelliJ/PyCharm 등. 유사 기능.
• 한계: CLI에만 있는 일부 명령(Cron, 복잡 훅)은 UI에서 제한될 수 있다. 고급 자동화는 CLI 병용.

9.3 -2-1. Desktop 앱 (macOS / Windows)

데스크톱 앱은 비주얼 워크플로우에 최적화돼 있고, 일부 기능은 CLI에 없다.

데스크톱 전용 기능:

• 비주얼 diff: 라인별 인라인 코멘트, 클릭식 수락/거부.
• 다중 세션 병렬: 자동 git worktree 격리로 여러 작업을 동시에.
• Drag-drop 레이아웃: 채팅·diff·터미널·파일·프리뷰 패널을 자유 배치.
• 라이브 앱 프리뷰: 개발 서버·HTML·PDF를 앱 내부에서 미리보기.
• Computer use: 앱 실행·화면 제어(macOS/Windows만).
• PR 모니터링: auto-fix / auto-merge 자동화 UI.
• Dispatch: 모바일에서 데스크톱 세션 신규 생성(편의 기능).
• Side chat: 메인 스레드를 분기하지 않고 빠른 질문.

CLI에만 있는 기능:

• --dangerously-skip-permissions, --print, --output-format 등 스크립팅 플래그.
• permissions.defaultMode의 dontAsk 같은 일부 모드.
• Bedrock / Vertex / Foundry 등 제3자 프로바이더 전환.
• 에이전트 팀(multi-agent orchestration)의 일부 기능.
• Linux 지원(데스크톱 앱은 macOS/Windows만).

세션 관리:

• CLI 세션과 데스크톱 세션의 대화 히스토리는 분리.
• CLAUDE.md, MCP 서버, Hooks, Skills, settings.json의 설정은 공유.
• 단, 데스크톱 채팅(코드 외 일반 Claude 채팅)의 claude_desktop_config.json은 Code tab과 별개. 혼동 주의.

9.4 -2-2. 모바일 앱 (iOS)

• Dispatch: 폰에서 데스크톱 세션을 새로 생성하고 시작. “원격 제어“보다는 원격 시작·알림·승인 처리에 가깝다.
• 장시간 실행 중인 세션의 완료 알림과 간단한 승인을 외출 중에 처리하는 용도.
• CLI 세션을 폰에서 이어받아 대화하는 완전한 원격 제어는 공식 문서에 명시 없음(확인 필요).

9.5 -3. Git/GitHub 워크플로우

• 커밋: 사용자가 “커밋 해줘“라 명시할 때만 생성(기본 정책). HEREDOC으로 메시지 포맷 유지.
• PR: gh pr create를 Bash로 호출. 템플릿은 CLAUDE.md에 고정하면 일관성 확보.
• 리뷰: /review와 /ultrareview. 후자는 클라우드에서 다중 에이전트 심층 리뷰. Pro/Max 계정당 3회 무료(1회성, 갱신 없음), 이후 변경 규모에 따라 건당 $5–20의 extra usage로 과금. 소요 시간 5–10분, 백그라운드로 진행하므로 터미널을 닫아도 된다. Extra usage가 비활성이면 실행이 차단된다.
• 위험 작업(force push, 브랜치 삭제, amend)은 기본적으로 사용자 확인을 요구. 자동화하고 싶다면 훅으로 가드레일을 직접 설계.

9.6 -4. 클라우드 제공자

기업 환경의 데이터 거주지·감사 요구를 충족할 때 유용. 공통 주의: Fast mode나 일부 최신 기능은 제공자별 롤아웃이 다를 수 있다.

10. 설정과 권한

10.1 -1. settings.json 계층

우선순위(높음 → 낮음):

1. Managed(기업 배포, 오버라이드 불가)
2. CLI 플래그(세션 한정)
3. Local .claude/settings.local.json
4. Project .claude/settings.json
5. User ~/.claude/settings.json

병합 규칙: 스칼라는 덮어씀, 배열은 연결 후 중복 제거, 객체는 deep merge.

10.2 -2. 주요 필드

10.3 -3. Permissions 모델

구문: Tool 또는 Tool(specifier).

Bash 매칭:

• 정확: Bash(npm run build)
• 와일드: Bash(git *), Bash(npm run *)
• 복합 명령(&&, ||, ;, |)은 각 부분 독립 평가.
• 읽기 전용(ls, cat, git status 등)은 자동 허용(구성 불가).

Read/Edit (gitignore 스타일):

• 절대: //Users/alice/file
• 홈: ~/Documents/*.pdf
• 프로젝트 루트 상대: /src/**/*.ts
• 현재 기준 상대: *.env

WebFetch: WebFetch(domain:example.com)

MCP: mcp__server 또는 mcp__server__tool

Agent: Agent(AgentName)

평가 순서: deny → ask → allow. 첫 매칭이 이긴다.

/permissions 명령으로 인터랙티브 관리. 자주 묻는 명령을 빠르게 허용 목록에 추가할 수 있다.

10.4 -4. Keybindings

파일: ~/.claude/keybindings.json

{
  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+enter": "chat:submit",
        "ctrl+j": "chat:newline",
        "shift+tab": "chat:cycleMode",
        "ctrl+g": "chat:externalEditor",
        "ctrl+u": null
      }
    }
  ]
}

주요 Context: Global, Chat, Autocomplete, Settings, Confirmation, Tabs, Help, Transcript, HistorySearch, Task, ThemePicker, Attachments, Footer, MessageSelector, DiffDialog, ModelPicker, Select, Plugin, Scroll, Doctor

Chord: ctrl+k ctrl+s 같은 두 단계 조합 지원.

Unbind: 값을 null로.

10.5 -5. Statusline

• statusLine에 명령 또는 스크립트 지정.
• stdin으로 JSON 입력(sessionId, model, cwd, contextUsed, contextLimit, costUsd, gitBranch 등).
• stdout의 텍스트가 하단에 표시.
• 예시 — 비용·모델·브랜치를 한 줄로:

#!/usr/bin/env bash
read INPUT
MODEL=$(echo "$INPUT" | jq -r '.model')
COST=$(echo "$INPUT" | jq -r '.costUsd')
BRANCH=$(echo "$INPUT" | jq -r '.gitBranch')
echo " $MODEL | 🌿 $BRANCH | 💰 \$$COST"

8-6. Managed policies

기업 배포용 고정 설정 경로:

드롭인: managed-settings.d/*.json 알파벳 순 병합. MDM(Jamf 등)으로 배포.

9. 실무 패턴

공식 문서에 잘 나오지 않는, 내부 관찰과 경험에서 뽑은 원칙.

9-1. 긴 작업의 분할

증상: 한 번에 “전체 리팩터링“을 지시하면 중반에 맥락이 흐려지고 엉뚱한 파일을 건드린다.

원칙:

1. 먼저 Plan mode로 범위·영향 파일을 합의.
2. 변경을 독립 커밋 단위로 쪼개 순서를 정의.
3. 각 단계 후 테스트·타입 체크로 회귀 감지.
4. 매 단계 커밋하면 /rewind보다 안전하다.

9-2. 컨텍스트 절약

• 큰 파일은 Grep으로 필요한 부분만 읽힌다. 전체 Read는 마지막 수단.
• 에이전트 위임은 맥락 먹히는 작업(대규모 탐색, 문서 검색)에 유리. 단, 결과를 받은 뒤 해당 결과로 메인 세션에서 의사 결정은 그대로 이어간다.
• 초반에 내린 결정은 CLAUDE.md나 자동 메모리에 고정. 압축으로 사라지지 않게.
• /compact는 과도하게 쓰면 뉘앙스 손실. 정말 필요한 순간에만.

9-3. 실패 복구

9-4. 위험 작업

• 파괴적 작업(force push, db drop, rm -rf)은 기본적으로 사람이 승인하도록 유지.
• 반복적으로 허용해도 되는 “대상“에만 구체적 allow.
• 공유 시스템(스테이징 DB, 프로덕션 API)에 대한 쓰기는 매번 확인이 원칙.
• 사용자 인증이 필요한 작업은 !명령 프롬프트를 이용해 사용자가 직접 실행.

9-5. 안티패턴

1. “무한 자동화” 기대: /loop으로 성능 문제를 풀 수는 없다. 본질은 프롬프트와 맥락 설계.
2. 거대 CLAUDE.md: 200줄 넘어가면 Claude가 실제로 지키는 비율이 떨어진다. 짧고 현실적으로.
3. MCP 무분별 설치: 공급자 신뢰 확인 없이 설치하면 prompt injection 경로가 된다.
4. Subagent 남발: 단순 검색을 서브에이전트에게 보내면 오히려 느려진다.
5. Plan mode의 과도한 세분화: 계획이 너무 상세하면 실행 단계에서 현실과 불일치. 큰 결정만 합의.
6. 메모리로 자동화 흉내내기: “이제부터 X하면 Y 해라“는 메모리가 아니라 훅이어야 한다. 메모리는 약속, 훅은 강제.
7. Bypass permissions 상시 사용: 치명적. 일회성 컨테이너에만.

9-6. 비용 관리

• /fast는 빠르지만 단가가 다르다. 단순 편집엔 표준 모드.
• Opus 1M 컨텍스트는 쌓이면 비싸다. 필요할 때만.
• 하위 에이전트는 자체 토큰을 소비한다. 가볍게 물어볼 수 있는 건 메인에서.
• 팀 단위라면 includeCoAuthoredBy: false 유지 여부, statusLine에 비용 표시 등으로 가시화.

9-7. 팀 협업 패턴

• ./CLAUDE.md 공유: 팀 컨벤션, 주요 파일 위치, 테스트 실행법.
• .claude/skills/: 팀 공용 PR 리뷰, 릴리즈 체크리스트.
• .claude/hooks/: 파일 변경 시 포맷, 테스트 자동 실행, 민감 파일 접근 차단.
• .claude/agents/: 도메인 특화 리뷰어(보안, 성능, DB 마이그레이션).
• .mcp.json을 공유하되 토큰은 환경 변수로.

9-8. 디버깅 절차

Claude가 이상하게 굴 때 체크 순서:

1. /context — 컨텍스트가 가득 찼는가?
2. 프로젝트·사용자·자동 메모리 — 낡은 지시가 방해하는가?
3. disableAllHooks: true — 훅이 응답을 꼬고 있는가?
4. MCP 서버 — 설치된 서버가 이상한 도구 이름을 주고 있는가?
5. /model 교차 — 특정 모델 이슈인가?
6. 간단한 프롬프트로 고립 재현 — 입력이 모호했는가?

부록 A. 자주 쓰는 슬래시 커맨드 치트시트

/help          전체 명령 목록
/model         모델 전환
/fast          고속 모드 토글 (Opus 4.6)
/effort        추론 강도 조절
/plan          계획 모드 진입
/clear         새 대화
/compact       컨텍스트 압축
/context       컨텍스트 사용량
/memory        CLAUDE.md / 자동 메모리 편집
/permissions   권한 관리
/loop          반복 실행
/schedule      스케줄 트리거
/rewind        체크포인트 복구
/review        PR 리뷰
/ultrareview   클라우드 다중 에이전트 리뷰
/batch         병렬 대규모 변경
/plugin        플러그인 설치·제거
/reload-plugins 플러그인 재로드
/discover-plugins 플러그인 탐색
/status        세션 상태
/doctor        환경 진단

부록 B. 내장 도구 요약

Read, Write, Edit, Glob, Grep, LSP, NotebookEdit
Bash (+ PowerShell on Windows)
Agent, AskUserQuestion
TaskCreate, TaskList, TaskGet, TaskUpdate, TaskStop, TaskOutput
CronCreate, CronList, CronDelete
Monitor
WebSearch, WebFetch
EnterPlanMode, ExitPlanMode, EnterWorktree, ExitWorktree
PushNotification, RemoteTrigger
ScheduleWakeup (내부 /loop 동적 모드)
ToolSearch (지연 로드 스키마 검색)

도구는 모델·세션 모드에 따라 일부가 숨겨진다. 실제 가용 목록은 시스템 상단에 노출된다.

부록 C. 자주 쓰는 settings.json 예시

{
  "model": "claude-sonnet-4-6",
  "outputStyle": "Explanatory",
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Read",
      "Grep",
      "Glob",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(npm test)",
      "Bash(npm run *)"
    ],
    "ask": [
      "Bash(git push:*)",
      "Bash(git reset:*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl http:*)",
      "Read(./.env)",
      "Read(~/.ssh/**)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{"type": "command", "command": "./scripts/format.sh"}]
      }
    ]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "cleanupPeriodDays": 14,
  "includeCoAuthoredBy": false,
  "language": "korean",
  "additionalDirectories": ["../docs/"]
}

참고 자료

• Claude Code 공식 문서: https://code.claude.com/docs
• Hooks: https://code.claude.com/docs/en/hooks.md
• Skills: https://code.claude.com/docs/en/skills.md
• Subagents: https://code.claude.com/docs/en/sub-agents.md
• MCP 서버: https://code.claude.com/docs/en/mcp-servers.md
• Settings: https://code.claude.com/docs/en/settings.md
• Permissions: https://code.claude.com/docs/en/permissions.md
• Keybindings: https://code.claude.com/docs/en/keybindings.md
• Statusline: https://code.claude.com/docs/en/statusline.md

변경 이력

• 2026-04-18: 초판.
• 2026-04-18: 5-5 플러그인, 7-2-1 데스크톱 앱, 7-2-2 모바일 앱 추가. /fast 단가(30/150 per 1M, 200K+는 60/225), /ultrareview 한도($5–20/회, 계정당 3회 무료), 체크포인트 30일·Bash 미추적 명시, Foundry 환경 변수(CLAUDE_CODE_USE_FOUNDRY·ANTHROPIC_FOUNDRY_RESOURCE·Entra ID) 구체화.