Кросс-вендорный стандарт, который объясняет coding-агенту правила проекта, фиксирует контекст между сессиями и передаёт смену между заходами. Используется в 60 000+ репозиториев, поддерживается ведущими coding-агентами и IDE.

Что это

AGENTS.md — файл в корне репозитория, который описывает проект для ИИ-агентов: команды сборки, архитектуру, конвенции, границы и правила ревью. Это операционный контекст для LLM-агента, которому нужно стать продуктивным за 60 секунд.

Стандарт курируется Agentic AI Foundation при Linux Foundation с декабря 2025 года. К апрелю 2026: 60 000+ репозиториев используют AGENTS.md, поддержка встроена в OpenAI Codex, Cursor, Jules, GitHub Copilot, Zed, JetBrains и другие инструменты. Сам OpenAI Codex использует 88 таких файлов в своём монорепозитории.

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

Checkpoint — отдельный документ-передача смены для крупных рабочих потоков. Содержит полный контекст: где лежит код, как запускать, что сделано, что нельзя трогать.

**Ключевое правило:**три уровня памяти работают вместе. AGENTS.md = постоянные правила проекта. SESSION_NOTES = свежие события и решения. Checkpoint = полная карта крупного рабочего контура.

Зачем нужно

Coding-агент просыпается в новом мире каждую сессию. Без контекста даже сильная модель:

  • путает production с preview, потому что границы проекта ей неизвестны;
  • теряет всё, что было сделано вчера;
  • рискует затронуть файлы, которые менять нельзя;
  • выполняет действия, требующие отдельного approval;
  • начинает каждый заход с археологии по истории чата.

AGENTS.md снижает этот риск, давая агенту правила до начала работы. SESSION_NOTES.md убирает проблему потери контекста между сессиями. Checkpoint передаёт полный контекст при смене смены — когда новый агент или новый чат берётся за сложный рабочий поток.

**Инсайт:**это не про «больше документации». Это про то, чтобы агент тратил свои первые 60 секунд на работу, а не на угадывание правил проекта.

Как устроено

Структура AGENTS.md

GitHub опубликовал исследование «How to write a great agents.md: Lessons from over 2 500 repositories» (ноябрь 2025) с практическими выводами о том, какие паттерны работают лучше всего:

ПаттернЭффект
Нумерованные воркфлоуповышают корректность вывода агента
Секция Commandsнаибольший вклад в результативность — агент знает, как запускать и проверять
Таблицы решений (allowed / ask / never)улучшают соблюдение границ
Более 30 запретов (don’ts)снижают полноту — агент начинает чрезмерно перестраховываться
Файл больше 32 KiBCodex обрезает. Держите файл компактным

Рекомендованный каркас

  1. Project overview — 1 абзац: что это, какой стек.
  2. Setup — команды для быстрого старта.
  3. Common commands — build, dev, test, lint.
  4. Architecture — карта директорий.
  5. Code conventions — именование, экспорты, фреймворки.
  6. Boundaries — yes edit / ask / never (таблица).
  7. Testing — команды и паттерны.
  8. PR guidelines — формат коммитов, модель веток.
  9. Review guidelines — рубрика для автоматического ревью.

Вложенные файлы

В монорепозиториях помещайте отдельный AGENTS.md в каждый пакет. Codex разрешает ближайший файл первым — apps/web/AGENTS.md перекрывает корневой для работы в этой директории.

SESSION_NOTES.md

SESSION_NOTES фиксирует не план, а реальность:

  • что было сделано;
  • какие файлы добавлены или изменены;
  • какие проверки прошли;
  • какие решения приняты;
  • что не трогали и почему;
  • какой следующий безопасный шаг.

Новый заход читает хвост SESSION_NOTES и продолжает работу без повторной раскачки. Особенно ценно при длинных многоэтапных задачах: агент видит точку остановки и продолжает с неё.

Checkpoint — передача смены

Для крупных рабочих контуров SESSION_NOTES недостаточно. Checkpoint — отдельная страница, содержащая:

  • где лежит код и как запускать;
  • что сделано в каждой версии;
  • какие API доступны;
  • что выяснили на практике;
  • что нельзя делать без approval;
  • следующий шаг.

Это полноценная передача смены. Любой новый агент или сессия может открыть checkpoint и получить полную карту.

Совместимость с инструментами

ИнструментПоддержкаПримечание
OpenAI CodexнативноЧитает цепочку: ~/.codex → корень репо → вложенные пакеты
CursorнативноОдин из соавторов стандарта
Jules (Google)нативноАвтоматически ищет файл в корне репозитория
GitHub CopilotнативноCoding agent + вложенные файлы
ZedнативноЧерез систему правил (.rules, AGENTS.md, CLAUDE.md)
JetBrains AIнативноAgent instructions в IDE
Aiderчерез конфигДобавьте read: AGENTS.md в .aider.conf.yml
Claude CodeнетЧитает CLAUDE.md. Решение: ln -s AGENTS.md CLAUDE.md

**Совет:**для кросс-совместимости с Claude Code создайте симлинк ln -s AGENTS.md CLAUDE.md в корне репозитория. Один файл, оба агента читают его, нет рассинхрона.

Когда использовать

Минимальный старт (5 минут)

  • Создать AGENTS.md в корне репозитория.
  • Заполнить три секции: Project overview, Setup, Common commands.
  • Добавить секцию Boundaries с таблицей yes edit / ask / never.
  • Закоммитить.

Полная настройка (30 минут)

  • Выбрать подходящий архетип из шаблонного пакета (web app, monorepo, library, CLI, ML pipeline, content site, API service, IaC, mobile, data project).
  • Заменить плейсхолдеры: пути, команды, инструменты.
  • Добавить SESSION_NOTES.md в корень — первая запись: текущее состояние проекта.
  • Добавить симлинк ln -s AGENTS.md CLAUDE.md, если используете Claude Code.
  • Настроить секцию Review guidelines для автоматического ревью PR.

Поддержание

Относитесь к AGENTS.md как к коду. Ревьюйте при каждом PR-цикле (около 30 секунд). Признаки дрейфа:

  • Setup-команды не работают у нового участника — AGENTS.md врёт.
  • Агент повторяет одну и ту же ошибку — добавьте правило.
  • Карта архитектуры описывает несуществующие директории — почистите.

Когда AGENTS.md особенно полезен

СитуацияПодходитПочему
Монорепозиторий с несколькими сервисамидаВложенные AGENTS.md дают точечные правила для каждого пакета
Open-source проект с внешними контрибьюторамидаЛюбой coding-агент сразу понимает границы проекта
Работа в команде с несколькими агентами (Codex + Claude Code + Cursor)даКросс-вендорный стандарт читают все
Личный одноразовый скрипт на 50 строкнетОверкилл, AGENTS.md не нужен
Проект без gitнетAGENTS.md предполагает версионирование и ревью в PR

Пример

Минимальный рабочий AGENTS.md для fullstack-приложения:

# AGENTS.md

## Project overview
MyApp — fullstack-приложение на Next.js 14 + PostgreSQL + Prisma.

## Setup
npm install && cp .env.example .env.local && npm run db:migrate

## Common commands
- Dev: `npm run dev`
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

## Boundaries
| Область | Можно | Спросить | Нельзя |
| --- | --- | --- | --- |
| `src/` | edit | | |
| `prisma/migrations/` | | ask | |
| `.env*` | | | never |
| CI/CD configs | | ask | |

Пример Boundaries в таблице — это та самая таблица решений, которая, по данным GitHub-исследования, даёт наибольший вклад в соблюдение границ проекта.

Ограничения

Ограничения

Что учитывать

Размер файла жёстко ограничен — Codex обрезает AGENTS.md больше 32 KiB.

Держите файл компактным, выносите детали в ссылки на внешние документы.

Датированные факты устаревают — формулировки вида «as of March 2025…» заставят агента действовать на старых данных.

Пишите правила без привязки к дате.

Большие архитектурные обзоры не работают — агент должен исследовать код сам, а не читать многостраничное описание.

AGENTS.md — это правила, не документация.

Не кросс-вендорно для Claude Code — Claude Code читает CLAUDE.md, а не AGENTS.md.

Без симлинка контекст не подхватится.

Aider требует ручной настройки — нужно явно добавить read:

AGENTS.md в .aider.conf.yml, нативной поддержки нет.

Антипаттерны

Антипаттерны

Чего не делать

Инструкции для конкретной модели —фразы вида «when using Claude Opus, do X» ограничивают применимость и нарушают кросс-вендорность стандарта.

Секреты и переменные окружения в AGENTS.md —файл коммитится в git, любые токены и ключи утекут в публичный репозиторий.

Датированные факты —привязка к конкретной дате или версии модели быстро устаревает и вводит агента в заблуждение.

Большие архитектурные обзоры —копипаста дизайн-доки в AGENTS.md мешает агенту, он должен исследовать структуру по коду.

Личные предпочтения под видом правил —«я люблю табы» не относится к проекту и засоряет файл.

Конфигурация инструментов в AGENTS.md —для настроек линтера, форматтера и тестов есть конфиг-файлы, дублировать их в AGENTS.md не нужно.

Role-play преамбулы —фразы «You are a senior engineer with 20 years of experience…» не несут практической пользы и тратят токены.

Больше 30 запретов —по данным GitHub-исследования, избыточные don’ts заставляют агента чрезмерно перестраховываться и снижают полноту ответов.

Чеклист

Чеклист

Проверка перед коммитом

AGENTS.md создан в корне репозитория

без него агенту придётся угадывать правила с нуля.

Секции Project overview, Setup, Common commands заполнены

это минимальный набор для продуктивного старта за 60 секунд.

Таблица Boundaries определена

yes edit / ask / never фиксирует, что агент может трогать без спроса, что требует approval и что вообще нельзя.

Setup-команды проверены на чистой машине

иначе AGENTS.md врёт новым участникам и агентам.

Размер файла ≤ 32 KiB

Codex обрезает больше, и важные правила могут потеряться.

SESSION_NOTES.md создан и содержит текущее состояние проекта

следующий заход подхватит контекст.

Симлинк CLAUDE.md создан

если используете Claude Code, без ln -s AGENTS.md CLAUDE.md он не прочитает правила.

AGENTS.md добавлен в git и ревьюится в PR

относитесь к файлу как к коду, а не как к одноразовой заметке.

Ссылки

Ссылки

По теме

По теме