Если вы подключаете AI-агента к репозиторию, не ждите, что он сам поймет правила. Ему нужен файл AGENTS.md. Идея простая: до того как агент напишет первую строчку кода, он должен узнать три вещи: как выглядит хорошая работа в этом репо, что под запретом и когда лучше остановиться и спросить.
Вот и весь файл. Три раздела, десять строк. Агент перестает угадывать и начинает работать. Вся хитрость в этом.
Почему без AGENTS.md все ломается
AI-агент — это не волшебник. Это очень старательный новичок, который не знает контекста. Он приходит в чужой проект и начинает действовать по своим представлениям. А представления у модели, мягко говоря, общие.
В итоге агент форматирует код не так, как принято в команде, трогает файлы, которые не стоило трогать, и делает рефакторинг там, где нужно было просто поправить баг. Ревью превращается в бесконечный список комментариев. Или еще хуже — агент «улучшает» код и ломает прод.
AGENTS.md решает эту проблему. Это короткий документ, который говорит агенту: «Вот правила этой территории». Не общие принципы, а конкретные границы.
Что именно должно быть в AGENTS.md
Три раздела. Больше не нужно.
1. Что такое хорошо
Опишите, как выглядит хорошая работа в этом репозитории. Это может быть:
- стиль кода, который принят в проекте;
- обязательные тесты и линтеры перед коммитом;
- структура файлов, которой надо придерживаться;
- примеры удачных решений, на которые можно ориентироваться.
Без этого агент будет делать «красиво» по своему разумению. А красота — штука субъективная.
2. Что под запретом
Один абзац, который явно перечисляет, что трогать нельзя. Например:
- не редактировать миграции;
- не менять конфигурацию CI;
- не трогать прод-данные даже в тестах;
- не переписывать чужие модули без явной команды.
Запреты лучше формулировать узко. «Не делай странного» не работает. А вот «не меняй файлы в папке /vendor» работает отлично.
3. Когда останавливаться и спрашивать
Самый недооцененный пункт. Агент должен знать, в каких случаях он не имеет права действовать сам. Например:
- если задача неоднозначна;
- если правка затрагивает несколько модулей;
- если нужно удалить код, который используется в другом месте.
Лучше пусть агент задаст лишний вопрос, чем молча сделает то, что потом придется откатывать.
Почему это работает
Агент — это система, которая принимает решения на основе подсказок. Если подсказки четкие, решения тоже четкие. Вы не можете контролировать каждый его шаг, но вы можете задать рамки, в которых он волен действовать.
И вот что важно: файл должен быть коротким. Двенадцать страниц устава никто не читает, включая агента. Десять строк — идеальный размер. В них умещается и критерий качества, и запреты, и правило «спроси, если сомневаешься».
Как внедрить AGENTS.md в свой проект
Практические шаги:
- Создайте файл AGENTS.md в корне репозитория.
- Запишите в него три раздела, описанных выше. Не пишите абстрактно — приводите примеры.
- Обновите его, когда правила меняются. Это живой документ.
- Добавьте файл в ревью при изменениях — вы же хотите, чтобы команда была в курсе.
Один нюанс: не путайте AGENTS.md с README. В README — как запустить проект, в AGENTS.md — как себя вести агенту. Это разные вещи.
Типичные ошибки
Часто видят файл, который либо ничего не объясняет, либо пытается объять необъятное.
Ошибка №1: Написать «будь аккуратен». Это бессмысленно. Нужно показать, что значит «аккуратен» в конкретной кодовой базе.
Ошибка №2: Не указать, когда спрашивать. Агент по умолчанию делает. Если вы не дадите ему права сомневаться, он будет ошибаться.
Ошибка №3: Слишком длинный файл. Агент читает инструкции в начале контекста, и длинные простыни съедают его лимиты. Десять строк — то, что надо.
Ошибка №4: Не обновлять файл. Через месяц проект меняется, а AGENTS.md остается в прошлом. Агент следует старым правилам и ломает то, что уже перестроили.
Ошибка №5: Не проверить на реальном примере. Скормите файл агенту и посмотрите, как он решает маленькую задачу. Если ведет себя не так, как ожидали, — правите AGENTS.md, а не ругаете агента.
Сравнение трех разделов
| Раздел | Что писать | Зачем |
|---|---|---|
| Что такое хорошо | Критерии качества, стиль, обязательные проверки | Агент знает целевую точку и не выдумывает свои стандарты |
| Что под запретом | Конкретные файлы, папки, операции | Предотвращает катастрофы до того, как они случились |
| Когда спрашивать | Ситуации неопределенности или зоны особого риска | Агент вовремя останавливается и не делает лишнего |
Когда AGENTS.md нужен, а когда — нет
AGENTS.md полезен, когда вы регулярно используете агентов в репозитории. Это может быть автогенерация кода, автоматизированные правки, ассистент в CI. Если агент заходит в проект редко — возможно, хватит обычного README и пары комментариев.
Но если вы видите, что агент раз за разом делает одно и то же неправильно — не переписывайте ему промпт каждый раз. Один раз опишите правила в AGENTS.md. Дальше он будет вести себя как надо.
Итог простой: научите агента вашим правилам игры. Три раздела, десять строк, ноль догадок. Это лучшая инвестиция в качество автоматизации.
Fluxs
Комментарии (0)
Войдите, чтобы комментировать.
Пока нет комментариев. Будьте первым.