Как написать AGENTS.md, который действительно помогает вашему ИИ-кодинг-агенту

Если вы использовали ИИ-кодинг-агента на реальном проекте, вы наверняка натыкались на момент, когда он запускает неверную команду теста, игнорирует ваш форматтер или заново изобретает хелпер, который у вас уже есть. Решение обычно не в более умной модели — а в том, чтобы дать агенту специфичный для проекта контекст, который он не может вывести сам. Для этого и существует файл AGENTS.md.

Что такое AGENTS.md

AGENTS.md — это простой открытый формат Markdown, который даёт кодинг-агентам предсказуемое место, где найти контекст и инструкции проекта. Он начался как сотрудничество OpenAI Codex, Amp, Google Jules, Cursor и Factory, а теперь курируется Agentic AI Foundation под эгидой Linux Foundation. Его читают более 25 инструментов — включая Codex, Cursor, VS Code, GitHub Copilot, Aider, Windsurf, JetBrains Junie, Zed и goose — и он встречается более чем в 60 000 open-source-репозиториев.

Представьте его как README, написанный для агента, а не для человека: README объясняет ваш проект новому участнику; AGENTS.md сообщает агенту то, что он иначе угадал бы неверно. (Пользователи Claude Code узнают CLAUDE.md как эквивалент; многие команды держат оба или делают симлинк одного на другой.)

Куда он кладётся

Положите AGENTS.md в корень репозитория. В монорепозитории добавьте вложенные файлы внутри каждого пакета — агенты читают ближайший файл в дереве каталогов, так что packages/api/AGENTS.md имеет приоритет над корневым, когда агент работает в той папке. Это позволяет Python-сервису и TypeScript-фронтенду получить каждому свои инструкции.

Что в него класть

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

• Команды сборки и тестирования — точные команды, а не приближения
• Стиль кода — форматтер, линтер и любые соглашения, которые линтер не отловит
• Инструкции по тестированию — как запустить один тест, что должно пройти, прежде чем изменение готово
• Соображения безопасности — файлы или операции, которые никогда не трогать
• Соглашения по коммитам / PR — формат сообщений, именование веток
• Шаги деплоя — только если предполагается, что агент будет их касаться

Вот минимальный, с высоким соотношением сигнал/шум пример:

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (do NOT run in CI)
- Test a single file: `pnpm vitest run path/to/file.test.ts`
- Lint + typecheck before any commit: `pnpm check`

## Conventions
- Use the existing `db()` helper in `src/lib/db.ts`; never open a raw client.
- Dates are stored as UTC ISO strings. Never use `Date.now()` in tests.

## Do not touch
- `src/generated/**` is codegen output. Edit the schema, then run `pnpm gen`.

Заметьте, чего там нет: ни лекции по архитектуре, ни пересказа структуры папок, ни «это современное веб-приложение, построенное по лучшим практикам». Это намеренно.

Короче обычно лучше

Есть соблазн попросить агента сгенерировать вам гигантский AGENTS.md. Не поддавайтесь. Исследование ETH Zurich 2026 года, освещённое InfoQ, измерило реальное влияние этих файлов и обнаружило, что эффект незначительный и неоднозначный. Сгенерированные LLM файлы контекста на деле снижали показатели успешности задач в среднем примерно на 3%, повышая при этом стоимость инференса более чем на 20%. Написанные людьми файлы помогали умеренно — рост успешности примерно на 4% — но всё равно подталкивали агентов делать больше шагов, увеличивая стоимость до ~19%.

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

Иными словами, каждая строка должна заслужить своё место, предотвращая конкретную ошибку, которую вы реально видели у агента.

Рабочий процесс, который работает

1. Начните с пустого. Не пишите AGENTS.md, пока не увидели, как агент что-то делает неверно.
2. Добавляйте исправление, а не теорию. Когда он запускает неверную команду теста, добавьте правильную. Когда он переформатирует файл по-своему и линтер ругается, добавьте правило.
3. Держите кратко. Если строка лишь пересказывает то, что агент мог прочитать из package.json или имён папок, удалите её.
4. Используйте вложенность для монорепозиториев, чтобы файл каждого пакета оставался маленьким.
5. Перечитывайте раз в месяц. Устаревшие инструкции хуже их отсутствия — агент, следующий устаревшей команде сборки, проваливается уверенно.

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