Откройте репозиторий, в котором работают с несколькими AI-инструментами, и вы найдёте рядом почти одинаковые файлы инструкций: CLAUDE.md, AGENTS.md, .github/copilot-instructions.md. Каждый инструмент читает свой. Каждый хранит одну и ту же копию правил проекта. И каждая копия гниёт в тишине: поправили одну, остальные остались на версию позади.
Японский разработчик Такаши Мацуяма описал эту ситуацию в посте от 11 июля 2026 года:
Open a repository these days and you’ll find several nearly identical agent-instruction files sitting side by side — CLAUDE.md, AGENTS.md, .github/copilot-instructions.md. This post is about ending that sprawl not by hand-syncing it forever, but with declaration and verification.
Открой репозиторий — и найдёшь рядом несколько почти одинаковых файлов-инструкций для агентов: CLAUDE.md, AGENTS.md, .github/copilot-instructions.md. Этот пост о том, как закончить этот зоопарк — не бесконечной ручной синхронизацией, а декларацией и проверкой.
— Takashi Matsuyama, «Ending the CLAUDE.md / AGENTS.md / copilot-instructions.md Sprawl»
Проблема знакома каждому, кто работает в команде, где одни используют Claude Code, другие — Codex, третьи — Cursor. Ниже — как устроен единый стандарт AGENTS.md, почему его нельзя слить в один файл со всеми инструментами и как команда Kobiton решает ту же задачу на практике.
Что такое AGENTS.md
AGENTS.md — это обычный Markdown-файл в корне репозитория, который агент читает при старте сессии. Спецификация определяет его как «README для агентов»:
Think of AGENTS.md as a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project.
Воспринимайте AGENTS.md как README для агентов: предсказуемое место, где лежит контекст и инструкции, помогающие AI-агентам работать над вашим проектом.
README.md остаётся для людей: обзор, быстрый старт, гайд для контрибьюторов. AGENTS.md дополняет его тем, что нужно именно агенту: команды сборки, правила тестирования, соглашения, «так делать нельзя». Отдельный файл, а не секция в README, — осознанное решение: README не раздувается, а у агента есть предсказуемое место, куда смотреть.
Кто за этим стоит. Формат родился из совместной работы нескольких компаний — OpenAI Codex, Amp, Google (Jules), Cursor и Factory. Сейчас спецификацию опекает Agentic AI Foundation под эгидой Linux Foundation.
Масштаб на август 2026:
— больше 733 000 открытых репозиториев содержат AGENTS.md (поиск на GitHub);
— по словам Мацуямы, файл читают более двадцати инструментов;
— в главном монорепозитории OpenAI — 88 вложенных AGENTS.md для отдельных пакетов (пример на agents.md).
Никаких обязательных полей в формате нет. Это просто Markdown: структура — на ваше усмотрение, агент разбирает текст как есть. FAQ спецификации прямо отвечает на вопросы о поведении: ближайший к редактируемому файлу AGENTS.md выигрывает, явные команды пользователя в чате перекрывают всё, а перечисленные команды тестов агент попытается запустить сам.
Что писать в AGENTS.md
Спецификация советует покрыть секции: обзор проекта, команды сборки и тестов, стиль кода, инструкции по тестированию, вопросы безопасности. Вот реальный пример из спецификации:
# AGENTS.md
## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`
## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible
Документация Claude Code добавляет к этому практическое правило о формулировках: «используй отступы в 2 пробела» вместо «форматируй код аккуратно», «запусти npm test перед коммитом» вместо «тестируй изменения». Конкретика, которую можно проверить, работает надёжнее общих пожеланий.
Пример посложнее — реальный AGENTS.md из репозитория OpenCode (документация проекта, раздел Rules):
# SST v3 Monorepo Project
This is an SST v3 monorepo with TypeScript. The project uses bun workspaces for package management.
## Project Structure
- `packages/` - Contains all workspace packages (functions, core, web, etc.)
- `infra/` - Infrastructure definitions split by service (storage.ts, api.ts, web.ts)
## Code Standards
- Use TypeScript with strict mode enabled
- Shared code goes in `packages/core/` with proper exports configuration
## Monorepo Conventions
- Import shared modules using workspace names: `@my-app/core/example`
Если файл разросся — в монорепо кладите вложенные AGENTS.md в подпакеты: агент читает ближайший к редактируемому файлу. Так сделано в OpenAI (88 файлов) и так устроен приоритет по спецификации.
Сравнительная таблица: какой инструмент что читает
Каждый крупный AI-инструмент принёс собственное имя файла. Матрица по состоянию на июль 2026 (по Мацуяме, строки по OpenCode — из его документации):
| Инструмент | Файл, который читает | Читает ли AGENTS.md |
|---|---|---|
| Claude Code (Anthropic) | CLAUDE.md |
нет, даже как fallback |
| Codex CLI (OpenAI) | AGENTS.md |
да, нативно |
| GitHub Copilot | .github/copilot-instructions.md |
кодинг-агент Copilot — да |
| Cursor | AGENTS.md |
да (.cursor/rules — отдельный механизм; старый .cursorrules помечен deprecated) |
| OpenCode | AGENTS.md |
да (при отсутствии — fallback на CLAUDE.md) |
| Gemini CLI | AGENTS.md (настраивается) |
да |
| Windsurf | AGENTS.md |
да |
| Aider | AGENTS.md (через .aider.conf.yml) |
да |
| Zed, VS Code, JetBrains Junie, Devin, Jules и др. | AGENTS.md |
да |
Ключевая асимметрия — Claude Code. Он читает CLAUDE.md, а не AGENTS.md. И, вопреки популярному заблуждению, не читает AGENTS.md даже как запасной вариант:
It doesn’t even read AGENTS.md as a fallback (the claim that “it reads AGENTS.md if CLAUDE.md is absent” is wrong). Start Claude Code in a repo that has only AGENTS.md and you’ll get no error — it just runs, cheerfully, with zero project instructions loaded.
Он не читает AGENTS.md даже как fallback (утверждение «читает AGENTS.md, если CLAUDE.md нет» — неверно). Запусти Claude Code в репозитории, где есть только AGENTS.md, — ошибки не будет: он просто работает, беззаботно, с нулём загруженных инструкций.
Запрос на поддержку AGENTS.md в Claude Code висит в issue #6235 с августа 2025 года — открыт, с метками area:core, enhancement, memory, без назначенного исполнителя. Официальная документация Anthropic подтверждает: «Claude Code reads CLAUDE.md, not AGENTS.md», — и предлагает два способа жить с этим: импорт или симлинк (о них ниже).
Именно из-за этой одной строки нельзя «просто стандартизироваться на одном AGENTS.md»: пока вы пользуетесь Claude Code, CLAUDE.md придётся держать в любом случае.
Практика: как создать AGENTS.md
Возьмём за основу кейс Мацуямы — он разбирает решения от наивных к рабочим.
Шаг 1. Создайте файл. Начните с команд сборки и тестов, структуры, соглашений. Многие инструменты умеют генерировать заготовку: команда /init в OpenCode анализирует репозиторий и создаёт или дополняет AGENTS.md (если файл уже есть — улучшает, а не перезаписывает). /init в Claude Code, в свою очередь, умеет читать правила Cursor (.cursor/rules, .cursorrules) и Copilot (.github/copilot-instructions.md) и переносить релевантное в генерируемый CLAUDE.md.
Шаг 2. Наивные решения и их пределы.
Копипаст. Скопировать одно тело во все файлы. Работает один раз. Со второй правки любое изменение правила требует редактирования N файлов, и человек всегда про кого-то забывает. Глазом не отличить, какая копия актуальна. Это два внутренних предела копипаста: стоимость синхронизации и невозможность заметить гниение.
Импорт. У Claude Code есть синтаксис импорта @path. Строка @AGENTS.md первой в CLAUDE.md разворачивается при старте в содержимое AGENTS.md:
<!-- CLAUDE.md -->
@AGENTS.md
Реальное тело живёт в одном месте, CLAUDE.md — однострочный стаб. Поверх импорта можно дописать инструмент-специфичные правила — например, «для изменений в src/billing/ используй plan-режим». Ограничения: синтаксис импорта не универсален (в Copilot-инструкциях тот же трюк не работает), а дисциплина «стаб в одну строку» рано или поздно проседает — и дрейф возвращается.
Шаг 3. Симлинк — рабочий вариант для одного репозитория. Делаем AGENTS.md каноническим файлом, а CLAUDE.md и .github/copilot-instructions.md — симлинками на него:
myrepo/AGENTS.md # канонический файл — правим только его
myrepo/CLAUDE.md -> AGENTS.md
myrepo/.github/copilot-instructions.md -> ../AGENTS.md
Команды, если тело сейчас живёт в CLAUDE.md:
git mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.md
mkdir -p .github
ln -s ../AGENTS.md .github/copilot-instructions.md
Относительные пути — ключевой трюк: репозиторий можно клонировать куда угодно, и ссылки разрешаются внутри него сами. Инструмент открывает CLAUDE.md, а файловую систему резолвит ОС — агенту не нужно ничего знать про симлинк. Официальная документация Claude Code прямо приводит ln -s AGENTS.md CLAUDE.md как допустимый вариант.
Git хранит симлинк как есть — блоб режима 120000, содержимое которого — путь назначения:
$ git ls-files -s AGENTS.md CLAUDE.md .github/copilot-instructions.md
120000 … .github/copilot-instructions.md # симлинк
100644 … AGENTS.md # реальный файл
120000 … CLAUDE.md # симлинк
Грабли Windows: для корректного checkout симлинков нужен core.symlinks=true плюс Developer Mode или права администратора. Без этого симлинк разворачивается в текстовый файл, содержимое которого — путь. Команде, где есть Windows-разработчики, стоит проверить это сразу. Альтернатива для Windows — импорт @AGENTS.md, который работает без прав.
Шаг 4. Куда симлинки не дотягиваются. Три проблемы вскрываются, когда репозиторий не один:
- Публичное и приватное. Если в инструкциях есть непубличные планы, настоящий файл в истории публичного репозитория раскрывает их. Симлинк прячет содержимое, но путь назначения — раскладка каталогов приватной стороны — всё равно попадает в историю.
- Несколько репозиториев. Чем больше репозиториев, тем хуже работает ручная привязка.
- Гниение самой проводки. Симлинк пропал, сломался или указывает не туда — глазом не отследить.
Мацуяма решает это ритмом из трёх шагов: declare (объявить канон), generate (сгенерировать проводку), verify (проверить). Его собственный инструмент basou кладёт объявления в манифест, генерирует симлинки всех репозиториев к приватному «якорю» (agents/<repo>/AGENTS.md) и проверяет расхождения и приватность. Но для старта инструмент не нужен: объявить канон можно строкой в документе, проводку разложить парой строк скрипта, а проверку начать с трёх строк в CI, которые диффят ожидаемый вывод git ls-files -s. Сама идея — «как должно быть» существует в виде кода, а не прозы, и машина сообщает, когда оно сломалось.
Честная позиция автора: для одного репозитория без инструмент-специфичных правил достаточно симлинков из шага 3 — его собственный блог живёт ровно в такой форме. А если нужны индивидуальные инструкции для конкретного агента — это домен импорта: полная симлинк-унификация под него ответа не даёт.
Кейс Kobiton: AGENTS.md как кросс-инструментальный бриф
Второй источник — кейс Джереми Лонгшора от 11 мая 2026 года про плагин Kobiton. Компания Kobiton — провайдер облака реальных мобильных устройств; их плагин kobiton/automate — тонкий Claude Code-плагин, который подключает агента к удалённому MCP-серверу (api.kobiton.com/mcp). В репозитории 12 MCP-инструментов: устройства (listDevices, reserveDevice…), сессии (listSessions, terminateSession…), приложения (uploadAppToStore, getApp…).
Лонгшор прогнал по облаку пять устройств (Galaxy A52s, moto g(7) play, iPhone XR, iPhone 14 Plus, iPad 9-го поколения) сценарием: открыть Appium-сессию, сделать пять скриншотов, замерить время загрузки, завершить сессию. Цифры:
| Пул | ОС | Модель | Boot, мс | Скриншот p50, мс |
|---|---|---|---|---|
| PRIVATE | Android 13 | Galaxy A52s 5G | 4 206 | 353 |
| CLOUD | Android 9 | moto g(7) play | 5 451 | 297 |
| PRIVATE | iOS 17.5.1 | iPhone XR | 5 091 | 242 |
| CLOUD | iOS 18.6 | iPhone 14 Plus | 4 490 | 306 |
| CLOUD | iOS 18.6.2 | iPad 9-го поколения | 5 259 | 256 |
Время загрузки разбросано на ~30%, p50 скриншотов — на ~46%. Android в среднем ~325 мс на скриншот, iOS ~268 мс — примерно на 17% быстрее. Самый быстрый скриншот снят с iPhone XR (828×1792), самый медленный — с Galaxy A52s (1080×2400): разрешение разброс не предсказывает.
Разница в 57 мс кажется мелочью, пока не накапливается: 100 тестов × 50 прогонов в день × 3 скриншота — это ~855 секунд в день на медленном пути, около 7 часов в месяц. Пять скриншотов на тест — уже ~12 часов в месяц.
Главное — не цифры, а то, что плагин их не документировал. Два пробела, которые AGENTS.md закрыл бы до начала тестов:
Совместимость эндпоинтов. driver.getLogs('logcat') не вернул данных через эндпоинт, который попробовал клиент. Документация Appium различает /session/:sessionId/log и /session/:sessionId/se/log — какой работает, зависит от драйвера и сервера. Плагин должен сразу говорить, какие эндпоинты логов поддерживает, какие отклоняет и что агенту делать при сбое. Иначе портированный тест молча теряет логи: тест проходит, а доказательства исчезли.
Невидимость жизненного цикла. После deleteSession устройства уходят в короткий cooldown. В это окно getDeviceStatus сообщал ACTIVATED и is_online=true, но новую сессию устройство принять не могло. Наивный планировщик видит «готово» и ставит следующую задачу в очередь. Лечится документированным жизненным циклом: ready / reserved / active / cleanup-required / cooldown-required / offline / unknown. Названия вторичны; главное — чтобы is_online=true не значило «готов к сессии», файл должен сказать это вслух.
Both gaps are documentation, not code.
Оба пробела — это документация, а не код.
Практический итог: PR #10 в репозиторий добавляет AGENTS.md и поддержку GitHub Copilot CLI — пять изменённых файлов, 75 строк. Доля кода — переносимость: нейтральные формулировки вместо «клод-специфичных», явные пути к скиллам и MCP. Плагин переезжает с «работает в Claude Code» на «любой разумный кодинг-агент прочитает и поведёт себя правильно».
Композиция файлов, по Лонгшору, выглядит так:
| Файл | Для кого | Что содержит |
|---|---|---|
README.md |
люди | обзор и установка |
CLAUDE.md |
Claude Code | специфичные для Claude инструкции |
SKILL.md |
агенты | триггер и сценарий скилла (спека AgentSkills.io) |
AGENTS.md |
любой агент | кросс-инструментальные операционные инструкции |
Ни один не заменяет другой — они дополняются. В сильном AGENTS.md для MCP-плагина должны быть: возможности, стоимость и задержки (p50/p95, тайминги скриншотов, лимиты загрузки, разброс по платформам), состояния жизненного цикла, границы совместимости, требования к оркестратору. Когда спецификация есть, агент принимает решения вместо того, чтобы гадать: «этот набор тестов идёт на более быстрый путь захвата», «этому устройству нужен cooldown».
В постскриптуме от 7 мая 2026 года — развитие: команда смёржила поддержку Copilot CLI (PR #10) и открыла PR #28 с расширением для Gemini CLI. Все три CLI используют один AGENTS.md, один и тот же MCP-эндпоинт через OAuth dynamic discovery (RFC 9728) и одну конвенцию skills/<name>/SKILL.md. Три командные строки против одного источника правды — и ноль изменений на стороне сервера. OpenAI Codex CLI напрашивается четвёртым: AGENTS.md читает нативно, MCP-серверы объявляются в ~/.codex/config.toml, единственное отличие — формат конфига (TOML вместо JSON).
Российские реалии
Сам файл AGENTS.md — это Markdown в git-репозитории. Его не нужно блокировать, ему не нужен VPN, аккаунт, регистрация или карта: он работает офлайн и с любым инструментом. Вопрос только в инструментах, которые его читают:
- OpenCode — open source, работает без аккаунта и без VPN из РФ (проверено на практике: разбор опыта — на spryt.ru, установка — в нашем гайде). С
AGENTS.mdработает нативно. - Aider — open source, дружит с локальными моделями; для работы в РФ доступен без ограничений (статья про Aider и локальные модели).
AGENTS.mdподключается одной строкой в.aider.conf.yml. - Cursor — сайт и сервис доступны из РФ без VPN, но оплата российскими картами не работает: нужна карта иностранного банка или посредник (подробно — в гайде по Cursor). Читает
AGENTS.md. - Claude Code — Россия отсутствует в списке поддерживаемых стран Anthropic: VPN обязателен, российские карты не принимаются (разбор в нашем гайде, подтверждение geo-блокировки — обзор ЦНИС на Хабре, июнь 2026). Читает
CLAUDE.md, так что файл придётся дублировать или связывать. - GitHub Copilot — работает, но оплата картами РФ — та же история, что с Cursor.
Русскоязычных материалов по самой теме почти нет — и это стоит сказать прямо. Поиск на Хабре по «AGENTS.md» и «CLAUDE.md» на 5 августа 2026 года не находит релевантных статей — на Хабре больше 200 материалов по AI-агентам, но специальных разборов именно AGENTS.md как стандарта почти нет; тема всплывает внутри обзоров Claude Code и агентного кодинга. Живые источники по смежным темам: обзор про Claude из РФ на Хабре (июнь 2026), Lifehacker про Claude в 2026 (апрель 2026), реальный опыт вайбкодинга из РФ и англоязычный, но живой r/ClaudeAI. Фактически эта статья — один из первых русскоязычных разборов именно AGENTS.md.
Советы и грабли
Собраны из кейсов выше и обсуждений в r/ClaudeAI.
1. AGENTS.md — конвенция, а не принуждение. Содержимое файла попадает в контекст как сообщение пользователя после системного промпта. Гарантии строгого соблюдения нет — особенно для расплывчатых или противоречащих друг другу инструкций (прямо сказано в документации Claude Code). Если правило должно исполняться железно — это хук, а не Markdown.
2. Держите файл коротким и конкретным. Документация Claude Code рекомендует держать CLAUDE.md в пределах ~200 строк: длинные файлы съедают контекст и снижают следование. Структура заголовками и буллетами работает лучше плотных абзацев. «Используй отступы в 2 пробела» — лучше, чем «форматируй код аккуратно».
3. Один источник правды. Как только у вас появляются копии — появляется гниение. Выберите канон (AGENTS.md), остальные файлы сделайте симлинками или импортами. Периодически проверяйте, что проводка на месте: git ls-files -s покажет режим 120000, в Claude Code — команда /context покажет, какие файлы памяти реально загружены.
4. Не кладите секреты и непубличные планы в AGENTS.md публичного репозитория. Симлинк прячет содержимое, но путь назначения попадает в историю git. Если приватная информация должна остаться приватной — держите канон в приватном репозитории-«якоре», как в схеме basou у Мацуямы.
5. Файл-конвенций не спасает от устаревания — только делает его заметным. Пользователь rehawks в треде r/ClaudeAI от 30 июля 2026 проверил простую схему контроля: папка коммиченных ADR (записей архитектурных решений) плюс строка в файле-конвенциях «Architecture decision records live in decisions/. Consult them when proposing or making architectural and tooling choices». Результат: 45/45 на Opus в контрольном сравнении, и во всех 120 контрольных запусках агент обращался к папке ADR через Read, Grep или Glob. Агент находит и читает файлы — но не проверяет их свежесть. Комментатор Beautiful-Energy2169 посчитал markdown в 14 репозиториях: 1 879 файлов, 317 из них — явно продукт агентов, и 54% этих файлов были либо устаревшими относительно git, либо осиротевшими. Худший случай — handoff-документ на 126 КБ, не тронутый 51 день и всё ещё ссылающийся из отслеживаемого файла: каждая новая сессия читала его как актуальное состояние проекта. «Мусор попал туда, будучи однажды правильным», — формулирует он. Практический рецепт из треда: помечать агентские документы коммитом, против которого они написаны, и читать с подозрением всё, что сильно отстало от HEAD.
6. Платформенные грабли. Windows: симлинки требуют core.symlinks=true + Developer Mode; иначе — текстовый файл с путём вместо ссылки. Импорт @AGENTS.md в Claude Code работает и без прав, но синтаксис импорта не поддерживается Copilot-инструкциями.
7. Запускайте заготовку через /init. OpenCode генерирует AGENTS.md сам, анализируя репозиторий; Claude Code — читает правила Cursor и Copilot и переносит их в CLAUDE.md. Старт с заготовки дешевле, чем ручное перечисление команд.
Ограничения
- Нет жёсткого исполнения. Файл конвенций читается как контекст, а не как политика. Агент может проигнорировать правило; против этого работает только конкретика формулировок или хук.
- Claude Code не читает AGENTS.md. Запрос на поддержку открыт с августа 2025 года (issue #6235), но на июль 2026 официальных признаков в роадмапе нет. Пока вы на Claude Code —
CLAUDE.md(стаб, импорт или симлинк) обязателен. - Markdown гниёт. Цифры из r/ClaudeAI: больше половины агентских md-файлов в выборке устарели или осиротели. Файл-конвенций снижает хаос, но не устраняет устаревание — его нужно проверять, как и любой другой код.
- Это не решение для контроля архитектуры. В том же треде rehawks ссылается на Питера Наура («Программирование как построение теории», 1985): теория о том, как код соотносится с задачей, живёт в головах людей, а не в Markdown. Агент может предложить решение, но не должен молча оставлять свои артефакты как принятое руководство для всех последующих агентов. Файл-конвенций не заменяет человека в точке принятия решения.
- Конфликты инструкций решаются в пользу ближайшего файла и явного чата. По спецификации побеждает ближайший к редактируемому файлу
AGENTS.md, а явные команды пользователя перекрывают всё. Если в двух файлах противоречащие правила — модель может выбрать произвольно. - Разные инструменты читают по-разному. Copilot-кодинг-агент и Codex понимают
AGENTS.md; Claude Code — нет; Cursor дополнительно держит отдельный механизм.cursor/rules. Унификация до одного файла на практике упирается в эту неоднородность.
Вывод
AGENTS.md стал де-факто стандартом: спецификацию опекает Agentic AI Foundation, файл читают два десятка инструментов, а в открытых репозиториях его больше 60 тысяч. Формат простой — обычный Markdown в корне проекта, и именно эта простота сделала его общим знаменателем.
Проблема зоопарка решается не очередным файлом, а выбором одного источника правды: каноном сделать AGENTS.md, а CLAUDE.md и .github/copilot-instructions.md — симлинками или импортами на него. Это работает в одном репозитории уже сегодня; на нескольких — добавляется проверка проводки (пара строк в CI, диффящих git ls-files -s). Кейс Kobiton показывает тот же принцип на уровне плагина: один AGENTS.md обслуживает Claude Code, Copilot CLI и Gemini CLI без изменений на стороне сервера.
Ограничение, которое нужно держать в голове: файл конвенций задаёт контекст, а не исполнение, и сам по себе не защищает от устаревания. Его сила — в том, чтобы у агентов был один предсказуемый источник правил, а у вас — место, где эти правила проверяются. Начать стоит с малого: один AGENTS.md с командами сборки и стилем, один симлинк для Claude Code — и из трёх копий правил останется одна.