Прополка: три проверки для каждой строки инструкций

Зачем это нужно

Файлы инструкций проекта только растут. Сначала в них пять строк, через полгода — пятьсот. Добавить правило кажется дешёвым и безопасным делом. Удалить — неловко: будто говоришь, что чужая работа больше не важна. Особенно в общем файле, куда пишет вся команда.

А цена каждой строки — context load в каждом запросе (см. 5.1). Документация Claude Code советует держать каждый CLAUDE.md короче 200 строк: длинные файлы занимают больше контекста и хуже соблюдаются. Поэтому файл инструкций нужно регулярно пропалывать — проходить строку за строкой и вырезать то, что не окупается.

Как это устроено

Решать, что остаётся, помогают три проверки.

1. Единственный источник правды

Каждый факт живёт в одном авторитетном месте. Дубли появляются незаметно: правило написали в AGENTS.md, его чуть другую версию — на странице документации, или один и тот же раздел дважды попал в длинный файл из разных pull request-ов.

Дубль обходится трижды:

• Поддержка. Изменили поведение — правьте в нескольких местах.
• Context load. Одно и то же оплачивается дважды.
• Вес. Повторённое правило звучит громче остальных и заглушает то, что сказано один раз.

Если копии расходятся, агент не знает, какая живая. Документация предупреждает: из двух противоречащих инструкций Claude может выбрать любую.

Отдельный случай: дубль того, что агент прочитает сам. Таблица npm-скриптов повторяет package.json, обзор стека — README.md, объяснение архитектурного решения — комментарий в коде. Источник правды — то, что исполняется или лежит рядом с кодом. Его и оставляйте.

2. Отложения

Отложения — строки, которые когда-то были правдой. Библиотеку заменили, соглашение поменялось, баг, от которого защищало правило, исправили. Правило осталось и тянет агента в мир, которого больше нет. Вопрос к каждой строке: это всё ещё правда?

Устаревшую строку вырезайте. Если часть её ещё верна, но нужна не всегда, вынесите эту часть за указатель (см. 5.2).

3. No-op

No-op — инструкция, которая ничего не меняет в поведении агента. Либо модель и так делает это по умолчанию («пиши понятные сообщения об ошибках», «не коммить секреты»), либо строка ничего не значит в своём контексте («этот файл содержит инструкции для агента»). Строка может быть правдивой и относиться к теме, но всё равно не стоить ни токена.

Проверка — один эксперимент: удалите строку и посмотрите, изменилось ли поведение. Не изменилось — это был no-op.

Что остаётся

Остаётся то, что агент сам не узнает и без чего ошибается. Пример из Cadence: маршруты регистрируются в конфиге, а не по имени файла, и новый файл маршрута без записи в таблице маршрутов отдаёт 404. Процедуры с предсказуемым триггером — «добавляю маршрут», «пишу тест» — переезжают в skills. Короткая таблица «симптом → причина» для поломок остаётся в файле: когда что-то сломается, заранее неизвестно.

Практика

Команда /init генерирует стартовый CLAUDE.md, и обычно он получается большим: обзор проекта, список команд, дерево директорий. Возьмите такой файл в Cadence (или свой текущий) и:

1. Выполните /context в новой сессии и запишите, сколько токенов занимают файлы инструкций.
2. Пометьте каждую строку: дубль, отложение, no-op или «остаётся».
3. Удалите помеченное или вынесите за указатель, затем снова выполните /context в новой сессии.

Число должно заметно упасть. Чтобы найти кандидатов быстрее, выполните /doctor prompt-audit: Claude ищет устаревшие инструкции, ссылки на несуществующие файлы и противоречия и предлагает правки, но ничего не меняет, пока вы не попросите.

Подводные камни

• Обобщение вместо удаления. Правило про старую библиотеку переписали в «выбирай библиотеки внимательно». Получился no-op: правда обо всём и ни о чём.
• Заметки для людей в контексте. Пояснения для сопровождающих пишите в блочных HTML-комментариях <!-- ... -->: Claude Code вырезает их из CLAUDE.md перед загрузкой, и они не тратят токены.

Вывод: каждая оставшаяся строка должна быть правдой, не повторяться и менять поведение агента.

Проверь себя

Источники

• Anthropic, How Claude remembers your project
• Anthropic, Commands
• По мотивам AI Coding Crash Course, AI Hero