refactor(skills): переработан плейбук координации Codex
- Зачем: - Актуализирована координация под Astra с сохранением замысла и бюджета контекста. - Что: - Разделены роли Astra, Sol и Luna; выбор приемов оставлен координатору. - Сохранены независимое ревью, триаж и проверка соразмерности исправлений. - Обновлены нативные механики и необязательная линия Claude CLI. - Проверка: - Проверены Markdown-ссылки, YAML и git diff --check; описано ограничение валидатора. - Пройден поведенческий сценарий с тремя тестами и независимое ревью Claude. - Перепроверены находки и фактическое продолжение фоновой сессии Claude.
This commit is contained in:
1 parent
65c802f8fc
commit
3a72ce906f
11 files changed
+538
-686
No files matched your search
@@ -1,155 +1,168 @@
|
||||
# Ревью и триаж
|
||||
|
||||
Читай этот файл целиком после выбора независимого ревью постановки или
|
||||
реализации. Режим и стоимость выбираются в [основной оптике](../SKILL.md);
|
||||
здесь один авторитетный договор выполнения.
|
||||
реализации. Это единственный подробный договор обзора, разбора находок и
|
||||
перепроверки.
|
||||
|
||||
- [Независимость и фокус](#независимость-и-фокус)
|
||||
- [Файловый маршрут](#файловый-маршрут)
|
||||
- [Отчёт ревьюера](#отчёт-ревьюера)
|
||||
- [Владелец триажа](#владелец-триажа)
|
||||
- [Перепроверка и круги](#перепроверка-и-круги)
|
||||
- [Что читает координатор](#что-читает-координатор)
|
||||
- [Выбор обзора](#выбор-обзора)
|
||||
- [Мандат и независимость](#мандат-и-независимость)
|
||||
- [Отчет ревьюера](#отчет-ревьюера)
|
||||
- [Разбор находок](#разбор-находок)
|
||||
- [Перепроверка](#перепроверка)
|
||||
- [Когда работа не сходится](#когда-работа-не-сходится)
|
||||
- [Доказательства для координатора](#доказательства-для-координатора)
|
||||
|
||||
## Независимость и фокус
|
||||
## Выбор обзора
|
||||
|
||||
Запускай ревьюера свежей сессией без истории исполнителя и других ревьюеров.
|
||||
Повторную проверку точечных исправлений продолжает тот же ревьюер: его контекст
|
||||
находок полезен и не отменяет независимость исходного обзора.
|
||||
Подбирай ревью по неопределенности и цене ошибки. Нативный ревьюер, Claude и
|
||||
свежая Astra - доступные линии. Обязательного набора нет. Отдельные основания:
|
||||
свежий контекст ловит предположения автора, другое семейство моделей замечает
|
||||
иные слепые зоны, Astra судит об устройстве и соразмерности. Одного обзора
|
||||
достаточно, если он закрывает существенный риск. Две сфокусированные линии
|
||||
оправданы, когда их независимый вклад стоит цены.
|
||||
|
||||
Для двойного ревью разделяй фокусы:
|
||||
Для двух линий заранее раздели фокус, например:
|
||||
|
||||
- **по задаче** — соответствие постановке, критериям, границам и ожидаемому
|
||||
результату;
|
||||
- **по коду** — корректность, межмодульные инварианты, регрессии, безопасность
|
||||
и честность тестов.
|
||||
- соответствие задаче, границам и наблюдаемому результату;
|
||||
- корректность, межмодульные инварианты, регрессии и честность проверок.
|
||||
|
||||
Давай обоим общую постановку и изменённый объём, но отдельный файл фокуса и
|
||||
отдельный путь отчёта. Они не знают о второй линии до завершения исходных
|
||||
обзоров. Разные семейства моделей предпочтительны; две доступные линии одного
|
||||
семейства всё равно полезны на сложной задаче, если их фокусы различаются.
|
||||
Перед первым обзором каждой линии зафиксируй проверяемую версию артефакта.
|
||||
Одна линия делает один общий обзор этой версии. Не запускай новый общий обзор
|
||||
той же линии без изменения версии или нового основания; точечные исправления
|
||||
проверяются узко.
|
||||
|
||||
Ревьюер — наблюдатель с нужными инструментами. Он может читать код, запускать
|
||||
тесты, проверять гипотезы, создавать временные кэши и писать назначенный файл
|
||||
отчёта. Исходники, постоянное окружение и Git он не меняет. Координатор
|
||||
сверяет состояние дерева до и после.
|
||||
## Мандат и независимость
|
||||
|
||||
## Файловый маршрут
|
||||
Исходный обзор запускается в свежем контексте без истории исполнителя и других
|
||||
ревьюеров. Ревьюер получает постановку, точные границы версии, свой фокус,
|
||||
доступные проверки и уникальный путь отчета. Он самостоятельно сверяет факты,
|
||||
а утверждения других агентов считает гипотезами до подтверждения.
|
||||
|
||||
Назначь каждому участнику уникальные файлы в каталоге задачи внутри
|
||||
`$SCRATCH`. Временные промпты и отчёты веди на английском.
|
||||
Ревьюеру разрешены чтение, тесты, доступная сеть, документация и временные
|
||||
файлы, нужные для проверки. Его мандат запрещает менять исходники, Git,
|
||||
службы, данные и другое постоянное состояние. Результат обзора - назначенный
|
||||
отчет; временные кэши и выводы инструментов допустимы.
|
||||
Координатор остается владельцем общего дерева и стенда и при необходимости
|
||||
сверяет их состояние до и после обзора.
|
||||
|
||||
Полный отчет пишет сам ревьюер в место, доступное владельцу триажа. Координатор
|
||||
не пересказывает и не восстанавливает доказательства по краткой сводке. Если
|
||||
общий файл недоступен, используй доступный канал и точно назови ограничение
|
||||
передачи: где остался полный отчет и какие доказательства не переживут сессию.
|
||||
Готовые английские блоки мандата и языка лежат в
|
||||
[шаблоне ревьюера](prompts/review-boilerplate.md) и
|
||||
[правиле обмена](prompts/runtime-language.md).
|
||||
|
||||
## Отчет ревьюера
|
||||
|
||||
Ревью возвращает проверяемые утверждения. Каждая находка получает
|
||||
устойчивый идентификатор с уникальным префиксом линии. Сохраняй идентификатор
|
||||
во всех следующих разборах и перепроверках. Полная запись содержит:
|
||||
|
||||
```text
|
||||
reviewer -> detailed report file -> triage owner
|
||||
|
|
||||
+-> short summary -> coordinator
|
||||
PREFIX-N | location | violated criterion | failure scenario | evidence |
|
||||
minimal verification
|
||||
```
|
||||
|
||||
Ревьюер сам пишет полный отчёт в назначенный файл. Координатор не принимает
|
||||
полный отчёт сообщением и не переписывает его перед передачей. Владелец
|
||||
триажа читает исходные отчёты напрямую и пишет подробные резолюции в следующий
|
||||
файл.
|
||||
Существенный риск безопасно отложенного решения можно записать как
|
||||
неблокирующее соображение без идентификатора, тяжести и влияния на вердикт.
|
||||
Если проект или линия уже задает шкалу, добавь в запись тяжесть и считай ее.
|
||||
Замечание о стиле без проверяемого ущерба остается соображением и не требует
|
||||
исправления.
|
||||
`CHANGES_REQUESTED` означает, что версия содержит хотя бы один дефект, который
|
||||
нужно исправить на ее собственном уровне. `APPROVED` означает отсутствие
|
||||
такого дефекта.
|
||||
|
||||
Если общий каталог недоступен, верни через контекст компактный индекс без
|
||||
нарратива. Координатор сразу сообщает партнёру, какой агент не получил доступ,
|
||||
к какому пути, какой запасной канал использован и что нужно проверить после
|
||||
задачи. Сбой канала ухудшает экономию контекста, но не отменяет ревью.
|
||||
Даже при нуле находок отчет называет просмотренный объем, проверенные гипотезы,
|
||||
запущенные команды и их результаты. Голый вердикт без свидетельств не
|
||||
засчитывается. Сообщение координатору может содержать только вердикт, доступные
|
||||
счетчики, по одной строке на идентификатор и на каждое существенное
|
||||
неблокирующее соображение, а также путь к подробному отчету.
|
||||
|
||||
## Отчёт ревьюера
|
||||
## Разбор находок
|
||||
|
||||
Каждая находка получает устойчивый идентификатор с уникальным префиксом
|
||||
линии: `SPEC-A-N` и `SPEC-B-N` для постановки, `TASK-N` для соответствия
|
||||
реализации задаче и `CODE-N` для качества кода. Полный файл содержит:
|
||||
Каждую находку сначала проверяют на трех осях: фактическая верность,
|
||||
применимость сценария к этому проекту и соразмерность исправления. Предложение
|
||||
ревьюера - один из вариантов. Исполнитель может закрыть дефект более подходящим
|
||||
путем. Аргументированное отклонение имеет тот же статус, что и подтвержденное
|
||||
исправление; квота отклонений не нужна.
|
||||
|
||||
- идентификатор, тяжесть и `файл:строка` либо раздел постановки;
|
||||
- нарушенный критерий;
|
||||
- сценарий сбоя и доказательство;
|
||||
- минимальный способ проверки.
|
||||
Находки о постановке разбирает координатор. Он сохраняет цель и границы,
|
||||
проверяет технические утверждения доступным способом и выносит владельцу
|
||||
продуктовый выбор или существенный риск.
|
||||
|
||||
Неблокирующее соображение не получает идентификатор и тяжесть, не входит в
|
||||
счётчики и не меняет вердикт. Так сохраняй только существенный риск от
|
||||
отложенного решения, не проектируя реализацию за следующего владельца.
|
||||
`CHANGES_REQUESTED` означает, что хотя бы одна находка требует исправить
|
||||
документ на его собственном уровне. `APPROVED` означает отсутствие такого
|
||||
дефекта, а не отсутствие всех будущих вопросов.
|
||||
Находки реализации разбирает исполнитель с контекстом кода. Он получает
|
||||
подробные отчеты напрямую. Координатор добавляет только решения уровня задачи,
|
||||
совпадения или противоречия линий. Каждый идентификатор получает один исход:
|
||||
|
||||
В сообщение координатору верни только:
|
||||
- `FIXED` - дефект подтвержден и исправлен; названы способ и проверка;
|
||||
- `REJECTED` - утверждение не подтвердилось, неприменимо к проекту или не
|
||||
описывает дефект по действующему договору; приведены контракт и доказательство;
|
||||
- `OUT_OF_SCOPE` - решение меняет согласованные границы;
|
||||
- `NEEDS_DECISION` - требуется выбор цели, устройства или остаточного риска.
|
||||
|
||||
- `VERDICT: APPROVED | CHANGES_REQUESTED`;
|
||||
- счётчики по тяжести;
|
||||
- по одной строке на находку: идентификатор, область, суть и тяжесть;
|
||||
- по одной строке на существенное неблокирующее соображение, если оно есть;
|
||||
- абсолютный путь к полному отчёту.
|
||||
`OUT_OF_SCOPE` и `NEEDS_DECISION` поднимаются координатору с вариантами,
|
||||
последствиями, стоимостью и рекомендацией исполнителя. Координатор не заменяет
|
||||
этот разбор молчаливым решением. Подробный файл резолюций сохраняет связь
|
||||
между исходной находкой, ее исходом и проверкой.
|
||||
|
||||
При отсутствии находок полный файл перечисляет просмотренный объём и
|
||||
выполненные проверки. Голая строка `APPROVED` без подтверждения работы не
|
||||
засчитывается.
|
||||
Отклонение предложенного способа починки само по себе не закрывает
|
||||
подтвержденный применимый дефект. Такой дефект получает соразмерное
|
||||
`FIXED`, либо решение владельца через `OUT_OF_SCOPE` или
|
||||
`NEEDS_DECISION`.
|
||||
|
||||
## Владелец триажа
|
||||
## Перепроверка
|
||||
|
||||
**Постановка.** Координатор принимает или отклоняет каждую находку, потому что
|
||||
цель, границы и критерии — его решения. Открытое техническое исследование он
|
||||
может отдать deep-reasoner, но сам читает верхнеуровневые документы и итоговую
|
||||
постановку. Продуктовый выбор и принятие риска выносит партнёру.
|
||||
Точечные исправления и отклонения проверяет тот же ревьюер в продолжении
|
||||
исходного контекста. Он читает собственный отчет, резолюции и измененную
|
||||
версию, затем проверяет исходные идентификаторы и только соседние изменения.
|
||||
Для каждого `FIXED` или `REJECTED` он возвращает `CLOSED`, `NOT_CLOSED`,
|
||||
`REJECTION_VALID` или `REJECTION_INVALID` с кратким доказательством.
|
||||
`OUT_OF_SCOPE` и `NEEDS_DECISION` переносятся в индекс без изменения:
|
||||
ревьюер их не пересматривает и не включает в свой вердикт. Они остаются
|
||||
открытыми до решения владельца.
|
||||
|
||||
**Реализация.** Пофиндинговый триаж делает исполнитель, у которого есть
|
||||
контекст кода. Координатор передаёт актуальные подробные отчёты выбранных линий
|
||||
без изменений и добавляет отдельную короткую шапку: совпадения, противоречия и
|
||||
возможный выход за границы. Он не сливает и не удаляет «дубликаты».
|
||||
Для `FIXED` ревьюер отдельно оценивает соразмерность починки:
|
||||
`PROPORTIONATE` либо `OVERREACH` с объяснением лишнего охвата. Для
|
||||
`REJECTED` он судит по аргументу и проверке; совпадение со вкусом не требуется.
|
||||
Узкая область не требует скрывать замеченный рядом новый дефект: такой дефект
|
||||
получает новый устойчивый идентификатор и возвращается владельцу триажа.
|
||||
|
||||
Для каждого идентификатора исполнитель возвращает один статус:
|
||||
Выбранная линия ревью закрывается после начального `APPROVED` без открытых
|
||||
вопросов либо после успешных нужных перепроверок и разрешения владельцем всех
|
||||
вынесенных вопросов. Полномочный владелец также может явно записать принятие
|
||||
оставшегося риска. Вердикт одной линии не закрывает открытые идентификаторы
|
||||
другой.
|
||||
|
||||
- `FIXED` — исправлено и названо доказательство;
|
||||
- `REJECTED` — отклонено через контракт и проверку;
|
||||
- `OUT_OF_SCOPE` — требует отдельного решения о границах;
|
||||
- `NEEDS_DECISION` — технического решения недостаточно.
|
||||
Изменения шире прежней версии, слабый исходный отчет или новая независимая
|
||||
неопределенность могут оправдать свежий общий обзор. Сам номер круга такого
|
||||
основания не создает.
|
||||
|
||||
Подробности остаются в файле триажа. Координатор получает по одной компактной
|
||||
строке `ID | status | essence` на находку, счётчики, вопросы уровня задачи и
|
||||
путь. Риск и выход за границы решает координатор; техническую истинность
|
||||
находки — исполнитель и ревьюер.
|
||||
## Когда работа не сходится
|
||||
|
||||
## Перепроверка и круги
|
||||
Сигналы несходимости: тот же спор повторяется без новых доказательств,
|
||||
исправления разрастаются дальше исходного риска, новые общие обзоры мало что
|
||||
добавляют или стороны проверяют разные версии и контракты. Координатор сначала
|
||||
останавливает петлю и устанавливает общий предмет спора. Затем он может
|
||||
уточнить постановку, сузить проверку, сменить исполнителя или ревьюера,
|
||||
повысить доступную модель или глубину, разделить задачу либо принять риск в
|
||||
пределах полномочий.
|
||||
|
||||
Один круг — назначенные обзоры, триаж его владельца и узкая перепроверка.
|
||||
Исходный ревьюер читает свой отчёт и файл резолюций, проверяет только свои
|
||||
находки и соседние изменения. Выбранное независимое ревью закрывается
|
||||
`APPROVED` либо явным принятием риска полномочным координатором или партнёром.
|
||||
Координатор получает по одной компактной строке со статусом каждого исходного
|
||||
или нового идентификатора; подробности остаются в файле перепроверки.
|
||||
Если идентификатор не закрыт либо появился рядом с исправлением, актуальный
|
||||
отчёт перепроверки напрямую идёт владельцу следующего триажа. Координатор не
|
||||
восстанавливает доказательства из компактной сводки.
|
||||
Третий круг - практическое напоминание явно объяснить пользователю или
|
||||
полномочному владельцу, почему работа не сходится, сколько стоит продолжение и
|
||||
какой подход меняется. Пятый круг - напоминание не начинать еще один повтор
|
||||
без явного решения. Это ориентиры наблюдения; обязательных этапов и
|
||||
автоматических запросов разрешения здесь нет.
|
||||
|
||||
Повторно поднятое аргументированно отклонённое замечание пометь как спор и
|
||||
отправь на отдельную узкую проверку усиленного уровня. Полный новый обзор
|
||||
нужен, когда реализация широко изменилась, исходный отчёт слаб или требуется
|
||||
новая независимая линия.
|
||||
## Доказательства для координатора
|
||||
|
||||
Третий круг — точка вмешательства: сообщи партнёру, почему процесс не сходится,
|
||||
какова стоимость и что меняешь. Координатор может уточнить постановку,
|
||||
повысить модель или effort, заменить исполнителя свежим сильным агентом,
|
||||
разделить задачу, назначить усиленный гейт либо принять риск в пределах
|
||||
мандата.
|
||||
Координатор обычно получает вердикт, счетчики, компактные строки находок и
|
||||
пути. Он раскрывает подробный отчет, когда находка меняет границы или риск,
|
||||
линии противоречат друг другу, возник спор, сводка не дает основания для
|
||||
решения либо это нужно для собственной приемки. Для спорного утверждения он
|
||||
читает соответствующее доказательство. Весь diff или журнал нужен лишь когда
|
||||
узкого фрагмента недостаточно.
|
||||
|
||||
Пятый круг не начинай автоматически. Сначала прими явное решение и объясни его
|
||||
партнёру; если полномочий недостаточно, остановись и запроси решение. Это
|
||||
предохранитель от дорогой вложенной петли, а не запрет координатору управлять
|
||||
работой.
|
||||
|
||||
## Что читает координатор
|
||||
|
||||
Краткие строки находок нужны координатору для сравнения линий. Подробный файл
|
||||
открывай, когда находка меняет границы или риск, ревьюеры противоречат друг
|
||||
другу, возник спор, сводка непонятна либо без деталей нельзя выбрать следующий
|
||||
шаг.
|
||||
|
||||
Для обычной починки координатор видит переход:
|
||||
|
||||
```text
|
||||
CHANGES_REQUESTED -> triaged -> rechecked -> APPROVED
|
||||
```
|
||||
|
||||
Полный diff, доказательства и журналы читают назначенные агенты. Координатор
|
||||
углубляется в них по правилам приёмки основной оптики, когда это нужно для его
|
||||
собственного решения.
|
||||
Так защита контекста остается ступенчатой: подробности доходят до владельца
|
||||
триажа напрямую, а Astra читает ровно тот уровень, который нужен для
|
||||
самостоятельного решения.
|
||||
Reference in new issue
Block a user