avandClaude Opus 5
a81dd1a5a7
Замечено при сверке документов канона с составом ступеней: три документа остались без читателя ниже 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>
109 lines
9.3 KiB
Markdown
109 lines
9.3 KiB
Markdown
# Калибровка проходов
|
||
|
||
Без измерения набор проходов растёт монотонно и вырождается в театр: каждый
|
||
кажется полезным, потому что иногда что-то говорит. Калибровка отвечает на
|
||
единственный вопрос — **ловит ли проход дефект своего класса**.
|
||
|
||
## Процедура (инъекция дефекта)
|
||
|
||
1. Взять **реальный коммит** из истории (`git log --oneline`), лучше
|
||
архивированный change с непустым диффом.
|
||
2. Внести в него **один** дефект того класса, который проход обязан ловить по
|
||
своему charter'у. Дефект должен быть правдоподобным — таким, какой реально
|
||
пишет модель, а не карикатурой (`panic("TODO")` не считается).
|
||
3. Прогнать **только этот проход** на подготовленном диффе — **три раза**,
|
||
каждый в чистом контексте.
|
||
4. Зафиксировать: нашёл `n/3`, число находок всего, число ложных.
|
||
5. Вердикт:
|
||
|
||
| Результат | Вердикт | Что делаем |
|
||
|---|---|---|
|
||
| нашёл 3/3 или 2/3, ложных немного | `keep` | ничего |
|
||
| нашёл 1/3 или 0/3 | `retune` | правим charter — сужаем вход, убираем чек-лист, добавляем оракул |
|
||
| `retune` уже был дважды подряд | `drop` | удаляем проход |
|
||
| находит, но ложных больше трети от всех находок | `retune` | триаж съедает больше, чем экономит проход |
|
||
|
||
Вердикты образуют храповик со счётчиком — его-то таблица и не показывает:
|
||
|
||
```mermaid
|
||
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-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'а существующего — иначе непонятно, правка помогла или нет;
|
||
- при появлении записи в журнале проскочивших дефектов — калибруем тот проход,
|
||
который должен был поймать;
|
||
- планово — нет. Календарная калибровка ради галочки сама превращается в театр.
|