CLAUDE.md: как описать проект, чтобы агент перестал переспрашивать

Переспрос — это дырка в контексте

Когда агент спрашивает «где лежат компоненты?» или «какой роутер используем?», он упёрся в то, что в проекте есть, но нигде не записано. Вопрос выглядит как вежливость. На деле это счётчик: каждый переспрос стоит вам минуты внимания и добавляет шанс, что в следующий раз агент угадает сам и угадает мимо.

Я отношусь к CLAUDE.md как к списку ответов на вопросы, которые агент задаёт чаще всего. Список собирается сам — достаточно неделю поработать и записывать, обо что он спотыкается.

Один вход вместо пяти файлов

Корневой CLAUDE.md в одном моём проекте состоит из одной строки:

@AGENTS.md

Всё содержимое живёт в AGENTS.md, который читают и другие агенты. CLAUDE.md работает указателем. Правила хранятся в одном месте, при переезде на другой инструмент переписывать нечего.

Если правил много, дробите их по темам и подключайте ссылками: @docs/stack.md, @docs/conventions.md. Агент подтянет файлы при старте, вы редактируете короткие куски.

Предупреждайте о том, что расходится с обучением

Самая дорогая категория ошибок — когда агент уверенно пишет код по памяти, а в проекте стоит версия библиотеки с другими API. Он молчит и ничего не уточняет, потому что «знает». Лечится прямым предупреждением в начале файла:

# This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure
may all differ from your training data. Read the relevant guide in
`node_modules/next/dist/docs/` before writing any code.
Heed deprecation notices.

Здесь работают три вещи сразу: сбита ложная уверенность, назван точный путь к документации, задан порядок действий — сначала читаем, потом пишем. Такой блок стоит завести для каждой библиотеки, которую вы обновили недавно.

Словарь проекта

Второй источник переспросов — термины. Агент находит расхождение между макетом и вёрсткой и идёт спрашивать, что с этим делать.

В проекте витрины я завёл четыре метки, и агент проставляет их сам:

• дефект вёрстки — реализация разошлась с эталоном, чиним;
• осознанное отклонение — разошлась намеренно, причина указана;
• пробел в спеке — эталон молчит, нужно решение человека;
• достроено — блок собран с нуля, в холсте его нет.

После этого вместо вопроса «в макете нет футера, что делать?» приходит строка отчёта: футер, достроено, причина — этого требует спека. Я читаю и одобряю за секунды.

Работает любой словарь, лишь бы он покрывал развилки, на которых агент буксует.

Куда отправлять за деталями

CLAUDE.md распухает, если складывать в него всё. Держите его тонким и ссылайтесь на планы.

Мои планы лежат в docs/plans/ с датой в имени: docs/plans/2026-08-02-sexygram-mvp.md. Внутри — фазы, зоны ответственности агентов (каждому свои папки) и уровни гейта, например уровень 2 «визуальная сверка структуры». В CLAUDE.md остаётся одна фраза: перед работой прочитай актуальный план в docs/plans/.

Эта связка убирает целый класс вопросов «что мы вообще делаем и в каком порядке».

Что стоит выкинуть

• Описание структуры папок — агент прочитает её сам за две секунды.
• Лозунги вроде «пиши чистый код».
• Историю проекта и объяснения, почему когда-то выбрали React.
• Устаревшие правила. Мёртвая строка хуже отсутствующей: агент ей верит.

Правило отбора простое: в файл идёт то, чего нельзя увидеть в коде. Договорённости, запреты, ссылки на источники правды, предупреждения о версиях.

Как понять, что файл работает

Метрика одна — количество переспросов за сессию. Каждый вопрос агента дописывайте ответом в CLAUDE.md прямо во время работы, одной строкой. Через две-три недели поток пересыхает, и остаются вопросы, которые действительно требуют человека: приоритеты, бюджеты, вкусовые решения по дизайну.

И финальная проверка: попросите агента пересказать правила проекта своими словами. Расхождение с тем, что вы имели в виду, означает размытую формулировку — правьте её.