AGENTS.md: пример, шаблон и 5 правил за 30 минут

Практические советы по вайб-кодингу и работе с ИИ-агентами собраны в документации Ailoot.

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

В этом руководстве формат рассматривается по материалам agents.md, документации OpenAI Codex, JetBrains Junie, Cursor Rules, GitHub Copilot Coding Agent и пресс-релизу Linux Foundation об Agentic AI Foundation. Числа и сведения о возможностях приведены по состоянию на 30 мая 2026 года. О поддержке AGENTS.md в Claude Code рассказывается по документации Anthropic, с учётом обновления от 24 сентября 2026 года.

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

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

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

В августе 2025 года OpenAI выпустила Codex CLI и представила открытый формат на сайте agents.md. Там его сравнили с README, предназначенным для агентов:

«Представьте AGENTS.md как README для агентов».

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

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

На сайте также объясняется:

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

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

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

Так общий файл инструкций стал форматом, который используют разные разработчики ИИ-инструментов, а не только OpenAI.

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

Сводка поддержки на 30 мая 2026 года; сведения о Claude Code обновлены 24 сентября 2026 года:

В августе 2025 года в официальном репозитории anthropics/claude-code открыли issue №6235 с запросом на поддержку AGENTS.md. В ней отмечалось, что Codex, Amp, Cursor и другие инструменты движутся к общему Markdown-файлу с инструкциями по проекту, тогда как CLAUDE.md предназначен только для Claude Code.

Обсуждение закрыли 17 августа 2026 года, а 18 сентября вышла версия 2.1.277 с поддержкой AGENTS.md. Правило Anthropic таково: CLAUDE.md имеет приоритет, а AGENTS.md используется, если CLAUDE.md нет в рабочей папке и родительских каталогах. Документация описывает следующие случаи:

Учитывается и личный файл CLAUDE.local.md: если он есть, Claude Code перестаёт самостоятельно читать AGENTS.md. Настройку можно изменить в /config, в разделе Project instructions, например включив чтение обоих файлов. В версиях старше 2.1.277 файл AGENTS.md по-прежнему нужно подключать строкой @AGENTS.md внутри CLAUDE.md.

AGENTS.md и другие форматы инструкций удобно сопоставить по тому, какие инструменты их читают и как эти файлы устроены.

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

Сравнение форматов по состоянию на 30 мая 2026 года:

AGENTS.md решает задачу общих правил для разных агентов, но не предоставляет личные настройки, которые не нужно коммитить. Для этого в Claude Code есть CLAUDE.local.md, а в Cursor — локальные файлы .mdc. Сам по себе AGENTS.md таких настроек не даёт: можно сочетать форматы или отдельно договориться в команде, как хранить личные правила и исключать их из Git.

Есть и вопрос расположения файлов в монорепозитории. Codex и Cursor применяют правило ближайшего AGENTS.md: отдельный файл можно поместить в пакет, а инструмент использует инструкции, ближайшие к текущей папке.

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

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

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

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

Сайт agents.md оставляет структуру свободной: подойдёт любой Markdown. Однако во многих полезных файлах повторяется один набор из восьми разделов. Следите, чтобы каждый пункт содержал конкретную команду или пример, а не расплывчатое пожелание.

1. Обзор проекта — две-три строки о назначении проекта, его пользователях и основной цели; без рекламных формулировок. Например: «Telegram-бот для онбординга в платный практикум. Стек: Next.js 14, Prisma, PostgreSQL. Запускается при добавлении новой записи в purchases».
2. Команды настройки — точные команды для запуска проекта локально: npm install, npm run dev, npm run build. Не ограничивайтесь советом «обычно делаем так».
3. Стиль и соглашения по коду — конкретные требования с примерами. Например: «Строгая типизация TypeScript, одинарные кавычки, без экспортов по умолчанию; компоненты называются в PascalCase, хуки — с префиксом use».
4. Среда разработки — укажите важные параметры: какие переменные нужны в .env, где хранить секреты, какие порты используются и как работать с локальной базой данных.
5. Тестирование — опишите команду запуска и условие успешного результата. Например: npm test -- --testPathPattern=user-auth; все тесты должны завершиться успешно.
6. Правила для PR и коммитов — задайте формат сообщений коммитов, проверок перед PR и согласования изменений.
7. Безопасность — перечислите конкретные запреты: «Не коммить .env. Храни секреты только в Vault. Не добавляй персональные данные пользователей в логи».
8. Границы и запреты — укажите, чего не делать, и приведите безопасный вариант. Например: «Не запускай 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)
- Не используй `npm install -g` или `sudo` для проектных зависимостей
- Не добавляй новые зависимости без согласования (особенно тяжёлые: webpack-плагины, ORM)

Обычно такой файл занимает 80–120 строк. Если объём превысил 150 строк, проверьте, какие подробности можно вынести в docs/, заменить ссылкой или сформулировать короче. По приведённым в исходном тексте данным исследования, оптимальная длина находится в пределах 100–150 строк, а после превышения этого объёма прирост качества начинает снижаться.

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

1. Команды вместо пожеланий. Фразу «осторожно работай с миграциями» легко пропустить. Команда alembic check перед alembic upgrade head задаёт ясное действие. Формулируйте правило как «сделай X; если условие Y не выполнено — поступи так-то».

2. Запреты вместе с альтернативами. Одного «не делай force push» может быть недостаточно. Лучше написать: «Не используй git push --force для main; если нужно отменить изменение, выполни git revert или создай новый PR».

3. Единое место для актуальных правил. Корневой AGENTS.md содержит общие инструкции проекта. В монорепозитории к ним можно добавлять отдельные AGENTS.md в подпапках, чтобы ближайший к рабочей области файл уточнял локальные правила. Проверяйте, чтобы файлы не противоречили друг другу.

4. Условия готовности, которые можно проверить. «Тесты должны проходить» — недостаточно конкретно. Лучше задать критерий: команда npm test завершается с кодом 0 и не выводит FAIL. Условие «код должен быть чистым» можно уточнить так: npm run lint завершается без предупреждений.

5. Умеренный размер. Старайтесь уложить файл в 150 строк. Дополнительное описание архитектуры перенесите в docs/architecture.md, а из AGENTS.md дайте ссылку. В основном файле оставьте команды, ключевые правила и ограничения.

Какие 10 ошибок превращают AGENTS.md в бесполезный файл?#

1. Общие пожелания вместо точных действий. Совет «осторожно выполняй миграции» не объясняет, что делать. Укажите последовательность: «Перед alembic upgrade head запусти alembic check. Если проверка завершилась ошибкой, не применяй миграцию и уточни дальнейшие действия».

2. Фраза «чистый код». Она не задаёт конкретного образца. Замените её правилом: «Используй функциональные компоненты и хуки. Например: function LoginForm() { const [email, setEmail] = useState(''); ... }».

3. Текст без заголовков и списков. В документе на сотни строк сплошного текста нужное правило легко потерять. Разбейте содержание заголовками H2/H3 и короткими пунктами.

4. Слишком длинный файл. Если AGENTS.md занимает больше 150 строк, перенесите подробности в отдельные документы в docs/ и оставьте на них ссылки.

5. Много запретов без указания следующего шага. Перечень «не делай X, не делай Y» оставляет агента без понятной альтернативы. К каждому запрету добавьте разрешённое действие.

6. Повторение README.md. Не копируйте инструкции по установке и запуску, если они уже есть в README. Дайте ссылку и оставьте в AGENTS.md контекст, нужный агенту.

7. Настоящие секреты в файле. AGENTS.md может храниться в Git и быть доступен другим. Не вставляйте ключи API, токены и пароли; вместо этого укажите место их безопасного хранения, например Vault: secret/staging/db.

8. Неясная расстановка приоритетов. Правила «делай быстро» и «обеспечь покрытие тестами на 90%» могут конфликтовать. Укажите, что главнее: «Сначала добейся покрытия не ниже 80%, затем оптимизируй скорость. Если требования конфликтуют, приоритет у тестов».

9. Устаревшая документация. Если описание говорит о REST и опросе сервера, а проект уже перешёл на WebSockets, агент может принять неверное решение. Обновляйте AGENTS.md в том же PR, что и соответствующий код.

10. Избыточные детали архитектуры. Чтобы изменить пару строк конфигурации, агенту не нужно читать описание всех 14 микросервисов. Вынесите подробную схему в docs/architecture.md, а здесь добавьте правило читать её для архитектурных задач.

В официальной публикации GitHub Blog о разборе более 2500 файлов AGENTS.md общий вывод сформулирован так: чрезмерно общие инструкции часто мало помогают; фраза «You are a helpful coding assistant» сама по себе не даёт агенту полезных указаний.

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

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

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

Сценарий 2: несколько клиентов разработки. Храните общие правила в AGENTS.md и отдельно подключайте и проверяйте каждый клиент. Gemini CLI поддерживает настройку имени файла контекста, а Aider — загрузку через настройку чтения. Это явные способы подключения, а не одинаковый автоматический поиск.

Откройте новую сессию в безопасном тестовом репозитории. Добавьте уникальную безвредную инструкцию, например «включи маркер instructions-loaded в тестовый ответ», и проверьте как ответ, так и документированный список загруженных файлов или журнал клиента. Повторите для каждого используемого клиента и версии. Заявление самой модели о чтении файла не является независимым доказательством загрузки; один успешный тест не подтверждает поддержку во всех остальных инструментах.

Сценарий 3: Claude Code работает вместе с другими агентами. Основным файлом можно назначить AGENTS.md. Если отдельные инструкции для Claude Code не нужны, CLAUDE.md можно не создавать: начиная с версии 2.1.277 Claude Code сам прочитает AGENTS.md, когда в проекте нет CLAUDE.md. Если специальные правила нужны, подключите AGENTS.md символической ссылкой или импортом @AGENTS.md.

Перед изменением изучите и сохраните оба файла. Если они уже существуют, объедините непротиворечивые общие правила в AGENTS.md, а специальные инструкции Claude оставьте в CLAUDE.md с импортом @AGENTS.md. Существующие символические ссылки сохраняйте.

Для обычного CLAUDE.md только при отсутствии AGENTS.md следующая проверка macOS/Linux не перезапишет ни файл, ни символическую ссылку:

if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then
  printf '%s\n' 'STOP: AGENTS.md exists; merge both files first.' >&2
elif [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then
  mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md
else
  printf '%s\n' 'STOP: inspect the existing CLAUDE.md path first.' >&2
fi

После успешного переименования CLAUDE.md становится символической ссылкой на AGENTS.md. Инструменты находят общие правила по обоим именам.

В Windows для создания символической ссылки может потребоваться режим разработчика или права администратора. Более простой вариант — короткий 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. Если общий файл больше не нужен, импорт можно убрать. Согласно документации Claude Code, повторного чтения одного AGENTS.md не происходит, даже когда он доступен инструменту напрямую.

Для команды, использующей несколько инструментов, структура репозитория может выглядеть так:

repo-root/
├── AGENTS.md                              # общий источник правил, не более 150 строк
├── CLAUDE.md                              # только при наличии особых правил для Claude: ссылка или @AGENTS.md и дополнения
├── .cursor/rules/                         # точечные правила для Cursor
├── .github/copilot-instructions.md        # «См. AGENTS.md», если файл используется
└── docs/architecture.md                   # подробная архитектура, на которую ссылается AGENTS.md

Подробнее о CLAUDE.md рассказывает руководство «Как настроить CLAUDE.md правильно». О контекст-инжиниринге можно узнать в отдельном руководстве.

Что изменилось в 2026 году: почему AAIF включила AGENTS.md в Linux Foundation?#

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

В пресс-релизе от 9 декабря 2025 года Linux Foundation сообщила о создании Agentic AI Foundation и назвала три проекта, вошедших в неё:

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

В пресс-релизе Linux Foundation отмечалось:

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

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

К 24 февраля 2026 года в AAIF входили 146 организаций; за два месяца к фонду присоединились ещё 97 участников. Среди новых золотых участников — Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, Hitachi, UiPath, American Express и Autodesk. Anthropic, OpenAI и Block вошли в число платиновых участников и поддерживали соответственно MCP, AGENTS.md и goose.

Таким образом, AGENTS.md получил поддержку организаций, работающих над разными агентскими инструментами. В сентябре 2026 года Claude Code также научился читать этот файл, хотя расположенный в проекте CLAUDE.md обычно имеет приоритет.

Для проекта, использующего агентов от нескольких разработчиков, практический вариант — хранить общие инструкции в AGENTS.md. Добавляйте CLAUDE.md, если нужны дополнительные правила только для Claude Code; общий файл можно подключить импортом @AGENTS.md или символической ссылкой.

Что дальше#

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

Практические материалы по работе с ИИ-инструментами и агентами доступны в документации Ailoot.

Больше материалов и инструментов — на Ailoot.