AGENTS.md: как дать ИИ-кодеру понять ваш проект за 10 минут

Если вы хоть раз открывали Cursor или Claude Code и думали «почему оно опять не понимает, что у нас за проект?» — эта статья для вас. Есть простой способ сказать агенту всё, что он должен знать о вашей кодовой базе, ещё до начала работы. Файл называется AGENTS.md, и за последний год он стал стандартом де-факто для индустрии.

Ниже — что это, зачем нужно, как написать без боли и почему вам, скорее всего, пора его завести в своём репозитории. С практическими примерами, таблицей смежных форматов и антипаттернами, на которых обжигаются почти все.

Что это вообще такое

AGENTS.md — обычный Markdown-файл в корне репозитория. Его автоматически читают все основные ИИ-кодеры при старте сессии: Cursor, Claude Code, GitHub Copilot, OpenAI Codex, Windsurf, Aider, Devin, Gemini CLI. Содержимое попадает прямо в контекст модели, сразу под системным промптом — то есть агент видит ваши правила прежде, чем прикоснётся к первому файлу.

Файл придумали в 2024 году как «специализированное дополнение к README.md». README традиционно описывает проект для людей — обзор, как запустить, маркетинговое позиционирование. Пытаться впихнуть туда же «при сборке передавай флаг --no-fallthrough» — значит получить документ, который неудобно читать ни человеку, ни агенту. AGENTS.md — это и есть та самая «инструкция для робота», которая не мешает живым людям.

В августе 2025-го стандарт формализовали консорциумом OpenAI, Google, Cursor, Factory, Anthropic и Sourcegraph. Сейчас его официально поддерживает Agentic AI Foundation под Linux Foundation — наряду с MCP от Anthropic и goose от Block. По состоянию на 2026 год AGENTS.md принят в более чем 60 000 репозиториев — от пет-проектов до крупных корпораций. Это уже не «ещё один формат», это инфраструктурный стандарт.

Что он даёт на практике

Конкретные цифры измерений, которые меня убедили:

• Ошибки в генерируемом коде сокращаются на 35–55%. Не абстрактное «AI стал лучше», а измеримое падение числа дефектов в коммерческих проектах, которые внедрили AGENTS.md.
• Медианное время задачи падает с 98,6 секунды до 70,3. Агент меньше блуждает, меньше задаёт уточняющих вопросов, быстрее выдаёт рабочий код.
• Объём выходных токенов падает на 16,6%. С 2925 до 2440 в среднем на одну задачу. Экономия не только денег, но и контекста.

Важная оговорка: это работает только при ручном составлении. Если попросить LLM сгенерировать AGENTS.md автоматически — получите +23% к расходу токенов и почти ноль прироста к точности. Причина простая: модель переполняет файл абстрактными формулировками вроде «пишите чистый код» и «следуйте best practices». Это не инструкции, это шум.

Шесть блоков, которые нужны

Команда GitHub проанализировала более 2500 репозиториев и выделила 6 функциональных блоков, без которых AGENTS.md работает плохо. Вот они:

1. Обзор проекта (Project Overview)

Одно-два предложения о том, что это за проект. Стек с указанием точных версий. Не «React и TypeScript», а «React 18, TypeScript 5.4, Vite, Tailwind CSS, Node.js v20 LTS». Версия критична: между минорными релизами часто меняются API и поведение.

2. Команды сборки и окружения

Явные исполняемые команды с точными флагами. Не абстрактное «запустите тесты», а pnpm --filter @app/core build и uv run pytest tests/unit/ -v. Агенты отлично копируют команды в терминал, но теряются в нарративных описаниях того, как «у нас принято собирать проект».

3. Стиль кода — только отклонения

Самый коварный блок. Соблазн написать «код должен быть чистым и читаемым» нужно давить. Это не инструкция. Пишите только то, что отличается от дефолтов вашего языка или фреймворка.

Примеры правильных формулировок:

• «Использовать только именованный экспорт. Запрещены default export»
• «Имена файлов в kebab-case, кроме index.ts»
• «Не использовать any в TypeScript без комментария с обоснованием»

4. Структура репозитория

Семантическое назначение директорий, а не абсолютные пути к файлам. /src/services/ — бизнес-логика, /src/api/ — HTTP-обработчики, /tests/integration/ — интеграционные тесты.

Почему не пути к файлам: при рефакторинге файл переедет из /services/payments/process.ts в /services/payments/processor.ts, а AGENTS.md останется прежним. Если там был прописан путь — агент продолжит стучаться по несуществующему адресу.

5. Инструкции по тестированию

Как запускать точечные тесты, какие правила изоляции (mocking), что проверять после рефакторинга. Пример:

• pnpm vitest run -t "<test_name>" — запуск одного теста
• «Не использовать моки для БД в интеграционных тестах»
• «Перед PR: запустить full test suite через pnpm test:ci»

6. Границы и безопасность

Чёткие правила доступа. Что агент делать обязан, что — только после подтверждения, что — вообще нельзя.

Трёхуровневая модель ограничений — золотой стандарт:

Последний пункт особенно важен. Модели — отзывчивые исполнители, и если они видят упавший тест с абсурдным ожиданием, у них есть соблазн «исправить» тест, чтобы он прошёл. Это надо явно запретить.

Бюджет инструкций: главное ограничение

Современные модели с поддержкой рассуждений (reasoning) удерживают устойчиво 150–200 изолированных инструкций. Для моделей попроще — сильно меньше. Содержимое AGENTS.md загружается при каждом обращении, поэтому:

• Чем больше файл, тем меньше внимания модель уделяет каждой отдельной инструкции.
• При переполнении возникает «снежный ком»: добавляется новое правило для починки разовой ошибки, устаревшие правила не удаляются, файл разбухает, качество падает.
• У OpenAI Codex есть жёсткий лимит в 32 КиБ. Превышение → молчаливое обрезание. Файл выглядит огромным, а обрабатывается только его начало.

Решение: Progressive Disclosure (прогрессивное раскрытие)

Архитектурный паттерн, который решает эту проблему:

1. Корневой AGENTS.md содержит только абсолютный минимум, релевантный любой задаче: описание в одно предложение, пакетный менеджер, нестандартные команды проверки.
2. Узкоспециализированная информация выносится в иерархию файлов в docs/ — по доменам (стиль TypeScript, паттерны тестов, конфигурация сборки).
3. Из корневого AGENTS.md ставятся Markdown-ссылки на эти документы.
4. Агент обращается к специализированному руководству только тогда, когда задача действительно про этот модуль.

Это баланс между «ничего не сказать» и «заблудиться в правилах». Звучит сложно, но на практике это просто «вынесите длинные разделы в отдельные файлы и ссылайтесь».

Иерархия в монорепозиториях

В больших проектах AGENTS.md лежит не только в корне — его можно класть в подкаталоги, отдельные пакеты, микросервисы. Главный репозиторий OpenAI Codex использует 88 независимых AGENTS.md, распределённых по дереву.

Разрешение приоритетов работает снизу вверх:

1. Прямые указания пользователя в чате — высший приоритет, отменяют любые файловые правила.
2. Локальный AGENTS.md рядом с файлом — максимальный приоритет для этого файла.
3. Корневой AGENTS.md — базовый контекст, наименьший приоритет при наличии локальных правил.

Если правила в локальном и корневом файлах противоречат друг другу — побеждает локальный. Это правило позволяет разным командам внутри одной кодовой базы иметь свои конвенции без конфликтов с корпоративным стандартом.

Сравнение с похожими форматами

AGENTS.md — не единственный стандарт. Вокруг него выросла целая экосистема. Чтобы не путаться:

Главное отличие AGENTS.md от llms.txt — они работают на разных уровнях. AGENTS.md читает кодирующий агент, чтобы правильно редактировать ваш код. llms.txt читает поисковый ИИ-краулер (вроде того, что индексирует сайты для GPTBot), чтобы понять структуру вашей публичной документации.

Если у вас в команде микс инструментов — есть трюк. Создайте единственный источник правды (AGENTS.md) и символическую ссылку или @import для специализированных инструментов:

• ln -s AGENTS.md CLAUDE.md — для Claude Code
• @AGENTS.md внутри CLAUDE.md — то же самое через include

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

Антипаттерны: как не облажаться

Ошибки, которые совершают почти все при первом подходе:

1. Абстрактные правила

«Пишите читаемый код». «Следуйте принципам SOLID». «Делайте код testable». Это шум. Модель не знает, что с этим делать, и тратит бюджет токенов на размышления о высоких материях вместо работы.

2. Жёстко зашитые пути

Когда тестируешь модуль оплаты, иди в /src/services/payments/v2/stripe/process-payment.ts. После первого же рефакторинга путь изменится, а AGENTS.md останется прежним. Используйте семантическое описание директорий, не конкретные файлы.

3. Дублирование README и package.json

Если список зависимостей лежит и в AGENTS.md, и в package.json — модель получает два источника правды. Если они расходятся — модель путается. Не дублируйте. Ссылайтесь.

4. Попытка покрыть всё сразу

Не надо описывать весь проект в одном файле. Корневой AGENTS.md — это оглавление и абсолютный минимум. Узкие правила — в docs/ или в локальных AGENTS.md.

5. Накопление без ревизии

Каждая новая «особая» ситуация → новое правило. Через полгода файл превращается в кашу. Раз в квартал пересматривайте и удаляйте устаревшее.

Пошаговый рефакторинг для тех, у кого уже бардак

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

1. Выявление противоречий. Попросите агента отсканировать файл и найти конфликтующие инструкции. Каждое противоречие — решение инженера, что важнее.
2. Извлечение минимума. Из всего файла оставляете описание в одно предложение, пакетный менеджер и ключевые команды сборки. Остальное — на удаление или вынос.
3. Группировка по доменам. Из оставшегося формируете группы: правила типизации, паттерны тестов, требования к API, особенности стиля.
4. Создание структуры docs/. Каждая группа становится отдельным файлом в docs/. В корневом AGENTS.md — Markdown-ссылки на них.
5. Беспощадное удаление. Всё, что можно описать одной фразой или вообще опустить — удаляется. Всё, что вы не помните зачем добавляли — удаляется. То, что осталось — компактная и рабочая спецификация.

Что делать прямо сейчас

Если у вас ещё нет AGENTS.md и вы работаете с Cursor, Claude Code или GitHub Copilot — стоит завести. Минимум усилий, заметный эффект:

1. Создайте файл AGENTS.md в корне репозитория.
2. Опишите проект одним абзацем с указанием версий основных технологий.
3. Пропишите команды сборки, тестов и линтера с точными флагами.
4. Опишите семантику основных директорий верхнего уровня.
5. Зафиксируйте 3–5 правил, без которых ваш код улетает в неправильную сторону.
6. Добавьте трёхуровневую модель ограничений по разделу безопасности.

Если у вас AGENTS.md уже есть и разросся — вынесите узкие правила в docs/, почистите абстрактные формулировки, оставьте в корне только базу.

Главный критерий успеха простой: после прочтения вашего AGENTS.md новый агент должен сделать правильный первый шаг без дополнительных вопросов. Если агенту всё ещё нужно объяснять, что у вас за проект — значит, файл работает плохо.

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

AGENTS.md на практике: 3 готовых примера под Node.js, Python и Go

Этот пост — практическое дополнение к прошлой статье про AGENTS.md. Там был стандарт, концепция, антипаттерны. Здесь — конкретные файлы, которые можно скопировать в свой репозиторий и адаптировать за полчаса. Ниже три примера: Node.js TypeScript (фронт/бэк на TS), Python FastAPI (бэкенд на ML/DATA), Go (микросервис). К каждому — короткая инструкция

ПРМПТKami