Как писать AGENTS.md для AI-агентов

Как писать AGENTS.md для AI-агентов

Влад Смирнов

AGENTS.md становится общим файлом инструкций для AI-агентов в репозитории. Его читают Codex, OpenCode, Hermes, OpenClaw, многие IDE-агенты и сервисы вокруг них. Claude Code использует свой CLAUDE.md, но по сути это тоже самое.

Хороший AGENTS.md похож на рабочий контракт для нового разработчика: где что лежит, какие команды запускать, какие правила нельзя нарушать, как понять, что задача закончена. Это обычный Markdown без обязательной схемы. Сила файла в конкретике, коротком размере и регулярном обновлении.

Что показал поиск

Официальный сайт AGENTS.md описывает формат как README для агентов и отмечает, что он уже используется десятками тысяч открытых проектов. В документации OpenAI Codex AGENTS.md называется долговременным проектным контекстом: Codex читает его перед работой, поддерживает глобальные и вложенные файлы, а команда /init может помочь сгенерировать инструкции. OpenCode тоже предлагает /init и рекомендует коммитить проектный AGENTS.md в Git.

Claude Code прямо пишет: он читает CLAUDE.md, а не AGENTS.md. Практический способ совместимости - создать CLAUDE.md с импортом:

@AGENTS.md

Hermes читает AGENTS.md как один из проектных context files и умеет подхватывать вложенные AGENTS.md при работе с поддиректориями. OpenClaw ожидает AGENTS.md в workspace вместе с SOUL.md, USER.md и другими файлами, поэтому для него важно отделять проектные правила от личности и памяти ассистента.

Одни советуют копировать короткие готовые файлы вроде настроек Karpathy и дорабатывать под себя. Другие жалуются, что агенты всё равно пропускают правила, а слишком большой CLAUDE.md или AGENTS.md может ухудшать результат. Это нормально: AGENTS.md не заменяет тесты, линтеры, ревью и его понимание зависит от мощности модели.

Главный принцип

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

  • где искать код;
  • какую команду запустить;
  • какой стиль считается правильным;
  • чего нельзя трогать;
  • как проверить результат;
  • когда нужно спросить человека.

Если правило нельзя проверить, его стоит переписать. Формулировка «пиши хороший код» бесполезна. Формулировка «после изменения backend запусти pytest tests/api -q» работает.

Где хранить файл

Для большинства репозиториев достаточно одного AGENTS.md в корне. В монорепозиториях лучше добавить вложенные файлы рядом с пакетами:

repo/
  AGENTS.md
  apps/web/AGENTS.md
  services/api/AGENTS.md
  packages/ui/AGENTS.md

Правила в ближайшей директории обычно важнее общих правил. Это удобно: корневой файл описывает репозиторий, а вложенный файл описывает конкретный сервис, пакет или стек.

Для личных предпочтений используйте глобальные файлы инструмента, а не проектный AGENTS.md. Например, Codex читает ~/.codex/AGENTS.md, OpenCode - ~/.config/opencode/AGENTS.md, Claude Code - ~/.claude/CLAUDE.md. В репозиторий кладите только то, что полезно всей команде.

Оптимальный размер

Держите корневой файл коротким. Хороший ориентир - 80-200 строк. Если файл растет, вынесите детали в:

  • вложенные AGENTS.md;
  • документацию в docs/;
  • skills или playbooks агента;
  • конфиги линтеров, форматтеров, typecheck и CI.

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

Структура, которая работает

Минимальный универсальный порядок разделов:

  1. Project overview - что это за проект и какие технологии используются.
  2. Repository map - где лежат основные части.
  3. Commands - установка, запуск, тесты, линтинг, сборка.
  4. Coding conventions - стиль, типизация, архитектурные правила.
  5. Testing policy - какие тесты нужны и какие команды считать обязательными.
  6. Safety and boundaries - секреты, миграции, продакшен, внешние API.
  7. PR or completion checklist - что агент должен сделать перед финальным ответом.
  8. Agent-specific notes - короткие исключения для Claude, Codex, Hermes, OpenCode, OpenClaw.

Секции можно назвать по-русски или по-английски. Важнее, чтобы они были короткими и стабильными.

Шаблон AGENTS.md

Скопируйте и заполните только актуальные пункты:

# AGENTS.md

## Project overview

- Product: <one sentence about the project>
- Stack: <frameworks, language versions, database, queue, hosting>
- Package manager: <npm, pnpm, uv, poetry, cargo, go, etc.>

## Repository map

- `apps/web/` - frontend application
- `services/api/` - backend API
- `packages/ui/` - shared UI components
- `docs/` - architecture notes and decisions
- `.github/workflows/` - CI definitions

## Setup

- Install dependencies: `<command>`
- Start local dev: `<command>`
- Copy env template: `<command>`
- Required services: <PostgreSQL, Redis, Docker Compose, etc.>

## Commands

- Lint: `<command>`
- Typecheck: `<command>`
- Unit tests: `<command>`
- Integration tests: `<command>`
- Build: `<command>`

If a command is slow, first run the focused command for changed files, then run the full command before finishing.

## Coding conventions

- Use <style rule that can be checked>.
- Keep public APIs typed.
- Prefer existing helpers in `<path>` before adding new abstractions.
- Put tests next to the code or in `<tests path>`.

## Testing policy

- Add or update tests for behavior changes.
- For bug fixes, add a regression test that fails before the fix.
- If tests cannot run locally, explain why and list the command that should be run.

## Safety and boundaries

- Do not commit secrets, tokens, `.env` files, or real credentials.
- Do not rewrite migrations manually. Use `<migration command>`.
- Do not change public API contracts without updating `<schema/docs path>`.
- Ask before adding production dependencies or changing deployment config.

## Done checklist

Before final response:

- Run the relevant lint, test, typecheck, or build command.
- Summarize changed files and behavior.
- Mention any skipped checks with the exact reason.
- Leave the working tree clean unless the task asks for uncommitted changes.

## Agent-specific notes

- Claude Code: keep `CLAUDE.md` as `@AGENTS.md` plus Claude-only notes.
- Codex: run `/init` when bootstrapping and keep nested AGENTS.md near specialized code.
- Hermes: prefer AGENTS.md for project rules; use `.hermes.md` only for Hermes-specific overrides.
- OpenCode: use `/init` to create or improve this file; use `opencode.json` for extra instruction files.
- OpenClaw: keep persona and memory in SOUL.md, USER.md, MEMORY.md; keep AGENTS.md focused on operating rules.

Как писать команды

Команды должны быть точными. Плохо:

- Run tests before submitting.

Хорошо:

- For backend changes: `uv run pytest tests/api -q`.
- For frontend changes: `pnpm --filter web test`.
- Before PR: `pnpm lint && pnpm typecheck && pnpm test`.

Добавьте контекст, когда команда зависит от окружения:

- Integration tests require Docker: `docker compose up -d postgres redis`.
- E2E tests require the dev server on port 3000: `pnpm dev`.

Как писать архитектурные правила

Агенту нужен маршрут по коду. Давайте карту и ограничения:

## Architecture

- API handlers live in `services/api/src/routes/`.
- Database models live in `services/api/src/db/models/`.
- Do not import from `services/api/src/internal/` in frontend code.
- Shared validation schemas live in `packages/contracts/` and are the source of truth for API types.

Такие правила уменьшают случайное чтение файлов и лишние изменения.

Как описывать запреты

Запреты должны быть связаны с риском:

## Safety

- Never print secrets from `.env`, CI variables, or production logs.
- Never run `terraform apply`, `kubectl apply`, or deployment commands unless the user explicitly asks.
- Never edit generated files in `src/generated/`; update the source schema and regenerate.

Если запрет критичен, закрепите его технически: pre-commit hook, CI, policy-файл, sandbox, permissions. Текст в AGENTS.md помогает агенту, но не является системой безопасности.

Совместимость с разными агентами

Для универсального проекта удобно держать один источник правды:

AGENTS.md      shared rules for all agents
CLAUDE.md      imports AGENTS.md and adds Claude-specific notes
.hermes.md     optional Hermes-only override, only when really needed
opencode.json  optional list of extra instruction files

Пример CLAUDE.md:

@AGENTS.md

## Claude Code

- Use plan mode for large refactors.
- When working under `infra/`, show the plan before editing files.

Для OpenCode можно подключить дополнительные файлы через opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["docs/development.md", ".cursor/rules/*.md"]
}

Для Hermes лучше начать с AGENTS.md. .hermes.md имеет более высокий приоритет, поэтому используйте его только для правил, которые должны отличаться от общих.

Для OpenClaw учитывайте workspace-модель. Там AGENTS.md может описывать поведение ассистента в канале, память и безопасные границы. Если тот же файл лежит в кодовом репозитории, оставляйте в нем проектные правила, а личность и приватную память храните отдельно.

Когда обновлять AGENTS.md

Обновляйте файл после повторяющихся ошибок:

  • агент дважды выбрал неправильный пакетный менеджер;
  • ревью снова просит один и тот же стиль;
  • агент ищет код не в тех директориях;
  • тесты требуют скрытого шага настройки;
  • изменился контракт API или структура проекта.

Хорошая практика - просить агента предложить патч к AGENTS.md после исправления ошибки. Затем человек быстро ревьюит diff. Так файл остается живым и не превращается в архив старых запретов.

Чего избегать

  • Длинных философских правил.
  • Повторения README, если README уже хорошо объясняет установку.
  • Списков на сотни строк в корневом файле.
  • Секретов, внутренних URL с токенами, личных учетных данных.
  • Конфликтующих правил в корне и поддиректориях.
  • Инструкций без проверки: «будь аккуратен», «пиши красиво», «думай глубже».

Заменяйте абстракции проверяемыми правилами:

Bad: Be careful with database changes.
Good: For schema changes, create a migration with `alembic revision --autogenerate`, run `alembic upgrade head`, then run `pytest tests/db -q`.

Быстрый аудит существующего файла

Проверьте AGENTS.md по семи вопросам:

  1. Есть ли точные команды установки, запуска и проверки?
  2. Понятно ли, где искать frontend, backend, shared packages, инфраструктуру?
  3. Есть ли правила для тестов после изменения поведения?
  4. Есть ли явные запреты для секретов, миграций, deploy и generated files?
  5. Есть ли критерий завершения задачи?
  6. Можно ли удалить 20 процентов текста без потери смысла?
  7. Нет ли противоречий с README, CONTRIBUTING, CI и вложенными AGENTS.md?

Если ответ «нет» на первые пять вопросов, файл пока слабый. Если ответ «нет» на шестой, файл слишком раздут.

Вывод

AGENTS.md работает лучше всего как короткая карта проекта и набор проверяемых правил. В нем должны быть команды, пути, инварианты и критерии завершения. Все, что относится к личности ассистента, долговременной памяти, приватным предпочтениям или редким процедурам, лучше хранить в механизмах конкретного агента: CLAUDE.md, SOUL.md, skills, rules, hooks, opencode.json или глобальных инструкциях.


Сообщество энтузиастов - https://t.me/agents_lab

Report content on this page

Report Page

Please submit your DMCA takedown request to dmca@telegram.org