# ORCH-52 — Комплексный системный анализ каркаса агентов + предложения **Автор:** Стрим · **Дата:** 2026-06-08 · **Для:** ORCH-52 (стандарт документов + протокол handoff + оптимизация промптов + трассировка) **Метод:** инвентаризация всего каркаса орка + сверка с официальным каноном Anthropic. --- ## 0. Что составляет «каркас работы агентов» (полная карта) | Слой | Артефакт | Состояние | |---|---|---| | Паспорт проекта | `CLAUDE.md` | есть, живой, читается всеми (правило №1) | | Архитектура | `docs/architecture/README.md` (495 стр), `internals.md`, корневой `README.md` | есть; **README отстал от кода** (worktree/ORCH-26 «известные ограничения» помечены открытыми, хотя решены; битая нумерация) | | Системные промпты | `.openclaw/agents/{analyst,architect,developer,reviewer,tester,deployer}.md` | есть 6 шт; **разнобой, мёртвый frontmatter, нет few-shot/XML/CoT** | | Выбор модели/эффорта | `resolve_agent_model/effort` (launcher), `agent_model_*` (config) | механизм есть (ORCH-41); **дублирует frontmatter, который игнорируется** | | Frontmatter-контракт | `src/frontmatter.py` (75 стр, только reader) | минимальный; **нет writer/валидатора, нет обязательной схемы** | | Протокол вердиктов | `review_parse.py`, `staging_verdict.py`, `qg/checks.py` | работает (machine-readable verdict/result/status); **размазан по коду, нет единой спеки** | | Шаблоны документов | `docs/_templates/`, `docs/_standards/` | **НЕ СУЩЕСТВУЮТ** — каждый агент пишет с нуля | --- ## 1. КРИТИЧНО: проблема модели (то, на что ткнул Слава) ### Что обнаружено - **frontmatter промптов лжёт:** `analyst/developer/tester/deployer` → `model: claude-sonnet-4-6`; `architect/reviewer` → `model: claude-opus-4-7`. - **Реальность (resolve_agent_model):** ВСЕ агенты бегут на `claude-opus-4-8` (config `agent_model_default`, frontmatter `model:` НЕ читается launcher'ом). - **agent_runs (история) — дрейф:** opus-4-8 доминирует, но хвосты `haiku-4-5`, `opus-4-7[1m]`, `vibecode/sonnet-4.6`, `None`. Разнобой моделей по факту. ### Почему это плохо (3 уровня вреда) 1. **Документация лжёт** — frontmatter выглядит источником правды, но мёртв. Любой, кто читает промпт (человек ИЛИ агент по ORCH-52 трассировке), получает неверную инфу. Прямое нарушение «doc = golden source». 2. **Разнобой моделей** — sonnet-4-6 указан для analyst/developer/tester. Если кто-то «починит» launcher читать frontmatter — агенты молча деградируют на sonnet. Мина. 3. **Неоптимально по стратегии (экономика):** одна модель (opus-4-8) на ВСЕ роли — дорого. Anthropic прямо рекомендует **routing**: простое → дешёвая модель, сложное → мощная. ### Решение (канон Anthropic + стратегия) - **Убрать `model:` из frontmatter промптов** ИЛИ сделать его источником правды (одно из двух, не оба). Рекомендация: **убрать** — config (ORCH-41) уже единый источник, frontmatter оставить только описательным (name/description/tools). - **Ввести model-routing по ролям** (Anthropic «Routing» workflow): - Мощная модель (opus-4-8, xhigh) → analyst, architect, developer, reviewer (интеллект-критичные). - Дешёвая (haiku-4-5 / sonnet, low-medium) → tester, deployer (механические: прогнать тесты, заполнить лог). - Задаётся через `agent_model_*` / `agent_effort_*` (механизм УЖЕ есть, просто не заполнен!). - **Эффорт — настроить обязательно.** Сейчас `agent_effort_*` ПУСТЫЕ. Anthropic про Opus 4.8: «effort важнее, чем у любого прежнего Opus»; coding/agentic → **xhigh**, интеллект → минимум **high**. Сейчас эффорт не задан → CLI-дефолт (риск under-thinking на сложном ИЛИ overthinking-расход на простом). --- ## 2. Дефекты системных промптов (сверка с Anthropic prompting best-practices) Канон Anthropic для последних моделей: **clarity, few-shot examples, XML-структура, chain-of-thought/thinking, output formatting, success-criteria, литеральность Opus 4.8**. | # | Дефект (что есть) | Канон Anthropic | Предложение | |---|---|---|---| | 1 | Промпты ОПИСЫВАЮТ формат (BRD/ТЗ/AC), но не ПОКАЗЫВАЮТ | few-shot examples — мощнейший рычаг | Few-shot: эталон каждого артефакта ИЛИ ссылка на канонический шаблон (слой templates) + образцовый work-item (ORCH-073) | | 2 | Секции плоским markdown | XML-теги структурируют для Claude | Обернуть `////` | | 3 | Нет шага рассуждения | thinking/CoT как scratchpad | «Сначала продумай root cause/edge-cases, потом пиши». Для Opus 4.8 — `thinking: adaptive` где нужно | | 4 | Нет success-criteria артефакта | чёткие критерии успеха | Чек-лист «хороший BRD = root cause доказан не гипотеза; цели измеримы». Агент валидирует себя | | 5 | «Доказывай не предполагай» не зафиксировано | — | Явно: root cause подтверждать git/кодом, гипотезы помечать (лучшие BRD 71/73 это делали — сделать нормой) | | 6 | Opus 4.8 ЛИТЕРАЛЕН (не обобщает) | «state scope explicitly» | Все инструкции — явные, со scope. «применить ко ВСЕМ секциям, не только первой» | | 7 | Opus 4.8 калибрует verbosity сам | контроль длины | Где нужна краткость/полнота — прописать явно с позитивным примером | | 8 | Запреты как negative («не делай») | позитивные примеры эффективнее негативных | Дополнить «как НАДО» рядом с «Запрещено» (anti-pattern + good-pattern) | --- ## 3. Дефекты стандарта документов и протокола (исходный скоуп ORCH-52) 1. **Нет `docs/_templates/`** — агенты пишут артефакты с нуля → разнобой качества (71/73 эталон, ранние слабее = везение, не система). 2. **Нет манифеста стадии→документы** — непонятно что required / when-applicable / optional. Заполнение неравномерное (01-04 всегда, 08-data 1 раз, 07-infra 7 раз). 3. **frontmatter-контракт минимален** (`frontmatter.py` — только reader). Нет writer/валидатора, нет обязательной схемы `work_item/stage/author_agent/status/created_at/model_used`. 4. **Протокол вердиктов размазан** (review_parse/staging_verdict/checks) — нет единого документа-контракта «reviewer обязан выдать `verdict:`, tester — `result:`, в таком YAML». 5. **ADR именуются произвольно** (ADR-001-unified-status... / ADR-001-tracker-bump...) — нет конвенции. 6. **README дрейфует** — «известные ограничения» врут (worktree/параллелизм решены), битая нумерация. Reviewer валидирует work-item доки, но НЕ обзорный README. --- ## 4. Связь со СТРАТЕГИЕЙ (принципы платформы) | Принцип | Как ORCH-52 его реализует | |---|---| | **Автономно** | Шаблоны + success-criteria → агент работает без уточнений, заполняет канон | | **Надёжно/безопасно** | frontmatter-контракт + протокол вердиктов machine-readable → гейты не ошибаются; трассировка ORCH-NNN → агент не ломает инварианты прошлых задач | | **Саморазвитие** | Стандарт = база для ORCH-8 (петля обучения): орк сам обновляет шаблоны/промпты по урокам инцидентов | | **Экономично/рационально** | Model-routing (дешёвая для механики) + эффорт-калибровка + меньше REQUEST_CHANGES-циклов = меньше токенов (связь ORCH-72/23) | | **Наблюдаемо** | Единый frontmatter (`model_used`, `verdict`, метрики) → видно кто/чем/с каким результатом отработал; `/queue` snapshot | --- ## 5. Предлагаемая структура ORCH-52 (3+1 слой, единый эпик) > Большая задача → кандидат на ДЕКОМПОЗИЦИЮ (ORCH-25), но пока ORCH-25 нет — вести как эпик с под-PR по слоям. - **Слой 1 — Стандарт документов:** `docs/_standards/PIPELINE_DOCS.md` (манифест стадия→доки: владелец/required/gate) + `docs/_templates/*` (канонические скелеты) + ADR-naming конвенция. - **Слой 2 — Протокол handoff/вердиктов:** единый документ-контракт + расширенный `frontmatter.py` (writer/валидатор, обязательная схема). Гейты читают стандартные поля. - **Слой 3 — Оптимизация промптов:** переписать 6 `.openclaw/agents/*.md` по Anthropic (8 дефектов выше) + **починить модель** (убрать мёртвый frontmatter, ввести routing+effort через config). - **Слой 4 — Трассировка ORCH-NNN:** маркеры-стандарт + правило чтения в промптах (уже добавлено в описание). ### Измеримый DoD (эффект) - frontmatter промптов НЕ противоречит реальной модели (или удалён). - Model-routing: ≥1 механический агент на дешёвой модели, эффорт задан явно для всех. - A/B: одна реальная задача старый-vs-новый промпт → сравнить циклы REQUEST_CHANGES / токены / качество. - README синхронизирован с кодом (известные ограничения актуальны). - pytest зелёный; гейты вердиктов не сломаны. --- ## 6. Источники (официальный канон Anthropic) - Building Effective Agents — anthropic.com/engineering/building-effective-agents (workflows vs agents, routing, prompt-chaining+gate, evaluator-optimizer, orchestrator-workers). - Prompting best practices (latest models) — platform.claude.com/docs/.../claude-prompting-best-practices (Opus 4.8: effort xhigh/high, литеральность, verbosity-calibration, thinking adaptive, subagent-steering, output budget 64k). - Multi-agent research system — anthropic.com/engineering/multi-agent-research-system (thinking как scratchpad, роли субагентов). - Building agents with Claude Agent SDK — субагенты, параллелизация. - Prompt engineering overview — clarity, examples, XML, role, CoT, success-criteria.