ddmitry/dotfiles
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(skill): принцип «мастер решает», готовые boilerplate-промпты, ревизия

Browse Source 
- Зачем:
  - ретро прогона 2026-07-12 (задача 20, clickstream-demo): контекст
    оркестратора съедали инлайн-диагнозы, переписывание boilerplate и
    кириллица в обменных файлах.
- Что:
  - SKILL.md: принцип «мастер решает — субагенты выясняют» со стоп-краном
    «сам — максимум один заход», обменные файлы на английском, сквозная
    проверка до ревьюеров, будильник одной строкой.
  - references/prompts/: готовые английские boilerplate-файлы (мандат
    ревью, триаж, перепроверка) — подшиваются cat'ом, контекст мастера
    не проходят; prompt-templates перестроен под сборку.
  - codex-exec: модель gpt-5.6-sol, лестница эффорта, ловушка «&»;
    sandbox-справочник переименован в codex-sandbox-apparmor.md;
    lessons дистиллирован, добавлена запись прогона 2026-07-12.
  - закрыты 14 находок слепого Fable-ревью скилла (согласованность,
    единый источник $SCRATCH, скелет ревью постановки).
- Проверка:
  - все внутренние ссылки резолвятся; слепое ревью: APPROVED_WITH_MINORS,
    восстановление структуры подтверждено без потерь.
This commit is contained in:
ddadmin committed 2026-07-12 22:17:59 +03:00
1 parent 60182ab493
commit 7110a075ea
9 files changed
+357 -410
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

agents/.agents/skills/claude-subagent-playbook/SKILL.md
+56 -45
View File
@@ -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/<feature>/issues/`; репозиторий настроен под скиллы
Мэтта Покока — постановка через `/to-tickets` в сконфигурированный трекер:
(например, `.scratch/<feature>/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) — определения
agents/.agents/skills/claude-subagent-playbook/references/claude-agents.md
+2 -2
View File
@@ -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 репозитория)
agents/.agents/skills/claude-subagent-playbook/references/codex-exec.md
+42 -36
View File
@@ -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 <pid>; do sleep 10; done` под
`run_in_background` будит по его реальному выходу.
- **thread_id — в первой строке stdout-JSONL** (`{"type":"thread.started",...}`).
Забирай сразу после старта: это страховка — если процесс умер или его
прибил хост, тред жив: `codex exec resume <id> «дай финальный отчёт»`.
@@ -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 <thread-id> \
-o "$SCRATCH/fix-result.md" - \
> "$SCRATCH/fix-stdout.jsonl" 2> "$SCRATCH/fix-stderr.txt"
cat "$D/fix-prompt.md" | codex exec resume --json <thread-id> \
-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 <thread-id> \
ожиданием: команда запускается его собственным фоновым 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 <job-id>`); конвейер ходит прямым
agents/.agents/skills/claude-subagent-playbook/references/codex-sandbox-fix-handover-2026-07-10.md → agents/.agents/skills/claude-subagent-playbook/references/codex-sandbox-apparmor.md
+3 -8
View File
@@ -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` (исходная машина —
agents/.agents/skills/claude-subagent-playbook/references/lessons.md
+92 -212
View File
@@ -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.
agents/.agents/skills/claude-subagent-playbook/references/prompt-templates.md
+114 -107
View File
@@ -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/<NN-slug>/` на задачу: `$SCRATCH` —
временный каталог ОС (скретчпад сессии или `mktemp -d`), подпапка — чтобы
обмен нескольких задач не сваливался в кучу. В репо не мусорит, ребут не
переживает. Windows-кавеат из codex-exec.md в силе: путь —
forward-slash, не голый `/tmp` Git Bash.
- Через Write оркестратор пишет **только параметрические блоки** ниже;
плейсхолдеры `{{...}}` — значения задачи, секции «adapt» — по смыслу.
Сборка на прогон: `D="$SCRATCH/<NN-slug>"` — подпапка задачи; `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 <thread-id>`)
## 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). Если нет — резолюции по
его находкам передай текстом (только его находки, не весь отчёт).
agents/.agents/skills/claude-subagent-playbook/references/prompts/recheck-header.md
+13
View File
@@ -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.
agents/.agents/skills/claude-subagent-playbook/references/prompts/review-boilerplate.md
+17
View File
@@ -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
agents/.agents/skills/claude-subagent-playbook/references/prompts/triage-header.md
+18
View File
@@ -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.