AGENTS.md: как написать инструкции для AI-агентов

Что такое AGENTS.md

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

Формат появился в 2025 году как общий стандарт нескольких вендоров. В декабре 2025 года OpenAI передала AGENTS.md в Agentic AI Foundation при Linux Foundation. Фонд основали OpenAI, Anthropic и Block, туда же вошли протокол MCP и агент goose. По данным agents.md, файл используют больше 60 тысяч открытых проектов.

Какие агенты читают AGENTS.md

Файл поддерживают OpenAI Codex, Cursor, GitHub Copilot coding agent, Google Jules и Gemini CLI, Amp, Factory, Aider, Zed, Warp и другие инструменты. Полный список ведётся на agents.md.

Claude Code читает свой файл CLAUDE.md. Чтобы не вести два файла, в CLAUDE.md ставят одну строку с импортом:

@AGENTS.md

Claude Code подставит содержимое AGENTS.md в контекст. Ниже можно добавить правила, которые нужны только Claude Code. Второй способ — символическая ссылка CLAUDE.md на AGENTS.md.

Что писать в AGENTS.md

В файл попадает то, без чего агент ошибётся или потратит время на поиск. Рабочий набор разделов:

• Команды. Установка зависимостей, сборка, запуск тестов, линтер, форматирование. С точными флагами, например pnpm test --filter api.
• Структура репозитория. Где какой сервис, где общие библиотеки, куда класть новые модули.
• Стиль кода и договорённости. Только то, что не ловит линтер: как называть сущности, где обрабатывать ошибки, какие паттерны в проекте приняты.
• Тесты. Какие тесты писать к изменению, как запустить один тест, что считается готовым.
• Границы. Какие каталоги и файлы не трогать, какие команды запрещены, когда остановиться и спросить человека.
• Процесс. Как называть ветки и коммиты, что писать в описании PR, какие проверки должны пройти перед сдачей.
• Ссылки на базу знаний. Где лежат архитектурная карта, ADR и спеки. Детали остаются в этих документах, в AGENTS.md только указатель.

Пример файла

# AGENTS.md

## Команды
- Установка: `pnpm install`
- Тесты сервиса: `pnpm test --filter billing`
- Один тест: `pnpm vitest run path/to/file.test.ts -t "название"`
- Линтер и типы: `pnpm lint && pnpm typecheck` — обязательно перед сдачей

## Структура
- `services/` — сервисы, у каждого свой AGENTS.md
- `packages/shared/` — общие типы и утилиты, менять только через ADR
- `docs/architecture.md` — карта сервисов и контракты
- `docs/adr/` — журнал решений
- `specs/` — спецификации задач

## Правила
- Перед реализацией прочитай спеку задачи в `specs/` и сверь план с acceptance criteria.
- Даты храним в UTC, группируем по часовому поясу клиента из `client.tz`.
- Деньги — только `Decimal`, никаких float.
- Новый эндпоинт = тест на контракт в `contracts/`.

## Границы
- Не трогай `migrations/` и `infra/`. Если задача этого требует, остановись и опиши план в PR.
- Не добавляй зависимости без записи в ADR.
- Не отключай и не ослабляй тесты, чтобы они прошли.

## Сдача работы
- Ветка: `feat/<тикет>-кратко`
- В описании PR: ссылка на спеку, какие AC закрыты, как проверено.

Монорепозиторий и вложенные файлы

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

Практика, которая работает:

• В корне — общие команды, процесс и границы для всего репозитория.
• В сервисе — стек, команды тестов этого сервиса и его особые правила.
• Если в подкаталоге нужно отменить общее правило, это пишут явно: «здесь, в отличие от корня, …».

Частые ошибки

• Копия README. Агенту не нужны история проекта и бейджи. Ему нужны команды и правила.
• Слишком длинный файл. Чем больше текста, тем выше шанс, что агент пропустит важное правило. Детали выносят в базу знаний и вложенные файлы.
• Общие слова. «Пиши чистый код» ничего не меняет в поведении агента. «Деньги — только Decimal» меняет.
• Правила, которые можно проверить автоматически. Форматирование и порядок импортов задаёт линтер. В AGENTS.md достаточно команды, которая его запускает.
• Файл не обновляется. Команды сборки поменялись, а AGENTS.md нет, и агент тратит время на неработающие инструкции.

Как поддерживать AGENTS.md

AGENTS.md — первый слой harness, и обновлять его нужно так же регулярно, как код. Рабочий цикл:

1. Агент ошибся или человек поправил его результат руками.
2. Команда разбирает причину: не хватило правила, контекста или проверки.
3. Если правило можно проверить автоматически, его добавляют в линтер или тест. Если нет, в AGENTS.md или базу знаний.
4. Изменение AGENTS.md проходит ревью через PR, как любой код.

У файла должен быть владелец. Без него правила устаревают за пару месяцев.

Вопросы