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

name, description

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

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

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

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

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

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

Роли

• Оркестратор (ты) — план, постановка, синтез, коммит. Принцип: мастер решает — субагенты выясняют; твой контекст — самый дорогой ресурс, в него входят решения, вердикты и находки файл:строка — не diff, не полные логи, не нарратив. Работу с неизвестным заранее объёмом вывода (диагноз падения, исследование гипотезы, серия экспериментов, чтение логов) отдавай субагенту до её начала: изнутри она всегда выглядит «ещё на один шаг». Стоп-кран: сам — максимум один заход (одна команда с коротким выводом по единственной гипотезе); не подтвердилось — делегируй. Перед запуском любого субагента назови его вклад: защита контекста, свежий взгляд, специализация, параллельность или отдельная среда; не можешь назвать — делай сам или продолжай существующий тред. Механику (правки файлов по готовым решениям, скрипты, вёрстку) — fast-worker'у: твоё в них только короткий список решений. Индекс — у тебя, полезная нагрузка — файлами между агентами: вердикты, отчёты и промпты живут в $SCRATCH (обменный temp-каталог прогона — скретчпад сессии или mktemp -d; детали — в references/prompt-templates.md) и ведутся на английском — проект их не хранит, а кириллица в 1,5–2 раза дороже по токенам; русский — только тому, что уходит в репозиторий и пользователю. Читай их один раз, дальше передавай путями и конкатенацией (cat), не переписывай Write'ом — каждое переписывание дублирует контент в твоём контексте. SendMessage возвращает эхом весь текст сообщения — teammate'у шли короткое (вердикт, путь, вопрос), длинное — файлом, который он прочтёт сам.
• Codex — реализация кода. У пользователя лимиты Codex больше, код он пишет в целом лучше, но верхнеуровнево планирует хуже — поэтому декомпозиция и постановка остаются у тебя. Механика вызова — references/codex-exec.md.
• Ревьюеры — до двух (шкалы — этапы 2 и 4), разных родословных, слепые друг к другу: Claude-субагент (adversarial-reviewer; нет в среде — deep-reasoner или скептический general-purpose) и Codex свежим тредом, не тем, что писал код. Разные родословные ловят разные классы находок (пересечение в прогонах — от нуля до пары тем). Обоим — руки: тесты, гипотезы, поиск, документация, первоисточники; запрет менять исходники и окружение — мандатом в промпте, не урезанием песочницы (рецепт и подстраховка — references/codex-exec.md).
• Свежесть: ревьюеров запускай свежими сессиями, без форка своей истории (форк тратит токены и убивает независимость). Повторную проверку точечных правок — тем же ревьюером узким вопросом «закрывают ли правки твои находки», не полным обходом.
• Пределы параллельности: глубина один — субагенты не разворачивают собственных субагентов; параллельно только работа без конфликтующих входов и общего изменяемого состояния; второй обзор добавляй ради отдельной линии, а не ради свободного слота; реализацию и починку одного дерева веди последовательно одним владельцем.
• Вспомогательные Claude-субагенты для попутного делегирования: глубокое рассуждение — deep-reasoner, механика с шумным выводом — fast-worker. Они репо-локальные; нет в репозитории — определения для создания в references/claude-agents.md.
• Модель Claude-субагентов задавай явно: Опус — рассуждения и ревью, Sonnet — механика. Без явной модели субагент наследует Fable, чьи лимиты самые дорогие — держи их для оркестрации (у deep-reasoner/fast-worker модели пришиты в определениях). Две ручки эскалации: не хватило глубины — повышай effort; не хватает качества суждения — повышай модель; после двух слабых результатов подряд — свежий более сильный агент вместо переноса неудачного контекста.
• Effort Claude-субагентов тоже задавай явно (решение пользователя 2026-07-21), по цене тихой ошибки этапа, не по сложности: xhigh — ревью постановок и планов (дефект каскадирует: отравляет реализацию, оба ревью и триаж — казус CODE-1 в xray-proxy 04); high — слепое ревью (последняя линия обороны своей линзы, пропуск тихий); medium/default — узкие перепроверки и механика (за ними приёмка оркестратора, ошибка громкая). Ревью ниже high не опускать даже при двух ревьюерах: линзы разные, избыточность — не дублирование. Внутри одного агента effort между резюмами не менять (у Claude смена thinking-конфига сбрасывает messages-ярус кэша; про effort не задокументировано — не рисковать). Ограничение любого эффорта: от уверенной выдумки внешних фактов (форматы артефактов, версии) не страхует — факты проверять отдельно.

Конвейер

1. Постановка — самодостаточный файл-задача. У исполнителя нет твоего контекста; всё нужное — в файле: цель, критерии приёмки чекбоксами, границы («что трогать нельзя»), «сначала прочитать» (спека, ADR, README с командами), команды проверки. Разбиение крупнее одного тикета веди по критериям /to-tickets — и его руками, если подключён (настройка — /setup-matt-pocock-skills, конвенции трекера — в docs/agents/): тикет — вертикальный срез, демонстрируемый сам по себе; влезает в один свежий контекст; рёбра блокировок явные. Мерка самодостаточности — тикет можно взять в отдельной сессии вообще без общего контекста. Сверка разбиения с пользователем внутри /to-tickets — уже первая линия ревью постановки, засчитай её на этапе 2. Формат и место — по конвенции репозитория (например, .scratch/<feature>/issues/ или трекер из docs/agents/). Не хватает фактуры по внешним библиотекам/API — сначала /research и Context7 MCP, выжимку — в «сначала прочитать». Задача просится под test-first — сошлись в ней на /tdd (скиллы у Codex те же — общий каталог), ключевые требования продублируй текстом. Готово, когда исполнитель в свежей сессии может сделать задачу, не задав тебе ни одного вопроса.
2. Свежий взгляд на постановку — до реализации, по шкале и один раз. Правило: одно ревью на версию артефакта, а не на каждую передачу из рук в руки — спека ревьюится при принятии, разбиение — сверкой с пользователем в /to-tickets, тикет — здесь; отревьюенный и не изменившийся тикет перед выполнением заново не ревьюится и целиком в твой контекст не перечитывается (передавай номером/путём — исполнитель прочтёт сам), после правок — узкая проверка дельты тем же ревьюером. Шкала: тикет-срез по уже принятой спеке, без решений сверх неё — внешнюю линию пропусти, причину назови одной фразой; обычный тикет — адверсарный ревьюер без твоего контекста проверяет задачу против кода: фактические ошибки, скрытые решения-«однострочники», недостающие критерии — ловит блокеры, которые исполнитель молча реализовал бы. Постановка крупная или цена ошибки высока — сделай ревью двойным и слепым, как для кода: вторая линия — Codex свежим тредом с явной рамкой «ревьюируй постановку, не реализацию; детали реализации — только если постановка молча предрешает решение» (без рамки зарывается в детали). Родословные и тут ловят разное: Codex — уровень требований (недостающие критерии, наблюдаемость, «формально отчитаться можно»), Клод — механику кода (нереализуемые формулировки, мёртвые стабы). Этап закрыт, когда каждая находка внесена в задачу решением или письменно отклонена — «пусть решит исполнитель» решением не считается; при пропуске внешней линии — когда причина пропуска названа.
3. Реализация Кодексом. Промпт: «задача самодостаточна, следуй буквально, коммит не делай». Запуск — прямым codex exec фоновым Bash оркестратора: шум — редиректами в файлы, в контекст читается только файл отчёта, харнесс будит по завершении; рецепты, ветки и ловушки — references/codex-exec.md. Один писатель в дереве: пока Codex пишет — никто больше (казус с форвардером — в references/lessons.md). После отчёта — саморевью тем же тредом (resume, effort medium; заготовка — references/prompt-templates.md): исполнитель проходит свой diff против критериев как ревьюер и сам чинит найденное, тебе — одна строка «found N, fixed N». Дёшево и снимает часть находок до внешних глаз. Готово, когда Codex вернул отчёт, саморевью пройдено, в дереве нет правок, которых он не называл, и дешёвая сквозная проверка (если она есть в репо) зелёная: гонял её исполнитель по промпту, а если ему она недоступна (docker, стенд) — ты, до запуска ревьюеров: иначе ревью уйдёт на код, который сквозной прогон ещё поменяет.
4. Ревью реализации — по шкале риска. Саморевью уже пройдено (этап 3); дальше по цене ошибки: тривиальное изменение (до-правка по готовому диагнозу, механика, целиком накрытое детерминированной проверкой) — внешних линий не гоняй, причину пропуска назови одной фразой; простое, но с заметной ценой ошибки — один ревьюер другой родословной, чем исполнитель (у нас — Клод при Codex-исполнителе; одиночную линию выбирай по родословной, не по цене); обычное и сложнее — два слепых ревью параллельно с разведёнными фокусами: одна линия «по задаче» (соответствие постановке, критериям, границам), другая «по коду» (корректность, инварианты, регрессии, честность тестов) — разность семейств даёт разные находки, разность фокусов страхует от дублирования, когда семейства сходятся. Промпт — общий блок один на обе линии плюс крошечный файл линии (линза и префикс ID); собираются два файла с разными путями (скелет и обёртки вызова — references/prompt-templates.md): Codex получает свой через stdin, Клод-субагенту в prompt — короткая обёртка «прочитай файл X и выполни; индекс — в файл Y» (не дублируй текст промпта в параметре — это второй полный экземпляр в твоём контексте). Содержание: путь к задаче-файлу + фокус и префикс ID линии; мандат, формат индекса с устойчивыми ID и поощрение эмпирических проверок уже в готовом boilerplate. Друг про друга не знают, твои выводы им не пересказывай. Вердикты — файлами с разными путями: у Codex это его -o-отчёт, Клод-ревьюеру путь и финальный акт (SendMessage только со строкой VERDICT, счётчиками и путём) задаёт готовая обёртка из шаблонов; его idle-уведомления результата не содержат, не жди из них ничего. После ревью сверь дерево (git status). Клод-ревьюеру можно поручить смотреть артефакты (картинки из ноутбука). Этап закрыт, когда вердикты всех выбранных линий у тебя индексами и дерево нетронуто; вердикт без единой находки засчитывай только после проверки его лога — работа, не отписка (приём — в references/codex-exec.md).
5. Синтез и триаж. Сведи вердикты по индексам: пересечения, противоречия. Пофиндинговый триаж — у исполнителя, не у тебя (правило /claude-team-review и /coordinator-loop: судит тот, у кого контекст кода): перешли Codex индекс находок дословно, он чинит или аргументированно отклоняет — через контракт и тест, не голословно; промпт починки — «закрой перечисленное, больше ничего не меняй». «Дословно» — это конкатенация: cat triage-header.md вердикт-A.md вердикт-B.md > fix-prompt.md Bash'ем (шапка готова в references/prompts/); Write'ом ты бы переписал те же находки в контекст ещё раз. Статус каждого ID — FIXED / REJECTED / OUT_OF_SCOPE / NEEDS_DECISION; два последних — решения твоего уровня, исполнитель возвращает их тебе, а не решает молча. Резолюции и доводы он пишет в свой файл отчёта, тикет в триаже не правится: правка тикета эхом вкатывает весь его текст в твой контекст (пожиратель №1 прогона задачи 13), выжимку в тикет перенесёт fast-worker на финале. Свои замечания к триажу — только шапкой. Ты судишь уровнем задачи: принять риск / вне скоупа. Повторная проверка — узкая (см. «Свежесть»); её промпт не пересказывает резолюции — ссылается на файл отчёта исполнителя. Третий круг триажа — точка вмешательства: доложи пользователю, почему процесс не сходится и что меняешь (постановку, модель/effort, исполнителя, границы); пятый не начинай без явного решения. Повторно поднятая уже отклонённая находка — спор: отдельная узкая проверка усиленным уровнем, не новый общий круг. Этап закрыт, когда у каждого ID обоих ревью есть статус: FIXED и перепроверен, REJECTED с доводом, либо OUT_OF_SCOPE / NEEDS_DECISION закрыт твоим решением.
6. Финал. В доказательства углубляйся постепенно: состав изменений и сводки ревью → отдельные спорные фрагменты → полный diff, только когда он ограничен и нужен для решения; зелёный журнал не читай, красный отдай исполнителю или разборщику; проверку, доступную только агенту в спецсреде, называй косвенным свидетельством. Ключевые артефакты проверь своими глазами (счётчик тестов, картинки, прогон CLI) — ревью не заменяет твою приёмку. Команды нового приёмочного сценария проверь на живом объекте до полного прогона; сложные вставки собирай файлами, не экранированием. Чекбоксы, статус и выжимку резолюций в тикет переносит fast-worker из файла отчёта исполнителя (не твой Write). Коммит — по /conventional-commits, пользователю — выжимка: вердикты, что принято/отклонено, что осталось — плюс короткая саморефлексия: что больше всего потратило контекст и что в следующий раз направить файлом или субагентом (метрика: каждый полный артефакт проходит через твой контекст не более одного раза). Готово, когда чекбоксы проставлены, дерево чистое после коммита и пользователь получил отчёт.

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

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

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

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

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

• /coordinator-loop — автономный цикл очереди issue на стороне Codex (координатор в Codex, worker'ы — его субагенты). Выстрадан и отлажен; словарь (индекс, свежие сессии, две ручки стоимости) — общий.
• /claude-team-review — ревью-петля, где лид сам чинит код (живёт отдельным репозиторием, в среде может быть не подключён).
• /adversarial-review — разовое адверсарное ревью Кодексом.
• /to-tickets — разбиение на тикеты-срезы с рёбрами блокировок (этап 1); его сверка разбиения с пользователем — первая линия ревью постановки.
• /tdd — дисциплина test-first: для задач-мелочей, которые делаешь сам, и как словарь для test-first-постановки (этап 1).
• /research — фоновое исследование первоисточников с выжимкой-файлом; кормит «сначала прочитать» постановки (этап 1).
• /conventional-commits — формат коммита на финале.

Подробнее

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