AGENTS.md: как объяснить ИИ-агенту правила проекта
Neaptide · 6 сентября 2026 г. · 7 мин чтения
Как составить 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, приоритет имеет override; содержимое этих двух файлов не объединяется. Правила ближе к рабочей папке уточняют общие. Это порядок работы Codex — другие агенты могут читать инструкции иначе.
Вложенный AGENTS.md нужен, если у раздела есть собственные команды или требования. Например, в корне описана сборка приложения, а в content/blog — работа со статьями. Дублировать один текст во всех папках не нужно.
Как убедиться, что файл работает
- Проверьте имя файла и рабочую папку, из которой запускается задача.
- После изменения инструкций начните новый запуск и попросите перечислить применённые файлы и связанные с задачей правила.
- Дайте небольшую реальную правку. Посмотрите на изменённые пути, команды и результат, а не только на обещание агента.
- Если правило не выполнено, проверьте противоречия с другими инструкциями и наличие AGENTS.override.md. Затем уточните неоднозначную формулировку.
Перед изменениями перечисли применимые файлы инструкций, рабочую папку и команды проверки, которые относятся к этой задаче. Затем выполни правку и покажи, чем подтверждён результат.Пересказ правил помогает заметить, какие инструкции агент прочитал, но не подтверждает их выполнение. Смотрите на изменённые файлы и результаты команд. У Codex также есть общий лимит объёма загружаемых инструкций проекта. Если файлы слишком велики, часть текста может не попасть в контекст, поэтому длинные инструкции стоит сокращать.
Что нельзя обеспечить только инструкцией в файле
Просьба «не трогай секреты» не заменяет ограничения доступа, а требование запустить тест — автоматическую проверку в CI. Права инструментов, защиту веток и проверки настраивают отдельно. Ключи и пароли в AGENTS.md или его примеры добавлять не следует.
Обновляйте AGENTS.md, когда меняются структура проекта и команды. Новое правило полезно добавлять после повторяющейся ошибки и проверять на следующей задаче. Устаревшие указания удаляйте: файл должен помогать выполнять текущую работу, а не хранить историю всех замечаний.