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,123 @@
+---
+name: claude-subagent-playbook
+disable-model-invocation: true
+description: >-
+  Конвейер одной задачи со стороны Claude Code: постановка → свежий взгляд →
+  реализация Кодексом → слепое двойное ревью → синтез. Знания, не каркас.
+---
+
+# Плейбук: одна задача через Кодекса и слепое двойное ревью
+
+Ты — **оркестратор** в сессии Claude Code: планируешь, ставишь задачу,
+раздаёшь работу, синтезируешь. Реализацию не пишешь. Это плейбук — знания и
+приёмы; порядок этапов разумен, но подстраивай под задачу, а не наоборот.
+
+## Когда применять — и когда нет
+
+Одна нетривиальная задача: спека/issue + реализация + проверка. Признаки
+«за»: правки в нескольких файлах с тестами, цена ошибки заметна, пользователь
+хочет след (задача-файл, ревью).
+
+**Не разворачивай конвейер на мелочь.** Косметика, пара часов работы, один
+файл — сделай сам: накладные расходы процесса многократно превысят цену
+работы (эмпирика 2026-07-06: на полировку ноутбука чуть не завели несколько
+issue; пользователь справедливо остановил). Очередь зависимых issue с
+автономным прогоном — это `/coordinator-loop`, не этот плейбук.
+
+## Роли
+
+- **Оркестратор (ты)** — план, постановка, синтез, коммит. Работай по
+  **индексу** (правило `/coordinator-loop`): в твой контекст входят вердикты
+  и находки `файл:строка`, а не diff, не полные логи и не нарратив. Шумные
+  команды — через файл-лог, в контекст только сводку.
+- **Codex** — реализация кода. У пользователя лимиты Codex больше, код он
+  пишет в целом лучше, но верхнеуровнево планирует хуже — поэтому
+  декомпозиция и постановка остаются у тебя. Механика вызова —
+  [references/codex-companion.md](references/codex-companion.md).
+- **Ревьюеры** — два, **разных родословных**, слепые друг к другу:
+  Claude-субагент (adversarial-reviewer, **на Опусе** — экономия лимитов) и
+  Codex **свежим тредом** (не тем, что писал код). Разные родословные ловят
+  непересекающиеся классы находок — это центральная находка и
+  `/coordinator-loop` (кросс-линия), и прогона 2026-07-06 (Клод подтвердил
+  математику и краевые случаи, Кодекс нашёл дыры в тестах). Нет типа
+  `adversarial-reviewer` в среде — возьми `general-purpose` со скептическим
+  промптом и запретом менять репозиторий (мандат промптом, не урезанием).
+- **Свежесть**: ревьюеров запускай свежими сессиями, без форка своей истории
+  (форк тратит токены и убивает независимость). Повторную проверку точечных
+  правок — **тем же** ревьюером узким вопросом «закрывают ли правки твои
+  находки», не полным обходом.
+- **Вспомогательные Claude-субагенты** для попутного делегирования: глубокое
+  рассуждение — `deep-reasoner`, механика с шумным выводом — `fast-worker`.
+  Они репо-локальные; нет в репозитории — определения для создания в
+  [references/claude-agents.md](references/claude-agents.md).
+
+## Конвейер
+
+1. **Постановка — самодостаточный файл-задача.** У исполнителя нет твоего
+   контекста; всё нужное — в файле: цель, критерии приёмки чекбоксами,
+   границы («что трогать нельзя»), «сначала прочитать» (спека, ADR, README с
+   командами), команды проверки. Формат и место — по конвенции репозитория
+   (например, `.scratch/<feature>/issues/`). Готово, когда исполнитель может
+   сделать задачу, не задав тебе ни одного вопроса.
+2. **Свежий взгляд на постановку — до реализации.** Адверсарный ревьюер без
+   твоего контекста проверяет задачу против кода: фактические ошибки, скрытые
+   решения-«однострочники», недостающие критерии. Окупается: ловит блокеры,
+   которые исполнитель молча реализовал бы (эмпирика: «русские названия из
+   `name_ru`» — а в данных `name_ru` английский). Этап закрыт, когда каждая
+   находка внесена в задачу **решением** или письменно отклонена — «пусть
+   решит исполнитель» решением не считается.
+3. **Реализация Кодексом.** Промпт: «задача самодостаточна, следуй буквально,
+   коммит не делай». Запуск — **раннером-субагентом** (приём из
+   `/adversarial-review`: раннеру — готовую команду, шум остаётся у него,
+   монитор не нужен) либо companion-CLI напрямую; рецепты и ловушки —
+   [references/codex-companion.md](references/codex-companion.md).
+   Один писатель в дереве: пока Codex пишет — никто больше (казус с
+   форвардером — в [references/lessons.md](references/lessons.md)). Готово,
+   когда Codex вернул отчёт, а в дереве нет правок, которых он не называл.
+4. **Два слепых ревью параллельно.** Каждому: путь к задаче-файлу + фокус
+   (математика/краевые случаи, соответствие критериям, честность тестов,
+   артефакты). Друг про друга не знают, твои выводы им не пересказывай.
+   Клод-ревьюеру можно поручить смотреть артефакты (картинки из ноутбука).
+   Этап закрыт, когда оба вердикта у тебя индексами.
+5. **Синтез и триаж.** Сведи вердикты по индексам: пересечения, противоречия.
+   Пофиндинговый триаж — у **исполнителя**, не у тебя (правило
+   `/claude-team-review` и `/coordinator-loop`: судит тот, у кого контекст
+   кода): перешли Codex индекс находок **дословно**, он чинит или
+   **аргументированно отклоняет** — через контракт и тест, не голословно;
+   промпт починки — «закрой перечисленное, больше ничего не меняй». Ты судишь
+   уровнем задачи: принять риск / вне скоупа. Повторная проверка — узкая
+   (см. «Свежесть»). Этап закрыт, когда по каждой находке обоих ревью есть
+   решение: починено и перепроверено — или отклонено с доводом.
+6. **Финал.** Артефакты проверь **своими глазами** (счётчик тестов, картинки,
+   прогон CLI) — ревью не заменяет твою приёмку. Обнови чекбоксы и статус
+   задачи-файла, коммит — по `/conventional-commits`, пользователю — выжимку:
+   вердикты, что принято/отклонено, что осталось. Готово, когда чекбоксы
+   проставлены, дерево чистое после коммита и пользователь получил отчёт.
+
+## Пользователь в петле
+
+В отличие от `/coordinator-loop`, здесь пользователь рядом: докладывай в чат
+короткие статусы на границах этапов (постановка готова, ревью пришло,
+вердикты сведены), решения по скоупу оставляй ему. Фоновые этапы будят тебя
+сами — не поллинг вручную, а фоновый монитор + уведомления
+(механика — [references/codex-companion.md](references/codex-companion.md)).
+
+## Соседние скиллы
+
+- `/coordinator-loop` — автономный цикл очереди issue на стороне Codex
+  (координатор в Codex, worker'ы — его субагенты). Выстрадан и отлажен;
+  словарь (индекс, свежие сессии, две ручки стоимости) — общий.
+- `/claude-team-review` — ревью-петля, где лид сам чинит код.
+- `/adversarial-review` — разовое адверсарное ревью Кодексом.
+- `/conventional-commits` — формат коммита на финале.
+
+## Подробнее
+
+- [references/codex-companion.md](references/codex-companion.md) — команды
+  companion-CLI, мониторинг, ловушки (read-only без `--write`, форвардер,
+  idle-уведомления фоновых агентов).
+- [references/lessons.md](references/lessons.md) — датированная эмпирика
+  прогонов: что поймал каждый этап, казусы, цифры.
+- [references/claude-agents.md](references/claude-agents.md) — определения
+  репо-локальных субагентов `deep-reasoner`/`fast-worker` и конструкция
+  оркестрации из CLAUDE.md — воссоздать в новом репозитории.
@@ -0,0 +1,64 @@
+# Handoff: рождение скилла claude-subagent-playbook и что в нём не проверено
+
+Дата: 2026-07-06. Для сессии, которая будет развивать сам скилл (не МЛ-задачу).
+
+## Состояние
+
+- Скилл собран и готов к вызову: источник —
+  `~/dotfiles/agents/.agents/skills/claude-subagent-playbook/` (в git dotfiles
+  ещё не закоммичен), зеркало — `~/.claude/skills/claude-subagent-playbook/`.
+  Состав: SKILL.md + references/{codex-companion,lessons,claude-agents}.md.
+- Собран по итогам одного боевого прогона (задача 05 «полировка витрины» в
+  `~/sources/t2-ml-forecast`, коммит 880d506) — но сам прогон шёл ДО оформления
+  скилла. **Скилл ни разу не исполнялся по своему письменному тексту.**
+- Эмпирика прогона — в references/lessons.md (файл накопительный, дописывать
+  после каждого прогона). Память проекта t2-ml-forecast тоже знает о скилле:
+  `~/.claude/projects/-home-ddmitry-sources-t2-ml-forecast/memory/`.
+
+## Дизайн-решения и их источники (не пересказ — только происхождение)
+
+- Форма «набор знаний, не жёсткий каркас» — явное требование пользователя;
+  жёсткий каркас уже есть у `/coordinator-loop` (очередь issue, сторона Codex).
+- Структура и словарь выверены по `/writing-great-skills`: user-invoked,
+  короткий description, completion criteria на шагах, ведущие слова общие с
+  coordinator-loop (индекс, родословная, свежесть).
+- Раннер-паттерн для вызова Codex — из `/adversarial-review`
+  (references/runner.md там — самый проработанный образец: двухканальный
+  протокол, результат файлом, ретраи). Добавлен по предложению пользователя.
+- Триаж находок исполнителем — из `/claude-team-review` и coordinator-loop
+  («судит тот, у кого контекст кода»). Тоже добавлен по замечанию пользователя.
+
+## Не проверено боем — проверять в следующих прогонах
+
+1. **Раннер с `task --wait`** — в прогоне 05 использовался `--background` +
+   bash-монитор, раннер не пробовали. Открытый риск: у Bash-вызова внутри
+   субагента потолок 10 минут (timeout max 600000 мс), а реализация у Codex
+   шла ~15 минут. Раннеру, видимо, нужна инструкция «по таймауту не падать, а
+   опрашивать `$CC status`/`result` до завершения». Обкатать и вписать в
+   references/codex-companion.md то, что реально сработало.
+2. **Триаж исполнителем** — в прогоне 05 триаж делал оркестратор (обе находки
+   принял сам). Формулировка «перешли индекс дословно, Codex чинит или
+   аргументированно отклоняет» — теория из соседних скиллов, не наша эмпирика.
+3. **Фолбэк ревьюера** (general-purpose со скептическим промптом при
+   отсутствии adversarial-reviewer) — не обкатан.
+4. **Порог «мелочь vs конвейер»** откалиброван по одному случаю — уточнять.
+5. **Чего в скилле осознанно нет** (кандидаты при развитии, не тащить без
+   нужды): журнала прогона (след живёт в задаче-файле — хватит ли на длинной
+   задаче?); узкого rerun-а ревьюера продолжением той же сессии (SendMessage —
+   в 05 не понадобился); ролей deep-reasoner в синтезе.
+
+## Ближайший боевой тест
+
+Регламент переобучения («выживаемость») в t2-ml-forecast — единственный
+незакрытый пункт Этапа 1 пилота, калибр подходящий. Вызвать
+`/claude-subagent-playbook` в свежей сессии и смотреть, где текст скилла
+расходится с практикой; расхождения — в lessons.md и правки SKILL.md.
+
+## Suggested skills
+
+- `/claude-subagent-playbook` — предмет работы; прогнать как написано.
+- `/writing-great-skills` — перед любыми правками структуры скилла.
+- `/adversarial-review` — образец раннера (references/runner.md) при обкатке
+  пункта 1.
+- `/handoff` — по завершении сессии развития обновить эту записку (или
+  положить рядом новую; старую можно удалить, если полностью поглощена).
@@ -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 минут; остальное — ревью и оркестрация. На мелочь такое не разворачивать.