0 Fork 0

Files

T

Dmitriy Dementiev 02a98df8c3 fix(codex-playbook): уточнён вердикт ревью планов

- Зачем:
  - ревью высокоуровневых документов могло требовать преждевременных деталей и постоянно блокировать одобрение.
- Что:
  - находки ограничены дефектами на уровне самого документа.
  - существенные отложенные риски отделены от блокирующих замечаний.
  - уточнено, что APPROVED допускает открытые вопросы будущей реализации.
- Проверка:
  - quick_validate.py, git diff --check и проверка локальных Markdown-путей.

2026-07-13 14:09:25 +03:00

12 KiB

Raw Blame History

Ревью и триаж

Читай этот файл целиком после выбора независимого ревью постановки или реализации. Режим и стоимость выбираются в основной оптике; здесь один авторитетный договор выполнения.

Независимость и фокус
Файловый маршрут
Отчёт ревьюера
Владелец триажа
Перепроверка и круги
Что читает координатор

Независимость и фокус

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

Для двойного ревью разделяй фокусы:

по задаче — соответствие постановке, критериям, границам и ожидаемому результату;
по коду — корректность, межмодульные инварианты, регрессии, безопасность и честность тестов.

Давай обоим общую постановку и изменённый объём, но отдельный файл фокуса и отдельный путь отчёта. Они не знают о второй линии до завершения исходных обзоров. Разные семейства моделей предпочтительны; две доступные линии одного семейства всё равно полезны на сложной задаче, если их фокусы различаются.

Ревьюер — наблюдатель с нужными инструментами. Он может читать код, запускать тесты, проверять гипотезы, создавать временные кэши и писать назначенный файл отчёта. Исходники, постоянное окружение и Git он не меняет. Координатор сверяет состояние дерева до и после.

Файловый маршрут

Назначь каждому участнику уникальные файлы в каталоге задачи внутри $SCRATCH. Временные промпты и отчёты веди на английском.

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

Пятый круг не начинай автоматически. Сначала прими явное решение и объясни его партнёру; если полномочий недостаточно, остановись и запроси решение. Это предохранитель от дорогой вложенной петли, а не запрет координатору управлять работой.

Что читает координатор

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

Для обычной починки координатор видит переход:

CHANGES_REQUESTED -> triaged -> rechecked -> APPROVED

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

12 KiB Raw Blame History