AGENTS.md: пример и шаблон файла для AI-агентов

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

Формат: просто Markdown, без схемы

Главное, что снимает страх перед файлом: «AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide» — обычный Markdown без обязательных полей и структуры. Никакого YAML-фронтматтера, никакой валидации: заголовки любые, порядок любой. Агент читает текст как есть. Это конвенция, а не формат со спецификацией — её уже поддерживают более шестидесяти тысяч проектов и десятки инструментов (Codex, Cursor, Jules, Aider, Zed, GitHub Copilot и другие).

Какие секции держать

Схемы нет, но за практикой закрепился набор секций, которые агенту реально нужны:

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

Готовый шаблон

Скопируйте в AGENTS.md в корне репозитория и подставьте своё:

# AGENTS.md

## Обзор проекта

Next.js-приложение (App Router, TypeScript). Веб-часть в `src/`,
контент — в `src/content/`. База данных — Postgres через Prisma.

## Команды

- Установка: `pnpm install`
- Дев-сервер: `pnpm dev`
- Тесты: `pnpm test`
- Линт и типы: `pnpm lint`

## Стиль кода

- TypeScript strict, без `any`.
- Компоненты функциональные; общие — в `src/components/`.
- Импорты идут по слоям, снизу вверх — не наоборот.

## Тесты

- Каждая фича сопровождается тестом, который доказанно умеет падать.
- Перед коммитом зелёные `pnpm test` и `pnpm lint`.

## Безопасность

- Ввод в server actions и роутах валидируется через zod до использования.
- Секреты — только через переменные окружения, не в коде.

## Коммиты

- Conventional Commits: `feat(scope): ...`, `fix(scope): ...`.

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

- Не ходить в сеть/БД во внешнем middleware.
- Не использовать прямую навигацию по `href` там, где есть роутер-компонент.

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

Вложенные файлы в монорепо

Для монорепозитория один корневой файл не обязателен: «Agents automatically read the nearest file in the directory tree, so the closest one takes precedence» — агент берёт ближайший AGENTS.md вверх по дереву. Кладёте общий файл в корень, а в packages/api/ или apps/web/ — свой, с локальными командами и правилами; для этого пакета он перекрывает корневой.

Связь с CLAUDE.md и правилами инструментов

Исторически инструменты завели свои файлы: Claude Code читает CLAUDE.md, Cursor — .cursor/rules, и так далее. Чтобы не поддерживать пять копий одного и того же, распространённый приём — держать один источник (AGENTS.md), а остальные файлы сделать симлинком или копией на него. Тогда правила живут в одном месте, а каждый инструмент видит их под своим именем — один AGENTS.md, а CLAUDE.md или .cursor/rules указывают на него.

Соседний по смыслу файл — constitution.md из GitHub Spec Kit: он тоже фиксирует неизменные принципы проекта, только уже внутри конкретного spec-driven-процесса.

Частые ошибки

• Дублировать README. AGENTS.md — не витрина проекта, а инструкции: команды, соглашения, запреты.
• Писать «роман». Чем длиннее файл, тем хуже агент удерживает его целиком; оставляйте то, что меняет поведение.
• Забывать актуализировать. Поменяли команду или правило — поправьте файл в том же коммите, иначе агент уверенно сделает по-старому.
• Расплывчатые формулировки. «Пишите чисто» агенту ничего не говорит; «функция не длиннее экрана, без any» — говорит.

В своей разработке мы держим такой файл в каждом проекте и настраиваем под него AI-агентов. Если хотите так же, но не знаете, с чего начать — расскажите о проекте, поможем составить.