# adr-0021: Канон Anthropic для системных промптов агентов + эмиссия frontmatter-схемы 52c

- **Статус:** proposed
- **Дата:** 2026-06-09
- **Источник:** ORCH-077 (эпик ORCH-52, слой 52d — замыкающий)
- **Связи:** реализует слой промптов к adr-0019 (52b, PIPELINE_DOCS) и adr-0020 (52c,
  frontmatter-контракт). Детально — `docs/work-items/ORCH-077/06-adr/ADR-001-anthropic-prompt-canon.md`.

## Контекст

Эпик ORCH-52 строит сквозной контракт документации конвейера: **52b** (adr-0019) — описательный
стандарт документов + скелеты `docs/_templates/`; **52c** (adr-0020) — машинный контракт
`src/frontmatter.py` (reader/writer/валидатор `REQUIRED_FIELDS`) + спека `HANDOFF_PROTOCOL.md` с
обязательной 6-польной схемой `(work_item, stage, author_agent, status, created_at, model_used)`.

Две незакрытые проблемы:
1. **Цепочка 52b→52c→52d разорвана.** Writer и валидатор схемы есть, но работают warning-only
   (`frontmatter_validation_strict=False`); агенты **не эмитят** поля схемы — на входе валидатора нет
   данных, петля не замкнута.
2. **Форма 6 промптов `.openclaw/agents/*.md` разнородна** (RU/EN, свободная структура) → снижает
   предсказуемость агентов прода, которые исполняются на КАЖДОЙ задаче ВСЕХ проектов из общего
   инстанса (self-hosting).

Факт загрузки (сверено `src/agents/launcher.py`): промпт `cat`-ается из git-worktree агента в момент
запуска (`--system-prompt "$(cat .openclaw/agents/<role>.md)"`), НЕ запекается в образ.

## Решение

Ввести **обязательный канон формы** для всех агент-промптов и сделать его машинно-проверяемым.

1. **Фиксированный XML-скелет (5 обязательных секций, нормативный порядок):**
   `<context>` → `<task>` (+ опц. `<thinking>`) → `<deliverables>` → `<constraints>` →
   `<output_format>`. Доп. секции (`<success_criteria>`, `<escalation>`) — после. Контекст/роль
   вперёд, формат вывода последним (recency для следования схеме).
2. **Аддитивная эмиссия схемы 52c.** `<output_format>` каждого промпта перечисляет 6 полей схемы с
   роле-специфичными значениями и инструктирует ставить их **рядом** с существующим machine-verdict
   ключом, **не меняя его имя/регистр/значения** (`verdict:`, `result:`, `staging_status:`,
   `deploy_status:`, `security_status:` — байт-в-байт). Для `04-test-plan.yaml` (чистый YAML) — как
   top-level ключи. Гейты читают вердикты как раньше (схема в boolean-вердикте не участвует).
3. **Few-shot + позитивные альтернативы.** Ссылки на `docs/_templates/` и эталоны (ORCH-073/088);
   каждый запрет в формате «❌ X → ✅ Y».
4. **CoT/thinking** у решающих ролей (architect/reviewer/tester/deployer).
5. **Анти-регресс машинно.** Структурные тесты `tests/test_agent_prompts_canon.py` (без запуска
   агентов): 5 секций, 6 полей схемы, точный регистр machine-verdict ключей, ключевые
   self-hosting-маркеры (deployer: `docker exec orchestrator-staging`, `pr_already_merged`,
   «не рестартить 8500»). `test_agent_frontmatter_no_model.py` остаётся зелёным.
6. **Enforcement не включается.** `frontmatter_validation_strict` остаётся `False` (warning-only);
   52d учит эмитить добровольно. Hard-fail — отдельная будущая задача.

**Границы:** docs/prompts-only. `src/**` (config, launcher, frontmatter, stages, qg/checks,
stage_engine), `STAGE_TRANSITIONS`, `QG_CHECKS`, состав machine-verdict ключей, схема БД, `tools:`-блок
промптов — **не трогаются**.

**Норматив на будущее:** любая новая правка/добавление агент-промпта следует этому канону (5 секций +
аддитивная схема + ❌→✅). Отступление требует нового ADR.

## Альтернативы

- **Сразу включить hard-fail схемы.** Отвергнуто: правка `src/config.py` вне scope; для self-hosting
  рискованно (забытое поле валит гейт всех проектов). Сначала эмиссия, enforcement — позже.
- **Канон как рекомендация, не норма.** Отвергнуто: теряется машинная проверяемость, эпик требует
  контракт.
- **Запечь промпты в образ.** Отвергнуто: противоречит loading-model (cat из worktree), добавило бы
  прод-рестарт-зависимость.

## Последствия

- **+** Петля 52 замкнута: схема наполняется реальными данными на каждой стадии всех проектов.
- **+** Единый предсказуемый канон; правки промптов вступают в силу **без прод-рестарта** (следующий
  worktree от `main`) → нулевой self-hosting-риск выкатки.
- **+** Естественный in-vivo A/B: reviewer/tester задачи исполняются под новыми промптами в той же
  ветке (метод BR-6).
- **−** Рост объёма промптов (митигейшн: ссылки вместо инлайна, контроль объёма).
- **−** Риск регресса инструкции (митигейшн: построчная карта + структурные тесты + приоритетный
  review deployer/reviewer).
- **Откат:** `git revert` PR — свободная форма возвращается, эмиссия прекращается, гейты идентичны.

## Связи
- Реализует: adr-0019 (52b), adr-0020 (52c).
- Per-work-item: `docs/work-items/ORCH-077/06-adr/ADR-001-anthropic-prompt-canon.md`.
- Стандарты: `docs/_standards/PIPELINE_DOCS.md`, `docs/_standards/HANDOFF_PROTOCOL.md`,
  `src/frontmatter.py::REQUIRED_FIELDS`.
- Сверено по коду: `src/agents/launcher.py`, `Dockerfile`,
  `src/config.py::frontmatter_validation_strict`, `tests/test_agent_frontmatter_no_model.py`.
