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,37 @@
# Репо-локальные Claude-субагенты и конструкция оркестрации
`deep-reasoner` и `fast-worker` — субагенты уровня репозитория
(`.claude/agents/*.md`), не глобальные. В новом репозитории их нет — проверь
`ls .claude/agents/` и при отсутствии создай файлы ниже как есть.
У ревьюера `adversarial-reviewer` репо-локального определения намеренно
нет: рабочие фолбэки — `deep-reasoner` (обкатан ревью 2026-07-12) или
`general-purpose` со скептическим промптом (см. «Роли» в SKILL.md).
`deep-reasoner`, `craftsman` и `fast-worker` — субагенты уровня
репозитория (`.claude/agents/*.md`), не глобальные. Определений ровно
столько, сколько различных пар (модель, ступень) в карте ниже: роль
задаёт бриф-файл, определение — только ступень и модель. В
новом репозитории их нет — проверь `ls .claude/agents/` и при отсутствии
предложи пользователю создать файлы ниже как есть. Определение — не
только удобство: `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 репозитория)
@@ -13,9 +39,11 @@
## Orchestration workflow
You (Fable) are the orchestrator. Plan, decompose, synthesize.
Reasoning-heavy phases → deep-reasoner
Human-facing work (prose, interfaces, names) → craftsman
Mechanical work → fast-worker
Codex (/codex:rescue --background) is a cracked engineer on par with
deep-reasoner, from a different perspective. Treat as a peer, not a reviewer.
Codex (direct `codex exec`, see claude-subagent-playbook) is a cracked
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,
synthesize the best of both, without showing either the other's answer.
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.
```
## `.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`
```markdown
@@ -381,31 +381,14 @@ Opus 5 по отдаче ближе к прежнему `xhigh`, а `medium` —
главный предел — от уверенной выдумки внешних фактов не страхует никакой
эффорт (казус CODE-1).
### Открытый вопрос 2026-07-26: чем координатор выставляет effort субагенту
### Открытый вопрос 2026-07-26 — закрыт 2026-07-31
Правило «effort задавай явно» предполагает, что ручка у оркестратора
есть. По схеме Agent-тула в текущем харнессе её нет: параметры вызова —
`model`, `subagent_type`, `isolation`, `run_in_background`, но не
`effort`. Достоверно ступень задаётся двумя путями: фронтматтером в
определении агента (`effort:` — как у `deep-reasoner`) и `opts.effort` в
скрипте Workflow. Значит для разового вызова без определения — вариант
«скептический `general-purpose`» из SKILL.md, этап 4 — карта
нереализуема: агент приедет на эффорте сессии.
Обход, доступный уже сейчас (решение пользователя): нужного субагента
нет в репозитории — **предложи пользователю его создать** по заготовке
из [claude-agents.md](claude-agents.md) (в том числе роль с нужным
`effort:` во фронтматтере) и дальше работай уже им, а не разовым
`general-purpose`. Определение — одноразовая цена, ступень и модель
после него заданы явно и переживают сессию. Заводить молча не надо:
файлы в `.claude/agents/` — территория пользователя.
Пользователь предполагал, что ручка координатору доступна, — проверить
на ближайшем прогоне. Если подтвердится, что нет, это тема рефакторинга
скилла: либо карта явно расписывается «через определение агента / через
Workflow», либо для каждой роли карты заводится определение с пришитым
эффортом (и фолбэк «скептический general-purpose» из этапа 4 уходит).
До проверки карту не переписывать — вопрос механики, не решения.
Проверено по схеме Agent-тула: ручки `effort` у него нет — ступень
задаётся только `effort:` во фронтматтере определения агента или
`opts.effort` в Workflow. Поглощено рефакторингом 2026-07-31: карта в
SKILL.md переписана на определения, в claude-agents.md добавлена
заготовка `adversarial-reviewer` (opus, medium), фолбэк «скептический
general-purpose» снят.
### 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 критериев, переписан дважды (двойное ревью постановки
сняло невозможный критерий: ноды кластера — шарды, не реплики). Саморевью
@@ -522,65 +507,38 @@ compose down`); отдельных событий эскалации в `--json`
пороге 3,4 ГБ, `make smoke-cluster` 8/8 за 7 с — и одно зависание на 23
минуты до починки.
### Открытый вопрос 2026-07-31: рефакторинг заготовок линий
### Открытый вопрос 2026-07-31 — закрыт рефакторингом того же дня
Решение пользователя: скилл важный и работает регулярно, структурные
правки — отдельной осознанной работой, не походя. Накопилось на один
заход:
- `line-task.md` / `line-code.md` не содержат ни одного `{{...}}` — это
константы, но лежат не в `prompts/`, и оркестратор перепечатывает их
Write'ом каждый прогон. Тот самый канал дрейфа, ради которого правка
2026-07-31 и делалась. Перенести в `prompts/`, подшивать `cat`'ом;
блок `Taste:` — отдельным файлом, тогда разрез по родословной станет
выбором файла, а не пересказом границы.
- Четыре правила координации выше поглотить в механизм: два — в обёртку
вызова Клод-ревьюера (свой путь вердикта, инкрементальная запись), два —
в «Сбои координации» SKILL.md (проверка среды своими руками, стенд не
делить между линиями).
- Заодно проверить остальные заготовки на то же расхождение «константа
живёт в документации вместо `prompts/`».
- **Третья ось выбора — вкус.** Наши две ручки (эффорт, модель) обе про
силу; матрица Тео (@t3dotgg) разводит стоимость, интеллект и вкус и
заставляет выбирать исполнителя на каждую задачу, а не наследовать
дефолт. Прогон #18 показал цену: код технически безупречен и при этом
неправильной формы. Решение пользователя 2026-07-31 — то, что читает
человек, пишет модель со вкусом (в учебном репозитории это почти всё);
Кодексу — техническая работа, где его лимиты и работают на нас; ось
ревью переворачивается. **Спроси у пользователя матрицу и примеры её
применения**: числа Тео расписаны под другой набор моделей (gpt-5.5,
opus-4.8) и требуют пересчёта под наш.
Разрез идёт не по тикету, а **по подзадачам, и назначается на этапе 1**:
что человек будет читать и разбирать — Опусу, руки (сборка образа,
обвязка проверок, повторяющиеся правки) — Кодексу. Два ограничения.
Порядок: сначала вкусовая часть — она задаёт форму, имена и границы,
под которые механическая потом подстраивается; наоборот получится
ретрофит. И один писатель в дереве остаётся в силе — либо
последовательно, либо по разным worktree, шов вести по файлам, которые
не пересекаются.
- **Под «родословной» ехали два механизма.** Различие семейств нужно для
покрытия классов ошибок, свежая сессия — для независимости от рассуждений
автора. Пока они склеены, разговор о ревью упирается в ложный выбор между
независимостью и компетентностью: «линию уместности ведёт тот, кто не
писал» звучит безупречно и при Опусе-исполнителе отдаёт вкусовую линию
Кодексу, у которого вкуса нет. Разведя механизмы, получаем два основания:
линия дефектов назначается по различию, линия уместности — по умению,
даже если умеет автор. Плата — общая слепота автора и ревьюера одной
родословной проходит дважды; гасится свежей сессией и другой линзой, но
не до конца, поэтому при высокой цене ошибки линию уместности берёт
третья модель. Принято 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 открыл этот
файл сам первой командой прогона: механизма нет, а нужда есть.
- Константы — файлами в `prompts/`: line-task, line-code, line-rev,
self-review; вкусовая линза с базой двенадцати запахов Фаулера из
`/code-review` Мэтта Покока — `line-taste.md`, разрез — выбором файла
в `cat`. Оттуда же правило «линии не сливать в один ранжир» — этап 5.
- Третья ось — вкус: матрица Тео (@t3dotgg) получена от пользователя с
поправкой под gpt-5.6-sol/Opus 5 (интеллект вырос, вкус прежний) —
references/model-matrix.md. Разрез по подзадачам на этапе 1, сначала
вкусовая часть (задаёт форму), один писатель в дереве — в силе.
- «Родословная» разведена на **семейство** (классы находок) и
**свежесть** (независимость от автора): «Роли» и этап 4 — линия
дефектов по различию семейства, линия уместности по умению (модель со
вкусом), при высокой цене ошибки уместность — третьей модели. Перенос
из `AGENTS.md` стенда кликстрима состоялся.
- Дополнение того же дня (решение пользователя): вкусовую реализацию
ведёт `craftsman` (opus, `medium`) — ошибка реализации громкая,
конвейер ловит, вкус едет с моделью, не с эффортом; `high` на
реализации не дефолтить.
- Слепое ревью рефакторинга (Опус, по writing-great-skills):
CHANGES_REQUIRED — 7 MAJOR, 17 MINOR, 3 NIT; закрыто тем же днём.
Главное: эффорт-карта с обоснованиями демотирована в claude-agents.md
(SSOT — там, где живут `effort:`), хвост «Ролей» ужат втрое, фрагмент
CLAUDE.md приведён к прямому exec и ревью-линии Codex, критерий
этапа 3 обобщён на двух исполнителей, конфликт имён этапа 2 снят
(ревьюер постановок — `deep-reasoner`). Отклонено два: порог
«вкус ≥ 7» (содержательная граница: пропускает Sonnet, отсекает Sol) и
мандат внутри определения `craftsman` (определение уезжает в
репозитории без скилла — самодостаточность важнее дедупликации).
- Позже тем же днём (решение пользователя): три Опус-определения
избыточны — определений нужно ровно столько, сколько различных пар
(модель, ступень) в карте, а роли живут в бриф-файлах.
`adversarial-reviewer` слит в `craftsman` (opus, medium — исполнение
брифов: вкусовая реализация, слепое ревью, перепроверки); упоминание
заготовки adversarial-reviewer в записях выше — история того дня.
@@ -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) — мандат
ревьюера + формат индекса находок (этапы 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) — правила триажа
для исполнителя (этап 5).
- [prompts/recheck-header.md](prompts/recheck-header.md) — узкая
@@ -29,7 +37,7 @@
переживает. Windows-кавеат из codex-exec.md в силе: путь —
forward-slash, не голый `/tmp` Git Bash.
- Через Write оркестратор пишет **только параметрические блоки** ниже;
плейсхолдеры `{{...}}` — значения задачи, секции «adapt» — по смыслу.
секции «adapt» — по смыслу.
Сборка на прогон: `D="$SCRATCH/<NN-slug>"` — подпапка задачи; `P` —
`references/prompts` в базовом каталоге скилла (путь даётся в шапке
@@ -37,10 +45,15 @@
```bash
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" \
"$P/runtime-language.md" > "$D/review-prompt-task.md"
# вторая линия: line-code.md -> review-prompt-code.md;
# одиночный ревьюер: line-rev.md -> review-prompt.md
cat "$D/review-params.md" "$P/line-task.md" "$P/line-taste.md" \
"$P/review-boilerplate.md" "$P/runtime-language.md" \
> "$D/review-prompt-task.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" \
"$D/notes.md" "$P/runtime-language.md" > "$D/fix-prompt.md"
# notes.md опционален — нет, так не включай
@@ -91,15 +104,16 @@ will run it before the reviews start.
Отдельным ходом после отчёта о реализации, до внешних ревью — смена рамки
«автор → критик» отдельным ходом ловит больше, чем финальный пункт
чек-листа в промпте задачи:
чек-листа в промпте задачи. Текст готов файлом:
```text
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.
```bash
cat "$P/self-review.md" | codex exec resume <thread-id> ...
```
Опус-исполнителю (`craftsman`) — тот же файл продолжением его треда:
запускай его с `name` и шли SendMessage
«read and execute $P/self-review.md».
## 2. Ревью: общий блок + файл линии
Общий параметрический блок (`review-params.md`) один на обе линии и не
@@ -111,17 +125,20 @@ phrase per unfixed item, if any.
```text
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
it (via Write or a Bash heredoc, whichever you have). Keep the index
strict: ONE line per finding and per confirmation, as the boilerplate
demands — no multi-line entries. Final message: ONLY the VERDICT line,
severity counters and the file path.
it (via Write or a Bash heredoc, whichever you have). Append each finding
to that file as you go — incremental writing keeps a partial index alive
if the session dies. Keep the index strict: ONE line per finding and per
confirmation, as the boilerplate demands — no multi-line entries. Final
message: ONLY the VERDICT line, severity counters and the file path.
```
(Однострочность продублирована в обёртке не случайно: boilerplate это уже
требует, но Клод-родословная держит формат хуже Codex — эмпирика
требует, но Клод-семейство держит формат хуже Codex — эмпирика
2026-07-12/13, многострочные находки и развёрнутые confirmations.)
Замене молчащего ревьюера давай **другой** путь вердикта — правило в
«Сбоях координации» SKILL.md.
```markdown
# Code review: {{ticket NN — essence}}
@@ -140,36 +157,16 @@ Test command (expect {{N}} passed): {{command}}
shared code}}
```
Файлы линий (`line-task.md` / `line-code.md`), по одному на слепую линию:
```markdown
## Your line
FINDING PREFIX: TASK
Lens: compliance with the statement, acceptance criteria, boundaries,
intended observable result.
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.
```
```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)). При обычном распределении и у одиночного
ревьюера он уже на месте — обоих ведёт Клод. Поменялись родословными —
переставь блок целиком туда, где Клод.
Файлы линий — готовые константы в `prompts/`, оркестратор их не
перепечатывает: `line-task.md` (уместность: постановка, критерии,
границы), `line-code.md` (дефекты: корректность, инварианты, регрессии),
одиночному ревьюеру — `line-rev.md` (обе линзы, префикс `REV`).
Вкусовая линза с базой запахов — `line-taste.md`; она едет с **линией
уместности** (её ведёт модель со вкусом — назначение линий в этапе 4
SKILL.md), поэтому разрез — выбором файла в `cat`, не пересказом
границы. Стенд делится между линиями? Явный запрет ломающих команд
второй линии — отдельным параметрическим файлом `$D/access-<line>.md`,
подшитым после файла линии (правило — этап 4 SKILL.md).
Вариант для **этапа 2** (ревью постановки, кода изменений ещё нет) — тот же
boilerplate, другой параметрический блок:
@@ -192,8 +189,9 @@ Code to check the statement's facts against: {{file list with why}}
criteria checkable and gameable?, observability}}
```
Файл линии — тем же механизмом: только префикс (`SPEC-A` / `SPEC-B`,
одиночному обзору — `SPEC`); линза уже задана рамкой блока.
Файл линии здесь — двухстрочный Write (`## Your line` +
`FINDING PREFIX: SPEC-A|SPEC-B|SPEC`): константного файла нет
намеренно — префикс варьируется, а линза уже задана рамкой блока.
## 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
repo make a verdict much firmer than reading alone.
- 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,
no narrative. Where to put it: your call wrapper says, or it is your
`-o` report if you were invoked via stdin.
@@ -12,7 +17,7 @@
## Findings file format — index only
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
@@ -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.