Для чего нужен файл AGENTS.md
ИИ-агент может читать проект и редактировать файлы, но не всегда знает внутренние соглашения команды. Например, в репозитории могут использоваться собственные правила именования, особая последовательность команд тестирования или запрет на изменение автоматически сгенерированного кода.
Файл AGENTS.md позволяет изложить эти требования в одном месте. Вместо повторения длинных пояснений при каждом обращении к агенту разработчик сохраняет их вместе с проектом. Это особенно полезно, когда над кодовой базой работают несколько человек и каждый использует совместимый AI-инструмент.
Что обычно пишут в AGENTS.md
Содержимое файла зависит от проекта. Чаще всего в него включают:
- Ориентиры по репозиторию: где находятся исходники, тесты, конфигурации и основные модули.
- Правила работы с кодом: соглашения по стилю, допустимые зависимости, требования к именованию и обработке ошибок.
- Команды проверки: как установить зависимости, собрать проект, запустить линтер и тесты (например,
npm test). - Ограничения: какие каталоги нельзя изменять, когда нужна ручная проверка и что требуется сделать перед завершением задачи.
Полезнее записывать конкретные исполнимые правила, чем абстрактные указания вроде «пиши качественный код». Например, требование «после изменения обработчика запусти тесты соответствующего модуля» дает агенту понятный критерий завершения работы.
Как AI-инструменты используют инструкции
Совместимые агенты могут автоматически искать AGENTS.md при открытии проекта или запуске задачи. Файл часто размещают в корне репозитория. Для больших проектов допускаются дополнительные файлы в отдельных директориях, чтобы установить правила для конкретных частей кодовой базы. Точный порядок поиска и приоритет инструкций зависят от инструмента.
Например, в Kodik инструкции загружаются с учетом расположения рабочей директории. Для отдельного каталога можно использовать AGENTS.override.md, если нужно переопределить обычные инструкции. Подробнее механизм описан в документации Kodik по AGENTS.md.
AGENTS.md, README.md и Agent Skills: в чем разница
Эти файлы решают разные задачи:
- README.md в первую очередь помогает человеку понять назначение проекта, порядок установки и запуска.
- AGENTS.md сообщает ИИ-агенту, как ему действовать в репозитории и каких ограничений придерживаться.
- Agent Skills содержат инструкции и материалы для отдельных повторяемых сценариев: например, аудита кода или создания тестов.
Документы могут дополнять друг друга. README рассказывает о проекте, AGENTS.md задает общие правила работы агента, а соответствующий skill помогает выполнить конкретную задачу. При этом AGENTS.md — обычный текстовый файл, а не механизм принудительного запрета: критичные ограничения нужно дополнительно обеспечивать правами доступа и проверками.