feat(skill): claude-subagent-playbook — конвейер одной задачи с Codex

- Зачем: - выжимка боевого прогона 2026-07-06 (t2-ml-forecast, витрина) в переиспользуемый плейбук: постановка → свежий взгляд → реализация Codex → слепое двойное ревью разных родословных → синтез. - Что: - SKILL.md: роли, шаги с критериями закрытия, триаж у исполнителя, границы применимости; словарь общий с coordinator-loop; - references: механика codex-companion с ловушками и раннер-паттерном, накопительная эмпирика прогонов, определения deep-reasoner/fast-worker для воссоздания в новом репозитории; - handoffs: записка о рождении скилла и списке непроверенного боем. - Проверка: - зеркало ~/.claude/skills синхронно (diff -rq чисто); боевой тест — следующий прогон конвейера по тексту скилла. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-06 18:22:00 +03:00
1 parent ca30ac5272
commit 138315d496
@@ -0,0 +1,96 @@
+# Репо-локальные Claude-субагенты и конструкция оркестрации
+
+`deep-reasoner` и `fast-worker` — субагенты уровня репозитория
+(`.claude/agents/*.md`), не глобальные. В новом репозитории их нет — проверь
+`ls .claude/agents/` и при отсутствии создай файлы ниже как есть.
+
+## Конструкция оркестрации (фрагмент CLAUDE.md репозитория)
+
+```markdown
+## Orchestration workflow
+You (Fable) are the orchestrator. Plan, decompose, synthesize.
+Reasoning-heavy phases → deep-reasoner
+Mechanical work → fast-worker
+Codex (/codex:rescue --background) is a cracked engineer on par with
+deep-reasoner, from a different perspective. Treat as a peer, not a reviewer.
+High-stakes decisions: task Opus + Codex on the same problem in parallel,
+synthesize the best of both, without showing either the other's answer.
+Keep your own context lean.
+```
+
+## `.claude/agents/deep-reasoner.md`
+
+```markdown
+---
+name: deep-reasoner
+description: >
+  Use for reasoning-heavy phases: architecture, debugging complex issues,
+  algorithm design, tricky trade-offs. Think thoroughly, return a concise
+  conclusion the orchestrator can act on.
+model: opus
+effort: high
+color: purple
+---
+
+# Deep Reasoner
+
+You are the orchestrator's reasoning specialist. You are handed the hard
+thinking: architecture decisions, complex debugging, algorithm design,
+non-obvious trade-offs.
+
+## Operating stance
+
+- Think thoroughly before answering. Explore the problem, consider
+  alternatives, check your reasoning for holes.
+- Do the deep work internally. What you return to the orchestrator is a
+  **concise conclusion it can act on** — not a transcript of your thinking.
+- State assumptions explicitly. If a decision hinges on something you
+  couldn't verify, say so and give your best recommendation anyway.
+- When there are real trade-offs, name them briefly, then commit to a
+  recommendation. The orchestrator wants a decision, not a menu.
+
+## Output
+
+Lead with the conclusion. Then, only if it adds value:
+- the key reasoning in a few bullets,
+- risks or open questions the orchestrator should know about,
+- concrete next steps.
+
+Keep it tight. Your value is the quality of the conclusion, not its length.
+```
+
+## `.claude/agents/fast-worker.md`
+
+```markdown
+---
+name: fast-worker
+description: >
+  Use for mechanical tasks: boilerplate, tests, formatting, simple edits,
+  batch and file operations, running checks. Execute efficiently and
+  return only the result.
+model: sonnet
+color: green
+---
+
+# Fast Worker
+
+You are the orchestrator's execution specialist. You are handed mechanical,
+well-scoped work: boilerplate, tests, formatting, simple edits, batch and
+file operations, running lint/checks.
+
+## Operating stance
+
+- Execute efficiently. The task is usually clear — do it, don't re-plan it.
+- Follow existing conventions in the codebase: match surrounding style,
+  naming, and structure. Read a neighbouring file if unsure.
+- If the task is genuinely ambiguous or you hit a real blocker, stop and
+  report back with the specific question — don't guess on decisions that
+  belong to the orchestrator.
+- Read noisy input/output yourself and return only the distilled result,
+  so the orchestrator's context stays clean.
+
+## Output
+
+Return just what the orchestrator needs: what you did, and any result it
+must see (a summary, a diff of note, a failing check). Skip narration.
+```
@@ -0,0 +1,89 @@
+# Codex companion из Claude Code: команды и ловушки
+
+Проверено 2026-07-06 (плагин openai-codex/codex 1.0.5). Путь к скрипту зависит
+от версии — найди актуальный:
+
+```bash
+ls ~/.claude/plugins/cache/openai-codex/codex/*/scripts/codex-companion.mjs
+```
+
+Далее `$CC` = `node <найденный путь>`.
+
+## Команды
+
+```bash
+$CC task --background --write --fresh "промпт"   # реализация (пишет файлы)
+$CC adversarial-review --background --scope working-tree "фокус ревью"
+$CC status                    # все задачи; status <job-id> — одна, с прогрессом
+$CC result <job-id>           # финальный отчёт завершённой задачи
+$CC cancel <job-id>
+$CC task-resume-candidate --json   # есть ли возобновляемый тред этой сессии
+```
+
+## Запуск через раннера-субагента — рекомендуемый путь
+
+Приём из `/adversarial-review`: оркестратор не зовёт CLI сам и не городит
+мониторы — фоновый субагент-раннер синхронно гоняет команду у себя, шум
+остаётся в нём, а завершение субагента само будит оркестратора.
+
+Ключевое правило: **раннеру — готовую команду, не постановку задачи.**
+Получив постановку, «тонкий» агент реализует её сам (ловушка форвардера).
+Промпт задачи живёт только внутри строки-аргумента команды.
+
+Рецепт: Agent tool, `subagent_type: "general-purpose"` (или `fast-worker`,
+если есть), `run_in_background: true`, промпт раннеру:
+
+```text
+Выполни ровно одну команду Bash, ничего не решай и не делай сверх неё:
+$CC task --wait --write --fresh "<полный промпт задачи>" \
+  > /tmp/<scratchpad>/codex-run-<id>.log 2>&1
+Затем верни: код возврата, путь к логу и последние ~30 строк лога.
+```
+
+Так же запускается и ревью (`adversarial-review --wait ...`). Прямой вызов
+CLI с `--background` + фоновый bash-монитор (ниже) — запасной путь, когда
+раннер нежелателен (например, экономия субагентов).
+
+## Ловушки (все выстраданы)
+
+- **Без `--write` среда Codex только на чтение.** Задача «реализуй…» без
+  этого флага молча не сможет писать файлы.
+- **`task --help` не существует** — строка `--help` уходит Кодексу как промпт
+  и создаёт мусорный тред. Синтаксис смотри `$CC` без аргументов.
+- **`--fresh` против `--resume-last`:** resume-last цепляет самый свежий тред,
+  а им может оказаться тред ревью, не реализации. Для точечных починок надёжнее
+  `--fresh` + точный промпт («добавь только X, ничего больше не меняй»).
+- **Коммит запрещай промптом** («коммит не делай — оставь в рабочем дереве»):
+  ревью идёт по незакоммиченному дифу, коммитит оркестратор.
+- **Тонкому агенту-форвардеру не давай содержательный промпт.** Субагент
+  `codex:codex-rescue` должен только пробросить команду; получив постановку
+  задачи, он реализует её сам вместо передачи (казус 2026-07-06 — второй
+  писатель в дереве). Либо зови companion напрямую из Bash, либо давай
+  форвардеру только готовую команду.
+
+## Мониторинг фоновых задач (запасной путь)
+
+При прямом `--background` уведомлений от companion нет — повесь фоновый
+bash-монитор, он разбудит оркестратора по завершении:
+
+```bash
+# run_in_background: true
+for i in $(seq 1 120); do
+  st=$($CC status <job-id> 2>/dev/null)
+  if echo "$st" | grep -q '| running |'; then sleep 30; else echo FINISHED; exit 0; fi
+done
+```
+
+Парсить plain-text: `status --json` устроен иначе, чем кажется (грабли
+2026-07-06 — монитор на JSON-поле `state` крутился вечно на `unknown`).
+
+## Фоновые Claude-субагенты (Agent tool)
+
+- Ревьюеров запускай `model: "opus"` (экономия лимитов; ревью на Фабуле —
+  ~60k токенов за прогон).
+- Фоновый агент по завершении шлёт **idle-уведомление без содержимого**.
+  Финальный отчёт запроси `SendMessage`: «верни готовый результат, ничего
+  нового не проверяй».
+- Проверяй, что делегат сделал именно то, что просили: `git status` до и
+  после, кто и когда трогал файлы (`stat -c '%y'`), прежде чем запускать
+  следующего писателя.
@@ -0,0 +1,42 @@
+# Эмпирика прогонов
+
+Датированные факты: что поймал каждый этап конвейера, казусы, цифры.
+Дописывай после каждого прогона — это и есть «выжимка опыта», ради которой
+скилл существует.
+
+## 2026-07-06 — t2-ml-forecast, задача 05 «полировка витрины под демо»
+
+Первый прогон конвейера. Задача: ~200 строк правок в ядре отчёта + ноутбук.
+
+**Свежий взгляд на постановку (Клод, adversarial-reviewer) — окупился:**
+- блокер: постановка требовала «русские названия из `report.name_ru`», а в
+  данных `name_ru` — английские имена из Excel-книги; исполнитель молча
+  сделал бы английские заголовки. Решение внесено в задачу: словарь
+  «статья → русское имя» как явная поставка;
+- две «одностроки», прятавшие проектные решения: поворот отрицательного ряда
+  (правило, пересчёт коридора, единый хелпер) и согласованность
+  «график по модулю vs таблица со знаком»;
+- процессная дыра: без явных двух шагов регенерации `.ipynb` остался бы без
+  выводов, и тест ноутбука его бы завернул.
+
+**Казус форвардера:** субагент `codex:codex-rescue`, получив постановку
+вместо команды, реализовал задачу сам (+1227 строк). Настоящий Codex стартовал
+на уже изменённом дереве — столкновения избежали везением (форвардер успел
+закончить). Урок в SKILL.md и codex-companion.md.
+
+**Слепое двойное ревью — родословные поймали разное:**
+- Клод (Опус): APPROVE; подтвердил математику поворота/коридора
+  (алгебраическое тождество), краевые случаи (ряд через ноль, нули),
+  неизменность метрик и таблиц; посмотрел картинки из `.ipynb`; один nit.
+- Codex (свежий тред): needs-attention; две дыры в тестах — раздел ноутбука
+  не закреплён в required_snippets, нет регрессионного теста «таблица
+  отрицательного ряда остаётся со знаком». Оба — про то, что зелёный прогон
+  не докажет готовность; Клод этих дыр не нашёл.
+- Пересечения находок — ноль. Слепота и разность родословных работают.
+
+**Точечная починка:** Codex `--fresh` с промптом «добавь только два теста,
+продуктовый код не трогай» — чисто, 148 → 150 passed.
+
+**Цифры для калибровки:** ревью Клода на Фабуле (этап постановки) — ~60k
+токенов; конвейер целиком — ~3 часа настенного времени, из них реализация
+~20 минут; остальное — ревью и оркестрация. На мелочь такое не разворачивать.