Как написать файл AGENTS.md, чтобы любой ИИ-агент для кодинга понимал ваш проект

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

Что такое AGENTS.md на самом деле

AGENTS.md — это «README для агентов»: обычный Markdown-файл, который вы кладёте в корень репозитория, чтобы рассказать ИИ-инструментам для кодинга, как устроен ваш проект (agents.md). Это не новый язык конфигурации — здесь нет обязательных полей и нет специального синтаксиса. Используйте любые Markdown-заголовки, какие захотите.

Формат важен потому, что он по-настоящему кросс-инструментальный. По состоянию на середину 2026 года его нативно читают OpenAI Codex, GitHub Copilot, Cursor, Windsurf, Devin, Aider, Zed, VS Code, JetBrains Junie и десятки других — 28+ инструментов и 60 000+ репозиториев с открытым исходным кодом (agents.md; Codersera). Теперь его курирует Agentic AI Foundation при Linux Foundation — наряду с Model Context Protocol от Anthropic. Claude Code тоже читает AGENTS.md, хотя его более богатый нативный формат по-прежнему CLAUDE.md (DeployHQ).

Один файл — и большинство ваших инструментов ведут себя согласованно.

Почему файл лучше, чем повторяться в чате

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

Что в него положить

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

• Обзор проекта — один абзац о том, что это такое и какой у вас стек технологий.
• Команды установки и сборки — точные команды для установки, запуска и сборки.
• Тестирование — как запускать тесты и правило, что тесты должны проходить, прежде чем изменение считается готовым.
• Стиль кода — форматтер, линтер, соглашения об именовании, предпочтительные или нежелательные паттерны.
• Правила коммитов и PR — формат сообщений, правила ветвления, что нельзя трогать.
• Подводные камни — всё неочевидное, на чём люди спотыкаются.

Будьте конкретны. «Пишите чистый код» не говорит агенту ничего. «Используйте pnpm, а не npm; запускайте pnpm test перед завершением; никогда не редактируйте файлы в src/generated/» — это можно проконтролировать.

Конкретный пример

Вот компактный AGENTS.md для типичного веб-приложения:

# AGENTS.md

## Project
Next.js 15 + TypeScript storefront. Package manager is pnpm.

## Setup & commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Build: `pnpm build`

## Testing
- Run all tests: `pnpm test`
- All tests must pass before a task is considered done.

## Code style
- TypeScript strict mode; no `any`.
- Format with Prettier (`pnpm format`) — do not hand-format.
- Prefer named exports. Reuse helpers in `src/lib/` before writing new ones.

## Do not touch
- `src/generated/**` is auto-generated. Never edit by hand.
- Never commit `.env` files.

Передайте это Claude Code, Cursor или Copilot — и каждый из них подхватит одни и те же правила.

Монорепозитории: используйте вложенные файлы

В монорепозитории вы можете разместить AGENTS.md в каждом пакете, а также один в корне. Когда агент работает внутри подкаталога, побеждает ближайший файл (agents.md). Держите общие соглашения в корне, а специфичные для пакета команды — во вложенных файлах, чтобы агент, редактирующий packages/api/, автоматически получал команды сборки и тестирования именно этого пакета.

AGENTS.md против CLAUDE.md против правил Cursor

У вас уже могут быть специфичные для инструментов файлы, например CLAUDE.md или .cursor/rules. Их не нужно выбрасывать. На практике команды кладут общие, независимые от инструмента соглашения в AGENTS.md — то, что нужно каждому агенту, — а специфичные для инструмента дополнения оставляют в нативном файле того инструмента, который поддерживает более богатые возможности (DeployHQ). Claude Code, например, читает оба, причём CLAUDE.md — его более выразительный формат. Распространённый подход — держать один канонический AGENTS.md и, где инструменту нужен собственный файл, указывать в этом файле на AGENTS.md, чтобы был единый источник правды. Начинайте с AGENTS.md; тянитесь к специфичному для инструмента файлу только тогда, когда вам нужна функция, которую поддерживает лишь он.

Держите его коротким и конкретным

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

Как поддерживать его полезным

AGENTS.md окупается только если остаётся правдивым. Относитесь к нему как к коду: когда меняется команда или соглашение, обновляйте файл в том же коммите. А когда агент дважды совершает одну и ту же ошибку, не просто исправляйте её в чате — запишите правило. Одна эта привычка превращает каждую оплошность в постоянное исправление, и это самое результативное, что вы можете сделать, чтобы ИИ-агенты были надёжными в вашем проекте.