Claude Code 미문서 기능: 훅, 메모리, YOLO 분류기 등

André Figueira가 Claude Code 소스 코드(v2.1.87)를 읽고 수십 개의 문서화되지 않은 구성 옵션을 발견했습니다. 공식 문서는 기본 사항만 다루지만, 실제 패키지(node_modules에서 자유롭게 확인 가능)에는 훅, 에이전트 메모리, 자동 모드 규칙 등에 대한 필드가 노출되어 있습니다. 지금 바로 설정할 수 있는 것들을 소개합니다.

YOLO 분류기: 일반 영어로 작업 자동 승인

내부적으로 "YOLO 분류기"(yoloClassifier.ts)라고 불리는 이 시스템은 일반 영어로 환경을 설명하여 Claude가 작업을 자동 승인할 조건을 지정할 수 있게 해줍니다. settings.json에 "this is a staging server, destructive operations are acceptable"와 같은 설명을 추가하면 특정 작업을 프롬프트 없이 허용할 수 있습니다.

실시간으로 동작을 변경하는 훅 반환 값

훅은 stdin으로 JSON을 받고, stdout으로 이벤트별 JSON을 반환할 수 있습니다. 주요 반환 필드는 다음과 같습니다:

• PreToolUse: updatedInput(실행 전 도구 입력 수정), permissionDecision(강제 허용/거부), permissionDecisionReason, additionalContext
• SessionStart: watchPaths(자동 파일 감시로 FileChanged 이벤트 발생), initialUserMessage(첫 사용자 메시지 앞에 내용 추가), additionalContext
• PostToolUse: updatedMCPToolOutput, additionalContext
• PermissionRequest: decision(updatedInput 또는 updatedPermissions로 프로그래밍 방식 허용/거부)

예: 모든 git push 명령에 --dry-run을 추가하는 PreToolUse 훅. .claude/settings.json에서:

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

~/.claude/hooks/dry-run-pushes.sh 스크립트:

#!/bin/bash
INPUT=$(jq -r '.tool_input.command' 
이 스크립트는 실행 전 명령을 수정하며, 이는 문서화되지 않은 필드입니다.

세션 컨텍스트 및 파일 감시

SessionStart 훅은 watchPaths를 설정하여 package.json, .env, tsconfig.json과 같은 파일을 감시하고 변경 시 FileChanged 이벤트를 발생시킬 수 있습니다. 또한 initialUserMessage를 삽입하여 현재 git 브랜치 및 커밋되지 않은 변경 사항 수와 같은 컨텍스트를 앞에 추가할 수 있습니다.

감시 경로와 초기 메시지를 반환하는 예제 스크립트:

#!/bin/bash
BRANCH=$(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"],
    "initialUserMessage": "Current branch: \($branch), uncommitted changes: \($changes)"
  }'

영구 에이전트 메모리 및 자동 모드 규칙

에이전트 메모리는 ~/.claude/agents/ 디렉토리의 필드를 사용하여 세션 간 유지되도록 구성할 수 있습니다. 자동 모드 규칙은 일반 영어 파일로 작성하여 Claude가 작업을 자동 승인할 조건을 지정할 수 있습니다. 소스 코드는 또한 Claude가 자신의 설정을 개선할 수 있는 "자기 개선 드림 루프"를 암시합니다.

파일 위치

• 설정: ~/.claude/settings.json(개인) 또는 .claude/settings.json(프로젝트, git으로 공유 가능)
• 스킬: ~/.claude/skills/<name>/SKILL.md(개인) 또는 .claude/skills/<name>/SKILL.md(프로젝트)
• 에이전트: ~/.claude/agents/<name>.md(개인) 또는 .claude/agents/<name>.md(프로젝트)
• 훅 스크립트: 일반적으로 ~/.claude/hooks/에 위치하며, 실행 가능해야 함(chmod +x)

이러한 기능들은 문서화된 API 이상으로 Claude Code를 커스터마이징하려는 개발자에게 실용적입니다. 이러한 기능들은 릴리스 사이에 변경될 수 있습니다.