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

---
name: claude-subagent-playbook
disable-model-invocation: true
description: >-
  Конвейер одной задачи со стороны Claude Code: постановка → свежий взгляд →
  реализация Кодексом → слепое двойное ревью → синтез. Знания, не каркас.
---

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

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

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

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

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

## Роли

- **Оркестратор (ты)** — план, постановка, синтез, коммит. Работай по
  **индексу** (правило `/coordinator-loop`): в твой контекст входят вердикты
  и находки `файл:строка`, а не diff, не полные логи и не нарратив. Шумные
  команды — через файл-лог, в контекст только сводку. **Индекс — у тебя,
  полезная нагрузка — файлами между агентами**: вердикты, отчёты и промпты
  живут в `$SCRATCH` (обменный temp-каталог прогона с полуслучайным
  префиксом — скретчпад сессии или `mktemp -d`; детали — в
  [references/prompt-templates.md](references/prompt-templates.md)), ты
  читаешь их один раз и дальше передаёшь путями и конкатенацией (`cat`), а
  не переписываешь Write'ом — каждое переписывание дублирует контент в
  твоём контексте (ретро 2026-07-10: находки ревью проходили через
  оркестратора до шести раз). SendMessage возвращает эхом
  весь текст сообщения — teammate'у шли короткое (вердикт, путь, вопрос),
  длинное — файлом, который он прочтёт сам.
- **Codex** — реализация кода. У пользователя лимиты Codex больше, код он
  пишет в целом лучше, но верхнеуровнево планирует хуже — поэтому
  декомпозиция и постановка остаются у тебя. Механика вызова —
  [references/codex-exec.md](references/codex-exec.md).
- **Ревьюеры** — два, **разных родословных**, слепые друг к другу:
  Claude-субагент (`adversarial-reviewer`; нет в среде — скептический
  `general-purpose`) и Codex **свежим тредом**, не тем, что писал код.
  Разные родословные ловят непересекающиеся классы находок (пересечение в
  прогонах — стабильно ~ноль). Обоим — руки: тесты, гипотезы, поиск,
  документация, первоисточники; запрет менять исходники и окружение —
  **мандатом в промпте, не урезанием песочницы** (рецепт и подстраховка —
  [references/codex-exec.md](references/codex-exec.md)).
- **Свежесть**: ревьюеров запускай свежими сессиями, без форка своей истории
  (форк тратит токены и убивает независимость). Повторную проверку точечных
  правок — **тем же** ревьюером узким вопросом «закрывают ли правки твои
  находки», не полным обходом.
- **Вспомогательные Claude-субагенты** для попутного делегирования: глубокое
  рассуждение — `deep-reasoner`, механика с шумным выводом — `fast-worker`.
  Они репо-локальные; нет в репозитории — определения для создания в
  [references/claude-agents.md](references/claude-agents.md).
- **Модель Claude-субагентов задавай явно**: Опус — рассуждения и ревью,
  Sonnet — механика. Без явной модели субагент наследует Fable, чьи лимиты
  самые дорогие — держи их для оркестрации (у `deep-reasoner`/`fast-worker`
  модели пришиты в определениях).

## Конвейер

1. **Постановка — самодостаточный файл-задача.** У исполнителя нет твоего
   контекста; всё нужное — в файле: цель, критерии приёмки чекбоксами,
   границы («что трогать нельзя»), «сначала прочитать» (спека, ADR, README с
   командами), команды проверки. Формат и место — по конвенции репозитория
   (например, `.scratch/<feature>/issues/`; репозиторий настроен под скиллы
   Мэтта Покока — постановка через `/to-tickets` в сконфигурированный трекер:
   тикеты-срезы с рёбрами блокировок вместо ad-hoc файла, конвенции — в
   `docs/agents/`, настройка — `/setup-matt-pocock-skills`). Не хватает
   фактуры по внешним библиотекам/API — сначала `/research` и Context7 MCP,
   выжимку — в
   «сначала прочитать». Задача просится под test-first — сошлись в ней на
   `/tdd` (скиллы у Codex те же — общий каталог), ключевые требования
   продублируй текстом. Готово, когда исполнитель может сделать задачу,
   не задав тебе ни одного вопроса.
2. **Свежий взгляд на постановку — до реализации.** Адверсарный ревьюер без
   твоего контекста проверяет задачу против кода: фактические ошибки, скрытые
   решения-«однострочники», недостающие критерии. Окупается: ловит блокеры,
   которые исполнитель молча реализовал бы (эмпирика: «русские названия из
   `name_ru`» — а в данных `name_ru` английский). Постановка крупная или
   цена ошибки высока — сделай ревью двойным и слепым, как для кода: вторая
   линия — Codex свежим тредом с явной рамкой «ревьюируй постановку, не
   реализацию; детали реализации — только если постановка молча предрешает
   решение» (без рамки зарывается в детали). Родословные и тут ловят разное:
   Codex — уровень требований (недостающие критерии, наблюдаемость,
   «формально отчитаться можно»), Клод — механику кода (нереализуемые
   формулировки, мёртвые стабы; эмпирика 2026-07-10: пересечение — 2 темы
   из ~15). Этап закрыт, когда каждая
   находка внесена в задачу **решением** или письменно отклонена — «пусть
   решит исполнитель» решением не считается.
3. **Реализация Кодексом.** Промпт: «задача самодостаточна, следуй буквально,
   коммит не делай». Запуск — прямым `codex exec` **фоновым Bash
   оркестратора**: шум — редиректами в файлы, в контекст читается только
   файл отчёта, харнесс будит по завершении; рецепты, ветки и ловушки —
   [references/codex-exec.md](references/codex-exec.md).
   Один писатель в дереве: пока Codex пишет — никто больше (казус с
   форвардером — в [references/lessons.md](references/lessons.md)). Готово,
   когда Codex вернул отчёт, а в дереве нет правок, которых он не называл.
4. **Два слепых ревью параллельно.** Промпт — **один канонический файл в
   `$SCRATCH` на оба ревью** (скелет и обёртки вызова —
   [references/prompt-templates.md](references/prompt-templates.md)): Codex
   получает его через stdin, Клод-субагенту в prompt — короткая обёртка
   «прочитай файл X и выполни; индекс — в файл Y» (не дублируй текст
   промпта в параметре — это второй полный экземпляр в твоём контексте).
   Содержание: путь к задаче-файлу + фокус (математика/краевые случаи,
   соответствие критериям, честность тестов, артефакты). Друг про друга не
   знают, твои выводы им не пересказывай. Обоим поощряй безопасные
   эмпирические проверки (воспроизвести краевой случай вне репо, сходить в
   документацию) — вердикт заметно твёрже; менять исходники и окружение
   нельзя. Вердикты — файлами с **разными путями**: у Codex это его
   `-o`-отчёт, Клод-ревьюеру обёртка разрешает запись файла вердикта в
   `$SCRATCH` (вне репо — мандату не противоречит), финальным актом —
   SendMessage только со строкой VERDICT, счётчиками и путём: его
   idle-уведомления не содержат результата, не жди из них ничего. После
   ревью сверь дерево (`git status`). Клод-ревьюеру можно поручить смотреть
   артефакты (картинки из ноутбука). Этап закрыт, когда оба вердикта у тебя
   индексами и дерево нетронуто; вердикт без единой находки засчитывай
   только после проверки его лога — работа, не отписка
   (приём — в [references/codex-exec.md](references/codex-exec.md)).
5. **Синтез и триаж.** Сведи вердикты по индексам: пересечения, противоречия.
   Пофиндинговый триаж — у **исполнителя**, не у тебя (правило
   `/claude-team-review` и `/coordinator-loop`: судит тот, у кого контекст
   кода): перешли Codex индекс находок **дословно**, он чинит или
   **аргументированно отклоняет** — через контракт и тест, не голословно;
   промпт починки — «закрой перечисленное, больше ничего не меняй».
   «Дословно» — это конкатенация: `cat шапка.md вердикт-A.md вердикт-B.md >
   fix-prompt.md` Bash'ем; Write'ом ты бы переписал те же находки в контекст
   ещё раз. Свои замечания к триажу — только шапкой. Ты судишь уровнем
   задачи: принять риск / вне скоупа. Повторная проверка — узкая (см.
   «Свежесть»); её промпт не пересказывает резолюции — ссылается на файл
   отчёта исполнителя. Этап закрыт, когда по каждой находке обоих ревью есть
   решение: починено и перепроверено — или отклонено с доводом.
6. **Финал.** Артефакты проверь **своими глазами** (счётчик тестов, картинки,
   прогон CLI) — ревью не заменяет твою приёмку. Обнови чекбоксы и статус
   задачи-файла, коммит — по `/conventional-commits`, пользователю — выжимку:
   вердикты, что принято/отклонено, что осталось. Готово, когда чекбоксы
   проставлены, дерево чистое после коммита и пользователь получил отчёт.

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

В отличие от `/coordinator-loop`, здесь пользователь рядом: докладывай в чат
короткие статусы на границах этапов (постановка готова, ревью пришло,
вердикты сведены), решения по скоупу оставляй ему. Фоновые этапы будят тебя
сами — не поллинг вручную, а отслеживаемые фоновые процессы + уведомления
(механика — [references/codex-exec.md](references/codex-exec.md)).
Подстраховка от молчаливой смерти агента — ScheduleWakeup сроком дольше
ожидаемой длительности: по пробуждению смотри логи сам, по приходу
результата таймер снимай. Idle-уведомления teammate-субагентов — шум, а не
событие: не докладывай о них пользователю и не действуй по ним, если
результат уже получен (ретро 2026-07-10: ~7 пустых ходов на idle-пингах).

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

- `/coordinator-loop` — автономный цикл очереди issue на стороне Codex
  (координатор в Codex, worker'ы — его субагенты). Выстрадан и отлажен;
  словарь (индекс, свежие сессии, две ручки стоимости) — общий.
- `/claude-team-review` — ревью-петля, где лид сам чинит код (живёт
  отдельным репозиторием, в среде может быть не подключён).
- `/adversarial-review` — разовое адверсарное ревью Кодексом.
- `/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/lessons.md](references/lessons.md) — датированная эмпирика
  прогонов: что поймал каждый этап, казусы, цифры.
- [references/claude-agents.md](references/claude-agents.md) — определения
  репо-локальных субагентов `deep-reasoner`/`fast-worker` и конструкция
  оркестрации из CLAUDE.md — воссоздать в новом репозитории.