Руководство против свода правил: дорогостоящее недопонимание
Непонимание многими командами роли файла AGENTS.md создает дорогостоящее «слепое пятно» в работе. Недавнее исследование инженеров Coldtea выявило суровую реальность: только 27% из 1000 лучших репозиториев GitHub вообще имеют файл AGENTS.md, и подавляющее большинство из них используется неправильно. Этот повсеместный недосмотр оставляет критический пробел в управлении вкладом AI.
Основная проблема заключается в том, что «руководство по эксплуатации» путают со «сводом правил». Большинство существующих файлов AGENTS.md функционируют как руководства, фокусируясь на описании архитектуры проекта или перечислении точных команд для сборки и тестирования. Они говорят AI, как работать, но, что критически важно, они не ограничивают то, что ему следует и чего не следует делать.
Настоящий AGENTS.md выступает в роли свода правил, устанавливая строгие ограждения и явные негативные ограничения для AI-агентов. Без этого свода правил агенты работают без границ, что приводит к несогласованному вкладу, неожиданному поведению и появлению потенциальных багов. Например, более крупные репозитории отводят почти вдвое больше места правилам «не делай», что является четким сигналом понимания ими этой необходимости. Отсутствие четких директив «должен», «всегда» и «никогда» превращает потенциально мощный инструмент в непредсказуемую обузу.
Сила «не делай»: уроки от Vercel и Bun
Исследование Coldtea выявило критическую закономерность среди ведущих репозиториев: наиболее эффективные файлы AGENTS.md отдают приоритет явным негативным ограничениям. Репозитории из топ-100 отводят почти вдвое больше места правилам о том, чего не следует делать, по сравнению с небольшими проектами: было найдено 784 примера подразумеваемых предложений «не делай».
Поразительные 90% этих высокоэффективных файлов используют такие категоричные термины, как «должен», «всегда» или «никогда», чтобы направлять AI-агентов. Это не случайно; это осознанная стратегия предотвращения непреднамеренных действий и поддержания целостности кода — отличительная черта надежных систем.
Конкретные примеры подчеркивают эту точность. Например, репозиторий Next.js от Vercel прямо запрещает использование футеров 'generated with Claude code' в коммитах. Такой уровень детализации гарантирует, что вклад AI идеально соответствует стандартам проекта и ожиданиям людей.
Репозиторий Bun предлагает еще одну яркую иллюстрацию с предупреждением заглавными буквами: 'NEVER run bun test directly - it won't include your changes' (НИКОГДА не запускайте bun test напрямую — это не включит ваши изменения). Такие прямые запреты устраняют двусмысленность, не давая агентам выполнять пагубные команды, которые могут скомпрометировать среду сборки или тестирования.
Четкие границы необходимы, потому что AI-агенты работают без человеческого контекста или интуиции. Им не хватает неявного понимания истории проекта, командных норм или потенциальных побочных эффектов. Поэтому вы должны точно сказать им, каких файлов, функций или паттернов следует тщательно избегать, выступая в роли цифрового ограждения. Этот проактивный подход предотвращает тонкие ошибки и защищает кодовую базу.
От 33 до 14 000 слов: как найти правильный размер вашего файла
Огромная вариативность длины файла AGENTS.md выявляет зарождающуюся лучшую практику. Рассмотрим крайности: весь файл VS Code занимает всего 33 слова, выступая в качестве простого перенаправления. Файл Neovim, едва длиннее — 35 слов, фокусируется на одном правиле раскрытия информации для коммитов, созданных AI. В то же время репозиторий OpenHands представляет собой внушительный набор инструкций из 14 000 слов. Этот дикий спектр подчеркивает сложность определения оптимального шаблона.
Исследование Coldtea, однако, предлагает практический ориентир: медианный объем около 1200 слов. Эта цифра указывает на прагматичную «золотую середину» для большинства проектов, позволяя сбалансировать достаточную детализацию для AI-контрибьюторов с ясностью, необходимой для контроля со стороны человека и быстрой итерации. Это реалистичный эталон для установления эффективных границ для агентов без излишней многословности.
В конечном итоге, сложность вашего файла AGENTS.md должна напрямую соответствовать масштабу вашего проекта и конкретным рискам, которые вы стремитесь минимизировать с помощью AI-помощников. Небольшой специализированный инструмент может требовать минимальных ограничений, но сложная система с множеством участников требует надежного свода правил. Для более глубокого понимания того, как контекстные файлы действительно помогают AI-агентам в программировании, ознакомьтесь с работой Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?.
Нравится статья? Получайте такие каждое утро на почту.
одно письмо в день · отписка в два клика · без сторонних трекеров
Ваш чек-лист из 3 пунктов для репозитория, готового к работе с агентами
Проанализировав 1000 лучших репозиториев на GitHub, инженеры Coldtea выделили суть эффективных файлов AGENTS.md в виде важного чек-листа из трех пунктов. Это не просто рекомендации; это предоставление точных команд для ваших AI-агентов, превращающее ваш файл в надежный свод правил.
Чтобы ваш репозиторий был готов к работе с агентами, убедитесь, что ваш AGENTS.md включает:
- Как минимум одно явное правило «не делай». Эта критически важная директива, присутствующая в 86% эффективных файлов, устанавливает четкие границы поведения агента. Без этих негативных ограничений агенты часто полагаются на предположения, что может привести к нежелательным изменениям или «сгенерированным» футерам, как это было в случае с Vercel Next.js. Это включает в себя четкое определение того, к чему агенту никогда нельзя прикасаться.
- Тщательно прописанные требования к формату коммитов и pull-реквестов. Встречаются в 79% успешных файлов и гарантируют, что история проекта и стандарты остаются неизменными, независимо от того, кто отправляет код — человек или AI-агент. Предписанное форматирование предотвращает хаос в системе контроля версий.
- Точные инструкции по запуску тестов и линтингу кода. Примерно три четверти (75%) эффективных файлов содержат эти четкие указания. Это не опциональные шаги, а прямые команды для выполнения агентом, гарантирующие, что каждый вклад проходит проверку качества перед интеграцией.
Часто задаваемые вопросы
Какую главную ошибку совершают проекты при работе с файлами AGENTS.md?
Самая распространенная ошибка — рассматривать AGENTS.md как операционное руководство (список команд), а не как строгий свод правил, который говорит AI-агенту, что он должен делать и, что более важно, чего он делать не должен.
Каковы ключевые элементы хорошего файла AGENTS.md?
Эффективный файл включает явные негативные ограничения (правила «не делай»), четкие инструкции по форматированию коммитов и PR, а также точные рекомендации по запуску тестов и линтингу кода.
Нужны ли крупным проектам другие файлы AGENTS.md, чем маленьким?
Да. Исследования показывают, что в более крупных и сложных проектах файлы AGENTS.md гораздо строже, они уделяют почти вдвое больше места негативным ограничениям (правилам «не делай») для защиты кодовой базы.
Насколько распространены файлы AGENTS.md в топовых репозиториях GitHub?
Они все еще относительно редки. Исследование 1000 лучших репозиториев GitHub показало, что только 27% имеют файл AGENTS.md, что указывает на огромные возможности для улучшения процесса управления AI-агентами.