CLAUDE.md в репозитории: какие инструкции агент действительно читает

Агент приходит в репозиторий с тем же багажом, что и новый подрядчик: он видел сотни похожих проектов и уверен, что здесь всё устроено так же. CLAUDE.md — единственное место, где эту уверенность можно перехватить до первой строки кода.

Файл в корне читается раньше всего

CLAUDE.md попадает в контекст ещё до того, как агент начнёт что-то искать по проекту. Всё, что вы туда положите, влияет на каждое решение в сессии. Всё лишнее размывает остальное.

Отсюда простой критерий: строка остаётся в файле, если без неё агент сделает конкретную ошибку. Всё прочее — мусор, который конкурирует за внимание с полезным.

Пример, который у меня работает лучше всего

# 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.

Четыре строки. Разберу, почему они срабатывают:

• Бьют по конкретной привычке. Модель пишет по памяти, и память у неё зафиксирована на дате обучения. Фраза «это не тот Next.js, который ты знаешь» ломает автопилот прямо в заголовке.
• Называют причину. «Отличается от твоих тренировочных данных» — агент понимает, почему именно его знание здесь ненадёжно.
• Дают адрес. node_modules/next/dist/docs/ — точный путь внутри репозитория, куда можно сходить прямо сейчас. Сравните с «изучи документацию».
• Ставят действие перед кодом. Read before writing. Порядок операций задан явно.

Инструкция без адреса остаётся пожеланием. «Следуй современным практикам» агент прочитает и продолжит делать по-своему: современные практики он и так считает своими.

Чем это отличается от README

Стандартный README от create-next-app начинается так:

First, run the development server:
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

Человеку в первый день это помогает. Агенту такой блок вредит: четыре равноправных варианта одной команды превращаются в выбор наугад, и он запустит npm в проекте, где залочен pnpm.

Разделение простое. README отвечает на вопрос «как запустить». CLAUDE.md отвечает на вопрос «как здесь принято и где смотреть, прежде чем писать».

Один источник правды вместо двух расходящихся

Разные инструменты ищут файлы с разными именами. Держите два комплекта инструкций — через пару недель они разойдутся гарантированно, потому что правку внесут только в один.

Поэтому всё содержимое живёт в AGENTS.md. CLAUDE.md у меня состоит из одной строки:

CLAUDE: @AGENTS.md

Импорт подтягивает содержимое. Редактировать остаётся один файл.

Что кладу внутрь

• Версии и то, чем они расходятся с привычным. Именно здесь агент ошибается чаще всего.
• Команды проекта — ровно одна на задачу. Один способ запустить, один способ прогнать тесты.
• Пути к документации, которую надо открыть до кода.
• Запреты с причиной. «Не трогай миграции руками — они генерируются» работает, голое «не трогай миграции» обходится через десять минут.
• Границы: каталоги и сервисы, куда лезть не нужно.

Что убираю

• Пересказ структуры папок. Агент обойдёт дерево быстрее, чем вы это опишете, и его версия будет свежее.
• Вежливые общие места про чистый код и лучшие практики. Нулевая информация при ненулевой цене.
• Всё, что устареет через спринт: номера задач, временные обходные пути, имена людей.

Как проверяю, что файл действительно читается

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

Второй приём — временный маркер. На день добавляю строку вроде «перед первым вызовом инструмента напиши: контекст загружен». Пара запусков показывает, доходит ли файл до модели. Дальше строку удаляю.

Где такие файлы ломаются

Они растут. Каждая неудачная сессия добавляет строчку, через полгода получается регламент на две страницы, и агент выбирает из него то, что ближе к его привычкам.

Раз в месяц я прохожу по файлу и выкидываю пункты, для которых уже не вспомню конкретный сбой. Короткий файл, который агент выполняет, полезнее исчерпывающего, который он пролистывает.

Лучшая проверка остаётся прежней: сравните, что агент сделал бы без этой строки. Разницы нет — строки быть не должно.