Как написать AGENTS.md: что объяснить AI-агенту до старта

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

Вот и весь файл. Три раздела, десять строк. Агент перестает угадывать и начинает работать. Вся хитрость в этом.

Почему без AGENTS.md все ломается

AI-агент — это не волшебник. Это очень старательный новичок, который не знает контекста. Он приходит в чужой проект и начинает действовать по своим представлениям. А представления у модели, мягко говоря, общие.

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

AGENTS.md решает эту проблему. Это короткий документ, который говорит агенту: «Вот правила этой территории». Не общие принципы, а конкретные границы.

Что именно должно быть в AGENTS.md

Три раздела. Больше не нужно.

1. Что такое хорошо

Опишите, как выглядит хорошая работа в этом репозитории. Это может быть:

• стиль кода, который принят в проекте;
• обязательные тесты и линтеры перед коммитом;
• структура файлов, которой надо придерживаться;
• примеры удачных решений, на которые можно ориентироваться.

Без этого агент будет делать «красиво» по своему разумению. А красота — штука субъективная.

2. Что под запретом

Один абзац, который явно перечисляет, что трогать нельзя. Например:

• не редактировать миграции;
• не менять конфигурацию CI;
• не трогать прод-данные даже в тестах;
• не переписывать чужие модули без явной команды.

Запреты лучше формулировать узко. «Не делай странного» не работает. А вот «не меняй файлы в папке /vendor» работает отлично.

3. Когда останавливаться и спрашивать

Самый недооцененный пункт. Агент должен знать, в каких случаях он не имеет права действовать сам. Например:

• если задача неоднозначна;
• если правка затрагивает несколько модулей;
• если нужно удалить код, который используется в другом месте.

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

Почему это работает

Агент — это система, которая принимает решения на основе подсказок. Если подсказки четкие, решения тоже четкие. Вы не можете контролировать каждый его шаг, но вы можете задать рамки, в которых он волен действовать.

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

Как внедрить AGENTS.md в свой проект

Практические шаги:

1. Создайте файл AGENTS.md в корне репозитория.
2. Запишите в него три раздела, описанных выше. Не пишите абстрактно — приводите примеры.
3. Обновите его, когда правила меняются. Это живой документ.
4. Добавьте файл в ревью при изменениях — вы же хотите, чтобы команда была в курсе.

Один нюанс: не путайте AGENTS.md с README. В README — как запустить проект, в AGENTS.md — как себя вести агенту. Это разные вещи.

Типичные ошибки

Часто видят файл, который либо ничего не объясняет, либо пытается объять необъятное.

Ошибка №1: Написать «будь аккуратен». Это бессмысленно. Нужно показать, что значит «аккуратен» в конкретной кодовой базе.

Ошибка №2: Не указать, когда спрашивать. Агент по умолчанию делает. Если вы не дадите ему права сомневаться, он будет ошибаться.

Ошибка №3: Слишком длинный файл. Агент читает инструкции в начале контекста, и длинные простыни съедают его лимиты. Десять строк — то, что надо.

Ошибка №4: Не обновлять файл. Через месяц проект меняется, а AGENTS.md остается в прошлом. Агент следует старым правилам и ломает то, что уже перестроили.

Ошибка №5: Не проверить на реальном примере. Скормите файл агенту и посмотрите, как он решает маленькую задачу. Если ведет себя не так, как ожидали, — правите AGENTS.md, а не ругаете агента.

Сравнение трех разделов

Когда AGENTS.md нужен, а когда — нет

AGENTS.md полезен, когда вы регулярно используете агентов в репозитории. Это может быть автогенерация кода, автоматизированные правки, ассистент в CI. Если агент заходит в проект редко — возможно, хватит обычного README и пары комментариев.

Но если вы видите, что агент раз за разом делает одно и то же неправильно — не переписывайте ему промпт каждый раз. Один раз опишите правила в AGENTS.md. Дальше он будет вести себя как надо.

Итог простой: научите агента вашим правилам игры. Три раздела, десять строк, ноль догадок. Это лучшая инвестиция в качество автоматизации.