Files

T

ревью по темам: документ проекта стал направлением проверки

Замечено при сверке документов канона с составом ступеней: три документа
остались без читателя ниже wide — security.md, database.md и adr/. Проект
поддерживал их, а на 90% задач не открывал никто. Причина оказалась не в
переезде проходов, а в том, как описан состав прогона.

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

Тема есть документ, список открытый. Всё, что проект кладёт в docs/, становится
темой ревью; запретить нельзя, разрешения не надо. Не темы ровно две: docs/tasks/
и docs/review — настройка самого конвейера, слой над темами. Отсюда главное:
docs/ перестал быть документацией и стал конфигурацией конвейера. Проект
настраивает проверку тем, что пишет о себе, а не отдельным файлом настроек,
который разошёлся бы с документами. Ядро — requirements, autotests, conventions,
architecture, security, operations; всё сверх разбирает basics, потому что
именных проходов конечное число, а тем столько, сколько заведёт проект.

Тема живёт файлом или каталогом, на выбор проекта: docs/security.md и
docs/security/ — одно и то же. Прежде форма была задана поимённо и обосновать её
было нечем; заодно в TODO висел вопрос «а если architecture.md разрастётся».
Теперь ответ механический: разросся — стал каталогом с README.md, и это не смена
версии. Обе формы сразу — ошибка, docs.py её ловит.

Заведён review-scope, sonnet, стадия 0, до гейта: находит документы, выводит
темы, назначает глубины, выбирает ступень с обоснованием. Довод оказался сильнее
синхронизации документов — до сих пор профиль называл тот же оркестратор,
который написал код, то есть в точке выбора глубины проверки разведённости с
автором не было вовсе, а решала она под давлением «я почти закончил». Вызывающий
пайплайн профиль больше не передаёт. Поднять и понизить ступень разметчик вправе
одинаково, но обоснование обязательно всегда.

Sonnet ему хватает потому, что вывод устроен как список: каждый файл в docs/
обязан попасть в план темой или строкой «не тема, потому что», и план сверяется с
ls docs/ за секунду. Выбор ступени — суждение, но у него три независимых
корректора: отрицательный тест quick, правило «спорный случай вниз» и сигнал
basics о заниженной ступени.

Разметчик передаёт адреса, а не пересказ. Проект однажды уже держал
review-brief.md и убрал его: второй дом расходится с первым и выглядит
актуальным. Пересказ в задании — тот же посредник, живущий один прогон.
Исключение одно: отсутствие дома, этого проход сам дёшево не выяснит.

quick и standard совпали составом и разошлись глубиной — иначе требование
«нижние ступени закрывают все темы, просто не так глубоко» не выполняется.
Глубин три, и они про способ доказательства, а не про старательность: сверка
(открыть дом, открыть дифф, сравнить), разбор (построить сценарий рассуждением),
доказательство (прогнать, померить, построить путь). Третья есть только в wide.
Цена принята: это единственное место, где профиль не выводится из списка
проходов, поэтому глубина объявляется в отчёте наравне со ступенью.

review-code переписан, и это оказалось крупнее исходной находки: код как код не
читал никто. specs сверял с требованиями, basics — с отказами окружения,
architecture — с устройством, а code был проходом только по прозаическим
конвенциям и прямо объявлял, что рантайм и логика не его. «Здесь ошибка в логике»
не говорил вообще никто. Теперь у прохода две половины: девять классов
технического дефекта (необработанная ветка отказа, пустое и нулевое, граница
диапазона, перепутанный операнд, неосвобождённый ресурс, изменение под итерацией,
неверно применённый интерфейс библиотеки, недостижимая ветка, «сделано соседнее»)
и прежняя сверка с конвенциями. Модель поднята до opus по признаку темы 35: цена
пропущенной находки — дефект в проде.

Канон повышен до версии 5: форма дома на выбор, открытый список тем, AGENTS.md
законно лежит рядом с CLAUDE.md, «Вопросы к проходам» → «Вопросы по темам» (имя
прохода переезд не переживает, тема переживает), «Недоступно проверке» — тоже по
темам. docs.py переписан под темы: ловит двойной дом, принимает обе формы,
перечисляет свои темы проекта вместо «файл вне канона».

Побочно закрыт давний пункт TODO про каталожную форму architecture.md — решать
больше нечего.

Прогон от всего этого стал дороже, а не дешевле, впервые за сессию: плюс scope в
голове каждого прогона, плюс code на opus, плюс basics теперь и в quick. Куплены
разведённость выбора ступени, видимость непокрытых тем и технический разбор кода,
которого не было вовсе.

Тема 36 в DECISIONS.md, следствия 137-140.

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

2026-08-07 08:35:11 +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-gate`	отсутствующая верификация	убрать тест на изменённую ветку, оставить код рабочим
`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