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 name: claude-subagent-playbook
description: >- description: >-
Конвейер одной нетривиальной задачи со стороны Claude Code: постановка → Конвейер одной нетривиальной задачи со стороны Claude Code — от
свежий взгляд → реализация Кодексом → слепое ревью по шкале риска → постановки до приёмки через слепое ревью. Применяй, когда пользователь
триаж → приёмка. Применяй, когда пользователь даёт issue/тикет в работу даёт issue/тикет в работу конвейером, просит делегировать реализацию
конвейером, просит делегировать реализацию Codex или устроить Codex или устроить независимое ревью изменений.
независимое ревью изменений.
--- ---
# Плейбук: одна задача через Кодекса и слепое ревью # Плейбук: одна задача через Кодекса и слепое ревью
@@ -43,76 +42,67 @@ description: >-
существующий тред. Механику (правки файлов по готовым решениям, существующий тред. Механику (правки файлов по готовым решениям,
скрипты, вёрстку) — `fast-worker`'у: твоё в них только короткий список скрипты, вёрстку) — `fast-worker`'у: твоё в них только короткий список
решений. **Индекс — у тебя, полезная нагрузка — файлами между решений. **Индекс — у тебя, полезная нагрузка — файлами между
агентами**: вердикты, отчёты и промпты живут в `$SCRATCH` (обменный агентами**: вердикты, отчёты и промпты живут в `$SCRATCH` и ведутся
temp-каталог прогона — скретчпад сессии или `mktemp -d`; детали — в **на английском**; русский — только тому, что уходит в репозиторий и
[references/prompt-templates.md](references/prompt-templates.md)) и пользователю (конвенция каталога и языковой хвост — в
ведутся **на английском** — проект их не хранит, а кириллица в 1,5–2 [references/prompt-templates.md](references/prompt-templates.md)). Читай их один раз, дальше передавай путями и
раза дороже по токенам; русский — только тому, что уходит в репозиторий
и пользователю. Читай их один раз, дальше передавай путями и
конкатенацией (`cat`), не переписывай Write'ом — каждое переписывание конкатенацией (`cat`), не переписывай Write'ом — каждое переписывание
дублирует контент в твоём контексте. SendMessage возвращает эхом весь дублирует контент в твоём контексте. SendMessage возвращает эхом весь
текст сообщения — teammate'у шли короткое (вердикт, путь, вопрос), текст сообщения — teammate'у шли короткое (вердикт, путь, вопрос),
длинное — файлом, который он прочтёт сам. длинное — файлом, который он прочтёт сам.
- **Codex** — реализация кода. У пользователя лимиты Codex больше, код он - **Исполнители** — двое; разрез между ними задаёт этап 1 по осям
пишет в целом лучше, но верхнеуровнево планирует хуже — поэтому цена/интеллект/вкус
декомпозиция и постановка остаются у тебя. Механика вызова — ([references/model-matrix.md](references/model-matrix.md)). `craftsman`
[references/codex-exec.md](references/codex-exec.md). (Опус) — вкусовая часть; Codex — техническая: лимиты у него почти
- **Ревьюеры** — до двух (шкалы — этапы 2 и 4), **разных родословных**, слепые бесплатные, код пишет отлично, а верхнеуровнево планирует хуже —
друг к другу: декомпозиция и постановка при любом разрезе остаются у тебя. Механика
Claude-субагент (`adversarial-reviewer`; нет в среде — `deep-reasoner` вызова Codex — [references/codex-exec.md](references/codex-exec.md).
или скептический `general-purpose`) и Codex **свежим тредом**, не тем, - **Ревьюеры** — до двух линий (шкалы — этапы 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)). [references/codex-exec.md](references/codex-exec.md)).
- **Свежесть**: ревьюеров запускай свежими сессиями, без форка своей истории - **Перепроверка**: повторную проверку точечных правок — **тем же**
(форк тратит токены и убивает независимость). Повторную проверку точечных ревьюером узким вопросом «закрывают ли правки твои находки», не полным
правок — **тем же** ревьюером узким вопросом «закрывают ли правки твои обходом.
находки», не полным обходом.
- **Пределы параллельности**: глубина один — субагенты не разворачивают - **Пределы параллельности**: глубина один — субагенты не разворачивают
собственных субагентов; параллельно только работа без конфликтующих собственных субагентов; параллельно только работа без конфликтующих
входов и общего изменяемого состояния; второй обзор добавляй ради входов и общего изменяемого состояния; второй обзор добавляй ради
отдельной линии, а не ради свободного слота; реализацию и починку одного отдельной линии, а не ради свободного слота; у одного дерева один
дерева веди последовательно одним владельцем. владелец — параллельная запись только разными worktree со швом по
- **Вспомогательные Claude-субагенты** для попутного делегирования: глубокое непересекающимся файлам.
рассуждение — `deep-reasoner`, механика с шумным выводом — `fast-worker`. - **Субагенты — по готовым определениям** из
Они репо-локальные; нет в репозитории — **предложи пользователю создать** [references/claude-agents.md](references/claude-agents.md)
по заготовкам из (`deep-reasoner` — рассуждения и ревью постановок; `craftsman` —
[references/claude-agents.md](references/claude-agents.md) и дальше исполнение брифов: вкусовая реализация, слепое ревью, перепроверки;
работай ими, а не разовым `general-purpose`: определение — одноразовая `fast-worker` — механика):
цена, зато модель и effort заданы явно и переживают сессию. Молча не ступень эффорта не задаётся в вызове (у Agent-тула такой ручки нет) —
заводить: `.claude/agents/` — территория пользователя. её **выбирают выбором агента**: модель и effort пришиты фронтматтером;
- **Модель Claude-субагентов задавай явно**: Опус — рассуждения и ревью, разовый `general-purpose` приедет на эффорте сессии, а без явной
Sonnet — механика. Без явной модели субагент наследует Fable, чьи лимиты модели субагент наследует Fable, чьи лимиты держи для оркестрации. Карта «роль → модель и
самые дорогие — держи их для оркестрации (у `deep-reasoner`/`fast-worker` ступень» и её основания — там же. Нет определений в репозитории —
модели пришиты в определениях). Две ручки эскалации: не хватило **предложи пользователю создать** (молча не заводить:
глубины — повышай effort; не хватает качества суждения — повышай модель; `.claude/agents/` — территория пользователя). Эскалация: не хватило
после двух слабых результатов подряд — свежий более сильный агент вместо глубины — выше effort, не хватает суждения — выше модель; после двух
переноса неудачного контекста. слабых результатов подряд — свежий более сильный агент, не перенос
- **Effort Claude-субагентов тоже задавай явно** (решение пользователя неудачного контекста. Внутри одного агента effort между резюмами не
2026-07-26 под Opus 5: усилия распределены иначе, чем у 4.8, — `high` менять (сбрасывает messages-ярус кэша). Никакой эффорт не страхует от
верхняя рабочая ступень, `xhigh` не дефолтить; условно `high` у Opus 5 уверенной выдумки внешних фактов — проверяй первоисточником.
ближе к прежнему `xhigh`, `medium` — чуть ниже прежнего `high`, то есть
ступени сдвинулись неравномерно), по цене *тихой* ошибки этапа, не по
сложности: `high` — ревью постановок и планов (дефект каскадирует:
отравляет реализацию, оба ревью и триаж); `medium` — слепое ревью
(последняя линия обороны своей линзы, пропуск тихий) и узкие
перепроверки; default — механика (за ней приёмка оркестратора, ошибка
громкая; она и так идёт Sonnet-агентом — эффорт там не крутить вовсе).
Ревью ниже medium не опускать даже при двух ревьюерах: линзы разные,
избыточность — не дублирование. У `deep-reasoner` `high` пришит
фронтматтером и понижению не подлежит: он специалист по рассуждению, а
в роли фолбэк-ревьюера просто приедет ступенью выше карты — карта
задаёт минимум для роли, а не ограничение для агента. Ступеней меньше,
чем этапов, — это нормально: эффорт задаёт лишь глубину поверх
выбранной модели, тонкая настройка идёт промптом. Внутри одного агента
effort между
резюмами не менять (у Claude смена thinking-конфига сбрасывает
messages-ярус кэша; про effort не задокументировано — не рисковать).
Ограничение любого эффорта: от уверенной выдумки внешних фактов (форматы
артефактов, версии) не страхует — факты проверять отдельно.
## Конвейер ## Конвейер
@@ -126,7 +116,14 @@ description: >-
свежий контекст; рёбра блокировок явные. Мерка самодостаточности — свежий контекст; рёбра блокировок явные. Мерка самодостаточности —
тикет можно взять в отдельной сессии вообще без общего контекста. тикет можно взять в отдельной сессии вообще без общего контекста.
Сверка разбиения с пользователем внутри `/to-tickets` — уже первая Сверка разбиения с пользователем внутри `/to-tickets` — уже первая
линия ревью постановки, засчитай её на этапе 2. Формат и место — по линия ревью постановки, засчитай её на этапе 2. Здесь же — разрез
исполнителей по подзадачам (ось вкуса —
[references/model-matrix.md](references/model-matrix.md)): что человек
будет читать и разбирать — вкусовой части (Опус), руки — Кодексу.
Сначала вкусовая часть: она задаёт форму, имена и границы, под
которые механическая подстраивается, — обратный порядок даёт ретрофит;
параллелить части — только в рамках «Пределов параллельности».
Формат и место — по
конвенции репозитория (например, `.scratch/<feature>/issues/` или конвенции репозитория (например, `.scratch/<feature>/issues/` или
трекер из `docs/agents/`). Не хватает трекер из `docs/agents/`). Не хватает
фактуры по внешним библиотекам/API — сначала `/research` и Context7 MCP, фактуры по внешним библиотекам/API — сначала `/research` и Context7 MCP,
@@ -144,7 +141,7 @@ description: >-
прочтёт сам), после правок — узкая проверка дельты тем же ревьюером. прочтёт сам), после правок — узкая проверка дельты тем же ревьюером.
Шкала: тикет-срез по уже принятой спеке, без решений сверх неё — Шкала: тикет-срез по уже принятой спеке, без решений сверх неё —
внешнюю линию пропусти, причину назови одной фразой; обычный тикет — внешнюю линию пропусти, причину назови одной фразой; обычный тикет —
адверсарный ревьюер без ревьюер роли постановок (`deep-reasoner`) без
твоего контекста проверяет задачу против кода: фактические ошибки, скрытые твоего контекста проверяет задачу против кода: фактические ошибки, скрытые
решения-«однострочники», недостающие критерии — решения-«однострочники», недостающие критерии —
ловит блокеры, которые исполнитель молча реализовал бы. Постановка ловит блокеры, которые исполнитель молча реализовал бы. Постановка
@@ -152,26 +149,30 @@ description: >-
цена ошибки высока — сделай ревью двойным и слепым, как для кода: вторая цена ошибки высока — сделай ревью двойным и слепым, как для кода: вторая
линия — Codex свежим тредом с явной рамкой «ревьюируй постановку, не линия — Codex свежим тредом с явной рамкой «ревьюируй постановку, не
реализацию; детали реализации — только если постановка молча предрешает реализацию; детали реализации — только если постановка молча предрешает
решение» (без рамки зарывается в детали). Родословные и тут ловят разное: решение» (без рамки зарывается в детали). Семейства и тут ловят разное:
Codex — уровень требований (недостающие критерии, наблюдаемость, Codex — уровень требований (недостающие критерии, наблюдаемость,
«формально отчитаться можно»), Клод — механику кода (нереализуемые «формально отчитаться можно»), Клод — механику кода (нереализуемые
формулировки, мёртвые стабы). Этап закрыт, когда каждая формулировки, мёртвые стабы). Этап закрыт, когда каждая
находка внесена в задачу **решением** или письменно отклонена — «пусть находка внесена в задачу **решением** или письменно отклонена — «пусть
решит исполнитель» решением не считается; при пропуске внешней линии — решит исполнитель» решением не считается; при пропуске внешней линии —
когда причина пропуска названа. когда причина пропуска названа.
3. **Реализация Кодексом.** Промпт: «задача самодостаточна, следуй буквально, 3. **Реализация — по разрезу этапа 1.** Вкусовую часть пишет
коммит не делай». Запуск — прямым `codex exec` **фоновым Bash `craftsman` свежей сессией, техническую — Codex; у обоих один и тот же
оркестратора**: шум — редиректами в файлы, в контекст читается только файл задачи, промпт — скелет из
файл отчёта, харнесс будит по завершении; рецепты, ветки и ловушки — [references/prompt-templates.md](references/prompt-templates.md)
(мандат «следуй буквально, коммит не делай» уже в нём). Запуск
Codex — прямым `codex exec` **фоновым Bash оркестратора**: шум —
редиректами в файлы, в контекст читается только файл отчёта, харнесс
будит по завершении; рецепты, ветки и ловушки —
[references/codex-exec.md](references/codex-exec.md). [references/codex-exec.md](references/codex-exec.md).
Один писатель в дереве: пока Codex пишет — никто больше (казус с Пока исполнитель пишет — дерево его («Пределы параллельности»; казус
форвардером — в [references/lessons.md](references/lessons.md)). форвардера — в [references/lessons.md](references/lessons.md)).
После отчёта — **саморевью тем же тредом** (resume, effort medium; После отчёта — **саморевью тем же тредом** (resume, effort medium;
заготовка — [references/prompt-templates.md](references/prompt-templates.md)): файл готов в `prompts/`):
исполнитель проходит свой diff против критериев как ревьюер и сам чинит исполнитель проходит свой diff против критериев как ревьюер и сам чинит
найденное, тебе — одна строка «found N, fixed N». Дёшево и снимает часть найденное, тебе — одна строка «found N, fixed N». Дёшево и снимает часть
находок до внешних глаз. Готово, когда Codex вернул отчёт, саморевью находок до внешних глаз. Готово, когда каждый исполнитель вернул отчёт
пройдено, в дереве нет правок, которых он не называл, и саморевью, в дереве нет правок, которых отчёты не называли,
и дешёвая сквозная проверка (если она есть в репо) зелёная: гонял её и дешёвая сквозная проверка (если она есть в репо) зелёная: гонял её
исполнитель по промпту, а если ему она недоступна (docker, стенд) — ты, исполнитель по промпту, а если ему она недоступна (docker, стенд) — ты,
**до запуска ревьюеров**: иначе ревью уйдёт на код, который сквозной **до запуска ревьюеров**: иначе ревью уйдёт на код, который сквозной
@@ -180,35 +181,34 @@ description: >-
дальше по цене ошибки: **тривиальное** изменение (до-правка по готовому дальше по цене ошибки: **тривиальное** изменение (до-правка по готовому
диагнозу, механика, целиком накрытое детерминированной проверкой) — диагнозу, механика, целиком накрытое детерминированной проверкой) —
внешних линий не гоняй, причину пропуска назови одной фразой; внешних линий не гоняй, причину пропуска назови одной фразой;
**простое, но с заметной ценой ошибки** — один ревьюер другой **простое, но с заметной ценой ошибки** — один ревьюер семейства,
родословной, чем исполнитель (у нас — Клод при Codex-исполнителе; отличного от исполнителя (линза — `line-rev`, обе в одной); **обычное
одиночную линию выбирай по родословной, не по цене); **обычное и и сложнее** — два слепых ревью параллельно с разведёнными фокусами:
сложнее** — два слепых ревью параллельно с разведёнными фокусами: одна линию «по задаче» (`line-task` + `line-taste`: постановка, критерии,
линия «по задаче» (соответствие постановке, критериям, границам и границы, уместность и вкус) ведёт модель со вкусом, линию «по коду»
уместность решения — точные слова в заготовке линии), другая (`line-code`: корректность, инварианты, регрессии, честность
«по коду» (корректность, инварианты, регрессии, честность тестов) — тестов) — семейство, отличное от исполнителя (основания — «Роли»).
разность семейств даёт разные находки, разность фокусов страхует от Разность семейств даёт разные находки, разность фокусов страхует от
дублирования, когда семейства сходятся. Промпт — **общий блок один на дублирования, когда семейства сходятся; артефакты-картинки (ноутбуки,
обе линии** плюс крошечный файл линии (линза и префикс ID); собираются графики) видит только Claude-линия — учитывай при назначении. Сборка
два файла с разными путями (скелет и обёртки вызова — промптов и обёртки вызова — целиком в
[references/prompt-templates.md](references/prompt-templates.md)): Codex [references/prompt-templates.md](references/prompt-templates.md); два
получает свой через stdin, Клод-субагенту в prompt — короткая обёртка правила при этом твои: пути промптов и вердиктов у линий разные, и
«прочитай файл X и выполни; индекс — в файл Y» (не дублируй текст текст промпта в параметр вызова не дублируй — это второй полный
промпта в параметре — это второй полный экземпляр в твоём контексте). экземпляр в твоём контексте. Друг про друга линии не знают, твои
Содержание: путь к задаче-файлу + фокус и префикс ID линии; мандат, выводы им не пересказывай. Живой стенд двум линиям не давай: их
формат индекса с устойчивыми ID и поощрение эмпирических проверок уже стражи гасят службы и роняют таблицы друг другу — стенд получает одна
в готовом boilerplate. Друг про линия, второй — явный запрет ломающих команд. Idle-уведомления
друга не знают, твои выводы им не пересказывай. Вердикты — файлами с Клод-ревьюера результата не содержат — итог придёт строкой VERDICT и
**разными путями**: у Codex это его `-o`-отчёт, Клод-ревьюеру путь и файлом по пути из обёртки. После
финальный акт (SendMessage только со строкой VERDICT, счётчиками и ревью сверь дерево (`git status`). Этап закрыт, когда вердикты всех
путём) задаёт готовая обёртка из шаблонов; его idle-уведомления
результата не содержат, не жди из них ничего. После
ревью сверь дерево (`git status`). Клод-ревьюеру можно поручить смотреть
артефакты (картинки из ноутбука). Этап закрыт, когда вердикты всех
выбранных линий у тебя индексами и дерево нетронуто; вердикт без единой находки засчитывай выбранных линий у тебя индексами и дерево нетронуто; вердикт без единой находки засчитывай
только после проверки его лога — работа, не отписка только после проверки его лога — работа, не отписка
(приём — в [references/codex-exec.md](references/codex-exec.md)). (приём — в [references/codex-exec.md](references/codex-exec.md)).
5. **Синтез и триаж.** Сведи вердикты по индексам: пересечения, противоречия. 5. **Синтез и триаж.** Сведи вердикты по индексам: пересечения,
противоречия. Линии не сливай в один ранжир: оси разведены намеренно,
уверенный вердикт одной (APPROVED без находок) не закрывает находки
другой.
Пофиндинговый триаж — у **исполнителя**, не у тебя (правило Пофиндинговый триаж — у **исполнителя**, не у тебя (правило
`/claude-team-review` и `/coordinator-loop`: судит тот, у кого контекст `/claude-team-review` и `/coordinator-loop`: судит тот, у кого контекст
кода): перешли Codex индекс находок **дословно**, он чинит или кода): перешли Codex индекс находок **дословно**, он чинит или
@@ -221,10 +221,10 @@ description: >-
NEEDS_DECISION`; два последних — решения твоего уровня, исполнитель NEEDS_DECISION`; два последних — решения твоего уровня, исполнитель
возвращает их тебе, а не решает молча. Резолюции и доводы он пишет в возвращает их тебе, а не решает молча. Резолюции и доводы он пишет в
свой файл отчёта, **тикет в триаже не правится**: правка тикета эхом свой файл отчёта, **тикет в триаже не правится**: правка тикета эхом
вкатывает весь его текст в твой контекст (пожиратель №1 прогона задачи вкатывает весь его текст в твой контекст — главный пожиратель
13), выжимку в тикет перенесёт fast-worker на финале. Свои замечания к прогонов; выжимку в тикет перенесёт fast-worker на финале. Свои замечания к
триажу — только шапкой. Ты судишь уровнем задачи: принять риск / вне триажу — только шапкой. Ты судишь уровнем задачи: принять риск / вне
скоупа. Повторная проверка — узкая (см. «Свежесть»); её промпт не скоупа. Повторная проверка — узкая (см. «Перепроверка»); её промпт не
пересказывает резолюции — ссылается на файл отчёта исполнителя. пересказывает резолюции — ссылается на файл отчёта исполнителя.
Третий круг триажа — точка вмешательства: доложи пользователю, почему Третий круг триажа — точка вмешательства: доложи пользователю, почему
процесс не сходится и что меняешь (постановку, модель/effort, процесс не сходится и что меняешь (постановку, модель/effort,
@@ -241,7 +241,9 @@ description: >-
**своими глазами** (счётчик тестов, картинки, прогон CLI) — ревью не **своими глазами** (счётчик тестов, картинки, прогон CLI) — ревью не
заменяет твою приёмку. Команды нового приёмочного сценария проверь на заменяет твою приёмку. Команды нового приёмочного сценария проверь на
живом объекте до полного прогона; сложные вставки собирай файлами, не живом объекте до полного прогона; сложные вставки собирай файлами, не
экранированием. Чекбоксы, статус и выжимку резолюций в тикет экранированием; фоновому запуску закрывай stdin (`< /dev/null`) —
команда, дочитывающая ввод, из терминала зелёная, а в фоне виснет
навсегда. Чекбоксы, статус и выжимку резолюций в тикет
переносит fast-worker из файла отчёта исполнителя (не твой Write). переносит fast-worker из файла отчёта исполнителя (не твой Write).
Коммит — по `/conventional-commits`, пользователю — выжимка: вердикты, Коммит — по `/conventional-commits`, пользователю — выжимка: вердикты,
что принято/отклонено, что осталось — плюс короткая саморефлексия: что что принято/отклонено, что осталось — плюс короткая саморефлексия: что
@@ -254,9 +256,9 @@ description: >-
В отличие от `/coordinator-loop`, здесь пользователь рядом: на границах В отличие от `/coordinator-loop`, здесь пользователь рядом: на границах
этапов давай в чат карту прогресса в 4–7 строк обычными словами этапов давай в чат карту прогресса в 4–7 строк обычными словами
(✅ сделано / ▶ идёт / ⬜ дальше); термины плейбука — только с расшифровкой (✅ сделано / ▶ идёт / ⬜ дальше); термины плейбука — только с
(урок 2026-07-13: телеграфные статусы в терминах этапов потеряли расшифровкой: телеграфные статусы в терминах этапов теряют пользователя.
пользователя). Карта дополняет содержательную сводку, не заменяет её. Карта дополняет содержательную сводку, не заменяет её.
Решения по скоупу оставляй пользователю. Фоновые этапы будят тебя Решения по скоупу оставляй пользователю. Фоновые этапы будят тебя
сами — не поллинг вручную, а отслеживаемые фоновые процессы + уведомления сами — не поллинг вручную, а отслеживаемые фоновые процессы + уведомления
(механика — [references/codex-exec.md](references/codex-exec.md)). (механика — [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` — ревью-петля, где лид сам чинит код (живёт - `/claude-team-review` — ревью-петля, где лид сам чинит код (живёт
отдельным репозиторием, в среде может быть не подключён). отдельным репозиторием, в среде может быть не подключён).
- `/adversarial-review` — разовое адверсарное ревью Кодексом. - `/adversarial-review` — разовое адверсарное ревью Кодексом (в среде
может быть не подключён).
- `codex-subagent-playbook` — близнец этого плейбука для координатора на
стороне Codex; скрыт от автовызова, зови по имени.
- `/to-tickets` — разбиение на тикеты-срезы с рёбрами блокировок (этап 1); - `/to-tickets` — разбиение на тикеты-срезы с рёбрами блокировок (этап 1);
его сверка разбиения с пользователем — первая линия ревью постановки. его сверка разбиения с пользователем — первая линия ревью постановки.
- `/tdd` — дисциплина test-first: для задач-мелочей, которые делаешь сам, - `/tdd` — дисциплина test-first: для задач-мелочей, которые делаешь сам,
@@ -305,8 +316,12 @@ teammate-субагентов — шум, а не событие: не докл
промптов: готовые boilerplate-файлы в `references/prompts/` подшиваются промптов: готовые boilerplate-файлы в `references/prompts/` подшиваются
`cat`'ом из каталога скилла, Write'ом пишутся только параметрические `cat`'ом из каталога скилла, Write'ом пишутся только параметрические
блоки. блоки.
- [references/model-matrix.md](references/model-matrix.md) — оси
цена/интеллект/вкус: матрица моделей и правила применения (разрез
этапа 1, назначение линий этапа 4).
- [references/lessons.md](references/lessons.md) — датированная эмпирика - [references/lessons.md](references/lessons.md) — датированная эмпирика
прогонов: что поймал каждый этап, казусы, цифры. прогонов: что поймал каждый этап, казусы, цифры.
- [references/claude-agents.md](references/claude-agents.md) — определения - [references/claude-agents.md](references/claude-agents.md) — определения
репо-локальных субагентов `deep-reasoner`/`fast-worker` и конструкция репо-локальных субагентов (`deep-reasoner`, `craftsman`,
`fast-worker`), карта «роль → модель и ступень» и конструкция
оркестрации из CLAUDE.md — воссоздать в новом репозитории. оркестрации из CLAUDE.md — воссоздать в новом репозитории.
@@ -0,0 +1,69 @@
# Handoff разработки скилла: структурный рефакторинг — ось вкуса, брифы, два Опус-агента
Дата: 2026-07-31. Контекст: не боевой прогон, а отдельный осознанный
заход на рефакторинг (решение пользователя от 2026-07-31 в lessons) —
закрыты все открытые вопросы, накопленные с 2026-07-26. Сессия шла под
`/writing-great-skills`; правки прошли слепое ревью Опусом по тому же
фреймворку (CHANGES_REQUIRED: 7 MAJOR, 17 MINOR, 3 NIT — закрыто, два
отклонения с доводами). Полный список решений и отклонений — в
`references/lessons.md`, записи «Открытый вопрос 2026-07-26 — закрыт» и
«Открытый вопрос 2026-07-31 — закрыт», здесь не дублируются.
## Что изменилось радикально (карта для свежего агента)
1. **Третья ось выбора исполнителя — вкус** (`references/model-matrix.md`,
матрица Тео с поправкой пользователя под gpt-5.6-sol/Opus 5). Разрез
по подзадачам на этапе 1: что читает человек — Опусу, руки — Кодексу;
сначала вкусовая часть.
2. **«Родословная» разведена на два механизма**: свежесть (независимость
от автора, обязательна каждой линии) и семейство (классы находок).
Линия дефектов — по различию семейства, линия уместности — по умению.
3. **Ступень эффорта выбирается выбором агента** (у Agent-тула ручки
effort нет — проверено по схеме). Определений ровно столько, сколько
пар (модель, ступень) в карте: `deep-reasoner` (opus/high — рассуждения
и ревью постановок, штатно), `craftsman` (opus/medium — исполнение
брифов: вкусовая реализация, слепое ревью, перепроверки),
`fast-worker` (sonnet — механика). `adversarial-reviewer` слит в
`craftsman`; роли живут в бриф-файлах, не в определениях.
4. **Константы — файлами в `prompts/`**: line-task / line-code / line-rev /
line-taste (вкусовая линза + 12 запахов Фаулера из `/code-review`
Мэтта Покока) / self-review. Разрез линз — выбором файла в `cat`.
5. **Правила координации прогона #18 поглощены в механизм**: обёртка
ревьюера (инкрементальная запись), мандат (глубина один, проверка
восстановления среды), «Сбои координации» (признак жизни —
уведомление; замене — другой путь вердикта; среда — своими глазами),
этап 4 (стенд одной линии), этап 6 (stdin фона `< /dev/null`).
## Что проверить следующим боевым прогоном (не обкатано)
1. **`craftsman` как единый агент** для вкусовой реализации и слепого
ревью: держит ли обобщённое определение обе стойки, не путает ли
режимы. Определений в боевых репозиториях ещё нет — создавать по
свежей заготовке из `references/claude-agents.md` (старые копии
deep-reasoner/fast-worker в репозиториях живы, craftsman — новый).
2. **Разрез по вкусу на этапе 1**: первый прогон с Опус-исполнителем;
порядок «сначала вкусовая часть», шов по файлам, ревью-оси при
Опусе-авторе (линия уместности по умению — та же родословная).
3. **`$D/access-<line>.md`** — новый механизм ограничения второй линии
при общем стенде (prompt-templates, раздел 2): синтаксис есть, боем
не проверен.
4. **Инкрементальная запись индекса** Клод-ревьюером: реально ли пишет
по ходу (правка обёртки после казуса «молчание 59 минут»).
5. Сверить близнеца `codex-subagent-playbook` после этих правок —
перенос туда ещё не делался (прошлая сверка — 2026-07-23).
## Ориентиры
- Вся эмпирика и датированные решения — `references/lessons.md` (хвост:
записи 2026-07-31).
- Вердикт слепого ревью правок жил в скретчпаде сессии — не сохраняйте,
всё принятое уже в файлах, отклонения задокументированы в lessons.
- Коммит этого захода — в истории dotfiles рядом с датой handoff'а.
## Suggested skills
- `claude-subagent-playbook` — следующий боевой прогон с чек-листом
«что проверить» выше; после прогона — дописать lessons.
- `writing-great-skills` — если прогон потребует новых структурных
правок скилла.
- `conventional-commits` — коммиты правок в dotfiles.
@@ -1,11 +1,37 @@
# Репо-локальные Claude-субагенты и конструкция оркестрации # Репо-локальные Claude-субагенты и конструкция оркестрации
`deep-reasoner` и `fast-worker` — субагенты уровня репозитория `deep-reasoner`, `craftsman` и `fast-worker` — субагенты уровня
(`.claude/agents/*.md`), не глобальные. В новом репозитории их нет — проверь репозитория (`.claude/agents/*.md`), не глобальные. Определений ровно
`ls .claude/agents/` и при отсутствии создай файлы ниже как есть. столько, сколько различных пар (модель, ступень) в карте ниже: роль
У ревьюера `adversarial-reviewer` репо-локального определения намеренно задаёт бриф-файл, определение — только ступень и модель. В
нет: рабочие фолбэки — `deep-reasoner` (обкатан ревью 2026-07-12) или новом репозитории их нет — проверь `ls .claude/agents/` и при отсутствии
`general-purpose` со скептическим промптом (см. «Роли» в SKILL.md). предложи пользователю создать файлы ниже как есть. Определение — не
только удобство: `effort:` во фронтматтере — единственный канал, которым
оркестратор задаёт ступень эффорта субагенту (у Agent-тула ручки effort
нет — проверено по схеме 2026-07-31; в Workflow-скриптах ступень
задаётся на вызов через `opts.effort`, но конвейер ходит субагентами);
без определения агент приедет на эффорте сессии. Поэтому роль с другой
ступенью — это другой агент, а не другой вызов.
## Карта «роль → модель и ступень»
По цене *тихой* ошибки этапа, не по сложности (решение пользователя
2026-07-26 под Opus 5; `xhigh` не дефолтить):
- `high` — ревью постановок и планов: `deep-reasoner`. Дефект
каскадирует — отравляет реализацию, оба ревью и триаж.
- `medium` — слепое ревью, узкие перепроверки и вкусовая реализация:
`craftsman`. Ревью — последняя линия обороны своей линзы, пропуск
тихий, ниже не опускать даже при двух ревьюерах (линзы разные,
избыточность не дублирование); ошибка реализации громкая — за ней
саморевью, оба ревью и приёмка; вкус едет с моделью, не с эффортом.
- default — механика: `fast-worker` (Sonnet). Ошибка громкая, эффорт не
крутить вовсе.
Карта задаёт минимум для роли, не ограничение для агента: на линии
постановок `deep-reasoner` — штатный ход, а на линии слепого ревью —
временный фолбэк при отсутствии `craftsman` (обкатан ревью 2026-07-12),
там он приедет ступенью выше карты.
## Конструкция оркестрации (фрагмент CLAUDE.md репозитория) ## Конструкция оркестрации (фрагмент CLAUDE.md репозитория)
@@ -13,9 +39,11 @@
## Orchestration workflow ## Orchestration workflow
You (Fable) are the orchestrator. Plan, decompose, synthesize. You (Fable) are the orchestrator. Plan, decompose, synthesize.
Reasoning-heavy phases → deep-reasoner Reasoning-heavy phases → deep-reasoner
Human-facing work (prose, interfaces, names) → craftsman
Mechanical work → fast-worker Mechanical work → fast-worker
Codex (/codex:rescue --background) is a cracked engineer on par with Codex (direct `codex exec`, see claude-subagent-playbook) is a cracked
deep-reasoner, from a different perspective. Treat as a peer, not a reviewer. engineer from a different model family: implementer for technical work
and an independent blind review line.
High-stakes decisions: task Opus + Codex on the same problem in parallel, High-stakes decisions: task Opus + Codex on the same problem in parallel,
synthesize the best of both, without showing either the other's answer. synthesize the best of both, without showing either the other's answer.
Keep your own context lean. Keep your own context lean.
@@ -62,6 +90,41 @@ Lead with the conclusion. Then, only if it adds value:
Keep it tight. Your value is the quality of the conclusion, not its length. Keep it tight. Your value is the quality of the conclusion, not its length.
``` ```
## `.claude/agents/craftsman.md`
```markdown
---
name: craftsman
description: >
Opus at medium effort for prepared briefs: tasteful implementation of
a self-contained task file, a blind review line, a narrow re-check.
The brief carries the mandate; taste — form, proportion, naming — is
why this agent and not a mechanical one.
model: opus
effort: medium
color: blue
---
# Craftsman
You execute the prepared brief the orchestrator names — a self-contained
task file or an assembled review prompt. The brief carries your mandate
and output format: follow it exactly; if something seems wrong, do what
is written and flag the doubt in your report.
## Operating stance
- You are chosen for taste: honest names, proportionate solutions, no
artifact that does not earn its existence. Match the repository's
conventions and voice; read a neighbouring file when unsure.
- Implementing: stay inside the task's boundaries, no commits; report
files changed with a one-line "why" each, test command and counters,
checkbox status, doubts.
- Reviewing: stay blind — judge only what the brief and the repository
give you; empirical checks beat reading; findings exactly in the
index format the brief demands.
```
## `.claude/agents/fast-worker.md` ## `.claude/agents/fast-worker.md`
```markdown ```markdown
@@ -381,31 +381,14 @@ Opus 5 по отдаче ближе к прежнему `xhigh`, а `medium` —
главный предел — от уверенной выдумки внешних фактов не страхует никакой главный предел — от уверенной выдумки внешних фактов не страхует никакой
эффорт (казус CODE-1). эффорт (казус CODE-1).
### Открытый вопрос 2026-07-26: чем координатор выставляет effort субагенту ### Открытый вопрос 2026-07-26 — закрыт 2026-07-31
Правило «effort задавай явно» предполагает, что ручка у оркестратора Проверено по схеме Agent-тула: ручки `effort` у него нет — ступень
есть. По схеме Agent-тула в текущем харнессе её нет: параметры вызова — задаётся только `effort:` во фронтматтере определения агента или
`model`, `subagent_type`, `isolation`, `run_in_background`, но не `opts.effort` в Workflow. Поглощено рефакторингом 2026-07-31: карта в
`effort`. Достоверно ступень задаётся двумя путями: фронтматтером в SKILL.md переписана на определения, в claude-agents.md добавлена
определении агента (`effort:` — как у `deep-reasoner`) и `opts.effort` в заготовка `adversarial-reviewer` (opus, medium), фолбэк «скептический
скрипте Workflow. Значит для разового вызова без определения — вариант general-purpose» снят.
«скептический `general-purpose`» из SKILL.md, этап 4 — карта
нереализуема: агент приедет на эффорте сессии.
Обход, доступный уже сейчас (решение пользователя): нужного субагента
нет в репозитории — **предложи пользователю его создать** по заготовке
из [claude-agents.md](claude-agents.md) (в том числе роль с нужным
`effort:` во фронтматтере) и дальше работай уже им, а не разовым
`general-purpose`. Определение — одноразовая цена, ступень и модель
после него заданы явно и переживают сессию. Заводить молча не надо:
файлы в `.claude/agents/` — территория пользователя.
Пользователь предполагал, что ручка координатору доступна, — проверить
на ближайшем прогоне. Если подтвердится, что нет, это тема рефакторинга
скилла: либо карта явно расписывается «через определение агента / через
Workflow», либо для каждой роли карты заводится определение с пришитым
эффортом (и фолбэк «скептический general-purpose» из этапа 4 уходит).
До проверки карту не переписывать — вопрос механики, не решения.
### 2026-07-30: классификатор авторежима блокирует `-s danger-full-access` ### 2026-07-30: классификатор авторежима блокирует `-s danger-full-access`
@@ -510,9 +493,11 @@ compose down`); отдельных событий эскалации в `--json`
одно из двух ревью этого не видело. Приёмка оркестратора нашла то, чего одно из двух ревью этого не видело. Приёмка оркестратора нашла то, чего
не нашли обе линии — потому что запускала иначе. не нашли обе линии — потому что запускала иначе.
Эти четыре правила пока живут только здесь — то есть повторяют ровно тот Поглощено рефакторингом 2026-07-31: обёртка Клод-ревьюера
отказ, который диагностирует запись выше. Поглощение — в рефакторинге (инкрементальная запись индекса), «Сбои координации» SKILL.md (признак
(см. открытый вопрос ниже). жизни — уведомление; замене — другой путь вердикта; среда — своими
глазами), этап 4 (стенд одной линии), этап 6 (stdin фонового запуска),
мандат review-boilerplate (глубина один; проверка восстановления среды).
**Цифры:** тикет — 20 критериев, переписан дважды (двойное ревью постановки **Цифры:** тикет — 20 критериев, переписан дважды (двойное ревью постановки
сняло невозможный критерий: ноды кластера — шарды, не реплики). Саморевью сняло невозможный критерий: ноды кластера — шарды, не реплики). Саморевью
@@ -522,65 +507,38 @@ compose down`); отдельных событий эскалации в `--json`
пороге 3,4 ГБ, `make smoke-cluster` 8/8 за 7 с — и одно зависание на 23 пороге 3,4 ГБ, `make smoke-cluster` 8/8 за 7 с — и одно зависание на 23
минуты до починки. минуты до починки.
### Открытый вопрос 2026-07-31: рефакторинг заготовок линий ### Открытый вопрос 2026-07-31 — закрыт рефакторингом того же дня
Решение пользователя: скилл важный и работает регулярно, структурные - Константы — файлами в `prompts/`: line-task, line-code, line-rev,
правки — отдельной осознанной работой, не походя. Накопилось на один self-review; вкусовая линза с базой двенадцати запахов Фаулера из
заход: `/code-review` Мэтта Покока — `line-taste.md`, разрез — выбором файла
в `cat`. Оттуда же правило «линии не сливать в один ранжир» — этап 5.
- `line-task.md` / `line-code.md` не содержат ни одного `{{...}}` — это - Третья ось — вкус: матрица Тео (@t3dotgg) получена от пользователя с
константы, но лежат не в `prompts/`, и оркестратор перепечатывает их поправкой под gpt-5.6-sol/Opus 5 (интеллект вырос, вкус прежний) —
Write'ом каждый прогон. Тот самый канал дрейфа, ради которого правка references/model-matrix.md. Разрез по подзадачам на этапе 1, сначала
2026-07-31 и делалась. Перенести в `prompts/`, подшивать `cat`'ом; вкусовая часть (задаёт форму), один писатель в дереве — в силе.
блок `Taste:` — отдельным файлом, тогда разрез по родословной станет - «Родословная» разведена на **семейство** (классы находок) и
выбором файла, а не пересказом границы. **свежесть** (независимость от автора): «Роли» и этап 4 — линия
- Четыре правила координации выше поглотить в механизм: два — в обёртку дефектов по различию семейства, линия уместности по умению (модель со
вызова Клод-ревьюера (свой путь вердикта, инкрементальная запись), два — вкусом), при высокой цене ошибки уместность — третьей модели. Перенос
в «Сбои координации» SKILL.md (проверка среды своими руками, стенд не из `AGENTS.md` стенда кликстрима состоялся.
делить между линиями). - Дополнение того же дня (решение пользователя): вкусовую реализацию
- Заодно проверить остальные заготовки на то же расхождение «константа ведёт `craftsman` (opus, `medium`) — ошибка реализации громкая,
живёт в документации вместо `prompts/`». конвейер ловит, вкус едет с моделью, не с эффортом; `high` на
- **Третья ось выбора — вкус.** Наши две ручки (эффорт, модель) обе про реализации не дефолтить.
силу; матрица Тео (@t3dotgg) разводит стоимость, интеллект и вкус и - Слепое ревью рефакторинга (Опус, по writing-great-skills):
заставляет выбирать исполнителя на каждую задачу, а не наследовать CHANGES_REQUIRED — 7 MAJOR, 17 MINOR, 3 NIT; закрыто тем же днём.
дефолт. Прогон #18 показал цену: код технически безупречен и при этом Главное: эффорт-карта с обоснованиями демотирована в claude-agents.md
неправильной формы. Решение пользователя 2026-07-31 — то, что читает (SSOT — там, где живут `effort:`), хвост «Ролей» ужат втрое, фрагмент
человек, пишет модель со вкусом (в учебном репозитории это почти всё); CLAUDE.md приведён к прямому exec и ревью-линии Codex, критерий
Кодексу — техническая работа, где его лимиты и работают на нас; ось этапа 3 обобщён на двух исполнителей, конфликт имён этапа 2 снят
ревью переворачивается. **Спроси у пользователя матрицу и примеры её (ревьюер постановок — `deep-reasoner`). Отклонено два: порог
применения**: числа Тео расписаны под другой набор моделей (gpt-5.5, «вкус ≥ 7» (содержательная граница: пропускает Sonnet, отсекает Sol) и
opus-4.8) и требуют пересчёта под наш. мандат внутри определения `craftsman` (определение уезжает в
Разрез идёт не по тикету, а **по подзадачам, и назначается на этапе 1**: репозитории без скилла — самодостаточность важнее дедупликации).
что человек будет читать и разбирать — Опусу, руки (сборка образа, - Позже тем же днём (решение пользователя): три Опус-определения
обвязка проверок, повторяющиеся правки) — Кодексу. Два ограничения. избыточны — определений нужно ровно столько, сколько различных пар
Порядок: сначала вкусовая часть — она задаёт форму, имена и границы, (модель, ступень) в карте, а роли живут в бриф-файлах.
под которые механическая потом подстраивается; наоборот получится `adversarial-reviewer` слит в `craftsman` (opus, medium — исполнение
ретрофит. И один писатель в дереве остаётся в силе — либо брифов: вкусовая реализация, слепое ревью, перепроверки); упоминание
последовательно, либо по разным worktree, шов вести по файлам, которые заготовки adversarial-reviewer в записях выше — история того дня.
не пересекаются.
- **Под «родословной» ехали два механизма.** Различие семейств нужно для
покрытия классов ошибок, свежая сессия — для независимости от рассуждений
автора. Пока они склеены, разговор о ревью упирается в ложный выбор между
независимостью и компетентностью: «линию уместности ведёт тот, кто не
писал» звучит безупречно и при Опусе-исполнителе отдаёт вкусовую линию
Кодексу, у которого вкуса нет. Разведя механизмы, получаем два основания:
линия дефектов назначается по различию, линия уместности — по умению,
даже если умеет автор. Плата — общая слепота автора и ревьюера одной
родословной проходит дважды; гасится свежей сессией и другой линзой, но
не до конца, поэтому при высокой цене ошибки линию уместности берёт
третья модель. Принято 2026-07-31 в `AGENTS.md` стенда кликстрима; в
плейбуке этап 4 и эффорт-карта всё ещё исходят из того, что пишет всегда
Codex, — при рефакторинге решить, переносить ли.
- **Принести ревьюеру набор запахов.** В `/code-review` Мэтта Покока
(`~/dotfiles/agents/.agents/skills/code-review/SKILL.md`) есть готовая
база из двенадцати запахов Фаулера, которая вклеивается ревьюеру в
промпт целиком, с оговорками «документированный стандарт репозитория
побеждает» и «каждый запах — суждение, не нарушение». Это сильнее моих
трёх самодельных примеров в блоке `Taste:`: имена вроде Speculative
Generality или Data Clumps — слова из претрейна, они поднимают целый
пласт поведения, а пересказ своими словами — нет. Наши CODE и TASK
повторяют его оси Standards и Spec, придуманные независимо; забрать
оттуда стоит и правило «находки двух осей не сливать и не
переранжировать» — оно прямо про то, как уверенный вердикт одной линии
закрывает собой другую. Показательно, что Codex-ревьюер #18 открыл этот
файл сам первой командой прогона: механизма нет, а нужда есть.
@@ -0,0 +1,45 @@
# Три оси выбора исполнителя: цена, интеллект, вкус
Эффорт и модель — ручки силы; вкус ими не выражается (прогон #18: код
технически безупречен и при этом неправильной формы). Ось вкуса задаёт
разрез по подзадачам (этап 1 SKILL.md) и линию уместности ревью
(этап 4).
Матрица — калибровка Тео (@t3dotgg) под его стек (gpt-5.5, opus-4.8),
принята пользователем 2026-07-31 с поправкой: актуальны gpt-5.6-sol и
Opus 5, оба заметно выросли в интеллекте, вкус остался примерно тем же.
Числа — порядок, не измерение. `affordability` — практическая
доступность лимитов у нас, 9 — почти бесплатно (не публичные цены);
`intelligence` — сложность работы, которую можно отдать без надзора;
`taste` — суждение в UI/UX, качестве кода, дизайне API, именах и
тексте.
| модель | affordability | intelligence | taste |
| ----------- | ------------: | -----------: | ----: |
| gpt-5.6-sol | 9 | ~9 | 5 |
| sonnet-5 | 5 | 5 | 7 |
| opus-5 | 4 | ~8 | 8 |
| fable-5 | 2 | 9 | 9 |
## Правила применения
Оценки — дефолты, не запреты. Разрешение эскалировать без вопроса
действует всегда: слабая модель выдала ниже стандарта — повтори более
сильной; суди результат, не цену модели.
- Цена решает только там, где разница в качестве неважна. Для того, что
уйдёт в продукт, интеллект и вкус важнее цены.
- Всё, что читает человек, пишет модель со вкусом ≥ 7: интерфейсы,
проза и продуктовый текст, публичные API и контракты, имена,
архитектурные решения, задающие форму системы (в учебном репозитории
это почти всё). Дефолт вкусовой части — Опус.
- Дешёвые модели собирают, сильные судят: обследование репозитория,
чтение объёмов, механика, реализация по жёсткой спеке — дешёвым;
результат переносится сильной модели там, где нужно суждение. Токены
Fable и Опуса на объёмную работу без суждения не тратить.
- Fable держи для самого трудного: оркестрация, архитектура, задачи,
где интеллект и вкус нужны одновременно.
Механика вызова: Claude-модели — параметром `model` (Agent/Workflow) и
определениями из [claude-agents.md](claude-agents.md); Codex — прямым
`codex exec` ([codex-exec.md](codex-exec.md)).
@@ -6,6 +6,14 @@
- [prompts/review-boilerplate.md](prompts/review-boilerplate.md) — мандат - [prompts/review-boilerplate.md](prompts/review-boilerplate.md) — мандат
ревьюера + формат индекса находок (этапы 2 и 4). ревьюера + формат индекса находок (этапы 2 и 4).
- [prompts/line-task.md](prompts/line-task.md) /
[prompts/line-code.md](prompts/line-code.md) /
[prompts/line-rev.md](prompts/line-rev.md) — файлы линий ревью: линза и
префикс ID (две слепые линии / одиночный ревьюер).
- [prompts/line-taste.md](prompts/line-taste.md) — вкусовая линза с базой
запахов Фаулера; подшивается к линии уместности (этап 4 SKILL.md).
- [prompts/self-review.md](prompts/self-review.md) — саморевью
исполнителя (этап 3, resume тем же тредом).
- [prompts/triage-header.md](prompts/triage-header.md) — правила триажа - [prompts/triage-header.md](prompts/triage-header.md) — правила триажа
для исполнителя (этап 5). для исполнителя (этап 5).
- [prompts/recheck-header.md](prompts/recheck-header.md) — узкая - [prompts/recheck-header.md](prompts/recheck-header.md) — узкая
@@ -29,7 +37,7 @@
переживает. Windows-кавеат из codex-exec.md в силе: путь — переживает. Windows-кавеат из codex-exec.md в силе: путь —
forward-slash, не голый `/tmp` Git Bash. forward-slash, не голый `/tmp` Git Bash.
- Через Write оркестратор пишет **только параметрические блоки** ниже; - Через Write оркестратор пишет **только параметрические блоки** ниже;
плейсхолдеры `{{...}}` — значения задачи, секции «adapt» — по смыслу. секции «adapt» — по смыслу.
Сборка на прогон: `D="$SCRATCH/<NN-slug>"` — подпапка задачи; `P` — Сборка на прогон: `D="$SCRATCH/<NN-slug>"` — подпапка задачи; `P` —
`references/prompts` в базовом каталоге скилла (путь даётся в шапке `references/prompts` в базовом каталоге скилла (путь даётся в шапке
@@ -37,10 +45,15 @@
```bash ```bash
cat "$D/task-body.md" "$P/runtime-language.md" > "$D/task-prompt.md" cat "$D/task-body.md" "$P/runtime-language.md" > "$D/task-prompt.md"
cat "$D/review-params.md" "$D/line-task.md" "$P/review-boilerplate.md" \ cat "$D/review-params.md" "$P/line-task.md" "$P/line-taste.md" \
"$P/runtime-language.md" > "$D/review-prompt-task.md" "$P/review-boilerplate.md" "$P/runtime-language.md" \
# вторая линия: line-code.md -> review-prompt-code.md; > "$D/review-prompt-task.md"
# одиночный ревьюер: line-rev.md -> review-prompt.md cat "$D/review-params.md" "$P/line-code.md" \
"$P/review-boilerplate.md" "$P/runtime-language.md" \
> "$D/review-prompt-code.md"
# одиночный ревьюер: line-rev.md (+ line-taste.md) -> review-prompt.md
# line-taste.md едет с линией уместности — переставь, если её ведёт
# другая линия (назначение линий — этап 4 SKILL.md)
cat "$P/triage-header.md" "$D/review-codex.md" "$D/review-claude.md" \ cat "$P/triage-header.md" "$D/review-codex.md" "$D/review-claude.md" \
"$D/notes.md" "$P/runtime-language.md" > "$D/fix-prompt.md" "$D/notes.md" "$P/runtime-language.md" > "$D/fix-prompt.md"
# notes.md опционален — нет, так не включай # notes.md опционален — нет, так не включай
@@ -91,15 +104,16 @@ will run it before the reviews start.
Отдельным ходом после отчёта о реализации, до внешних ревью — смена рамки Отдельным ходом после отчёта о реализации, до внешних ревью — смена рамки
«автор → критик» отдельным ходом ловит больше, чем финальный пункт «автор → критик» отдельным ходом ловит больше, чем финальный пункт
чек-листа в промпте задачи: чек-листа в промпте задачи. Текст готов файлом:
```text ```bash
Now switch roles: you are a reviewer of your own diff. Walk it against the cat "$P/self-review.md" | codex exec resume <thread-id> ...
task's acceptance criteria and boundaries. Fix what you find, stay inside
the task scope. Return one line: SELF-REVIEW: found N, fixed N — plus one
phrase per unfixed item, if any.
``` ```
Опус-исполнителю (`craftsman`) — тот же файл продолжением его треда:
запускай его с `name` и шли SendMessage
«read and execute $P/self-review.md».
## 2. Ревью: общий блок + файл линии ## 2. Ревью: общий блок + файл линии
Общий параметрический блок (`review-params.md`) один на обе линии и не Общий параметрический блок (`review-params.md`) один на обе линии и не
@@ -111,17 +125,20 @@ phrase per unfixed item, if any.
```text ```text
Read {{path to this line's review prompt}} and execute it. Working directory: Read {{path to this line's review prompt}} and execute it. Working directory:
{{repo root}}. Write the full findings index to {{repo root}}. Write the findings index to
{{$D/review-claude.md}} — it is outside the repo, so the mandate allows {{$D/review-claude.md}} — it is outside the repo, so the mandate allows
it (via Write or a Bash heredoc, whichever you have). Keep the index it (via Write or a Bash heredoc, whichever you have). Append each finding
strict: ONE line per finding and per confirmation, as the boilerplate to that file as you go — incremental writing keeps a partial index alive
demands — no multi-line entries. Final message: ONLY the VERDICT line, if the session dies. Keep the index strict: ONE line per finding and per
severity counters and the file path. confirmation, as the boilerplate demands — no multi-line entries. Final
message: ONLY the VERDICT line, severity counters and the file path.
``` ```
(Однострочность продублирована в обёртке не случайно: boilerplate это уже (Однострочность продублирована в обёртке не случайно: boilerplate это уже
требует, но Клод-родословная держит формат хуже Codex — эмпирика требует, но Клод-семейство держит формат хуже Codex — эмпирика
2026-07-12/13, многострочные находки и развёрнутые confirmations.) 2026-07-12/13, многострочные находки и развёрнутые confirmations.)
Замене молчащего ревьюера давай **другой** путь вердикта — правило в
«Сбоях координации» SKILL.md.
```markdown ```markdown
# Code review: {{ticket NN — essence}} # Code review: {{ticket NN — essence}}
@@ -140,36 +157,16 @@ Test command (expect {{N}} passed): {{command}}
shared code}} shared code}}
``` ```
Файлы линий (`line-task.md` / `line-code.md`), по одному на слепую линию: Файлы линий — готовые константы в `prompts/`, оркестратор их не
перепечатывает: `line-task.md` (уместность: постановка, критерии,
```markdown границы), `line-code.md` (дефекты: корректность, инварианты, регрессии),
## Your line одиночному ревьюеру — `line-rev.md` (обе линзы, префикс `REV`).
FINDING PREFIX: TASK Вкусовая линза с базой запахов — `line-taste.md`; она едет с **линией
Lens: compliance with the statement, acceptance criteria, boundaries, уместности** (её ведёт модель со вкусом — назначение линий в этапе 4
intended observable result. SKILL.md), поэтому разрез — выбором файла в `cat`, не пересказом
Taste: formally correct but substantively wrong is a finding — work out of границы. Стенд делится между линиями? Явный запрет ломающих команд
proportion to the task, an added artifact that does not earn its второй линии — отдельным параметрическим файлом `$D/access-<line>.md`,
existence, a check that passes without proving its own claim. Grade a подшитым после файла линии (правило — этап 4 SKILL.md).
taste finding by the cost of living with the code, not by whether it
breaks a test.
```
```markdown
## Your line
FINDING PREFIX: CODE
Lens: correctness, invariants, regressions, security, test honesty.
```
Одиночному ревьюеру (простая ступень шкалы этапа 4) — один `line-rev.md`
с обеими линзами и префиксом `REV`. По эмпирике прогонов естественное
распределение: Codex — CODE (дефекты нового кода), Клод — TASK (уровень
задачи и архитектуры).
Блок `Taste:` едет с **родословной**, а не с буквой линии: он адресован
Клоду (решение пользователя 2026-07-23, запись в
[lessons.md](lessons.md)). При обычном распределении и у одиночного
ревьюера он уже на месте — обоих ведёт Клод. Поменялись родословными —
переставь блок целиком туда, где Клод.
Вариант для **этапа 2** (ревью постановки, кода изменений ещё нет) — тот же Вариант для **этапа 2** (ревью постановки, кода изменений ещё нет) — тот же
boilerplate, другой параметрический блок: boilerplate, другой параметрический блок:
@@ -192,8 +189,9 @@ Code to check the statement's facts against: {{file list with why}}
criteria checkable and gameable?, observability}} criteria checkable and gameable?, observability}}
``` ```
Файл линии — тем же механизмом: только префикс (`SPEC-A` / `SPEC-B`, Файл линии здесь — двухстрочный Write (`## Your line` +
одиночному обзору — `SPEC`); линза уже задана рамкой блока. `FINDING PREFIX: SPEC-A|SPEC-B|SPEC`): константного файла нет
намеренно — префикс варьируется, а линза уже задана рамкой блока.
## 3. Параметрические хвосты триажа и перепроверки ## 3. Параметрические хвосты триажа и перепроверки
@@ -0,0 +1,3 @@
## Your line
FINDING PREFIX: CODE
Lens: correctness, invariants, regressions, security, test honesty.
@@ -0,0 +1,5 @@
## Your line
FINDING PREFIX: REV
Lens: correctness, invariants, regressions, security, test honesty; plus
compliance with the statement, acceptance criteria, boundaries, intended
observable result.
@@ -0,0 +1,4 @@
## Your line
FINDING PREFIX: TASK
Lens: compliance with the statement, acceptance criteria, boundaries,
intended observable result.
@@ -0,0 +1,38 @@
## Taste
Formally correct but substantively wrong is a finding: work out of
proportion to the task, an added artifact that does not earn its
existence, a check that passes without proving its own claim. Grade a
taste finding by the cost of living with the code, not by whether it
breaks a test.
Match the changes against this smell baseline (Fowler, _Refactoring_,
ch. 3). Two rules bind it: a documented repo standard overrides the
baseline, and every smell is a judgement call to label ("possible
Feature Envy"), never a hard violation. Skip anything tooling already
enforces.
- **Mysterious Name** — the name hides what it does or holds → rename;
if no honest name comes, the design is murky.
- **Duplicated Code** — the same logic shape in more than one place →
extract the shared shape, call it from both.
- **Feature Envy** — a method works another object's data more than its
own → move it onto the data it envies.
- **Data Clumps** — the same few fields or params keep travelling
together → bundle them into one type, pass that.
- **Primitive Obsession** — a primitive or string stands in for a domain
concept → give the concept its own small type.
- **Repeated Switches** — the same type-dispatch cascade recurs across
the change → polymorphism, or one map both sites share.
- **Shotgun Surgery** — one logical change forces scattered edits across
many files → gather what changes together into one module.
- **Divergent Change** — one module edited for several unrelated reasons
→ split so each part changes for one reason.
- **Speculative Generality** — abstraction, parameters, or hooks for
needs the spec does not have → delete; inline until a real need shows.
- **Message Chains** — long `a.b().c().d()` navigation the caller should
not depend on → hide the walk behind one method on the first object.
- **Middle Man** — a unit that mostly delegates onward → cut it, call
the real target direct.
- **Refused Bequest** — an implementer ignores or overrides most of what
it inherits → drop the inheritance, use composition.
@@ -5,6 +5,11 @@
allowed and encouraged; safe empirical checks in temp dirs outside the allowed and encouraged; safe empirical checks in temp dirs outside the
repo make a verdict much firmer than reading alone. repo make a verdict much firmer than reading alone.
- No `git add` / `git commit` / `git checkout`. - No `git add` / `git commit` / `git checkout`.
- Work alone, depth one: no subagents, no delegating parts of the review.
- Leave the environment as you found it; if you stop or restart services,
verify the restoration actually took effect (e.g. `docker compose ps
-a`) — a trap that should have restored state is not evidence that it
did.
- Output only the findings index and the VERDICT line — no code retelling, - Output only the findings index and the VERDICT line — no code retelling,
no narrative. Where to put it: your call wrapper says, or it is your no narrative. Where to put it: your call wrapper says, or it is your
`-o` report if you were invoked via stdin. `-o` report if you were invoked via stdin.
@@ -12,7 +17,7 @@
## Findings file format — index only ## Findings file format — index only
One line per finding, with a stable ID (FINDING PREFIX comes from your One line per finding, with a stable ID (FINDING PREFIX comes from your
parameter block): line block):
PREFIX-N | BLOCKER|MAJOR|MINOR|NIT | file:line (or spec/task-file section) | one-phrase essence | how to verify/reproduce PREFIX-N | BLOCKER|MAJOR|MINOR|NIT | file:line (or spec/task-file section) | one-phrase essence | how to verify/reproduce
@@ -0,0 +1,4 @@
Now switch roles: you are a reviewer of your own diff. Walk it against
the task's acceptance criteria and boundaries. Fix what you find, stay
inside the task scope. Return one line: SELF-REVIEW: found N, fixed N —
plus one phrase per unfixed item, if any.