Dmitriy Dementiev
02a98df8c3
- Зачем: - ревью высокоуровневых документов могло требовать преждевременных деталей и постоянно блокировать одобрение. - Что: - находки ограничены дефектами на уровне самого документа. - существенные отложенные риски отделены от блокирующих замечаний. - уточнено, что APPROVED допускает открытые вопросы будущей реализации. - Проверка: - quick_validate.py, git diff --check и проверка локальных Markdown-путей.
156 lines
12 KiB
Markdown
156 lines
12 KiB
Markdown
# Ревью и триаж
|
|
|
|
Читай этот файл целиком после выбора независимого ревью постановки или
|
|
реализации. Режим и стоимость выбираются в [основной оптике](../SKILL.md);
|
|
здесь один авторитетный договор выполнения.
|
|
|
|
- [Независимость и фокус](#независимость-и-фокус)
|
|
- [Файловый маршрут](#файловый-маршрут)
|
|
- [Отчёт ревьюера](#отчёт-ревьюера)
|
|
- [Владелец триажа](#владелец-триажа)
|
|
- [Перепроверка и круги](#перепроверка-и-круги)
|
|
- [Что читает координатор](#что-читает-координатор)
|
|
|
|
## Независимость и фокус
|
|
|
|
Запускай ревьюера свежей сессией без истории исполнителя и других ревьюеров.
|
|
Повторную проверку точечных исправлений продолжает тот же ревьюер: его контекст
|
|
находок полезен и не отменяет независимость исходного обзора.
|
|
|
|
Для двойного ревью разделяй фокусы:
|
|
|
|
- **по задаче** — соответствие постановке, критериям, границам и ожидаемому
|
|
результату;
|
|
- **по коду** — корректность, межмодульные инварианты, регрессии, безопасность
|
|
и честность тестов.
|
|
|
|
Давай обоим общую постановку и изменённый объём, но отдельный файл фокуса и
|
|
отдельный путь отчёта. Они не знают о второй линии до завершения исходных
|
|
обзоров. Разные семейства моделей предпочтительны; две доступные линии одного
|
|
семейства всё равно полезны на сложной задаче, если их фокусы различаются.
|
|
|
|
Ревьюер — наблюдатель с нужными инструментами. Он может читать код, запускать
|
|
тесты, проверять гипотезы, создавать временные кэши и писать назначенный файл
|
|
отчёта. Исходники, постоянное окружение и Git он не меняет. Координатор
|
|
сверяет состояние дерева до и после.
|
|
|
|
## Файловый маршрут
|
|
|
|
Назначь каждому участнику уникальные файлы в каталоге задачи внутри
|
|
`$SCRATCH`. Временные промпты и отчёты веди на английском.
|
|
|
|
```text
|
|
reviewer -> detailed report file -> triage owner
|
|
|
|
|
+-> short summary -> coordinator
|
|
```
|
|
|
|
Ревьюер сам пишет полный отчёт в назначенный файл. Координатор не принимает
|
|
полный отчёт сообщением и не переписывает его перед передачей. Владелец
|
|
триажа читает исходные отчёты напрямую и пишет подробные резолюции в следующий
|
|
файл.
|
|
|
|
Если общий каталог недоступен, верни через контекст компактный индекс без
|
|
нарратива. Координатор сразу сообщает партнёру, какой агент не получил доступ,
|
|
к какому пути, какой запасной канал использован и что нужно проверить после
|
|
задачи. Сбой канала ухудшает экономию контекста, но не отменяет ревью.
|
|
|
|
## Отчёт ревьюера
|
|
|
|
Каждая находка получает устойчивый идентификатор с уникальным префиксом
|
|
линии: `SPEC-A-N` и `SPEC-B-N` для постановки, `TASK-N` для соответствия
|
|
реализации задаче и `CODE-N` для качества кода. Полный файл содержит:
|
|
|
|
- идентификатор, тяжесть и `файл:строка` либо раздел постановки;
|
|
- нарушенный критерий;
|
|
- сценарий сбоя и доказательство;
|
|
- минимальный способ проверки.
|
|
|
|
Неблокирующее соображение не получает идентификатор и тяжесть, не входит в
|
|
счётчики и не меняет вердикт. Так сохраняй только существенный риск от
|
|
отложенного решения, не проектируя реализацию за следующего владельца.
|
|
`CHANGES_REQUESTED` означает, что хотя бы одна находка требует исправить
|
|
документ на его собственном уровне. `APPROVED` означает отсутствие такого
|
|
дефекта, а не отсутствие всех будущих вопросов.
|
|
|
|
В сообщение координатору верни только:
|
|
|
|
- `VERDICT: APPROVED | CHANGES_REQUESTED`;
|
|
- счётчики по тяжести;
|
|
- по одной строке на находку: идентификатор, область, суть и тяжесть;
|
|
- по одной строке на существенное неблокирующее соображение, если оно есть;
|
|
- абсолютный путь к полному отчёту.
|
|
|
|
При отсутствии находок полный файл перечисляет просмотренный объём и
|
|
выполненные проверки. Голая строка `APPROVED` без подтверждения работы не
|
|
засчитывается.
|
|
|
|
## Владелец триажа
|
|
|
|
**Постановка.** Координатор принимает или отклоняет каждую находку, потому что
|
|
цель, границы и критерии — его решения. Открытое техническое исследование он
|
|
может отдать deep-reasoner, но сам читает верхнеуровневые документы и итоговую
|
|
постановку. Продуктовый выбор и принятие риска выносит партнёру.
|
|
|
|
**Реализация.** Пофиндинговый триаж делает исполнитель, у которого есть
|
|
контекст кода. Координатор передаёт актуальные подробные отчёты выбранных линий
|
|
без изменений и добавляет отдельную короткую шапку: совпадения, противоречия и
|
|
возможный выход за границы. Он не сливает и не удаляет «дубликаты».
|
|
|
|
Для каждого идентификатора исполнитель возвращает один статус:
|
|
|
|
- `FIXED` — исправлено и названо доказательство;
|
|
- `REJECTED` — отклонено через контракт и проверку;
|
|
- `OUT_OF_SCOPE` — требует отдельного решения о границах;
|
|
- `NEEDS_DECISION` — технического решения недостаточно.
|
|
|
|
Подробности остаются в файле триажа. Координатор получает по одной компактной
|
|
строке `ID | status | essence` на находку, счётчики, вопросы уровня задачи и
|
|
путь. Риск и выход за границы решает координатор; техническую истинность
|
|
находки — исполнитель и ревьюер.
|
|
|
|
## Перепроверка и круги
|
|
|
|
Один круг — назначенные обзоры, триаж его владельца и узкая перепроверка.
|
|
Исходный ревьюер читает свой отчёт и файл резолюций, проверяет только свои
|
|
находки и соседние изменения. Выбранное независимое ревью закрывается
|
|
`APPROVED` либо явным принятием риска полномочным координатором или партнёром.
|
|
Координатор получает по одной компактной строке со статусом каждого исходного
|
|
или нового идентификатора; подробности остаются в файле перепроверки.
|
|
Если идентификатор не закрыт либо появился рядом с исправлением, актуальный
|
|
отчёт перепроверки напрямую идёт владельцу следующего триажа. Координатор не
|
|
восстанавливает доказательства из компактной сводки.
|
|
|
|
Повторно поднятое аргументированно отклонённое замечание пометь как спор и
|
|
отправь на отдельную узкую проверку усиленного уровня. Полный новый обзор
|
|
нужен, когда реализация широко изменилась, исходный отчёт слаб или требуется
|
|
новая независимая линия.
|
|
|
|
Третий круг — точка вмешательства: сообщи партнёру, почему процесс не сходится,
|
|
какова стоимость и что меняешь. Координатор может уточнить постановку,
|
|
повысить модель или effort, заменить исполнителя свежим сильным агентом,
|
|
разделить задачу, назначить усиленный гейт либо принять риск в пределах
|
|
мандата.
|
|
|
|
Пятый круг не начинай автоматически. Сначала прими явное решение и объясни его
|
|
партнёру; если полномочий недостаточно, остановись и запроси решение. Это
|
|
предохранитель от дорогой вложенной петли, а не запрет координатору управлять
|
|
работой.
|
|
|
|
## Что читает координатор
|
|
|
|
Краткие строки находок нужны координатору для сравнения линий. Подробный файл
|
|
открывай, когда находка меняет границы или риск, ревьюеры противоречат друг
|
|
другу, возник спор, сводка непонятна либо без деталей нельзя выбрать следующий
|
|
шаг.
|
|
|
|
Для обычной починки координатор видит переход:
|
|
|
|
```text
|
|
CHANGES_REQUESTED -> triaged -> rechecked -> APPROVED
|
|
```
|
|
|
|
Полный diff, доказательства и журналы читают назначенные агенты. Координатор
|
|
углубляется в них по правилам приёмки основной оптики, когда это нужно для его
|
|
собственного решения.
|