npm 패키지로 배포되는 Claude Code의 소스 코드는 누구나 node_modules 안에서 볼 수 있습니다. 그걸 실제로 뜯어본 사람이 나왔습니다. 공식 문서가 설명하는 수준과 실제 구현 사이의 간격은 생각보다 컸습니다.

개발자 뉴스레터 Building Better의 필자가 @anthropic-ai/[email protected] 소스 코드를 직접 분석해 공식 문서에 없는 기능들을 정리했습니다. 이미 작동하는 기능이고, 대부분은 설정 파일 몇 줄이면 활성화됩니다.

출처: I Read the Claude Code Source Code – Building Better

훅 시스템: AI가 실행하기 전에 명령을 가로챌 수 있다

공식 문서는 훅(hooks)이 JSON을 stdin으로 받고, 종료 코드 2가 작업을 차단한다는 정도만 설명합니다. 실제 소스에는 훨씬 더 많은 응답 필드가 있습니다.

PreToolUse 훅은 updatedInput 필드를 통해 Claude가 실행하려는 명령 자체를 바꿀 수 있습니다. Claude 입장에서는 git push origin main을 실행했지만, 훅이 실제로는 git push origin main --dry-run으로 교체해버리는 식입니다. permissionDecision 필드로 사용자 확인 없이 자동 허용이나 차단도 가능하고, additionalContext로 대화 맥락에 텍스트를 주입할 수도 있습니다.

SessionStart 훅은 watchPaths를 반환해 특정 파일 변경을 자동으로 감지하게 만들 수 있고, initialUserMessage로 세션 첫 메시지 앞에 내용을 덧붙일 수도 있습니다.

문서에 없는 훅 필드도 세 가지 더 있습니다. once: true는 훅을 한 번만 실행하고 자동 제거합니다. async: true는 Claude를 차단하지 않고 백그라운드에서 실행합니다. asyncRewake: true가 흥미로운데, 평소에는 비동기로 돌다가 종료 코드 2가 발생했을 때만 Claude를 깨워 작업을 차단합니다. 감사 로그나 시크릿 스캔처럼 느려도 되는 안전장치에 쓰기 좋습니다.

에이전트와 스킬: 문서에 없는 프론트매터 필드들

커스텀 에이전트(.claude/agents/)와 스킬(.claude/skills/)의 프론트매터에는 문서에 나오지 않는 필드가 여럿 있습니다.

에이전트에서 주목할 것은 memory 필드입니다. user(전역), project(프로젝트별), local(로컬 전용) 세 가지 범위로 설정할 수 있고, 세션이 끝나도 에이전트가 이전 세션의 맥락을 기억합니다. 반복 사용할수록 코드베이스의 패턴이나 과거 리뷰 내용을 축적해 가는 전문가 에이전트를 만들 수 있는 구조입니다.

omitClaudeMd: true는 CLAUDE.md의 프로젝트 지침 계층을 건너뜁니다. 프로젝트 관습이 아닌 산업 표준으로만 코드를 보고 싶을 때, 즉 편향 없는 리뷰어가 필요할 때 씁니다.

criticalSystemReminder_EXPERIMENTAL은 대화 압축이 일어나도 매 턴마다 시스템 메시지로 재주입되는 텍스트입니다. 소스 코드 변수명에 EXPERIMENTAL이 명시되어 있어서, 작동은 하지만 언제든 바뀔 수 있습니다.

스킬 쪽에서는 model과 effort 필드가 유용합니다. 빠른 린트에는 haiku를, 심층 아키텍처 분석에는 opus를 지정하는 식입니다. effort는 low부터 max까지 모델의 추론 깊이를 제어합니다.

YOLO Classifier: 자연어로 환경을 설명하면 AI가 읽는다

auto mode의 자동 승인 시스템은 내부 코드명이 yoloClassifier.ts입니다. settings.json의 autoMode 필드로 설정하는데, allow와 soft_deny 패턴 외에 environment 배열이 핵심입니다.

이 배열에는 패턴이 아니라 평문 설명을 씁니다. “스테이징 서버라 파괴적 작업도 허용된다”, “테스트 DB는 격리돼 있어 반복 실행해도 안전하다” 같은 문장을 클래시파이어가 읽고, 애매한 명령의 안전 여부를 판단할 때 참고합니다. 환경을 구체적으로 설명할수록 판단이 정교해집니다.

자동 메모리와 드림 시스템

settings.json에서 autoMemoryEnabled와 autoDreamEnabled 두 필드를 켤 수 있습니다.

autoMemoryEnabled는 세션이 끝날 때마다 백그라운드 에이전트가 대화에서 기억할 만한 것들을 추출해 ~/.claude/projects/<path>/memory/에 씁니다. 개발자의 선호, 코드베이스 패턴, 결정 사항 같은 것들입니다.

autoDreamEnabled는 24시간마다, 세션이 5개 이상 쌓이면 백그라운드 에이전트가 과거 트랜스크립트를 검토해 메모리를 통합합니다. 중복 제거, 모순 해소, 낡은 항목 삭제가 이 시간에 일어납니다.

세션이 메모리를 만들고, 드림이 메모리를 정제하고, 정제된 메모리가 다음 세션에 반영되는 루프입니다. 모델 재학습 없이 경험에서 학습하는 구조를 Claude Code가 이미 갖추고 있다는 뜻입니다.

공식 문서와 소스 코드 사이

이 발견들이 흥미로운 이유는 숨겨진 기능 목록 때문이 아닙니다. 훅 미들웨어, 에이전트 메모리, 자연어 환경 설명, 드림 통합 시스템이 하나의 방향을 가리키고 있기 때문입니다. Claude Code가 단순 코딩 보조에서 세션을 넘어 학습하고 판단하는 자율적인 개발 환경으로 설계되고 있다는 것입니다. 공식 문서가 아직 따라오지 못하고 있을 뿐입니다.

각 기능의 실제 설정 예시와 구체적인 스크립트 코드는 원문에서 확인할 수 있습니다.