Сплошное ревью всего репозитория блоками: карта покрытия «файл → блок», гипотезы как второй знаменатель, три роли агентов (охотник, проверяющий, исполнитель) и состояние на диске, которое переживает смену сессий.
Ревью всего кода, а не диффа: репозиторий режется на блоки, каждый блок проходят четыре роли — охотник, проверяющий, исполнитель, ревьюер починки, — а полноту доказывает карта покрытия: ни одного файла без блока. Сессии меняются, контекст кончается, поэтому **всё состояние живёт на диске** в `docs/review/` проекта и читается обратно инструментом. Ничего не держи в памяти переписки. Основатель метода — **Георгий Худобандаев**: набор родился на его проекте, и всё устройство пришло оттуда. Исходный код, тесты и история изменений — [github.com/mikey-semy/finetooth](https://github.com/mikey-semy/finetooth) (там же ставится одной командой: `npx skills add mikey-semy/finetooth`). Лицензия MIT на обоих авторов, полный текст — в `references/LICENSE`.
Все действия — через `scripts/review.py` скилла, **запущенный из корня ревьюируемого репозитория**: корень берётся у git по рабочему каталогу. Нужны git и Python 3, только стандартная библиотека. Ниже инструмент называется `review`: поставленный в проект, он лежит в `.claude/skills/finetooth/scripts/review.py`. Если в `docs/review/blocks.json` есть поле `cli` — проект зовёт инструмент по-своему (`npm run review --`, `make review`), используй его. Сообщения самого инструмента — по-английски. Язык промптов ролей и образцов задаёт поле `lang` в `blocks.json` (`en` по умолчанию, `ru`): русские шаблоны лежат рядом с английскими с суффиксом `.ru.md`. Каждый отказ инструмента сам называет команду, которой он исправляется: читай отказ, а не угадывай.
В репозитории уже есть `docs/review/` — значит, ревью идёт. Не начинай своё параллельное. `review status` — где мы и какой блок следующий; `review next` — его id.
Why: Состояние на диске, а не в памяти прошлой сессии.
`review check`.
Why: Работа поверх противоречивого состояния множит ошибки: блок, закрытый на другой версии кода, выглядит пройденным.
`docs/review/journal.md` — что решили до тебя и почему.
Why: Находки восстановимы повторным прогоном, решения — нет.
`review setup --project <Имя>` — скелет `blocks.json`, `invariants.md` и точка входа `docs/review/README.md`. Если проект зовёт инструмент по-своему, добавь `--cli "<команда>"`; для русских промптов и образцов — `--lang ru`.
`docs/review/invariants.md` — правила ЭТОГО проекта. Вклеивается каждому агенту и решает, что тот сочтёт дефектом.
Why: Общие слова бесполезны: «код должен быть корректным» не помогает агенту отличить находку от придирки. Пиши то, за что проект уже заплатил.
В `docs/review/blocks.json` — `gates` (команды ворот проекта) и блоки: сквозные сначала, доменные потом, стендовые последними. `review inventory` печатает дерево репозитория с размерами и владением — нарезай по нему; `review sizes` показывает блоки выше порога. Блок, который чтение не докажет (качество тестов, производительность, сканеры), получает `"proof": "measured"`: доказательство — артефакты из манифеста, порог на него не действует. Блок без `paths` — живой стенд. Образец — `assets/blocks.example.json`.
Why: Блок — то, что читается за один сеанс: порог `readable_lines`, по умолчанию 6000 строк. Больше — и отчёт соврёт про охват.
`review init`, затем `review coverage` — разбирай непокрытые файлы, пока их не станет ноль.
Why: Файл в блок относит человек: попавший по совпадению шаблона будет числиться прочитанным, не будучи прочитанным.
`docs/review/blocks/<ID>-<слаг>.md`: зачем блок, что считается находкой, пронумерованные гипотезы про этот проект, критерий приёмки. Образец — `assets/manifest.example.md`.
Why: Без проектных гипотез ревью выходит «по общим соображениям». Эту часть не срезать.
`review prompt <ID> --role hunter` печатает готовый промпт — отдай его субагенту **целиком и без правок**. Агент сам пишет отчёт и черновик находок на диск. Затем `review set-status <ID> hunted`.
`review prompt <ID> --role verify`. Проверяет каждую находку исполнением, делает свой проход по самому опасному, перезаписывает файл находок. Затем `review set-status <ID> verified`.
Why: Ценность второй роли — не в фильтре, а в углублении; и работает она, только когда исполняет, а не перечитывает.
Прочитай оба отчёта и сверь с критерием приёмки.
Why: Отчёт агента отвечает «файл открывали», а критерий — «вопрос решён».
`review import <ID>`, `review findings`, `review check`.
`review log <ID> "что решили и почему"`.
Why: Что решили и почему — не восстанавливается ничем, кроме этой записи.
`review prompt <ID> --role fix`. Режь задания по связным областям, а не по одной находке. Ворота и проверку откатом прогоняй сам после исполнителя. Находки переводятся `review set-finding <ID…> fixed --commit <sha>` (несколько id разом); отложить можно только с причиной (`deferred --reason`).
Why: Класс дефекта с третьим экземпляром закрывается уздой (`--rule <путь к тесту или правилу>`), а не списком правок: иначе четвёртый придёт на следующей неделе.
`review prompt <ID> --role fixreview --diff main...HEAD [--round N] [--scope половина]`. Дифф вклеивается в промпт целиком; два агента на две половины диффа — нормально. Подтверждённые находки ревьюера заносятся добором (`import <ID> --append`), даже уже починенные.
Why: Правки пишет исполнитель, а смотрит тот, кто их не писал. Круги повторяются, пока ревьюер отвечает «следующий круг нужен»; круг, нашедший дефект, внесённый прошлым кругом, — сигнал остановиться и подумать.
`review set-status <ID> closed` — только после отчёта ревьюера правок.
Why: Без отчёта ревьюера правок блок с починками закрыть нельзя: `review check` это держит.
**Один агент не ищет и не чинит одновременно.** Чинит не тот, кто нашёл; проверяет не тот, кто чинил. Повторную починку — свежему агенту, не тому же: задание самодостаточно, а ошибки первого захода — ошибки внимания.
**Граница блока — полная остановка:** доложить владельцу и ждать команды на следующий. Открытый вопрос повторяется целиком, у каждого — кто решает и рекомендация.
**Блок не закрывается** без выполненного критерия приёмки и без отчёта проверяющего.
**Проверка за пределами своего репозитория — против свежего `origin` после `git fetch`.** Отставшее дерево показывает починенное как сломанное.
**Никаких ссылок на ревью в коде:** номера находок и блоков умрут вместе с `docs/review/`.
**Больше двух-трёх агентов разом не запускать**, если на машине идёт сборка.
Проверка красная — работа не сделана, даже если так кажется. Она ловит, среди прочего: - файл без блока и устаревшую карту покрытия; шаблон блока, под который попадают только нетрекнутые файлы; - файл читаемого блока, не названный полным путём ни в одном отчёте; - гипотезу без вердикта или с противоречивыми вердиктами; - отчёт охотника без раздела «Границы охвата» и пустой отчёт проверяющего; - отложенную находку без причины, блок в `blocked` без записки, фазы не по порядку; - закрытый с починками блок без ревью правок; - блок и находку, закрытые на другой версии кода (отпечатки — `review restamp`, если правки к делу не относятся; `review backfill` — для записей старше отпечатков); - находку без причины отказа, коммит починки, не трогающий файл, дубль несуществующей находки, узду по несуществующему пути; - дерево, отставшее от сервера больше чем на неделю.
Все блоки `closed`, открытых находок нет, у каждой отвергнутой — причина. Долговечное переезжает: правила — в корневой файл инструкций, решения — в ADR, проверки — в тесты.
Why: Каталог ревью — леса вокруг стройки, а не часть здания. Но без итога следующее ревью начнётся с нуля.
- `references/hunter.md`, `verify.md`, `fix.md`, `fixreview.md` — шаблоны ролей (английские; русские рядом — `<роль>.ru.md`, выбираются по `lang`). Промпт из них собирает `review prompt`; читать их нужно, только чтобы понять или поправить роль. Проект может держать свою версию в `docs/review/prompts/<роль>.md` — тогда берётся она. - `references/lessons.md` — уроки двух ревью, из которых выросли правила: читать до первого блока. - `references/LICENSE` — MIT, оба автора. - `assets/` — образцы (тоже в двух языках): блоки, манифест, инварианты, дневник, баннер для корневого файла инструкций, цели `make` и `package.json`, пример узды.