AGENTS.md: как объяснить ИИ-агенту правила проекта
Neaptide · 6 сентября 2026 г. · 7 мин чтения · Обновлено: 3 октября 2026 г.
Как составить AGENTS.md для проекта: какие правила записать, куда поместить файл и как проверить их выполнение в Codex. Пример и шаблон для скачивания.
В этой статье
Если агент каждый раз сохраняет статью не в той папке или предлагает несуществующую команду проверки, удобнее записать постоянное правило, чем повторять его в чате. Для этого есть AGENTS.md, Markdown-файл с инструкциями по работе над проектом. Полезнее всего в нём договорённости, которые из кода надёжно не вычитать.
Начните с конкретных указаний: где менять содержание, какую команду использовать для проверки и что считать готовым результатом. Фраза «пиши качественный код» почти ничего не объясняет. А вот по правилу «сохраняй адреса опубликованных статей и проверяй сборку после правок» уже понятно, что делать.
Чем AGENTS.md отличается от README и скилла
| Место | Что хранить |
|---|---|
| README | Как человеку установить, запустить и понять проект |
| AGENTS.md | Постоянные правила работы агента с этим проектом |
| Скилл (навык) | Инструкцию для повторяющейся задачи: исследования, редактуры или проверки |
| Сообщение в задаче | Что нужно сделать сейчас и какое исключение разрешено |
Не переносите в AGENTS.md всю документацию. Укажите путь к нужному разделу и объясните, когда его читать. Когда команда изменится, не придётся править одно и то же описание в нескольких местах.
Короткий пример для контентного сайта
Пример ниже основан на структуре нашего сайта: указанные пути и команда сборки в проекте существуют. Для своего проекта проверьте и замените их. Шаблон скачивается как .txt; после адаптации сохраните его под именем AGENTS.md в нужной папке.
# Работа с проектом
- Перед правкой прочитай package.json и соседние файлы.
- Статьи хранятся в content/blog/articles; не помещай их в словарь интерфейса.
- Сохраняй slug опубликованной статьи, если задача не требует смены адреса.
- После изменения контента выполни npm run build.
- Для новой логики запускай относящиеся к ней проверки из scripts.
- В отчёте укажи выполненные проверки и оставшиеся ограничения.Каждая команда в инструкции должна существовать в проекте. Например, npm test не стоит переносить из чужого шаблона, если такого скрипта у вас нет. Проверки подбирайте под изменение: ради небольшой правки подписи полный аудит не нужен.
Как Codex выбирает инструкции
По документации Codex, инструкции собираются один раз при запуске. Сначала читаются глобальные правила, затем файлы по пути от корня проекта до текущей рабочей папки. Если в одной папке есть AGENTS.override.md и AGENTS.md, приоритет имеет AGENTS.override.md; содержимое этих двух файлов не объединяется. Правила ближе к рабочей папке уточняют общие. Так устроен именно Codex, другие агенты могут читать инструкции иначе.
Вложенный AGENTS.md нужен, если у раздела есть собственные команды или требования. Например, в корне описана сборка приложения, а в content/blog — работа со статьями. Дублировать один текст во всех папках не нужно.
Как убедиться, что файл работает
- Проверьте имя файла и рабочую папку, из которой запускается задача.
- После изменения инструкций начните новый запуск и попросите перечислить применённые файлы и связанные с задачей правила.
- Дайте небольшую реальную правку. Посмотрите на изменённые пути, команды и результат, а не только на обещание агента.
- Если правило не выполнено, проверьте противоречия с другими инструкциями и наличие AGENTS.override.md. Затем уточните неоднозначную формулировку.
Перед изменениями перечисли применимые файлы инструкций, рабочую папку и команды проверки, которые относятся к этой задаче. Затем выполни правку и покажи, чем подтверждён результат.После пробной задачи откройте изменённые файлы и журнал команд. Статья попала в нужную папку? Запущена команда из проекта, а не из чужого шаблона? По этому и видно, сработали ли правила. Пересказ агента лишь помогает понять, что он прочитал. У Codex есть общий лимит на объём инструкций проекта (по умолчанию 32 КиБ). Если файл разрастается, сокращайте повторы и переносите подробности в документы, на которые можно сослаться.
Что нельзя обеспечить только инструкцией в файле
Просьба «не трогай секреты» не заменяет ограничения доступа, а требование запустить тест — автоматическую проверку в CI. Права инструментов, защиту веток и проверки настраивают отдельно. Ключи и пароли не добавляйте ни в AGENTS.md, ни в его примеры.
Когда ошибка повторилась, добавьте правило, которое объясняет нужное действие, и проверьте его на следующей задаче. При смене структуры или команды сборки сразу обновите инструкцию. Старые замечания, которые больше ни на что не влияют, удаляйте, иначе при чтении придётся отделять действующие правила от истории проекта.