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

22 октября разработчик Дейв Кисс процитировал в X одно правило из инструкций для агентов в репозитории opencode. Правило взято из 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.

По-русски: прежде чем усложнять код ради гипотетической гонки11Гонка (race condition) это ошибка, при которой результат зависит от порядка выполнения параллельных операций. Обычная защита от неё блокировка, например мьютекс: он пускает к общим данным только один поток за раз. или маловероятной уязвимости, объясни пользователю конкретный сценарий сбоя, его вероятность и цену сложности и получи согласие. Не расширяй задачу молча ради теоретической надёжности.

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

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

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

Codex, по своей документации, склеивает файлы от корня проекта до текущей папки33В одной папке Codex выбирает только один файл инструкций. Непустой AGENTS.override.md заменяет соседний AGENTS.md целиком. Если правила будто пропали, проверьте наличие override-файла, в том числе в ~/.codex: порядок поиска., и более близкий идёт позже, поэтому перевешивает. Когда склеенный текст доходит до 32 КиБ (порог по умолчанию), следующие файлы уже не добавляются.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Поэтому 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: они загружаются, когда агент открывает подходящие файлы. Многошаговые процедуры вроде релиза лучше оформить скилом.

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

Добавляйте правило, когда агент ошибся одинаково второй раз, и формулируйте его через этот сбой. Удаляйте правило, когда оно устарело. Сами разработчики opencode в октябре сделали коммит с названием «docs: trim agent instructions» и подрезали файл до 186 строк. К 11 ноября 2026 года файл снова вырос, до 222 строк. В Claude Code команда /doctor prompt-audit88По умолчанию аудит проверяет CLAUDE.md, CLAUDE.local.md и AGENTS.md, а ещё правила, скилы, команды и субагентов в .claude/. Одному файлу или папке передают путь: /doctor prompt-audit .claude/skills/deploy. Нужна версия 2.1.283 или новее. ищет в инструкциях противоречия, ссылки на несуществующие файлы и правила, написанные под старые модели.

Как устроены CLAUDE.md, автопамять и компактинг, подробно описано в статье о контексте и памяти в Claude Code.

Курсы по теме

У каждого курса есть бесплатная часть: оставьте почту и начните сразу.

Рассылка

Раз в месяц — новые курсы, обновления программ и платформы. Отписаться можно в один клик из любого письма.

Начните учиться сегодня

Все курсы за 1500 ₽ в месяц. Доступ откроется сразу после оплаты, отменить можно в любой момент.

Для компаний — 5000 ₽ в месяц за сотрудника