AGENTS.md: полный гайд по настройке

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

CLAUDE.md и совместимость

Важный нюанс: Claude Code не использует AGENTS.md — вместо этого он читает CLAUDE.md. Чтобы все ваши инструменты работали одинаково, можно создать символическую ссылку между файлами:

ln -s AGENTS.md CLAUDE.md

Теперь оба файла указывают на один и тот же источник истины, и вам не придётся дублировать инструкции.

Агент делает что-то не так — вы добавляете правило. Повторяете сотни раз за месяцы работы. В результате файл превращается в «свалку инструкций». Разные разработчики добавляют противоречивые мнения, никто не проводит полную ревизию стиля. Результат — неуправляемый беспорядок, который на самом деле вредит производительности агента.

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

Инструкционный бюджет

Существует концепция «инструкционного бюджета».

Каждый токен в вашем файле AGENTS.md загружается при каждом запросе, независимо от его релевантности. Это создаёт проблему жёсткого бюджета:

Поэтому идеальный файл AGENTS.md должен быть как можно меньше.

Устаревшая документация портит контекст

Документация быстро устаревает. Но человек обычно помнит, как всё устроено на самом деле, и поэтому относится к старым документам скептически. Для AI-агентов, которые читают документацию при каждом запросе, устаревшая информация активно «отравляет» контекст.

Это особенно опасно, когда вы документируете структуру файловой системы. Пути к файлам меняются постоянно. Если ваш AGENTS.md говорит «логика аутентификации находится в src/auth/handlers.ts», а файл переименован или перемещён, агент просто пойдёт не туда.

Давайте подсказки о том, где что может находиться, и общую форму проекта. Позвольте агенту генерировать свою собственную документацию «точно в срок» во время планирования. Доменные концепции (например, «organization» против «group» против «workspace») более стабильны, чем пути к файлам, поэтому их безопаснее документировать. Но даже они могут дрейфовать в быстро меняющихся кодовых базах с AI-ассистентами.

Будьте безжалостны к тому, что попадает в этот файл. Считайте это абсолютным минимумом:

1. Описание проекта в одном предложении (действует как ролевой промпт)
2. Пакетный менеджер (если не npm; или используйте corepack для предупреждений)
3. Команды сборки/проверки типов (если нестандартные)

Честно говоря, это всё. Всё остальное должно жить в другом месте.

Описание проекта в одном предложении

Это единственное предложение даёт агенту контекст о том, почему он работает в этом репозитории. Оно якорит каждое решение, которое он принимает. Пример:

Это библиотека React-компонентов для доступной визуализации данных.

Это фундамент. Теперь агент понимает свою область работы.

Указание пакетного менеджера

Если вы работаете в JavaScript-проекте и используете что-то кроме npm, скажите агенту явно:

Этот проект использует pnpm.

Без этого агент может по умолчанию использовать npm и генерировать неправильные команды.

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

Вынесите языко-специфичные правила в отдельные файлы

Если ваш AGENTS.md сейчас содержит:

Всегда используй const вместо let.
Никогда не используй var.
Используй interface вместо type, когда возможно.
Включи строгие проверки null.
...

Переместите это в отдельный файл. В корневом AGENTS.md:

Для конвенций TypeScript см. docs/TYPESCRIPT.md

Обратите внимание, что в этом тексте нет никаких «всегда» или использования капсов для «принуждения». Просто разговорная ссылка.

Преимущества:

1. Правила TypeScript загружаются, только когда агент пишет на TypeScript
2. Другие задачи (отладка CSS, управление зависимостями) не тратят токены
3. Файл остаётся сфокусированным и переносимым между моделями

Вложенное progressive disclosure

Можно пойти ещё глубже. Ваш docs/TYPESCRIPT.md может ссылаться на docs/TESTING.md. Создайте дерево ресурсов:

docs/
├── TYPESCRIPT.md
│   └── ссылается на TESTING.md
├── TESTING.md
│   └── ссылается на конкретные тест-раннеры
└── BUILD.md
    └── ссылается на конфигурацию esbuild

Вы даже можете ссылаться на внешние ресурсы: документацию Prisma, Next.js и т.д. Агент будет эффективно перемещаться по этим иерархиям.

Используйте agent skills

Многие инструменты поддерживают «agent skills» — команды или рабочие процессы, которые агент может вызывать, чтобы узнать, как сделать что-то конкретное. Это ещё одна форма progressive disclosure: агент подтягивает знания только тогда, когда они нужны.

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

Что где размещать

Корневой AGENTS.md:

Это монорепозиторий, содержащий веб-сервисы и CLI-инструменты.
Используй pnpm workspaces для управления зависимостями.
См. AGENTS.md каждого пакета для конкретных указаний.

Пакетный AGENTS.md (в packages/api/AGENTS.md):

Этот пакет — Node.js GraphQL API с Prisma.
Следуй docs/API_CONVENTIONS.md для паттернов дизайна API.

Не перегружайте ни один уровень. Агент видит все объединённые файлы AGENTS.md в своём контексте. Держите каждый уровень сфокусированным на том, что релевантно в его области.

Промпт для исправления сломанного AGENTS.md

Если вы начинаете нервничать из-за файла AGENTS.md в вашем репозитории и хотите отрефакторить его для использования progressive disclosure, попробуйте скопировать этот промпт в вашего кодинг-агента:

Я хочу, чтобы ты отрефакторил мой файл AGENTS.md в соответствии с принципами progressive disclosure.
Следуй этим шагам:
1. **Найди противоречия**: Определи любые инструкции, которые конфликтуют друг с другом. Для каждого противоречия спроси меня, какую версию я хочу сохранить.
2. **Определи главное**: Извлеки только то, что принадлежит корневому AGENTS.md:
   - Описание проекта в одном предложении
   - Пакетный менеджер (если не npm)
   - Нестандартные команды сборки/проверки типов
   - Всё, что действительно релевантно каждой задаче
3. **Сгруппируй остальное**: Организуй оставшиеся инструкции в логические категории (например, конвенции TypeScript, паттерны тестирования, дизайн API, Git workflow). Для каждой группы создай отдельный markdown-файл.
4. **Создай структуру файлов**: Выведи:
   - Минимальный корневой AGENTS.md с markdown-ссылками на отдельные файлы
   - Каждый отдельный файл с его релевантными инструкциями
   - Предлагаемую структуру папки docs/
5. **Отметь для удаления**: Определи любые инструкции, которые:
   - Избыточны (агент уже знает это)
   - Слишком расплывчаты, чтобы быть действенными
   - Слишком очевидны (например, «пиши чистый код»)

Когда вы собираетесь что-то добавить в ваш AGENTS.md, спросите себя, где это должно находиться:

Идеальный AGENTS.md — маленький, сфокусированный и указывающий в другие места. Он даёт агенту достаточно контекста, чтобы начать работу, с хлебными крошками для более детального руководства.

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

AGENTS.md — это мощный инструмент настройки AI-агентов, но только при правильном подходе. Держите его минимальным по размеру, используйте progressive disclosure и не позволяйте ему превращаться в свалку инструкций.