dotfiles/agents/.agents/skills/claude-subagent-playbook/SKILL.md

---
name: claude-subagent-playbook
description: >-
  Конвейер одной нетривиальной задачи со стороны Claude Code — от
  постановки до приёмки через слепое ревью. Применяй, когда пользователь
  даёт issue/тикет в работу конвейером, просит делегировать реализацию
  Codex или устроить независимое ревью изменений.
---

# Плейбук: одна задача через Кодекса и слепое ревью

Ты ведешь задачу как координатор и несешь за нее ответственность: планируешь, ставишь задачу,
раздаёшь работу, синтезируешь, принимаешь результат. Реализацию без явной причины сам не пишешь.
Это оптика, а не обязательный конвейер: своё внимание держи для цели, ограничений, решений,
рисков и приёмки — субагенты выясняют и выполняют, решаешь ты. Порядок
этапов разумен, но подстраивай его под задачу, а не наоборот.

## Когда применять — и когда нет

Одна нетривиальная задача: спека/issue + реализация + проверка. Признаки
«за»: правки в нескольких файлах с тестами, цена ошибки заметна, пользователь
хочет след (задача-файл, ревью).

**Не разворачивай конвейер на мелочь.** Косметика, один
файл — сделай сам: накладные расходы процесса многократно превысят цену
работы.

## Роли

- **Оркестратор (ты)** — план, постановка, синтез, коммит. Принцип:
  **мастер решает — субагенты выясняют**; твой контекст — самый дорогой
  ресурс, в него входят решения, вердикты и находки `файл:строка` — не
  diff, не полные логи, не нарратив. Работу с неизвестным заранее объёмом
  вывода (диагноз падения, исследование гипотезы, серия экспериментов,
  чтение логов) отдавай субагенту **до её начала**: изнутри она всегда
  выглядит «ещё на один шаг». Стоп-кран: **сам — максимум один заход**
  (одна команда с коротким выводом по единственной гипотезе); не
  подтвердилось — делегируй. Перед запуском любого субагента назови его
  вклад: защита контекста, свежий взгляд, специализация, параллельность
  или отдельная среда; не можешь назвать — делай сам или продолжай
  существующий тред. Механику (правки файлов по готовым решениям,
  скрипты, вёрстку) — `fast-worker`'у: твоё в них только короткий список
  решений. **Индекс — у тебя, полезная нагрузка — файлами между
  агентами**: вердикты, отчёты и промпты живут в `$SCRATCH` и ведутся
  **на английском**; русский — только тому, что уходит в репозиторий и
  пользователю (конвенция каталога и языковой хвост — в
  [references/prompt-templates.md](references/prompt-templates.md)). Читай их один раз, дальше передавай путями и
  конкатенацией (`cat`), не переписывай Write'ом — каждое переписывание
  дублирует контент в твоём контексте. SendMessage возвращает эхом весь
  текст сообщения — teammate'у шли короткое (вердикт, путь, вопрос),
  длинное — файлом, который он прочтёт сам.
- **Исполнители** — двое; разрез между ними задаёт этап 1 по осям
  цена/интеллект/вкус
  ([references/model-matrix.md](references/model-matrix.md)). `craftsman`
  (Опус) — вкусовая часть; Codex — техническая: лимиты у него почти
  бесплатные, код пишет отлично, а верхнеуровнево планирует хуже —
  декомпозиция и постановка при любом разрезе остаются у тебя. Механика
  вызова Codex — [references/codex-exec.md](references/codex-exec.md).
- **Ревьюеры** — до двух линий (шкалы — этапы 2 и 4), слепых друг к
  другу. Назначение — по двум разным основаниям, это разные механизмы:
  **свежая сессия** (обязательна каждой линии; не форк твоей истории —
  форк убивает независимость) отвязывает от рассуждений автора;
  **семейство** (Claude/GPT) определяет, какие
  классы находок линия вообще видит (пересечение линий в прогонах — от
  нуля до пары тем). Линию дефектов веди семейством, отличным от
  исполнителя; линию уместности — моделью со вкусом, даже когда она из
  семейства автора: плата — общая слепота семейства проходит дважды, её
  гасят свежесть и другая линза, а при высокой цене ошибки уместность
  отдай третьей модели. Claude-линии — по карте: ревью постановок
  (high) штатно ведёт `deep-reasoner`, слепое ревью кода (medium) —
  `craftsman` свежей сессией (нет в репозитории — предложи создать по
  заготовке из
  [references/claude-agents.md](references/claude-agents.md); временный
  фолбэк — `deep-reasoner` ступенью выше). Codex-линия — **свежим
  тредом**, не тем, что писал код. Обоим — руки: тесты, гипотезы, поиск,
  документация, первоисточники; запрет менять исходники и окружение —
  **мандатом в промпте, не урезанием песочницы** (рецепт и подстраховка —
  [references/codex-exec.md](references/codex-exec.md)).
- **Перепроверка**: повторную проверку точечных правок — **тем же**
  ревьюером узким вопросом «закрывают ли правки твои находки», не полным
  обходом.
- **Пределы параллельности**: глубина один — субагенты не разворачивают
  собственных субагентов; параллельно только работа без конфликтующих
  входов и общего изменяемого состояния; второй обзор добавляй ради
  отдельной линии, а не ради свободного слота; у одного дерева один
  владелец — параллельная запись только разными worktree со швом по
  непересекающимся файлам.
- **Субагенты — по готовым определениям** из
  [references/claude-agents.md](references/claude-agents.md)
  (`deep-reasoner` — рассуждения и ревью постановок; `craftsman` —
  исполнение брифов: вкусовая реализация, слепое ревью, перепроверки;
  `fast-worker` — механика):
  ступень эффорта не задаётся в вызове (у Agent-тула такой ручки нет) —
  её **выбирают выбором агента**: модель и effort пришиты фронтматтером;
  разовый `general-purpose` приедет на эффорте сессии, а без явной
  модели субагент наследует Fable, чьи лимиты держи для оркестрации. Карта «роль → модель и
  ступень» и её основания — там же. Нет определений в репозитории —
  **предложи пользователю создать** (молча не заводить:
  `.claude/agents/` — территория пользователя). Эскалация: не хватило
  глубины — выше effort, не хватает суждения — выше модель; после двух
  слабых результатов подряд — свежий более сильный агент, не перенос
  неудачного контекста. Внутри одного агента effort между резюмами не
  менять (сбрасывает messages-ярус кэша). Никакой эффорт не страхует от
  уверенной выдумки внешних фактов — проверяй первоисточником.

## Конвейер

1. **Постановка — самодостаточный файл-задача.** У исполнителя нет твоего
   контекста; всё нужное — в файле: цель, критерии приёмки чекбоксами,
   границы («что трогать нельзя»), «сначала прочитать» (спека, ADR, README с
   командами), команды проверки. Разбиение крупнее одного тикета веди по
   критериям `/to-tickets` — и его руками, если подключён (настройка —
   `/setup-matt-pocock-skills`, конвенции трекера — в `docs/agents/`):
   тикет — вертикальный срез, демонстрируемый сам по себе; влезает в один
   свежий контекст; рёбра блокировок явные. Мерка самодостаточности —
   тикет можно взять в отдельной сессии вообще без общего контекста.
   Сверка разбиения с пользователем внутри `/to-tickets` — уже первая
   линия ревью постановки, засчитай её на этапе 2. Здесь же — разрез
   исполнителей по подзадачам (ось вкуса —
   [references/model-matrix.md](references/model-matrix.md)): что человек
   будет читать и разбирать — вкусовой части (Опус), руки — Кодексу.
   Сначала вкусовая часть: она задаёт форму, имена и границы, под
   которые механическая подстраивается, — обратный порядок даёт ретрофит;
   параллелить части — только в рамках «Пределов параллельности».
   Формат и место — по
   конвенции репозитория (например, `.scratch/<feature>/issues/` или
   трекер из `docs/agents/`). Не хватает
   фактуры по внешним библиотекам/API — сначала `/research` и Context7 MCP,
   выжимку — в
   «сначала прочитать». Задача просится под test-first — сошлись в ней на
   `/tdd` (скиллы у Codex те же — общий каталог), ключевые требования
   продублируй текстом. Готово, когда исполнитель в свежей сессии может
   сделать задачу, не задав тебе ни одного вопроса.
2. **Свежий взгляд на постановку — до реализации, по шкале и один раз.**
   Правило: **одно ревью на версию артефакта**, а не на каждую передачу из
   рук в руки — спека ревьюится при принятии, разбиение — сверкой с
   пользователем в `/to-tickets`, тикет — здесь; отревьюенный и не
   изменившийся тикет перед выполнением заново не ревьюится и целиком в
   твой контекст не перечитывается (передавай номером/путём — исполнитель
   прочтёт сам), после правок — узкая проверка дельты тем же ревьюером.
   Шкала: тикет-срез по уже принятой спеке, без решений сверх неё —
   внешнюю линию пропусти, причину назови одной фразой; обычный тикет —
   ревьюер роли постановок (`deep-reasoner`) без
   твоего контекста проверяет задачу против кода: фактические ошибки, скрытые
   решения-«однострочники», недостающие критерии —
   ловит блокеры, которые исполнитель молча реализовал бы. Постановка
   крупная или
   цена ошибки высока — сделай ревью двойным и слепым, как для кода: вторая
   линия — Codex свежим тредом с явной рамкой «ревьюируй постановку, не
   реализацию; детали реализации — только если постановка молча предрешает
   решение» (без рамки зарывается в детали). Семейства и тут ловят разное:
   Codex — уровень требований (недостающие критерии, наблюдаемость,
   «формально отчитаться можно»), Клод — механику кода (нереализуемые
   формулировки, мёртвые стабы). Этап закрыт, когда каждая
   находка внесена в задачу **решением** или письменно отклонена — «пусть
   решит исполнитель» решением не считается; при пропуске внешней линии —
   когда причина пропуска названа.
3. **Реализация — по разрезу этапа 1.** Вкусовую часть пишет
   `craftsman` свежей сессией, техническую — Codex; у обоих один и тот же
   файл задачи, промпт — скелет из
   [references/prompt-templates.md](references/prompt-templates.md)
   (мандат «следуй буквально, коммит не делай» уже в нём). Запуск
   Codex — прямым `codex exec` **фоновым Bash оркестратора**: шум —
   редиректами в файлы, в контекст читается только файл отчёта, харнесс
   будит по завершении; рецепты, ветки и ловушки —
   [references/codex-exec.md](references/codex-exec.md).
   Пока исполнитель пишет — дерево его («Пределы параллельности»; казус
   форвардера — в архиве уроков, запись 2026-07-06).
   После отчёта — **саморевью тем же тредом** (resume, effort medium;
   файл готов в `prompts/`):
   исполнитель проходит свой diff против критериев как ревьюер и сам чинит
   найденное, тебе — одна строка «found N, fixed N». Дёшево и снимает часть
   находок до внешних глаз. Готово, когда каждый исполнитель вернул отчёт
   и саморевью, в дереве нет правок, которых отчёты не называли,
   и дешёвая сквозная проверка (если она есть в репо) зелёная: гонял её
   исполнитель по промпту, а если ему она недоступна (docker, стенд) — ты,
   **до запуска ревьюеров**: иначе ревью уйдёт на код, который сквозной
   прогон ещё поменяет.
4. **Ревью реализации — по шкале риска.** Саморевью уже пройдено (этап 3);
   дальше по цене ошибки: **тривиальное** изменение (до-правка по готовому
   диагнозу, механика, целиком накрытое детерминированной проверкой) —
   внешних линий не гоняй, причину пропуска назови одной фразой;
   **простое, но с заметной ценой ошибки** — один ревьюер семейства,
   отличного от исполнителя (линза — `line-rev`, обе в одной); **обычное
   и сложнее** — два слепых ревью параллельно с разведёнными фокусами:
   линию «по задаче» (`line-task` + `line-taste`: постановка, критерии,
   границы, уместность и вкус) ведёт модель со вкусом, линию «по коду»
   (`line-code`: корректность, инварианты, регрессии, честность
   тестов) — семейство, отличное от исполнителя (основания — «Роли»).
   Разность семейств даёт разные находки, разность фокусов страхует от
   дублирования, когда семейства сходятся; артефакты-картинки (ноутбуки,
   графики) видит только Claude-линия — учитывай при назначении. Сборка
   промптов и обёртки вызова — целиком в
   [references/prompt-templates.md](references/prompt-templates.md); два
   правила при этом твои: пути промптов и вердиктов у линий разные, и
   текст промпта в параметр вызова не дублируй — это второй полный
   экземпляр в твоём контексте. Друг про друга линии не знают, твои
   выводы им не пересказывай. Живой стенд двум линиям не давай: их
   стражи гасят службы и роняют таблицы друг другу — стенд получает одна
   линия, второй — явный запрет ломающих команд. Idle-уведомления
   Клод-ревьюера результата не содержат — итог придёт строкой VERDICT и
   файлом по пути из обёртки. После
   ревью сверь дерево (`git status`). Этап закрыт, когда вердикты всех
   выбранных линий у тебя индексами и дерево нетронуто; вердикт без единой находки засчитывай
   только после проверки его лога — работа, не отписка
   (приём — в [references/codex-exec.md](references/codex-exec.md)).
5. **Синтез и триаж.** Сведи вердикты по индексам: пересечения,
   противоречия. Линии не сливай в один ранжир: оси разведены намеренно,
   уверенный вердикт одной (APPROVED без находок) не закрывает находки
   другой.
   Пофиндинговый триаж — у **исполнителя**, не у тебя (правило
   `/claude-team-review`: судит тот, у кого контекст
   кода): перешли Codex индекс находок **дословно**, он чинит или
   **аргументированно отклоняет** — через контракт и тест, не голословно;
   промпт починки — «закрой перечисленное, больше ничего не меняй».
   «Дословно» — это конкатенация: `cat triage-header.md
   review-impl-codex.md review-impl-claude.md > fix-prompt.md` Bash'ем
   (шапка готова в
   `references/prompts/`); Write'ом ты бы переписал те же находки в
   контекст ещё раз. Статус каждого ID — `FIXED / REJECTED / OUT_OF_SCOPE /
   NEEDS_DECISION`; два последних — решения твоего уровня, исполнитель
   возвращает их тебе, а не решает молча. Резолюции и доводы он пишет в
   свой файл отчёта, **тикет в триаже не правится**: правка тикета эхом
   вкатывает весь его текст в твой контекст — главный пожиратель
   прогонов; выжимку в тикет перенесёт fast-worker на финале. Свои замечания к
   триажу — только шапкой. Ты судишь уровнем задачи: принять риск / вне
   скоупа. Повторная проверка — узкая (см. «Перепроверка»); её промпт не
   пересказывает резолюции — ссылается на файл отчёта исполнителя.
   Третий круг триажа — точка вмешательства: доложи пользователю, почему
   процесс не сходится и что меняешь (постановку, модель/effort,
   исполнителя, границы); пятый не начинай без явного решения. Повторно
   поднятая уже отклонённая находка — спор: отдельная узкая проверка
   усиленным уровнем, не новый общий круг. Этап закрыт, когда у каждого ID
   обоих ревью есть статус: FIXED и перепроверен, REJECTED с доводом, либо
   OUT_OF_SCOPE / NEEDS_DECISION закрыт твоим решением.
6. **Финал.** В доказательства углубляйся постепенно: состав изменений и
   сводки ревью → отдельные спорные фрагменты → полный diff, только когда
   он ограничен и нужен для решения; зелёный журнал не читай, красный
   отдай исполнителю или разборщику; проверку, доступную только агенту в
   спецсреде, называй косвенным свидетельством. Ключевые артефакты проверь
   **своими глазами** (счётчик тестов, картинки, прогон CLI) — ревью не
   заменяет твою приёмку. Команды нового приёмочного сценария проверь на
   живом объекте до полного прогона; сложные вставки собирай файлами, не
   экранированием; фоновой команде, которой нечего читать со входа,
   закрывай stdin (`< /dev/null`) — команда, дочитывающая ввод, из
   терминала зелёная, а в фоне виснет навсегда. Чекбоксы, статус и
   выжимку резолюций в тикет переносит fast-worker из файла отчёта
   исполнителя (не твой Write).
   Коммит — по `/conventional-commits`, пользователю — выжимка: вердикты,
   что принято/отклонено, что осталось — плюс короткая саморефлексия: что
   больше всего потратило контекст и что в следующий раз направить файлом
   или субагентом (метрика: каждый полный артефакт проходит через твой
   контекст не более одного раза). Готово, когда чекбоксы проставлены,
   дерево чистое после коммита и пользователь получил отчёт.

## Пользователь в петле

Здесь пользователь рядом: на границах
этапов давай в чат карту прогресса в 4–7 строк обычными словами
(✅ сделано / ▶ идёт / ⬜ дальше); термины плейбука — только с
расшифровкой: телеграфные статусы в терминах этапов теряют пользователя.
Карта дополняет содержательную сводку, не заменяет её.
Решения по скоупу оставляй пользователю — и неси их так, чтобы решение
можно было принять, не держа код в голове: в чём выбор, чем платит каждый
вариант, что предлагаешь ты и почему. Сжатая до одной строки развилка
экономит твой контекст за счёт чужого решения. Фоновые этапы будят тебя
сами — не поллинг вручную, а отслеживаемые фоновые процессы + уведомления
(механика — [references/codex-exec.md](references/codex-exec.md)).
Подстраховка от молчаливой смерти агента — ScheduleWakeup сроком дольше
ожидаемой длительности: по пробуждению смотри логи сам, по приходу
результата таймер снимай; промпт будильника — одна короткая строка,
план не пересказывай (он живёт в разговоре). Idle-уведомления
teammate-субагентов — шум, а не событие: не докладывай о них пользователю
и не действуй по ним, если результат уже получен.

## Сбои координации

- Нет ожидаемого файла или отчёта: один запрос короткого итога в тот же
  тред; повторная тишина — свежий агент от сохранённых артефактов, владение
  деревом — только после остановки прежнего владельца. Молчание — не
  смерть: признак жизни — уведомление харнесса, не размер транскрипта;
  замене давай **другой** путь вердикта — дубль на тот же путь затирает
  находки живого.
- Отчёт агента о состоянии среды — не факт: перед приёмкой посмотри стенд
  своими глазами (`docker compose ps -a`; без `-a` погашенные службы
  невидимы).
- Длинный рассказ пришёл сообщением: попроси сводку с путём к файлу,
  рассказ дальше не переноси.
- Два писателя пересеклись в дереве: стоп обоим, назначь одного владельца,
  продолжай от проверенного состояния; чужие правки не откатывай не
  разобравшись.
- После финала удали обменный каталог прогона: долговечно только то, что
  предусмотрено проектом (тикет, коммит, lessons).

## Соседние скиллы

- `/claude-team-review` — ревью-петля, где лид сам чинит код (живёт
  отдельным репозиторием, в среде может быть не подключён).
- `codex-subagent-playbook` — близнец этого плейбука для координатора на
  стороне Codex; скрыт от автовызова, зови по имени.
- `/to-tickets` — разбиение на тикеты-срезы с рёбрами блокировок (этап 1);
  его сверка разбиения с пользователем — первая линия ревью постановки.
- `/tdd` — дисциплина test-first: для задач-мелочей, которые делаешь сам,
  и как словарь для test-first-постановки (этап 1).
- `/research` — фоновое исследование первоисточников с выжимкой-файлом;
  кормит «сначала прочитать» постановки (этап 1).
- `/conventional-commits` — формат коммита на финале.

## Подробнее

- [references/codex-exec.md](references/codex-exec.md) — прямой `codex exec`:
  сквозные правила (шум в файлы, thread_id, resume по id, проверка отписки),
  ветки исполнитель/ревьюер/триаж, раннер для переваривания шума.
- [references/prompt-templates.md](references/prompt-templates.md) — сборка
  промптов: готовые boilerplate-файлы в `references/prompts/` подшиваются
  `cat`'ом из каталога скилла, Write'ом пишутся только параметрические
  блоки.
- [references/model-matrix.md](references/model-matrix.md) — оси
  цена/интеллект/вкус: матрица моделей и правила применения (разрез
  этапа 1, назначение линий этапа 4).
- [references/lessons.md](references/lessons.md) — датированная эмпирика
  прогонов: что поймал каждый этап, казусы, цифры.
- [references/claude-agents.md](references/claude-agents.md) — определения
  репо-локальных субагентов (`deep-reasoner`, `craftsman`,
  `fast-worker`), карта «роль → модель и ступень» и конструкция
  оркестрации из CLAUDE.md — воссоздать в новом репозитории.