docs(skill): claude-subagent-playbook — write-ревьюер Codex и уборка

- Зачем: - read-only-конфайн обеднял ревью Codex (без тестов, поиска, первоисточников), а плотность SKILL.md и дефолты модели/усилия из config.toml накопили риски по итогам трёх прогонов. - Что: - ветка «ревьюер» в codex-exec.md переведена на запись + авто-аппрув, защита — мандат промптом; в рецепты добавлены --strict-config и явные -m / model_reasoning_effort. - SKILL.md: правило «мандат промптом» для обоих ревьюеров, правило моделей субагентов (Опус/Sonnet, не Fable), /tdd и /research + Context7 в этапе 1, таймер-подстраховка ScheduleWakeup; уборка плотности и инлайн-дат. - handoffs 07-06/07-07/07-09 поглощены запиской 2026-07-10; в lessons.md добавлены правило дистилляции и блок 2026-07-10; правки прошли слепое ревью Опусом, все находки закрыты. - Проверка: - оверрайды -m/-c проверены живым codex exec --strict-config; перекрёстные ссылки и команды сверены ревьюером с codex --help. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-10 12:41:09 +03:00
1 parent 4e496a1548
commit 89ebd1d327
@@ -1,64 +0,0 @@
-# Handoff: рождение скилла claude-subagent-playbook и что в нём не проверено
-
-Дата: 2026-07-06. Для сессии, которая будет развивать сам скилл (не МЛ-задачу).
-
-## Состояние
-
- Скилл собран и готов к вызову: источник —
-  `~/dotfiles/agents/.agents/skills/claude-subagent-playbook/` (в git dotfiles
-  ещё не закоммичен), зеркало — `~/.claude/skills/claude-subagent-playbook/`.
-  Состав: SKILL.md + references/{codex-companion,lessons,claude-agents}.md.
- Собран по итогам одного боевого прогона (задача 05 «полировка витрины» в
-  `~/sources/t2-ml-forecast`, коммит 880d506) — но сам прогон шёл ДО оформления
-  скилла. **Скилл ни разу не исполнялся по своему письменному тексту.**
- Эмпирика прогона — в references/lessons.md (файл накопительный, дописывать
-  после каждого прогона). Память проекта t2-ml-forecast тоже знает о скилле:
-  `~/.claude/projects/-home-ddmitry-sources-t2-ml-forecast/memory/`.
-
-## Дизайн-решения и их источники (не пересказ — только происхождение)
-
- Форма «набор знаний, не жёсткий каркас» — явное требование пользователя;
-  жёсткий каркас уже есть у `/coordinator-loop` (очередь issue, сторона Codex).
- Структура и словарь выверены по `/writing-great-skills`: user-invoked,
-  короткий description, completion criteria на шагах, ведущие слова общие с
-  coordinator-loop (индекс, родословная, свежесть).
- Раннер-паттерн для вызова Codex — из `/adversarial-review`
-  (references/runner.md там — самый проработанный образец: двухканальный
-  протокол, результат файлом, ретраи). Добавлен по предложению пользователя.
- Триаж находок исполнителем — из `/claude-team-review` и coordinator-loop
-  («судит тот, у кого контекст кода»). Тоже добавлен по замечанию пользователя.
-
-## Не проверено боем — проверять в следующих прогонах
-
-1. **Раннер с `task --wait`** — в прогоне 05 использовался `--background` +
-   bash-монитор, раннер не пробовали. Открытый риск: у Bash-вызова внутри
-   субагента потолок 10 минут (timeout max 600000 мс), а реализация у Codex
-   шла ~15 минут. Раннеру, видимо, нужна инструкция «по таймауту не падать, а
-   опрашивать `$CC status`/`result` до завершения». Обкатать и вписать в
-   references/codex-companion.md то, что реально сработало.
-2. **Триаж исполнителем** — в прогоне 05 триаж делал оркестратор (обе находки
-   принял сам). Формулировка «перешли индекс дословно, Codex чинит или
-   аргументированно отклоняет» — теория из соседних скиллов, не наша эмпирика.
-3. **Фолбэк ревьюера** (general-purpose со скептическим промптом при
-   отсутствии adversarial-reviewer) — не обкатан.
-4. **Порог «мелочь vs конвейер»** откалиброван по одному случаю — уточнять.
-5. **Чего в скилле осознанно нет** (кандидаты при развитии, не тащить без
-   нужды): журнала прогона (след живёт в задаче-файле — хватит ли на длинной
-   задаче?); узкого rerun-а ревьюера продолжением той же сессии (SendMessage —
-   в 05 не понадобился); ролей deep-reasoner в синтезе.
-
-## Ближайший боевой тест
-
-Регламент переобучения («выживаемость») в t2-ml-forecast — единственный
-незакрытый пункт Этапа 1 пилота, калибр подходящий. Вызвать
-`/claude-subagent-playbook` в свежей сессии и смотреть, где текст скилла
-расходится с практикой; расхождения — в lessons.md и правки SKILL.md.
-
-## Suggested skills
-
- `/claude-subagent-playbook` — предмет работы; прогнать как написано.
- `/writing-great-skills` — перед любыми правками структуры скилла.
- `/adversarial-review` — образец раннера (references/runner.md) при обкатке
-  пункта 1.
- `/handoff` — по завершении сессии развития обновить эту записку (или
-  положить рядом новую; старую можно удалить, если полностью поглощена).
@@ -1,62 +0,0 @@
-# Handoff: уроки прогона 2026-07-07 для доработки скилла
-
-Дата: 2026-07-07 22:34. Прогон: проверка пути менти + диагноз флаки-гейта
-в репозитории clickstream-ch-kafka-superset-demo (Claude — оркестратор,
-два Claude-субагента, Codex-диагност через плагин).
-
-## Что сработало
-
- Пара «читатель-скептик (Opus) + прогонщик-механик (Sonnet)» параллельно:
-  читатель нашёл 4 доковых находки, прогонщик — реальное падение гейта.
- «Шум в файлы» окупился дважды: когда прогонщик умер без отчёта, вердикт
-  собрался из его логов; когда форвардер Codex соврал «finished», результат
-  забрался из output-файла фонового задания.
- Перепроверка ключевого факта диагноза своими глазами (grep по коду) —
-  дёшево и поймала бы подмену анализа (bug #158 плагина).
-
-## Находки для SKILL.md / references/lessons.md
-
-1. **Таймер-подстраховка для фоновых субагентов** (совет пользователя):
-   субагенты молча останавливаются («жду уведомления», которого не будет;
-   «закончил и умер без отчёта»). Ставить ScheduleWakeup сроком больше
-   ожидаемой длительности, при пробуждении смотреть логи агента самому,
-   снимать таймер по приходу результата. Экономика: кэш мастер-сессии живёт
-   ~1 час — пробуждение в пределах часа тёплое (~0,1×); таймер — страховка,
-   не поллинг.
-2. **Прямой `codex exec` вместо плагина** (веб-ресёрч, первоисточники):
-   обёртка codex-companion.mjs — багованная машина фоновых задач
-   (openai/codex-plugin-cc issues #279, #158, #49, #277; #158 — молчаливая
-   подмена Codex своим анализом, ломает слепое ревью разных родословных).
-   Рекомендация: CLI в собственном run_in_background Bash оркестратора
-   (pid/код выхода/лог у нас), `codex exec resume <session-id>` для раундов.
-3. **Поправки пользователя к флагам CLI** (важно, расходится с ресёрчем):
-   НЕ дефолтить `-s read-only -c approval_policy=never`. Рабочая практика:
-   сессия с правом записи, ограниченная промтом (иначе Codex не гоняет тесты
-   и не гуглит), плюс авто-режим аппрува, где отдельная модель оценивает
-   безопасность действий. `timeout 600` мал — сессии запросто длиннее,
-   таймаут подбирать под задачу. В скилле развести два режима: «ревьюер»
-   (можно жёстко read-only) и «исполнитель/диагност» (запись + авто-аппрув).
-4. **Идея пользователя для форвардера:** субагент-обёртка мог бы читать
-   историю сессии Codex (JSONL / resume) и отвечать на поллинг оркестратора,
-   вместо «выстрелил и умер». Казус прогона: codex-rescue отказался проверять
-   статус своего же вызова, сославшись на мандат «только один проброс».
-5. **Казус «умер без отчёта»:** правильный ход — не воскрешать агента ради
-   отчёта, а собрать вердикт из его логов (дополнение к приёму «шум в файлы»).
-6. **Правильный паттерн ожидания у субагента** (это реально разбудило
-   заснувшего прогонщика): долгий шаг ждать через отслеживаемый харнесом
-   фоновый Bash (`run_in_background`) с командой-ожидателем под `timeout` —
-   `until grep -q '<маркер>' <лог>; do sleep 30; done` — тогда харнес
-   переинвоцирует агента по выходу процесса. Самодельные «фоновые мониторы»
-   и «жду уведомления» без отслеживаемого процесса не будят никогда.
-   Вписывать этот паттерн в промпт раннера сразу, а не после двух побудок.
-
-## Открытое
-
- ~~Механику references/codex-companion.md стоит пересмотреть в пользу прямого
-  CLI (пункты 2–3); плагин оставить для интерактива.~~ Сделано 2026-07-09:
-  файл заменён на references/codex-exec.md (три ветки: исполнитель/ревьюер/
-  триаж; пункты 2–3 и 6 поглощены), companion — абзац «для интерактива».
- Определения deep-reasoner/fast-worker из references/claude-agents.md
-  созданы в репозитории демо (закоммичены); фрагмент «Orchestration
-  workflow» в CLAUDE.md демо-репозитория НЕ добавлен — пользователь решил
-  не засорять учебный контракт, вопрос «куда класть» открыт.
@@ -1,57 +0,0 @@
-# Handoff: прогон 2026-07-09 (Windows) и переход на прямой codex exec
-
-Дата: 2026-07-09. Для сессии, которая будет развивать скилл или гонять
-конвейер (на Linux — см. «Открытое»).
-
-## Состояние
-
- Скилл прошёл **первый прогон по своему письменному тексту** и первый под
-  Windows (local-transcriber, SendTo-меню; фича закоммичена f18ad6e).
-  Эмпирика прогона — в references/lessons.md, блок 2026-07-09; здесь не
-  дублируется.
- По итогам + урокам handoff 07-07 механика Codex переведена на прямой CLI:
-  references/codex-companion.md **удалён**, вместо него —
-  references/codex-exec.md (три ветки: исполнитель/ревьюер/триаж; сквозные
-  правила: шум в файлы, thread_id из первой строки, resume только по id,
-  проверка «отписки» логом, блок классификатора → решение пользователя).
-  SKILL.md: этап 3 — прямой exec фоновым Bash оркестратора; этап 4 —
-  критерий «вердикт без находок засчитывай после проверки лога».
- Правки прошли свежий взгляд (Опус, с оптикой /writing-great-skills,
-  сверял команды с реальным `codex --help`): 2 major исправлены
-  (resume принимает `-m`; кавеат про недокументированный
-  `approvals_reviewer`), sediment companion-эры сжат до строки, дубль
-  промпта исполнителя схлопнут в указатель на этап 3.
-
-## Решения и их источники
-
- Раннер-субагент понижен из «пути запуска» в «переваривание шумного
-  результата» (самодостаточный абзац в codex-exec.md, без ссылок на другие
-  скиллы — они могут быть недоступны). Причина: файл-редиректы дают чистоту
-  контекста без раннера, а 10-минутный потолок Bash бьёт именно по
-  синхронному раннеру, не по фоновому Bash оркестратора.
- `approvals_reviewer="auto_review"`: в `--help` отсутствует, но
-  `--strict-config` принимает (проверено 2026-07-09), связка с
-  `approval_policy="on-request"` отработала боевой write-прогон. Следить:
-  если в новой версии CLI ключ отвалится — падение будет громким только
-  со `--strict-config`.
-
-## Открытое / не проверено боем
-
-1. **Linux-прогон рецептов codex-exec.md** — файл написан по
-   Windows-эмпирике + старым companion-урокам; первый линукс-прогон должен
-   подтвердить рецепты (особенно пути `$SCRATCH` и поведение классификатора).
-2. **Раннер-«переваривание»** в новой формулировке не обкатан (сегодня не
-   понадобился — вердикты были короткими).
-3. **Порог «мелочь vs конвейер»** — по-прежнему калиброван парой случаев.
-4. **deep-reasoner/fast-worker** в прогонах плейбука пока не участвовали;
-   вопрос «куда класть фрагмент Orchestration workflow» из handoff 07-07
-   так и открыт.
-5. Идея «эмпирического ревьюера» (безопасные проверки вне репо — сегодня
-   Опус сам воспроизводил краевые случаи) вписана в lessons, но в промпт
-   ревьюера в SKILL.md не поднята — решить при следующей правке, стоит ли.
-
-## Suggested skills
-
- `/claude-subagent-playbook` — прогнать на Linux, расхождения — в lessons.
- `/writing-great-skills` — оптика перед любыми правками структуры.
- `/handoff` — обновить/заменить эту записку по итогам следующей сессии.
@@ -0,0 +1,71 @@
+# Handoff: Codex-ревьюер переведён на write+авто-аппрув; хендоффы слиты
+
+Дата: 2026-07-10. Для сессии, которая будет развивать скилл или гонять
+конвейер. Заменяет записки 07-06, 07-07 и 07-09 — их непроверенные пункты
+перенесены сюда, остальное поглощено SKILL.md / references.
+
+## Состояние
+
+- По указанию пользователя ветка «ревьюер» в references/codex-exec.md
+  переведена с `-s read-only` на тот же вызов, что у исполнителя (запись +
+  авто-аппрув). Мотив: read-only отнимал у ревьюера руки — тесты, гипотезы,
+  поиск, документацию, первоисточники. Защита — мандат промптом
+  «исходники/окружение не менять» (Codex держит его надёжно — практика
+  пользователя), подстраховка — сверка `git status --porcelain` до/после.
+  Провенанс — lessons.md, блок 2026-07-10.
+- SKILL.md: правило «мандат промптом, не урезанием» распространено на обоих
+  ревьюеров (Роли); в этап 4 подняты эмпирические проверки ревьюером (закрыт
+  открытый пункт 5 записки 07-09) и сверка дерева; в «Пользователь в петле»
+  добавлена таймер-подстраховка ScheduleWakeup (поглощён пункт 1 записки
+  07-07); в этап 1 и «Соседние скиллы» добавлены `/tdd` (в задаче можно
+  ссылаться прямо: у Codex тот же набор скиллов — общий каталог
+  `.agents/skills`; ключевые требования всё равно дублировать текстом) и
+  `/research` + Context7 MCP (исследование до постановки, выжимка — в
+  «сначала прочитать»).
+- В «Роли» добавлено правило моделей: Claude-субагентам модель задавать
+  явно (Опус — рассуждения/ревью, Sonnet — механика), не наследовать Fable —
+  его лимиты держать для оркестрации.
+- SKILL.md прошёл уборку плотности: сжаты «Ревьюеры» (детали write-мандата —
+  только в codex-exec.md), этап 1 (research/tdd — по фразе со ссылкой),
+  буллет моделей и «Пользователь в петле»; инлайн-даты эмпирики убраны —
+  провенанс живёт в lessons.md. В шапку lessons.md добавлено правило
+  дистилляции (урок поглощён → запись сжимается до строки-факта).
+- Правки прошли свежее ревью (Опус, скептический general-purpose;
+  NEEDS-ATTENTION → всё закрыто): в рецепт исполнителя добавлены
+  `--strict-config` (опечатки в `-c`-ключах падают громко) и явные
+  `-m` + `model_reasoning_effort` (новое сквозное правило: дефолты из
+  `~/.codex/config.toml` плавают за интерактивными сессиями пользователя;
+  оверрайды проверены живым вызовом 2026-07-10); в ветку ревьюера вписан
+  кавеат про сеть (гипотеза, не эмпирика); раннер — `fast-worker` с
+  фолбэком general-purpose (было противоречие со SKILL.md); починена
+  висячая ссылка на удалённую записку в lessons.md; в claude-agents.md
+  оговорено намеренное отсутствие определения adversarial-reviewer;
+  `/claude-team-review` помечен как внешний (в `.agents/skills/` его нет).
+
+## Открытое / не проверено боем
+
+1. **Write-ревьюер Codex не обкатан** — все прежние прогоны шли read-only
+   ревью-тредом. Проверить: (а) дерево действительно нетронуто; (б) хватает
+   ли связки `approval_policy="on-request"` + `approvals_reviewer=
+   "auto_review"` для сетевых действий (поиск, документация) — песочница
+   workspace-write сеть по умолчанию режет, рабочая гипотеза — эскалация
+   через авто-аппрув.
+2. **Linux-прогон рецептов codex-exec.md** — вся эмпирика прямого exec
+   Windows-ная (Git Bash); особенно пути `$SCRATCH` и поведение
+   классификатора авторежима.
+3. **Раннер-«переваривание шумного результата»** в новой формулировке не
+   обкатан (пока не понадобился — вердикты были короткими).
+4. **Порог «мелочь vs конвейер»** — калиброван парой случаев, уточнять.
+5. **deep-reasoner/fast-worker** в прогонах плейбука не участвовали; вопрос
+   «куда класть фрагмент Orchestration workflow из claude-agents.md» открыт
+   (в демо-репо решили не засорять учебный CLAUDE.md).
+6. **Test-first-постановка** (ссылка на `/tdd` в задаче + дублирование
+   ключевых требований текстом) — теория, в прогоне не проверялась; в т.ч.
+   действительно ли Codex подхватывает скилл по ссылке из файла задачи.
+
+## Suggested skills
+
+- `/claude-subagent-playbook` — прогнать с write-ревьюером; расхождения — в
+  lessons.md.
+- `/writing-great-skills` — оптика перед правками структуры скилла.
+- `/handoff` — заменить эту записку по итогам следующей сессии.