AGENTS.md — открытый формат для управления поведением кодящих агентов

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

Формат поддерживается более чем 60 000 проектами на GitHub и стюардится Agentic AI Foundation при Linux Foundation. Среди участников — OpenAI Codex, Jules от Google, Cursor, Amp, Factory и другие.

Зачем нужен отдельный файл

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

Авторы намеренно разделили два формата:

• Дают агентам понятное и предсказуемое место для инструкций.
• Сохраняют README компактным и сфокусированным на человеческом контрибьюторе.
• Предоставляют точные инструкции для агентов, дополняя существующую документацию.

Структура файла

AGENTS.md — это обычный Markdown без обязательных полей. Агент просто парсит текст и следует инструкциям. Типичные секции:

# AGENTS.md

## Dev environment tips
- Use `pnpm install` to install dependencies.
- Run `pnpm dev` to start the development server.

## Testing instructions
- Run `pnpm test` to execute the test suite.
- All tests must pass before merging.

## Code style
- TypeScript strict mode.
- Single quotes, no semicolons.
- Use functional patterns where possible.

## PR instructions
- Title format: [project] Description
- Always run `pnpm lint` and `pnpm test` before committing.

Поддержка агентами

Один файл AGENTS.md работает со множеством агентов и инструментов:

• Codex (OpenAI), Jules (Google), Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin (Cognition), Junie (JetBrains)
• Amp, Cursor, RooCode, Gemini CLI (Google), Kilo Code, Phoenix, Semgrep, Coding Agent (GitHub Copilot)
• Ona, Windsurf (Cognition), Augment Code

Агент автоматически находит файл в корне репозитория и использует его как контекст при работе с кодом.

Монорепозитории и вложенность

Для крупных монорепозиториев можно размещать вложенные AGENTS.md в подкаталогах. Агент автоматически читает ближайший файл в дереве каталогов — самый близкий к редактируемому файлу имеет приоритет. Например, в репозитории OpenAI на момент написания 88 файлов AGENTS.md.

project/
├── AGENTS.md              # общие инструкции
├── packages/
│   ├── core/
│   │   └── AGENTS.md      # инструкции для core
│   └── api/
│       └── AGENTS.md      # инструкции для api

Рекомендации по содержимому

Авторы рекомендуют включать:

1. Обзор проекта — что делает проект, основные компоненты.
2. Команды сборки и тестов — как запускать, что проверять.
3. Стиль кодирования — стандарты, паттерны, соглашения.
4. Инструкции по тестированию — как тестировать, что покрывать.
5. Соображения безопасности — что проверять перед мержем.

Миграция и конфигурация

Если у вас уже есть файлы вроде AGENT.md, CLAUDE.md или .cursorrules, можно просто переименовать их в AGENTS.md. Для обратной совместимости создайте симлинк:

mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

Конфигурация для конкретных агентов:

Aider (.aider.conf.yml):

read: AGENTS.md

Gemini CLI (.gemini/settings.json):

{
  "context": {
    "fileName": "AGENTS.md"
  }
}

Часто задаваемые вопросы

• Обязательные поля? Нет — просто Markdown с любыми заголовками.
• Конфликт инструкций? Ближайший к редактируемому файлу побеждает, промпт пользователя перекрывает всё.
• Агент автоматически запускает тесты? Да, если они перечислены в файле.
• Можно ли обновлять? Конечно — это living documentation.

Технический чартер

Проект включает Technical Charter, описывающий процесс эволюции формата и управление проектом через Agentic AI Foundation.

Заключение

AGENTS.md решает простую, но важную задачу: даёт разработчикам единый способ общаться с AI-агентами через понятный Markdown-файл. Формат не требует специальных инструментов, работает со всеми основными агентами и постепенно становится стандартом de facto для взаимодействия людей и кодящих агентов.