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 уровня вреда)

Документация лжёт — frontmatter выглядит источником правды, но мёртв. Любой, кто читает промпт (человек ИЛИ агент по ORCH-52 трассировке), получает неверную инфу. Прямое нарушение «doc = golden source».
Разнобой моделей — sonnet-4-6 указан для analyst/developer/tester. Если кто-то «починит» launcher читать frontmatter — агенты молча деградируют на sonnet. Мина.
Неоптимально по стратегии (экономика): одна модель (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)

Нет docs/_templates/ — агенты пишут артефакты с нуля → разнобой качества (71/73 эталон, ранние слабее = везение, не система).
Нет манифеста стадии→документы — непонятно что required / when-applicable / optional. Заполнение неравномерное (01-04 всегда, 08-data 1 раз, 07-infra 7 раз).
frontmatter-контракт минимален (frontmatter.py — только reader). Нет writer/валидатора, нет обязательной схемы work_item/stage/author_agent/status/created_at/model_used.
Протокол вердиктов размазан (review_parse/staging_verdict/checks) — нет единого документа-контракта «reviewer обязан выдать verdict:, tester — result:, в таком YAML».
ADR именуются произвольно (ADR-001-unified-status... / ADR-001-tracker-bump...) — нет конвенции.
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.

13 KiB Raw Blame History Unescape Escape