I Read the Claude Code Source Code. Here's Everything You Can Configure That the Docs Don't Tell You.

명령 실행 도중 명령을 재작성하는 Hook 필드, 지속적인 에이전트 메모리 (agent memory), 평문 영어로 작성하는 자동 모드 (auto-mode) 규칙, 스스로 개선되는 드림 루프 (dream loops), 그리고 모든 예제는 즉시 복사하여 붙여넣을 수 있습니다.

Claude Code의 자동 모드 (auto-mode) 권한 시스템은 내부적으로 “YOLO Classifier”라고 불립니다. 이는 yoloClassifier.ts에 있는 실제 변수 이름입니다. 그리고 여러분은 자신의 환경에 대한 평문 영어 설명을 통해 이를 설정할 수 있습니다. 예를 들어 “이것은 스테이징 서버이므로 파괴적인 작업이 허용됩니다”와 같은 설명을 입력하면, 분류기 (classifier)가 이를 읽고 무엇을 자동으로 승인해도 안전할지 결정합니다. 이 내용은 어떤 문서에도 나와 있지 않습니다.

이는 공개적으로 배포된 npm 패키지로서 여러분의 node_modules에 바로 위치해 있는 Claude Code 소스 코드에 묻혀 있는 수십 가지의 문서화되지 않은 기능 중 하나입니다. 공식 문서는 기본 사항을 충분히 잘 다루고 있습니다. 하지만 소스 코드를 살펴보면 여러분이 구축할 수 있는 범위를 극적으로 확장해 주는 필드 (fields), 응답 형식 (response formats), 그리고 설정 (settings)들이 드러납니다. 여기에 있는 모든 것은 현재 바로 작동하며, 모든 예제는 여러분의 프로젝트에 있는 그대로 바로 사용할 수 있도록 설계되었습니다.

버전 관리에 관한 참고 사항: 이 발견 사항들은 @anthropic-ai/claude-code@2.1.87에서 도출되었습니다. 문서화되지 않은 기능은 릴리스 사이에 변경될 수 있으므로, 이를 오늘 사용 가능한 기능의 스냅샷으로 취급하십시오. 이름에 “EXPERIMENTAL”이 포함된 필드들은 Anthropic의 엔지니어들에 의해 명시적으로 불안정하다고 표시되어 있으며, 저는 이를 개별적으로 지적할 것입니다.

시작하기 전에

모든 항목이 어디에 위치하는지에 대한 빠른 참조:

Settings (설정): ~/.claude/settings.json (개인용) 또는 .claude/settings.json (프로젝트용, git을 통해 공유됨)

Skills (기술): ~/.claude/skills/<name>/SKILL.md (개인용) 또는 .claude/skills/<name>/SKILL.md (프로젝트용)

Agents (에이전트): ~/.claude/agents/<name>.md (개인용) 또는 .claude/agents/<name>.md (프로젝트용)

Hook scripts (Hook 스크립트): ~/.claude/hooks/는 좋은 관례입니다. 스크립트에 chmod +x를 실행하는 것을 잊지 마세요.

.claude/ 내의 프로젝트 수준 파일들

git에 커밋하여 팀원들과 공유할 수 있습니다. ~/.claude/에 있는 개인 파일들은 오직 당신만의 것입니다.

당신의 hooks는 응답할 수 있습니다, 하지만 아무도 그 방법을 알려주지 않았죠

이것이 문서에서 가장 큰 공백입니다. 공식 문서는 hooks가 stdin(표준 입력)을 통해 JSON을 받고, 종료 코드(exit code) 2가 작업을 차단한다는 점만 알려줍니다. 하지만 문서가 알려주지 않는 사실은, hooks가 stdout(표준 출력)을 통해 Claude Code의 동작을 실시간으로 수정할 수 있는 이벤트별 특정 필드를 포함한 JSON을 반환할 수 있다는 점입니다. 소스 코드를 통해 각 이벤트 유형이 정확히 무엇을 수용하는지 확인할 수 있습니다.

PreToolUse hooks는 다음을 반환할 수 있습니다:

updatedInput

• 도구가 실행되기 전에 도구의 입력을 재작성합니다. 실행 도중에 명령어를 수정할 수 있습니다.

permissionDecision

• 사용자에게 묻지 않고 "허용(allow)" 또는 "거부(deny)"를 강제합니다.

permissionDecisionReason

• 결정 이유를 설명합니다 (UI에 표시됨).

additionalContext

• 대화 컨텍스트(conversation context)에 텍스트를 주입합니다.

SessionStart hooks는 다음을 반환할 수 있습니다:

watchPaths

• FileChanged 이벤트를 트리거하는 자동 파일 감시(file watching)를 설정합니다.

initialUserMessage

• 세션의 첫 번째 사용자 메시지 앞에 내용을 추가합니다.

additionalContext

• 세션 전체 동안 유지되는 컨텍스트를 주입합니다.

PostToolUse hooks는 다음을 반환할 수 있습니다:

updatedMCPToolOutput

• MCP 도구 응답에서 Claude가 보는 내용을 수정합니다.

additionalContext

• 도구가 실행된 후 컨텍스트를 주입합니다.

PermissionRequest hooks는 다음을 반환할 수 있습니다:

decision

• updatedInput 또는 updatedPermissions를 사용하여 프로그래밍 방식으로 허용하거나 거부합니다.

이것은 매우 강력한 기능입니다. 다음은 Claude가 실행하기 전에 모든 git push 명령어에 자동으로 --dry-run을 추가하는 PreToolUse hook 예시입니다.

settings.json 파일에서:

{
"hooks": {
"PreToolUse": [{
...

그리고 ~/.claude/hooks/dry-run-pushes.sh에 있는 스크립트:

#!/bin/bash
INPUT=$(jq -r '.tool_input.command' < /dev/stdin)
if echo "$INPUT" | grep -q 'git push'; then
...

Claude는 git push origin main을 실행한다고 생각하지만, 당신의 hook은 실행 전에 이를 조용히 git push origin main --dry-run으로 재작성합니다. updatedInput 필드는 그 어떤 문서에도 나와 있지 않습니다.

다음은 설정 파일을 감시하고 모든 세션에 git 컨텍스트 (context)를 주입하는 SessionStart 훅 (hook) 예시입니다.

settings.json

:

{
"hooks": {
"SessionStart": [{
...

~/.claude/hooks/session-context.sh

:

#!/bin/bash
BRANCH=$(git branch --show-current 2>/dev/null)
CHANGES=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
...

이제 Claude Code는 사용자가 아무것도 입력하기 전에 package.json, .env, tsconfig의 변경 사항을 자동으로 감시하며, 사용자가 어떤 브랜치에 있는지와 커밋되지 않은 파일이 몇 개인지 파악합니다.

그리고 여기에는 프롬프트(prompt) 없이 읽기 전용 bash 명령어를 자동으로 승인하는 설정이 있습니다.

settings.json

:

{
"hooks": {
"PreToolUse": [{
...

~/.claude/hooks/auto-approve-readonly.sh

:

#!/bin/bash
CMD=$(jq -r '.tool_input.command' < /dev/stdin)
if echo "$CMD" | grep -qE '^(ls|cat|echo|pwd|whoami|date|git status|git log|git diff)'; then
...

기본적으로 셸 스크립트 (shell script)를 사용하여 자신만의 권한 분류기 (permission classifier)를 구축하고 있는 셈입니다. permissionDecision 필드는 그 어떤 문서에도 나와 있지 않습니다.

문서에서 언급하지 않은 세 가지 훅 필드

문서에 기록된 훅 필드는 type, command, matcher, timeout, if, statusMessage입니다. 소스 코드 파서 (parser)는 훅의 동작 방식을 근본적으로 바꾸는 세 가지 필드를 추가로 허용합니다.

once: true는 훅을 정확히 한 번만 실행한 후 자동으로 제거합니다. 첫 세션 설정에 완벽합니다:

{
"hooks": {
"SessionStart": [{
...

인라인 (inline)으로 작성하기에 충분히 간단합니다. .env가 존재하는지 확인하고, 없으면 템플릿을 복사한 뒤 다시는 실행되지 않습니다.

async: true는 Claude를 차단하지 않고 백그라운드 (background)에서 훅을 실행합니다. 실행 후 잊어버리는 (Fire and forget) 방식입니다:

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

이는 세션에 지연 시간 (latency)을 추가하지 않고 모든 bash 명령어를 감사 파일 (audit file)에 기록합니다.

asyncRewake: true

asyncRewake: true

은 영리한 설정입니다. async와 마찬가지로 백그라운드에서 실행되므로 정상적인 경로 (happy path)에서는 작업을 차단하지 않습니다. 하지만 종료 코드가 2번인 경우, 모델을 다시 깨우고(wake up) 해당 작업을 차단합니다. 모든 것이 정상일 때는 비차단 (non-blocking) 방식으로 작동하고, 문제가 발생했을 때만 차단 (blocking) 방식으로 작동합니다.

settings.json

:

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

~/.claude/hooks/scan-secrets.sh

:

#!/bin/bash
FILE=$(jq -r '.tool_input.file_path // .tool_response.filePath' < /dev/stdin)
if grep -qE '(password|secret|api_key)\s*=' "$FILE" 2>/dev/null; then
...

이 스크립트는 Claude가 작성하는 모든 파일을 스캔하여 하드코딩된 비밀 정보 (secrets)가 있는지 확인합니다. 만약 발견하면 작업을 차단하고 Claude에게 알립니다. 발견되지 않으면 이 스크립트가 실행되었는지조차 알 수 없습니다.

문서에 공개되지 않은 Skill 프론트매터 (frontmatter) 필드

공식 문서에는 name, description, allowed-tools, argument-hint, when_to_use, 그리고 context가 다뤄집니다. 하지만 소스 코드 내의 실제 프론트매터 파서 (parser)는 6개의 필드를 더 허용합니다.

model 필드는 해당 스킬을 실행할 모델을 재정의할 수 있게 해줍니다. 저렴하고 빠른 작업에는 Haiku를 사용하고, 복잡한 분석에는 Opus를 사용하세요:

---
name: quick-lint
description: 가장 저렴한 모델을 사용한 빠른 린트 (lint) 체크
...

이 설정은 적은 노력 (low effort)으로 Haiku에서 실행되므로 빠르고 저렴합니다. 심층적인 아키텍처 리뷰를 원한다면 model: opus와 effort: max를 사용해야 합니다.

effort는 모델이 얼마나 깊게 생각할지를 제어합니다. low, medium, high, 또는 max 값을 가집니다. 이는 응답당 추론 깊이 (reasoning depth)를 내부적으로 제어하는 동일한 노력 (effort) 시스템에 매핑됩니다.

hooks는 스킬이 활성화된 시점에 적용되는 범위 (scope)를 가진 훅 (hooks)을 정의합니다. 이들은 스킬이 실행될 때 등록되고, 완료될 때 등록 해제됩니다:

---
name: strict-typescript
description: 저장할 때마다 타입 체크를 수행하는 TypeScript 작성
...

~/.claude/hooks/typecheck-on-save.sh

:

#!/bin/bash
FILE=$(jq -r '.tool_input.file_path // .tool_response.filePath' < /dev/stdin)
[[ "$FILE" == *.ts ]] && npx tsc --noEmit 2>&1 || true

~/.claude/hooks/lint-on-save.sh

:

#!/bin/bash
FILE=$(jq -r '.tool_input.file_path // .tool_response.filePath' < /dev/stdin)
[[ "$FILE" == *.ts ]] && npx eslint --fix "$FILE" 2>&1 || true

이 스킬(skill)이 실행되는 동안, Claude가 작성하는 모든 TypeScript 파일은 동기적으로 타입 체크(type-checked)를 거치며 백그라운드에서 린트(linted) 작업이 수행됩니다. 스킬이 종료되면 해당 훅(hooks)들은 사라집니다. 스코핑(scoping)이 깔끔합니다.

agent

스킬을 커스텀 에이전트(custom agent)에게 위임합니다:

---
name: deep-review
description: Thorough security review delegated to the review agent
...

disable-model-invocation: true

자동 호출(auto-invocation)을 방지합니다. 오직 명시적인 /skill-name 명령만 작동합니다. 실수로 실행되어서는 안 되는 파괴적인 스킬(destructive skills)에 이 설정을 사용하세요.

shell: bash

실행에 사용할 셸(shell)을 지정합니다.

어떤 문서에서도 찾을 수 없는 에이전트 필드들

.claude/agents/에 있는 커스텀 에이전트들은 문서에 언급되지 않은 프론트매터(frontmatter) 필드들을 지원합니다.

color

UI 색상을 설정합니다: red, orange, yellow, green, blue, purple, pink, 또는 gray. 여러 에이전트가 실행 중일 때 시각적으로 에이전트를 구분하는 데 도움이 됩니다.

memory

가장 중요한 기능입니다. 에이전트에게 호출 간 지속되는 메모리(persistent memory)를 부여합니다:

user - 전역(global), 모든 프로젝트에 걸쳐 유지됨
project - 프로젝트별 유지
local - 프로젝트별 비공개 (gitignored)

이는 학습하는 에이전트를 구축할 수 있음을 의미합니다. 과거의 발견 사항을 추적하는 보안 리뷰어(security reviewer), 세션 전반에 걸쳐 사용자의 패턴을 기억하는 코드 리뷰어(code reviewer)를 만들 수 있습니다. 메모리는 자동 메모리 시스템(auto-memory system)과 동일한 프론트매터 형식을 사용합니다.

---
name: codebase-guide
description: Answer questions about the codebase, learning more with each session
...

몇 번의 세션이 지나면, 이 에이전트는 코드베이스(codebase)에 대한 지식 베이스(knowledge base)를 구축하며, grep 명령을 수행하기 전에 메모리로부터 답변을 시작합니다.

omitClaudeMd: true

CLAUDE.md 지침 계층(instruction hierarchy) 로딩을 건너뜁니다. 프로젝트의 컨벤션(conventions) 대신 업계 표준을 적용하는 "새로운 시각(fresh eyes)"을 가진 리뷰어에게 유용합니다.

---
name: fresh-eyes
description: Review code without project-specific biases
...

criticalSystemReminder_EXPERIMENTAL

이는 매 턴(turn)마다 시스템 리마인더(system reminder)로서 재주입되는 짧은 메시지입니다. 대화 압축(conversation compaction) 이후에도 컨텍스트(context)에 유지됩니다:

---
name: prod-deployer
description: Manages production deployments with strict safety checks
...

경고: 이 필드는 소스 코드 내 실제 이름에 EXPERIMENTAL이 포함되어 있습니다. Anthropic의 엔지니어들은 이를 불안정하다고 간주합니다. 현재는 작동하지만, 어떤 릴리스(release)에서든 제거되거나 이름이 변경될 수 있습니다. 부가적인 안전 리마인더 용도로만 사용하고, 이를 기반으로 핵심 인프라를 구축하지 마십시오.

requiredMcpServers

반드시 구성되어야 하는 MCP 서버 이름 패턴을 나열합니다. 서버를 사용할 수 없는 경우, 에이전트(agent)가 나타나지 않습니다. 이는 의존성(dependencies)이 설정되지 않았을 때 에이전트가 로드되는 것을 방지합니다.

auto-mode 분류기는 평이한 영어를 수용합니다

settings.json의 autoMode 필드는 Anthropic이 내부적으로 "YOLO Classifier"라고 부르는 것을 구성합니다. 이는 auto 모드에서 무엇이 자동 승인(auto-approved)될지를 제어합니다:

{
"autoMode": {
"allow": [
...

allow 패턴은 자동 승인됩니다. soft_deny 패턴은 항상 확인을 요구합니다. environment 배열이 흥미로운 부분인데, 이는 패턴이 전혀 아닙니다. 이는 분류기가 사용자의 설정을 이해하기 위해 읽는 평이한 영어 문맥 문자열(context strings)입니다. "This project uses Docker, all commands run in containers"(이 프로젝트는 Docker를 사용하며, 모든 명령은 컨테이너 내에서 실행됩니다)라고 작성하면, 분류기가 모호한 명령에 대한 안전 결정을 내릴 때 이를 고려합니다.

분류기에게 사용자의 환경에 대한 브리핑(briefing)을 제공하는 것이라고 생각하면 됩니다. 구체적일수록 더 나은 결정을 내립니다. "No production access"(운영 환경 접근 권한 없음)라고 하면 파괴적인 작업에 대해 덜 편집증적으로 반응하게 됩니다. "Test database is isolated"(테스트 데이터베이스는 격리되어 있음)라고 하면 테스트 실행이 항상 안전하다고 판단합니다.

문서화되지 않은 러닝 루프(learning loop) 토글

두 개의 settings.json 필드가 Claude Code의 자기 개선(self-improvement) 시스템을 활성화합니다:

{
"autoMemoryEnabled": true,
"autoDreamEnabled": true
...

autoMemoryEnabled

autoMemoryEnabled

Claude Code가 세션으로부터 영구적인 메모리 (durable memories)를 자동으로 추출하도록 만듭니다. 각 대화가 끝난 후, 백그라운드 에이전트 (background agent)가 기억할 가치가 있는 사항들, 사용자의 선호도, 코드베이스 패턴, 내린 결정 등을 추출하여 표준 메모리 프론트매터 (memory frontmatter) 형식을 사용하여 ~/.claude/projects/<path>/memory/에 기록합니다.

autoDreamEnabled

백그라운드 "꿈" 통합 (dream consolidation) 기능을 활성화합니다. 24시간마다 5개 이상의 세션이 축적되면, 백그라운드 에이전트가 과거 세션의 트랜스크립트 (transcripts)를 검토하고 메모리를 통합합니다. 이 과정에서 중복된 내용을 병합하고, 모순을 해결하며, 상대적인 날짜를 절대적인 날짜로 변환하고, 오래된 항목을 정리 (prune) 합니다.