Третий раз за неделю вы объясняете агенту одно и то же: тесты запускаются вот такой командой, компоненты лежат вот здесь, а вот так у нас делать нельзя. Он соглашается, исправляет, а в следующей сессии начинает заново.
Лечится это файлом CLAUDE.md. Но у него есть свойство, из-за которого половина команд разочаровывается ещё до того, как он начнёт работать: это контекст, а не конфигурация. Файл не заставляет агента что-то делать, он подсказывает.
Разберём, что туда класть, что оттуда убрать, чем он отличается от скиллов и хуков и как убедиться, что он вообще загрузился.
Главное свойство: подсказка, а не приказ
Содержимое CLAUDE.md приезжает в сессию как обычное сообщение, а не как часть системного промпта. Агент его читает и старается следовать, но строгого исполнения тут нет, особенно если инструкция расплывчатая или противоречит другой.
Отсюда практический вывод, который экономит много раздражения. Если правило должно выполняться всегда и обязательно, скажем запрет пушить в главную ветку или обязательный линтер перед коммитом, ему не место в CLAUDE.md. Такое выражают хуками: они запускаются в фиксированных точках жизненного цикла и работают независимо от того, что решит модель.
CLAUDE.md хорош для другого: для того, что агент не может вывести из кода сам.
Куда класть файл
Файлы читаются в порядке от общего к частному, и всё найденное складывается вместе, а не перезаписывает друг друга:
| Уровень |
Путь |
Для чего |
| Организация |
управляемая политика на машине |
Общие стандарты компании |
| Пользователь |
~/.claude/CLAUDE.md |
Ваши личные привычки во всех проектах |
| Проект |
./CLAUDE.md или ./.claude/CLAUDE.md |
Командные правила, коммитится в репозиторий |
| Личный в проекте |
./CLAUDE.local.md |
Ваши локальные мелочи, добавляется в .gitignore |
Читается не один лишь файл в текущем каталоге: агент поднимается по всем каталогам выше. Файлы во вложенных папках подхватываются позже, когда агент до этих папок доберётся.
Быстрый старт даёт команда /init: она осмотрит проект и соберёт черновик с командами сборки и найденными конвенциями. Дальше файл дописывают руками — тем, чего в коде не видно.
Что стоит записать
Ориентир простой: записывайте то, что вам приходится объяснять повторно. Признаки, что пора дописать файл:
- агент второй раз совершает одну и ту же ошибку
- на ревью всплывает то, что он мог бы знать про этот проект
- вы печатаете в чат ту же поправку, что и в прошлый раз
- новому человеку в команде понадобился бы ровно этот же контекст
По содержанию хорошо ложатся четыре вещи: команды проверки, архитектурные запреты, конвенции именования и раскладка проекта.
От формулировок требуется конкретность, которую можно проверить:
# Плохо # Хорошо
Форматируй код правильно → Отступ 2 пробела
Тестируй изменения → Перед коммитом запускай `npm test`
Держи файлы в порядке → Обработчики API лежат в `src/api/handlers/`
Разница не косметическая. Расплывчатую инструкцию агент истолкует по-своему, а проверяемую просто выполнит.
Что записывать не нужно
Здесь и находится главная ошибка: файл превращают в описание проекта. А он уезжает в контекст каждой сессии, то есть вы платите за каждую строку постоянно, независимо от того, пригодилась она сегодня или нет.
Ориентир по размеру: до двухсот строк. Длинный файл дороже обходится и хуже соблюдается: чем больше правил, тем меньше внимания каждому.
Не стоит класть в файл:
То, что видно из кода. Раскладка каталогов, список зависимостей, обзор архитектуры. Агент прочитает это сам, когда понадобится.
Многошаговые процедуры. Инструкция «как выкатить релиз» на сорок строк нужна раз в месяц, а платите вы за неё каждую сессию. Такому место в скилле, который загружается по требованию.
Правила для одного каталога. Если инструкция касается только фронтенда, она не должна ехать в сессию, где вы правите миграции.
Последние два пункта не абстрактный совет: для них есть отдельные механизмы.
Правила с областью действия
Для инструкций, привязанных к части кодовой базы, есть каталог .claude/rules/. Файл с фронтматтером paths загружается только тогда, когда агент работает с подходящими файлами:
---
paths:
- "src/api/**/*.ts"
---
# Правила для API
- Каждый эндпоинт валидирует вход
- Ошибки отдаются в едином формате
Правило без paths грузится всегда, наравне с основным файлом.
Здесь легко ошибиться с импортами. CLAUDE.md умеет подтягивать другие файлы синтаксисом @путь/к/файлу, и кажется, что так можно разгрузить контекст. Нельзя: импортированные файлы загружаются в контекст вместе с основным. Импорт помогает организовать текст, но не экономит ни одного токена. Экономят только правила с областью действия и скиллы.
Мелочь, которая пригодится: чтобы упомянуть путь и не импортировать его, оберните в обратные кавычки.
Чем это отличается от скиллов и хуков
Три механизма решают три разные задачи, и путаница между ними порождает большую часть проблем.
CLAUDE.md и правила держат то, что должно быть в голове у агента постоянно или при работе с определёнными файлами. Загружается автоматически, стоит токенов, не гарантирует исполнения.
Скиллы упаковывают сценарии, которые подключаются, когда действительно нужны. Не занимают контекст, пока не вызваны. Сюда переезжает всё длинное и редкое.
Хуки выполняют команды в фиксированных точках. Единственный механизм с гарантией. Если что-то обязано случиться перед каждым коммитом, это хук, и никакая формулировка в CLAUDE.md его не заменит.
Отдельно стоит упомянуть автопамять: агент сам записывает то, что вы поправили, в свой каталог памяти. Она дополняет CLAUDE.md, но не заменяет его: правила пишете вы, наблюдения — он.
Как проверить, что файл работает
При жалобе «он игнорирует мой CLAUDE.md» первым делом убедитесь, что файл вообще загрузился.
Команда /context показывает список загруженных файлов памяти. Если вашего там нет, дело не в формулировках, а в расположении. Команда /memory открывает файлы на редактирование и заодно показывает, где они лежат.
Если файл загрузился, а инструкции всё равно не соблюдаются, проверьте три вещи по порядку:
- Конкретность. «Форматируй красиво» проверить нельзя, значит, и выполнить однозначно тоже.
- Противоречия. Два правила из разных файлов могут спорить друг с другом, и тогда агент выберет одно произвольно. В больших монорепозиториях это частая история: подхватываются файлы соседних команд.
- Природа требования. Если правило обязано соблюдаться железно, оно и не должно жить в
CLAUDE.md.
Полезная деталь про длинные сессии: корневой файл проекта переживает уплотнение контекста — после /compact он перечитывается с диска. А вот инструкция, произнесённая только в чате, после уплотнения пропадёт. Это ещё один довод переносить повторяющиеся поправки в файл.
Две мелочи, которые мало кто знает
Комментарии HTML вырезаются. Блочный комментарий вида <!-- заметка для своих --> удаляется до попадания в контекст. То есть в файле можно держать пояснения для коллег, не платя за них токенами.
Файл AGENTS.md сам по себе не читается. Если в репозитории уже есть конфигурация для других агентов, не дублируйте её: сделайте CLAUDE.md, который импортирует AGENTS.md, и допишите специфику ниже.
Чек-лист
Заключение
Хороший CLAUDE.md короткий и скучный: несколько команд, несколько запретов, несколько конвенций, которые нельзя вывести из кода. Всё остальное либо переезжает в скиллы и правила, либо становится хуком, либо не нужно вовсе.
Проверить себя можно одним вопросом: пригодится ли эта строка в каждой сессии? Если нет, она стоит вам токенов на каждом запросе и не окупается. Про то, куда ещё утекает контекст, мы написали отдельно.
Читайте также
