diff --git a/agents/.agents/skills/claude-subagent-playbook/SKILL.md b/agents/.agents/skills/claude-subagent-playbook/SKILL.md index c74f19d..5225eeb 100644 --- a/agents/.agents/skills/claude-subagent-playbook/SKILL.md +++ b/agents/.agents/skills/claude-subagent-playbook/SKILL.md @@ -20,35 +20,42 @@ description: >- **Не разворачивай конвейер на мелочь.** Косметика, пара часов работы, один файл — сделай сам: накладные расходы процесса многократно превысят цену -работы (эмпирика: на полировку ноутбука чуть не завели несколько issue — -пользователь остановил). Очередь зависимых issue с автономным прогоном — +работы. Очередь зависимых issue с автономным прогоном — это `/coordinator-loop`, не этот плейбук. ## Роли -- **Оркестратор (ты)** — план, постановка, синтез, коммит. Работай по - **индексу** (правило `/coordinator-loop`): в твой контекст входят вердикты - и находки `файл:строка`, а не diff, не полные логи и не нарратив. Шумные - команды — через файл-лог, в контекст только сводку. **Индекс — у тебя, - полезная нагрузка — файлами между агентами**: вердикты, отчёты и промпты - живут в `$SCRATCH` (обменный temp-каталог прогона с полуслучайным - префиксом — скретчпад сессии или `mktemp -d`; детали — в - [references/prompt-templates.md](references/prompt-templates.md)), ты - читаешь их один раз и дальше передаёшь путями и конкатенацией (`cat`), а - не переписываешь Write'ом — каждое переписывание дублирует контент в - твоём контексте (ретро 2026-07-10: находки ревью проходили через - оркестратора до шести раз). SendMessage возвращает эхом - весь текст сообщения — teammate'у шли короткое (вердикт, путь, вопрос), +- **Оркестратор (ты)** — план, постановка, синтез, коммит. Принцип: + **мастер решает — субагенты выясняют**; твой контекст — самый дорогой + ресурс, в него входят решения, вердикты и находки `файл:строка` — не + diff, не полные логи, не нарратив. Работу с неизвестным заранее объёмом + вывода (диагноз падения, исследование гипотезы, серия экспериментов, + чтение логов) отдавай субагенту **до её начала**: изнутри она всегда + выглядит «ещё на один шаг». Стоп-кран: **сам — максимум один заход** + (одна команда с коротким выводом по единственной гипотезе); не + подтвердилось — делегируй. Механику (правки файлов по готовым решениям, + скрипты, вёрстку) — `fast-worker`'у: твоё в них только короткий список + решений. **Индекс — у тебя, полезная нагрузка — файлами между + агентами**: вердикты, отчёты и промпты живут в `$SCRATCH` (обменный + temp-каталог прогона — скретчпад сессии или `mktemp -d`; детали — в + [references/prompt-templates.md](references/prompt-templates.md)) и + ведутся **на английском** — проект их не хранит, а кириллица в 1,5–2 + раза дороже по токенам; русский — только тому, что уходит в репозиторий + и пользователю. Читай их один раз, дальше передавай путями и + конкатенацией (`cat`), не переписывай Write'ом — каждое переписывание + дублирует контент в твоём контексте. SendMessage возвращает эхом весь + текст сообщения — teammate'у шли короткое (вердикт, путь, вопрос), длинное — файлом, который он прочтёт сам. - **Codex** — реализация кода. У пользователя лимиты Codex больше, код он пишет в целом лучше, но верхнеуровнево планирует хуже — поэтому декомпозиция и постановка остаются у тебя. Механика вызова — [references/codex-exec.md](references/codex-exec.md). - **Ревьюеры** — два, **разных родословных**, слепые друг к другу: - Claude-субагент (`adversarial-reviewer`; нет в среде — скептический - `general-purpose`) и Codex **свежим тредом**, не тем, что писал код. - Разные родословные ловят непересекающиеся классы находок (пересечение в - прогонах — стабильно ~ноль). Обоим — руки: тесты, гипотезы, поиск, + Claude-субагент (`adversarial-reviewer`; нет в среде — `deep-reasoner` + или скептический `general-purpose`) и Codex **свежим тредом**, не тем, + что писал код. + Разные родословные ловят разные классы находок (пересечение в прогонах — + от нуля до пары тем). Обоим — руки: тесты, гипотезы, поиск, документация, первоисточники; запрет менять исходники и окружение — **мандатом в промпте, не урезанием песочницы** (рецепт и подстраховка — [references/codex-exec.md](references/codex-exec.md)). @@ -71,8 +78,8 @@ description: >- контекста; всё нужное — в файле: цель, критерии приёмки чекбоксами, границы («что трогать нельзя»), «сначала прочитать» (спека, ADR, README с командами), команды проверки. Формат и место — по конвенции репозитория - (например, `.scratch//issues/`; репозиторий настроен под скиллы - Мэтта Покока — постановка через `/to-tickets` в сконфигурированный трекер: + (например, `.scratch//issues/`; если репозиторий настроен под + скиллы Мэтта Покока — постановка через `/to-tickets` в его трекер: тикеты-срезы с рёбрами блокировок вместо ad-hoc файла, конвенции — в `docs/agents/`, настройка — `/setup-matt-pocock-skills`). Не хватает фактуры по внешним библиотекам/API — сначала `/research` и Context7 MCP, @@ -83,17 +90,16 @@ description: >- не задав тебе ни одного вопроса. 2. **Свежий взгляд на постановку — до реализации.** Адверсарный ревьюер без твоего контекста проверяет задачу против кода: фактические ошибки, скрытые - решения-«однострочники», недостающие критерии. Окупается: ловит блокеры, - которые исполнитель молча реализовал бы (эмпирика: «русские названия из - `name_ru`» — а в данных `name_ru` английский). Постановка крупная или + решения-«однострочники», недостающие критерии. Окупается каждый прогон: + ловит блокеры, которые исполнитель молча реализовал бы. Постановка + крупная или цена ошибки высока — сделай ревью двойным и слепым, как для кода: вторая линия — Codex свежим тредом с явной рамкой «ревьюируй постановку, не реализацию; детали реализации — только если постановка молча предрешает решение» (без рамки зарывается в детали). Родословные и тут ловят разное: Codex — уровень требований (недостающие критерии, наблюдаемость, «формально отчитаться можно»), Клод — механику кода (нереализуемые - формулировки, мёртвые стабы; эмпирика 2026-07-10: пересечение — 2 темы - из ~15). Этап закрыт, когда каждая + формулировки, мёртвые стабы). Этап закрыт, когда каждая находка внесена в задачу **решением** или письменно отклонена — «пусть решит исполнитель» решением не считается. 3. **Реализация Кодексом.** Промпт: «задача самодостаточна, следуй буквально, @@ -103,7 +109,11 @@ description: >- [references/codex-exec.md](references/codex-exec.md). Один писатель в дереве: пока Codex пишет — никто больше (казус с форвардером — в [references/lessons.md](references/lessons.md)). Готово, - когда Codex вернул отчёт, а в дереве нет правок, которых он не называл. + когда Codex вернул отчёт, в дереве нет правок, которых он не называл, + и дешёвая сквозная проверка (если она есть в репо) зелёная: гонял её + исполнитель по промпту, а если ему она недоступна (docker, стенд) — ты, + **до запуска ревьюеров**: иначе ревью уйдёт на код, который сквозной + прогон ещё поменяет. 4. **Два слепых ревью параллельно.** Промпт — **один канонический файл в `$SCRATCH` на оба ревью** (скелет и обёртки вызова — [references/prompt-templates.md](references/prompt-templates.md)): Codex @@ -111,15 +121,13 @@ description: >- «прочитай файл X и выполни; индекс — в файл Y» (не дублируй текст промпта в параметре — это второй полный экземпляр в твоём контексте). Содержание: путь к задаче-файлу + фокус (математика/краевые случаи, - соответствие критериям, честность тестов, артефакты). Друг про друга не - знают, твои выводы им не пересказывай. Обоим поощряй безопасные - эмпирические проверки (воспроизвести краевой случай вне репо, сходить в - документацию) — вердикт заметно твёрже; менять исходники и окружение - нельзя. Вердикты — файлами с **разными путями**: у Codex это его - `-o`-отчёт, Клод-ревьюеру обёртка разрешает запись файла вердикта в - `$SCRATCH` (вне репо — мандату не противоречит), финальным актом — - SendMessage только со строкой VERDICT, счётчиками и путём: его - idle-уведомления не содержат результата, не жди из них ничего. После + соответствие критериям, честность тестов, артефакты); мандат и + поощрение эмпирических проверок уже в готовом boilerplate. Друг про + друга не знают, твои выводы им не пересказывай. Вердикты — файлами с + **разными путями**: у Codex это его `-o`-отчёт, Клод-ревьюеру путь и + финальный акт (SendMessage только со строкой VERDICT, счётчиками и + путём) задаёт готовая обёртка из шаблонов; его idle-уведомления + результата не содержат, не жди из них ничего. После ревью сверь дерево (`git status`). Клод-ревьюеру можно поручить смотреть артефакты (картинки из ноутбука). Этап закрыт, когда оба вердикта у тебя индексами и дерево нетронуто; вердикт без единой находки засчитывай @@ -131,9 +139,10 @@ description: >- кода): перешли Codex индекс находок **дословно**, он чинит или **аргументированно отклоняет** — через контракт и тест, не голословно; промпт починки — «закрой перечисленное, больше ничего не меняй». - «Дословно» — это конкатенация: `cat шапка.md вердикт-A.md вердикт-B.md > - fix-prompt.md` Bash'ем; Write'ом ты бы переписал те же находки в контекст - ещё раз. Свои замечания к триажу — только шапкой. Ты судишь уровнем + «Дословно» — это конкатенация: `cat triage-header.md вердикт-A.md + вердикт-B.md > fix-prompt.md` Bash'ем (шапка готова в + `references/prompts/`); Write'ом ты бы переписал те же находки в + контекст ещё раз. Свои замечания к триажу — только шапкой. Ты судишь уровнем задачи: принять риск / вне скоупа. Повторная проверка — узкая (см. «Свежесть»); её промпт не пересказывает резолюции — ссылается на файл отчёта исполнителя. Этап закрыт, когда по каждой находке обоих ревью есть @@ -153,9 +162,10 @@ description: >- (механика — [references/codex-exec.md](references/codex-exec.md)). Подстраховка от молчаливой смерти агента — ScheduleWakeup сроком дольше ожидаемой длительности: по пробуждению смотри логи сам, по приходу -результата таймер снимай. Idle-уведомления teammate-субагентов — шум, а не -событие: не докладывай о них пользователю и не действуй по ним, если -результат уже получен (ретро 2026-07-10: ~7 пустых ходов на idle-пингах). +результата таймер снимай; промпт будильника — одна короткая строка, +план не пересказывай (он живёт в разговоре). Idle-уведомления +teammate-субагентов — шум, а не событие: не докладывай о них пользователю +и не действуй по ним, если результат уже получен. ## Соседние скиллы @@ -176,9 +186,10 @@ description: >- - [references/codex-exec.md](references/codex-exec.md) — прямой `codex exec`: сквозные правила (шум в файлы, thread_id, resume по id, проверка отписки), ветки исполнитель/ревьюер/триаж, раннер для переваривания шума. -- [references/prompt-templates.md](references/prompt-templates.md) — скелеты - четырёх промптов конвейера (задача/ревью/триаж/перепроверка): пиши только - параметрический блок на задачу, boilerplate не переписывай. +- [references/prompt-templates.md](references/prompt-templates.md) — сборка + промптов: готовые boilerplate-файлы в `references/prompts/` подшиваются + `cat`'ом из каталога скилла, Write'ом пишутся только параметрические + блоки. - [references/lessons.md](references/lessons.md) — датированная эмпирика прогонов: что поймал каждый этап, казусы, цифры. - [references/claude-agents.md](references/claude-agents.md) — определения diff --git a/agents/.agents/skills/claude-subagent-playbook/references/claude-agents.md b/agents/.agents/skills/claude-subagent-playbook/references/claude-agents.md index 818bcee..f67f50a 100644 --- a/agents/.agents/skills/claude-subagent-playbook/references/claude-agents.md +++ b/agents/.agents/skills/claude-subagent-playbook/references/claude-agents.md @@ -4,8 +4,8 @@ (`.claude/agents/*.md`), не глобальные. В новом репозитории их нет — проверь `ls .claude/agents/` и при отсутствии создай файлы ниже как есть. У ревьюера `adversarial-reviewer` репо-локального определения намеренно -нет: рабочий фолбэк — `general-purpose` со скептическим промптом -(см. «Роли» в SKILL.md). +нет: рабочие фолбэки — `deep-reasoner` (обкатан ревью 2026-07-12) или +`general-purpose` со скептическим промптом (см. «Роли» в SKILL.md). ## Конструкция оркестрации (фрагмент CLAUDE.md репозитория) diff --git a/agents/.agents/skills/claude-subagent-playbook/references/codex-exec.md b/agents/.agents/skills/claude-subagent-playbook/references/codex-exec.md index 97b287c..033efe8 100644 --- a/agents/.agents/skills/claude-subagent-playbook/references/codex-exec.md +++ b/agents/.agents/skills/claude-subagent-playbook/references/codex-exec.md @@ -1,12 +1,14 @@ # Codex через прямой `codex exec`: рецепты и ловушки -Проверено 2026-07-09 (codex-cli 0.142.5, Windows + Git Bash); линукс-эмпирика -прогонов 07-06/07-07 шла через companion-обёртку и отражена в уроках ниже. +Проверено 2026-07-09 (codex-cli 0.142.5, Windows + Git Bash) и 2026-07-12 +(0.144.1, WSL2 Ubuntu: exec/resume/`-o`/фоновый Bash — весь конвейер); +линукс-эмпирика 07-06/07-07 шла через companion-обёртку и отражена в уроках +ниже. Прямой CLI надёжнее обёртки: её фоновая машина глючит (молчаливая подмена анализа Кодекса своим — issue #158, ломает слепое ревью; зависшие статусы), -и её `--write`-запуски режет классификатор авторежима. Далее `$SCRATCH` = -каталог скретчпада сессии из системного промпта (не `/tmp`: под Windows -`/tmp` Git Bash — ловушка). +и её `--write`-запуски режет классификатор авторежима. Далее `$D` = +подпапка задачи в обменном каталоге прогона (определение и конвенция — +[prompt-templates.md](prompt-templates.md)). ## Сквозные правила (любая ветка) @@ -22,17 +24,22 @@ - **Модель и глубину рассуждения задавай явно** (`-m`, `-c 'model_reasoning_effort="..."'`): дефолты берутся из `~/.codex/config.toml` и плавают за последней интерактивной сессией - пользователя. Для реализации и ревью — high; боевая модель — - **`gpt-5.5`** (решение пользователя 2026-07-10). Модель из конфига НЕ - наследовать: «сверить с конфигом» ≠ «взять из конфига» — туда утекают - фронтирные модели интерактивных сессий (gpt-5.6-sol — фронтир уровня - Fable, лимиты дорогие; казус — прогон тикета 02, 2026-07-10). Конфиг - разошёлся с правилом — спроси пользователя. Оверрайды проверены под - `--strict-config`. + пользователя — из конфига не наследовать, при расхождении с правилом — + спроси пользователя. Боевая модель — **`gpt-5.6-sol`** (решение + пользователя 2026-07-12), она хороша и для анализа/ревью, не только для + кода. Эффорт по сложности: `high` — реализация, ревью, диагноз; `medium` + — механика и **узкие починки по готовому диагнозу** (resume-триаж, где + рецепт уже расписан); `xhigh` — не дефолтить: расход удваивается, а + выигрыш мал — только по явному запросу пользователя. Оверрайды проверены + под `--strict-config`. - **Запуск — собственным фоновым Bash оркестратора** (`run_in_background`): фоновый процесс детачится, живёт сквозь ходы и будит оркестратора по выходу. Потолок 10 минут — только у фронтграундного Bash; фоновому таймаут - не нужен, `timeout NNN` вокруг codex не ставь. + не нужен, `timeout NNN` вокруг codex не ставь. **`&` внутрь команды не + добавляй** — фон даёт харнесс; с `&` уведомление придёт от обёртки при + живом codex (эмпирика 2026-07-12). Спасение осиротевшего процесса: + ожидатель `while kill -0 ; do sleep 10; done` под + `run_in_background` будит по его реальному выходу. - **thread_id — в первой строке stdout-JSONL** (`{"type":"thread.started",...}`). Забирай сразу после старта: это страховка — если процесс умер или его прибил хост, тред жив: `codex exec resume «дай финальный отчёт»`. @@ -55,11 +62,11 @@ а `pwd` в sandbox — нет. Обход без sudo `use_legacy_landlock=true` чинит только read-only (write-режим с ним паникует); полный фикс — AppArmor- профиль. Диагностика и рецепты — - [codex-sandbox-fix-handover-2026-07-10.md](codex-sandbox-fix-handover-2026-07-10.md). + [codex-sandbox-apparmor.md](codex-sandbox-apparmor.md). Фикс целиком под sudo — сам не применяй: дай пользователю готовые команды - из handover-файла (`!`-префикс в чат), после применения профиля напомни + из файла рецептов (`!`-префикс в чат), после применения профиля напомни убрать `use_legacy_landlock`. Перед первым прогоном конвейера на новой - Linux-машине прогони диагностику из handover-файла превентивно. + Linux-машине прогони диагностику из файла рецептов превентивно. - **Блок классификатора — решение пользователя.** Если запуск не прошёл permission-гейт, дай пользователю готовую команду с префиксом `!` в чат или попроси сменить режим разрешений. Сработавший путь — прямой exec; @@ -68,12 +75,12 @@ ## Ветка «исполнитель» (пишет код) ```bash -cat "$SCRATCH/task-prompt.md" | codex exec --json --strict-config \ - -s workspace-write -m gpt-5.5 \ +cat "$D/task-prompt.md" | codex exec --json --strict-config \ + -s workspace-write -m gpt-5.6-sol \ -c 'model_reasoning_effort="high"' \ -c 'approval_policy="on-request"' -c 'approvals_reviewer="auto_review"' \ - -o "$SCRATCH/task-result.md" - \ - > "$SCRATCH/task-stdout.jsonl" 2> "$SCRATCH/task-stderr.txt" + -o "$D/task-result.md" - \ + > "$D/task-stdout.jsonl" 2> "$D/task-stderr.txt" ``` - `--strict-config` — обязателен: опечатка в `-c`-ключе упадёт громко, а не @@ -92,27 +99,25 @@ cat "$SCRATCH/task-prompt.md" | codex exec --json --strict-config \ Тот же вызов, что у исполнителя — запись + авто-аппрув, — но **свежим тредом**, не тем, что писал код. Read-only-песочницей ревьюера не режь: она отнимает у него руки — тесты, проверку гипотез, поиск, документацию, -первоисточники. Защита — мандат в промпте: «исходники и окружение не менять, -правок не вносить — только находки»; Codex держит его надёжно (практика -пользователя, 2026-07-10). Дешёвая подстраховка: `git status --porcelain` -до ревью и сверка после — дерево должно остаться нетронутым. Кавеат: сеть -под workspace-write по умолчанию закрыта; что поиск/документация проходят -эскалацией через авто-аппрув — рабочая гипотеза, боем не обкатана -(см. handoff 2026-07-10). +первоисточники. Защита — мандат в промпте, готовым файлом +[prompts/review-boilerplate.md](prompts/review-boilerplate.md) (сборка — +[prompt-templates.md](prompt-templates.md)); Codex держит его надёжно +(практика пользователя, 2026-07-10). Дешёвая подстраховка: +`git status --porcelain` до ревью и сверка после — дерево должно остаться +нетронутым. Кавеат: сеть под workspace-write по умолчанию закрыта; что +поиск/документация проходят эскалацией через авто-аппрув — рабочая +гипотеза, боем не обкатана (см. +[../handoffs/20260710-codex-revyuer-write-i-sliyanie-handoffov.md](../handoffs/20260710-codex-revyuer-write-i-sliyanie-handoffov.md)). -В промпте — формат «только индекс находок» (SEVERITY, файл:строка, суть, -как проверить), явная строка VERDICT и поощрение безопасных эмпирических -проверок вне репо (воспроизвести краевой случай, свериться с -первоисточником) — вердикт заметно твёрже (эмпирика 2026-07-09). `-o`-файл вердикта — и есть обменный артефакт: на триаже он уходит в fix-промпт конкатенацией, читай его один раз для синтеза и не пересказывай. ## Ветка «триаж/починка» (тем же тредом, что писал код) ```bash -cat "$SCRATCH/fix-prompt.md" | codex exec resume --json \ - -o "$SCRATCH/fix-result.md" - \ - > "$SCRATCH/fix-stdout.jsonl" 2> "$SCRATCH/fix-stderr.txt" +cat "$D/fix-prompt.md" | codex exec resume --json \ + -o "$D/fix-result.md" - \ + > "$D/fix-stdout.jsonl" 2> "$D/fix-stderr.txt" ``` - `resume` не принимает `-s`/`-C` — песочница и CWD наследуются от исходного @@ -133,8 +138,9 @@ cat "$SCRATCH/fix-prompt.md" | codex exec resume --json \ ожиданием: команда запускается его собственным фоновым Bash, а ждёт он процессом-ожидателем (`until grep -q '<маркер>' лог; do sleep 30; done` под `run_in_background`) — харнесс переинвоцирует его по выходу процесса. -«Жду уведомления» без отслеживаемого процесса не будит никогда -(эмпирика 2026-07-07). +«Жду уведомления» без отслеживаемого процесса не будит никогда, а голый +поллер вне `run_in_background` умирает при смене хода (эмпирика +2026-07-07) — живучесть даёт именно фоновый запуск. Companion-плагин (`codex-companion.mjs` в кэше плагинов) — только для ручного интерактива (`status`, `result `); конвейер ходит прямым diff --git a/agents/.agents/skills/claude-subagent-playbook/references/codex-sandbox-fix-handover-2026-07-10.md b/agents/.agents/skills/claude-subagent-playbook/references/codex-sandbox-apparmor.md similarity index 87% rename from agents/.agents/skills/claude-subagent-playbook/references/codex-sandbox-fix-handover-2026-07-10.md rename to agents/.agents/skills/claude-subagent-playbook/references/codex-sandbox-apparmor.md index 2d99fb8..62f8ce5 100644 --- a/agents/.agents/skills/claude-subagent-playbook/references/codex-sandbox-fix-handover-2026-07-10.md +++ b/agents/.agents/skills/claude-subagent-playbook/references/codex-sandbox-apparmor.md @@ -1,6 +1,7 @@ -# Handover: починка sandbox Codex CLI на Ubuntu 24.04 (2026-07-10) +# Sandbox Codex на Linux: диагностика и починка (bwrap/AppArmor) -Для агента, дорабатывающего скилл работы с Codex. Самодостаточно: диагностика и фикс воспроизводимы без контекста исходной сессии. +Справочник: симптомы, корень и рецепты фикса поломки песочницы Codex CLI +на Linux с AppArmor (эмпирика Ubuntu 24.04, 2026-07-10). Самодостаточен. ## Симптом @@ -109,12 +110,6 @@ bwrap --ro-bind / / --unshare-net --dev /dev --proc /proc true && echo BWRAP_OK sudo dmesg | grep -iE 'apparmor.*(userns|bwrap)' | tail # AUDIT/DENIED — подтверждение ``` -## Что стоит внести в скилл - -1. Ловушка: с включённым `use_legacy_landlock` `--write`-задачи паникуют — либо профиль AppArmor и убрать флаг, либо жить в read-only. -2. web_search Codex работает даже при мёртвом shell-sandbox — «гуглит, но не может выполнить `ls`» — характерная сигнатура именно этой поломки. -3. Поломка прилетает молча с обновлением npm-пакета codex — при странных отказах первым делом `codex --version` и дата установки. - ## Связанные записи Принесено 2026-07-10 из ветки `codex-sandbox-fix-20260710` (исходная машина — diff --git a/agents/.agents/skills/claude-subagent-playbook/references/lessons.md b/agents/.agents/skills/claude-subagent-playbook/references/lessons.md index 0aed21c..d6482b7 100644 --- a/agents/.agents/skills/claude-subagent-playbook/references/lessons.md +++ b/agents/.agents/skills/claude-subagent-playbook/references/lessons.md @@ -6,228 +6,108 @@ поглощён SKILL.md или references, сжимай его запись здесь до строки-факта (дата, что случилось, куда поглощено) — иначе файл растёт бесконечно. -## 2026-07-06 — t2-ml-forecast, задача 05 «полировка витрины под демо» +## 2026-07-06 — t2-ml-forecast, задача 05 (первый прогон; дистиллировано 2026-07-12) -Первый прогон конвейера. Задача: ~200 строк правок в ядре отчёта + ноутбук. +- Свежий взгляд на постановку окупился: блокер name_ru (в данных — английский), + две «одностроки» с проектными решениями, дыра регенерации `.ipynb`. + Поглощено: SKILL.md этап 2. +- Казус форвардера: субагент, получив постановку вместо команды, реализовал + задачу сам (+1227 строк). Поглощено: SKILL.md этап 3, codex-exec (раннер). +- Слепое двойное ревью: пересечение находок — ноль; Клод подтвердил математику + и артефакты, Codex нашёл две дыры в тестах. Поглощено: SKILL.md (роли). +- Смерть фонового ревьюера без доставленного отчёта; транскрипт не спас. + Поглощено: SKILL.md этап 4 (вердикт — файлом, сообщение — указателем). +- Цифры: ревью постановки ~60k токенов; конвейер ~3 часа, реализация ~20 мин. -**Свежий взгляд на постановку (Клод, adversarial-reviewer) — окупился:** -- блокер: постановка требовала «русские названия из `report.name_ru`», а в - данных `name_ru` — английские имена из Excel-книги; исполнитель молча - сделал бы английские заголовки. Решение внесено в задачу: словарь - «статья → русское имя» как явная поставка; -- две «одностроки», прятавшие проектные решения: поворот отрицательного ряда - (правило, пересчёт коридора, единый хелпер) и согласованность - «график по модулю vs таблица со знаком»; -- процессная дыра: без явных двух шагов регенерации `.ipynb` остался бы без - выводов, и тест ноутбука его бы завернул. +## 2026-07-07 — наглядность витрины (полный конвейер; дистиллировано 2026-07-12) -**Казус форвардера:** субагент `codex:codex-rescue`, получив постановку -вместо команды, реализовал задачу сам (+1227 строк). Настоящий Codex стартовал -на уже изменённом дереве — столкновения избежали везением (форвардер успел -закончить). Урок в SKILL.md и codex-exec.md (раздел про раннера). +- Idle-уведомление ≠ отчёт; голый поллер вне run_in_background умирает при + смене хода; статус job — не истина (зомби «running» после смерти воркера: + истина — mtime артефакта + лог + pgrep). Поглощено: SKILL.md + («Пользователь в петле»), codex-exec (фоновый запуск, раннер). +- Безадресный resume подхватывает чужой тред. Поглощено: codex-exec. +- Доводы отклонений — в файл задачи (свежий тред продолжает без контекста + предшественника). Поглощено: prompts/triage-header.md. +- Не поглощено (держать в уме при постановке): правила задачи ранжировать + явно («правило A главнее буквы E») — внутренние противоречия всплывают + после починки. +- Цифры: реализация 18 мин; триаж ~8 мин; тесты 147 -> 154. -**Слепое двойное ревью — родословные поймали разное:** -- Клод (Опус): APPROVE; подтвердил математику поворота/коридора - (алгебраическое тождество), краевые случаи (ряд через ноль, нули), - неизменность метрик и таблиц; посмотрел картинки из `.ipynb`; один nit. -- Codex (свежий тред): needs-attention; две дыры в тестах — раздел ноутбука - не закреплён в required_snippets, нет регрессионного теста «таблица - отрицательного ряда остаётся со знаком». Оба — про то, что зелёный прогон - не докажет готовность; Клод этих дыр не нашёл. -- Пересечения находок — ноль. Слепота и разность родословных работают. +## 2026-07-09 — local-transcriber, SendTo (первый под Windows; дистиллировано 2026-07-12) -**Точечная починка:** Codex `--fresh` с промптом «добавь только два теста, -продуктовый код не трогай» — чисто, 148 → 150 passed. +- Git Bash-стек работает целиком; классификатор режет companion `--write`, + прямой `codex exec` проходит. Поглощено: codex-exec. +- Свежий взгляд: 2 major (OEM-кодировка `.cmd` на кириллическом профиле, + протухание пути venv) + load-bearing порядок проверок. Поглощено: этап 2. +- Отписка: вердикт одной строкой, проверка по JSONL подтвердила работу. + Поглощено: SKILL.md этап 4, codex-exec. +- Эмпирический ревьюер (воспроизведение краевых случаев вне репо) — вердикт + твёрже. Поглощено: SKILL.md этап 4, boilerplate шаблонов. +- Цифры: ревью постановки ~57k, кода ~48k, перепроверка ~45k токенов. -**Цифры для калибровки:** ревью Клода на Фабуле (этап постановки) — ~60k -токенов; конвейер целиком — ~3 часа настенного времени, из них реализация -~20 минут; остальное — ревью и оркестрация. На мелочь такое не разворачивать. +## 2026-07-10 — четыре записи (дистиллировано 2026-07-12) -**Смерть ревьюера (тот же день, ревью самого скилла по /claude-team-review):** -Опус-ревьюер дважды ушёл в idle без доставленного отчёта (одно напоминание -по idle-гарду — снова тишина), пользователь подтвердил: субагент исчез из -интерфейса. Спасти отчёт из транскрипта не удалось — jsonl тиммейтов не -нашлись в каталоге проекта. Урок: отчёт фонового ревьюера — скоропортящийся; -если он критичен, проси ревьюера сначала писать результат в файл -(двухканальный протокол раннера из /adversarial-review), а сообщение слать -как указатель. Ревью скилла не состоялось — отложено до боевого прогона. +- Ревьюер Codex без read-only: мандат промптом надёжен, песочница не режется. + Поглощено: codex-exec (ветка ревьюера). +- Sandbox-инцидент CLI 0.144.1 (bwrap+userns vs AppArmor) и ловушка memfd + (профиль на путь bwrap не цепляется — вешать на бинарь codex). Поглощено: + codex-exec + codex-sandbox-apparmor.md. +- Постановка через `/to-tickets` ложится в конвейер без трения; двойное + слепое ревью постановки окупилось (Клод — механика кода, Codex — уровень + требований; пересечение 2 из ~15). Поглощено: SKILL.md этапы 1–2. +- Ретро расхода контекста (3 цикла): находки проходили через оркестратора + до шести раз; review-промпт дублировался; ~7 пустых ходов на idle-пингах. + Поглощено: SKILL.md (роль оркестратора: индекс, cat, файлы), шаблоны. -## Прогон 2026-07-07: наглядность витрины (боевой, полный конвейер) +## Прогон 2026-07-12: clickstream-demo, задача 20 — флаки runtime-гейта -Задача: витрина понятна финансисту без голоса (5 блоков, 5 файлов). Конвейер -отработал целиком: исследование двумя головами → постановка → свежий взгляд -(1 блокер + 9 находок, в т.ч. повторно поймана ловушка name_ru) → Codex 18 мин -→ два слепых ревью → триаж у исполнителя → две точечные правки → приёмка. -Пересечение находок ревьюеров — снова ~ноль (Клод смотрел артефакты глазами и -принял; Codex дал 4 «поправить» по букве задачи). Их прямое противоречие -(ослаблен ли тест) рассудил исполнитель по контракту — механизм работает. +Полный конвейер + три захода стендовой приёмки. Главный урок прогона: +**ревью по чтению кода не заменяет сквозный прогон** — два класса дефектов +вскрылись только на стенде. -**Ожидание фоновых job:** -- Idle-уведомление субагента ≠ отчёт: почти каждый субагент уходил в idle ДО - доставки отчёта. Лечится немедленным явным «пришли отчёт на main». -- Фоновый bash-поллер (`until…sleep`) у раннера умирает при смене хода. - Надёжно: persistent Monitor без таймаута. -- Статус job — не истина: воркер финальной правки умер после успешных проверок, - статус завис «running» навсегда (зомби). Диагностика оркестратором: mtime - артефакта (showcase-check.ipynb дописан) + лог job (все проверки зелёные) + - pgrep (воркера нет) → забрать финал себе, раннера распустить. +**Что поймал каждый этап:** +- Ревью постановки (Opus): настоящий корень — отсутствие SIGTERM-хендлера + (python PID 1, SIGKILL после grace); один из двух вариантов фикса в + постановке гонку не закрывал. Плюс критерий «красный сценарий всё ещё + ловится» и запрет вероятностных смягчений. +- Слепые ревью: Codex — grace-период 10с и обходимость precheck (пара из + старой backfill-строки); Клод — подтвердил структурный довод, на узкой + перепроверке принёс НОВУЮ находку (тест биндил порт 9109 — флаки 1/13). + Пересечение — 2 темы из ~8 (grace, слабый контракт-тест): не «стабильно + ноль», но малое; обе родословные оправдались. +- Стендовая приёмка (3 захода): (1) гейт годами жил на побочном эффекте + бага — пересекающие визиты давала «нелегальная переработка» генератора + после игнорируемого SIGTERM; честный фикс оставил проверку без сырья; + (2) таймзона: наивные метки STG (UTC) против границы с `+00:00` на + сервере Europe/Moscow — precheck был зелёным вакуумно; та же ошибка — в + приёмочном скрипте координатора (наивная конвенция DDS). Урок: сравнение + времени в SQL — только с явным поясом с обеих сторон. -**Codex companion:** -- Безадресный `--resume`/resumeLast резолвится в «последний тред сессии» — при - параллельных тредах подхватывает чужой read-only ревью-тред. С ЯВНЫМ id тред - подхватывается свой (сэндбокс привязан к треду: у write-треда останется write) — - это же проходили в /adversarial-review. Правило: resume — только по id; если id - не сохранился, свежий write-тред дочитает контекст из файла задачи (решения - вписаны туда). +**Ретро контекста оркестратора** (главный пожиратель — внеплановые циклы): +диагнозы падений приёмки велись мастером инлайн (~15 вызовов); boilerplate +промптов переписывался трижды; обменные файлы шли кириллицей (×1,5–2); +правки задачи-файла — тремя крупными Edit (old+new = двойной текст); +промпты будильников пересказывали план. Поглощено 2026-07-12: SKILL.md +(принцип «мастер решает — субагенты выясняют», стоп-кран «сам — максимум +один заход», механика — fast-worker'у, обменные файлы на английском, +будильник одной строкой, сквозная проверка до ревью, фолбэк ревьюера +deep-reasoner — обкатан этим прогоном), prompt-templates + prompts/ +(готовые boilerplate-файлы, английские скелеты), codex-exec (модель +gpt-5.6-sol, medium для узких починок, ловушка `&`). Слепое Fable-ревью +самого скилла (по глоссарию writing-great-skills): восстановление после +rm -rf подтверждено без потерь, 9 MINOR + 5 NIT согласованности — все +закрыты тем же днём. -**Постановка:** -- Правила задачи стоит ранжировать явно («правило A главнее буквы E»): - внутреннее противоречие (де-жаргон vs «заголовки не трогать») всплыло только - после починки по ревью и потребовало отдельной правки решением оркестратора. -- Требовать от исполнителя вписывать доводы отклонений в файл задачи — окупилось: - свежий write-тред продолжил работу без контекста предшественника. +**Прочее:** казус двойного фона (`&` при run_in_background) — спасён +ожидателем `kill -0`; принятие остаточного риска (публикация не ограничена +по времени) зафиксировано доводом в задаче — паттерн «риск принят + после +фикса такой отказ падает громко и честно» работает как аргумент приёмки. +Отдельный казус координатора: `rm -rf` «зеркала» скилла прошёл сквозь +симлинк `~/.claude/skills -> dotfiles` и снёс оригинал; восстановлено из +git (`git show HEAD:path`) + повторным наложением правок из контекста. +Урок: перед rm — `ls -la` цели и родителя, симлинк-родитель = чужая +территория. -**Цифры:** реализация 18 мин; триаж-починка ~8 мин; финальная правка ~3 мин -работы + ~20 мин зомби-ожидания. Тесты 147 → 154. Панель конвенций дала демо -аргумент: 10 из 13 против 6 из 13 в зависимости от прочтения порога. - -## Прогон 2026-07-09: local-transcriber, SendTo-меню (первый по тексту скилла; первый под Windows) - -Задача: контекстное меню проводника через SendTo + флаги -`--install-menu`/`--uninstall-menu`; 5 файлов, +345 строк, тесты в финале -191 passed / 1 skipped. Конвейер целиком, вместе с фичей — один вечер. - -**Первый прогон под Windows:** Git Bash-стек работает целиком — `codex exec`, -`jq`, редиректы, heredoc, фоновый Bash с побудкой, SendMessage-rerun. -Скретчпад сессии вместо `/tmp`. - -**Классификатор авторежима — новый класс препятствия:** companion с -`--write` заблокирован и через раннера-субагента, и напрямую из Bash -(«Create Unsafe Agents»); повторная попытка с другим флагом расценена как -обход. Прямой `codex exec` фоновым Bash оркестратора прошёл гейт и отработал -все три ветки (write-исполнитель, read-only ревьюер, resume-триаж). Правила — -в codex-exec.md; companion-обёртка поглощена им же. - -**Свежий взгляд на постановку — снова окупился:** 2 major, которые -исполнитель молча реализовал бы: `.cmd` с путём, писанный «как ASCII», ломался -бы на кириллическом профиле (cmd.exe читает батники в OEM-кодировке) — при -том что фича делалась именно «для коллег»; плюс протухание зашитого пути к -venv. Третья находка — load-bearing порядок проверок (exit 2 требует -валидации до `expand_globs`, иначе чужой except даст exit 1). Одна находка -отклонена письменно (проброс `%errorlevel%` — нет потребителя). - -**Слепое двойное ревью:** Codex — APPROVED, 0 находок; Опус — APPROVED, -3 minor (0-байтный leftover при `UnicodeEncodeError` — воспроизвёл на -машине; OEM-запись ни разу не исполняется в тестах; LF vs CRLF). Пересечение -снова ~ноль, но с нюансом: Codex в промежуточных сообщениях *колебался* -ровно над местом находки №2 Опуса и не оформил её — колебания в логе стоят -чтения при синтезе. - -**Отписка:** вердикт Codex пришёл одной строкой без находок. Проверка по -JSONL (19 command_execution: полный pytest, узкий прогон, usage) подтвердила -работу. Приём «вердикт без находок — проверь лог» вписан в SKILL.md -(этап 4) и codex-exec.md. - -**Закрыты давние пункты «не проверено боем» (записка 2026-07-06, ныне -поглощена):** фолбэк-ревьюер -general-purpose на Опусе — обкатан дважды (постановка и код), работает; -триаж исполнителем — `codex exec resume` по явному id закрыл 3/3 находки, -лишнего не тронул; узкий rerun ревьюера — SendMessage поднял того же -Опус-агента из транскрипта, RECHECK OK за ~38 сек. - -**Эмпирический ревьюер:** Опус сам воспроизводил краевые случаи вне репо -(UnicodeEncodeError с обрезкой файла, LF-`.cmd` через `cmd /c`) — вердикт -заметно твёрже. Приём поощрять в промпте ревьюера («безопасные -эмпирические проверки вне репо разрешены»). - -**Цифры:** ревью постановки ~57k токенов, ревью кода ~48k, перепроверка -~45k (тот же агент из транскрипта); триаж-раунд Codex — одна resume-команда. - -## 2026-07-10 — правка по практике пользователя: Codex-ревьюер без read-only - -Ветка «ревьюер» в codex-exec.md была записана как `-s read-only` — по -осторожности, не по эмпирике. Пользователь поправил: read-only-конфайн -обедняет ревью — с записью и авто-аппрувом ревьюер гоняет тесты, проверяет -гипотезы, гуглит, читает документацию и первоисточники. Инструкцию -«исходники/окружение не менять» Codex держит надёжно (многократная практика -пользователя). Итог: обе ветки (исполнитель и ревьюер) ходят одним вызовом, -различие — мандат промптом; подстраховка — сверка `git status --porcelain` -до/после ревью. Непроверенное — в handoff 2026-07-10 (сеть под -workspace-write-песочницей для поиска). - -## 2026-07-10 — Linux: sandbox-инцидент Codex CLI 0.144.1 (другая сессия, Ubuntu 24.04) - -Обновление npm-пакета codex молча сломало песочницу: backend сменился на -bwrap+userns, AppArmor Ubuntu 24.04 блокирует его до запуска команд. -Характерная сигнатура: «гуглит, но не может выполнить `ls`» (web_search -исполняется вне sandbox). Обход без sudo — `use_legacy_landlock=true` -(только read-only, write паникует); полный фикс — AppArmor-профиль -`codex-bwrap` (на той машине не применён, write ждёт sudo). При странных -отказах Codex первым делом — `codex --version` и дата обновления. -Подробности — references/codex-sandbox-fix-handover-2026-07-10.md -(принесено из ветки `codex-sandbox-fix-20260710`). - -## Прогон 2026-07-10: mws-data-test-t2-presale, постановка FTP/CSV DQ (этапы 1–2 без реализации) - -Постановка велась не файлом-задачей, а `/to-tickets` (репозиторий настроен -`/setup-matt-pocock-skills`): 5 тикетов-срезов с рёбрами блокировок; связка -с конвейером легла без трения — тикет и есть файл-задача этапа 1. Урок -поглощён SKILL.md (этап 1). - -**Двойное слепое ревью постановки — впервые, окупилось:** Клод (Опус, -9 находок) поймал механику кода — нереализуемый контракт «таблица под именем -из `table`» (поле недоступно коннектору в момент создания соединения), -мёртвый стаб-ловушку `dataframe`, `load_config` = API-эндпоинт, а не CLI. -Codex (8 находок) поймал уровень требований: параметр из спеки, пропавший в -тикетах; критерий, который можно закрыть формально; поведение при -неподдерживаемом FTP `SIZE`; ненаблюдаемость «понятных ошибок» за общим -`SourceQueryException`. Пересечение — 2 темы из ~15 (Django-противоречие в -тестах, несамодостаточность smoke). Рамка мандата Codex обязательна: -«ревьюируй постановку, не реализацию» — наблюдение пользователя: без неё -зарывается в детали. Урок поглощён SKILL.md (этап 2). - -**Ретро-оговорка:** Codex-ревью этого прогона шло ещё через companion-канал -(обновление скилла с прямым exec приехало позже) — с учётом issue #158 -чистота родословной второй линии не гарантирована; находки от этого не -обесценились, но эмпирику «2 из 15» читать с этой поправкой. - -**Наблюдение пользователя (в память проекта тоже записано):** Codex хорошо -ревьюит планы/постановки, не только код — при явной рамке уровня. - -## Прогон 2026-07-10 (позже): AppArmor-фикс — ловушка memfd - -Рецепт «профиль на путь vendored bwrap» из handover-файла оказался -недостаточным: Codex ≥0.144 исполняет встроенный bwrap **из memfd** -(`bundled_bwrap.rs`, `memfd_create` в бинаре) — путевой attachment не -цепляется никогда. Коварство: прямой запуск vendored bwrap с диска под -профилем проходит (BWRAP_OK) — ложное подтверждение фикса; истина — в audit: -`profile="unconfined" comm="bwrap"` → transition. Рабочий фикс — профиль на -**сам бинарь codex**: метка наследуется через memfd-exec, `userns,` -срабатывает у ребёнка (стандартный приём Ubuntu для браузеров). Применён и -проверен: оба режима работают, изоляция цела. Обновлённый рецепт — в -handover-файле. - -## Ретро 2026-07-10: расход контекста оркестратора за 3 цикла (тикеты 01–03) - -Конвейер отработал (3 цикла: реализация → двойное слепое ревью → триаж → -узкие перепроверки → коммит; пересечение находок ревьюеров — ноль во всех -трёх, подтверждая ценность двух родословных). Главные пожиратели контекста -оркестратора, по убыванию: - -1. **Находки ревью проходили через оркестратора до шести раз**: вердикт → - Write fix-промпта с находками «дословно» → пересказ резолюций в двух - recheck-промптах → SendMessage-эхо (tool result возвращает весь текст - сообщения). Лечение — «индекс у оркестратора, нагрузка файлами»: - вердикты в файлы, fix-промпт cat'ом, recheck ссылкой на файл отчёта. - Внесено в SKILL.md (роль оркестратора, этапы 4–5) и codex-exec.md. -2. **Review-промпт уходил полным текстом дважды** (файл для Codex + - параметр prompt Клод-субагента, ~80 строк × 2 × 3 тикета). Лечение — - один канонический файл, оба читают сами; скелеты — prompt-templates.md. -3. **Idle-пинги teammate-ревьюера**: ~7 пустых ходов; вердикт не приходит - сам — нужен запрос. Лечение — мандат «финальный акт — SendMessage с - коротким вердиктом», idle-пинги игнорировать. -4. Сага починки санбокса — разовая, задокументирована отдельно. - -Обменный каталог прогона — временный, с полуслучайным префиксом (скретчпад -сессии или mktemp -d): не мусорит в репо и не переживает ребут (решение -пользователя). +**Цифры:** реализация ~25 мин; ревью постановки 75k токенов субагента, +ревью кода 65k, перепроверка 80k (с новой находкой); приёмка — 4 прогона +гейта по ~1,5 мин + красный сценарий; тесты 190 -> 192 + 21. diff --git a/agents/.agents/skills/claude-subagent-playbook/references/prompt-templates.md b/agents/.agents/skills/claude-subagent-playbook/references/prompt-templates.md index 25c61d6..37eab72 100644 --- a/agents/.agents/skills/claude-subagent-playbook/references/prompt-templates.md +++ b/agents/.agents/skills/claude-subagent-playbook/references/prompt-templates.md @@ -1,136 +1,143 @@ -# Скелеты промптов конвейера +# Сборка промптов конвейера -Отработали боевой прогон 2026-07-10 (3 цикла, тикеты FTP/CSV DQ). Правило -использования: заполни скелет в `$SCRATCH` **один раз за прогон** и дальше -не переписывай — на каждую следующую задачу пиши только параметрический -блок и собирай финальный промпт конкатенацией. Плейсхолдеры `{{...}}` -заполняются значениями задачи; секции, помеченные «адаптируй», меняются -по смыслу задачи, остальное — стабильный boilerplate. +Постоянные блоки лежат готовыми файлами в +[prompts/](prompts/) — их не переписывают, а подшивают `cat`'ом прямо из +каталога скилла, через контекст оркестратора они не проходят вовсе: -`$SCRATCH` здесь — общий обменный каталог прогона во **временном каталоге -ОС с полуслучайным префиксом**: скретчпад сессии из системного промпта -(он уже такой) или `mktemp -d` на прогон. Это безопасный вариант -(решение пользователя 2026-07-10): не мусорит в репо, не сталкивается с -параллельными прогонами и не переживает ребут машины — устаревшие обменные -файлы не накапливаются. Windows-кавеат из codex-exec.md в силе: путь — -forward-slash, не голый `/tmp` Git Bash. +- [prompts/review-boilerplate.md](prompts/review-boilerplate.md) — мандат + ревьюера + формат индекса находок (этапы 2 и 4). +- [prompts/triage-header.md](prompts/triage-header.md) — правила триажа + для исполнителя (этап 5). +- [prompts/recheck-header.md](prompts/recheck-header.md) — узкая + перепроверка (этап 5); может принести новую находку — это не нарушение + узости, отправь её исполнителю тем же порядком. + +Правила: + +- **Обменные файлы — на английском** (правило SKILL.md): скелеты ниже уже + английские. Русский — только формулировкам, попадающим в задачу-файл, + коммиты и доклады пользователю. +- **Каталог прогона** — `$SCRATCH//` на задачу: `$SCRATCH` — + временный каталог ОС (скретчпад сессии или `mktemp -d`), подпапка — чтобы + обмен нескольких задач не сваливался в кучу. В репо не мусорит, ребут не + переживает. Windows-кавеат из codex-exec.md в силе: путь — + forward-slash, не голый `/tmp` Git Bash. +- Через Write оркестратор пишет **только параметрические блоки** ниже; + плейсхолдеры `{{...}}` — значения задачи, секции «adapt» — по смыслу. + +Сборка на прогон: `D="$SCRATCH/"` — подпапка задачи; `P` — +`references/prompts` в базовом каталоге скилла (путь даётся в шапке +вызова скилла): + +```bash +cat "$D/review-params.md" "$P/review-boilerplate.md" > "$D/review-prompt.md" +cat "$P/triage-header.md" "$D/review-codex.md" "$D/review-claude.md" \ + "$D/notes.md" > "$D/fix-prompt.md" # notes.md опционален — нет, так не включай +cat "$P/recheck-header.md" "$D/recheck-params.md" > "$D/recheck-prompt.md" +``` ## 1. Задача исполнителю (`codex exec`, workspace-write) -```markdown -# Задача: {{тикет/цель одной строкой}} - -Рабочий каталог — корень репозитория {{repo}}. Ветка {{branch}} — работай -в ней, ветку не менять. - -## Что делать -Реализуй {{тикет NN}} из {{путь к задаче-файлу}}. Задача самодостаточна: -постановка — в тикете, следуй ей буквально; чекбоксы — критерии приёмки. -Кажется неправильным — реализуй как написано и отметь сомнение в отчёте. - -## Сначала прочитать (обязательно, до кода) -{{нумерованный список: задача-файл, спека, образцы кода, конвенции}} - -## Порядок и дисциплина -{{адаптируй: TDD, порядок слоёв, команда тестов}} - -## Границы (что трогать нельзя) -- **Коммитов не делать.** Никаких `git commit`/`git add`. -{{адаптируй: стабы, чужой код, существующие тесты, файлы вне репо}} - -## Финальный отчёт (что вернуть) -1. Файлы с одной строкой «зачем» на каждый. -2. Команда тестов и итог прогона (счётчик, все зелёные). -3. Чекбоксы: какие закрыты, какие нет и почему. -4. Сомнения, если были. -``` - -## 2. Слепое ревью (один файл на ОБОИХ ревьюеров) - -Канонический файл не знает, кто его читает — куда класть вердикт, задаёт -обёртка вызова, и пути у ревьюеров разные (иначе коллизия): - -- **Codex**: файл через stdin; отдельный файл вердикта не нужен — вердикт - и есть его `-o`-отчёт (`$SCRATCH/NN-review-codex.md`). -- **Клод-субагент**: в prompt — только обёртка: «прочитай {{путь к - каноническому файлу}} и выполни, рабочий каталог {{корень репо}}; - полный индекс запиши в {{$SCRATCH/NN-review-claude.md}} — это вне репо, - мандату не противоречит (Write у тебя нет — Bash heredoc'ом); финальным - сообщением пришли только строку VERDICT, счётчики по severity и путь - к файлу». +Сохрани как `$D/task-prompt.md` — под этим именем его ждут примеры +codex-exec.md. ```markdown -# Ревью кода: {{тикет NN — суть}} +# Task: {{ticket/goal in one line}} -Ты — независимый адверсарный ревьюер. Рабочий каталог — корень -репозитория {{repo}}, ветка {{branch}}. +Working directory: repo root {{repo}}. Branch {{branch}} — stay on it. -## Мандат (жёсткий) -- Исходники и окружение НЕ менять. Правок не вносить — только находки. -- Запускать тесты, проверять гипотезы, читать документацию — можно и - нужно; безопасные эмпирические проверки во временных каталогах вне - репо поощряются: вердикт с проверкой твёрже вердикта по прочтению. -- Никаких `git add`/`git commit`/`git checkout`. -- Итог — только индекс находок и строка VERDICT, без пересказа кода и - нарратива; куда его положить — сказано в вызове. +## What to do +Implement {{ticket NN}} from {{path to task file}}. The task is +self-contained: follow it literally; checkboxes are the acceptance +criteria. If something seems wrong — implement as written and flag the +doubt in your report. -## Что ревьюишь -{{задача-файл + спека; что уже закоммичено и не ревьюится}} -Изменения (незакоммичены, смотри рабочее дерево): {{список файлов}} -Команда тестов (ожидается {{N}} passed): {{команда}} +## Read first (mandatory, before any code) +{{numbered list: task file, spec, code samples, conventions}} -## Фокус -{{адаптируй: 3–4 пункта под задачу — математика/краевые, соответствие -критериям, честность тестов, общий код/регрессии}} +## Order and discipline +{{adapt: TDD, layer order, test command}} -## Формат файла находок — только индекс -SEVERITY(BLOCKER|MAJOR|MINOR|NIT) | файл:строка | суть одной фразой | как проверить/воспроизвести -В конце — отдельная строка: VERDICT: APPROVED | APPROVED_WITH_MINORS | CHANGES_REQUIRED +## End-to-end check <-- опционально: только если в репо есть дешёвый сквозной прогон +Run {{command}} before finishing. If it is unavailable in your sandbox +(docker, live stand) — say so explicitly in the report: the orchestrator +will run it before the reviews start. + +## Boundaries (do not touch) +- **No commits.** No `git commit` / `git add`. +{{adapt: stubs, foreign code, existing tests, files outside the repo}} + +## Final report (return this) +1. Files changed, one-line "why" each. +2. Test command and result (counters, all green). +3. Checkboxes: which are closed, which are not and why. +4. Doubts, if any. ``` -## 3. Триаж исполнителю (`codex exec resume `) +## 2. Ревью: параметрический блок (один на ОБОИХ ревьюеров) -Собирается конкатенацией — находки НЕ переписывать: -`cat шапка.md review-A.md review-B.md замечания.md > fix-prompt.md` +Блок не знает, кто его читает; куда класть вердикт, задаёт обёртка вызова, +и пути у ревьюеров разные (иначе коллизия). Codex получает собранный файл +через stdin (вердикт = его `-o`-отчёт); Клод-субагенту в prompt — короткая +английская обёртка: -Шапка (стабильная): +```text +Read {{path to review-prompt.md}} and execute it. Working directory: +{{repo root}}. Write the full findings index to +{{$D/review-claude.md}} — it is outside the repo, so the mandate allows +it (via Write or a Bash heredoc, whichever you have). Final message: +ONLY the VERDICT line, severity counters and the file path. +``` ```markdown -# Триаж находок двух независимых ревью твоей реализации +# Code review: {{ticket NN — essence}} -Ниже — находки двух слепых ревью **дословно**. Закрой перечисленное, -больше ничего не меняй. По каждой — починка по TDD (сначала тест, -воспроизводящий находку) или аргументированное отклонение через -контракт/спеку и тест — голословное «не важно» не принимается. -Коммитов не делать. +You are an independent adversarial reviewer. Working directory: repo root +{{repo}}, branch {{branch}}. -Финальный отчёт: по каждой находке одной строкой — починено (чем) / -отклонено (довод + где зафиксировано); команда тестов, счётчик прогона, -список изменённых файлов. +## What you review +{{task file + spec; what is already committed and NOT under review}} +Changes (uncommitted, see the working tree): {{file list}} +Test command (expect {{N}} passed): {{command}} + +## Focus +{{adapt: 3–4 points — math/edge cases, criteria compliance, test honesty, +shared code/regressions, artifacts}} ``` -Замечания оркестратора (опционально, коротко): фактура, которой нет у -исполнителя (проверенные тобой данные), решения уровня задачи -(вне скоупа / принять риск), приоритеты. - -## 4. Узкая перепроверка (тем же ревьюером) +Вариант для **этапа 2** (ревью постановки, кода изменений ещё нет) — тот же +boilerplate, другой параметрический блок: ```markdown -# Узкая повторная проверка: закрывают ли правки твои находки +# Spec review: {{ticket NN — essence}} -Исполнитель обработал находки. Проверь ТОЛЬКО свои — полный повторный -обход не нужен. Мандат прежний: ничего не менять, только чтение и прогон -тестов. +You review a TASK STATEMENT, not an implementation. Go into implementation +details only where the statement silently pre-decides a solution. The task +goes to an implementer with no session context — they will do literally +what is written. Working directory: repo root {{repo}}, branch {{branch}}. -Отчёт исполнителя с резолюциями: прочитай {{$SCRATCH/NN-fix-result.md}}. -Команда тестов (ожидается {{N}} passed): {{команда}} +## What you review +Statement: {{path to task file}}. Related context (not under review): +{{parent PRD, sibling tickets}}. +Code to check the statement's facts against: {{file list with why}} -Ответ — по каждой твоей находке одной строкой: CLOSED / NOT_CLOSED -(почему) / REJECTION_VALID / REJECTION_INVALID (почему). Финальная -строка: RECHECK: ALL_CLOSED | ISSUES_REMAIN +## Focus +{{adapt: facts vs code, hidden one-liner decisions/forks, acceptance +criteria checkable and gameable?, observability}} ``` -Кавеат: проверь, что Codex-ревьюер может читать `$SCRATCH` из своей -песочницы (temp-каталоги обычно читаемы в workspace-write; в этом прогоне -`-o`-файлы под `/tmp` работали). Если нет — резолюции по его находкам -передай текстом (только его находки, не весь отчёт). +## 3. Параметрические хвосты триажа и перепроверки + +`notes.md` (опционально, коротко, по-английски): фактура, которой нет у +исполнителя, решения уровня задачи (вне скоупа / принять риск), приоритеты. + +`recheck-params.md` — три строки: + +```markdown +Implementer's report with resolutions: read {{$D/fix-result.md}}. +Test command (expect {{N}} passed): {{command}} +``` + +Кавеат: проверь, что Codex-ревьюер может читать `$SCRATCH` из песочницы +(temp-каталоги обычно читаемы в workspace-write). Если нет — резолюции по +его находкам передай текстом (только его находки, не весь отчёт). diff --git a/agents/.agents/skills/claude-subagent-playbook/references/prompts/recheck-header.md b/agents/.agents/skills/claude-subagent-playbook/references/prompts/recheck-header.md new file mode 100644 index 0000000..1e2ef88 --- /dev/null +++ b/agents/.agents/skills/claude-subagent-playbook/references/prompts/recheck-header.md @@ -0,0 +1,13 @@ +# Narrow re-check: do the fixes close your findings? + +The implementer has processed the findings of your review. Check ONLY your +own findings — no full second pass. Mandate unchanged: modify nothing; +reading and running tests are allowed. + +Answer one line per your finding: CLOSED / NOT_CLOSED (why) / +REJECTION_VALID / REJECTION_INVALID (why). If you spot a NEW defect while +re-checking, report it in the same index format — narrowness limits scope, +not honesty. Final line: RECHECK: ALL_CLOSED | ISSUES_REMAIN + +The implementer's report path, test command and expected counters are +appended below. diff --git a/agents/.agents/skills/claude-subagent-playbook/references/prompts/review-boilerplate.md b/agents/.agents/skills/claude-subagent-playbook/references/prompts/review-boilerplate.md new file mode 100644 index 0000000..bc52a65 --- /dev/null +++ b/agents/.agents/skills/claude-subagent-playbook/references/prompts/review-boilerplate.md @@ -0,0 +1,17 @@ +## Mandate (strict) + +- Do NOT modify sources or environment. No edits — findings only. +- Running tests, verifying hypotheses, reading docs and primary sources — + allowed and encouraged; safe empirical checks in temp dirs outside the + repo make a verdict much firmer than reading alone. +- No `git add` / `git commit` / `git checkout`. +- Output only the findings index and the VERDICT line — no code retelling, + no narrative. Where to put it: your call wrapper says, or it is your + `-o` report if you were invoked via stdin. + +## Findings file format — index only + +SEVERITY(BLOCKER|MAJOR|MINOR|NIT) | file:line (or spec/task-file section) | one-phrase essence | how to verify/reproduce + +Confirmations of correctness — one line per item, no elaboration. +Final line: VERDICT: APPROVED | APPROVED_WITH_MINORS | CHANGES_REQUIRED diff --git a/agents/.agents/skills/claude-subagent-playbook/references/prompts/triage-header.md b/agents/.agents/skills/claude-subagent-playbook/references/prompts/triage-header.md new file mode 100644 index 0000000..de45dbf --- /dev/null +++ b/agents/.agents/skills/claude-subagent-playbook/references/prompts/triage-header.md @@ -0,0 +1,18 @@ +# Triage of findings from independent blind reviews of your implementation + +Below are the findings of the blind reviews, **verbatim**. Close what is +listed, change nothing else. For each finding, either: + +- a TDD fix — first a test reproducing the finding, then the fix; or +- a reasoned rejection via contract/spec and test — a bare "not important" + is not accepted. + +No commits. Record rejection arguments in the task file so a fresh thread +can continue without this thread's context. + +Final report: one line per finding — fixed (how) / rejected (argument + +where recorded); test command, run counters, list of changed files. + +Orchestrator notes, if present below, carry task-level decisions (out of +scope / risk accepted) and verified facts you don't have — they are not +findings to fix.