Claude Code – Everything You Can Configure That the Docs Don't Tell You

개요

Claude Code의 공식 문서에 공개되지 않은 다양한 설정과 기능을 통해 기능 확장 및 사용자 정의가 가능하며, 이는 AI 개발 환경의 잠재력을 극대화하는 데 기여합니다.

주요 내용

* YOLO Classifier: Claude Code의 자동 모드 권한 시스템으로, yoloClassifier.ts 파일 내 yoloClassifier 변수로 관리됩니다. NODE_ENV=development와 같은 환경 설명을 영어 평문으로 제공하여 안전한 자동 승인 여부를 결정하는 데 사용됩니다.
* Hooks 시스템: 공식 문서에는 Hooks가 표준 입력(stdin)으로 JSON을 받고 종료 코드 2가 작업을 차단한다는 내용만 명시되어 있습니다. 그러나 소스 코드 분석을 통해 PreToolUse, SessionStart, PostToolUse, PermissionRequest 등 이벤트별로 JSON 응답을 통해 Claude Code의 동작을 실시간으로 수정할 수 있는 기능이 드러났습니다.
* PreToolUse hooks는 updatedInput (도구 입력 수정), permissionDecision (권한 강제), permissionDecisionReason (결정 이유 설명), additionalContext (대화 컨텍스트 주입) 등을 반환할 수 있습니다.
* SessionStart hooks는 watchPaths (파일 변경 감지 트리거), initialUserMessage (첫 사용자 메시지 내용 변경), additionalContext (세션 전체 컨텍스트 주입) 등을 반환할 수 있습니다.
* PostToolUse hooks는 updatedMCPToolOutput (MCP 도구 응답 수정), additionalContext (도구 실행 후 컨텍스트 주입) 등을 반환할 수 있습니다.
* PermissionRequest hooks는 decision (프로그래밍 방식 승인/거부)을 반환할 수 있습니다.
* Hook 스크립트 활용 예시:
* git push 명령어에 --dry-run을 자동으로 추가하는 PreToolUse hook.
* package.json, .env, tsconfig.json 파일 변경 감지와 현재 브랜치 및 변경 파일 수를 세션 시작 시 주입하는 SessionStart hook.
* ls, cat 등 읽기 전용 bash 명령어에 대해 자동 승인을 적용하는 PreToolUse hook.
* 추가 Hook 필드: 문서에 명시된 type, command, matcher, timeout, if, statusMessage 외에 once: true (한 번만 실행 후 제거), async: true (백그라운드 실행, 차단 없음), asyncRewake: true (백그라운드 실행, 오류 시 차단) 필드가 존재합니다.
* Skills 고급 설정: 문서의 name, description, allowed-tools, argument-hint, when_to_use, context 외에 model (Haiku, Opus 등 모델 선택), effort (low, medium, high, max 수준 조절), hooks (스킬 활성 시점에만 등록/해제되는 scoped hooks), agent (스킬 위임), disable-model-invocation (자동 호출 방지), shell (실행 셸 지정) 등이 있습니다.
* Custom Agents: .claude/agents/ 디렉토리 내 커스텀 에이전트는 문서에 언급되지 않은 추가 frontmatter 필드를 지원합니다.
* color: UI 색상 설정.
* memory: user (전역), project (프로젝트별), local (프로젝트별, gitignore) 수준의 영구 메모리 설정으로 에이전트가 학습 가능하게 합니다.
* omitClaudeMd: CLAUDE.md 계층 구조 로딩을 건너뛰어 프로젝트별 제약 없이 산업 표준 적용 가능.
* criticalSystemReminder_EXPERIMENTAL: 모든 턴에 시스템 리마인더로 재주입되는 짧은 메시지 (실험적 기능).
* requiredMcpServers: 필요한 MCP 서버 이름 패턴 목록.
* Auto Mode 설정 (settings.json): autoMode 설정은 allow (자동 승인 패턴), soft_deny (확인 필요 패턴), environment (자연어 설명 기반 환경 이해)를 포함하며, 특히 environment 필드는 Claude Code가 사용자의 개발 환경을 이해하고 안전 결정을 내리는 데 중요한 역할을 합니다.
* Self-Improvement 시스템: autoMemoryEnabled: true는 세션에서 영구 메모리를 자동으로 추출하고, autoDreamEnabled: true는 24시간마다 세션 기록을 검토하여 메모리를 통합, 중복 제거, 불일치 해결 등을 수행하여 모델 재학습 없이 경험을 통해 학습하는 루프를 생성합니다.
* MAGIC DOC: # MAGIC DOC: H1 헤더와 그 다음 줄의 이탤릭체 설명으로 문서 업데이트 에이전트의 작업 범위를 지정할 수 있습니다.
* Wildcard 패턴 언어: Bash(npm *), Read(src/**/*.ts), mcp__slack__* 등 globs를 사용하여 도구 및 파일 패턴을 지정합니다.
* Forked Skills: context: fork 설정은 스킬을 별도의 포크된 서브에이전트로 실행하며, CacheSafeParams 계약을 통해 부모 프롬프트 캐시를 공유하여 API 요청 접두어의 바이트 동일성을 극대화합니다.
* 실무 적용 예시:
* 학습하는 코드 리뷰어 에이전트 (.claude/agents/reviewer.md).
* 세션 시작 시 컨텍스트 로딩 및 위험 명령어 차단을 위한 asyncRewake Hook 조합 (settings.json).
* 최대 노력, 에이전트 위임, omitClaudeMd를 사용한 아키텍처 리뷰 스킬 (architecture-review).

시사점

Claude Code의 공식 문서에 공개되지 않은 고급 기능들은 Hooks 시스템, 영구 에이전트 메모리, 환경 기반 자동 모드 분류기 등을 통해 기존의 AI 도구 사용을 넘어서 지속적으로 학습하고 자율적으로 발전하는 개발 환경을 구축할 수 있는 강력한 기반을 제공합니다.