Что писать в AGENTS.md, чтобы агент работал лучше

22 октября разработчик Дейв Кисс процитировал в X одно правило из инструкций для агентов в репозитории opencode, и пост собрал больше 4000 лайков. Правило взято из AGENTS.md проекта, из раздела о стиле кода:

Before adding complexity for a speculative or vanishingly unlikely race or security edge case, explain the concrete failure mode, likelihood, and complexity cost to the user and get their buy-in. Do not silently expand scope for theoretical robustness.

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

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

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

AGENTS.md это открытый формат, обычный Markdown в корне репозитория. Создатели называют его README для агентов: туда идёт то, что загромоздило бы README для людей, то есть команды сборки, тесты, соглашения по коду. Формат ведёт Agentic AI Foundation при Linux Foundation, его используют больше 60 тысяч опенсорс-проектов, а читают Codex, Cursor, opencode, GitHub Copilot, Gemini CLI и десятки других агентов. В монорепозитории файлов может быть несколько: агент читает ближайший к файлу, который правит, а прямая просьба в чате важнее любого из них.

Codex, по своей документации, склеивает файлы от корня проекта до текущей папки, и более близкий идёт позже, поэтому перевешивает. Когда склеенный текст доходит до 32 КиБ (порог по умолчанию), следующие файлы уже не добавляются.

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

Главное свойство этих файлов: агент загружает их в начале сеанса целиком, до того как вы что-то попросили. Документация Anthropic отдельно предупреждает, что CLAUDE.md это контекст, а не принудительная настройка. Агент читает правило и сам решает, как его применить. Поэтому от формулировки зависит, что он сделает.

Почему правило opencode работает

В нём четыре части. Оно называет конкретное поведение: усложнение ради спекулятивных гонок и уязвимостей. Задаёт условие, когда срабатывает: перед тем как добавить сложность. Говорит, что делать вместо этого: описать сценарий, вероятность и цену и спросить. И закрывает лазейку: не расширять задачу молча.

Агент может сам проверить, выполнил ли он такое правило. Он либо спросил перед тем, как добавить мьютекс, либо нет. С правилом «пиши простой код» так не выйдет: модель и так считает свой код простым.

Правило не запрещает думать о безопасности. Оно переносит решение к человеку, у которого есть контекст: насколько вероятен сбой и сколько стоит лишняя сложность в поддержке.

Какие правила меняют поведение

Anthropic в документации даёт простой тест: инструкция должна быть достаточно конкретной, чтобы её можно было проверить. «Отступ два пробела» вместо «форматируй аккуратно». «Запускай npm test перед коммитом» вместо «тестируй изменения». «Обработчики API лежат в src/api/handlers/» вместо «держи файлы в порядке».

По нашему опыту, полезнее всего правила четырёх видов. Команды, которые агент сам не угадает. Границы: какие папки не трогать и какие действия согласовывать. Ошибки, которые агент уже совершал в этом проекте. И рамки задачи, как в правиле opencode. Пример такого набора:

## Команды
- Пакеты ставь через `pnpm`, не через npm и yarn.
- Перед коммитом запусти `pnpm lint && pnpm test`. Если тест упал,
  исправь причину. Не отключай и не удаляй тест, чтобы он прошёл.
- Тесты запускай из папки пакета, не из корня репозитория.

## Границы
- Не редактируй `src/generated/`: эти файлы собирает `pnpm generate`.
- Старые миграции в `db/migrations/` не меняй, пиши новую.
- Новую зависимость добавляй, только когда объяснил, зачем она
  и почему не хватает уже установленных.

Ещё одно правило из обсуждений этой недели предложил Блейк Янг, у его поста почти 2000 лайков. Смысл такой: незнакомую функцию не пиши сразу с нуля, сначала найди на GitHub живые проекты с понятной лицензией и сравни подходы. В виде правила:

## Перед новой функциональностью
- Если задача незнакомая (парсер формата, синхронизация, платёжный
  поток), сначала найди 2–3 поддерживаемых опенсорс-проекта
  с понятной лицензией, сравни их подходы, зависимости и известные
  проблемы и покажи мне вывод. Не копируй код с несовместимой или
  неясной лицензией.

Это правило тоже проверяемое: агент либо показал сравнение до того, как писать код, либо нет.

Чего в файл не писать

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

То, что агент найдёт сам. Структуру папок и стек он увидит, открыв package.json. Команда /init в Claude Code сама составляет черновик файла по коду, а дописывать документация советует только то, чего Claude не узнает из кода.

То, что проверяет машина. Документация Codex в разделе о правилах для ревью советует оставить форматирование и линтер на CI. Отступы надёжнее задать в конфиге форматтера, чем просить словами.

Жёсткие запреты. Если действие нельзя допускать ни при каких условиях, например rm -rf или пуш в main, правило в файле не гарантия. В Claude Code для этого есть хук PreToolUse и правила разрешений, которые срабатывают независимо от решения модели.

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

Шесть файлов и один короткий

Другой популярный пост недели, от Сураджа Шармы, советует завести шесть файлов до начала вайбкодинга: PRD, архитектуру, дизайн, правила, задачи и прогресс. С мыслью мы согласны: без записанного плана агент угадывает. Но если все шесть грузить в каждый сеанс, получится раздутый контекст.

Anthropic советует держать CLAUDE.md короче 200 строк: длинный файл занимает больше контекста, и агент хуже его соблюдает. Импорт через @ здесь не спасает: импортированный файл грузится целиком вместе с основным. Ссылка словами работает иначе. Если написать, где лежит документ и когда его читать, агент откроет его, только если сам решит, что задача до него дошла.

Поэтому AGENTS.md удобно держать оглавлением: коротко о проекте, команды, правила и указатели на остальное.

# Запись к мастеру
Next.js, PostgreSQL, оплата через Stripe.

## Команды
- `pnpm dev`, `pnpm test`, `pnpm lint`

## Правила
- Перед защитой от маловероятного сбоя опиши сценарий,
  вероятность и цену и спроси меня.

## Где читать подробнее
- `docs/architecture.md`: перед изменением схемы БД или API.
- `docs/design.md`: перед правками интерфейса.
- `PROGRESS.md`: в начале работы, что сделано и что сломано.

Правила, нужные только части кода, в Claude Code выносят в .claude/rules/ с полем paths: они загружаются, когда агент открывает подходящие файлы. Многошаговые процедуры вроде релиза лучше оформить скилом.

Как вести файл