Что такое AGENTS.md и как написать свой за 30 минут в 2026

Каждый день в Telegram-канале - что нового в вайб-кодинге: инструменты, примеры, ошибки. Подпишись, чтобы быть в курсе.

AGENTS.md в одном абзаце

Я держу AGENTS.md рядом с CLAUDE.md в смыслокоде и в Piratix AI несколько месяцев. Ниже разбираю формат по agents.md, документации OpenAI Codex, JetBrains Junie, Cursor Rules Docs, GitHub Copilot Coding Agent changelog и пресс-релизу Linux Foundation про Agentic AI Foundation. Все цифры и фичи актуальны на 30 мая 2026.

Если ты вообще не понимаешь, что за зоопарк инструментов сейчас на рынке и зачем им единый файл - сначала прочитай гайд «Чем кодить в 2026: 8 ИИ-инструментов от Claude Code до Antigravity». Тут я фокусируюсь именно на формате AGENTS.md и на том, как написать свой за 30 минут.

Что такое AGENTS.md и откуда он взялся?

Раньше каждый ИИ-инструмент тянул свой файл правил: Anthropic - CLAUDE.md, Cursor - .cursorrules, GitHub - .github/copilot-instructions.md, Aider - .aider.conf.yml, JetBrains - .junie/guidelines.md. Если в команде три разных агента - три параллельных файла с одинаковым содержимым, которые расходятся через неделю.

OpenAI это надоело первым. В августе 2025 они выпустили Codex CLI и одновременно подняли agents.md как открытый формат. Со страницы:

«Думай об AGENTS.md как о README для агентов.»

(agents.md, перевод с английского)

Главный смысл - AGENTS.md дополняет README. README пишется для людей: «что за проект, как запустить локально, как контрибьютить». AGENTS.md пишется для агента: точные shell-команды, проверяемые критерии «готово», границы «никогда не трогай это».

Со страницы:

«AGENTS.md дополняет README: туда уходит дополнительный, иногда детальный контекст, нужный агенту, - шаги сборки, тесты и соглашения, которые засорили бы README или просто не нужны людям-контрибьюторам.»

(agents.md, перевод с английского)

К сентябрю 2025 формат поддержал GitHub Copilot Coding Agent (changelog 28.08.2025). К декабрю - Cursor, Junie, Gemini CLI, Aider и ещё десяток. 9 декабря 2025 Linux Foundation сформировала Agentic AI Foundation (AAIF): три founding-проекта внутри - AGENTS.md от OpenAI, MCP от Anthropic, goose от Block. Founding-члены - AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft, OpenAI. К 24 февраля 2026 фонд уже включал 146 организаций, включая Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, UiPath и Hitachi.

С этого момента AGENTS.md перестал быть «вот ещё одна штука от OpenAI» и превратился в де-факто стандарт.

Какие ИИ-агенты читают AGENTS.md, а какие нет?

Таблица поддержки на 30 мая 2026:

Картина простая: индустрия договорилась, Anthropic пока в стороне. В августе 2025 пользователь под ником DylanLIiii открыл issue #6235 в репозитории anthropics/claude-code с просьбой добавить поддержку:

«Codex, Amp, Cursor и другие начинают стандартизироваться вокруг AGENTS.md - единого markdown-файла, который агенты для кодинга могут использовать, чтобы разобраться в проекте. CLAUDE.md в сравнении с этим выглядит слишком специфичным для Claude Code.»

(github.com/anthropics/claude-code/issues/6235, перевод с английского)

Issue висит открытым 9 месяцев. Официального комментария от Anthropic нет. Возможные причины: Anthropic давно вложилась в свой механизм (CLAUDE.md + CLAUDE.local.md + ~/.claude/CLAUDE.md + @import + path-scoped rules + .claude/skills/) и не хочет терять контроль над поведением Claude Code. Стратегически - они членствуют в AAIF на Platinum-уровне и продвигают MCP как свой главный вклад в стандарт.

Для русскоязычного контекста интересен один практический угол: AGENTS.md можно использовать не только как инструкцию агенту, но и как ловушку для агента. На Хабре в апреле 2026 Vladlen Kaveev описал паттерн, где он повесил в AGENTS.md инструкцию с чек-боксом про «отметь, если ты ИИ-агент» и в PR-шаблоне ловит автоматизированные PR:

«AGENTS.md создавали, чтобы помогать агентам. Я использую его, чтобы их вычислять.»

(Habr 1038786, май 2026)

Это не основной сценарий, но хорошо иллюстрирует силу формата: один файл, который агент точно прочитает.

Сам AGENTS.md - один кирпичик из трёх. Он задаёт правила игры для агента. Контекст бизнеса агенту даёт Второй мозг (папка business/). Голос и стиль решений - ИИ-клон (папка ai-clone/). На практикуме за три эфира собираем все три кита: ИИ-клон + Второй мозг + контекст-инжиниринг. AGENTS.md без двух других - это правила без контекста, и агент всё равно ошибается.

Практикум по вайб-кодингу

+Твой второй мозг

3 вечера - стек, метод, первый проект

Старт 9–11 июня  ·  2 000 ₽

Записаться →

Чем AGENTS.md отличается от CLAUDE.md и .cursorrules?

Сравнение четырёх форматов на 30 мая 2026:

Ключевая мысль: AGENTS.md решает проблему «один файл для всех агентов», но не решает проблему «личных настроек, которые я не коммичу». Для этого у Claude Code есть CLAUDE.local.md, а у Cursor - локальные .mdc под user. AGENTS.md в одиночку этого не даёт - нужно либо комбинировать с другими файлами, либо договариваться в команде, что личные правила пишутся в gitignore-секции.

Ещё одна важная деталь - монорепо. Codex и Cursor реализуют правило «ближайший AGENTS.md побеждает»:

«В монорепо клади отдельный AGENTS.md внутрь каждого пакета. Агенты автоматически читают ближайший файл в дереве каталогов, и ближайший побеждает.»

(agents.md, перевод с английского)

На agents.md упоминается, что в основном моно-репо OpenAI лежит 88 AGENTS.md файлов для разных подпакетов. Если ты работаешь в монорепо - разноси правила по уровням: общий в корне, специфические в подпапках.

Что должно быть внутри хорошего AGENTS.md?

Сайт agents.md предлагает гибкий формат - «любой markdown». Но 80% хороших файлов в дикой природе содержат одну и ту же восьмёрку секций. Главное правило: каждый пункт - точная команда или конкретный пример. Общая мысль типа «пишите чистый код» агент проигнорирует.

1. Project overview - 2-3 строки. Что за проект, для кого, главная цель. Без маркетинга. Пример: «Telegram-бот для онбординга в платный практикум. Stack: Next.js 14, Prisma, PostgreSQL. Триггерится при новой записи в purchases».
2. Setup commands - точные shell-команды для запуска локально. npm install, npm run dev, npm run build. Без «обычно делаем так».
3. Code style / conventions - конкретные правила с примером, а не «писать чисто». Например: «TypeScript strict, single quotes, no default exports, имена компонентов в PascalCase, хуки начинаются с use».
4. Dev environment tips - где лежит важное. Какие переменные нужны в .env, где спрятаны секреты, какие порты заняты, как работать с локальной БД.
5. Testing instructions - как запустить конкретный тест и что считается «зелёным». Например: npm test -- --testPathPattern=user-auth, ожидается 100% pass.
6. PR / commit guidelines - формат commit-сообщений, чек-лист перед PR (тесты, линтер, документация), кто аппрувит.
7. Security considerations - чего точно нельзя. «Никогда не коммить .env. Секреты только в Vault. Не показывать персональные данные пользователей в логах».
8. Boundaries / Never do this - запреты с альтернативой. «Не используй git push --force на main. Если нужно откатить, делай git revert или git reset на feature-ветке».

Для каждой секции работает принцип «команда вместо мысли». «Будь осторожен с миграциями» агент проигнорирует. «Перед alembic upgrade head запусти alembic check. Если в нём ошибка - не накатывай, спроси меня» - исполнит.

Готовый шаблон AGENTS.md (копируй и подгоняй)

# AGENTS.md

## Project overview

<project-name> - <одна фраза про назначение>.
Stack: <Next.js / Python / Go / ...>.
Главные сущности: <users, orders, posts ...>.
Подробности для людей - в README.md.

## Setup commands

```bash
# первая установка
npm install
cp .env.example .env  # потом заполнить вручную, см. список ниже

# запуск
npm run dev           # dev-сервер на :3000
npm run build         # production-сборка
npm run start         # запуск production-сборки
```

## Dev environment

- Node 20+ (через nvm: `nvm use 20`)
- PostgreSQL 16 локально на :5432 (`docker-compose up postgres`)
- Redis опционален, нужен только для очередей (`docker-compose up redis`)
- `.env`: `DATABASE_URL`, `STRIPE_KEY`, `RESEND_API_KEY`, `JWT_SECRET`
- Никогда не читай `.env` целиком. Если нужна одна переменная: `grep "^VAR=" .env`

## Code style

- TypeScript strict mode
- Single quotes, no semicolons (если не требует ESLint)
- Импорты: внешние, потом внутренние через `@/`, потом относительные
- Компоненты в PascalCase, хуки начинаются с `use`
- Никаких `any` без явного комментария «почему нельзя типизировать»

Пример хорошего модуля:

```ts
import { z } from 'zod'

const UserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
})

export function parseUser(raw: unknown) {
  return UserSchema.parse(raw)
}
```

## Testing

```bash
npm test                                # все тесты
npm test -- --testPathPattern=auth      # только auth
npm test -- --watch                     # watch-режим
```

Все тесты должны проходить (зелёные) перед коммитом. Если тест красный - не коммить, спроси меня, что делать.

## Pull request guidelines

- Commit-формат: `<type>(<scope>): <описание>` (`feat(auth): добавить magic-link`)
- Перед PR: `npm run build && npm test && npm run lint`
- PR-описание = что меняется, зачем, как тестировать
- Не аппрувь PR сам - всегда жди ревью человека

## Security

- Секреты только в `.env` и в Vault, никогда в коде
- Персональные данные (email, телефон, имя) не выводи в логи
- При работе с production-БД - только read-only запросы без явного разрешения
- API-ключи внешних сервисов (Stripe, OpenAI) не хардкодь в тестах

## Never do this

- Не делай `git push --force` на main. Если нужно откатить - `git revert` или новый PR
- Не запускай миграции БД без `alembic check` (или эквивалента в твоей ORM)
- Не удаляй файлы из `business/` или `ai-clone/` без явного запроса - там источник правды
- Не используй `npm install -g` или `sudo` для проектных зависимостей
- Не добавляй новые зависимости без согласования (особенно тяжёлые: webpack-плагины, ORM)

В среднем шаблон занимает 80-120 строк. Если файл выходит за 150 строк - это сигнал к рефакторингу: что-то надо вынести в docs/, на что-то поставить ссылку, что-то ужать в одну строку. Augment Code в своём исследовании AGENTS.md показали: лучше всего работают файлы на 100-150 строк, после этой границы прирост качества начинает разворачиваться.

Какие 5 правил делают AGENTS.md реально полезным?

1. Команды вместо мыслей. «Будь осторожен с миграциями» агент не понимает. alembic check перед alembic upgrade head - исполнит. Агент работает с командами и условиями, не с настроением. Все ключевые правила формулируй как «сделай X, иначе Y».

2. Запреты с альтернативой. Чистое «не делай force push» агент тихо игнорирует через два-три промпта. Работает связка «не делай X, делай вместо этого Y». Пример: «не используй git push --force на main; если нужно откатить - сделай git revert или новый PR». В исследовании Augment Code про decision tables зафиксирован эффект: PR-ы с явно прописанными альтернативами набирают примерно на 25% выше по показателю best_practices.

3. Ровно один источник истины. AGENTS.md в корне = источник истины для всего проекта. Если у тебя монорепо - вложенные AGENTS.md в подпапках, по правилу «ближайший побеждает». Никаких параллельных файлов с противоречиями. На бенчмарке AMBIG-SWE (ICLR 2026) показано: когда агенты не задают уточняющих вопросов при неоднозначных инструкциях и идут по «стандартному» пути, resolve rate падает с 48,8% до 28%.

4. Проверяемые критерии «готово». «Тесты должны проходить» - бесполезно. Точный критерий: npm test возвращает exit-код 0 и не пишет FAIL в stdout. «Код должен быть чистым» - тоже бесполезно. Точный критерий: npm run lint проходит без warnings. Агент понимает, что значит «готово», только если ты явно описал условие.

5. Файл короче 150 строк. За пределами 150 строк начинаются деградация метрик: агент тратит больше контекста на чтение и пропускает важные правила. Если не помещаешься - выноси детали в docs/architecture.md со ссылкой из AGENTS.md, а в самом файле оставляй только команды и границы.

Augment Code формулирует это одним предложением:

«Хороший AGENTS.md - это апгрейд модели. Плохой - хуже, чем без документации вообще.»

(Augment Code blog, перевод с английского)

Какие 10 ошибок превращают AGENTS.md в мусор?

1. Расплывчатые правила без команд. «Будь осторожен с миграциями» агент проигнорирует - такое предложение для него пустое. Сработает только конкретная команда с условием: «Запусти alembic check перед alembic upgrade head. Если ошибка - не накатывай, спроси меня».

2. «Чистый код». Бесполезная фраза. Заменяй на конкретный паттерн: «Используй функциональные компоненты с хуками. Пример: function LoginForm() { const [email, setEmail] = useState(''); ... }».

3. Сплошной текст без структуры. Если AGENTS.md - это 300 строк прозы без заголовков, агент потратит 80К токенов контекста на нерелевантные куски и пропустит важное. Делай заголовки H2/H3, короткие пункты, bullet lists.

4. Файл больше 150 строк. После этого порога метрики качества деградируют. Дели на основной + ссылки на детали в docs/.

5. 30+ запретов без альтернатив. Если в файле длинный список «не делай X, не делай Y», без объяснения «делай вместо этого Z» - агент будет тыкаться вслепую. У Augment Code такие файлы стабильно проседают по completeness на сложных задачах: «хорошая» рутинная задача +25%, сложная фича -30%.

6. Дублирование README.md. Если ты уже написал в README «как поставить и запустить», не копируй то же в AGENTS.md. Лучше сошлись на README одной строкой и опиши в AGENTS.md то, что нужно агенту, но не нужно людям.

7. Хардкод секретов. AGENTS.md потенциально публичный (он лежит в git). Никаких реальных ключей API, токенов, паролей. Только ссылки на хранилища секретов: «См. Vault: secret/staging/db».

8. Конфликтующие приоритеты без ранжирования. «Делай быстро» + «покрывай тестами на 90%» = агент не знает, что выбрать. Ранжируй явно: «Сначала покрытие тестами ≥80%, потом скорость. Если конфликт - тесты главнее».

9. Stale документация. Описание архитектуры REST+polling, когда в реальности уже WebSockets. Агент следует устаревшему описанию и ломает архитектуру. Правило: при изменении архитектуры обновляй AGENTS.md в том же PR, что и сам код.

10. Архитектурная избыточность для простой задачи. Если человек попросил поменять две строки в конфиге, агент не должен читать полное описание топологии 14 микросервисов. Вынеси «глубокую» архитектуру в docs/architecture.md, в AGENTS.md оставь только «если задача архитектурная - читай docs/architecture.md».

GitHub Blog в исследовании 2500+ AGENTS.md репозиториев формулируют главный вывод:

«Большинство agent-файлов проваливаются, потому что написаны слишком общо. "You are a helpful coding assistant" не работает.»

(GitHub Blog, перевод с английского)

Как держать AGENTS.md и CLAUDE.md в одном репозитории?

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

Сценарий 1: Только Claude Code. Оставляй CLAUDE.md и пользуйся всеми фичами Claude Code: ~/.claude/CLAUDE.md для user-level, CLAUDE.md для проекта, CLAUDE.local.md для личных override, @import для подключения других файлов, .claude/skills/ для специализированных навыков. AGENTS.md не нужен.

Сценарий 2: Только не-Claude инструменты. Используй AGENTS.md как единственный source of truth. Подходит, если в команде Codex, Cursor, Copilot, Junie, Gemini CLI, Aider в разных комбинациях. Один файл - все агенты читают одинаково.

Сценарий 3: Mix-команда (Claude Code + другие). Самый частый расклад в 2026. Решение - AGENTS.md основной, CLAUDE.md либо symlink, либо короткий wrapper с @AGENTS.md import.

На macOS и Linux работает одна команда:

mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md

После этого AGENTS.md и CLAUDE.md - один и тот же файл. Все агенты, читающие AGENTS.md, видят одно содержимое. Claude Code, читающий CLAUDE.md, видит то же самое через symlink.

На Windows symlink требует Developer Mode (или Admin), что не всем команде удобно. Альтернатива - короткий CLAUDE.md, который импортирует AGENTS.md:

# CLAUDE.md

@AGENTS.md

## Claude Code specific

- Используй .claude/skills/ для специализированных промптов
- При работе с Skills - сверяйся с .claude/skills/INDEX.md
- Plan Mode перед большими изменениями (Shift+Tab)

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

Канонический layout для multi-tool команды в 2026:

repo-root/
├── AGENTS.md                              # source of truth, ≤150 строк
├── CLAUDE.md                              # symlink → AGENTS.md ИЛИ @AGENTS.md + extras
├── .cursor/rules/                         # точечные override только для Cursor
├── .github/copilot-instructions.md        # «См. AGENTS.md», если используется
└── docs/architecture.md                   # глубокая архитектура, на которую AGENTS.md ссылается

Подробнее про CLAUDE.md - в гайде «Как настроить CLAUDE.md правильно». Если нужен глубже контекст про второй мозг и зачем агенту вообще большой файл инструкций - читай «Второй мозг в Claude Code» и «Что такое контекст-инжиниринг».

Что изменилось в 2026: зачем AAIF подобрала AGENTS.md под Linux Foundation?

Главная политическая история мая 2026 вокруг ИИ-кодинга - не очередной релиз модели, а консолидация форматов. Раньше каждый вендор тянул свой файл правил, и это было удобно вендорам, но мучительно командам, которые работали с несколькими инструментами.

Linux Foundation в пресс-релизе от 9 декабря 2025 объявила Agentic AI Foundation как зонтик для трёх форматов:

• AGENTS.md от OpenAI - формат файла-инструкции для агентов
• Model Context Protocol (MCP) от Anthropic - протокол подключения внешних инструментов к агентам
• goose от Block - open-source агент-фреймворк

Цитата Jim Zemlin, исполнительного директора Linux Foundation:

«Объединение этих проектов под крышей AAIF гарантирует, что они смогут развиваться с прозрачностью и стабильностью, которые даёт только открытое управление.»

(Linux Foundation press release, 9 декабря 2025, перевод с английского)

К 24 февраля 2026 в AAIF состояло 146 организаций (+97 новых за два месяца). Среди новых Gold-членов - Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, Hitachi, UiPath, American Express, Autodesk. Anthropic - на Platinum-уровне, продвигает MCP. OpenAI - на Platinum-уровне, продвигает AGENTS.md. Block - на Platinum-уровне с goose.

Это меняет позиционирование AGENTS.md: из «формата OpenAI» он стал «индустриальным стандартом, к которому Anthropic присоединилась как Platinum-член AAIF, но Claude Code пока не реализовал нативную поддержку». Бюрократический парадокс, но в индустрии он работает - формат закрепился, дальше дело времени, когда Claude Code добавит поддержку или окончательно зафиксирует CLAUDE.md как параллельный путь.

Для вайб-кодера на 2026 рабочая стратегия одна: AGENTS.md в корне + CLAUDE.md как symlink или import. Это покрывает 95% сценариев и не привязывает тебя к одному вендору.

Что дальше

AGENTS.md - это первый кирпич в стене «как договориться с агентом, чтобы он работал предсказуемо». Дальше идёт второй кирпич - Второй мозг проекта, в котором лежит бизнес-контекст, аудитория, продукты, цены. И третий кирпич - контекст-инжиниринг, который собирает всё в систему: какие файлы агент видит на каждом шаге, как сохраняется состояние между сессиями, как переключаться между разными моделями.

Один AGENTS.md без двух других - это правила игры без поля и без мяча. Полная схема - на практикуме за три эфира. ИИ-клон + Второй мозг + Контекст-инжиниринг. Записи остаются.

Практикум по вайб-кодингу

+Твой второй мозг

3 вечера - стек, метод, первый проект

Старт 9–11 июня  ·  2 000 ₽

Записаться →