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

name, description

name

description

code-deep-review

Глубокое ревью области кода — не задачи, а куска проекта: модуля, слоя, сервиса целиком. Зовёт проходы, которых нет в цикле задачи: 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.

Когда звать

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

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

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

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

Копия. Дом правила — 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	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, который владеет этим документом. В следе: область, состав проходов, что взято задачами, что отвергнуто и почему, что проверить было невозможно.

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

Доклад

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

Тонкости

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