AI 코딩 에이전트를 사용해 반복적인 보일러플레이트 코드를 작성하거나 리팩토링을 자동화하는 환경은 이제 낯설지 않다. 하지만 대부분의 사용자는 제공된 공식 문서의 설정 범위 내에서만 도구를 활용한다. 최근 Anthropic가 공개한 Claude Code의 npm 패키지 소스 코드를 분석한 결과, 공식 문서에는 언급되지 않은 런타임 제어 기능과 메모리 최적화 설정들이 확인됐다.
YOLO 분류기와 훅(Hook)을 이용한 런타임 제어
Claude Code의 자동 승인 시스템은 내부적으로 `yoloClassifier.ts` 파일 내의 'YOLO 분류기'라는 변수로 작동한다. 개발자는 이 분류기에 영어로 된 환경 설명문을 입력해 도구의 자동 승인 여부를 결정한다. 예를 들어 "이 서버는 스테이징 서버이며 파괴적인 작업이 허용된다"는 문구를 넣으면, 분류기가 이를 읽고 위험도가 높은 명령어도 자동으로 승인한다. 이는 정해진 규칙 기반의 필터링이 아니라 자연어 컨텍스트를 통해 권한 체계를 동적으로 조정하는 방식이다.
개발자는 `~/.claude/hooks/` 경로에 훅 스크립트를 배치해 런타임 제어권을 확보한다. 이 경로에 작성된 스크립트는 `chmod +x` 명령으로 실행 권한을 부여해야 시스템이 인식한다. 훅은 `stdout`으로 특정 JSON 필드를 반환해 툴의 동작을 즉각 수정한다. `updatedInput` 필드를 사용하면 툴 실행 직전에 입력값을 가로채 내용을 바꿀 수 있다. 예를 들어 사용자가 위험한 명령을 내렸을 때 훅이 이를 감지해 안전한 옵션을 추가한 명령어로 대체한다. `permissionDecision` 필드는 사용자 확인 절차를 생략하고 허용 또는 거부를 강제하며, `additionalContext` 필드는 대화 흐름에 필요한 추가 정보를 주입해 모델의 판단 근거를 보강한다.
`async: true`와 `asyncRewake: true` 설정은 작업의 효율성과 안전성을 제어한다. `async: true`를 적용하면 훅이 백그라운드에서 실행되어 모델의 응답 속도에 영향을 주지 않고 로그 기록 같은 부수 작업을 처리한다. 반면 `asyncRewake: true`는 평소에는 비동기로 작동하다가 스크립트가 종료 코드 2를 반환하는 순간 모델을 다시 깨워 작업을 즉시 차단한다. 이는 정상 경로에서는 지연 시간을 없애고 보안 위반이나 치명적 오류가 발생한 시점에만 개입하는 구조다.
실무에서는 이를 통해 위험한 명령어를 안전하게 강제하거나 단순 반복 승인 과정을 자동화한다. `git push` 명령에 `--dry-run` 옵션을 자동으로 추가해 실수로 코드를 밀어넣는 상황을 방지하는 스크립트가 대표적이다.
bash
~/.claude/hooks/dry-run-pushes.sh
git push 명령 감지 시 updatedInput에 --dry-run 추가 반환
또한 읽기 전용 bash 명령을 자동으로 승인하는 훅을 구성해 불필요한 확인 클릭을 줄인다.
bash
~/.claude/hooks/auto-approve-readonly.sh
읽기 전용 명령 확인 시 permissionDecision: allow 반환
자동 메모리 통합과 에이전트 최적화 설정
`autoMemoryEnabled` 설정은 세션에서 유용한 정보를 자동으로 추출하고, `autoDreamEnabled`가 24시간마다 누적된 메모리를 통합하며 중복을 제거한다. 특히 5개 이상의 세션이 쌓이면 배경 에이전트가 과거 기록을 검토해 모순을 해결하고 상대적 날짜를 절대값으로 변환하며 낡은 항목을 삭제한다. 메모리는 모든 프로젝트에 적용되는 `user` 글로벌 계층, 특정 프로젝트에 귀속되는 `project` 계층, 그리고 gitignore 대상이 되어 외부 유출을 막는 `local` 계층으로 세분화된다. 이를 통해 모델 재학습 없이 프로젝트 고유의 패턴과 의사결정 이력을 유지하는 지속적 메모리 시스템을 구축한다.
에이전트의 추론 깊이와 비용은 `model`과 `effort` 필드로 제어한다. 단순 작업에는 Haiku 모델을, 복잡한 아키텍처 분석에는 Opus 모델을 할당하며, `effort` 값을 low, medium, high, max 중 하나로 설정해 모델의 내부 추론 깊이를 조절한다. 에이전트 확장 설정에서는 `color` 필드로 UI 색상을 지정해 여러 에이전트를 시각적으로 구분하고, `omitClaudeMd: true`를 설정해 프로젝트 내부 컨벤션을 무시하고 산업 표준만을 적용하는 제3자 리뷰어 역할을 부여한다. 실험적 기능인 `criticalSystemReminder_EXPERIMENTAL`은 대화 내용이 압축되어 컨텍스트가 사라진 이후에도 매 턴 시스템 리마인더를 강제로 주입해 핵심 안전 제약 사항을 유지한다.
리소스 효율은 `context: fork`와 `CacheSafeParams`라는 타입 계약을 통해 관리한다. 포크된 서브 에이전트는 부모 프롬프트의 캐시를 공유하며 API 요청 접두사를 바이트 단위로 일치시켜 토큰 비용을 절감한다. 포크된 스킬에서 모델을 다르게 설정하면 캐시 미스가 발생하므로 `model: inherit` 설정을 통해 캐시 효율을 유지한다. 특정 파일의 배경 정보를 자동으로 업데이트하는 기능은 `/^#\s*MAGIC\s+DOC:\s*(.+)$/im` 정규식을 통해 구현한다. 배경 업데이트 에이전트가 이 H1 헤더를 추적하며 이탤릭체로 작성된 지침에 따라 특정 범위만 수정하고, 헤더를 삭제하면 추적을 즉시 중단하는 방식으로 문서 최신성을 유지한다.
Claude Code는 YOLO 분류기와 자동 메모리 시스템을 통해 개발 환경의 컨텍스트를 스스로 분류하고 기억하는 구조를 갖췄다. 개발자는 이제 단순한 프롬프트 작성을 넘어, 에이전트의 메모리 계층과 환경 인지 범위를 직접 설정함으로써 도구의 실무적 활용 한계를 확장할 수 있다.
