원문 캡처 · hidekazu-konishi.com
원문 캡처 · hidekazu-konishi.com

Claude Code 기능과 설정 참고서 2026

최초 게시일: 2026-05-16

최종 업데이트: 2026-10-03

  • 이 글은 위 최종 업데이트 날짜의 Claude Code를 설명한다. Claude Code는 빠르게 바뀌므로 기능이 정식 출시되거나 폐기되면 항목을 이 페이지에서 수정한다.

이 문서는 Claude Code의 사용자에게 보이는 기능을 한 페이지에서 찾아보는 참고서다. 배포 채널, 기본 도구, 계획 모드, 하위 에이전트, 스킬, 훅, 슬래시 명령, MCP 연동, 설정 키와 키 바인딩을 다룬다. 처음부터 끝까지 읽기보다 필요한 내용을 찾아보도록 구성했다. 각 카탈로그는 여러 질문을 한 번에 해결할 수 있도록 항목별 표 형식으로 정리돼 있다.

처음 Claude Code를 사용한다면 Claude Code 시작하기에서 설치와 첫 세션을 확인할 수 있다. 팀의 Claude Code 설정을 담당한다면 하네스 및 환경 엔지니어링 안내서에서 이 참고서가 목록으로만 다루는 운영 설계를 볼 수 있다.

빠른 참조: 스냅샷 작성 방법 · 배포 채널 · 핵심 기능 · 설정 참고 · 훅 목록 · 기본 슬래시 명령 · MCP 연동 · 키 바인딩 · 최근 추가 기능 · 최근 폐기 항목 · 자주 묻는 질문 · 참고 자료

스냅샷 작성 방법과 범위

이 페이지는 필요할 때 같은 주소에서 갱신하는 연간 스냅샷이다. 엔지니어나 그를 대신하는 AI 에이전트가 “현재 Claude Code가 사용자에게 제공하는 기능은 무엇인가?”라는 질문에 한 번의 조회로 답하도록 만들었다. 각 항목은 확인을 위해 공식 문서로 연결된다. 공식 Anthropic 배포판에서 사용자에게 보이는 범위, 즉 CLI·IDE 확장·데스크톱·웹·SDK·CI 통합, 사용자·프로젝트·로컬 범위의 settings.json 설정 키, 훅으로 가로챌 수 있는 생명주기 이벤트, CLI 기본 슬래시 명령, 외부 도구 서버를 연결하는 클라이언트 측 MCP 설정, 터미널과 IDE의 기본 키 바인딩을 다룬다.

설치·인증·첫 세션의 단계별 안내, 훅·권한 규칙·샌드박스·CLAUDE.md의 작성 예시, 요금제와 토큰당 비용은 범위에서 제외한다. 관련 내용은 시작 안내서와 하네스 및 환경 엔지니어링 안내서를 참고할 수 있다. 기준 자료는 Claude Code 공식 문서이며, 새 기능을 알리는 Anthropic 엔지니어링 게시물도 보완 자료로 쓴다. CLI에서 존재를 확인할 수 있지만 문서가 바뀔 수 있는 항목은 [Tracking], 미리보기·실험 채널 전용 기능은 [Preview], 제거 예정 기능은 [Deprecating]으로 표시한다.

최초 검토는 2026-05에 완료했다. 같은 해 필요에 따라 갱신하고, 항목은 해당 카탈로그에 추가한다. 제거된 항목은 한 차례 최근 폐기 항목에 둔 뒤 목록에서 뺀다. 각 카탈로그는 항목별 행, 동일한 열 구성, 간단한 동작 설명, 공식 문서 링크를 사용한다. 별칭이 여러 개면 CLI 프롬프트나 설정 파일에 표시되는 이름을 앞세우고 문서의 이름을 괄호에 적는다.

배포 채널

Claude Code는 여러 환경에서 쓸 수 있지만 각 환경이 제공하는 기능 범위는 다르다. CLI는 기준 채널이며 다른 채널은 기능 일부를 제공한다.

  • CLI: 터미널 프로그램 claude. macOS·Linux·Windows용 네이티브 설치 프로그램 또는 npm install -g @anthropic-ai/claude-code로 설치한다. Claude.ai 브라우저 OAuth 또는 API 키를 사용하며, 전체 도구를 제공하고 모든 편집기와 함께 쓸 수 있다. 정식 출시.
  • VS Code 확장: 편집기 사이드바와 인라인 채팅. VS Code Marketplace의 “Claude Code”에서 설치하고 CLI 인증을 이어받는다. IDE 인식 차이 미리보기와 VS Code·Cursor·Windsurf 등의 네이티브 연동을 제공한다. 정식 출시.
  • JetBrains 플러그인: IDE 도구 창. JetBrains Marketplace에서 설치하고 CLI 인증을 이어받는다. IntelliJ·PyCharm·GoLand·Rider·WebStorm 등에 네이티브로 연동하며 선택 영역 연결과 리팩터링 미리보기를 제공한다. 정식 출시.
  • 데스크톱 앱: macOS와 Windows용 독립 GUI. Anthropic 서명 설치 프로그램과 Anthropic 계정을 사용하며 세션 관리자, 프로젝트 전환기, 다중 프로젝트 세션 목록, GUI 관리 환경을 제공한다. 정식 출시.
  • 웹(claude.ai/code): 브라우저에서 https://claude.ai/code를 연다. Anthropic 계정이 필요하다. 로컬 파일 시스템은 사용하지 않고 클라우드 샌드박스만 이용하는 축소된 기능 범위를 제공하며, 대화 공유 링크를 지원한다. 정식 출시.
  • Claude Agent SDK: TypeScript와 Python 라이브러리. npm install @anthropic-ai/claude-agent-sdk 또는 pip install claude-agent-sdk로 설치하고 API 키를 쓴다. 도구를 직접 구성해 제품에 Claude Code를 구성 요소로 삽입하는 용도다. 정식 출시.
  • GitHub Action: CI 단계에서 실행한다. Marketplace의 anthropics/claude-code-action을 사용하고 저장소 시크릿에 API 키를 둔다. 체크아웃한 작업 공간에 범위를 제한하며 PR 검토와 CI 자동 diff를 지원한다. 정식 출시.
  • GitHub App: CLI에서 /install-github-app으로 설치하는 호스팅 봇. OAuth와 GitHub를 사용하며 저장소별로 범위를 제한한다. 채팅에서 이슈와 PR을 분류한다. 정식 출시.

도구별로 지원·부분 지원·미지원 여부를 비교하려면 핵심 기능 목록을 참고한다. 웹은 로컬 컴퓨터의 파일을 다루지 않으며 SDK는 직접 사용하는 제품이 아니라 내장용이다.

핵심 기능

기본 도구

모든 도구는 개별 권한 규칙의 적용을 받는다. MCP 서버가 제공하는 도구는 이 목록에 동적으로 추가된다.

  • Read: 로컬 파일 읽기. 기본적으로 읽기 전용이며 별도 권한 없이 소스 검토, 로그 확인, 설정 감사에 쓴다.
  • Edit: 기존 파일의 문자열을 정확히 바꾼다. 파일을 수정하므로 허용 규칙이 없으면 승인을 요청한다. 표적 버그 수정·이름 변경·일부 리팩터링에 쓴다.
  • Write: 파일을 만들거나 덮어쓴다. 허용 규칙이 없으면 승인을 요청한다. 새 파일 작성이나 전체 재작성에 쓴다.
  • Bash: 셸 명령을 실행한다. 셸이 할 수 있는 모든 부작용이 가능하며 명령 패턴별로 승인을 요청한다. 테스트·빌드·git·패키지 관리자 등에 쓴다.
  • Glob: 패턴으로 파일 경로를 찾는다. 읽기 전용이다.
  • Grep: ripgrep으로 파일 내용을 검색한다. 읽기 전용이며 저장소 전체에서 심볼이나 문자열을 찾는다.
  • NotebookEdit: Jupyter 노트북 셀을 수정한다. 승인 대상이다.
  • WebFetch: URL을 가져와 처리한다. 네트워크 요청이며 도메인별 권한을 적용한다. 공개 문서나 지정 URL에 쓴다.
  • WebSearch: 웹 검색을 실행한다. 네트워크 요청이며 권한으로 제어한다.
  • Task(Agent): 권한을 상속하는 하위 세션을 실행한다. 병렬 조사나 범위를 제한한 편집에 쓴다.
  • TodoWrite: 세션 할 일 목록을 만들거나 갱신한다. 내부 상태만 바꾼다.
  • BashOutput: 백그라운드 셸 명령 출력을 읽는다. 읽기 전용이다.
  • KillShell: ID로 백그라운드 셸을 종료한다. 프로세스를 중단하며 권한으로 제어한다.
  • SlashCommand: 사용자가 정의한 슬래시 명령을 실행한다. 동작은 명령에 따라 달라지고 명령의 도구 권한을 상속한다.
  • EnterPlanMode와 ExitPlanMode: 세션 중 계획 모드에 들어가거나 나온다. 나올 때 계획을 제시한다.
  • Skill: 등록된 스킬을 호출한다. 스킬에 따라 동작하고 스킬 도구 권한을 상속한다.

계획 모드와 하위 에이전트

계획 모드는 파일을 건드리기 전에 여러 단계의 변경을 검토하는 읽기 전용 모드다. Shift+Tab을 두 번 눌러 기본 모드와 자동 수락 모드를 지난 뒤 진입하거나, CLI에 --permission-mode plan을 지정하거나, settings.json에 permissions.defaultMode: "plan"을 설정한다. 허용 도구는 Read, Glob, Grep, WebFetch, WebSearch, 읽기 전용 Task, TodoWrite다. Edit, Write, NotebookEdit, 변경을 일으키는 Bash 명령은 차단된다. ExitPlanMode가 계획을 제시하면 사용자가 승인하거나 거부한다. 계획은 대화 문맥에만 보존되고 디스크에는 쓰지 않는다. 큰 리팩터링, 모호한 작업, 되돌리기 어려운 작업에 적합하다.

하위 에이전트는 부모가 Task(별칭 Agent) 도구로 실행하는 독립 Claude 세션이다. 자체 문맥 창과 도구 목록을 가지며 선택적으로 격리 전략을 쓴다. 정의 파일은 .claude/agents/<name>.md이고 YAML frontmatter에 name, description, tools, model을 적는다. 기본 하위 에이전트는 general-purpose, Explore, Plan, statusline-setup과 채널별 도우미다. 부모는 subagent_type: "<name>"으로 호출한다. 하위 에이전트는 부모 대화 내용을 볼 수 없고, isolation: "worktree"를 지정하면 git worktree에서 실행할 수 있다. 부모에게는 최종 메시지 하나만 돌아오며 중간 과정은 보이지 않는다. 권한은 부모와 같은 settings.json 권한 트리를 따른다.

하위 에이전트는 사용자에게 대화형 권한 승인을 요청할 수 없다. ask 규칙에 걸리는 도구 호출은 거부된다. 따라서 frontmatter의 tools: 목록에서 Edit, Write, NotebookEdit을 빼 읽기 전용으로 제한하고 승인 처리가 가능한 부모 에이전트에 편집·셸 작업을 맡기는 방식을 권장한다. 파일 편집을 맡는 statusline-setup처럼 범위가 좁고 예측 가능한 기본 하위 에이전트는 예외다.

스킬·출력 스타일·메모리

스킬은 필요할 때 하네스가 불러오는 재사용 가능한 이름 있는 지침·스크립트 묶음이며 보조 도구를 포함할 수 있다. .claude/skills/<name>/SKILL.md와 같은 디렉터리의 지원 파일로 구성한다. frontmatter에는 name, description, 선택 사항인 model과 도구 목록을 둔다. 하네스가 사용 가능한 스킬을 나열하고, 설명이 요청과 맞으면 Claude가 Skill 도구로 호출한다. 사용자·프로젝트 범위 또는 플러그인에 포함할 수 있다. 슬래시 명령이 /name으로 실행하는 프롬프트 템플릿이라면 스킬은 파일과 지침을 포함하는 더 풍부한 묶음이다. 스킬은 부모와 같은 세션·문맥에서 실행되고 하위 에이전트는 별도 문맥을 쓴다. 단순히 프롬프트 템플릿을 넣을 때는 슬래시 명령, 도메인 로직·구조화된 입력·보조 파일이 필요하면 스킬, 문맥 격리가 목적이면 하위 에이전트를 쓴다.

출력 스타일은 응답의 자세함, 코드 주석 밀도, 문체를 정한다. /config에서 선택하거나 settings.json에 outputStyle을 설정한다. 기본 제공 스타일은 간결한 엔지니어링 문체의 default, 코드 설명을 더하는 explanatory, 이유를 설명하는 교육 문체의 learning이다. 이후 버전에는 스타일이 더 추가될 수 있으므로 설치 버전의 정식 목록은 /config에서 확인한다. 사용자 정의 스타일은 .claude/output-styles/<name>.md에 두며 설정 키는 outputStyle: "<name>"이다. 세션별로 설정해 모든 응답에 적용한다.

자동 메모리는 활성화하면 세션 사이에 유지하는 파일 기반 개인 메모다. ~/.claude/projects/<workspace-slug>/memory/에 작은 Markdown 파일을 두고, 최상위 MEMORY.md에 항목별 한 줄 색인을 둬 문맥에 불러온다. 메모리 유형은 user, feedback, project, reference다. 프롬프트 입력의 #<text> 접두어나 자연어 요청으로 저장하고, Claude에게 해당 항목을 잊으라고 해 삭제한다. 작업 공간별로 적용된다. 대화 간 유지할 정보는 메모리에, 현재 대화에만 필요한 정보는 할 일 목록에 둔다.

대화 관리와 권한 모드

문맥 창에 가까워지면 하네스가 오래된 대화를 요약해 작업을 이어가는 압축(compaction)을 자동 실행할 수 있다. /compact로 직접 실행할 수도 있다. 오래된 도구 기록은 버리고 요약을 새 대화 접두부로 삼는다. /compact 뒤에 지시를 덧붙여 보존할 내용을 지정할 수 있다. 예를 들어 인증 모듈의 변경 사항에 집중하도록 요청한다. 압축 전에는 PreCompact가 실행되고, 뒤에는 PostCompact가 실행된다. 후자는 auto 또는 manual 일치 조건으로 실행 원인을 구분한다.

권한 모드는 도구 실행 전에 사용자에게 얼마나 자주 묻는지를 바꾼다.

  • Default: 호출마다 ask·allow·deny를 평가한다. 세션 시작 기본값이다.
  • Auto-Accept Edits: 편집은 승인 없이 진행하지만 다른 도구는 기존 규칙을 따른다. Shift+Tab 한 번 또는 /permissions로 진입한다.
  • Plan Mode: 읽기 전용이며 편집과 셸 명령을 허용하지 않는다. Shift+Tab 두 번째 순환, --permission-mode plan, permissions.defaultMode: "plan"으로 진입한다.
  • Bypass Permissions: 모든 권한 규칙을 우회한다. 샌드박스 환경에서만 사용하며 --dangerously-skip-permissions를 명시해야 한다.

모드는 세션 상태이며 settings.json에 저장되지 않는다. defaultMode는 시작 모드만 정하고 Shift+Tab으로 세션 중 바꾼다.

CLI 아래쪽의 상태 표시줄에는 모델, 현재 작업 디렉터리(cwd), 문맥 사용량 등 세션 정보가 나온다. settings.json의 statusLine으로 설정할 수 있고, 외부 스크립트가 한 줄을 출력하도록 구성할 수 있다. 기본 렌더러는 모델·cwd·사용 토큰을 보여준다. 사용자 정의 형식은 statusLine: { type: "command", command: "<path-to-script>" }이며 스크립트는 stdin으로 문맥 JSON을 받고 stdout으로 한 줄 상태 문자열을 출력한다. statusline-setup 하위 에이전트가 settings.json을 수정해 설정을 도울 수 있다.

Bash 도구에 run_in_background: true를 지정하면 장시간 셸 명령을 백그라운드로 돌릴 수 있다. 하네스가 셸 ID를 부여하고 완료 알림을 제공한다. BashOutput으로 출력을 확인하고 KillShell로 취소한다. 개발 서버, 감시 프로세스, 긴 테스트에 쓸 수 있다.

플러그인과 비대화형 실행

플러그인은 스킬, 하위 에이전트, 슬래시 명령, 훅, 출력 스타일, MCP 서버 정의를 하나로 묶어 배포하는 버전 관리 가능한 패키지다. 팀과 공개 마켓플레이스에서 Claude Code 확장을 공유하는 표준 방식이다. 사용자 범위 ~/.claude/plugins/ 또는 프로젝트 범위 <project>/.claude/plugins/에 설치한다. /plugin으로 설치된 플러그인과 설정된 마켓플레이스를 찾아보고, 설치·활성화·비활성화·업데이트를 관리한다. 플러그인에 포함된 항목은 plugin:name처럼 플러그인 이름을 붙여 표시하며, 프로젝트별 버전을 고정할 수 있다. 플러그인 코드는 하네스 안에서 실행되므로 제3자 플러그인도 공급망의 다른 의존성처럼 취급해야 한다. 예를 들어 팀 플러그인 하나에 보안 검토 스킬, 비밀을 검사하는 PreToolUse 훅, 사용자 정의 상태 표시줄, 내부 API용 MCP 서버를 함께 담아 /plugin으로 설치할 수 있다.

Claude Code는 TTY 없이 한 번 실행하는 CLI 비대화형 모드를 제공한다. GitHub Action, 예약 작업, pre-commit 통합이 이를 활용할 수 있다. 대화형 CLI와 같은 설정·훅·권한 규칙을 쓴다. claude -p "<prompt>" 또는 --print로 실행하며 최종 응답은 stdout에 출력한다. 프롬프트는 인수 문자열, stdin(예: echo "..." | claude -p), 파일에서 가져올 수 있다. 브라우저 OAuth 없이 인증하려면 settings.json의 apiKeyHelper 또는 환경 변수 ANTHROPIC_API_KEY를 쓴다. 출력은 기본 텍스트인 --output-format text, 또는 기계 판독용 json·stream-json 형식으로 지정한다. 이전 대화를 이어가려면 --resume <id>나 --continue를 쓴다. 프로젝트 settings.json에서 --permission-mode와 명시적인 allow·deny 규칙을 함께 설정한다. 완전히 샌드박스된 CI 실행기 밖에서는 --dangerously-skip-permissions를 피한다. CI 검토, 코드 수정 봇, 스크립트 리팩터링, 예약 감사에 활용할 수 있다.

설정 참고

`settings.json` 우선순위

설정은 여러 위치에서 읽어 병합한다. 아래 순서는 낮은 우선순위부터 높은 우선순위 순이다. 단일 값은 높은 계층이 낮은 계층을 덮어쓰고, 배열은 대체로 이어 붙인다. 엔터프라이즈 관리 설정은 최종 정책 기준이며 하위 설정이나 CLI 플래그로 완화할 수 없다.

  • 가장 낮음: ~/.claude/settings.json — 모든 프로젝트에 적용되는 사용자 개인 기본값.
  • <project>/.claude/settings.json — 버전 관리에 포함하는 프로젝트 팀 기본값.
  • <project>/.claude/settings.local.json — gitignore 처리하는 프로젝트별 개인 재정의.
  • CLI 플래그 — 한 번의 실행에만 적용하는 재정의.
  • 가장 높음: 엔터프라이즈 관리 설정 — 조직 전체 정책이며 낮은 계층과 CLI 플래그가 완화할 수 없다.

관리 설정 파일은 macOS에서 /Library/Application Support/ClaudeCode/managed-settings.json, Linux와 WSL에서 /etc/claude-code/managed-settings.json, Windows에서 C:\\Program Files\\ClaudeCode\\managed-settings.json이다. 각 플랫폼은 managed-settings.d/*.json 추가 파일 디렉터리를 지원한다. 파일을 알파벳순으로 병합하며 뒤의 파일이 앞의 파일을 덮어쓰고 배열은 연결한다. macOS의 MDM plist 도메인 com.anthropic.claudecode, Windows의 레지스트리 키 HKLM\\SOFTWARE\\Policies\\ClaudeCode로도 관리자가 설정할 수 있다.

주요 최상위 설정 키는 다음과 같다.

  • model(문자열): 기본 모델 별칭. 예: "claude-sonnet-4-6", "claude-opus-4-7".
  • permissions(객체): allow, deny, ask, defaultMode, additionalDirectories.
  • hooks(객체): 이벤트별 훅 설정.
  • env(객체): 도구에 전달할 환경 변수.
  • apiKeyHelper(문자열): 비대화형 인증을 위해 API 키를 출력하는 스크립트 경로.
  • mcpServers(객체): MCP 서버 정의.
  • includeCoAuthoredBy(불리언): git 커밋에 Co-Authored-By: Claude 줄을 붙일지 지정한다.
  • statusLine(객체): 상태 표시줄 렌더러.
  • outputStyle(문자열): 활성 출력 스타일 이름.
  • theme(문자열): CLI 색상 테마. 예: "dark", "light", "dark-daltonized", "light-daltonized".
  • cleanupPeriodDays(숫자): 로컬 대화 기록 보존 기간. 기준값은 30일이다.
  • autoUpdates(불리언): CLI 시작 시 업데이트를 확인하고 적용할지 지정한다.
  • forceLoginMethod(문자열): 인증을 oauth 또는 apikey로 고정한다. 공유 환경에서 쓸 수 있다.
  • enableAllProjectMcpServers(불리언): 프로젝트가 정의한 MCP 서버를 자동 승인한다.
  • enabledMcpjsonServers(문자열 배열): 프로젝트 MCP 서버의 명시적 허용 목록.
  • disabledMcpjsonServers(문자열 배열): 프로젝트 MCP 서버의 명시적 거부 목록.
  • disableBypassPermissionsMode(문자열): "disable"로 설정하면 CLI 플래그와 관계없이 bypassPermissions 모드를 금지한다. 주로 관리형 엔터프라이즈 설정에서 쓴다.

관측성은 최상위 설정 키가 아니라 환경 변수로 설정한다. CLAUDE_CODE_ENABLE_TELEMETRY, OTEL_*, 감사 관련 변수는 뒤에서 설명한다. settings.json에는 enableAuditLog 키가 없다. 지속적인 감사 기록은 OpenTelemetry 내보내기나 자체 파이프라인에 구조화된 기록을 쓰는 PostToolUse 훅으로 만든다.

permissions 블록의 하위 키는 allow(자동 승인 패턴 배열), deny(프롬프트 없이 거부하는 패턴 배열), ask(allow와 일치해도 항상 확인하는 패턴 배열), defaultMode(세션 시작 모드), additionalDirectories(프로젝트 루트 밖에서 읽고 쓸 수 있는 추가 디렉터리 배열)다. defaultMode의 값은 "default", "acceptEdits", "plan", "bypassPermissions"다. 패턴은 도구별 문법을 따른다. Bash는 명령 접두어(예: "Bash(npm test*)"), Read·Edit·Write는 glob 경로(예: "Read(~/Documents/**)")를 쓴다. 평가는 deny → ask → allow 순이며 가장 엄격한 일치 규칙을 적용한다.

env에 둔 환경 변수는 하네스가 실행하는 모든 도구에 전달된다. 설정 예시는 다음과 같다.

json
{
 "env": {
 "BASH_DEFAULT_TIMEOUT_MS": "180000",
 "BASH_MAX_TIMEOUT_MS": "600000",
 "HTTP_PROXY": "http://proxy.example.com:3128",
 "ANTHROPIC_LOG_LEVEL": "info"
 }
}

하네스 수준에서 인식하는 변수에는 ANTHROPIC_MODEL, ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, CLAUDE_CODE_ENABLE_TELEMETRY, CLAUDE_CODE_DISABLE_THINKING, CLAUDE_CODE_DISABLE_AUTO_MEMORY, CLAUDE_CODE_SKIP_PROMPT_HISTORY, CLAUDE_CODE_EFFORT_LEVEL, CLAUDE_CODE_MAX_OUTPUT_TOKENS, BASH_DEFAULT_TIMEOUT_MS, BASH_MAX_TIMEOUT_MS, DISABLE_AUTOUPDATER, MCP_TIMEOUT, MAX_MCP_OUTPUT_TOKENS가 있다. OpenTelemetry 표준 내보내기 변수는 OTEL_LOGS_EXPORTER, OTEL_METRICS_EXPORTER이며, OTEL_LOG_TOOL_DETAILS를 쓰면 file_path, full_command 같은 확장 도구 span 속성을 기록한다. BASH_DEFAULT_TIMEOUT_MS는 Bash 도구의 명령별 기본 시간 제한을 덮어쓴다(기준 2분). BASH_MAX_TIMEOUT_MS는 Claude가 요청할 수 있는 시간을 제한한다(기준 10분). 둘을 같은 값으로 설정하면 모든 Bash 호출의 제한 시간을 고정한다.

사용자 디렉터리와 `CLAUDE.md`

~/.claude/는 Claude Code의 사용자별 상태 파일 위치다.

text
~/.claude/
 settings.json # 사용자 수준 설정
 CLAUDE.md # 모든 세션에 불러오는 사용자 지침
 keybindings.json # 사용자 키 바인딩 재정의
 agents/ # 사용자 하위 에이전트 정의
 commands/ # 사용자 슬래시 명령
 skills/ # 사용자 스킬
 output-styles/ # 사용자 출력 스타일
 hooks/ # settings.json에서 참조하는 훅 스크립트
 projects/<workspace>/ # 프로젝트별 상태(기록, 메모리)
 memory/ # 자동 메모리 파일
 sessions/ # 저장된 세션 기록
 logs/ # 활성화한 경우 로컬 로그

프로젝트 범위의 <project>/.claude/...에도 대응 항목을 둘 수 있지만 projects/와 logs/는 제외된다. CLAUDE.md는 세션 시작 때 읽는다. 시스템 프롬프트 일부가 아니라 시스템 프롬프트 뒤에 사용자 메시지로 전달되며, 세 계층의 내용을 순서대로 이어 붙인다.

  • 사용자: ~/.claude/CLAUDE.md — 모든 프로젝트의 모든 세션에 적용할 개인 선호.
  • 프로젝트: <project>/CLAUDE.md — 프로젝트의 세션에 적용할 코드베이스 관례, 빌드 명령, 디렉터리 구조.
  • 하위 디렉터리: <project>/path/CLAUDE.md — 현재 작업 디렉터리가 해당 경로 아래일 때 적용할 하위 시스템 규칙.

CLAUDE.md는 대화 시작 때 Claude에게 지침을 주지만 이를 강제하지는 않는다. 강제하려면 permissions와 hooks를 쓴다. 사용자 키 바인딩 재정의 파일은 ~/.claude/keybindings.json이다. 동작 이름을 키 조합에 연결하는 JSON 객체이며, 기본값과 다른 항목만 기록하면 된다.

훅과 슬래시 명령

훅은 세션 생명주기의 정해진 시점에 하네스가 실행하는 사용자 제공 셸 명령이다. 도구 호출을 차단하고, 프롬프트를 바꾸고, 이벤트를 기록하거나 외부 자동화를 시작할 수 있어 주요 강제 수단으로 쓰인다.

  • PreToolUse: 모든 도구 실행 전. stdin에 도구 이름과 입력 JSON을 받는다. 차단할 수 있으며 종료 코드 2로 거부한다. 가드레일, 명령 검사, 비밀 탐지에 쓴다.
  • PostToolUse: 모든 도구 실행 후. 도구 이름과 결과 JSON을 받으며 차단하지 않는다. 감사 기록, 포매터, 파일 작성 후 lint에 쓴다.
  • Notification: Claude가 시스템 알림을 보낼 때 알림 문구를 받는다. 데스크톱 알림이나 Slack 알림에 쓴다.
  • UserPromptSubmit: 사용자가 프롬프트를 제출할 때 원문을 받는다. 차단하거나 프롬프트를 수정할 수 있다. 문맥 주입, 비밀 제거, 전역 규칙 추가에 쓴다.
  • Stop: 기본 에이전트가 응답을 마칠 때 세션 요약을 받는다. 완료 알림음, 배포, 테스트에 쓴다.
  • SubagentStop: 하위 에이전트가 반환할 때 요약을 받는다. 하위 에이전트별 감사를 할 수 있다.
  • PreCompact: 대화 압축 전 상태를 받는다. 기록 저장과 체크포인트 표시에 쓴다.
  • PostCompact: 압축 후 요약을 받는다. auto 또는 manual 일치 조건으로 실행 원인을 필터링할 수 있다. 초기 문맥·프로젝트 규칙을 다시 넣고 할 일 상태를 갱신하는 데 쓴다.
  • SessionStart: 세션 시작 시 메타데이터를 받는다. 임시 디렉터리를 만들거나 환경을 기록할 수 있다.
  • SessionEnd: 세션 종료 시 요약을 받는다. 정리와 기록 보관에 쓴다.

위 목록은 이 스냅샷 날짜의 문서에 나온 이벤트다. 새 이벤트가 릴리스 사이에 추가될 수 있으므로 자동화를 새로 연결하기 전 공식 훅 참고서에서 최신 목록을 확인한다. 훅 이벤트에는 일치 조건 목록을 지정하고, 각 조건에 실행 명령을 둔다. 일치 문법은 이벤트별로 다르다. 예를 들어 PreToolUse는 도구 이름과 선택적 입력 패턴으로 고른다.

json
{
 "hooks": {
 "PreToolUse": [
 {
 "matcher": "Bash",
 "hooks": [{ "type": "command", "command": "~/.claude/hooks/guard-bash.sh" }]
 },
 {
 "matcher": "Write",
 "hooks": [{ "type": "command", "command": "~/.claude/hooks/scan-secrets.sh" }]
 }
 ],
 "PostToolUse": [
 {
 "matcher": "Edit|Write",
 "hooks": [{ "type": "command", "command": "~/.claude/hooks/format-on-write.sh" }]
 }
 ]
 }
}

종료 코드 0은 작업을 허용하고 정상 진행, 1은 허용하되 Claude에 경고를 표시, 2는 작업을 거부하고 도구 호출을 중단한다. 그 밖의 값은 실패로 처리하며 동작은 이벤트에 따라 다르다. rm -rf를 막는 PreToolUse, prettier를 실행하는 PostToolUse, 전역 규칙을 앞에 붙이는 UserPromptSubmit 예시는 하네스 및 환경 안내서에 있다.

슬래시 명령은 /permissions, /model처럼 하네스 상태에 접근하거나 .claude/commands/에 저장한 프롬프트 템플릿을 실행하는 단축 명령이다. CLI 기본 명령은 다음과 같다.

  • 세션 관리: /clear는 작업 디렉터리와 설정을 유지하고 대화를 초기화한다. /compact [instruction]은 보존할 내용에 선택적으로 무게를 둬 대화를 압축한다. /resume은 이전 세션을 재개하며 데스크톱과 CLI에서 쓸 수 있다. /continue는 가장 최근 세션을 잇는다. /cost는 토큰 사용량과 대략적인 세션 비용을, /status는 현재 모델·모드·세션 정보를 보여준다. /help는 사용 가능한 슬래시 명령을 나열한다.
  • 설정: /config는 모델·출력 스타일·테마와 기타 최상위 설정 화면을 연다. /model은 활성 모델 별칭을 바꾼다. /permissions는 권한 규칙을 확인·편집하고 모드를 전환한다. /hooks는 현재 훅 설정을 확인한다. /add-dir <path>는 현재 세션의 additionalDirectories에 디렉터리를 추가한다. /memory는 자동 메모리를 확인·편집한다. 프롬프트 입력의 # 접두어로도 메모리를 추가할 수 있다.
  • 도구와 확장: /mcp는 MCP 서버와 연결 상태, /agents는 기본·사용자 정의 하위 에이전트, /skills는 설치된 스킬과 세션에서의 사용 가능 여부를 보여준다. /plugin은 플러그인을 찾아 설치·활성화·비활성화한다. /ide는 실행 중인 CLI를 감지된 VS Code 또는 JetBrains IDE에 연결해 선택 영역과 diff를 주고받는다. /init은 프로젝트 CLAUDE.md를 만든다. /install-github-app은 현재 저장소에 GitHub App을 설치한다. /login은 재인증하고 /logout은 로그아웃한다.
  • 진단: /doctor는 인증·네트워크·설치 프로그램 무결성을 검사한다. /bug는 CLI 버그를 신고한다. /release-notes는 설치 버전의 릴리스 노트를 보여준다. /terminal-setup은 셸 통합(키 바인딩, 터미널 안내)을 설치하거나 갱신한다. /migrate-installer는 네이티브 설치와 npm 설치 사이를 이동한다. /upgrade는 상위 요금제로 바꾸는 페이지를 연다.
  • 편집 및 생산성: /vim은 프롬프트 입력에서 vim 키 바인딩을 켠다. /fast는 지연 시간을 줄인 Claude Opus 빠른 모드를 켜거나 끈다. Opus 4.6과 Opus 4.7에서 사용할 수 있고 더 작은 모델로 대체되지 않는다. /pr-comments는 GitHub PR 댓글을 가져와 검토한다. /review는 현재 브랜치의 대기 중인 변경을 검토한다. /export는 현재 대화를 Markdown으로 내보낸다.

사용자 정의 명령은 프로젝트의 .claude/commands/<name>.md 또는 사용자 범위 ~/.claude/commands/에 둔다. Markdown 본문이 프롬프트 템플릿이며, 선택적 YAML frontmatter에서 설명·허용 도구·기본 모델을 정한다. 예시는 다음과 같다.

markdown
---
description: Run a security review of the staging branch
allowed-tools: Read, Grep, Glob, Bash, WebFetch
model: claude-opus-4-7
---
Audit the diff between `main` and `HEAD` for security issues. Focus on:
- Authentication / authorization changes
- Input handling boundaries
- Secrets in logs
- New dependencies
Report findings as a punch list.

이렇게 정의한 명령은 /<name>으로 호출하며 세션 시작 때 하네스가 불러온다.

MCP 연동

Claude Code는 MCP 클라이언트다. 별도로 작성한 MCP 서버에 연결해 도구·리소스·프롬프트를 기본 기능처럼 모델에 제공한다. 아래 내용은 클라이언트 설정만 다루며 개별 MCP 서버를 목록화하지 않는다.

서버 정의 위치는 ~/.claude/settings.json의 mcpServers(모든 프로젝트에 적용하는 사용자 서버), <project>/.claude/settings.json의 mcpServers(버전 관리에 포함하는 프로젝트 서버), <project>/.claude/settings.local.json(개발자별 재정의), 프로젝트의 <project>/.mcp.json(프로젝트 배포 서버, enabledMcpjsonServers·disabledMcpjsonServers로 제어), 세션 전용 --mcp-config <file>이다.

전송 방식은 stdio(로컬 바이너리나 스크립트, 대부분 서버의 기본값이며 command와 선택적 args, env로 설정), http(별칭 streamable-http; 원격 서버의 스트리밍 가능한 응답에 쓰며 원격 서버에 권장, url과 선택적 headers로 설정), sse(Server-Sent Events 방식의 원격 서버, 폐기 예정이며 기존 설정은 계속 작동하지만 새 서버에는 http를 사용, url과 선택적 headers로 설정)다. WebSocket은 지원하지 않는다. 원격에는 http(별칭 streamable-http), 로컬 프로세스에는 stdio를 쓴다.

json
{
 "mcpServers": {
 "filesystem": {
 "type": "stdio",
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
 },
 "company-api": {
 "type": "streamable-http",
 "url": "https://mcp.example.com/v1",
 "headers": {
 "Authorization": "Bearer ${COMPANY_MCP_TOKEN}"
 }
 }
 }
}

${VAR} 형식의 환경 변수는 연결할 때 하네스 env 블록에서 값을 가져온다. 권한 시스템에서 MCP 도구 이름은 mcp__<server>__<tool>이다. 단일 도구를 허용하려면 "allow": ["mcp__filesystem__read_file"], 서버의 모든 도구를 허용하려면 "allow": ["mcp__filesystem"]를 쓴다. 같은 와일드카드를 deny와 ask에도 쓸 수 있다. enableAllProjectMcpServers, enabledMcpjsonServers, disabledMcpjsonServers는 프로젝트 MCP 서버 연결 시도 여부를 결정하며 도구별 권한 규칙보다 앞단의 별도 제어 계층이다.

/mcp는 설정한 서버별 연결 상태(connected / connecting / failed), 제공 도구·리소스·프롬프트 수를 보여준다. 세션 시작 때 연결하지 못한 서버는 백그라운드에서 재시도하며, 실패 알림은 사용자가 요청할 때만 표시한다.

키 바인딩

아래는 CLI와 IDE 채널의 기본 키 조합이다. CLI는 ~/.claude/keybindings.json, IDE 확장은 각 IDE의 일반 키 바인딩 설정에서 재정의한다.

  • CLI 프롬프트 입력: Enter는 프롬프트 제출, Shift+Enter는 줄바꿈, Up/Down은 이전·다음 프롬프트 탐색, Ctrl+R은 프롬프트 기록 검색, Tab은 파일 경로·슬래시 명령·@ 참조 자동 완성이다.
  • Shift+Tab은 기본 → 편집 자동 수락 → 계획 모드 → 기본 순으로 권한 모드를 바꾼다. Esc는 현재 모델 응답을 중단하고, Esc Esc는 이전 턴으로 이동한다. Ctrl+C는 현재 작업을 취소하며 두 번 누르면 종료한다. Ctrl+D는 CLI를 종료한다.
  • @<file>은 자동 완성으로 파일 참조를 첨부하고 !<command>는 모델을 부르지 않고 셸 명령을 실행하는 Bash 모드다. #<text>는 메모리에 빠르게 추가하며 /<command>는 슬래시 명령을 실행한다.
  • VS Code와 JetBrains 확장은 Claude Code 패널과 편집기 키 바인딩을 제공한다. 기본값은 조금씩 다르다. 패널 전환은 macOS VS Code에서 Cmd+Esc, Windows/Linux에서 Ctrl+Esc; JetBrains는 설정 가능한 도구 창 단축키를 쓴다. 현재 선택을 Claude에 보내는 동작은 두 IDE 모두 마우스 오른쪽 버튼 메뉴, 인라인 편집 승인과 거부는 diff 패널에서 각각 Enter와 Esc다. 활성 프롬프트 입력란은 패널별 입력 영역을 쓴다. 두 확장은 CLI와 같은 settings.json 계층을 읽으므로 permissions, hooks, mcpServers가 공통 적용된다.
  • 데스크톱 앱은 운영체제 기본 단축키를 쓴다. 새 프로젝트는 Cmd/Ctrl+N, 설정은 Cmd/Ctrl+, 등이며 세션 입력은 CLI 프롬프트 키 바인딩을 따른다.

최근 추가와 폐기 항목

최근 3개월(2026-05로 끝나는 이동 기간)의 주요 추가 사항은 다음과 같다. 항목은 문서나 발표로 연결되며 8주가 지나면 다음 갱신 때 목록에서 빠진다.

  • 2026-05 하위 에이전트: Task 도구의 worktree 격리(isolation: "worktree").
  • 2026-05 스킬: /skills로 불러오는 플러그인 배포형 스킬 팩.
  • 2026-05 훅: 세션 종료 때 보관·감사하는 SessionEnd 이벤트. 기존 SessionStart, PreCompact, PostCompact, Stop에 추가됐다.
  • 2026-05 CLI: Opus 4.6과 4.7에서 더 작은 모델로 대체하지 않고 지연 시간을 낮추는 /fast 전환 기능.
  • 2026-05 모델: 계획 모드 추론 기본값으로 Claude Opus 4.7(claude-opus-4-7) 추가.
  • 2026-05 MCP: 원격 전송 기본 방식으로 streamable-http 권장.
  • 2026-05 IDE: JetBrains 플러그인의 네이티브 선택 영역 연결.
  • 2026-05 웹: claude.ai/code의 대화 공유 링크.

문서나 릴리스 노트가 제거 예정으로 표시한 항목은 대체 방법과 함께 기록한다. 제거 날짜 이후 전체 갱신 주기 한 번 동안 이 목록에 둔다.

  • MCP의 오래된 Server-Sent Events 전송 방식 sse는 폐기 예정이다. streamable-http(별칭 http)를 대체 방식으로 쓴다. 기존 sse 설정은 한 릴리스 주기 동안 계속 작동하지만 새 MCP 서버에는 streamable-http를 써야 한다.
  • <project>/.mcp.json의 예전 자동 신뢰 동작은 명시적 허용 목록인 enabledMcpjsonServers로 바뀌었다. 기존 동작은 더 이상 기본값이 아니다.
  • 전용 명령 /output_style과 /output-style은 설정 인터페이스의 “Output style” 항목을 포함한 /config로 대체됐다. settings.json의 outputStyle 키는 계속 사용할 수 있다.
  • 훅 배열에서 단일 문자열 command를 쓰는 축약형 대신 { "type": "command", "command": "..." } 객체를 권장한다. 현재 릴리스에서는 두 형식 모두 허용된다.

현재 별칭 없이 완전히 제거된 항목은 여기 나열하지 않는다. 전체 삭제 목록은 상위 변경 기록을 확인한다.

자주 묻는 질문

2026년 현재 어떤 채널에서 Claude Code를 쓸 수 있나? CLI, VS Code 확장, JetBrains 플러그인, macOS·Windows 데스크톱 앱, claude.ai/code 웹, TypeScript·Python용 내장 Claude Agent SDK, GitHub Action, GitHub App에서 사용할 수 있다. CLI가 기준 채널이고 다른 채널은 도구 일부를 제공한다. 로컬 파일 시스템에 접근하지 않는 채널은 웹뿐이다.

하위 에이전트·스킬·슬래시 명령은 어떻게 다른가? 슬래시 명령은 /<name>으로 호출하는 프롬프트 템플릿이다. 스킬은 지침과 선택적 지원 파일을 묶어 Skill 도구로 호출하며 도메인 로직과 매개변수 입력을 담을 수 있다. 하위 에이전트는 Task 도구로 시작하는 별도 Claude 세션으로, 자체 문맥 창이 있다. 문맥 격리나 병렬 처리가 중요할 때 하위 에이전트를 쓴다.

도구 실행 전에 작동하고 호출을 차단할 수 있는 훅은 무엇인가? PreToolUse가 모든 도구 실행 전에 작동하며 stdin으로 도구 이름과 입력을 받는다. 종료 코드 2는 호출을 거부하고, 0은 허용하며, 1은 Claude에 경고를 보여주면서 허용한다. 위험한 Bash 패턴을 막거나 Write 내용을 비밀 정보와 대조하는 가드레일에 권장된다.

설정은 어디서 읽으며 어느 파일이 우선하나? 사용자 ~/.claude/settings.json, 프로젝트 <project>/.claude/settings.json, 프로젝트 <project>/.claude/settings.local.json, CLI 플래그, 엔터프라이즈 관리 설정의 다섯 계층을 낮은 우선순위부터 병합한다. 단일 값은 높은 계층이 낮은 계층을 덮고 배열은 대체로 연결한다. 엔터프라이즈 계층은 CLI와 하위 계층으로 완화할 수 없는 정책 기준이다. 한 계층 안에서는 가장 엄격한 권한 규칙이 이기며 deny가 ask보다, ask가 allow보다 우선한다.

한 프로젝트에만 MCP 서버를 추가하려면 어떻게 하나? <project>/.claude/settings.json의 mcpServers에 정의하거나 <project>/.mcp.json에 추가하고 서버 이름을 enabledMcpjsonServers에 넣는다. 자격 증명은 headers에서 환경 변수를 참조하고 env나 래퍼 스크립트로 전달한다. 서버를 사용하기 전에 /mcp로 연결 상태를 확인한다.

/compact와 /clear의 차이는 무엇인가? /clear는 작업 디렉터리와 설정을 유지하고 대화를 비운다. /compact는 대화를 요약해 이어가며 오래된 도구 기록은 버리지만 대화의 흐름은 보존한다. 문맥 창이 부족하지만 작업이 끝나지 않았으면 /compact, 새 작업을 시작하려면 /clear를 쓴다.

Claude가 파일을 쓴 뒤 항상 훅을 실행하려면? "Write|Edit" 일치 조건의 PostToolUse 훅을 등록한다. 스크립트는 stdin으로 도구 이름과 결과 JSON을 받는다. 결과의 tool_input.file_path 경로를 이용해 포매팅·lint·커밋을 할 수 있다. 예시는 하네스 및 환경 안내서에 있다.

Shift+Tab은 무엇을 하나? 기본(호출마다 확인), 편집 자동 수락(파일 편집은 확인 없이 진행하되 다른 도구는 규칙을 따름), 계획 모드(읽기 전용이며 편집·셸 사용 불가)를 순환한다. 현재 모드는 상태 표시줄에 나온다.

대화형 터미널 없이 CI에서 실행할 수 있나? 가능하다. CLI는 비대화형 플래그를 받고 stdin이나 파일에서 프롬프트를 읽으며, GitHub Action은 이를 PR 검토에 활용한다. 무인 환경에서 API 키를 인증할 때는 키를 디스크에 커밋하는 대신 apiKeyHelper가 시크릿 관리자에서 키를 가져오도록 설정한다.

세션에서 Claude Code가 하는 일을 확인하려면? /status는 모델과 모드, /cost는 토큰 사용량, /mcp는 MCP 연결 상태를 보여준다. 전체 대화 기록과 도구 호출을 보려면 CLAUDE_CODE_ENABLE_TELEMETRY=1과 OpenTelemetry 내보내기 변수 OTEL_LOGS_EXPORTER, OTEL_METRICS_EXPORTER를 설정한다. file_path, full_command 같은 확장 span 속성에는 OTEL_LOG_TOOL_DETAILS=1을 추가한다. 수집기 없이 필요할 때만 감사하려면 PostToolUse 훅에서 구조화된 이벤트를 자체 파이프라인에 기록한다.

참고 자료

공식 문서: Claude Code 문서 홈 · CLI 설치와 빠른 시작 · 설정 참고서 · 훅 참고서 · 슬래시 명령 참고서 · MCP 연동 · 하위 에이전트 · 스킬 · 계획 모드와 권한 모드

관련 글: Claude Code 시작하기: 로컬 AI 에이전트를 알아야 하는 이유 — 설치, 첫 세션, 초보자가 자주 겪는 문제. Claude Code 하네스와 환경 엔지니어링: 로컬 AI 에이전트가 실제로 작동하는 환경 설계 — 운영 설계, 권한 패턴, 훅 예시, 세 가지 참고 프로필. 코드 검토 체크리스트와 안티패턴 목록 — AI 지원 작업 흐름에서 나온 diff를 검토할 때 확인할 내용.

이 스냅샷은 게시 연도 중 필요에 따라 갱신한다. 마지막 검토: 2026-05.