From 158075e059922be0347008a8d5a5db3adf5406be Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Sat, 17 Oct 2026 16:03:50 +0200 Subject: [PATCH] =?UTF-8?q?feat(skills):=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2?= =?UTF-8?q?=D0=BB=D0=B5=D0=BD=20=D1=81=D0=BA=D0=B8=D0=BB=D0=BB=20cross-rev?= =?UTF-8?q?iew=20=D0=B4=D0=BB=D1=8F=20=D1=80=D0=B5=D0=B2=D1=8C=D1=8E=20?= =?UTF-8?q?=D0=BC=D0=BE=D0=B4=D0=B5=D0=BB=D1=8C=D1=8E=20=D0=B4=D1=80=D1=83?= =?UTF-8?q?=D0=B3=D0=BE=D0=B3=D0=BE=20=D1=81=D0=B5=D0=BC=D0=B5=D0=B9=D1=81?= =?UTF-8?q?=D1=82=D0=B2=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: два плейбука оркестрации разошлись, а из них на практике нужно только независимое ревью моделью другого семейства. - Что: линзы для ревьюера (по задаче, по коду, форма и вкус, вычитание, план), общий мандат и перепроверка; разбор находок остаётся у автора. Механика запуска вынесена в адаптеры: T3 Code, codex exec, claude -p. Следующие круги ревью идут продолжением сессии того же ревьюера. Старые плейбуки пока не удалены. - Проверка: запуск, запись отчёта и продолжение сессии прогнаны на codex-cli 0.163.0, Claude Code 2.1.302 и в T3 Code; два круга ревью скилла (gpt-6.1-sol, gpt-6-astra), находки исправлены; ссылки и YAML проверены скриптом. Co-Authored-By: Claude Opus 5.5 --- agents/.agents/skills/cross-review/SKILL.md | 166 ++++++++++++++++++ .../skills/cross-review/agents/openai.yaml | 4 + .../skills/cross-review/prompts/lens-code.md | 17 ++ .../skills/cross-review/prompts/lens-plan.md | 16 ++ .../skills/cross-review/prompts/lens-shape.md | 61 +++++++ .../skills/cross-review/prompts/lens-spec.md | 12 ++ .../cross-review/prompts/lens-subtract.md | 20 +++ .../skills/cross-review/prompts/mandate.md | 53 ++++++ .../skills/cross-review/prompts/recheck.md | 36 ++++ .../cross-review/references/launch-claude.md | 84 +++++++++ .../cross-review/references/launch-codex.md | 100 +++++++++++ .../cross-review/references/launch-t3.md | 89 ++++++++++ 12 files changed, 658 insertions(+) create mode 100644 agents/.agents/skills/cross-review/SKILL.md create mode 100644 agents/.agents/skills/cross-review/agents/openai.yaml create mode 100644 agents/.agents/skills/cross-review/prompts/lens-code.md create mode 100644 agents/.agents/skills/cross-review/prompts/lens-plan.md create mode 100644 agents/.agents/skills/cross-review/prompts/lens-shape.md create mode 100644 agents/.agents/skills/cross-review/prompts/lens-spec.md create mode 100644 agents/.agents/skills/cross-review/prompts/lens-subtract.md create mode 100644 agents/.agents/skills/cross-review/prompts/mandate.md create mode 100644 agents/.agents/skills/cross-review/prompts/recheck.md create mode 100644 agents/.agents/skills/cross-review/references/launch-claude.md create mode 100644 agents/.agents/skills/cross-review/references/launch-codex.md create mode 100644 agents/.agents/skills/cross-review/references/launch-t3.md diff --git a/agents/.agents/skills/cross-review/SKILL.md b/agents/.agents/skills/cross-review/SKILL.md new file mode 100644 index 0000000..4a9f1fb --- /dev/null +++ b/agents/.agents/skills/cross-review/SKILL.md @@ -0,0 +1,166 @@ +--- +name: cross-review +description: >- + Перекрёстное ревью своей работы моделью другого семейства (Claude ↔ Codex): + линзы для ревьюера, способы запуска и разбор находок самим автором. + Применяй, когда пользователь просит независимое или перекрёстное ревью, + ревью другой моделью, или когда готовое изменение либо план стоит показать + чужим глазам до сдачи. +--- + +# Перекрёстное ревью + +Ты автор изменения и остаёшься его владельцем. Ревьюер из другого семейства +моделей добавляет то, чего у тебя нет: свежая сессия не знает твоих +рассуждений, а другое семейство замечает иные классы ошибок. Его отчёт — +набор утверждений для проверки. Решения по ним принимаешь ты. + +Скилл даёт линзы, способы запуска и опыт разбора находок. Сколько линий +запускать, какие линзы брать и нужна ли перепроверка, решай по задаче и цене +ошибки. + +## Что передать ревьюеру + +Создай обменный каталог вне репозитория (`mktemp -d`) и напиши в нём +короткое поручение `brief.md`. Если переменные shell не сохраняются между +вызовами, дальше подставляй путь каталога целиком. В поручении: + +- **что проверять**: точная версия и способ её получить — diff-команда от + точки отсчёта, коммиты или пути. Ревьюер должен отличить проверяемое от + посторонних правок в дереве; +- **постановка**: путь к задаче, спеке или критериям приёмки. Без неё линза + «по задаче» работает вслепую — так и напиши; +- **команды проверки** и ожидаемый результат (например, число тестов); +- **места, где ты сам не уверен** — вопросами, без своих обоснований: + пересказ твоей логики лишает ревьюера независимости; +- **префикс находок** и **путь отчёта** (`REPORT`) — свои у каждого ревьюера. + +Поручение собирается конкатенацией: `cat brief.md prompts/mandate.md +prompts/lens-….md > prompt.md`. Файлы `prompts/` лежат в каталоге этого +скилла — там, откуда прочитан этот файл. Подставляй их как есть. + +## Линзы + +Линза — фокус ревьюера. Выбирай те, где в этом изменении правда может +прятаться ошибка. Два ревьюера параллельно, с разными линзами, видят +больше: у каждого свой контекст, и фокус не размывается. Один ревьюер с +несколькими линзами дешевле. + +- [`lens-spec.md`](prompts/lens-spec.md) — **по задаче**: сделано ли то, что + просили, что упущено, что добавлено сверх, можно ли пройти критерии, не + решив задачу. +- [`lens-code.md`](prompts/lens-code.md) — **по коду**: корректность, + инварианты, регрессии, безопасность, честность тестов. +- [`lens-shape.md`](prompts/lens-shape.md) — **форма и вкус**: эскиз решения + до чтения diff, глубина модулей, запахи кода по Фаулеру. +- [`lens-subtract.md`](prompts/lens-subtract.md) — **вычитание**: что можно + удалить без потери нужного поведения. Особенно полезна после нескольких + кругов исправлений и для моделей, склонных раздувать код. +- [`lens-plan.md`](prompts/lens-plan.md) — **план или спека до реализации**: + документ судится на своём уровне. + +Ревьюеру нужна сильная модель с высокой глубиной рассуждения. У слабой +модели больше ложных находок, и их разбор съедает экономию. Конкретные +модели указаны в адаптерах запуска. + +## Как запустить + +Способ запуска зависит от среды. Механика каждого — в отдельном файле: + +- [T3 Code](references/launch-t3.md) — если доступны инструменты + `orchestrator_capabilities` и `delegate_task`. Удобнее всего: приложение + само следит за задачей и будит тебя по завершении. +- [Codex из командной строки](references/launch-codex.md) — когда автор + Claude или другая модель. +- [Claude из командной строки](references/launch-claude.md) — когда автор + Codex или другая модель. + +Общее для всех способов: + +- ревьюер получает **свежую сессию**, а не копию твоей истории; +- ревьюер может то же, что ты: запускать тесты, ходить в сеть, создавать + временные файлы. Исходники и состояние защищает мандат в поручении. + Песочница только для чтения оставила бы ревьюеру одно чтение кода; +- перед запуском сними `git status --porcelain`, после — сверь: дерево + должно остаться прежним; +- пока ревьюер работает, проверяемые файлы не меняй, иначе он проверит + смесь двух версий. Правки, которые уже ясны, готовь рядом, во временном + каталоге; +- если ревьюеров или кругов несколько, веди в обменном каталоге короткий + реестр: кто проверял, какую версию, id сессии или задачи, пути отчётов, + открытые ID. Он переживёт сжатие контекста и пригодится для отчёта; +- код уходит к другому поставщику моделей. Просьба пользователя о + перекрёстном ревью покрывает проверяемое изменение и нужный ему контекст; + секреты и посторонние материалы в поручение не клади. + +## Разбор находок + +Разбирает находки автор: у тебя контекст кода и задачи. Пользователю нужен +итог в отчёте, а не участие в каждом споре. + +По каждой находке проверь три вещи: + +1. **Верна ли она фактически.** Воспроизведи сценарий, прочти код, запусти + тест. Ревьюеры ошибаются уверенно: выдумывают API, путают версии, + приписывают коду то, чего в нём нет, требуют защиты от невозможных + состояний. Уверенный тон — не доказательство. +2. **Применима ли к этому проекту** — его контрактам, масштабу, угрозам. +3. **Соразмерна ли починка риску.** Предложенный способ — один из вариантов. + Подтверждённый дефект закрывай лучшим путём, какой видишь; отказ от + предложенной починки сам дефект не закрывает. + +Бывает и обратная ошибка: отмахнуться от неудобной находки. Отклонение с +доводом от контракта или теста весит столько же, сколько исправление. +Отклонение без довода ничем не лучше пропущенной находки. + +Следи за сложностью. Исправление, которое добавляет больше, чем убирает +риска, — повод остановиться и поискать путь проще. Замечание о стиле без +показанного вреда — не дефект. + +Исход каждой находки — один из четырёх: + +- `FIXED` — подтверждена и исправлена; названа проверка, которая это + показывает (по возможности — тест, воспроизводящий дефект); +- `REJECTED` — не подтвердилась или неприменима; приведён довод; +- `OUT_OF_SCOPE` — верна, но починка выходит за границы задачи; +- `NEEDS_DECISION` — нужен выбор цели, устройства или допустимого риска. + +Последние два не решай молча правкой кода: вынеси пользователю с вариантами, +их ценой и своей рекомендацией. Если без ответа дальше идти нельзя — спроси +сразу, иначе — в итоговом отчёте. + +## Следующие круги + +Дороже всего в ревью — независимый контекст, который ревьюер набирает в +первом заходе: устройство кода, постановка, свои опыты. Набирается он один +раз. Все следующие круги отправляй в ту же сессию ревьюера: + +- **узкая перепроверка** — когда исправления нетривиальны или отклонение + могут оспорить. Отдай [`prompts/recheck.md`](prompts/recheck.md), путь к + своим резолюциям и что изменилось после ревью (diff-команду или список + файлов). Ревьюер проверяет только свои находки и оценивает, не вышла ли + починка шире нужного; +- **полный проход по новой версии** — когда изменения вышли за пределы + починок. Опиши, что изменилось, и попроси пройти новую версию теми же + линзами; ID прежних находок сохраняются. + +Свежий ревьюер нужен, когда прежний контекст мешает: ревьюер держится за +свои прошлые выводы, его сессия переполнена, его отчёт оказался слабым или +нужен взгляд другой модели. Если способ запуска не умеет продолжать сессию, +свежему ревьюеру дай пути к исходному поручению, отчёту и резолюциям, а +сохранённые прежним ревьюером скрипты и фикстуры он возьмёт по путям из +отчёта. + +Если спор повторяется без новых фактов, ещё один круг ничего не даст: реши +сам с доводом или вынеси пользователю. + +## Отчёт пользователю + +Коротко и обычными словами: + +- кто смотрел (модель, глубина, способ запуска), какую версию и какими + линзами; +- находки — по строке: ID, суть, исход; счётчики; +- что исправлено и чем это проверено, что отклонено и почему; +- что вынесено на решение пользователя; +- пути к полным отчётам; затраты времени и денег, если они известны. diff --git a/agents/.agents/skills/cross-review/agents/openai.yaml b/agents/.agents/skills/cross-review/agents/openai.yaml new file mode 100644 index 0000000..30ca913 --- /dev/null +++ b/agents/.agents/skills/cross-review/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Перекрёстное ревью" + short_description: "Перекрёстное ревью моделью другого семейства" + default_prompt: "Используй $cross-review: покажи готовое изменение ревьюеру другого семейства моделей, разбери его находки и дай мне короткий отчёт." diff --git a/agents/.agents/skills/cross-review/prompts/lens-code.md b/agents/.agents/skills/cross-review/prompts/lens-code.md new file mode 100644 index 0000000..97e1572 --- /dev/null +++ b/agents/.agents/skills/cross-review/prompts/lens-code.md @@ -0,0 +1,17 @@ +## Линза: по коду + +Попробуй сломать изменение. Ищи: + +- неверный результат на входах и состояниях, о которых автор не подумал: + пусто, граница диапазона, параллельный доступ, частичный сбой, повтор; +- нарушенные инварианты между модулями и поломки у вызывающего кода за + пределами diff; +- обработку ошибок, которая теряет данные, прячет причину или оставляет + состояние записанным наполовину; +- безопасность: недоверенный ввод, секреты, права доступа; +- честность тестов: тест проходит при любом коде, подменяет заглушкой то, + что сам проверяет, сверяет результат с тем же вычислением, что в коде, + а не с независимым ожидаемым значением, или остаётся зелёным при той + ошибке, от которой должен защищать. + +Воспроизведённый сбой лучше подозреваемого. Указывай, какой из двух у тебя. diff --git a/agents/.agents/skills/cross-review/prompts/lens-plan.md b/agents/.agents/skills/cross-review/prompts/lens-plan.md new file mode 100644 index 0000000..84495a3 --- /dev/null +++ b/agents/.agents/skills/cross-review/prompts/lens-plan.md @@ -0,0 +1,16 @@ +## Линза: план + +Ты проверяешь постановку, план или спеку, а не реализацию. Документ уйдёт +исполнителю, который сделает то, что написано. Ищи: + +- факты, которые расходятся с кодом: имена, пути, поведение, версии; +- решения, которые документ принимает молча или оставляет открытыми там, + где исполнителю придётся гадать; +- критерии приёмки, которые нельзя проверить или можно пройти, не решив + задачу; +- отсутствие наблюдаемости: как вообще станет видно, что всё работает. + +В детали реализации заходи только там, где документ молча её предрешает. +Открытые детали реализации не делают план неполным: `APPROVED` значит, что +в самом документе нет дефекта, который он должен исправить. Риски +отложенных решений записывай строками `NOTE:`. diff --git a/agents/.agents/skills/cross-review/prompts/lens-shape.md b/agents/.agents/skills/cross-review/prompts/lens-shape.md new file mode 100644 index 0000000..8b2cf7d --- /dev/null +++ b/agents/.agents/skills/cross-review/prompts/lens-shape.md @@ -0,0 +1,61 @@ +## Линза: форма и вкус + +Сильный исполнитель ошибается не в отделке кода, а в форме решения — в тех +решениях, которые постановка оставила открытыми. Чистый код такие ошибки +прячет, поэтому начни с формы, ещё до чтения изменённых файлов. + +1. По одной постановке набросай ожидаемую форму решения: какое вычисление + где живёт, что и примерно в каком объёме пересекает границы процессов и + хранилищ, какие артефакты должны появиться. Хватит нескольких строк. + Это гипотеза, а не образец, которому код обязан следовать. +2. Прочитай изменения и выпиши решения, которых постановка не требовала: + где размещены вычисления, какие данные идут через границы, какие + появились новые сущности, что сделано сверх просьбы. +3. Каждое расхождение с наброском и каждое такое решение оцени по + соглашениям репозитория, по риску и по размеру задачи. Формально верное, + но по сути неправильное — тоже находка: работа не по масштабу задачи, + артефакт, который не оправдывает своего существования, проверка, которая + проходит, ничего не доказывая. + +Набросок и список решений приведи в отчёте как выполненные проверки, даже +если находок нет. + +### Глубина модулей + +Глубокий модуль прячет много поведения за маленьким интерфейсом. Мелкий +заставляет вызывающего узнать почти столько же, сколько сам экономит. +Отмечай новые мелкие модули, слои, которые только передают вызов дальше, и +точки расширения с единственной реализацией, у которой не видно второй. + +### Запахи кода + +Оценивай находку о вкусе по цене жизни с этим кодом, а не по тому, ломает +ли она тест. Сверяй изменение с этим списком (Фаулер, «Рефакторинг», гл. 3). +Записанное соглашение репозитория важнее списка. Любой запах — повод для +суждения («возможно, Feature Envy»), а не нарушение правила. Пропускай то, +что уже проверяют линтеры и форматтеры. + +- **Mysterious Name** — имя скрывает, что делает или хранит сущность → + переименуй; если честное имя не находится, мутно само устройство. +- **Duplicated Code** — одна и та же логика в нескольких местах → вынеси её + и вызывай из обоих. +- **Feature Envy** — функция работает с чужими данными больше, чем со + своими → перенеси её к данным. +- **Data Clumps** — одни и те же несколько полей или параметров всё время + ходят вместе → собери их в один тип. +- **Primitive Obsession** — строка или число заменяют понятие предметной + области → дай понятию свой маленький тип. +- **Repeated Switches** — один и тот же выбор по типу повторяется → полиморфизм + или одна таблица соответствий на оба места. +- **Shotgun Surgery** — одно логическое изменение требует правок по многим + файлам → собери то, что меняется вместе, в один модуль. +- **Divergent Change** — один модуль правят по несвязанным причинам → + раздели так, чтобы каждая часть менялась по одной причине. +- **Speculative Generality** — абстракции, параметры или крючки для нужд, + которых у задачи нет → удали; встрой обратно, пока нужда не появится. +- **Message Chains** — длинные цепочки `a.b().c().d()` → спрячь обход за + одним методом первого объекта. +- **Middle Man** — модуль в основном передаёт вызовы дальше → вызывай + настоящую цель напрямую. +- **Refused Bequest** — наследник почти не пользуется тем, что унаследовал → + откажись от наследования в пользу композиции. diff --git a/agents/.agents/skills/cross-review/prompts/lens-spec.md b/agents/.agents/skills/cross-review/prompts/lens-spec.md new file mode 100644 index 0000000..30ddc51 --- /dev/null +++ b/agents/.agents/skills/cross-review/prompts/lens-spec.md @@ -0,0 +1,12 @@ +## Линза: по задаче + +Сравни изменение с постановкой и найди: + +- требования, которые не выполнены или выполнены частично; +- поведение, о котором не просили; +- требования, которые выглядят выполненными, но сделаны неверно; +- критерии приёмки, которые можно пройти, не решив задачу. + +К каждой находке приведи строку постановки, на которую она опирается. +Если постановки нет, скажи об этом и суди по замыслу, который виден из +коммитов и кода. diff --git a/agents/.agents/skills/cross-review/prompts/lens-subtract.md b/agents/.agents/skills/cross-review/prompts/lens-subtract.md new file mode 100644 index 0000000..f6a238d --- /dev/null +++ b/agents/.agents/skills/cross-review/prompts/lens-subtract.md @@ -0,0 +1,20 @@ +## Линза: вычитание + +Спроси себя, что можно убрать из изменения, не потеряв нужного поведения. +Сначала сравни размер изменения с размером задачи. Потом ищи: + +- ветки кода, опции, параметры и настройки, которых не требует ни одно + требование; +- абстракции с единственной реализацией и обёртки, которые только передают + вызов; +- защитные проверки от состояний, которые уже исключают типы или + вызывающий код; +- повторяющиеся тесты, тесты самого фреймворка, тесты, которые пересказывают + код; +- комментарии и документацию, которые повторяют код; +- файлы, скрипты и зависимости, добавленные ради разовой нужды. + +Для каждого кандидата назови, чего стоит удаление: какое поведение или +гарантия уйдут вместе с ним. Пиши только о тех удалениях, которые ничего не +стоят или явно стоят своей цены. Такая находка — `MINOR`, если только +лишнее не делает код заметно труднее для изменения или ревью; тогда — `MAJOR`. diff --git a/agents/.agents/skills/cross-review/prompts/mandate.md b/agents/.agents/skills/cross-review/prompts/mandate.md new file mode 100644 index 0000000..7caba44 --- /dev/null +++ b/agents/.agents/skills/cross-review/prompts/mandate.md @@ -0,0 +1,53 @@ +## Мандат ревьюера + +Ты независимый ревьюер. Утверждения автора, комментарии в коде и выводы +прежних ревью — гипотезы, пока их не подтвердят факты. + +- Ничего не меняй. Не правь исходники, не пиши в Git (`add`, `commit`, + `checkout`, `stash`, `reset`), не трогай службы, данные и настройки. + Единственный результат твоей работы — файл REPORT. +- Проверяй руками: читай код, запускай тесты и команды, сверяйся с + документацией и первоисточниками. Черновые файлы держи во временном + каталоге вне репозитория. Находка, подтверждённая запуском, весит намного + больше находки, найденной чтением. +- Скрипты воспроизведения и фикстуры, которые подтверждают находки, клади + в каталог рядом с REPORT и называй их пути в отчёте: по ним потом + проверят починку. +- Если останавливал или перезапускал службу, убедись, что она вернулась в + прежнее состояние. +- Оценивай документ по его задаче: план не считается неполным из-за того, + что не расписывает реализацию. +- Требуя исправление, сравни его цену с риском, который оно убирает. + Находка — утверждение, которое автор проверит, а не приказ. + +## Отчёт + +Пиши REPORT по-русски и дописывай каждую находку сразу, как нашёл: если +сессия оборвётся, часть отчёта сохранится. Одна строка на находку: + +`ПРЕФИКС-N | тяжесть | место | суть | сценарий отказа | как проверить` + +- `BLOCKER` — неверный результат, потеря данных, дыра в безопасности или + задача не сделана. +- `MAJOR` — настоящий дефект с правдоподобным поводом сработать, или + стоимость сопровождения, которая задаче не нужна. +- `MINOR` — дефект есть, но жить с ним дёшево. +- `NIT` — дело вкуса. Замечание о стиле без показанного вреда — не выше + `NIT`. + +`место` — `файл:строка` или раздел постановки. ID не меняются: в следующих +кругах на находки ссылаются только по ID. + +Заметный риск решения, которое можно спокойно отложить, пиши отдельной +строкой `NOTE: ...` — без ID и тяжести, на вердикт она не влияет. + +Если находок нет, перечисли, что именно ты просмотрел и какие проверки +запускал, с результатами. Голое «одобряю» — не ревью. + +Последняя строка REPORT: +`VERDICT: APPROVED | APPROVED_WITH_MINORS | CHANGES_REQUESTED` + +## Итоговое сообщение + +Верни только строку VERDICT, число находок по тяжести, по строке на каждую +находку BLOCKER и MAJOR (ID и суть) и `REPORT: <абсолютный путь>`. diff --git a/agents/.agents/skills/cross-review/prompts/recheck.md b/agents/.agents/skills/cross-review/prompts/recheck.md new file mode 100644 index 0000000..60cb799 --- /dev/null +++ b/agents/.agents/skills/cross-review/prompts/recheck.md @@ -0,0 +1,36 @@ +# Узкая перепроверка твоих находок + +Автор разобрал твои находки. Ниже — пути к исходному поручению, к твоему +отчёту и к резолюциям автора. Если сессия у тебя новая, сначала прочитай +все три файла: в поручении — постановка, границы проверяемой версии, мандат +и формат находок. Мандат прежний: ничего не меняй; читать и запускать тесты +можно. + +Проверяй только свои находки, а не всё изменение заново. Оценивай не только +то, закрыта ли находка, но и саму починку: соразмерна ли она и не сломала ли +что-то рядом. Чаще всего лишнее приходит из твоего же предписания, так что +проверь и его. Прежде чем назвать находку +незакрытой, убедись, что закрытое состояние вообще достижимо и что его цена +соразмерна тому, что оно защищает. Это взвешивание не смягчает находок о +доступе, данных и деньгах. + +Отклонение оценивай по доводу — контракт, тест, доказательство, — а не по +вкусу. Если по ходу заметил новый дефект, запиши его с новым ID в исходном +формате. + +Находки с исходом `OUT_OF_SCOPE` или `NEEDS_DECISION` ждут решения +владельца задачи. Их не пересматривай: перенеси строкой `ID | DEFERRED` и +не учитывай в итоговой строке. + +По строке на каждый остальной исходный ID: + +`ID | CLOSED | NOT_CLOSED (почему) | REJECTION_VALID | REJECTION_INVALID (почему)` + +Для исправленной находки (`FIXED`) допиши `| PROPORTIONATE` или +`| OVERREACH (что вышло шире, чем требовала находка)`. `OVERREACH` — сигнал +автору, а не блокер. + +Последняя строка: `RECHECK: ALL_CLOSED | ISSUES_REMAIN` + +Запиши результат по новому пути REPORT, указанному ниже, и верни только +последнюю строку, ID незакрытых находок и `REPORT: <абсолютный путь>`. diff --git a/agents/.agents/skills/cross-review/references/launch-claude.md b/agents/.agents/skills/cross-review/references/launch-claude.md new file mode 100644 index 0000000..7c98c22 --- /dev/null +++ b/agents/.agents/skills/cross-review/references/launch-claude.md @@ -0,0 +1,84 @@ +# Запуск Claude из командной строки + +Для автора, у которого есть shell и установлен `claude` (Claude Code CLI). +Проверено на Claude Code 2.1.302 (Linux, 2026-10-17): запуск с промптом из +stdin, запись отчёта, продолжение по id сессии, фоновая сессия. + +## Первый запуск + +```bash +# D — обменный каталог с готовым brief.md, S — каталог скилла +cat "$D/brief.md" "$S/prompts/mandate.md" "$S/prompts/lens-shape.md" \ + > "$D/prompt.md" + +cat "$D/prompt.md" | claude -p --permission-mode auto --model opus \ + --effort high --add-dir "$D" --output-format json \ + > "$D/out.json" 2> "$D/err.txt" + +jq -r '.session_id, .result, .is_error' "$D/out.json" +``` + +- **`--model opus`** — псевдоним последней модели Opus, он не устаревает с + выходом новых версий. Глубина ревью — `high`; выше — по просьбе + пользователя. +- **`--permission-mode auto`** разрешает запускать тесты, ходить в сеть и + создавать временные файлы; опасные действия отсекает встроенный + классификатор. Исходники защищает мандат. +- **`--add-dir "$D"`** разрешает запись отчёта в обменный каталог. +- **`--output-format json`** возвращает `session_id` для перепроверки, + `result` — финальное сообщение, `modelUsage` — фактическую модель и + стоимость для отчёта пользователю. + +## Ожидание + +`claude -p` держит процесс до конца ревью, а это часто дольше 10 минут. +Если твой инструмент shell столько не ждёт, есть два пути: + +- запусти ту же команду фоном средствами своей среды и жди завершения + процесса. Появление `out.json` ничего не значит: перенаправление создаёт + пустой файл сразу при запуске; +- или запусти фоновую сессию самого Claude: + + ```bash + claude --bg --permission-mode auto --model opus --effort high \ + --add-dir "$D" "Прочитай $D/prompt.md и выполни." < /dev/null + ``` + + Команда сразу печатает короткий id. Состояние сессии — + `claude agents --json --all` (поля `id`, `sessionId`, `state`); жди + `state: done`. Сам `REPORT` ревьюер дописывает по ходу, поэтому его + появление тоже не признак конца. `claude logs` выдаёт сырой вывод + терминала, агенту он бесполезен. Завершённую сессию останавливай + `claude stop `. + +В любом случае перед разбором проверь, что последняя строка `REPORT` — +`VERDICT: …`: иначе отчёт неполный. + +## Затраты + +`out.json` содержит `total_cost_usd`, `usage` (токены) и `modelUsage` +(разбивка по моделям, включая служебные вызовы). + +## Следующие круги + +Узкая перепроверка или полный проход по новой версии — продолжением той же +сессии. Что положить в поручение — в разделе «Следующие круги» SKILL.md. + +```bash +cat "$D/recheck-prompt.md" | claude -p --resume \ + --output-format json > "$D/recheck.json" 2> "$D/recheck-err.txt" +``` + +Модель сохраняется из первого запуска (проверено: продолжение шло на той же +Opus). Режим доступа и глубину заново не задавай; сверь, что `session_id` в +ответе совпал с исходным. Для фоновой сессии из `--bg` бери её `sessionId` +из `claude agents --json --all`. + +## Особенности ревьюеров Claude + +- Однострочный формат находок держат хуже: бывают многострочные записи и + развёрнутые подтверждения. Проверь индекс перед разбором. +- Видят картинки: графики, скриншоты, выводы ноутбуков. Если проверяемый + результат визуальный, это довод за Claude. +- Сильнее в механике кода и форме решения: нереализуемые формулировки, + мёртвые заглушки, неудачные имена и границы. diff --git a/agents/.agents/skills/cross-review/references/launch-codex.md b/agents/.agents/skills/cross-review/references/launch-codex.md new file mode 100644 index 0000000..83e69fa --- /dev/null +++ b/agents/.agents/skills/cross-review/references/launch-codex.md @@ -0,0 +1,100 @@ +# Запуск Codex из командной строки + +Для автора, у которого есть shell и установлен `codex`. Проверено на +codex-cli 0.163.0 (Linux, 2026-10-17): первый запуск, продолжение по id, +запись отчёта в обменный каталог. + +## Перед первым запуском + +На новой машине и после обновления Codex проверь, что команды внутри +песочницы вообще выполняются: + +```bash +codex sandbox -c 'sandbox_mode="workspace-write"' -- sh -c 'echo SANDBOX_OK' +``` + +На Linux отказ вида `bwrap: ... Failed RTM_NEWADDR` обычно значит, что +AppArmor запрещает непривилегированные user namespaces. Это настройка машины, +а не ревью: сообщи пользователю и сошлись на +[требования песочницы](https://learn.chatgpt.com/docs/sandboxing#prerequisites). +Работающий веб-поиск о песочнице ничего не говорит. + +## Первый запуск + +```bash +# D — обменный каталог с готовым brief.md, S — каталог скилла +cat "$D/brief.md" "$S/prompts/mandate.md" "$S/prompts/lens-code.md" \ + > "$D/prompt.md" + +set -o pipefail +cat "$D/prompt.md" | codex exec --json --strict-config --approve-for-me \ + --add-dir "$D" -m -c 'model_reasoning_effort=""' \ + -o "$D/final.md" - > "$D/log.jsonl" 2> "$D/err.txt" +``` + +- **Промпт — каналом через stdin** (`cat … | codex exec … -`): так он + доходит в любой среде. Поток событий и ошибки — в файлы; в свой контекст + читай только `final.md` и отчёт `REPORT`. +- **`--approve-for-me`** даёт песочницу `workspace-write` и сам одобряет + выход за неё: сеть, docker, команды вне каталога. Вместе с `-s` он не + принимается. Шире — `danger-full-access` — ревьюеру не нужно. +- **`--add-dir "$D"`** разрешает запись отчёта в обменный каталог. +- **Модель и глубину задавай явно.** Иначе они берутся из + `~/.codex/config.toml` и зависят от последней интерактивной сессии + пользователя. На 2026-10 для ревью кода обычно лучше всего подходит + `gpt-6.1-sol` с глубиной `high`. `gpt-6-astra` с `xhigh` сильнее и + заметно дороже: бери её по просьбе пользователя или когда ошибка особенно + дорога. Названия моделей быстро устаревают: при сомнении спроси + пользователя. +- **`--strict-config`** останавливает запуск при неизвестном ключе `-c`. + Без него опечатка молча заменяется настройкой по умолчанию. + +## Ожидание + +Ревью идёт от нескольких минут до получаса. Запускай команду фоном средствами +своей среды: в Claude Code — Bash с `run_in_background`, без `&` внутри +команды; среда разбудит тебя по завершении. + +- **id сессии** — в первой строке лога: + `head -1 "$D/log.jsonl" | jq -r .thread_id`. Сохрани его сразу: по нему + идут перепроверка и спасение, если процесс умер. +- **Признак жизни** — рост `log.jsonl`. Долгая сборка или тесты внутри + песочницы событий не пишут, поэтому застывший лог — повод посмотреть, а не + приговор. +- **Вердикт без находок** проверь по логу: работа это или отписка. + `grep -c '"command_execution"' "$D/log.jsonl"` — число выполненных команд. + Голое APPROVED при нуле команд перезапускай. + +## Затраты + +Токены по каждому ходу пишутся в лог: +`jq -c 'select(.type=="turn.completed") | .usage' "$D/log.jsonl"`. +Стоимости в выводе нет. + +## Следующие круги + +Узкая перепроверка или полный проход по новой версии — продолжением той же +сессии. Что положить в поручение — в разделе «Следующие круги» SKILL.md. + +```bash +cat "$D/recheck-prompt.md" | codex exec resume --json --strict-config \ + -m -c 'model_reasoning_effort=""' \ + -o "$D/recheck-final.md" - \ + > "$D/recheck-log.jsonl" 2> "$D/recheck-err.txt" +``` + +- **Только по явному id.** `--last` подхватит последнюю сессию, а при + нескольких ревьюерах это может быть чужая. +- Песочница и доступ к `$D` принадлежат сессии и сохраняются; ключей `-s`, + `--approve-for-me` и `--add-dir` у `resume` нет. +- Модель и глубину повтори явно — те же, что при первом запуске: иначе + подставятся значения из конфига, а смена глубины внутри сессии сбрасывает + кэш. + +## Особенности ревьюеров Codex + +- Мандат и формат отчёта держат надёжно. +- Бывает, требуют исправлений сверх цели задачи; в других прогонах все + починки выходили соразмерными. Проверяй соразмерность как обычно. +- Хорошо ловят уровень требований: недостающие критерии, наблюдаемость, + «формально отчитаться можно». diff --git a/agents/.agents/skills/cross-review/references/launch-t3.md b/agents/.agents/skills/cross-review/references/launch-t3.md new file mode 100644 index 0000000..f7b4376 --- /dev/null +++ b/agents/.agents/skills/cross-review/references/launch-t3.md @@ -0,0 +1,89 @@ +# Запуск через T3 Code + +Для автора, который работает внутри T3 Code и видит инструменты +`orchestrator_capabilities` и `delegate_task` (имена могут идти с префиксом +вроде `mcp__t3-code__`). Приложение само следит за дочерней задачей, будит +тебя по её завершении, а пользователь видит ход ревью в отдельном разговоре. +Проверено 2026-10-17: Claude → Codex. + +## Выбор модели + +Модель и глубину выбирай по адаптеру семейства ревьюера: +[Codex](launch-codex.md#первый-запуск) или +[Claude](launch-claude.md#первый-запуск). Вызови `orchestrator_capabilities`, +найди у нужного провайдера эту модель (`providerInstanceId`, `model`) и +проверь, что она есть в списке. Ключ глубины у провайдеров разный — +смотри `options` модели: у Codex это `reasoningEffort`, у Claude — +`effort`. + +## Запуск + +Собери `prompt.md` так же, как для командной строки, и передай его путь: + +```json +{ + "task": "Прочитай /tmp/…/prompt.md и выполни.", + "target": { + "providerInstanceId": "codex", + "model": "", + "options": { "reasoningEffort": "high" } + }, + "role": "review", + "mode": "async", + "title": "cross-review: <что проверяем>", + "clientRequestId": "<уникальный id этого раунда>" +} +``` + +- **`isolation` не задавай** (по умолчанию — общий checkout). Отдельный + worktree строится от последнего коммита, и незакоммиченные правки + ревьюер не увидит. +- **`runtimeMode` не задавай.** Режимы с подтверждением остановят ревьюера + на первом же действии и будут ждать человека в его разговоре. Ограничения + задаёт мандат в поручении. +- После запуска заверши ход: уведомление о завершении придёт само. + `task_status` нужен, только если результат требуется посреди хода. +- Итоговое сообщение ревьюера приходит в `summary`; полный отчёт — в файле + `REPORT`. + +## Следующие круги + +Следующие круги — узкую перепроверку и полный проход по новой версии — +отправляй тому же ревьюеру, в его дочерний разговор, когда предыдущая +задача уже завершилась. Это `t3_thread_send`: + +```json +{ + "threadId": "", + "message": "Прочитай /tmp/…/recheck-prompt.md и выполни.", + "mode": "auto", + "clientRequestId": "<уникальный id этого круга>" +} +``` + +- В дочернем разговоре появляется новая задача со своим `taskId`; по + завершении она будит тебя так же, как исходная. Ребёнок помнит свои + прошлые ходы (проверено 2026-10-17 на Codex). +- Модель, глубина и режим остаются от исходной задачи, поменять их нельзя. +- `childThreadId` запиши в реестр сразу после запуска ревью: разговор + хранит T3, но его id нужен тебе. +- Что положить в поручение круга — в разделе «Следующие круги» SKILL.md. + +Свежий ревьюер — новый `delegate_task` с новым `clientRequestId`. Когда он +нужен — там же, в SKILL.md. Если продолжить разговор не удалось, в +поручение свежей задачи положи пути к исходному `prompt.md`, отчёту +ревьюера и своим резолюциям. + +Системные инструкции T3 и описание `t3_thread_send` говорят об этом +по-разному. Первые велят на каждый круг ревью заводить новый +`delegate_task` и не продолжать делегированное ревью через +`t3_thread_send`. Второе отдаёт `delegate_task` независимым кругам, а +продолжение, которому нужен разговор того же ребёнка, отправляет в +`childThreadId`. Этот скилл намеренно выбирает продолжение: круги ревью +идут по уже набранному контексту ревьюера, а это дешевле и глубже, чем +набирать его заново. + +## Затраты + +T3 сообщает только время выполнения. Токены и стоимость видны в выводе +командной строки — см. адаптеры Codex и Claude.