ревью: лёгкий проход proof в цикле, тяжёлые — в code-deep-review
В цикле задачи темы security и operations закрывает один лёгкий проход review-proof: чтением и рассуждением, без запуска, потолки раздельные. Машину он не держит, поэтому идёт в общем залпе — цепочки за ресурс в обычном прогоне не осталось. Тяжёлая пара adversary и ops переехала в новый скилл code-deep-review: вход — названная область кода, глубина постоянная, исход — разбор с человеком и задачи через task-track. Вход глубокому прогону копит сам цикл строками «отложено». Журнал — тема 76.
This commit is contained in:
@@ -0,0 +1,224 @@
|
||||
---
|
||||
name: code-deep-review
|
||||
description: "Глубокое ревью области кода — не задачи, а куска проекта: модуля, слоя, сервиса целиком. Зовёт тяжёлые проходы, которых нет в цикле задачи: review-adversary (строит путь и прогоняет падающий тест), review-ops (снимает числа замером), review-architecture на входе шире диффа, review-code по коду целиком, а сводит их review-triage. Проходы, помеченные «держит машину», идут цепочкой. Исход — не правки, а разговор: находки предлагаются человеку, обсуждаются по одной, и согласованное уезжает задачами через av-dev:task-track, сценарий «задачи из ревью и аудита». Использовать время от времени и по признаку: накопился десяток задач в одной области, перед тем как опереться на узел в дорогом решении, после инцидента, по строке «отложено в code-deep-review» из отчётов ревью. Дорого — не на задаче и не по расписанию. Ревью одного изменения — скилл av-dev:code-review."
|
||||
---
|
||||
|
||||
# Глубокое ревью области
|
||||
|
||||
Смотрит **не задачу, а место в проекте**: модуль, слой, сервис целиком. Отсюда и
|
||||
всё остальное устройство — вход, состав проходов, исход.
|
||||
|
||||
Разрез с конвейером задачи проверяемый: **`av-dev:code-review` судит изменение,
|
||||
этот скилл судит написанное**. Там вход — дифф и дельта-спеки, здесь — область
|
||||
кода и её история. Там исход — правки в том же прогоне, здесь — разговор и
|
||||
задачи.
|
||||
|
||||
## Зачем он появился
|
||||
|
||||
Тяжёлые проходы стояли в цикле задачи, на метке `large`: `review-adversary`
|
||||
строил путь и прогонял падающий тест, `review-ops` снимал числа замером. Оба
|
||||
держали машину, шли цепочкой и стоили часов **на каждой задаче**, где
|
||||
запускались, — при том что их ценность оплачивается на каждой, а получается на
|
||||
немногих.
|
||||
|
||||
Их вынесли сюда целиком. В цикле задачи обе темы закрывает лёгкий проход
|
||||
`review-proof` — чтением и рассуждением, без запуска, — и он же **копит вход для
|
||||
этого скилла**: строка «отложено в `av-dev:code-deep-review`» в границах покрытия
|
||||
называет тему, место и запуск, которым это проверяется.
|
||||
|
||||
## Когда звать
|
||||
|
||||
**Зовёт человек**, и признак наблюдаемый, а не календарный:
|
||||
|
||||
- **накопился десяток задач в одной области** — по одной каждая была `medium`, а
|
||||
вместе они переписали узел;
|
||||
- **строки «отложено» скопились**: в отчётах ревью по одному месту повторяется
|
||||
один и тот же неснятый замер;
|
||||
- **перед дорогим решением**, которое обопрётся на этот узел;
|
||||
- **после инцидента** — когда уже известно, где болит, и надо понять, что рядом;
|
||||
- **узел, в который возвращаются третий раз**: `av-dev:code-review`,
|
||||
`references/review-levels.md` называет это поводом пересмотреть метку, а здесь
|
||||
это повод посмотреть весь узел.
|
||||
|
||||
**Не на задаче и не по расписанию.** Цена реальная: два прохода держат машину и
|
||||
идут цепочкой, вход шире диффа собирается командой проекта, а разбор находок
|
||||
требует человека. Прогон по каждой задаче был бы ровно той церемонией, ради
|
||||
снятия которой проходы отсюда и переехали.
|
||||
|
||||
## Чего может не быть
|
||||
|
||||
**Копия.** Дом правила — `shared/absence.md` в репозитории плагина.
|
||||
Правится дом, а не этот файл.
|
||||
|
||||
<!-- копия: отсутствие из av-dev/shared/absence.md -->
|
||||
|
||||
**Скилл не вправе считать раскладку проекта полной.** Части заводятся порознь и
|
||||
живут порознь; каждая узнаётся своим следом:
|
||||
|
||||
| Чего нет | Как видно | Чего теперь не делает никто |
|
||||
| --- | --- | --- |
|
||||
| настройки av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
|
||||
| документы канона | нет `docs/` | проектную конкретику брать неоткуда — темы, инварианты, прецеденты |
|
||||
| учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе |
|
||||
| источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять |
|
||||
|
||||
**Свой скилл зовётся полным именем** — `av-dev:canon`, `av-dev:task-track`,
|
||||
`av-dev:code-review`. Короткое имя может разрешиться в устаревшую проектную
|
||||
копию из `.claude/skills/`, и подмены не будет видно ни в докладе, ни в
|
||||
поведении.
|
||||
|
||||
**Внешний плагин может не стоять.** Их два: `opsx:*` — цикл SDD, и
|
||||
`av-dev-git:commit` — сообщения коммитов. Путь в дерево чужого плагина не
|
||||
пишется никогда: `$CLAUDE_PLUGIN_ROOT` ведёт только в своё дерево, а
|
||||
вычисленный от него путь к соседу либо не откроется, либо откроет чужую
|
||||
установку. Нужен чужой справочник — зови владеющий им скилл, он прочитает его
|
||||
сам.
|
||||
|
||||
**Отсутствие — исход, а не поломка.** Назови строкой доклада, чего теперь не
|
||||
делает никто, и продолжай работу. Молчать нельзя: пропуск неотличим от
|
||||
сделанного. Выдумывать обходной путь нельзя тоже.
|
||||
|
||||
**Присутствие узнаётся следом в проекте, а не объявлением.** Перечня того, что
|
||||
здесь заведено, проект не ведёт — он разошёлся бы с действительностью молча.
|
||||
|
||||
<!-- /копия: отсутствие -->
|
||||
|
||||
**Каталога задач нет** — находки остаются списком в докладе, и это говорится
|
||||
строкой: заводить их некуда, а держать в голове до следующего прогона нечем.
|
||||
|
||||
## Вход — область, а не дифф
|
||||
|
||||
**Область называет человек, и называет до запуска.** Пакет, слой, сервис,
|
||||
capability — одним адресом или несколькими. Скилл область не выбирает сам: выбор
|
||||
области и есть решение о том, во что вложить часы, и оно человеческое.
|
||||
|
||||
Область не названа — **спроси, а не бери репозиторий целиком**. Прогон по всему
|
||||
проекту даёт находки, рассыпанные по местам, между которыми нет связи, а разбор
|
||||
такого урожая не доводится до конца никогда.
|
||||
|
||||
К области собирается **корпус**:
|
||||
|
||||
| Что | Откуда | Зачем |
|
||||
|---|---|---|
|
||||
| код области целиком | адреса, названные человеком | вход всех проходов |
|
||||
| история области | `git log` по этим путям | что переписывалось и сколько раз |
|
||||
| отложенное | строки «отложено в `av-dev:code-deep-review`» из отчётов ревью | неснятые замеры и недостроенные пути |
|
||||
| журнал дефектов | `docs/review.md` | что уже проскакивало мимо конвейера |
|
||||
| дома тем | `docs/security.*`, `docs/architecture.*`, `docs/conventions.*` | против чего судить |
|
||||
|
||||
Отложенного нет вовсе — скажи это строкой. Пустой список значит либо что цикл
|
||||
ничего не откладывал, либо что `review-proof` не писал свою строку; вторая
|
||||
причина — находка о процессе, и она идёт в доклад.
|
||||
|
||||
## Состав прогона
|
||||
|
||||
Метки здесь нет и разметчик не зовётся: метку выводят из задачи, а задачи нет.
|
||||
Состав **постоянный**, и глубина у всех проходов одна — **доказательство**.
|
||||
|
||||
| Проход | Тема | Что делает |
|
||||
|---|---|---|
|
||||
| `review-adversary` | `security` | строит путь и **прогоняет** падающий тест |
|
||||
| `review-ops` | `operations` | снимает числа замером: удержание, рост, деградация |
|
||||
| `review-architecture` | `architecture` | концептуальная целостность на входе шире диффа |
|
||||
| `review-code` | `conventions` и техника | читает код **как код**, целиком, а не диффом |
|
||||
| `review-triage` | — | единственный сток: дедуп, оракулы, потолок |
|
||||
|
||||
**Гейта здесь нет, и это не пропуск.** Гейт судит изменение — красный он или
|
||||
зелёный, к написанному месяц назад коду это не относится. Если гейт проекта
|
||||
красный, скажи это строкой: находки о коде, который не собирается, стоят меньше.
|
||||
|
||||
**Цепочка за машину остаётся.** `review-adversary` и `review-ops` помечены
|
||||
«держит машину» и идут друг за другом, а не разом: два прохода на одной машине
|
||||
выдают числа, которые не воспроизведутся. Правило и его причина — дом в
|
||||
`av-dev:code-review`, раздел «Кто держит машину». Здесь эта цена приемлема:
|
||||
скилл идёт не на задаче, и часы у него есть.
|
||||
|
||||
`review-architecture` и `review-code` машину не держат — уходят первой волной,
|
||||
разом.
|
||||
|
||||
**Задание каждому проходу собирается адресами**: область, дома его тем, контракт
|
||||
находок, отложенные строки по его теме и признак «вход — область, а не дифф».
|
||||
Проход, получивший привычное «суди дифф», сузит себя сам.
|
||||
|
||||
## Триаж — тот же, вход другой
|
||||
|
||||
`review-triage` сводит выводы всех проходов: дедуп по причине, оракул на всё
|
||||
`critical` и `major`, понижение неподтверждённого до гипотезы, отсев вкусовщины,
|
||||
ранжирование по ущербу × вероятности.
|
||||
|
||||
**Потолка в 7 пунктов здесь нет.** Он существует потому, что отчёт по задаче
|
||||
читает тот, кто **молча реализует** прочитанное, и длинный список превращается в
|
||||
разросшийся код. Здесь читатель — человек, и каждый пункт он разбирает вслух.
|
||||
Вместо потолка — **порядок**: находки идут по убыванию ущерба, и разговор
|
||||
начинается сверху.
|
||||
|
||||
План прогона триажу передаётся составом: перечень проходов и тем. Тема, не
|
||||
вернувшая отчёта, называется в границах покрытия — правило то же, что в конвейере
|
||||
задачи.
|
||||
|
||||
## Разбор с человеком — главный шаг
|
||||
|
||||
**Исход этого скилла — не правки, а согласованный список работ.** Ни одной
|
||||
находки скилл не чинит сам, даже мелкой: правка по ходу разбора превращает
|
||||
разговор в работу и съедает то время, ради которого прогон и затевался.
|
||||
|
||||
Находки разбираются **по одной, сверху вниз**, и по каждой человек говорит одно
|
||||
из трёх:
|
||||
|
||||
- **берём** — находка становится задачей;
|
||||
- **не берём** — с причиной; причина уезжает в журнал дефектов `docs/review.md`,
|
||||
потому что отказ от находки это тоже решение о качестве;
|
||||
- **не находка** — проход ошибся; это тоже строка журнала, и по ней потом видно,
|
||||
какой проход даёт ложные срабатывания.
|
||||
|
||||
**Показывай находку целиком**, а не заголовком: оракул и последствие — это и есть
|
||||
то, по чему человек решает. Заголовок без оракула читается как мнение.
|
||||
|
||||
**Длинный список разбирается порциями.** Десяток пунктов за раз — потолок
|
||||
внимания, а не формальность; остальное ждёт следующей порции в том же прогоне.
|
||||
|
||||
## Задачи заводит `av-dev:task-track`
|
||||
|
||||
**Вызови Skill `av-dev:task-track`** и попроси завести задачи по согласованному
|
||||
списку — у него на этот вход отдельный сценарий «задачи из ревью и аудита»: своя
|
||||
нарезка, свой формат, свои правила дублей. Формулировку, оракул и происхождение
|
||||
находки передавай **дословно**: пересказ теряет как раз оракул, а без него задача
|
||||
превращается в пожелание.
|
||||
|
||||
Заводить записи руками, править индексы или придумывать свой формат нельзя —
|
||||
мост между скиллами это вызов, а не путь к файлу.
|
||||
|
||||
## Запись в журнал ревью
|
||||
|
||||
**Прогон оставляет след в `docs/review.md`** — вызовом `av-dev:doc-sync`, который
|
||||
владеет этим документом. В следе: область, состав проходов, что взято задачами,
|
||||
что отвергнуто и почему, что проверить было невозможно.
|
||||
|
||||
Без этого следа второй прогон по той же области начнётся с нуля и предложит те же
|
||||
находки, от которых человек уже отказался, — а отказ, не оставивший записи,
|
||||
неотличим от непойманного.
|
||||
|
||||
## Доклад
|
||||
|
||||
- **область** — что смотрели, адресами;
|
||||
- **состав прогона** — какие проходы шли, какие темы закрыты, какие нет;
|
||||
- **находки** — сколько выжило после триажа, сколько взято задачами, сколько
|
||||
отвергнуто с причиной;
|
||||
- **заведённые задачи** — слагами, либо строка «каталога задач нет, список
|
||||
остаётся в докладе»;
|
||||
- **границы покрытия** — что проверить было невозможно: недоступный инструмент,
|
||||
неподнимаемая зависимость, область, до которой не дошли;
|
||||
- **отложенное, которое сняли** — какие строки «отложено» из отчётов ревью
|
||||
закрыты этим прогоном.
|
||||
|
||||
## Тонкости
|
||||
|
||||
- **Прогон не правит код** — ни строки. Единственный его артефакт, кроме
|
||||
разговора, это задачи и запись в журнале ревью.
|
||||
- **Область меньше — прогон лучше.** Модуль разбирается до конца, сервис целиком
|
||||
даёт список, который бросают на середине.
|
||||
- **Находка о процессе — тоже находка.** Пустая строка «отложено» у прохода
|
||||
`review-proof`, дефект, трижды проскочивший в одном узле, тема без дома —
|
||||
всё это идёт в доклад наравне с находками о коде.
|
||||
- **Метку сюда не приносят.** Она свойство задачи; здесь задачи нет, и подставлять
|
||||
`large` «по аналогии» нельзя — состав здесь и так постоянный.
|
||||
@@ -319,6 +319,13 @@ flowchart TD
|
||||
сжатой строкой. Отчёт, из которого исчезло «что проверить было невозможно»,
|
||||
превращается в ложное ощущение проверенности.
|
||||
|
||||
**Строку «отложено в `av-dev:code-deep-review`» перенеси дословно.** Проход
|
||||
`review-proof` называет в ней тему, место и запуск, которым это проверяется, —
|
||||
всё, что доказывается только прогоном и замером, цикл задачи не доказывает ни на
|
||||
одной метке. Эти строки копятся и однажды становятся поводом позвать глубокое
|
||||
ревью области; пересказанные своими словами, они теряют оракул и перестают быть
|
||||
поводом.
|
||||
|
||||
**Отчёт триажа сохрани вместе с change (`openspec/changes/<id>/review/`; шаг 7
|
||||
унесёт его в архив вместе с change) — это обязательно, а не «если удобно».** По
|
||||
нему потом видно, что было найдено и что из этого осталось в урожае. И это
|
||||
@@ -413,7 +420,8 @@ change. Заводить запись задним числом, чтобы её
|
||||
это доклад приёмщику, а не отметка «принято»;
|
||||
- **`Урожай`** — отложенные находки списком (формулировка, оракул, откуда взялась);
|
||||
- **одна строка границ покрытия**: какая метка и режим гонялись, какие проходы не
|
||||
запускались и что проверить было невозможно. Доклад без неё сообщает
|
||||
запускались и что проверить было невозможно;
|
||||
- **отложенное в `av-dev:code-deep-review`** — дословно из отчёта, либо «нечего». Доклад без неё сообщает
|
||||
«проверено», не сообщая, что именно.
|
||||
|
||||
## Тонкости сценария
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: code-review
|
||||
description: "Конвейер ревью изменения, устроенный по темам: документ проекта либо заводит тему ревью, либо питает чужую тему источником, либо процессный и в ревью не читается вовсе. Ядро тем — requirements, autotests, conventions, architecture, security, operations; список тем открытый, свои темы проект заводит документом. Разметка задачи идёт один раз, после apply: агент review-scope выводит размер по диффу и сложность по форме решения, из их максимума — метка, и раздаёт темы проходам. Метка правит состав ревью кода: small — гейт, спеки, код, триаж; medium — плюс приёмник тем; large — плюс доказательство: враждебные постановки, эксплуатационный постмортем, архитектурный проход на широком входе. Триаж обязателен всегда. Порядок прогона — граф зависимостей: гейт открывает проходы с мнением, проходы с пометкой «держит машину» идут цепочкой, триаж — единственный сток. Проектная специфика приходит из документов канона проекта. Вызывается из скилла av-dev:code-resolve после apply. Второй вызов идёт от сценария обслуживания: без change и без метки, фиксированным планом (autotests, operations, плюс conventions, если тронут код), разметчик при этом не запускается."
|
||||
description: "Конвейер ревью изменения, устроенный по темам: документ проекта либо заводит тему ревью, либо питает чужую тему источником, либо процессный и в ревью не читается вовсе. Ядро тем — requirements, autotests, conventions, architecture, security, operations; список тем открытый, свои темы проект заводит документом. Разметка задачи идёт один раз, после apply: агент review-scope выводит размер по диффу и сложность по форме решения, из их максимума — метка, и раздаёт темы проходам. Метка правит состав ревью кода: small — гейт, спеки, код, триаж; medium — плюс приёмник тем; large — плюс review-proof (security и operations разом, чтением и рассуждением) и архитектурный проход на широком входе. Триаж обязателен всегда. Порядок прогона — граф зависимостей: гейт открывает проходы с мнением, триаж — единственный сток; проходы с пометкой «держит машину» идут цепочкой, но в обычном прогоне таких нет. Тяжёлые проходы — adversary и ops — переехали в скилл av-dev:code-deep-review, который идёт по области кода и время от времени. Проектная специфика приходит из документов канона проекта. Вызывается из скилла av-dev:code-resolve после apply. Второй вызов идёт от сценария обслуживания: без change и без метки, фиксированным планом (autotests, operations, плюс conventions, если тронут код), разметчик при этом не запускается."
|
||||
---
|
||||
|
||||
# Конвейер ревью
|
||||
@@ -17,7 +17,8 @@ description: "Конвейер ревью изменения, устроенны
|
||||
способ закрыть тему на заданной глубине, и проходы меняются: уезжают в старшую метку, сливаются, упраздняются. Если состав прогона считать списком проходов,
|
||||
то уехавший проход уносит тему с собой **беззвучно** — отчёт честно скажет
|
||||
«`ops` не запускался» и не скажет «эксплуатацию не смотрел никто», а нужно
|
||||
второе. Поэтому прогон описывается таблицей «тема → глубина → кто закрывает», и
|
||||
второе. Проверено на живом переезде: `ops` ушёл в `av-dev:code-deep-review`, а
|
||||
тема `operations` осталась в конвейере и досталась `proof`. Поэтому прогон описывается таблицей «тема → глубина → кто закрывает», и
|
||||
таблица эта есть в каждом отчёте.
|
||||
|
||||
1. **Recall чек-листа равен длине чек-листа.** Проход, устроенный как «проверь
|
||||
@@ -243,7 +244,7 @@ description: "Конвейер ревью изменения, устроенны
|
||||
| Модель | Цвет | Проходы | Почему |
|
||||
|---|---|---|---|
|
||||
| `sonnet` | green | scope, autotests, ops | вывод перечислим и сверяется механически |
|
||||
| `opus` | yellow | specs, code, basics, adversary, rubric, architecture, triage | дорога ошибка — ложная либо пропущенная |
|
||||
| `opus` | yellow | specs, code, basics, proof, rubric, architecture, triage | дорога ошибка — ложная либо пропущенная |
|
||||
|
||||
**`rubric` в составе прогона не стоит и в таблице держится за компанию.** Стадия,
|
||||
где он жил, снята: рубрику на задуманный узел он порождает, не видя кода, а
|
||||
@@ -306,8 +307,8 @@ charter'а, а модель потом двигает калибровка, и
|
||||
Экономия достигается **не понижением модели, а тремя другими рычагами**, и все
|
||||
три применяются к каждому проходу с мнением, а не к одному избранному.
|
||||
|
||||
1. **Непуск.** `large` добавляет доказательство — запуск, замер, построенный
|
||||
путь — и стоит часов; `small` снимает приёмник тем. Что при этом перестаёт
|
||||
1. **Непуск.** `large` добавляет две темы риска и взгляд на устройство; `small`
|
||||
снимает приёмник тем. Что при этом перестаёт
|
||||
проверяться, названо поимённо и идёт в границы покрытия.
|
||||
2. **Вход.** `basics` идёт на верхней модели, но с узким входом: дифф и его
|
||||
окрестности, без карты проекта. На `small` сужаются и остальные: `specs`
|
||||
@@ -358,9 +359,9 @@ charter'а, а модель потом двигает калибровка, и
|
||||
| `requirements` | `specs`, сверка | `specs`, разбор | `specs`, разбор |
|
||||
| `autotests` | `autotests` | `autotests` | `autotests` |
|
||||
| `conventions` | `code`, сверка | `code`, разбор | `code`, разбор |
|
||||
| `architecture` | `code`, сверка по инвариантам | `basics`, разбор | `architecture`, доказательство |
|
||||
| `security` | `code`, сверка по инвариантам | `basics`, разбор | `adversary`, доказательство |
|
||||
| `operations` | `code`, сверка по инвариантам | `basics`, разбор | `ops`, доказательство |
|
||||
| `architecture` | `code`, сверка по инвариантам | `basics`, разбор | `architecture`, разбор на широком входе |
|
||||
| `security` | `code`, сверка по инвариантам | `basics`, разбор | `proof`, разбор |
|
||||
| `operations` | `code`, сверка по инвариантам | `basics`, разбор | `proof`, разбор |
|
||||
| тема проекта | `basics`, сверка | `basics`, разбор | `basics`, разбор |
|
||||
|
||||
<!-- /дом: тема-метка-глубина -->
|
||||
@@ -383,7 +384,7 @@ flowchart TD
|
||||
cInv["code, третья половина:<br/>security, operations, architecture<br/>против инвариантов CLAUDE.md"]
|
||||
cB["basics — темы ядра + свои темы"]
|
||||
cBown["basics — только свои темы проекта"]
|
||||
cHeavy["adversary · ops · architecture<br/>доказательство"]
|
||||
cHeavy["proof (security + operations)<br/>· architecture"]
|
||||
cT["triage — единственный сток"]
|
||||
end
|
||||
|
||||
@@ -419,10 +420,15 @@ flowchart TD
|
||||
`apply`, до первой ступени. Раньше разметка стояла первой в каждом ревью кода и
|
||||
повторялась при каждом перезапуске прогона.
|
||||
|
||||
**Три глубины, и они не про старательность, а про способ доказательства.**
|
||||
**Глубины две, и они не про старательность, а про способ доказательства.**
|
||||
**Сверка** — открыть дом темы, открыть дифф, сравнить. **Разбор** — построить
|
||||
сценарий рассуждением, ничего не запуская. **Доказательство** — прогнать,
|
||||
померить, построить путь. Только третья требует машины, и только она стоит часов.
|
||||
сценарий рассуждением, ничего не запуская.
|
||||
|
||||
**Третья глубина — доказательство** (прогнать, померить, построить путь) — в
|
||||
цикле задачи не производится вовсе. Она требует машины и стоит часов, и потому
|
||||
живёт в скилле `av-dev:code-deep-review`, который идёт по названной области и
|
||||
время от времени. Проход, которому в плане назначили доказательство, получил план
|
||||
не от конвейера задачи.
|
||||
|
||||
**Здесь диспетчер и кончается: метка названа — состав читается.** Само правило
|
||||
выбора — две оси, «спорное решается вниз», максимум по поверхности, — а с ним
|
||||
@@ -467,8 +473,7 @@ flowchart TD
|
||||
specs["specs"]
|
||||
code["code"]
|
||||
basics["basics<br/>(medium: темы ядра и свои;<br/>small, large: только свои темы проекта)"]
|
||||
adversary["adversary<br/>(large, держит машину)"]
|
||||
ops["ops<br/>(large, держит машину)"]
|
||||
proof["proof<br/>(large: security + operations)"]
|
||||
architecture["architecture<br/>(large)"]
|
||||
triage["triage — единственный сток"]
|
||||
|
||||
@@ -476,15 +481,12 @@ flowchart TD
|
||||
autotests -->|зелёный| specs
|
||||
autotests -->|зелёный| code
|
||||
autotests -->|"зелёный, темы по плану"| basics
|
||||
autotests -->|"зелёный, large"| adversary
|
||||
autotests -->|"зелёный, large"| ops
|
||||
autotests -->|"зелёный, large"| proof
|
||||
autotests -->|"зелёный, large"| architecture
|
||||
adversary -. один ресурс — машина .- ops
|
||||
specs --> triage
|
||||
code --> triage
|
||||
basics --> triage
|
||||
adversary --> triage
|
||||
ops --> triage
|
||||
proof --> triage
|
||||
architecture --> triage
|
||||
```
|
||||
|
||||
@@ -492,9 +494,8 @@ flowchart TD
|
||||
сообщением**. Источник графа — гейт: он один по построению и идёт первым. На
|
||||
`medium` после зелёного гейта уходят разом `specs`, `code` и `basics`, и сразу
|
||||
триаж. На `small` — `specs` и `code`, а `basics` только при своих темах проекта.
|
||||
В `large` вместо тем `basics` идут три тяжёлых: `architecture` и первый из меряющей
|
||||
пары — сразу, второй меряющий — следом за первым, и он же определяет, когда
|
||||
стартует триаж.
|
||||
В `large` вместо тем `basics` уходят разом `proof` и `architecture` — ждать им
|
||||
нечего, машину не держит ни один, — и триаж стартует, когда вернулся последний.
|
||||
|
||||
**Схема здесь старше прозы.** Она не иллюстрация к тексту, а сам алгоритм
|
||||
планировщика; проза ниже объясняет рёбра и называет их цену. Разошлись — прав
|
||||
@@ -518,10 +519,13 @@ flowchart TD
|
||||
| Проход | Держит машину | Почему |
|
||||
|---|---|---|
|
||||
| `autotests` | да | запускает инструменты проекта — но он источник графа и один по построению |
|
||||
| `adversary` | да | находка есть **построенный путь**: он пишет падающий тест и гоняет его |
|
||||
| `ops` | да | доказывает числами: время удержания блокировки, пик кучи, темп роста журнала |
|
||||
| `triage` | да | проверяет оракул `critical`/`major` запуском — но он сток и тоже один |
|
||||
| `specs`, `code`, `basics`, `architecture`, `rubric`, `scope` | нет | читают и рассуждают, ничего не исполняют |
|
||||
| `triage` | да | проверяет оракул `major` запуском — но он сток и тоже один |
|
||||
| `specs`, `code`, `basics`, `proof`, `architecture`, `rubric`, `scope` | нет | читают и рассуждают, ничего не исполняют |
|
||||
|
||||
**В обычном прогоне цепочки за машину нет.** Оба прохода, что её держали —
|
||||
`adversary` и `ops`, — переехали в скилл `av-dev:code-deep-review`; там правило
|
||||
действует целиком, и дом его остаётся здесь. Оставшиеся двое машину держат, но
|
||||
каждый один по построению: один источник графа, другой сток.
|
||||
|
||||
**Правило про ресурс, а не про имена.** Раньше здесь стояло именованное
|
||||
исключение «`adversary` и `ops`»; оно рассыпается, как только проход начнёт
|
||||
@@ -663,8 +667,10 @@ change**: у работы, не меняющей поведения, дельт
|
||||
|
||||
- **С меткой** — обычный прогон по change: разметку сделал `review-scope`, состав
|
||||
прогона выведен из метки.
|
||||
- **Без метки** — прогон сценария обслуживания: change нет, размечать нечего,
|
||||
план фиксирован и назван сценарием. Разметчик не запускается вовсе.
|
||||
- **Без метки** — размечать нечего, план фиксирован и назван вызывающим,
|
||||
разметчик не запускается вовсе. Так идут двое: сценарий обслуживания, у
|
||||
которого нет change, и скилл `av-dev:code-deep-review`, у которого нет задачи —
|
||||
он смотрит названную область кода.
|
||||
|
||||
**Без метки — не то же самое, что `small`.** `small` — это суждение о размере и
|
||||
сложности, снятое с изменения; отсутствие метки — утверждение, что снимать её
|
||||
@@ -867,52 +873,51 @@ Recall темы `conventions` равен длине конвенций прое
|
||||
взгляда на ось времени — значит изменение, которое не откатывается обратной
|
||||
правкой, на `small` не идёт вовсе, каким бы малым оно ни было.
|
||||
|
||||
## Ступень 4 — Доказательство (только `large`)
|
||||
## Ступень 4 — Риск и устройство (только `large`)
|
||||
|
||||
Три прохода, и все три уходят сразу после зелёного гейта, в одном ряду со
|
||||
ступенью 2. Каждый берёт свою тему и доводит её до **доказательства**:
|
||||
Два прохода, оба уходят сразу после зелёного гейта, в одном ряду со ступенью 2.
|
||||
Машину не держит ни один, ждать им нечего:
|
||||
|
||||
- `review-adversary`, тема `security` — находка есть **построенный путь**, а не
|
||||
свойство: он пишет падающий тест и гоняет его;
|
||||
- `review-ops`, тема `operations` — постмортем от симптома у владельца сервиса к
|
||||
строке кода, с числами;
|
||||
- `review-proof` — **две темы разом**, `security` и `operations`. Набросок пути
|
||||
(вход, преобразование, куда легло) и ось времени (миграция и откат, рост,
|
||||
удержание, чужая деградация). Строит сценарий рассуждением и ничего не
|
||||
запускает; потолки раздельные — 2 находки на тему;
|
||||
- `review-architecture`, тема `architecture` — концептуальная целостность на
|
||||
входе шире диффа.
|
||||
|
||||
**Первые двое помечены «держит машину», поэтому между ними ребро конфликта: они
|
||||
идут цепочкой, а не разом** (правило и его причина — в «Порядок прогона», раздел
|
||||
«Кто держит машину»). Направления у ребра нет: кто первый — неважно.
|
||||
`architecture` машину не держит и ждать ему нечего — он уходит в первой волне.
|
||||
**Доказательства на этой ступени больше нет, и это решение по цене.** Прежде обе
|
||||
темы закрывала пара тяжёлых проходов: `review-adversary` строил путь и **прогонял**
|
||||
падающий тест, `review-ops` снимал числа замером. Оба держали машину, шли
|
||||
цепочкой и стоили часов на каждой задаче, где запускались.
|
||||
|
||||
Цепочка не отменяется общим «гони по графу» — она и есть часть графа. Отменяет
|
||||
её только прямое слово оператора про эту пару, и тогда в границы покрытия идёт
|
||||
строка, что числа прогона сняты под соседней нагрузкой.
|
||||
Пара никуда не делась — её зовёт скилл **`av-dev:code-deep-review`**, который
|
||||
идёт не на задаче, а по названной области и время от времени. Замер, ради
|
||||
которого её и держали, остался: враждебный проход дал пять из семи выживших
|
||||
находок дозапуска на пяти задачах подряд, эксплуатационный — единственный, кто
|
||||
нашёл, что откат бинаря поверх новой схемы стартует молча. Ценность этой пары
|
||||
оплачивалась **на каждой** задаче, а получалась на немногих; теперь она
|
||||
оплачивается тогда, когда её решают получить.
|
||||
|
||||
**Эта ступень зарабатывает больше всех остальных вместе — и она же дороже всех
|
||||
остальных вместе.** Измерено на пяти задачах подряд: враждебный проход дал пять из
|
||||
семи выживших находок дозапуска (включая обе верхние); эксплуатационный —
|
||||
единственный, кто нашёл, что откат бинаря поверх новой схемы стартует молча. Оба
|
||||
несут внешний оракул по построению: один обязан путь **прогнать**, второй смотрит
|
||||
ось времени и эксплуатации. Ровно поэтому они и стоят денег: оракул добывается
|
||||
запуском, а запуск — это машина, цепочка и часы.
|
||||
**`review-proof` копит вход глубокому прогону.** Всё, что доказывается только
|
||||
запуском, он не выдаёт находкой и не выбрасывает: строка в границах покрытия
|
||||
называет тему, место и запуск, которым это проверяется. Строка — единственный
|
||||
вход `av-dev:code-deep-review`, заводящийся по ходу обычной работы.
|
||||
|
||||
Раньше эта пара стояла в `medium`, то есть на большинстве задач. Ступень
|
||||
переехала в `large` **сознательно и по цене, а не потому, что перестала находить**:
|
||||
она осталась самой ценной, но её ценность оплачивается на каждой задаче, а
|
||||
получается — на немногих. Что из-за этого перестало проверяться на младших метках, названо в «Честном пределе» и обязано идти строкой в границы покрытия
|
||||
каждого прогона `small` и `medium`.
|
||||
**Чем платит цикл, названо прямо.** `critical` эта ступень больше не присваивает:
|
||||
его оракул добывается запуском. Дефект, который виден только под нагрузкой —
|
||||
гонка, деградация, исчерпание ресурса, — в цикле задачи не ловится ничем; это
|
||||
идёт строкой в границы покрытия каждого прогона и разобрано в «Честном пределе».
|
||||
|
||||
Дома тем приходят из плана разметки задачи: `security` — враждебному, `operations`
|
||||
(эксплуатация и хранилище) — эксплуатационному, `architecture` (устройство,
|
||||
граница домена) — архитектурному. Что с чем сшивать и почему —
|
||||
[project-facts.md](references/project-facts.md), раздел «Сшивать обязаны
|
||||
проходы». Без домов ступень вырождается в общие места.
|
||||
Дома тем приходят из плана разметки задачи: `security` и `operations` —
|
||||
`review-proof`, `architecture` (устройство, граница домена) — архитектурному. Что
|
||||
с чем сшивать и почему — [project-facts.md](references/project-facts.md), раздел
|
||||
«Сшивать обязаны проходы». Без домов ступень вырождается в общие места.
|
||||
|
||||
**Числа и решения проекта эта ступень больше не читает.** `research.*` и `adr.*` —
|
||||
процессные документы, и прогон их не открывает. Для эксплуатационного прохода это
|
||||
значит, что **число он обязан снять сам** — замером, а не цитатой из чужой
|
||||
записки; для архитектурного — что граница домена берётся из `passport.*`, а не из
|
||||
истории решений. Обе потери названы в «Честном пределе».
|
||||
**Числа и решения проекта эта ступень не читает.** `research.*` и `adr.*` —
|
||||
процессные документы, и прогон их не открывает. Для `review-proof` это значит,
|
||||
что чужое число ему не оракул: он его не снимал, а свои он не снимает вовсе. Для
|
||||
архитектурного — что граница домена берётся из `passport.*`, а не из истории
|
||||
решений. Обе потери названы в «Честном пределе».
|
||||
|
||||
**Условие ступени и есть условие метки `large`:** изменение крупное **или**
|
||||
незнакомое — любая из двух осей. Разведены они не для красоты: у архитектурного
|
||||
@@ -1033,8 +1038,8 @@ change»: сверять исход с планом триаж обязан и
|
||||
Отдельно и честно: **поимённая сверка с положениями руководств по стилю языка не
|
||||
задаётся ни одним проходом.** Проход про идиоматичность упразднён, его способные
|
||||
части переселены (эксперимент против поведения библиотеки и драйвера — в `ops`,
|
||||
вопрос 8; «не изобретаем ли то, что уже есть в библиотеке» — в `architecture`,
|
||||
вопрос 1), но различение «идиоматично против распространено» теперь не спрашивает
|
||||
вопрос 8, а он теперь в `av-dev:code-deep-review`; «не изобретаем ли то, что уже
|
||||
есть в библиотеке» — в `architecture`, вопрос 1), но различение «идиоматично против распространено» теперь не спрашивает
|
||||
никто. Класс обратимый — портит форму кода, не данные, — и его надо признавать в
|
||||
границах покрытия, а не считать проверенным.
|
||||
|
||||
@@ -1068,14 +1073,21 @@ change»: сверять исход с планом триаж обязан и
|
||||
|
||||
**Темы при этом названы все — но закрыты они по-разному, и это надо читать
|
||||
буквально.** «Тема `security`, глубина сверка» не значит «безопасность
|
||||
проверена»: значит, что дом темы открыли, дифф посмотрели и сравнили. Между
|
||||
сверкой и доказательством лежит весь класс дефектов, который виден только
|
||||
построенным путём, — и он проверяется на 5–10% задач.
|
||||
проверена»: значит, что дом темы открыли, дифф посмотрели и сравнили.
|
||||
|
||||
Это сознательная сделка, а не пробел в устройстве: цена метки `large` платится на
|
||||
каждой задаче, а окупается на немногих. Проверяется сделка не рассуждением, а
|
||||
журналом дефектов: если класс, который ловят только меряющие проходы, начал
|
||||
всплывать после мерджа — метку выбирают слишком низко.
|
||||
**Доказательства в цикле задачи нет ни на одной метке, и это самая крупная его
|
||||
граница.** Класс дефектов, который виден только построенным путём и снятым
|
||||
числом — гонка, деградация под нагрузкой, исчерпание ресурса, откат бинаря поверх
|
||||
новой схемы, — не ловится здесь ничем: на `large` его смотрит `proof` чтением и
|
||||
называет отложенным, ниже `large` его не смотрит никто.
|
||||
|
||||
Это сознательная сделка, а не пробел в устройстве: пара меряющих проходов
|
||||
оплачивалась на каждой задаче с меткой `large`, а получалась на немногих. Теперь
|
||||
она живёт в `av-dev:code-deep-review` и оплачивается тогда, когда её решают
|
||||
получить. Проверяется сделка не рассуждением, а двумя следами: **строками
|
||||
«отложено»** в отчётах — если по одному месту повторяется один и тот же неснятый
|
||||
замер, глубокий прогон просрочен, — и **журналом дефектов**: класс, всплывающий
|
||||
после мерджа, значит, что прогон надо звать чаще.
|
||||
|
||||
Так же честно и про упразднённый проход: **«не знаю, чего не знаю» больше
|
||||
не достаёт никто.** Проход независимой реализации писал свою версию узла, не
|
||||
@@ -1100,6 +1112,9 @@ change»: сверять исход с планом триаж обязан и
|
||||
и где это лежит в документах проекта; таблица поразрядной деградации.
|
||||
- [references/review-levels.md](references/review-levels.md) — дом правила выбора
|
||||
метки: две оси, спорное вниз, чем `small` дешевле, доли как проверка правила.
|
||||
- Skill `av-dev:code-deep-review` — глубокое ревью области кода: там живут
|
||||
`review-adversary` и `review-ops`, там же единственное место процесса, где
|
||||
находка доказывается прогоном и замером.
|
||||
- Skill `av-dev:canon` — приведение проекта к канону документов.
|
||||
- [references/finding-contract.md](references/finding-contract.md) — контракт находок.
|
||||
- [references/promote.md](references/promote.md) — промоут находка → конвенция → правило → удаление.
|
||||
|
||||
@@ -88,8 +88,7 @@ stateDiagram-v2
|
||||
| `review-basics` | отказ, видимый чтением | убрать обработку ошибки записи так, чтобы отказ считался успехом |
|
||||
| `review-basics` | своя тема проекта | нарушить правило из документа, у которого нет именного прохода |
|
||||
| `review-architecture` | второй способ | завести вторую точку генерации id мимо единой |
|
||||
| `review-adversary` | построенный путь | принять внешний идентификатор без разбора до запроса в хранилище |
|
||||
| `review-ops` | деградация окружения | убрать обработку недоступности внешней зависимости в фоновом цикле |
|
||||
| `review-proof` | набросок пути и ось времени | принять внешний идентификатор без разбора до запроса в хранилище; убрать обработку недоступности внешней зависимости в фоновом цикле |
|
||||
| `review-triage` | шум | подать 20 находок, из них 15 вкусовщина и 3 дубля — проверить потолок и дедуп |
|
||||
|
||||
Метрик сверх этого не заводим. Precision, корреляция между проходами, стоимость
|
||||
|
||||
@@ -65,7 +65,7 @@
|
||||
«запись лежит сжатой и распаковывается целиком»; «блокировка удерживалась
|
||||
5.019 с» — гарантированный отказ соседа только рядом с известным таймаутом
|
||||
занятости. **Число проход снимает сам, на этом прогоне**, настройки берёт из
|
||||
`docs/database.md`, и сшивают их `ops` и `adversary`. Раньше числа брались из
|
||||
`docs/database.md`, и сшивает их `proof`. Раньше числа брались из
|
||||
`docs/research/`; теперь этот документ процессный, и замер неизвестной свежести
|
||||
больше не выдаёт себя за оракул.
|
||||
- **инвариант + обратимость.** severity берётся из `CLAUDE.md`; если её там
|
||||
|
||||
@@ -69,8 +69,10 @@
|
||||
|
||||
- **Спорно между `medium` и `large` → бери `medium`.** Ошибка в эту сторону
|
||||
стоит находки, которая всплывёт на следующей задаче или в журнале дефектов.
|
||||
Ошибка в обратную стоит трёх тяжёлых проходов, двое из которых держат машину и
|
||||
идут цепочкой, — и платится она **на каждой** задаче, выбранной неверно.
|
||||
Ошибка в обратную стоит двух лишних проходов на каждой задаче, выбранной
|
||||
неверно. Цена этого шага заметно упала: тяжёлая пара, что держала машину и шла
|
||||
цепочкой, переехала в `av-dev:code-deep-review`, и `large` теперь добавляет два
|
||||
прохода чтением, а не часы запусков.
|
||||
- **Спорно между `small` и `medium` → бери `medium`.** Раньше эта строка
|
||||
обосновывалась тем, что состав одинаков и ошибка почти бесплатна. Теперь состав
|
||||
разный, и обоснование стало прямо противоположным: на `small` три темы ядра
|
||||
@@ -101,7 +103,7 @@
|
||||
Обратное тоже верно и тоже не бесплатно: у каждой задачи есть **несокращаемый
|
||||
костяк — гейт, спеки, код, триаж**. Разрезать задачу, обе половины которой
|
||||
остаются в одной метке, значит заплатить костяк дважды за ту же проверку.
|
||||
Резать стоит там, где разрез **снимает доказательство с большей части диффа**.
|
||||
Резать стоит там, где разрез **снимает старшую метку с большей части диффа**.
|
||||
Шов и правило нарезки живут у того, кто ведёт задачи, — скилл
|
||||
`av-dev:task-track`, его раздел о нарезке. Пути туда конвейер не выносит: за
|
||||
пределы своего скилла он ходит вызовом, а не файлом.
|
||||
@@ -150,9 +152,10 @@
|
||||
## Доли — не пожелание, а проверка правила, и проверок две
|
||||
|
||||
**Сверху: `large` — 5–10%.** Если туда уходит каждая третья задача, метку
|
||||
выбирают по ощущению важности. Обратный перекос виден по журналу проскочивших
|
||||
дефектов: класс, который ловят только меряющие проходы, начинает всплывать после
|
||||
мерджа.
|
||||
выбирают по ощущению важности. Обратный перекос виден по двум следам: по журналу
|
||||
проскочивших дефектов и по строкам «отложено» в отчётах — если по одному месту
|
||||
повторяется один и тот же неснятый замер, дело не в метке, а в том, что глубокое
|
||||
ревью области просрочено.
|
||||
|
||||
**Снизу: `small` не должен обгонять `medium`.** Ориентир — до трети задач, но
|
||||
сравнение важнее числа: **перевес `small` над `medium` значит, что рабочее
|
||||
|
||||
Reference in New Issue
Block a user