Как AGENTS.md делает репозиторий понятным для агентов

AGENTS.md оправдывает свое место в репозитории, когда объясняет кодинг-агенту, как здесь на самом деле выполняют работу. Это не второй README, не длинный промпт с правилами поведения и не замена тестам. Полезный файл превращает знания, которыми команда делится устно, в инструкции, доступные агенту до правки кода: где работать, какими командами подтверждать изменение, какие границы соблюдать и какие местные соглашения слишком дорого выяснять заново.

Онбординг от этого меняется вполне практично. Новому инженеру все еще нужно понять продукт и архитектуру, но агент перестает тратить первые десять минут на догадки, что принято запускать в команде: npm test, цель Make или команду с фильтром для монорепозитория. Результат измеряется меньшим числом правдоподобных, но неверных изменений. За это команда получает еще один рабочий документ, за которым нужно следить, а устаревшие инструкции порой вреднее их отсутствия.

Что стандартизирует AGENTS.md, а что оставляет открытым

AGENTS.md стандартизирует место и соглашение, а не формальный язык конфигурации. Официальный проект AGENTS.md описывает его как предсказуемое место для контекста и инструкций, по смыслу похожее на README для кодинг-агентов. Это обычный файл Markdown. В нем нет обязательных полей, закрепленных заголовков, схемы парсера или официального словаря. Благодаря такой простоте несколько инструментов могут поддерживать формат, не принимая конфигурацию одного поставщика.

Различие важно: команды часто называют AGENTS.md стандартом, а затем считают, что все агенты обрабатывают его одинаково. Переносимая часть включает имя файла, понятное человеку содержимое и идею о том, что инструкции могут следовать за деревом каталогов. Момент обнаружения, максимальный размер, имена файлов-переопределений и приоритет относительно глобальных настроек определяет конкретный агент. Если работа зависит от такого поведения, сначала проверьте руководство инструмента, который запускается в репозитории.

Codex дает наглядный пример. В его документации сказано, что цепочка инструкций строится один раз при запуске: сначала идет глобальное руководство, затем Codex проходит от корня проекта к текущему рабочему каталогу. Файлы соединяются в этом порядке, поэтому текст ближе к рабочему каталогу оказывается позднее и может переопределить более ранние правила. Codex также распознает AGENTS.override.md, позволяет настроить резервные имена файлов и прекращает добавлять проектные инструкции при достижении заданного лимита в байтах. Это поведение Codex, а не общие обещания открытого формата.

Официальный сайт AGENTS.md формулирует принцип шире: разместите файл в корне репозитория, добавьте вложенные файлы для подпроектов и при конфликте отдавайте приоритет ближайшим подходящим инструкциям. Такой принцип хорошо переносится между инструментами. Конкретную реализацию все равно нужно тестировать. Агент, который читает только корневой файл, и агент, который постепенно обнаруживает вложенные файлы, могут получить разный контекст для одной задачи.

Считайте формат интерфейсом с небольшим общим ядром. Пишите переносимые инструкции простым Markdown. Отмечайте предположения о конкретном инструменте, когда они влияют на результат. Если автоматизация зависит от приоритетов, запустите реального агента из двух или трех типичных каталогов и попросите перечислить загруженные источники инструкций. Соглашению можно доверять лишь после проверки его потребителя.

Помещайте в файл рабочую правду

Лучшее содержимое отвечает на вопросы, для которых исходный код не дает быстрого ответа. Агент может изучить package.json, но не всегда поймет, какой из шести скриптов CI считает обязательным перед слиянием. Он может найти три клиента базы данных, но не узнать, что один оставили только для миграций. Он может прочитать каталог сервиса, однако пропустить, что интеграционным тестам нужна локальная зависимость и их нельзя направлять в общую среду. AGENTS.md должен прямо снимать такую неоднозначность.

Корневому файлу обычно нужны пять типов сведений:

• Краткая карта репозитория с каталогами основных приложений, общих пакетов, сгенерированных файлов и тестов.
• Точные команды настройки, сборки, линтинга, проверки типов и тестирования, в том числе узкая команда для одного пакета или теста.
• Архитектурные границы, которые проверяют на ревью, но не могут выразить статические инструменты, например слой для работы с хранилищем или обязательный клиент для всех сетевых запросов.
• Ограничения безопасности для секретов, миграций, продакшен-ресурсов, сгенерированных артефактов и разрушительных команд.
• Определение готовности с проверками и артефактами, которые требуются для распространенных типов изменений.

Конкретика важнее объема. «Запустите тесты» заставляет агента искать команду и выбирать ее самому. «Для изменений в packages/billing запустите make test-billing; полный набор нужен только при изменении общих схем» задает правило выбора. «Следуйте принятому стилю» вынуждает искать образцы в случайных файлах. «Используйте форматтер репозитория, типизируйте публичные функции и не редактируйте сгенерированные клиенты» сужает пространство решений.

Добавляйте запреты лишь тогда, когда они предотвращают уже встречавшуюся ошибку или понятный риск. Сотня запретов борется за внимание и скрывает правила, защищающие продакшен. Если агент снова и снова меняет сгенерированный файл, укажите, где лежит его исходник, и назовите команду генерации. Если никто не помнит причину запрета, запишите ее рядом или удалите правило.

Не копируйте целые разделы README, руководства для контрибьюторов или журналов архитектурных решений. Ссылаться на другие локальные файлы полезно, только когда инструмент умеет их читать, а инструкция объясняет, когда это делать. Фраза «Перед изменением аутентификации прочитайте docs/auth-boundaries.md» дает понятное действие. Каталог всех документов репозитория его не дает.

Область действия должна совпадать с границами владения

Вложенные AGENTS.md работают, когда дерево каталогов отражает реальное владение кодом. Общие для всех пакетов правила оставьте в корне, а локальные инструкции добавляйте там, где меняются команды, архитектура или риск. Пакету фронтенда могут понадобиться проверки скриншотов и правила компонентов. Платежному сервису могут понадобиться эмулятор, проверка миграций и явное разрешение перед работой с учетными данными. Если смешать все это в корневом файле, каждая задача будет платить контекстом за лишние сведения.

Обычная модель наследования складывает инструкции, пока локальное правило не вступит в конфликт с общим. Описывайте конфликт прямо: «В этом каталоге запускайте make test-payments вместо корневой команды npm test». Не заставляйте агента догадываться, что другая команда молча заменяет корневое правило. Явное описание переопределения помогает и людям.

Область действия может быть неудачной в обе стороны. Один огромный корневой файл дает агенту лишние инструкции и может упереться в лимиты реализации. Слишком много вложенных файлов превращают работу в поиск подсказок, особенно если имена каталогов не совпадают с границами команд. Я добавляю вложенный файл, только если ниже этого каталога меняется хотя бы одно: порядок сборки или тестирования, архитектурные правила, процесс релиза или граница безопасности.

Сгенерированным каталогам и стороннему коду полезно дать короткое локальное предупреждение, если агенты часто заходят туда. «Не редактируйте файлы здесь; пересоздайте их из schemas/ командой make clients» вполне достаточно. Повторять под ним разделы корневого файла о форматировании, PR и тестировании незачем.

У монорепозиториев есть неудобный крайний случай: агент, запущенный из корня, в зависимости от инструмента может не загрузить руководство пакета, пока не начнет работать внутри него. Агент, запущенный в пакете, может получить всю цепочку от корня до пакета. Проверьте оба входа. Если задача на уровне корня затрагивает несколько пакетов, держите межпакетные инварианты в корне, а подробности пакетов локально. Тогда правила, обязательные для каждого изменения, не будут зависеть от способа обнаружения файлов.

Полезный AGENTS.md легко просмотреть целиком

Первая версия должна помещаться на одном-двух экранах и описывать обычный путь. Команды часто отвечают на каждую ошибку агента новым абзацем. В итоге файл превращается в архив происшествий с противоречивыми правилами и устаревшими командами. Начните с минимального набора, который меняет поведение, наблюдайте за реальными запусками и расширяйте его только при наличии фактов.

Этот шаблон намеренно конкретен, но не притворяется, будто всем репозиториям нужны одинаковые заголовки:

# Repository working guide

## Repository map
- apps/web owns the customer application.
- packages/api owns request validation and persistence.
- generated contains derived clients; do not edit it directly.

## Commands
- Install: pnpm install
- Web checks: pnpm test -F web
- API checks: pnpm test -F api
- Full merge gate: make verify

## Change rules
- Keep database access inside packages/api.
- Update contract tests when a public response changes.
- Generate clients with make clients after editing schemas.

## Safety
- Never use production credentials for local tests.
- Ask before adding a runtime dependency or changing a migration.

## Done
- Run the narrow checks for the changed package.
- Run make verify when shared code or schemas change.
- Report commands run and any checks that could not run.

Он предотвращает хорошо знакомую цепочку ошибок. Без карты агент правит сгенерированный клиент, потому что видимая ошибка типа находится именно там. Без различия команд он запускает быстрый набор модульных тестов после изменения общей схемы и пропускает поломку контракта. Без определения готовности он может описать правку кода и умолчать, что недоступный сервис помешал интеграционным тестам.

Обратите внимание, чего в шаблоне нет: должности для агента, общего совета писать чистый код, требования усердно думать или подробных синтаксических правил, которые уже проверяет форматтер. Эти слова занимают контекст, но не разрешают специфичные для репозитория вопросы. Статическим правилам место в линтерах, форматтерах, системах типов и CI. AGENTS.md говорит агенту, какие проверки запускать и какие решения эти проверки не умеют формализовать.

Команды должны быть безопасны для прямого запуска. Указывайте каталог, если команда не работает из корня. Не оставляйте заполнители, когда существует настоящая узкая команда. Если для настройки нужны секреты, назовите переменную и безопасный источник, но не помещайте значение секрета в файл. Если команда способна изменить общие данные, не представляйте ее обычным шагом проверки.

Реальные репозитории используют его как рабочее руководство

Публичные проекты показывают, что хорошие файлы похожи скорее на сжатые знания сопровождающих, чем на промпты. Их ценность в деталях, которые компетентный участник в конце концов нашел бы сам, но лишь после чтения множества скриптов, файлов CI и комментариев с ревью.

Корневой AGENTS.md репозитория OpenAI Codex подробно описывает рабочие операции. В разделе Rust он задает правила именования крейтов, требует использовать just test вместо прямого вызова cargo test, предписывает запускать just fmt после изменений Rust и объясняет тестирование отдельных пакетов. Там же записаны менее очевидные особенности сборки: например, нужно обновлять объявления данных Bazel, если макросы Rust во время компиляции читают файлы из дерева исходников. Это сильный дизайн инструкций, потому что каждое правило указывает на конкретный выбор или известную поломку.

Тот же файл задает ограничения для размера модулей Rust и наборов изменений, затем подробно описывает соглашения терминального интерфейса. Неважно, согласится ли другая команда с этими порогами. Агенту в этом репозитории нужны настоящие ожидания сопровождающих на ревью, а не общие вкусы в Rust. Локальный файл инструкций подходит для таких ожиданий, когда автоматические проверки не закрывают их полностью.

Репозиторий GitHub awesome-copilot использует AGENTS.md для определения процесса выпуска контента. Он описывает каталоги агентов, инструкций, навыков, хуков и рабочих процессов, перечисляет точные команды сборки и проверки, задает обязательный front matter для нескольких типов файлов. В нем есть и список проверок для ревью. Копировать его структуру незачем. Стоит перенять другое: соединить карту репозитория, договор авторинга, команды генерации и шаги проверки в одном предсказуемом месте.

В репозитории документации LangChain есть docs/AGENTS.md, настроенный под работу с документацией. Он объясняет расположение контента, требования к front matter, специальные конструкции MDX и команду проверки битых ссылок. Еще полезнее описание реального формата вывода этой проверки: читателю сообщают, какие строки с отступом обозначают настоящие ошибки после фильтрации известных ложных срабатываний. «Запустите проверку ссылок» оставило бы агенту шумный вывод без объяснения; инструкция по интерпретации замыкает цикл.

OpenHands показывает другой конец шкалы. Его корневой файл фиксирует архитектурные границы, разделение тестов, правила доступа к API, поведение среды и точные заметки о регрессиях. Некоторые пункты называют опробованные ранее подходы, которые не сработали, и объясняют, почему к ним нельзя возвращаться. Это спасает сопровождающего от ситуации, когда агент «упрощает» код до уже известной ошибки. Пример показывает и риск сопровождения: длинному файлу с изменчивыми внутренними деталями нужны владельцы и регулярная чистка, иначе вчерашняя правильная инструкция завтра поведет изменение назад.

У этих примеров общий рисунок. Они называют реальные пути, команды, ожидаемый вывод и исключения. Ни одному не нужен мотивирующий текст. Репозиторий задает предмет, а AGENTS.md собирает рабочие решения, которые иначе были бы разбросаны по нему.

Расплывчатые инструкции ломаются незаметно

Плохая команда обычно завершается ошибкой в терминале. Плохое правило на естественном языке часто приводит к правдоподобному коду, поэтому оно опаснее. «Используйте лучшие практики» оправдывает почти любую правку. «Сохраняйте обратную совместимость» не объясняет, какие интерфейсы считаются публичными. «Тестируйте тщательно» не называет набор, среду или ожидаемый результат. Агент может подтвердить соблюдение словами, но не выполнить замысел сопровождающего.

Переписывайте расплывчатые правила как наблюдаемые решения. Вместо «избегайте больших изменений» укажите, когда агент должен остановиться и разделить работу. Вместо «будьте осторожны с базой данных» назовите операции миграции, которые требуют разрешения, и безопасную локальную базу. Вместо «не ломайте API» укажите контрактный тест и политику совместимости. Полезная инструкция позволяет ревьюеру потребовать конкретное доказательство.

С конфликтами поступайте так же. Допустим, корень требует make verify, а файл пакета сообщает, что интеграционному набору нужны недоступные в локальной песочнице учетные данные. Локальный файл должен сказать, запускает ли агент меньшую проверку, пропускает ли набор с отчетом о блокировке или обращается к человеку. Если оставить оба утверждения без развязки, получится головоломка на соблюдение правил. Модель может выбрать более легкую инструкцию, а два запуска могут выбрать по-разному.

Устаревание встречается чаще всего. Скрипты пакетов меняются, сервисы переезжают, временные обходы переживают исправленную ошибку. Включите AGENTS.md в область ревью при изменениях команд, владельцев каталогов, сгенерированных результатов и обязательных проверок CI. OpenHands прямо требует обновлять соответствующий раздел AGENTS.md при изменении живого сквозного тестового фреймворка. Эту связь полезно перенять: правка кода и ее рабочие инструкции попадают в один PR.

Не превращайте прозу в слабую копию CI. Если правило можно проверить однозначно, добавьте проверку. Оставляйте предложение в AGENTS.md, только если оно помогает агенту выбрать или истолковать эту проверку. Например, CI должен ловить расхождение сгенерированных файлов, а инструкция должна сообщать агенту, какой исходник редактировать и какой генератор запускать. Такое разделение делает ошибки заметными и сохраняет фокус документа на решениях.

Онбординг агента отличается от онбординга человека

Онбординг человека строит ментальную модель несколько дней. Люди узнают, зачем существует продукт, кто владеет каждой подсистемой, как принимают решения и к кому идти, когда письменное руководство заканчивается. Онбординг агента происходит в начале задачи и конкурирует за ограниченное окно контекста. Ему нужны немедленные инструкции в пределах текущей области, связанные с используемыми файлами и командами. Если считать оба процесса одинаковыми, человеческое руководство выйдет поверхностным или файл агента окажется перегруженным.

Документы должны дополнять друг друга. Концепции продукта, длинные объяснения архитектуры и культуру участия держите в документации для людей. В AGENTS.md помещайте правила выполнения задач и границы, значимые для машины. Если архитектурный документ нужен только для определенной работы, точно скажите агенту, когда его читать. Так агент получает контекст постепенно, а вся внутренняя база знаний не копируется в каждую сессию.

Хороший файл делает честнее и онбординг людей. При записи узкой тестовой команды может выясниться, что ее знает только один старший инженер. Описание владения сгенерированным кодом может обнаружить шаг сборки, который существует лишь в чьей-то истории shell. Определение обязательного клиента API может вскрыть несколько исключений, с которыми никто не разобрался. Упражнение превращает скрытый процесс в процесс, доступный для ревью.

Потребность в суждении никуда не исчезает. Агент не выведет бизнес-приоритет из команды сборки, а документ не предвидит каждый продакшен-риск. Обозначьте конец полномочий: просите разрешение перед изменением зависимостей, миграций, публичных контрактов или инфраструктуры, если для этих решений нужен владелец. Понятный агенту репозиторий не становится автономным. В нем легко исполнять обычные решения и легко распознавать исключительные.

Здесь небольшие команды с ИИ получают больше, чем удобство. Когда один-два инженера контролируют несколько параллельных задач агентов, повторное объяснение становится узким местом. Общие инструкции репозитория сокращают повторы и делают требования ревью единообразными. Они не заменят слабые тесты или размытое владение, зато быстро обнаружат и то и другое.

Правила безопасности требуют действий и границ

Текст о безопасности должен объяснять агенту, что разрешено читать, записывать, выполнять и раскрывать. Общие напоминания «соблюдать безопасность» почти не влияют на поведение. Назовите запрещенные среды, чувствительные пути, допустимые тестовые учетные данные, точки согласования и безопасный запасной путь при отсутствии доступа.

Не помещайте секреты в AGENTS.md. Файл находится под контролем версий и может попасть в контекст модели, журналы, форки и сгенерированные сводки. Документируйте имена переменных и способы безопасного получения, но никогда не значения. Не вставляйте внутренние адреса, токены, идентификаторы клиентов или детали инцидентов лишь ради конкретности. Если сам репозиторий содержит чувствительные материалы, доступ должен ограничивать контур агента и его разрешения; текст промпта не создает границу безопасности.

Сильное правило связывает ограничение со следующим действием. «Никогда не запускайте миграции в продакшене» блокирует один путь, но оставляет задачу нерешенной. «Запускайте миграции на одноразовой локальной базе; для любой общей среды остановитесь и запросите разрешение владельца сервиса» объясняет продолжение. Тот же принцип работает для установки зависимостей, разрушительных команд, исходящих сетевых запросов и релизов.

Отделяйте полномочия от технической возможности. Команда может быть доступна агенту, но разрешения на ее запуск у него все равно нет. И наоборот, просьба не читать секрет не мешает широкому shell-инструменту случайно его показать. Для исполнения политики применяйте учетные данные с минимальными правами, изолированные среды, защищенные ветки, обязательное ревью и списки разрешенных команд. AGENTS.md должен объяснять процесс внутри этих ограничений.

Учитывайте риск инъекций. Текст репозитория может содержать инструкции от недоверенного участника или сведения, сгенерированные из внешних данных. Иерархия должна ставить доверенное руководство сопровождающих выше случайных файлов, а агенты должны считать содержимое исходников данными, если доверенная инструкция не говорит иначе. Разрешение на действия с серьезными последствиями держите в запросе пользователя и политике платформы, а не во вложенном Markdown, который может имитировать любая зависимость или тестовая фикстура.

Проверяйте инструкции как интерфейс

Оценить AGENTS.md можно без формального бенчмарка. Выберите типичные задачи, запишите поведение агента до и после появления файла и ищите меньше правок по неверному пути, меньше лишних команд и более ясные отчеты о проверке. В выборке должны быть обычное изменение, межпакетное изменение и задача, которая обязана остановиться ради согласования.

Простой аудит репозитория дает воспроизводимую отправную точку:

$ find . -name AGENTS.md -print
./AGENTS.md
./apps/web/AGENTS.md
./services/payments/AGENTS.md

$ wc -c AGENTS.md apps/web/AGENTS.md services/payments/AGENTS.md
1840 AGENTS.md
 912 apps/web/AGENTS.md
1107 services/payments/AGENTS.md
3859 total

Форма вывода важнее примерных чисел. Первая команда показывает, где меняется область действия. Вторая обнаруживает файлы, которые выросли настолько, что их пора пересмотреть. Затем запустите того же агента из корня и из каждого типичного пакета. Попросите перечислить активные источники инструкций, обобщить конфликты и назвать команду проверки для небольшой правки. Сравните ответ с намерением команды.

Оценивайте файл по отчетам об ошибках, а не по вкусу. Если агент выбирает неверный тест, выясните, отсутствовала ли команда, была ли она неоднозначной, находилась ли за пределами загруженной области или противоречила другому файлу. Если он игнорирует правило, проверьте, не спрятали ли его двадцать менее нужных пунктов. Если он точно исполняет устаревшее руководство, исправьте процесс владения документом, а не добавляйте еще одно предупреждение.

Проверяйте изменения AGENTS.md на обычном код-ревью. Ревьюер должен выполнить новые команды, проверить указанные пути, изучить конфликты вложенных файлов и спросить, не место ли однозначной проверке в CI. Ежеквартальное напоминание в календаре помогает, но сопровождение по событиям лучше: переносы каталогов, изменения скриптов, CI, политики зависимостей и инциденты должны сразу запускать ревью.

В моем Team & AI Audit я отношусь к инструкциям репозитория как к рабочей инфраструктуре: сокращение множества ручных передач до одного-двух инженеров с ИИ возможно, только если агенты получают одинаковые проверенные ограничения. Сам файл стоит дешево; трудная часть в решении, какие знания должны стать долгосрочным правилом.

Внедрение начинается с замеченных помех

Самый быстрый безопасный путь к внедрению начинается с пяти решений, в которых агенты и новые инженеры регулярно ошибаются. Возьмите их из недавних комментариев с ревью, неудачных запусков, сообщений об онбординге и сюрпризов CI. Превратите каждое в инструкцию с ясной областью, командой, путем, границей или ожидаемым результатом. Закоммитьте первую версию и используйте ее на реальных задачах неделю.

Не начинайте с объединения всех существующих файлов для разных агентов в один универсальный документ. Сначала сравните их. У CLAUDE.md, пользовательского правила IDE и промпта CI-бота могут отличаться область действия и приоритет. Выделите факты о репозитории, которые должны пережить смену инструмента, перенесите их в AGENTS.md, а специфичную конфигурацию оставьте только там, где поведение действительно отличается. Символические ссылки могут облегчить миграцию, если два инструмента принимают одинаковое содержимое, но ссылка не согласует несовместимую семантику.

Назначьте владельцев. Платформенная команда или команда удобства разработки может отвечать за корень, а владельцы пакетов будут проверять вложенные файлы. Требуйте обновления инструкции при изменении описанной в ней команды или инварианта. Удаляйте правила, когда автоматизация делает их лишними, если агенту больше не нужна отсылка к автоматической проверке. Короткий актуальный файл лучше полной истории.

AGENTS.md стоит внедрять, если агенты уже работают в репозитории или скоро начнут. Он дает каждому запуску общую отправную точку и снижает зависимость работы нескольких агентов от инженера, который повторяет одни и те же исправления. Не стоит превращать внедрение в проект по соответствию требованиям до появления наблюдаемой работы агентов. Без реальных задач команды пишут абстрактные правила, которые разумно звучат и ничего не меняют.

Первый полезный коммит звучит не как «добавить стандарт». Его смысл: «научить агентов тому, как этот репозиторий доказывает безопасность изменения». Если файл отвечает на этот вопрос для каждой области владения, машины проходят онбординг быстрее, а люди получают более ясный процесс. Если ответа нет, добавьте недостающую команду или границу, а затем назначьте человека, который будет поддерживать ее в актуальном состоянии.