Пользовательский хук PostToolUse для загрузки CLAUDE.md по требованию вне дерева проекта

Поведение загрузки CLAUDE.md в Claude Code

В источнике подробно описано, как Claude Code обрабатывает файлы CLAUDE.md в различных условиях:

• Иерархическая загрузка: При запуске сессии в подкаталоге загружаются как локальный файл CLAUDE.md, так и файлы CLAUDE.md из родительских каталогов. Пример: сессия в root/a/ загружает и root/a/CLAUDE.md, и root/CLAUDE.md.
• Загрузка по требованию для дочерних каталогов: Дочерние каталоги корневого каталога текущей сессии загружают свои файлы CLAUDE.md, когда Claude обращается к файлам в этих каталогах. Пример: сессия в root/ загружает root/CLAUDE.md изначально, затем загружает root/a/CLAUDE.md, когда Claude читает файл в root/a/.
• Доступ к дополнительным каталогам через флаги: Использование --add-dir с CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 позволяет получить доступ к файлам CLAUDE.md в каталогах за пределами дерева проекта, но они загружаются при запуске сессии, а не по требованию.

Проблема: файлы CLAUDE.md из внешних каталогов не загружаются по требованию

Автор отмечает, что при работе в одном проекте и указании Claude читать файлы из каталогов за пределами дерева каталогов сессии, любые файлы CLAUDE.md в этих внешних каталогах не загружаются автоматически. Это создает проблемы для постепенного раскрытия контекста и требует ручного вмешательства каждый раз.

Решение: пользовательский хук PostToolUse

Решение включает создание хука PostToolUse, который:

• Проверяет, работает ли Claude за пределами дерева проекта при каждом вызове инструмента
• Поднимается вверх от этого каталога в поисках файлов CLAUDE.md
• Если найден, завершается с кодом 2, чтобы передать инструкции Claude, указывая ему прочитать их
• Отслеживает, какие файлы уже были представлены в сеансе, во временном файле с областью действия сессии, чтобы избежать повторных инструкций

Хук SessionStop очищает временный файл, используемый для отслеживания. Автор предоставляет скрипт под названием check_claude_md.py (исходный код указан в оригинальном посте), который реализует эту функциональность хука PostToolUse.

Практическая реализация

Данный подход решает конкретное ограничение, когда файлы CLAUDE.md из внешних каталогов загружаются только при запуске сессии при использовании флага --add-dir с CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1. Перехватывая вызовы инструментов и проверяя операции за пределами дерева проекта, хук обеспечивает загрузку по требованию, аналогично тому, как работают дочерние каталоги внутри дерева проекта.

Такой пользовательский хук полезен для разработчиков, которые часто работают с несколькими проектами или нуждаются в ссылках на общие файлы контекста из внешних каталогов без необходимости каждый раз вручную указывать Claude читать файлы CLAUDE.md.