AGENTS.md хранит постоянные правила работы ИИ-агента в конкретном репозитории: структуру проекта, команды, границы изменений, обязательные проверки и формат доказательств. Хороший файл не пересказывает общие советы по программированию. Он объясняет, чем этот код отличается от типового проекта, какие источники считаются каноническими и что агент обязан показать перед завершением задачи.
Опишите корневой рабочий контракт
В корневом AGENTS.md укажите карту каталогов, поддерживаемую среду, менеджер зависимостей, безопасную установку, форматирование, тесты и правила для сгенерированных файлов. Назовите команды точно. Объясните, после каких изменений запускается каждая проверка и что делать, если внешняя среда недоступна. Отдельно закрепите сохранение чужих изменений в рабочем дереве и запрет на прямое редактирование производных артефактов.
Формулируйте наблюдаемые действия. Инструкция запустить набор модульных тестов после изменения логики проверяема. Требование работать качественно не задаёт поведения. Привязывайте каждое правило к риску, владельцу и подтверждению. Перед созданием сложного агентного контура можно использовать три вопроса перед покупкой ИИ, чтобы отделить полезный рабочий контракт от попытки автоматизировать неопределённый процесс.
Не помещайте в файл секреты, персональные данные и ключи. AGENTS.md может указать, какой доступ нужен и кто его согласует, но не должен хранить значение. Поведенческая инструкция также не заменяет песочницу, права учётной записи, защиту веток или проверки непрерывной интеграции.
Добавляйте вложенные правила только для различий
Codex собирает инструкции от глобального уровня и корня проекта к текущему рабочему каталогу. Более близкий файл применяется позже и может уточнить широкое правило. В одном каталоге override имеет приоритет над обычным AGENTS.md. Поэтому общие требования остаются в корне, а специальный контроль располагается рядом с той частью кода, где он нужен.
Представьте монорепозиторий с приложением, библиотеками и каталогом базы данных. Корневой файл задаёт установку, общий линтер, модульные тесты, правило документации и запрет внешних отправок. В каталоге базы данных AGENTS.override.md заменяет обычную проверку на тест совместимости миграций, запрещает разрушительные изменения схемы без явного разрешения и требует план возврата для изменения данных.
Не копируйте в override весь корневой текст. Дублирование быстро расходится и скрывает намеренное отличие. Вложенный файл содержит только замену команды, дополнительную границу или исключение. После изменения инструкций запускайте новую сессию, потому что цепочка собирается при старте.
Сравните одинаковые задачи до и после правил
Подготовьте две ограниченные задачи: изменение обычного модуля и изменение миграции в каталоге базы данных. До добавления правил сохраните источники инструкций, предложенные команды, изменённые файлы, результаты проверок и запросы разрешений. Это исходный след, а не обещание улучшения.
После добавления корневого и вложенного файлов повторите те же задачи. Обычный модуль должен использовать общие команды. Работа с миграцией наследует корневые ограничения, но применяет специальную проверку и требует разрешение на опасное действие. Проверяйте реальный diff и вывод команд. Тесты перед внедрением ИИ помогают добавить неполную задачу, конфликт правил и недоступную проверочную среду.
Проверьте отрицательный сценарий: запустите задачу из соседнего каталога, где специальный override не должен применяться. Агент обязан использовать только корневые правила и не переносить команду миграций в обычный модуль. Такая проверка показывает, что область действия определяется расположением файла, а не случайным упоминанием каталога в тексте задачи.
Следите за размером и противоречиями цепочки. Если важное правило перестало появляться в отчёте об активных инструкциях, сократите повторения и перенесите детали в ближайший файл. При конфликте формулировок явно укажите, какое правило заменяется и почему. Критичные ограничения лучше дополнительно закрепить в автоматической проверке, потому что документ направляет агента, но не блокирует команду технически.
Назначьте владельца корневого файла и каждого специализированного override. При изменении сборки, тестов или структуры каталога тот же pull request обновляет инструкцию либо подтверждает её актуальность. Устаревшая точная команда опаснее общего совета, потому что агент уверенно воспроизводит неправильный маршрут и может представить его как завершённую проверку.
Частые вопросы
Укажите структуру, среду, точные команды, канонические файлы, границы прав, обязательные тесты, правила ревью и доказательства завершения.
Codex объединяет файлы от корня к рабочему каталогу, поэтому более близкая инструкция уточняет или заменяет широкое правило для своего поддерева.
Он нужен там, где обычное правило каталога следует намеренно заменить, например специальной командой проверки или более строгой границей доступа.
Повторите одинаковые ограниченные задачи и сравните загруженные правила, команды, изменённые файлы, разрешения, тесты и проверенный diff.
Не принимайте самоотчёт агента как доказательство. Сверяйте выполненные команды, коды завершения, список файлов и результаты независимого ревью. Для числовых отчётов пригодятся правила против выдуманных фактов ИИ-агентов. Когда правило предупреждает повторяющуюся ошибку, добавьте соответствующую регрессионную задачу. Если нужно спроектировать агентный workflow и его repo-контракт, обсудите разработку ИИ-агентов с MYOD.
