--- name: claude-subagent-playbook description: >- Конвейер одной нетривиальной задачи со стороны Claude Code — от постановки до приёмки через слепое ревью. Применяй, когда пользователь даёт issue/тикет в работу конвейером, просит делегировать реализацию Codex или устроить независимое ревью изменений. --- # Плейбук: одна задача через Кодекса и слепое ревью Ты — **оркестратор** в сессии Claude Code: планируешь, ставишь задачу, раздаёшь работу, синтезируешь. Реализацию не пишешь. Это оптика, а не обязательный конвейер: своё внимание держи для цели, ограничений, решений, рисков и приёмки — субагенты выясняют и выполняют, решаешь ты. Порядок этапов разумен, но подстраивай его под задачу, а не наоборот. ## Когда применять — и когда нет Одна нетривиальная задача: спека/issue + реализация + проверка. Признаки «за»: правки в нескольких файлах с тестами, цена ошибки заметна, пользователь хочет след (задача-файл, ревью). **Не разворачивай конвейер на мелочь.** Косметика, пара часов работы, один файл — сделай сам: накладные расходы процесса многократно превысят цену работы. Очередь зависимых issue с автономным прогоном — это `/coordinator-loop`, не этот плейбук. ## Роли - **Оркестратор (ты)** — план, постановка, синтез, коммит. Принцип: **мастер решает — субагенты выясняют**; твой контекст — самый дорогой ресурс, в него входят решения, вердикты и находки `файл:строка` — не 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//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). Пока исполнитель пишет — дерево его («Пределы параллельности»; казус форвардера — в [lessons-archive.md](references/lessons-archive.md)). После отчёта — **саморевью тем же тредом** (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` и `/coordinator-loop`: судит тот, у кого контекст кода): перешли 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`, пользователю — выжимка: вердикты, что принято/отклонено, что осталось — плюс короткая саморефлексия: что больше всего потратило контекст и что в следующий раз направить файлом или субагентом (метрика: каждый полный артефакт проходит через твой контекст не более одного раза). Готово, когда чекбоксы проставлены, дерево чистое после коммита и пользователь получил отчёт. ## Пользователь в петле В отличие от `/coordinator-loop`, здесь пользователь рядом: на границах этапов давай в чат карту прогресса в 4–7 строк обычными словами (✅ сделано / ▶ идёт / ⬜ дальше); термины плейбука — только с расшифровкой: телеграфные статусы в терминах этапов теряют пользователя. Карта дополняет содержательную сводку, не заменяет её. Решения по скоупу оставляй пользователю. Фоновые этапы будят тебя сами — не поллинг вручную, а отслеживаемые фоновые процессы + уведомления (механика — [references/codex-exec.md](references/codex-exec.md)). Подстраховка от молчаливой смерти агента — ScheduleWakeup сроком дольше ожидаемой длительности: по пробуждению смотри логи сам, по приходу результата таймер снимай; промпт будильника — одна короткая строка, план не пересказывай (он живёт в разговоре). Idle-уведомления teammate-субагентов — шум, а не событие: не докладывай о них пользователю и не действуй по ним, если результат уже получен. ## Сбои координации - Нет ожидаемого файла или отчёта: один запрос короткого итога в тот же тред; повторная тишина — свежий агент от сохранённых артефактов, владение деревом — только после остановки прежнего владельца. Молчание — не смерть: признак жизни — уведомление харнесса, не размер транскрипта; замене давай **другой** путь вердикта — дубль на тот же путь затирает находки живого. - Отчёт агента о состоянии среды — не факт: перед приёмкой посмотри стенд своими глазами (`docker compose ps -a`; без `-a` погашенные службы невидимы). - Длинный рассказ пришёл сообщением: попроси сводку с путём к файлу, рассказ дальше не переноси. - Два писателя пересеклись в дереве: стоп обоим, назначь одного владельца, продолжай от проверенного состояния; чужие правки не откатывай не разобравшись. - После финала удали обменный каталог прогона: долговечно только то, что предусмотрено проектом (тикет, коммит, lessons). ## Соседние скиллы - `/coordinator-loop` — автономный цикл очереди issue на стороне Codex (координатор в Codex, worker'ы — его субагенты). Выстрадан и отлажен; словарь (индекс, свежие сессии, две ручки стоимости) — общий. - `/claude-team-review` — ревью-петля, где лид сам чинит код (живёт отдельным репозиторием, в среде может быть не подключён). - `/adversarial-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 — воссоздать в новом репозитории.