Claude Code - 문서가 알려주지 않는 설정 가능한 모든 것 완벽 가이드

Claude Code 숨겨진 설정 완벽 가이드 — Tistory에서 확인하기

Claude Code - 문서가 알려주지 않는 설정 가능한 모든 것 완벽 가이드

Claude Code는 Anthropic이 제공하는 명령행 AI 코딩 어시스턴트입니다. 버전 2.1.87 기준으로, 공식 문서에 나오지 않은 숨겨진 설정이 상당수 존재합니다. 이 글에서는 개발자들이 실제로 활용할 수 있는 문서화되지 않은 설정들을 정리합니다.

Claude Code 설정 파일 위치

Claude Code는 두 가지 수준의 설정 파일을 지원합니다.

개인 전역 설정은 ~/.claude/settings.json에 저장하며, 모든 프로젝트에 적용됩니다. 프로젝트 설정은 .claude/settings.json에 저장하고 Git에 커밋하여 팀과 공유할 수 있습니다.

Skills는 개인인 경우 ~/.claude/skills//SKILL.md, 프로젝트인 경우 .claude/skills//SKILL.md에 위치합니다. Agents 역시 개인은 ~/.claude/agents/.md, 프로젝트는 .claude/agents/.md에 저장합니다. Hook 스크립트는 ~/.claude/hooks/에 두는 것이 관례이며, 실행하려면 chmod +x가 필요합니다.

Hook 시스템의 숨겨진 기능

공식 문서는 Hook이 stdin으로 JSON을 받고 exit code 2로 작업을 막는 흐름만 설명합니다. 그러나 실제로는 stdout의 이벤트별 JSON 필드로 Claude Code 동작을 실시간으로 변경할 수 있습니다.

PreToolUse에서 사용할 수 있는 숨겨진 필드

PreToolUse Hook에서는 도구 실행 전 입력을 다시 작성하는 updatedInput 필드를 사용할 수 있습니다. 예를 들어 git push 명령에 자동으로 --dry-run을 붙이도록 만들 수 있습니다.

{"hooks": {"PreToolUse": [{"matcher": "Bash","hooks": [{"type": "command","command": "~/.claude/hooks/dry-run-pushes.sh"}]}]}}

#!/bin/bashINPUT=$(jq -r '.tool_input.command' < /dev/stdin)if echo "$INPUT" | grep -q 'git push'; thenjq -n --arg cmd "$INPUT --dry-run" '{"updatedInput": {"command": $cmd}}'fi

permissionDecision 필드를 사용하면 사용자에게 묻지 않고 allow 또는 deny를 강제할 수 있습니다. permissionDecisionReason으로 결정 이유를 UI에 표시할 수도 있고, additionalContext로 대화 컨텍스트에 텍스트를 주입할 수도 있습니다.

SessionStart Hook의 숨겨진 기능

SessionStart Hook에서는 세션 시작 시 파일 감시와 Git 컨텍스트 주입을 동시에 할 수 있습니다.

{"hooks": {"SessionStart": [{"hooks": [{"type": "command","command": "~/.claude/hooks/session-context.sh","statusMessage": "Loading project context..."}]}]}}

#!/bin/bashBRANCH=$(git branch --show-current 2>/dev/null)CHANGES=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')jq -n \--arg branch "$BRANCH" \--arg changes "$CHANGES" \'{"watchPaths": ["package.json", ".env", "tsconfig.json"], "additionalContext": "Current branch: \($branch). Uncommitted changes: \($changes) files."}'

문서에 없는 Hook 설정 필드 세 가지

문서화된 Hook 필드는 type, command, matcher, timeout, if, statusMessage뿐이지만, 소스 코드 파서는 세 개의 추가 필드를 지원합니다.

once: true는 Hook을 정확히 한 번만 실행한 뒤 자동 제거합니다. 첫 세션에서만 .env 파일을 생성하고 이후에는 실행하지 않는 흐름을 만들 수 있습니다.

async: true는 Hook을 백그라운드에서 실행하여 Claude의 진행을 막지 않습니다. 모든 Bash 명령을 감사 로그 파일에 기록하면서 세션 지연을 추가하지 않는 데 쓸 수 있습니다.

asyncRewake: true는 정상 경로에서는 async처럼 백그라운드로 실행하지만, exit code 2로 종료되면 모델을 다시 깨워 작업을 차단합니다. Claude가 작성한 파일에서 비밀번호나 API 키 패턴을 검사하고 발견 시 차단하는 안전망을 만들 수 있습니다.

{"hooks": {"PostToolUse": [{"matcher": "Write|Edit","hooks": [{"type": "command","command": "~/.claude/hooks/scan-secrets.sh","asyncRewake": true,"statusMessage": "Scanning for secrets..."}]}]}}

Skill frontmatter의 숨겨진 여섯 가지 필드

공식 문서에는 name, description, allowed-tools, argument-hint, when_to_use, context만 나와 있습니다. 그러나 실제 파서는 추가 여섯 가지 필드를 인식합니다.

model 필드로 Skill 실행 모델을 바꿀 수 있습니다. 빠른 저렴한 작업에는 haiku, 복잡한 분석에는 opus를 지정할 수 있습니다.

---name: quick-lintdescription: Fast lint check using the cheapest modelmodel: haikueffort: lowallowed-tools: Bash, Readargument-hint: "[file]"---

effort는 모델이 얼마나 깊게 생각할지를 조절하며 low, medium, high, max 값을 지원합니다. 내부적으로 응답별 추론 깊이를 제어하는 effort 시스템에 매핑됩니다.

hooks 필드는 Skill이 활성화될 때만 등록되고 완료되면 해제되는 스코프 지정 Hook을 정의합니다. TypeScript 파일을 쓸 때마다 동기적으로 타입 체크하고 백그라운드에서 lint를 실행하는 식으로 활용할 수 있습니다.

agent 필드로 Skill 실행을 특정 Agent에 위임할 수 있습니다. disable-model-invocation: true를 함께 설정하면 자동 호출을 막고 명시적인 /skill-name 호출로만 실행되게 할 수 있습니다.

shell 필드로 실행에 사용할 셸을 지정할 수 있습니다.

Agent frontmatter의 숨겨진 기능

.claude/agents/의 사용자 정의 Agent도 문서에 없는 frontmatter 필드를 지원합니다.

color는 UI 색상을 red, orange, yellow, green, blue, purple, pink, gray 중 하나로 설정합니다. 여러 Agent가 실행될 때 시각적으로 구분하는 데 도움이 됩니다.

memory는 Agent에 호출 간 지속 메모리를 부여합니다. user는 모든 프로젝트에 걸쳐 전역으로 유지되고, project는 프로젝트별로 유지되며, local은 Git에서 제외되는 비공개 프로젝트별 메모리입니다.

omitClaudeMd: true는 CLAUDE.md 지시 계층 로딩을 건너뛰며, 프로젝트 관습 대신 업계 기준으로 보는 새로운 시각의 리뷰어에 적합합니다.

criticalSystemReminder_EXPERIMENTAL은 짧은 메시지를 매 턴마다 시스템 리마인더로 다시 주입합니다. 필드 이름에 EXPERIMENTAL이 포함되어 있어 불안정할 수 있으므로 핵심 인프라보다는 보조 안전 리마인더 용도로만 쓰는 것이 좋습니다.

requiredMcpServers는 필요한 MCP 서버 이름 패턴을 나열하며, 해당 서버가 없으면 Agent가 나타나지 않게 합니다.

Auto Mode의 환경 분류기

settings.json의 autoMode 필드는 Anthropic 내부에서 YOLO Classifier라고 부르는 자동 승인 분류기를 설정합니다. allow 패턴은 자동 승인되고, soft_deny 패턴은 항상 확인을 요구합니다. environment 배열은 패턴이 아니라 분류기가 읽는 자연어 컨텍스트로, 프로젝트 환경을 설명하여 애매한 명령의 안전성 판단에 반영합니다.

{"autoMode": {"allow": ["Bash(npm test)","Bash(npm run )","Bash(git status)","Read","Grep","Glob"],"soft_deny": ["Bash(git push )","Bash(rm )","Write(.env)"],"environment": ["This is a local dev machine with no production database access","The test suite uses a dedicated test database"]}}

자동 메모리와 Dream 통합 시스템

settings.json에서 autoMemoryEnabled와 autoDreamEnabled를 켜면 Claude Code의 자기개선 시스템이 활성화됩니다.

autoMemoryEnabled는 각 대화 후 백그라운드 Agent가 세션에서 오래 유지할 가치가 있는 정보를 추출하여 사용자 선호, 코드베이스 패턴, 결정 사항을 표준 memory frontmatter 형식으로 저장합니다.

autoDreamEnabled는 24시간마다, 누적 세션이 5개 이상이면 백그라운드 Agent가 과거 세션 transcript를 검토하여 메모리를 통합합니다. 중복 병합, 모순 해결, 상대 날짜의 절대 날짜 변환, 오래된 항목 제거를 수행합니다.

두 설정을 함께 켜면 세션이 메모리를 만들고 Dream이 메모리를 통합하며, 통합된 메모리가 이후 세션에 반영되는 학습 루프가 만들어집니다. 몇 주 후에는 모델 재학습 없이 Claude Code가 사용자 선호, 관습, 공통 패턴을 기억하는 효과를 누릴 수 있습니다.

Magic Docs 형식

Magic Docs는 정규식 /^#\sMAGIC\s+DOC:\s(.+)$/im으로 감지됩니다. 반드시 H1 제목이어야 하고 대소문자를 구분하지 않습니다. 다음 줄에는 이탤릭 지시문을 둘 수 있으며, 업데이트 Agent가 집중할 범위를 제한합니다.

# MAGIC DOC: API Endpoint Reference_Only document public REST endpoints. Include method, path, request body, response schema, and auth requirements._## Endpoints (content auto-maintained by Claude Code)

지시문이 없으면 Agent는 모든 내용을 업데이트하려고 합니다. 지시문이 있으면 only track public endpoints나 focus on breaking changes 같은 범위를 따릅니다. 헤더를 삭제하면 추적이 자동으로 중단됩니다.

전체 권한 규칙 문법

공식 문서의 권한 문법 예시는 Bash(git )처럼 단순하지만, 실제 패턴 언어는 훨씬 폭넓습니다. Bash(npm:)는 레거시 콜론 프리픽스로 단어 경계를 나타내고, Read(src/*/.ts)는 확장자로 재귀 디렉터리를 매칭합니다. mcp__slack__post_message처럼 이중 밑줄 형식으로 특정 MCP 도구를 지정할 수 있습니다.

context: fork와 모델 선택의 캐시 영향

Skill에 context: fork를 설정하면 백그라운드 forked subagent로 실행됩니다. Fork는 CacheSafeParams라는 typed contract를 통해 부모의 prompt cache를 공유하며 캐시 적중률을 높이기 위해 byte-identical API request prefix를 생성합니다.

Forked Skill에 다른 모델을 지정하면 prefix가 달라져 캐시가 깨지고 전체 비용이 증가할 수 있습니다. 따라서 forked Skill에서는 model 필드를 생략하거나 model: inherit을 사용해야 캐시가 유지됩니다.

실전 활용 예시

지속 메모리와 스코프 Hook을 가진 코드 리뷰어 Agent를 설정하면, 코드베이스별 메모리를 읽고 과거 발견 패턴과 새 문제를 함께 리뷰한 후 발견 사항을 다시 메모리에 저장하는 흐름을 만들 수 있습니다. 여러 리뷰를 거치면 일반 리뷰어가 놓칠 수 있는 프로젝트별 반복 문제를 잡는 데 효과적입니다.

요약

Claude Code 2.1.87에는 문서화되지 않은 설정이 상당수 존재합니다. Hook 시스템의 once, async, asyncRewake 필드를 활용하면 1회 실행, 백그라운드 감사 로그, 비동기 보안 차단 흐름을 만들 수 있습니다. Skill과 Agent의 숨겨진 frontmatter 필드들을 이용하면 모델 선택, effort 제어, 지속 메모리, CLAUDE.md 생략 등을 세밀하게 제어할 수 있습니다. 자동 메모리와 Dream 통합 시스템을 함께 활성화하면 모델 재학습 없이 세션 경험에서 지속적으로 학습하는 개발 환경을 구축할 수 있습니다.

단, 문서화되지 않은 기능은 릴리스 사이에서 바뀔 수 있으므로, 프로덕션 환경에서는 안정적인 문서화된 기능 우선으로 사용하고, 문서화되지 않은 기능은 워크플로 최적화에 참고하는 수준으로 활용하는 것이 좋습니다.

---

📚 출처

• https://news.hada.io/topic?id=30030