docs(skills): плейбук — структурный рефакторинг: ось вкуса, брифы, два Опус-агента

Зачем.
Отдельный осознанный заход, закрывающий открытые вопросы 2026-07-26 и
2026-07-31: две ручки выбора (модель, эффорт) были про силу, вкус ими не
выражался; константы линий дрейфовали через перепечатку; правила
координации прогона #18 жили только в журнале; у Agent-тула нет ручки
effort — карта была нереализуема разовым вызовом.

Что.
- Третья ось выбора — вкус: references/model-matrix.md (матрица Тео с
  поправкой пользователя под gpt-5.6-sol/Opus 5); разрез по подзадачам
  на этапе 1, сначала вкусовая часть.
- «Родословная» разведена на семейство (классы находок) и свежесть
  (независимость); линия дефектов — по различию, уместности — по умению.
- Ступень эффорта выбирается выбором агента: определений столько,
  сколько пар (модель, ступень) — deep-reasoner (high), craftsman
  (medium, исполнение брифов: реализация/ревью/перепроверки; поглотил
  adversarial-reviewer), fast-worker; карта с обоснованиями — SSOT в
  claude-agents.md.
- Константы — файлами в prompts/: line-task/code/rev, self-review;
  line-taste — вкусовая линза с 12 запахами Фаулера из /code-review.
- Правила #18 — в механизм: инкрементальная запись индекса, глубина
  один и проверка среды в мандате, признак жизни / другой путь вердикта
  замене / среда своими глазами в «Сбоях», стенд одной линии, stdin фона.
- lessons дистиллирован (586→533), handoff захода — в handoffs/.

Проверка.
Слепое ревью Опусом по writing-great-skills: CHANGES_REQUIRED
(7 MAJOR, 17 MINOR, 3 NIT) — все закрыты или отклонены с доводом в
lessons; ссылки пакета проверены скриптом, битых нет. Боевой прогон
новой структуры — следующим заходом (чек-лист в handoff).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Dmitry DementievandClaude Fable 5 committed 2026-07-31 17:03:23 +03:00
1 parent 6070810c2d
commit 3e0498e242
12 files changed
+466 -259

No files matched your search

@@ -1,11 +1,10 @@
---
name: claude-subagent-playbook
description: >-
Конвейер одной нетривиальной задачи со стороны Claude Code: постановка →
свежий взгляд → реализация Кодексом → слепое ревью по шкале риска →
триаж → приёмка. Применяй, когда пользователь даёт issue/тикет в работу
конвейером, просит делегировать реализацию Codex или устроить
независимое ревью изменений.
Конвейер одной нетривиальной задачи со стороны Claude Code — от
постановки до приёмки через слепое ревью. Применяй, когда пользователь
даёт issue/тикет в работу конвейером, просит делегировать реализацию
Codex или устроить независимое ревью изменений.
---
# Плейбук: одна задача через Кодекса и слепое ревью
@@ -43,76 +42,67 @@ description: >-
существующий тред. Механику (правки файлов по готовым решениям,
скрипты, вёрстку) — `fast-worker`'у: твоё в них только короткий список
решений. **Индекс — у тебя, полезная нагрузка — файлами между
агентами**: вердикты, отчёты и промпты живут в `$SCRATCH` (обменный
temp-каталог прогона — скретчпад сессии или `mktemp -d`; детали — в
[references/prompt-templates.md](references/prompt-templates.md)) и
ведутся **на английском** — проект их не хранит, а кириллица в 1,5–2
раза дороже по токенам; русский — только тому, что уходит в репозиторий
и пользователю. Читай их один раз, дальше передавай путями и
агентами**: вердикты, отчёты и промпты живут в `$SCRATCH` и ведутся
**на английском**; русский — только тому, что уходит в репозиторий и
пользователю (конвенция каталога и языковой хвост — в
[references/prompt-templates.md](references/prompt-templates.md)). Читай их один раз, дальше передавай путями и
конкатенацией (`cat`), не переписывай Write'ом — каждое переписывание
дублирует контент в твоём контексте. SendMessage возвращает эхом весь
текст сообщения — teammate'у шли короткое (вердикт, путь, вопрос),
длинное — файлом, который он прочтёт сам.
- **Codex** — реализация кода. У пользователя лимиты Codex больше, код он
пишет в целом лучше, но верхнеуровнево планирует хуже — поэтому
декомпозиция и постановка остаются у тебя. Механика вызова —
[references/codex-exec.md](references/codex-exec.md).
- **Ревьюеры** — до двух (шкалы — этапы 2 и 4), **разных родословных**, слепые
друг к другу:
Claude-субагент (`adversarial-reviewer`; нет в среде — `deep-reasoner`
или скептический `general-purpose`) и Codex **свежим тредом**, не тем,
что писал код.
Разные родословные ловят разные классы находок (пересечение в прогонах —
от нуля до пары тем). Обоим — руки: тесты, гипотезы, поиск,
- **Исполнители** — двое; разрез между ними задаёт этап 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)).
- **Свежесть**: ревьюеров запускай свежими сессиями, без форка своей истории
(форк тратит токены и убивает независимость). Повторную проверку точечных
правок — **тем же** ревьюером узким вопросом «закрывают ли правки твои
находки», не полным обходом.
- **Перепроверка**: повторную проверку точечных правок — **тем же**
ревьюером узким вопросом «закрывают ли правки твои находки», не полным
обходом.
- **Пределы параллельности**: глубина один — субагенты не разворачивают
собственных субагентов; параллельно только работа без конфликтующих
входов и общего изменяемого состояния; второй обзор добавляй ради
отдельной линии, а не ради свободного слота; реализацию и починку одного
дерева веди последовательно одним владельцем.
- **Вспомогательные Claude-субагенты** для попутного делегирования: глубокое
рассуждение — `deep-reasoner`, механика с шумным выводом — `fast-worker`.
Они репо-локальные; нет в репозитории — **предложи пользователю создать**
по заготовкам из
[references/claude-agents.md](references/claude-agents.md) и дальше
работай ими, а не разовым `general-purpose`: определение — одноразовая
цена, зато модель и effort заданы явно и переживают сессию. Молча не
заводить: `.claude/agents/` — территория пользователя.
- **Модель Claude-субагентов задавай явно**: Опус — рассуждения и ревью,
Sonnet — механика. Без явной модели субагент наследует Fable, чьи лимиты
самые дорогие — держи их для оркестрации (у `deep-reasoner`/`fast-worker`
модели пришиты в определениях). Две ручки эскалации: не хватило
глубины — повышай effort; не хватает качества суждения — повышай модель;
после двух слабых результатов подряд — свежий более сильный агент вместо
переноса неудачного контекста.
- **Effort Claude-субагентов тоже задавай явно** (решение пользователя
2026-07-26 под Opus 5: усилия распределены иначе, чем у 4.8, — `high`
верхняя рабочая ступень, `xhigh` не дефолтить; условно `high` у Opus 5
ближе к прежнему `xhigh`, `medium` — чуть ниже прежнего `high`, то есть
ступени сдвинулись неравномерно), по цене *тихой* ошибки этапа, не по
сложности: `high` — ревью постановок и планов (дефект каскадирует:
отравляет реализацию, оба ревью и триаж); `medium` — слепое ревью
(последняя линия обороны своей линзы, пропуск тихий) и узкие
перепроверки; default — механика (за ней приёмка оркестратора, ошибка
громкая; она и так идёт Sonnet-агентом — эффорт там не крутить вовсе).
Ревью ниже medium не опускать даже при двух ревьюерах: линзы разные,
избыточность — не дублирование. У `deep-reasoner` `high` пришит
фронтматтером и понижению не подлежит: он специалист по рассуждению, а
в роли фолбэк-ревьюера просто приедет ступенью выше карты — карта
задаёт минимум для роли, а не ограничение для агента. Ступеней меньше,
чем этапов, — это нормально: эффорт задаёт лишь глубину поверх
выбранной модели, тонкая настройка идёт промптом. Внутри одного агента
effort между
резюмами не менять (у Claude смена thinking-конфига сбрасывает
messages-ярус кэша; про effort не задокументировано — не рисковать).
Ограничение любого эффорта: от уверенной выдумки внешних фактов (форматы
артефактов, версии) не страхует — факты проверять отдельно.
отдельной линии, а не ради свободного слота; у одного дерева один
владелец — параллельная запись только разными worktree со швом по
непересекающимся файлам.
- **Субагенты — по готовым определениям** из
[references/claude-agents.md](references/claude-agents.md)
(`deep-reasoner` — рассуждения и ревью постановок; `craftsman` —
исполнение брифов: вкусовая реализация, слепое ревью, перепроверки;
`fast-worker` — механика):
ступень эффорта не задаётся в вызове (у Agent-тула такой ручки нет) —
её **выбирают выбором агента**: модель и effort пришиты фронтматтером;
разовый `general-purpose` приедет на эффорте сессии, а без явной
модели субагент наследует Fable, чьи лимиты держи для оркестрации. Карта «роль → модель и
ступень» и её основания — там же. Нет определений в репозитории —
**предложи пользователю создать** (молча не заводить:
`.claude/agents/` — территория пользователя). Эскалация: не хватило
глубины — выше effort, не хватает суждения — выше модель; после двух
слабых результатов подряд — свежий более сильный агент, не перенос
неудачного контекста. Внутри одного агента effort между резюмами не
менять (сбрасывает messages-ярус кэша). Никакой эффорт не страхует от
уверенной выдумки внешних фактов — проверяй первоисточником.
## Конвейер
@@ -126,7 +116,14 @@ description: >-
свежий контекст; рёбра блокировок явные. Мерка самодостаточности —
тикет можно взять в отдельной сессии вообще без общего контекста.
Сверка разбиения с пользователем внутри `/to-tickets` — уже первая
линия ревью постановки, засчитай её на этапе 2. Формат и место — по
линия ревью постановки, засчитай её на этапе 2. Здесь же — разрез
исполнителей по подзадачам (ось вкуса —
[references/model-matrix.md](references/model-matrix.md)): что человек
будет читать и разбирать — вкусовой части (Опус), руки — Кодексу.
Сначала вкусовая часть: она задаёт форму, имена и границы, под
которые механическая подстраивается, — обратный порядок даёт ретрофит;
параллелить части — только в рамках «Пределов параллельности».
Формат и место — по
конвенции репозитория (например, `.scratch/<feature>/issues/` или
трекер из `docs/agents/`). Не хватает
фактуры по внешним библиотекам/API — сначала `/research` и Context7 MCP,
@@ -144,7 +141,7 @@ description: >-
прочтёт сам), после правок — узкая проверка дельты тем же ревьюером.
Шкала: тикет-срез по уже принятой спеке, без решений сверх неё —
внешнюю линию пропусти, причину назови одной фразой; обычный тикет —
адверсарный ревьюер без
ревьюер роли постановок (`deep-reasoner`) без
твоего контекста проверяет задачу против кода: фактические ошибки, скрытые
решения-«однострочники», недостающие критерии —
ловит блокеры, которые исполнитель молча реализовал бы. Постановка
@@ -152,26 +149,30 @@ description: >-
цена ошибки высока — сделай ревью двойным и слепым, как для кода: вторая
линия — Codex свежим тредом с явной рамкой «ревьюируй постановку, не
реализацию; детали реализации — только если постановка молча предрешает
решение» (без рамки зарывается в детали). Родословные и тут ловят разное:
решение» (без рамки зарывается в детали). Семейства и тут ловят разное:
Codex — уровень требований (недостающие критерии, наблюдаемость,
«формально отчитаться можно»), Клод — механику кода (нереализуемые
формулировки, мёртвые стабы). Этап закрыт, когда каждая
находка внесена в задачу **решением** или письменно отклонена — «пусть
решит исполнитель» решением не считается; при пропуске внешней линии —
когда причина пропуска названа.
3. **Реализация Кодексом.** Промпт: «задача самодостаточна, следуй буквально,
коммит не делай». Запуск — прямым `codex exec` **фоновым Bash
оркестратора**: шум — редиректами в файлы, в контекст читается только
файл отчёта, харнесс будит по завершении; рецепты, ветки и ловушки —
3. **Реализация — по разрезу этапа 1.** Вкусовую часть пишет
`craftsman` свежей сессией, техническую — Codex; у обоих один и тот же
файл задачи, промпт — скелет из
[references/prompt-templates.md](references/prompt-templates.md)
(мандат «следуй буквально, коммит не делай» уже в нём). Запуск
Codex — прямым `codex exec` **фоновым Bash оркестратора**: шум —
редиректами в файлы, в контекст читается только файл отчёта, харнесс
будит по завершении; рецепты, ветки и ловушки —
[references/codex-exec.md](references/codex-exec.md).
Один писатель в дереве: пока Codex пишет — никто больше (казус с
форвардером — в [references/lessons.md](references/lessons.md)).
Пока исполнитель пишет — дерево его («Пределы параллельности»; казус
форвардера — в [references/lessons.md](references/lessons.md)).
После отчёта — **саморевью тем же тредом** (resume, effort medium;
заготовка — [references/prompt-templates.md](references/prompt-templates.md)):
файл готов в `prompts/`):
исполнитель проходит свой diff против критериев как ревьюер и сам чинит
найденное, тебе — одна строка «found N, fixed N». Дёшево и снимает часть
находок до внешних глаз. Готово, когда Codex вернул отчёт, саморевью
пройдено, в дереве нет правок, которых он не называл,
находок до внешних глаз. Готово, когда каждый исполнитель вернул отчёт
и саморевью, в дереве нет правок, которых отчёты не называли,
и дешёвая сквозная проверка (если она есть в репо) зелёная: гонял её
исполнитель по промпту, а если ему она недоступна (docker, стенд) — ты,
**до запуска ревьюеров**: иначе ревью уйдёт на код, который сквозной
@@ -180,35 +181,34 @@ description: >-
дальше по цене ошибки: **тривиальное** изменение (до-правка по готовому
диагнозу, механика, целиком накрытое детерминированной проверкой) —
внешних линий не гоняй, причину пропуска назови одной фразой;
**простое, но с заметной ценой ошибки** — один ревьюер другой
родословной, чем исполнитель (у нас — Клод при Codex-исполнителе;
одиночную линию выбирай по родословной, не по цене); **обычное и
сложнее** — два слепых ревью параллельно с разведёнными фокусами: одна
линия «по задаче» (соответствие постановке, критериям, границам и
уместность решения — точные слова в заготовке линии), другая
«по коду» (корректность, инварианты, регрессии, честность тестов) —
разность семейств даёт разные находки, разность фокусов страхует от
дублирования, когда семейства сходятся. Промпт — **общий блок один на
обе линии** плюс крошечный файл линии (линза и префикс ID); собираются
два файла с разными путями (скелет и обёртки вызова —
[references/prompt-templates.md](references/prompt-templates.md)): Codex
получает свой через stdin, Клод-субагенту в prompt — короткая обёртка
«прочитай файл X и выполни; индекс — в файл Y» (не дублируй текст
промпта в параметре — это второй полный экземпляр в твоём контексте).
Содержание: путь к задаче-файлу + фокус и префикс ID линии; мандат,
формат индекса с устойчивыми ID и поощрение эмпирических проверок уже
в готовом boilerplate. Друг про
друга не знают, твои выводы им не пересказывай. Вердикты — файлами с
**разными путями**: у Codex это его `-o`-отчёт, Клод-ревьюеру путь и
финальный акт (SendMessage только со строкой VERDICT, счётчиками и
путём) задаёт готовая обёртка из шаблонов; его idle-уведомления
результата не содержат, не жди из них ничего. После
ревью сверь дерево (`git status`). Клод-ревьюеру можно поручить смотреть
артефакты (картинки из ноутбука). Этап закрыт, когда вердикты всех
**простое, но с заметной ценой ошибки** — один ревьюер семейства,
отличного от исполнителя (линза — `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. **Синтез и триаж.** Сведи вердикты по индексам: пересечения, противоречия.
5. **Синтез и триаж.** Сведи вердикты по индексам: пересечения,
противоречия. Линии не сливай в один ранжир: оси разведены намеренно,
уверенный вердикт одной (APPROVED без находок) не закрывает находки
другой.
Пофиндинговый триаж — у **исполнителя**, не у тебя (правило
`/claude-team-review` и `/coordinator-loop`: судит тот, у кого контекст
кода): перешли Codex индекс находок **дословно**, он чинит или
@@ -221,10 +221,10 @@ description: >-
NEEDS_DECISION`; два последних — решения твоего уровня, исполнитель
возвращает их тебе, а не решает молча. Резолюции и доводы он пишет в
свой файл отчёта, **тикет в триаже не правится**: правка тикета эхом
вкатывает весь его текст в твой контекст (пожиратель №1 прогона задачи
13), выжимку в тикет перенесёт fast-worker на финале. Свои замечания к
вкатывает весь его текст в твой контекст — главный пожиратель
прогонов; выжимку в тикет перенесёт fast-worker на финале. Свои замечания к
триажу — только шапкой. Ты судишь уровнем задачи: принять риск / вне
скоупа. Повторная проверка — узкая (см. «Свежесть»); её промпт не
скоупа. Повторная проверка — узкая (см. «Перепроверка»); её промпт не
пересказывает резолюции — ссылается на файл отчёта исполнителя.
Третий круг триажа — точка вмешательства: доложи пользователю, почему
процесс не сходится и что меняешь (постановку, модель/effort,
@@ -241,7 +241,9 @@ description: >-
**своими глазами** (счётчик тестов, картинки, прогон CLI) — ревью не
заменяет твою приёмку. Команды нового приёмочного сценария проверь на
живом объекте до полного прогона; сложные вставки собирай файлами, не
экранированием. Чекбоксы, статус и выжимку резолюций в тикет
экранированием; фоновому запуску закрывай stdin (`< /dev/null`) —
команда, дочитывающая ввод, из терминала зелёная, а в фоне виснет
навсегда. Чекбоксы, статус и выжимку резолюций в тикет
переносит fast-worker из файла отчёта исполнителя (не твой Write).
Коммит — по `/conventional-commits`, пользователю — выжимка: вердикты,
что принято/отклонено, что осталось — плюс короткая саморефлексия: что
@@ -254,9 +256,9 @@ description: >-
В отличие от `/coordinator-loop`, здесь пользователь рядом: на границах
этапов давай в чат карту прогресса в 4–7 строк обычными словами
(✅ сделано / ▶ идёт / ⬜ дальше); термины плейбука — только с расшифровкой
(урок 2026-07-13: телеграфные статусы в терминах этапов потеряли
пользователя). Карта дополняет содержательную сводку, не заменяет её.
(✅ сделано / ▶ идёт / ⬜ дальше); термины плейбука — только с
расшифровкой: телеграфные статусы в терминах этапов теряют пользователя.
Карта дополняет содержательную сводку, не заменяет её.
Решения по скоупу оставляй пользователю. Фоновые этапы будят тебя
сами — не поллинг вручную, а отслеживаемые фоновые процессы + уведомления
(механика — [references/codex-exec.md](references/codex-exec.md)).
@@ -271,7 +273,13 @@ teammate-субагентов — шум, а не событие: не докл
- Нет ожидаемого файла или отчёта: один запрос короткого итога в тот же
тред; повторная тишина — свежий агент от сохранённых артефактов, владение
деревом — только после остановки прежнего владельца.
деревом — только после остановки прежнего владельца. Молчание — не
смерть: признак жизни — уведомление харнесса, не размер транскрипта;
замене давай **другой** путь вердикта — дубль на тот же путь затирает
находки живого.
- Отчёт агента о состоянии среды — не факт: перед приёмкой посмотри стенд
своими глазами (`docker compose ps -a`; без `-a` погашенные службы
невидимы).
- Длинный рассказ пришёл сообщением: попроси сводку с путём к файлу,
рассказ дальше не переноси.
- Два писателя пересеклись в дереве: стоп обоим, назначь одного владельца,
@@ -287,7 +295,10 @@ teammate-субагентов — шум, а не событие: не докл
словарь (индекс, свежие сессии, две ручки стоимости) — общий.
- `/claude-team-review` — ревью-петля, где лид сам чинит код (живёт
отдельным репозиторием, в среде может быть не подключён).
- `/adversarial-review` — разовое адверсарное ревью Кодексом.
- `/adversarial-review` — разовое адверсарное ревью Кодексом (в среде
может быть не подключён).
- `codex-subagent-playbook` — близнец этого плейбука для координатора на
стороне Codex; скрыт от автовызова, зови по имени.
- `/to-tickets` — разбиение на тикеты-срезы с рёбрами блокировок (этап 1);
его сверка разбиения с пользователем — первая линия ревью постановки.
- `/tdd` — дисциплина test-first: для задач-мелочей, которые делаешь сам,
@@ -305,8 +316,12 @@ teammate-субагентов — шум, а не событие: не докл
промптов: готовые 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`/`fast-worker` и конструкция
репо-локальных субагентов (`deep-reasoner`, `craftsman`,
`fast-worker`), карта «роль → модель и ступень» и конструкция
оркестрации из CLAUDE.md — воссоздать в новом репозитории.