AGENTS.md и ADR: контракт агента на каждую сессию
Фаза 1 серии Harness Engineering — контекст-инжиниринг. Глубокий разбор четырёх файлов-источников правды, которые агент читает на старте: AGENTS.md (working rules + Definition of Done + retrieve-правило), аддендум под конкретного агента (CLAUDE.md / .cursorrules / system prompt), architecture.md (карта слоёв и границ) и каталог ADR (одно решение = один markdown). Минимальные шаблоны и готовые копируемые промпты для бутстрапа — стек-агностично, для любого языка и любого агента.
СреднийDevOps с AI25 минAGENTS.md, CLAUDE.md, ADR, Claude Code
1
Контекст-файл — это контракт сессии, а не README
Если агент пишет код, единственный источник правды для него — то, что лежит в репозитории. Чат, тикет, облачная дока — этого агент в начале новой сессии не видит. Repo-first: любое решение, которое должно влиять на работу агента, оформляется как файл в репо.
Фаза 1 даёт агенту контракт, который он читает на старте каждой сессии. Это не один большой файл — это четыре роли, по принципу «один artefact — одна цель»: контракт работы (AGENTS.md), аддендум под конкретного агента (CLAUDE.md / .cursorrules / system prompt), карта архитектуры (architecture.md) и каталог решений (ADR). Контракт короткий и ссылается на источники правды, а не дублирует их содержимое. Обзор всей среды — в хабе серии; здесь мы идём вглубь именно этой фазы.
AGENTS.md — контракт для любого агента
Working rules, Definition of Done, retrieve-правило, команды проверки
Аддендум под агента (CLAUDE.md / .cursorrules)
Специфика инструмента: skills, режимы, MCP — поверх общего контракта
architecture.md — карта слоёв и границ
Домены, слои, направления зависимостей, что НЕ в этом репо
docs/decisions/ — каталог ADR
Одно решение = один markdown: почему так, а не иначе
Машина важнее текста, но текст важнее ничего. Фаза 1 — это ещё текст (конвенции, не барьеры), но без неё агент додумывает архитектуру с нуля каждую сессию. Барьеры из фазы 3 опираются именно на эту карту.
2
AGENTS.md: working rules + Definition of Done + retrieve-правило
AGENTS.md — общий контракт для любого кодинг-агента (Claude Code, Codex, Cursor, любой будущий). Держите его коротким (≤100 строк): это карта, а не энциклопедия. Структура: что за проект в одном абзаце; стек одним списком; где лежит правда (ссылки на architecture.md, decisions/, шаблон ExecPlan, аудит среды); working rules; команды проверки; явные запреты.
Два раздела несут основную нагрузку. Definition of Done — один чек-лист «что значит готово»: что должно быть зелёным (форматтер, линтер, тайп-чек, тесты, билд), обновлена ли затронутая документация, есть ли ADR на новое решение. И retrieve-правило: перед задачей на конкретной границе агент обязан сначала прочитать накопленные по ней уроки и связанные ADR — это шов, в который позже встроится lessons-ledger. Конкретные команды берите из манифеста проекта (package.json, pyproject.toml, build.gradle, Cargo.toml — что применимо), не выдумывайте.
Минимум для AGENTS.md
Проект в одном абзаце + стек одним списком
Ссылки на источники правды (architecture.md, decisions/, ExecPlan)
Working rules: один тред = одна задача, атомарные коммиты, обновляй доки при смене поведения
Definition of Done: что должно быть зелёным + ADR на новое решение
Retrieve-правило: читай уроки и ADR границы ПЕРЕД задачей
Команды проверки — копировать из манифеста, не выдумывать
Дублировать содержимое architecture.md внутрь AGENTS.md
Phase 1: Context Engineering. Прочитай аудит среды и состояния
проекта (docs/audit/), затем создай AGENTS.md в корне репо.
Принципы:
- Файл короткий (<= 100 строк). Это КАРТА, а не энциклопедия.
- AGENTS.md — общий контракт для любых кодинг-агентов.
- Содержит ССЫЛКИ на источники правды в docs/, не дубль контента.
Структура AGENTS.md:
1. Какой это проект, в одном абзаце.
2. Стек (один список).
3. Где лежит правда: ссылки на docs/architecture.md,
docs/decisions/, docs/templates/ExecPlan.md, аудит среды.
4. Working rules:
- один тред = одна задача
- для крупных задач — ExecPlan
- коммиты атомарные
- обновляй документацию, если меняешь описанное в ней поведение
- не используй инструменты, не зафиксированные в аудите среды
5. Definition of Done: чек-лист, что значит «готово» —
форматтер/линтер/тайп-чек/тесты/билд зелёные, доки обновлены,
на новое архитектурное решение заведён ADR.
6. Retrieve-правило: перед задачей на конкретной границе сначала
прочитай накопленные по ней уроки и связанные ADR.
7. Команды проверки. Бери КОНКРЕТНЫЕ команды из манифеста проекта
(package.json, pyproject.toml, build.gradle, Cargo.toml — что
применимо). Не выдумывай команды, которых нет.
8. Что НЕ делать: явные запреты, специфичные для проекта.Definition of Done — это конвенция, пока она только в тексте. Цель фазы 3 — перенести как можно больше её пунктов в машинные барьеры (pre-commit + CI): что проверяет машина, агент не обойдёт; что осталось текстом — держится только на его дисциплине.
3
Аддендум под конкретного агента: CLAUDE.md / .cursorrules / system prompt
AGENTS.md — для любого агента. Но у каждого инструмента есть своя механика, которой нет смысла в общем контракте: у Claude Code это skills, plan mode и подключённые MCP-серверы; у Cursor — формат .cursorrules и его правила; у самописного агента — system prompt. Принцип: общее → в AGENTS.md, специфика инструмента → в его аддендум. Не дублируйте: аддендум ссылается на AGENTS.md, а не переписывает его.
Аддендум тоже короткий (≤100 строк) и отвечает на узкие вопросы: какие skills доступны и для каких процедур; какой режим использовать для каких задач (например, plan mode для нетривиальных); какие MCP-серверы подключены и зачем. Если завтра команда заведёт второго агента — вы создаёте второй аддендум, а общий контракт не трогаете. Это и есть стек- и агент-агностичность на практике.
| Агент / среда | Файл аддендума | Что кладём (специфика) |
|---|---|---|
| Claude Code | CLAUDE.md | Skills, plan mode, подключённые MCP-серверы |
| Cursor | .cursorrules / .cursor/rules | Правила в формате Cursor, scoped-rules по путям |
| Codex / GitHub-агент | AGENTS.md уже нативен | Доп. секция, если у инструмента есть свои хуки |
| Самописный агент | system prompt в репо | Преамбула: «сначала прочитай AGENTS.md» |
Тест на дубль: если строку из аддендума можно дословно перенести в AGENTS.md без потери смысла — её место в AGENTS.md. В аддендуме остаётся только то, что не имеет смысла для другого инструмента.
4
ADR: одно решение = один markdown
ADR (Architecture Decision Record) — это фиксация одного архитектурного решения в одном markdown-файле: контекст, само решение, последствия, рассмотренные альтернативы, статус. Формат имени — `NNNN-краткое-имя.md` в `docs/decisions/`. ADR отвечает на вопрос, который агент задаёт чаще всего: «почему здесь сделано так, а не иначе?» — и тем самым останавливает попытки «улучшить» то, что выбрано осознанно.
Самая ценная часть фазы — ретроспективное оформление. Пройдитесь по кодовой базе и на каждое неявное решение, которое уже живёт в коде, но нигде не записано, заведите ADR со статусом Discovered (не Proposed): выбор фреймворка, паттерн стейт-менеджмента, подход к тестированию, способ организации модулей, формат данных API, обработка ошибок. Минимум 3, максимум 10 — не больше, чтобы не утонуть. Это самое дешёвое внедрение во всей серии: один markdown за 15–20 минут, и решение перестаёт быть «племенным знанием». Шаблон ниже копируется как есть.
# NNNN. <Краткое имя решения / Short decision name>
- **Status / Статус:** Discovered | Proposed | Accepted | Superseded
- **Date / Дата:** YYYY-MM-DD
- **Authors / Авторы:** <...>
## Context / Контекст
Что заставило принимать решение: ограничения, силы, проблема.
What forced the decision: constraints, forces, the problem.
## Decision / Решение
Что именно решили. Один абзац, в настоящем времени.
What exactly was decided. One paragraph, present tense.
## Consequences / Последствия
Что стало проще, что — сложнее. Что теперь нельзя делать.
What got easier, what got harder. What is now off-limits.
## Alternatives Considered / Рассмотренные альтернативы
Какие варианты отвергли и почему. Без этого ADR бесполезен.
Which options were rejected and why. Without this an ADR is useless.Самая важная секция — Alternatives Considered. ADR без отвергнутых вариантов не останавливает агента: он не видит, что выбор был осознанным, и «чинит» то, что чинить не надо. Раздел Discovered-статуса честно говорит «так уже сделано», а не «так задумано идеально».
5
architecture.md: карта слоёв и границ
architecture.md — карта, по которой агент ориентируется и которую позже будет защищать линтер границ. Пять разделов: top-level map (бизнес-домены, без реализации); layer model (технические слои и направления зависимостей — для каждого: что МОЖНО, что НЕЛЬЗЯ); external integrations (с чем общаемся: API, БД, очереди); cross-cutting concerns (где живут аутентификация, логирование, ошибки, конфиг); и явный раздел «чего НЕТ в этом репо» — чтобы агент не пытался решать здесь задачи соседних систем.
Layer model — самый важный раздел: именно он на фазе 3 превратится в конфиг линтера границ (в JS/TS, например, eslint-plugin-boundaries или dependency-cruiser; в Python — import-linter; в Java — ArchUnit; в Go — внутренние пакеты и depguard). Пока это конвенция — пометьте её «Discovered, not enforced yet». И железное правило: если данных не хватает — не выдумывайте. Ставьте «?» и TODO. Архитектурная карта лучше неполная, чем выдуманная: на выдуманную карту агент будет молча опираться и тиражировать ошибку.
UI / точки входа
можно
Прикладной слой / use cases
можно
Домен / бизнес-логика
нельзя
Инфраструктура: API, БД, очереди
Стрелки на карте — это и есть будущий конфиг линтера. Слой домена, зависящий от инфраструктуры напрямую, — самое частое нарушение, которое агент допускает «по пути»; зафиксируйте направление словами здесь, чтобы на фазе 3 механизировать его проверкой.
6
Порядок внедрения и что дальше
Порядок внутри фазы 1 — от карты к контракту, потому что AGENTS.md ссылается на architecture.md и decisions/. (1) architecture.md — карта слоёв; (2) ADR: README + шаблон + ретроспективные Discovered-записи на то, что уже в коде; (3) AGENTS.md — общий контракт со ссылками на (1) и (2) + Definition of Done + retrieve-правило; (4) аддендум под вашего агента (CLAUDE.md / .cursorrules / system prompt). Каждый файл ≤100 строк, фаза заканчивается одним PR.
Definition of Done фазы 1: architecture.md есть; в docs/decisions/ лежат README, шаблон и ≥3 ADR; AGENTS.md и аддендум — каждый ≤100 строк. И честная граница: контекст-файлы — это конвенции, они держатся на дисциплине. «Записано в правилах» ≠ «реально соблюдается», пока вы не превратите это в барьер. Поэтому следующий обязательный шаг для крупных задач — ExecPlan (фаза 2), а механические барьеры под layer model и DoD ставит фаза 3.
Definition of Done — фаза 1
architecture.md есть: домены, layer model, интеграции, «что НЕ здесь»
docs/decisions/: README + шаблон + ≥3 ADR (Discovered на то, что уже в коде)
AGENTS.md ≤100 строк: working rules + Definition of Done + retrieve-правило
Аддендум под агента ≤100 строк, ссылается на AGENTS.md
Выдуманная архитектура вместо «?» и TODO в неясных местах
Считать контекст-файлы барьерами: это конвенции, барьеры — фаза 3
Не пытайтесь сделать карту идеальной с первого захода. Неполный architecture.md с честными «?» уже окупается на первой же задаче, а пробелы заполнятся ретроспективными ADR по ходу работы.
Результат
Вы собрали контракт фазы 1, который агент читает на старте каждой сессии: AGENTS.md с working rules, Definition of Done и retrieve-правилом; аддендум под вашего агента (CLAUDE.md / .cursorrules / system prompt) без дублирования общего контракта; architecture.md с картой слоёв и границ, готовой стать конфигом линтера; и каталог ADR, где одно решение = один markdown, включая ретроспективные Discovered-записи. Это всё ещё конвенции, а не барьеры — но без них агент додумывает архитектуру с нуля. Дальше: ExecPlan для многочасовых задач (фаза 2) и механические барьеры под эту карту (фаза 3).