dev-skills/av-dev/skills/code-deep-review/SKILL.md

---
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` судит изменение,
этот скилл судит написанное**. Там вход — дифф и дельта-спеки, здесь — область
кода и её история. Там исход — правки в том же прогоне, здесь — разговор и
задачи.

## Зачем он появился

Тяжёлые проходы стояли в цикле задачи: `review-adversary` строил путь и прогонял
падающий тест, `review-ops` снимал числа замером, `review-architecture` судил
форму решения на входе шире диффа. Первые двое держали машину и шли цепочкой,
третий требовал карты проекта; все трое стоили часов **на каждой задаче**, где
запускались, — при том что их ценность оплачивается на каждой, а получается на
немногих.

Их вынесли сюда целиком, и цикл задачи после этого проверяет **корректность и
механику**: заказанное против сделанного, дефект, который сработает сам,
конвенции проекта и сверку с записанными инвариантами `CLAUDE.md`. Темы
`security`, `operations` и `architecture` остались там ровно в объёме
инвариантов — свойства, которого в них нет, цикл не спросит.

**Вход этому скиллу копят проходы цикла.** Строка «отложено в
`av-dev:code-deep-review`» в границах покрытия называет тему, место и запуск,
которым это проверяется; триаж сводит такие строки в отдельную секцию отчёта.
Второй источник — сигнал «это изменение просит глубокого ревью»: его подаёт
`review-code` всегда и `review-basics`, когда запускается.

## Когда звать

**Зовёт человек**, и признак наблюдаемый, а не календарный:

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

**Не на задаче и не по расписанию.** Цена реальная: два прохода держат машину и
идут цепочкой, вход шире диффа собирается командой проекта, а разбор находок
требует человека. Прогон по каждой задаче был бы ровно той церемонией, ради
снятия которой проходы отсюда и переехали.

## Чего может не быть

**Копия.** Дом правила — `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-adversary` прогоняет
падающий тест, `review-ops` снимает числа замером. `review-architecture` и
`review-code` машину не держат — они дают **разбор на входе шире диффа**, и
выдать доказательство им нечем. Постоянен и состав цикла задачи, но он другой и
мельче: разница между скиллами не в старательности, а в том, что здесь запускают,
меряют и строят путь.

| Проход | Тема | Что делает |
|---|---|---|
| `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.md` — документ рода «новое»**
(`av-dev:doc-sync`, «Два рода правок»): слово по каждой находке человек уже сказал
в разборе, и след цитирует ровно его решения. Правило то же, что у сужения
проверок: спрашивается новое, которое заметил ты, а не то, что человек только что
решил вслух.

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

## Доклад

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

## Тонкости

- **Прогон не правит код** — ни строки. Единственный его артефакт, кроме
  разговора, это задачи и запись в журнале ревью.
- **Область меньше — прогон лучше.** Модуль разбирается до конца, сервис целиком
  даёт список, который бросают на середине.
- **Находка о процессе — тоже находка.** Пустой список отложенного, дефект,
  трижды проскочивший в одном узле, тема без дома — всё это идёт в доклад наравне
  с находками о коде.
- **Задачи здесь нет, и границей служит только область.** Дифф, дельта-спеки,
  критерии приёмки — всё это про задачу; сюда они не приходят, и подставлять их
  «по аналогии» нельзя.