Claude Code 잠금 해제: 문서에 없는 구성 및 고급 훅 심층 탐구

While the official documentation for Claude Code provides a solid foundation, a deep dive into the source code—available as a public npm package—reveals a layer of sophisticated, undocumented capabilities. These features transform Claude Code from a standard AI assistant into a programmable development environment with a middleware layer for tool use and a persistent learning loop.

This guide explores the advanced configurations discovered within the source, focusing on how to extend the tool's behavior through hooks, custom skills, and agent memory.

프로그래머블 미들웨어: 고급 훅

The most significant gap in the official documentation is the ability for hooks to return JSON on stdout to modify Claude Code's behavior in real time. While the docs mention that exit code 2 blocks an operation, the source code reveals specific fields that allow for dynamic intervention.

PreToolUse 훅

PreToolUse hooks can return the following fields to intercept and modify tool execution:

  • updatedInput: 도구의 입력을 재작성합니다 (예: git push 명령에 자동으로 --dry-run을 추가).
  • permissionDecision: 사용자에게 묻지 않고 "allow" 또는 "deny" 결정을 강제합니다.
  • permissionDecisionReason: UI에 표시되는 결정 이유를 제공합니다.
  • additionalContext: 텍스트를 대화 컨텍스트에 직접 삽입합니다.

SessionStart 및 PostToolUse 훅

  • SessionStart: watchPaths를 반환하여 자동 파일 감시를 트리거하고, initialUserMessage를 반환하여 첫 메시지 앞에 내용을 추가하며, additionalContext를 반환하여 세션 전체에 지속성을 제공합니다.
  • PostToolUse: updatedMCPToolOutput을 반환하여 MCP 도구 응답에서 Claude가 보는 내용을 수정하고, additionalContext를 반환하여 도구 실행 후 컨텍스트를 삽입합니다.

고급 훅 실행 필드

Beyond the standard type and command fields, the source code parser accepts three critical modifiers:

  • once: true: 훅이 정확히 한 번만 실행되고 자체적으로 제거됩니다. 최초 프로젝트 설정에 이상적이며 (예: .env.example을 .env로 복사).
  • async: true: 모델 응답을 차단하지 않고 백그라운드에서 훅을 실행합니다. 감사 로그에 적합합니다.
  • asyncRewake: true: 백그라운드에서 실행되지만 훅이 코드 2로 종료될 경우 모델을 "깨우고" 작업을 차단합니다. 이는 위반이 발견될 때만 흐름을 중단하는 비차단 안전 스캔(예: 비밀 탐지)에 활용됩니다.

사용자 정의 스킬로 기능 확장

.claude/skills/에 있는 사용자 정의 스킬은 기본 문서를 넘어서는 frontmatter 필드를 지원하여 모델 동작 및 리소스 할당을 세밀하게 제어할 수 있습니다.

모델 및 노력 재정의

  • model: 특정 스킬에 대한 기본 모델을 재정의합니다. 빠르고 저렴한 린팅에는 haiku를, 복잡한 아키텍처 검토에는 opus를 사용할 수 있습니다.
  • effort: 추론 깊이를 제어합니다. 옵션은 low, medium, high, max가 있습니다.

범위 지정 훅 및 위임

  • hooks: 특정 스킬이 실행되는 동안에만 활성화되는 훅을 정의할 수 있습니다. 예를 들어, strict-typescript 스킬은 모든 파일 편집 시 tsc를 실행하는 PostToolUse 훅을 등록하고, 스킬이 완료되면 해당 훅을 해제할 수 있습니다.
  • agent: 스킬 실행을 특정 사용자 정의 에이전트에 위임합니다.
  • disable-model-invocation: true: 모델이 스킬을 자동으로 호출하는 것을 방지합니다; 명시적인 /skill-name 명령을 통해서만 트리거됩니다.

지속적인 에이전트와 학습 루프

.claude/agents/에 있는 사용자 정의 에이전트는 장기 메모리와 시각적 구분을 위해 설정할 수 있습니다.

에이전트 메모리

The memory field allows agents to maintain state across sessions:

  • user: 모든 프로젝트에 걸친 전역 지속성.
  • project: 현재 프로젝트에 특화된 지속성.
  • local: 프로젝트별 개인 지속성(보통 gitignore 처리).

This enables the creation of agents that learn codebase patterns, remember previous architectural decisions, and track recurring issues over time.

고급 에이전트 구성

  • color: UI 색상을 설정하여(예: red, blue, green) 에이전트를 시각적으로 구분합니다.
  • omitClaudeMd: true: CLAUDE.md 지시 계층 로드를 건너뛰어, 프로젝트 특유의 편향 없이 기본 원칙에서 코드를 검토하도록 합니다.
  • criticalSystemReminder_EXPERIMENTAL: 대화 압축 중에도 안전 제약이 사라지지 않도록 매 턴마다 재삽입되는 짧은 메시지입니다.

"YOLO Classifier"와 자동 모드

내부적으로 Claude Code는 자동 모드에서 자동 승인될 수 있는 항목을 판단하기 위해 "YOLO Classifier"를 사용합니다. 패턴 매칭(예: Bash(npm *))이 주요 방법이지만, settings.json의 environment 배열을 통해 설정에 대한 일반 영어 설명을 제공할 수 있습니다.

"This is a local dev machine with no production database access"와 같은 문자열을 추가하면, 분류기가 모호한 명령에 대한 안전 결정을 내리는 데 사용할 컨텍스트를 제공하게 되며, 이는 AI에게 환경의 위험 프로필을 효과적으로 전달하는 것입니다.

자기 개선: 자동 메모리와 자동 드림

두 가지 설정은 모델 재학습 없이 Claude Code가 진화할 수 있는 복합 학습 루프를 활성화합니다:

  1. autoMemoryEnabled: 세션에서 지속 가능한 메모리를 자동으로 추출하여 프로젝트 메모리 저장소에 기록합니다.
  2. autoDreamEnabled: 24시간마다 백그라운드 에이전트가 세션 전사를 검토하여 메모리를 통합하고, 중복을 병합하며, 오래된 항목을 정리합니다.

커뮤니티 관점 및 주의사항

이러한 기능은 막대한 힘을 제공하지만, 커뮤니티는 사용에 대한 중요한 경고를 제기했습니다. Hacker News의 여러 사용자는 이러한 기능 대부분이 문서화되지 않았거나 소스에 숨겨져 있기 때문에 사전 통보 없이 변경될 수 있다고 지적했습니다.

"Claude 패키지는 매주 10개의 새로운 버전이 발표됩니다... 그 주위의 문서화되지 않은 트릭에 절대 의존해서는 안 됩니다: 변경될 것이고, 매우 구체적인 설정을 깨뜨릴 것입니다."

또한 일부 사용자는 Anthropic이 문서를 업데이트함에 따라 이러한 "문서화되지 않은" 기능들(asyncRewake 및 특정 frontmatter 필드 등)이 공식 문서에 등장하기 시작했지만 여전히 찾기 어려울 수 있다고 지적했습니다. 사용자는 적응형 사고나 텔레메트리를 비활성화하는 등 모델 동작을 미세 조정하기 위해 베드락 배포용 환경 변수도 살펴볼 것을 권장합니다.

Sources