Files

T

классификация задачи: три категории документов и метка вместо ступени

Канон 5 объявил «каждый документ docs/ — тема ревью». Правило верно ровно
наполовину и потому вредно целиком. Паспорт и схему хранилища ревью читает, но
темами они не являются: по ним нельзя сказать «в этом изменении сделано не так»,
они задают границу, по которой судит чужая тема. Журнал решений и журнал
наблюдений ревью изменения не нужны вовсе — ADR объясняет прошлое, а не
предъявляет требование. Разметчик, применявший правило буквально, обязан был
либо завести фантомные темы passport, adr, database, research и продублировать
ими работу architecture и operations, либо потерять четыре документа молча;
случались обе ветки, и в собственном образце плана docs/passport.md не попадал
ни строкой, а обязательная арифметика покрытия при этом не сходилась.

Категорий теперь три, разрез проверяемый. Тема — да, прямо: conventions,
security, architecture и любой свой документ проекта. Источник темы — нет, но он
задаёт границу для чужой: passport, database, CLAUDE.md, openspec/specs.
Процессный — нет, он про то, как мы работаем: tasks, review, adr, research,
.pm.json. Открыта одна категория из трёх, две другие перечислены поимённо, так
что документ вне раскладки — однозначно своя тема. adr и research прогон больше
не открывает ни одним проходом; docs/review остаётся читаемым, но как настройка
конвейера, а не критерий. Цена записана и стала обязательной строкой границ
покрытия: расхождение с записанным решением ловит теперь только сверка
документации, а число под находкой обязано быть снято на этом прогоне, с
приложенной командой.

Классификация выдаёт задаче метку — small, medium, large. Прежние quick,
standard и wide назывались ступенью и описывали ревью: как глубоко смотрим.
Классифицируется же задача, и пока величина называлась свойством прогона, её
естественно было пересчитывать на каждом прогоне — что конвейер и делал. Слово
«ступень» удалено, а не оставлено синонимом: два имени одной вещи расходятся.
Выводится метка из двух разведённых осей — размер (малое, среднее, крупное) и
сложность (знакомое, незнакомое), — и равна максимуму по ним. Метка не синоним
размера: малое незнакомое изменение получает large, трогая один узел, поэтому
план печатает три строки с обоснованием каждая и выводить одну из другой
запрещено. Оси остались русскими словами — это суждение прозой; метка
английская — это идентификатор, который проходы сравнивают.

Разметка переехала из ревью кода в шаг 4 пайплайна, сразу после propose. Она
шла первым проходом каждого ревью кода, а перед ревью дизайна ту же величину
называл сам пайплайн — то есть оркестратор, который только что довёл
предложение до propose. Одно и то же измерялось дважды, и один из двух раз без
разведённости с автором, ровно в той точке, ради которой разметчик заведён.
Теперь запуск один на задачу, диффа он не видит, план обслуживает обе стадии, и
метка после кода не пересматривается: расхождение факта с разметкой ловит журнал
дефектов постфактум, как и всякую другую ошибку выбора. На диск план не пишется —
четвёртый артефакт рядом с proposal, tasks и design пережил бы задачу и разошёлся
бы с ней молча.

Ревью дизайна тоже растёт меткой: small — specs, medium — плюс rubric, large —
плюс architecture и вопрос автору о трёх формах решения. Раньше rubric и
architecture включались одним условием, и medium получал ровно один проход, то
есть не отличался от quick ничем. Разведены они потому, что зарабатывают на
разном: рубрика порождает свойства узла и окупается уже на среднем изменении,
её выход уезжает приёмочными критериями в tasks.md; архитектура отвечает на
вопрос про второй способ, а он на среднем знакомом изменении отвечается «нет»
ещё до запуска.

small подешевел тремя способами сразу. Составом: приёмник тем не запускается,
три темы ядра переходят к code сверкой по записанным инвариантам CLAUDE.md с
потолком в одну находку, и это не «глубина ниже», а другой дом темы. Входом:
specs читает только дельта-спеку, code — только индекс конвенций. Потолком: он
появился у каждого опиниативного прохода, а не у одного basics, и у половин code
он раздельный, потому что конвенционных находок больше по построению и в общем
списке они вытеснили бы техническую половину. Сработавший потолок обязан быть
объявлен строкой — молчащий срез неотличим от «больше не нашлось». Отрицательный
тест small от этого стал жёстче, а не мягче: вопросы про обратимость миграции
задавал приёмник тем, и на этой метке их не задаст никто.

Пайплайн задачи вырос до двенадцати шагов. Тривиальность перестала решать состав
ревью — она влияет только на explore; глубину обеих стадий называет метка.

Проверено прогоном ревьюверов по готовому результату: девять расхождений найдено
и починено — контракт находок печатал старый перечень проходов вместо плана по
темам, три ссылки в task-batch указывали на шаг коммита вместо закрытия, запись
changelog не переводила вопросы, адресованные passport и database, ops и
adversary утверждали, что на нижних метках их вопросы задаёт basics, шаблон
покрытия в review-code зашивал потолки small намертво, триггеры метки рассыпались
на два списка против трёх, тема из директивы CLAUDE.md могла остаться без запуска
исполнителя. Гейт зелёный: фронтматтеры, копии, одиннадцать диаграмм, ruff,
pyrefly; docs.py прогнан на живом фикстуре и печатает категорию в отказе.

Канон повышен до версии 6 с записью, выполнимой upgrade. Решения — 40–44.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-07 10:57:15 +03:00

9.3 KiB

Raw Blame History

Калибровка проходов

Без измерения набор проходов растёт монотонно и вырождается в театр: каждый кажется полезным, потому что иногда что-то говорит. Калибровка отвечает на единственный вопрос — ловит ли проход дефект своего класса.

Процедура (инъекция дефекта)

Взять реальный коммит из истории (git log --oneline), лучше архивированный change с непустым диффом.
Внести в него один дефект того класса, который проход обязан ловить по своему charter'у. Дефект должен быть правдоподобным — таким, какой реально пишет модель, а не карикатурой (panic("TODO") не считается).
Прогнать только этот проход на подготовленном диффе — три раза, каждый в чистом контексте.
Зафиксировать: нашёл n/3, число находок всего, число ложных.
Вердикт:

Результат	Вердикт	Что делаем
нашёл 3/3 или 2/3, ложных немного	`keep`	ничего
нашёл 1/3 или 0/3	`retune`	правим charter — сужаем вход, убираем чек-лист, добавляем оракул
`retune` уже был дважды подряд	`drop`	удаляем проход
находит, но ложных больше трети от всех находок	`retune`	триаж съедает больше, чем экономит проход

Вердикты образуют храповик со счётчиком — его-то таблица и не показывает:

stateDiagram-v2
    state "проход в составе метки" as live
    state "retune №1 — правка charter'а" as r1
    state "retune №2 — последняя попытка" as r2
    state "проход удалён" as dead

    [*] --> live: заведён и откалиброван ДО включения
    live --> r1: 1/3, 0/3 или ложных больше трети
    r1 --> live: замер keep — счётчик сброшен
    r1 --> r2: снова не ловит
    r2 --> live: замер keep — счётчик сброшен
    r2 --> dead: снова не ловит — это театр

Схема — сводка к таблице вердиктов выше: она добавляет только счётчик, и при расхождении прав таблица.

retune не более двух раз подряд. Проход, не находящий дефект своего класса в 2 из 3 прогонов после двух правок промпта, — это театр. Удалять, а не бесконечно править формулировки: каждая итерация правки промпта стоит дороже, чем отсутствие прохода.

Существующий проход не удаляется без замера. Сначала калибровка, потом решение — иначе удаляется то, что работало, а остаётся то, что громче. Обратный пример уже был: проход про идиоматичность стоял в списке на удаление как «вкусовщина», а замер показал, что он зарабатывает экспериментами против поведения библиотеки и драйвера, — и находка, воспроизведённая числом, отменила решение, принятое по ощущению.

Состав проходов принадлежит плагину, а не проекту

Проходы общие. Проект не может удалить проход — он может не звать его, и тогда это идёт строкой «не запускался» в границы покрытия, как любой другой пропуск. Молча сузить состав нельзя: пропуск прохода не отличим от прохода без находок.

Отсюда два следствия:

правка charter'а — правка для всех проектов. Прежде чем сужать формулировку под свою боль, проверь, не место ли ей в документах проекта: предмет проверки живёт там, метод — в charter'е;
удаление прохода из плагина требует замера на двух проектах, а не на одном: класс, не всплывший здесь, мог быть единственным работающим там.

Пробы дефектов по проходам

Проба — заготовка инъекции. Список пополняется из журнала проскочивших дефектов (см. review-journal.md): реальный проскочивший дефект — лучшая проба, какая вообще возможна, потому что синтетические смещены в сторону тех, которые уже умеешь придумывать.

Проход	Класс дефекта для инъекции	Заготовка пробы
`review-scope`	пропущенная тема	положить в `docs/` новый документ и проверить, попал ли он в план темой
`review-autotests`	отсутствующая верификация	убрать тест на изменённую ветку, оставить код рабочим
`review-specs`	поведение вне спеки	добавить незаказанный фолбэк-дефолт на пустом входе
`review-code`	нарушение прозаической конвенции	увести штатный отказ мимо единой точки трансляции ошибки
`review-code`	технический дефект	не проверить возвращённую ошибку в ветке раннего возврата
`review-rubric`	нарушенное свойство узла	у клиента внешнего сервиса убрать таймаут и протяжку `context`
`review-basics`	отказ, видимый чтением	убрать обработку ошибки записи так, чтобы отказ считался успехом
`review-basics`	своя тема проекта	нарушить правило из документа, у которого нет именного прохода
`review-architecture`	второй способ	завести вторую точку генерации id мимо единой
`review-adversary`	построенный путь	принять внешний идентификатор без разбора до запроса в хранилище
`review-ops`	деградация окружения	убрать обработку недоступности внешней зависимости в фоновом цикле
`review-triage`	шум	подать 20 находок, из них 15 вкусовщина и 3 дубля — проверить потолок и дедуп

Метрик сверх этого не заводим. Precision, корреляция между проходами, стоимость прогона в токенах — всё это красиво звучит и никем не считается вручную; набор показателей, который не собирают, создаёт впечатление измеряемости и тем вреден. Работает ровно один механизм: инъекция дефекта и вердикт. Если корреляция двух проходов действительно бросается в глаза — это видно по полю Найдено проходом в триажированных отчётах и без отдельной метрики.

Когда калибровать

при заведении нового прохода — до включения в состав метки по умолчанию;
при правке charter'а существующего — иначе непонятно, правка помогла или нет;
при появлении записи в журнале проскочивших дефектов — калибруем тот проход, который должен был поймать;
планово — нет. Календарная калибровка ради галочки сама превращается в театр.

9.3 KiB Raw Blame History Unescape Escape