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-структурой секций: <context> / <task> / <deliverables> / <constraints> / <output_format> (допустимы дополнительные семантические секции, напр. <thinking>-подсказка).
Добавить в каждый промпт явную инструкцию эмитить обязательную 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-стилем секций (<context> / <task> / <deliverables> / <constraints> / <output_format>).
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 увеличат объём и «утопят» ключевые запреты. Митигация: ссылки на эталоны вместо инлайна, контроль объёма.

14 KiB Raw Permalink Blame History Unescape Escape