108 lines
13 KiB
Markdown
108 lines
13 KiB
Markdown
# 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.
|