프로젝트 트리 외부에서 주문형 CLAUDE.md 로딩을 위한 사용자 정의 PostToolUse 훅

Claude Code에서의 CLAUDE.md 로딩 동작

원문은 Claude Code가 다양한 조건에서 CLAUDE.md 파일을 어떻게 처리하는지 설명합니다:

• 계층적 로딩: 하위 디렉터리에서 세션을 시작할 때, 로컬 CLAUDE.md와 상위 디렉터리의 CLAUDE.md 파일이 모두 로드됩니다. 예: root/a/에서 세션을 시작하면 root/a/CLAUDE.md와 root/CLAUDE.md가 모두 로드됩니다.
• 필요에 따른 하위 디렉터리 로딩: 현재 세션의 루트 디렉터리의 하위 디렉터리는 Claude가 해당 디렉터리의 파일에 접근할 때 CLAUDE.md 파일을 로드합니다. 예: root/에서 세션을 시작하면 초기에 root/CLAUDE.md가 로드되고, Claude가 root/a/의 파일을 읽을 때 root/a/CLAUDE.md가 로드됩니다.
• 플래그를 통한 추가 디렉터리 접근: CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1과 함께 --add-dir를 사용하면 프로젝트 트리 외부 디렉터리의 CLAUDE.md 파일에 접근할 수 있지만, 이 파일들은 필요에 따라가 아닌 세션 시작 시 로드됩니다.

문제: 외부 디렉터리 CLAUDE.md 파일이 필요에 따라 로드되지 않음

작성자는 한 프로젝트에서 작업하면서 Claude에게 세션의 디렉터리 트리 외부 디렉터리의 파일을 읽도록 지시할 때, 해당 외부 디렉터리에 있는 CLAUDE.md 파일이 자동으로 로드되지 않는다고 지적합니다. 이는 점진적인 컨텍스트 공개에 문제를 일으키며 매번 수동 개입이 필요하게 합니다.

해결책: 사용자 정의 PostToolUse 훅

이 솔루션은 다음과 같은 PostToolUse 훅을 생성하는 것을 포함합니다:

• 각 도구 호출 시 Claude가 프로젝트 트리 외부에서 작동하는지 확인
• 해당 디렉터리에서 위로 올라가며 CLAUDE.md 파일을 찾음
• 발견되면, Claude에게 파일을 읽으라고 알리는 지시를 전달하기 위해 코드 2로 종료
• 세션 범위의 임시 파일에서 이미 표면화된 파일을 추적하여 반복 지시를 피함

SessionStop 훅은 추적에 사용된 임시 파일을 정리합니다. 작성자는 이 PostToolUse 훅 기능을 구현하는 check_claude_md.py라는 스크립트를 제공합니다(원문 게시물에 소스 링크 있음).

실제 구현

이 접근 방식은 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1과 함께 --add-dir 플래그를 사용할 때 외부 디렉터리 CLAUDE.md 파일이 세션 시작 시에만 로드되는 특정 한계를 해결합니다. 도구 호출을 가로채고 프로젝트 트리 외부 작업을 확인함으로써, 이 훅은 프로젝트 트리 내에서 하위 디렉터리가 작동하는 방식과 유사하게 필요에 따른 로딩을 가능하게 합니다.

이러한 사용자 정의 훅은 여러 프로젝트에서 자주 작업하거나 외부 디렉터리에서 공유 컨텍스트 파일을 참조해야 하지만 매번 Claude에게 CLAUDE.md 파일을 읽으라고 수동으로 지시하지 않아도 되는 개발자에게 유용합니다.