AGENTS.md — текстовый файл в корне проекта, который читают сразу несколько агентов: Codex, OpenCode, Claude Code, OpenClaw. Редкий случай, когда договорились об общем формате, и потому самый практичный способ объяснить агенту правила проекта.
Короткий ответ
Кладёте в корень репозитория файл AGENTS.md, пишете в нём обычным текстом: что за проект, как запускать, как тестировать, чего не делать. Агент читает его сам при старте работы — просить не нужно.
Главная ценность — переносимость. Один файл работает в нескольких инструментах, поэтому при смене агента правила проекта не переписываются заново.
Зачем он нужен
Без такого файла агент каждый раз изучает проект с нуля: читает структуру, догадывается о соглашениях, задаёт уточняющие вопросы или, хуже, не задаёт и делает по-своему.
С AGENTS.md он сразу знает:
- что это за проект и из чего состоит;
- какими командами собирать, запускать и тестировать;
- какие соглашения приняты — именование, структура, стиль;
- чего в этом проекте делать нельзя.
Экономия не столько в токенах, сколько в переделках: агент реже делает правильно, но не так, как у вас принято.
Что писать внутри
Формат свободный — это обычный Markdown. Работает такая структура:
# Проект
Короткое описание: что это, для кого, из чего состоит.
## Команды
- Установка: npm install
- Разработка: npm run dev
- Тесты: npm test
- Сборка: npm run build
## Структура
- src/components — переиспользуемые компоненты
- src/pages — страницы, маршрутизация по файлам
- scripts — служебные скрипты, в сборку не входят
## Соглашения
- Имена файлов в kebab-case
- Комментарии по-русски, код по-английски
- Новые зависимости — только после обсуждения
## Чего не делать
- Не менять формат конфигурации без явной просьбы
- Не коммитить в main напрямую
- Не трогать generated-файлы рукамиРаздел «чего не делать» полезнее остальных. Агент склонен додумывать и улучшать; явный запрет работает лучше, чем надежда на здравый смысл.
Чего в него класть не надо
- Секретов. Файл лежит в репозитории и виден всем, у кого есть доступ.
- Документации для людей. Для этого есть README.
AGENTS.md— инструкция агенту, и чем короче, тем лучше он ей следует. - Всего сразу. Файл на десять страниц агент прочитает, но выполнять будет выборочно. Начните с одного экрана.
AGENTS.md, CLAUDE.md и скиллы — как они уживаются
Три механизма, которые часто путают, хотя роли разные.
| Что это | Область | |
|---|---|---|
AGENTS.md | правила проекта | понимают разные агенты |
CLAUDE.md | то же, но для Клода | только Клод |
| Скиллы | как выполнять конкретную задачу | подключаются по ситуации |
| MCP | доступ к внешним системам | что агент физически может |
Практическая схема: AGENTS.md — про проект, скиллы — про задачи, MCP — про доступ. Первый читается всегда, вторые подключаются, когда подходят, третий даёт возможности.
Если работаете только с Клодом, CLAUDE.md и AGENTS.md во многом дублируют друг друга — разбор различий.
У OpenClaw своя система
OpenClaw читает AGENTS.md, но исторически у него свой набор файлов: описание агента, рабочее пространство, характер и стиль общения. Плюс навыки как отдельный механизм.
Если проект командный и агенты у людей разные, AGENTS.md — общий знаменатель: его прочитают все.
Как проверить, что работает
- Положите файл в корень и опишите в нём одно проверяемое правило — например, конкретный формат коммитов.
- Дайте агенту задачу, которая это правило затрагивает.
- Посмотрите, соблюдено ли оно без напоминания.
Не соблюдено — либо файл лежит не в корне, либо правило сформулировано как пожелание, а не как инструкция. «Желательно использовать» агент воспринимает именно как желательно.
Типичные ошибки
- Пишут прозой. Списки и команды выполняются точнее, чем абзацы рассуждений.
- Смешивают с README. Получается документ, который плохо служит и людям, и агенту.
- Не обновляют. Устаревшая инструкция хуже отсутствующей: агент уверенно делает по-старому.
- Кладут секреты. Ключи в репозитории — отдельная проблема, к агентам отношения не имеющая, но всплывает регулярно.
Коротко
Один текстовый файл в корне проекта, который понимают четыре разных агента, — самое дешёвое улучшение из всех доступных. Начните с команд и раздела «чего не делать»: этих двух блоков хватает, чтобы заметно сократить переделки. Что делать с задачами, которые повторяются, — вынести в скиллы.
Все механизмы настройки в одном месте, со сравнительной таблицей, — как настроить ИИ-агента.