Перейти к содержимому
Экосистема AI Vibe
← Назад к AI Vibe News

Редакция 6 августа 2026 г.

Разборы

README — для людей. AGENTS.md — для coding agents

README — для людей. AGENTS.md — для coding agents

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

Когда README перестаёт спасать агента

Агенты для кода уже не ограничиваются автодополнением: они смотрят структуру репозитория, правят несколько файлов, вызывают shell, запускают тесты и открывают pull request. Инструкции репозитория становятся частью окружения разработки — но README заточен под другую аудиторию.

README объясняет проект людям: зачем он существует, как установить, короткий сценарий использования, ссылки на документацию, правила контрибуции. Агенту оттуда не хватает проверяемых инструкций: какая команда для точечного теста, где сгенерированный код, какие архитектурные границы нельзя ломать, что считать «готовой» задачей. Ключевое разделение: README объясняет проект; AGENTS.md — как безопасно менять проект.

Копировать весь README в AGENTS.md — типичная ошибка: два документа начинают расходиться, и агент получает шум вместо рабочего контракта.

Что положить в первую версию AGENTS.md

Формат — обычный Markdown без обязательной схемы и «специального языка конфигурации». Один файл в корне репозитория; в монорепо допустимы вложенные AGENTS.md в подкаталогах — когда у web и API «разные миры», но не файл в каждой папке.

Для старта автор предлагает четыре блока (на примере TypeScript-сервиса):

Секция Зачем агенту
Repository map Где handlers, domain, data, generated-код, test helpers
Setup and validation Установка (pnpm install --frozen-lockfile), точечный и полный тест, typecheck, lint
Coding rules Тонкие HTTP handlers, переиспользование validation library и error format, запрет prod-зависимостей без approval, тесты на изменённое поведение
Before finishing Review diff, focused tests, typecheck/lint, отчёт о незавершённых проверках

Расширенный starter template добавляет: Project overview, Commands, Coding conventions, Restricted areas, Definition of done, Additional documentation (ссылки на architecture / contributing / security).

Команды в AGENTS.md должны быть рабочими, с явной директорией запуска — чаще корень репо. Не копируйте все скрипты из package.json: агенту нужны те, что реально гоняют при проверке задачи. Для интеграционных тестов укажите зависимость от сервиса — например PostgreSQL из compose.yaml и разницу .env.test vs .env.production.

Минимальный каркас из поста:

# AGENTS.md

## Repository map
- HTTP handlers: `src/handlers`
- Domain logic: `src/domain`
- Generated client: `src/generated` — do not edit

## Setup and validation
- Install: `pnpm install --frozen-lockfile` (repo root)
- Focused tests: `pnpm test -- path/to/changed.spec.ts`
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint`

## Coding rules
- Reuse existing validation library and error format
- Do not add production dependencies without approval
- Add tests for changed behavior

## Before finishing
- Review diff, run focused tests and typecheck/lint
- Report any checks you could not run

Хорошая инструкция отвечает хотя бы на один из трёх вопросов: Action (что сделать), Scope (где и в каких пределах), Evidence (как проверить). «Write clean code» не проходит; «Run pnpm typecheck» и «Do not modify src/generated» — проходит.

Границы автономии: restricted areas и definition of done

Слой правил для агента бессмысленен без жёстких запретов. Типичные restricted areas:

  • не редактировать generated files (src/generated);
  • не менять уже выпущенные миграции БД;
  • не читать .env* кроме .env.example;
  • не менять CI workflows без явной задачи;
  • не запускать deploy, publish и команды разрушения инфраструктуры;
  • спрашивать перед добавлением или апгрейдом production dependencies;
  • соблюдать архитектурные границы слоёв (API → application → data): handlers не ходят в repositories напрямую.

Отдельно выделяют security-sensitive changes и actions requiring approval: auth, schema, network, CI/deploy, persistent data.

Definition of done — нумерованный чеклист: review diff → тесты → минимальный релевантный test suite → typecheck/lint → build при изменении публичных интерфейсов → отчёт, какие команды выполнены и что не удалось проверить.

В монорепо вложенные AGENTS.md могут описывать локальные рабочие сценарии для apps/web, apps/api, packages/design-system — без дублирования всего корневого файла.

Кто уже читает AGENTS.md в экосистеме агентов

Открытый формат AGENTS.md позиционируется как «README for agents» — machine-oriented контракт репозитория, который дополняет человекочитаемую документацию.

В теле поста явно названы:

  • GitHub Copilot coding agent — поддержка AGENTS.md, в том числе nested; автор указывает август 2025 г.;
  • OpenAI Codex — иерархия project instructions от корня репозитория к текущей рабочей директории.

Как industry context упоминается GitHub Octoverse 2025: генеративный ИИ как стандартная часть разработки, рост AI-related репозиториев и agent-assisted workflows — без конкретных цифр в процитированном фрагменте.

Прямого сравнения с .cursor/rules, CLAUDE.md или Cursor в посте нет: это другой носитель того же смысла — guardrails и контекст для агента в репозитории, а не замена IDE-конфигов.

Семь ошибок и чеклист «прогони реальный таск»

Типичные промахи при написании AGENTS.md:

  1. Копирование всего README.
  2. «Эссе» вместо команд в начале файла.
  3. Размытые правила без проверки.
  4. Команды, которые никто не запускает на практике.
  5. Смешение предпочтений и жёстких требований.
  6. Иллюзия, что инструкции заменяют permissions.
  7. Отсутствие обновления при смене CI или структуры репо.

Перед тем как считать файл готовым, автор советует дать агенту реальную задачу и проверить семь пунктов: правильный package manager, точечный тест, соблюдение границ, уважение к generated files, approval перед dependency, честный отчёт о проваленных или недоступных проверках.

И ещё одна граница, которую легко забыть: instruction file — guidance, не security boundary. Нужны access controls, branch protection и secret management; AGENTS.md не закрывает дыру в правах доступа.

Источники