auto-sync: 2026-06-08 20:50:01

tasks/orchestrator/ORCH-52_SYSTEM_ANALYSIS.md

@@ -0,0 +1,107 @@
+# 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 | Обернуть `<context>/<task>/<deliverables>/<constraints>/<output_format>` |
+| 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.