Вы подключаете AI-агента к проекту, просите добавить эндпоинт — а он пишет код в чужом стиле, запускает не те тесты и тащит зависимость, которую вы давно выпилили. Агент не виноват. Он просто не знает правил, которые у команды держатся в голове.
Человек на онбординге задаёт вопросы. Агент не спрашивает — он угадывает. И чем больше угадывает, тем больше времени вы тратите на правки вместо результата.
AGENTS.md решает это в лоб: один файл в корне репозитория, где написано, как собирать проект, чем его тестировать, какого стиля держаться и куда лучше не лезть. Дальше — что это за формат, кто его читает и что в него класть.
Что такое AGENTS.md и зачем он нужен
AGENTS.md — это README для агентов. README объясняет проект людям: что это, как запустить, куда писать. AGENTS.md делает то же самое для AI-кодинг-агентов, но на языке команд и конвенций, а не презентации.
Это открытый формат, а не чья-то проприетарная фича. Им занимается Agentic AI Foundation под крылом Linux Foundation, а вырос он из общих усилий команд OpenAI Codex, Amp, Jules (Google), Cursor и Factory. По данным agents.md, файл уже лежит больше чем в 60 000 open-source проектов.
Технически это обычный Markdown-файл. Никакого нового синтаксиса учить не нужно — пишете так же, как написали бы заметку для нового коллеги.
Какие инструменты читают AGENTS.md
Главная ценность формата в том, что его понимает не один инструмент, а целая россыпь. Один файл — и большинство популярных агентов читают его без настройки.
- Codex (OpenAI), Jules (Google), Gemini CLI (Google)
- Cursor, Windsurf, Zed, VS Code, Warp
- Aider, goose, opencode, Amp, Factory
- GitHub Copilot coding agent, Devin (Cognition), Junie (JetBrains)
- RooCode, Kilo Code, Augment Code, Ona, Phoenix, Semgrep, UiPath Autopilot
Claude Code от Anthropic в этот список не входит. По умолчанию он читает свой файл — CLAUDE.md, а не AGENTS.md. Если в команде используют оба инструмента, держите оба файла рядом.
Некоторым инструментам можно указать файл явно. Aider: в .aider.conf.yml добавьте строку read: AGENTS.md. Gemini CLI: в .gemini/settings.json пропишите {"context": {"fileName": "AGENTS.md"}}.
Чем AGENTS.md отличается от CLAUDE.md и Cursor Rules
AGENTS.md, CLAUDE.md и правила Cursor решают одну задачу — объяснить агенту контекст проекта. Но читают их разные инструменты и в разных форматах.
| Файл | Кто читает | Формат |
|---|---|---|
| AGENTS.md | Кросс-инструментальный: Codex, Cursor, Jules, Aider, Gemini CLI, Copilot и др. | Обычный Markdown, открытый стандарт |
| CLAUDE.md | Claude Code (Anthropic) | Markdown, свой файл памяти |
| .cursor/rules | Cursor (правила проекта) | Проприетарный формат Cursor |
Если работаете в основном через Claude Code, начните с CLAUDE.md — у нас есть отдельный разбор, как написать CLAUDE.md. Файлы не конфликтуют: можно держать оба и закрыть всю команду инструментов сразу.
Что писать в AGENTS.md
Обязательной схемы нет. Это обычный Markdown — заголовки выбираете сами. Ориентир простой: напишите то, что рассказали бы новому разработчику в первый день. Рекомендуемый набор — обзор проекта, команды сборки и тестов, стиль кода, инструкции по тестированию и заметка про безопасность: опасные зоны, секреты, чего агенту лучше не касаться.
Обзор проекта
Пара абзацев о том, что это за продукт, на чём написан и как устроен. Агенту это нужно, чтобы не предлагать решения из чужого стека.
Команды сборки и тестов
Самая полезная секция. Перечислите точные команды: как поставить зависимости, как собрать проект, как прогнать тесты и линтер. Не «запустите тесты», а конкретная строка, которую можно скопировать.
Если вы перечислили тестовые команды, агент попытается выполнить их сам и починить падения, прежде чем отдать вам результат. Один абзац с командами экономит десятки итераций правок.
Стиль кода
Форматирование, именование, какие паттерны приняты, а какие под запретом. Сюда же — какие библиотеки использовать, а какие не тащить в проект.
Коммиты и пул-реквесты
Формат сообщений коммитов, требования к PR, что прогнать перед отправкой. В сэмпле AGENTS.md, например, задают формат заголовка пул-реквеста: [<project_name>] <Title>.
Структура проекта
Короткая карта репозитория: где лежит код, где конфиги, где тесты. Помогает агенту не создавать файлы в случайных местах.
Если у вас уже лежит старый AGENT.md (без s), переименуйте его и оставьте симлинк для совместимости: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.
Как использовать AGENTS.md в монорепозитории
В монорепозитории один файл на всё не работает: у каждого пакета свои команды и правила. Решение — класть отдельный AGENTS.md в каждый пакет. Агент читает тот, что ближе всего к файлу, который правит.
Это же правило снимает конфликты. Если инструкции в двух файлах расходятся, побеждает ближайший к коду. А прямой запрос в чате важнее любого файла: попросили агента сделать иначе — он слушает вас, а не Markdown.
Масштаб бывает серьёзным: в основном репозитории OpenAI лежит 88 файлов AGENTS.md.
Частые ошибки
- Описывать проект общими словами вместо точных команд. «Запустите тесты» бесполезно — нужна конкретная строка.
- Забывать про команды тестов и линтера. Без них агент не сможет сам проверить свою работу.
- Ждать, что Claude Code прочитает
AGENTS.md. Ему нуженCLAUDE.md— держите оба файла. - В монорепо обходиться одним файлом в корне. Пакетам нужны свои
AGENTS.md. - Раздувать файл до простыни. Пишите как для коллеги: коротко, по делу, без копий документации.
- Завести файл и забыть. Стек и команды меняются — устаревший
AGENTS.mdвредит больше, чем его отсутствие.
Больше об AI в разработке
Разбираю инструменты, агентов и рабочие приёмы без хайпа: что реально экономит время, а что просто маркетинг.
Подписаться
