# 01 — BRD (бизнес-требования): ORCH-077 — ORCH-52d: оптимизация 6 системных промптов по Anthropic Work Item: **ORCH-077** · Repo: **orchestrator** (self-hosting) · Стадия: analysis ## 1. Бизнес-контекст и проблема Эпик **ORCH-52** строит сквозной контракт документации конвейера тремя слоями: - **52b (ORCH-075)** — описательный стандарт документов: `docs/_standards/PIPELINE_DOCS.md` (карта «стадия → агент → документ → гейт → machine-key») + копируемые скелеты в `docs/_templates/`. - **52c (ORCH-076)** — машинный контракт: единый `src/frontmatter.py` (reader + writer + валидатор `validate_schema`/`REQUIRED_FIELDS`) и спека `docs/_standards/HANDOFF_PROTOCOL.md` с **обязательной frontmatter-схемой** (`work_item`, `stage`, `author_agent`, `status`, `created_at`, `model_used`). - **52d (эта задача, ORCH-077)** — слой промптов: замыкающее звено. **Боль 1 (разрыв цепочки 52b→52c→52d).** 52c заложила writer и валидатор обязательной схемы, но работает в режиме **обратной совместимости** (`frontmatter_validation_strict=False`, warning-only) — агенты **физически не проставляют** эти поля в своих выходных документах. Пока 6 системных промптов не научены эмитить схему, петля 52 не замкнута: writer есть, валидатор есть, а данных на входе нет. **Боль 2 (форма промптов).** 6 системных промптов агентов (`.openclaw/agents/*.md`) написаны в свободной разнородной форме (часть по-русски, deployer — по-английски), без единой структуры. Это снижает предсказуемость поведения агентов прода и затрудняет сопровождение. Канон Anthropic по построению системных промптов (XML-разметка секций, few-shot с эталонами, явное место для рассуждения, позитивные примеры рядом с запретами, литеральный scope) даёт измеримо более стабильный выход. **Установленные факты (проверено в репозитории):** - Промпты в `.openclaw/agents/`: `analyst.md`, `architect.md`, `developer.md`, `reviewer.md`, `tester.md`, `deployer.md` — все 6 в объёме. - Модель/эффорт каждого агента резолвятся ТОЛЬКО из config (`resolve_agent_model` / `resolve_agent_effort`, ORCH-41); frontmatter `model:` удалён как мёртвый (ORCH-074, тест `tests/test_agent_frontmatter_no_model.py`). Все 6 ролей сейчас на `claude-opus-4-8`. - Обязательная схема: `src/frontmatter.py::REQUIRED_FIELDS = ("work_item", "stage", "author_agent", "status", "created_at", "model_used")`. - Machine-verdict ключи (регистрозависимы, читаются гейтами ТОЛЬКО из frontmatter): `verdict:` (12-review.md), `result:`/`verdict:`/`status:` (13-test-report.md), `staging_status:` (15-staging-log.md), `deploy_status:` (14-deploy-log.md), `security_status:` (17-security-report.md). ## 2. Объём (scope) ### В объёме - Переписать **все 6** промптов `.openclaw/agents/*.md` в едином каноне Anthropic с XML-структурой секций: `` / `` / `` / `` / `` (допустимы дополнительные семантические секции, напр. ``-подсказка). - Добавить в каждый промпт **явную инструкцию эмитить обязательную frontmatter-схему 52c** (`work_item` / `stage` / `author_agent` / `status` / `created_at` / `model_used`) в тех выходных документах, которые роль авторствует, с конкретными для роли значениями (`author_agent` = роль, `stage` = стадия роли, `model_used` = резолв ORCH-41). - Few-shot: ссылки на скелеты 52b (`docs/_templates/`) и эталонные work item (ORCH-073 / ORCH-088) как примеры заполнения; позитивные примеры рядом с запретами («делай Y вместо X»). - Явное место для рассуждения (CoT/thinking) там, где это уместно для роли. - Чёткие success-criteria артефакта стадии (что считается готовым выходом). - Обновить документацию: `CLAUDE.md`, `docs/architecture/README.md`, ADR (per-work-item + при необходимости сквозной), `CHANGELOG.md`. ### Вне объёма - **Любая правка кода**: `src/config.py`, `src/agents/launcher.py`, `resolve_agent_model` / `resolve_agent_effort`, `src/frontmatter.py` (сделана в 52c), `src/stages.py`, `src/qg/checks.py`, `src/stage_engine.py`. - **Включение жёсткой валидации** схемы (`frontmatter_validation_strict`) — остаётся `False` (warning-only). 52d учит промпты эмитить схему добровольно; enforcement не включается. - Изменение состава/семантики Quality Gates, `STAGE_TRANSITIONS`, набора machine-verdict ключей. - Model-routing / смена моделей ролей (вне эпика). - Изменение `tools:`-блока (разрешённые инструменты) в frontmatter промптов. ## 3. Заинтересованные стороны - **Заказчик / Owner (Слава)** — принимает результат; ручной BRD-гейт. - **Потребитель прямой** — 6 агентов прода, которые исполняют эти промпты на КАЖДОЙ задаче ВСЕХ проектов (orchestrator + enduro-trails) из общего инстанса. - **Косвенно затронуты** — все будущие work item (качество артефактов конвейера) и петля 52 (наполнение frontmatter-схемы реальными данными). ## 4. Бизнес-требования (BR) - **BR-1** — Все 6 промптов (`.openclaw/agents/*.md`) переписаны единым XML-стилем секций (`` / `` / `` / `` / ``). - **BR-2** — Каждый промпт **явно инструктирует** агента проставлять обязательную frontmatter-схему 52c (все 6 полей) в выходных документах, которые роль авторствует, с конкретными для роли значениями. - **BR-3** — Few-shot: каждый промпт ссылается на скелеты 52b (`docs/_templates/`) и эталоны (ORCH-073 / ORCH-088); запреты сопровождаются позитивным примером («делай Y вместо X»). - **BR-4 (АНТИ-РЕГРЕСС, критично для self-hosting)** — НИ ОДНА функциональная инструкция старого промпта не потеряна: гейты, machine-verdict ключи и их регистр, маркеры `ORCH-NNN`, правила `CLAUDE.md`, ролевые запреты, идемпотентный merge-guard, canonical staging-команда (`docker exec`), self-hosting-запреты. Агенты продолжают проходить свои гейты. - **BR-5** — Код НЕ изменён: правятся только `.openclaw/agents/*.md` + документация; `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` нетронуты. - **BR-6** — Проведена A/B-проверка минимум на одной репрезентативной стадии (старый vs новый промпт): новый промпт НЕ хуже по числу циклов `REQUEST_CHANGES` / качеству артефакта. - **BR-7** — Документация (`CLAUDE.md` / `README` / ADR / `CHANGELOG`) обновлена в том же PR. ## 5. Нефункциональные требования (NFR) - **NFR-1 (обратная совместимость гейтов)** — Новые промпты эмитят схему **аддитивно**: рядом с существующими machine-verdict ключами, не меняя их имени/регистра/позиции. Гейты читают вердикты ровно как раньше (схема при `strict=False` в вердикте не участвует). - **NFR-2 (безопасность прода)** — Промпт = поведение агента прода для ВСЕХ проектов. Рефактор формы не должен ослабить ни одну рабочую инструкцию (особенно self-hosting-запреты deployer'а: «не рестартить 8500 изнутри», merge-guard). - **NFR-3 (валидность frontmatter промпта)** — YAML-frontmatter каждого `.openclaw/agents/*.md` остаётся валидным YAML, сохраняет `name`/`description`, НЕ возвращает удалённый `model:` (тест `test_agent_frontmatter_no_model.py` остаётся зелёным). - **NFR-4 (читабельность/сопровождаемость)** — Единый канон облегчает будущие правки; объём каждого промпта остаётся соразмерным (без раздувания «воды»). - **NFR-5 (обратимость)** — Изменение чисто текстовое; откат = git revert PR, без миграций состояния/БД. ## 6. Допущения и ограничения - **Допущение 1** — `model_used` для всех 6 ролей сейчас = `claude-opus-4-8` (README §«Модель и эффорт по ролям»); промпт инструктирует ставить именно эту модель как резолв ORCH-41. Если model-routing включат позже — значение пересматривается, но это вне ORCH-077. - **Допущение 2** — `created_at` агент берёт как текущую дату (`YYYY-MM-DD`); источник — доступный агенту способ (напр. `date +%F` через Bash там, где Bash в `tools:`). - **Ограничение 1** — `tools:`-блок и разрешённые пути записи каждого промпта НЕ расширяются: агент эмитит схему только в те документы, которые и так авторствует. - **Ограничение 2** — Developer не авторствует номерного handoff-вердикт-документа (его выход — код + PR, гейт `check_ci_green`); для него инструкция схемы применяется к when-applicable докам (`07`/`08`/`10`), если он их трогает, а основной акцент — на сохранении dev-инструкций. - **Ограничение 3** — `frontmatter_validation_strict` остаётся `False`; ORCH-077 НЕ включает hard-fail (это была бы правка config = вне scope). ## 7. Критерии успеха Резюме: 6 промптов переписаны по канону Anthropic, эмитят схему 52c, не потеряли ни одной функциональной инструкции, код не тронут, документация обновлена, A/B подтверждает «не хуже». Детальные PASS/FAIL — `03-acceptance-criteria.md`. ## 8. Риски Краткий перечень (детали — `10-tech-risks.md`, заполняет архитектор): - **R-1 (регресс поведения агента)** — при рефакторе формы потерять рабочую инструкцию → агент ломает выход для ВСЕХ проектов. Митигация: построчная карта «старая инструкция → где в новом промпте» (AC-4), A/B-прогон. - **R-2 (ложный гейт-провал)** — случайно изменить регистр/имя machine-verdict ключа или сместить его так, что парсер не найдёт. Митигация: явный инвентарь ключей, структурные тесты. - **R-3 (некорректный `model_used`)** — захардкодить неверную модель. Митигация: ссылка на резолв ORCH-41 и таблицу README. - **R-4 (раздувание промпта)** — XML-канон + few-shot увеличат объём и «утопят» ключевые запреты. Митигация: ссылки на эталоны вместо инлайна, контроль объёма.