CLAUDE.md и AGENTS.md: что это, что в них писать и почему агент игнорирует правила

Что такое CLAUDE.md и AGENTS.md

Это обычные Markdown-файлы в корне репозитория, которые агент автоматически подгружает в контекст в начале сессии. Через них вы сообщаете агенту то, чего он не может узнать из кода сам: как поднять окружение, какими командами проверять работу, какие правила проекта не обсуждаются и где лежит подробная документация.

CLAUDE.md — файл, который читает Claude Code. AGENTS.md — открытый формат с той же идеей, его поддерживают многие агенты для программирования. Если в команде пользуются разными агентами, удобно держать основное содержимое в AGENTS.md, а в CLAUDE.md сослаться на него. Claude Code поддерживает импорт другого файла строкой с @:

# CLAUDE.md
@AGENTS.md

Так правила живут в одном месте и не расходятся между двумя файлами.

Как агент читает эти файлы

Содержимое файла инструкций попадает в окно контекста модели вместе с системным промптом и остаётся там всю сессию. Отсюда три важных следствия.

• Каждая строка стоит места в контексте. Файл читается целиком при каждом запуске, даже если для текущей задачи нужна одна его десятая.
• Это не исполняемые правила, а текст. Модель учитывает его наравне с остальным контекстом, и ничто не гарантирует стопроцентного соблюдения. Жёсткие запреты нужно подкреплять механикой — проверками, хуками, правами доступа.
• Файлы можно вкладывать. Claude Code подгружает CLAUDE.md из корня проекта и из пользовательской папки ~/.claude/, а файлы во вложенных каталогах — когда агент работает с файлами в этих каталогах. Это позволяет держать правила модуля рядом с модулем.

Что писать в CLAUDE.md и AGENTS.md

Хороший файл инструкций — карта, а не учебник. Он отвечает на вопросы, которые агент задал бы опытному коллеге в первый день.

1. Как собрать и проверить проект

Самый ценный раздел. Конкретные команды, которые агент обязан выполнить перед тем, как сказать «готово»: тесты, линтер, проверка типов, запуск окружения. Без них агент проверяет себя «на глаз».

2. Жёсткие ограничения

Короткий список того, что нельзя нарушать ни при каких условиях: инварианты безопасности и данных. Формулируйте как инварианты, а не как инструкции по реализации: «все SQL-запросы параметризованы», а не «используй такую-то функцию в таком-то файле».

3. Карта проекта

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

4. Где хранится состояние работы

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

Что не писать

• То, что агент узнает из кода. Список зависимостей есть в package.json или pyproject.toml, структура классов — в самом коде.
• Общие советы. «Пиши чистый код», «будь внимателен» не меняют поведение и только занимают место.
• Историю проекта и разовые заметки. «В марте мы переехали с MySQL 5.7» не помогает текущей задаче.
• Подробные инструкции по редким задачам. Процедура деплоя или миграции данных нужна раз в неделю — вынесите её в отдельный документ или skill.
• Секреты. Файл лежит в репозитории и целиком уходит в модель. Токены и пароли — только в переменных окружения.

Почему агент игнорирует правило, которое написано в файле

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

Раздутый файл

Файл на 600 строк — это порядка 10–20 тысяч токенов. Окно контекста кажется огромным, но за него борются код, вывод команд и история диалога. Чем больше занимают инструкции, тем меньше внимания достаётся каждому правилу и тем больше места отнято у самой задачи.

Правило в середине

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

Нет приоритетов

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

Гниение

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

Как исправить: роутер вместо простыни

Чинить одну причину бесполезно: если сократить файл, но оставить его без структуры, правила по-прежнему смешаны. Работает комплекс мер.

1. Сделайте входной файл роутером. 50–150 строк: команды проверки, жёсткие ограничения, карта проекта и ссылки на тематические документы.
2. Вынесите темы в отдельные файлы. Например, docs/agents/deploy.md, docs/agents/database.md. Агент открывает их по необходимости. В Claude Code для повторяющихся процедур удобны skills — они подгружаются, только когда нужны.
3. Поднимите критичное наверх. Жёсткие ограничения — в начало файла, отдельным коротким блоком с явной пометкой MUST.
4. Уберите противоречия. Для каждой темы — одно правило. Если есть исключение, напишите его рядом с правилом.
5. Подкрепите правило механикой. Если нарушение недопустимо, текста мало. Нужна проверка, которая это ловит: линтер, тест, pre-commit хук или хук агента, запрет на уровне прав доступа.
6. Ревизуйте регулярно. Ставьте лимит строк и при каждом добавлении спрашивайте, что можно удалить или вынести.

Правило или проверка?

Пример компактного AGENTS.md

# AGENTS.md — платёжный бэкенд (FastAPI, PostgreSQL)

## MUST — не нарушать
- Суммы денег — int в копейках, никогда float
- SQL только параметризованный, без f-строк
- Не менять применённые миграции, только добавлять новые
- Секреты — только из переменных окружения

## Проверка перед словом «готово»
docker compose up -d     # окружение
make lint                # ruff + mypy
make test                # pytest
make e2e                 # сценарий оформления заказа
Зелёные юнит-тесты без e2e — не «готово».

## Карта
- app/payments/   — расчёт сумм, скидки, вебхуки провайдера
- app/api/        — HTTP-ручки
- tests/e2e/      — сценарии пользователя
Подробно: docs/agents/architecture.md, docs/agents/database.md

## Состояние работы
- PLAN.md      — текущая цель, критерии готовности, следующий шаг
- PROGRESS.md  — что сделано и как проверено, тупики
- BACKLOG.md   — замеченное «заодно»: записать сюда, не чинить сейчас

В конце сессии обнови PROGRESS.md и следующий шаг в PLAN.md.

Обратите внимание, чего здесь нет: перечня библиотек, советов по стилю, истории проекта. Всё это либо видно из кода, либо закреплено проверками, либо лежит в тематических документах.

Амнезия между сессиями: файл инструкций плюс файл плана

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

Не путайте два файла. Инструкции меняются редко и касаются всех задач. План меняется каждую сессию и касается текущей задачи. Если смешать их, файл инструкций быстро разрастётся устаревшими заметками.

Как проверить, что файл работает

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

Итог

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