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 минут; остальное — ревью и оркестрация. На мелочь такое не разворачивать.