docs(skill): claude-subagent-playbook — прямой codex exec, уроки прогона 2026-07-09

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-09 20:05:37 +03:00
1 parent 35d4114ba3
commit 4e496a1548
@@ -33,7 +33,7 @@ issue; пользователь справедливо остановил). Оч
 - **Codex** — реализация кода. У пользователя лимиты Codex больше, код он
  пишет в целом лучше, но верхнеуровнево планирует хуже — поэтому
  декомпозиция и постановка остаются у тебя. Механика вызова —
-  [references/codex-companion.md](references/codex-companion.md).
+  [references/codex-exec.md](references/codex-exec.md).
 - **Ревьюеры** — два, **разных родословных**, слепые друг к другу:
  Claude-субагент (adversarial-reviewer, **на Опусе** — экономия лимитов) и
  Codex **свежим тредом** (не тем, что писал код). Разные родословные ловят
@@ -67,10 +67,10 @@ issue; пользователь справедливо остановил). Оч
   находка внесена в задачу **решением** или письменно отклонена — «пусть
   решит исполнитель» решением не считается.
 3. **Реализация Кодексом.** Промпт: «задача самодостаточна, следуй буквально,
-   коммит не делай». Запуск — **раннером-субагентом** (приём из
+   коммит не делай». Запуск — прямым `codex exec` **фоновым Bash
-   `/adversarial-review`: раннеру — готовую команду, шум остаётся у него,
+   оркестратора**: шум — редиректами в файлы, в контекст читается только
-   монитор не нужен) либо companion-CLI напрямую; рецепты и ловушки —
+   файл отчёта, харнесс будит по завершении; рецепты, ветки и ловушки —
-   [references/codex-companion.md](references/codex-companion.md).
+   [references/codex-exec.md](references/codex-exec.md).
   Один писатель в дереве: пока Codex пишет — никто больше (казус с
   форвардером — в [references/lessons.md](references/lessons.md)). Готово,
   когда Codex вернул отчёт, а в дереве нет правок, которых он не называл.
@@ -78,7 +78,9 @@ issue; пользователь справедливо остановил). Оч
   (математика/краевые случаи, соответствие критериям, честность тестов,
   артефакты). Друг про друга не знают, твои выводы им не пересказывай.
   Клод-ревьюеру можно поручить смотреть артефакты (картинки из ноутбука).
-   Этап закрыт, когда оба вердикта у тебя индексами.
+   Этап закрыт, когда оба вердикта у тебя индексами; вердикт без единой
   находки засчитывай только после проверки его лога — работа, не отписка
   (приём — в [references/codex-exec.md](references/codex-exec.md)).
 5. **Синтез и триаж.** Сведи вердикты по индексам: пересечения, противоречия.
   Пофиндинговый триаж — у **исполнителя**, не у тебя (правило
   `/claude-team-review` и `/coordinator-loop`: судит тот, у кого контекст
@@ -99,8 +101,8 @@ issue; пользователь справедливо остановил). Оч
 В отличие от `/coordinator-loop`, здесь пользователь рядом: докладывай в чат
 короткие статусы на границах этапов (постановка готова, ревью пришло,
 вердикты сведены), решения по скоупу оставляй ему. Фоновые этапы будят тебя
-сами — не поллинг вручную, а фоновый монитор + уведомления
+сами — не поллинг вручную, а отслеживаемые фоновые процессы + уведомления
-(механика — [references/codex-companion.md](references/codex-companion.md)).
+(механика — [references/codex-exec.md](references/codex-exec.md)).
 ## Соседние скиллы
@@ -113,9 +115,9 @@ issue; пользователь справедливо остановил). Оч
 ## Подробнее
- [references/codex-companion.md](references/codex-companion.md) — команды
+- [references/codex-exec.md](references/codex-exec.md) — прямой `codex exec`:
-  companion-CLI, мониторинг, ловушки (read-only без `--write`, форвардер,
+  сквозные правила (шум в файлы, thread_id, resume по id, проверка отписки),
-  idle-уведомления фоновых агентов).
+  ветки исполнитель/ревьюер/триаж, раннер для переваривания шума.
 - [references/lessons.md](references/lessons.md) — датированная эмпирика
  прогонов: что поймал каждый этап, казусы, цифры.
 - [references/claude-agents.md](references/claude-agents.md) — определения
@@ -52,8 +52,10 @@
 ## Открытое
- Механику references/codex-companion.md стоит пересмотреть в пользу прямого
+- ~~Механику references/codex-companion.md стоит пересмотреть в пользу прямого
-  CLI (пункты 2–3); плагин оставить для интерактива.
+  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 демо-репозитория НЕ добавлен — пользователь решил
@@ -0,0 +1,57 @@
 # 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` — обновить/заменить эту записку по итогам следующей сессии.
@@ -1,89 +0,0 @@
 # Codex companion из Claude Code: команды и ловушки
 Проверено 2026-07-06 (плагин openai-codex/codex 1.0.5). Путь к скрипту зависит
 от версии — найди актуальный:
 ```bash
 ls ~/.claude/plugins/cache/openai-codex/codex/*/scripts/codex-companion.mjs
 ```
 Далее `$CC` = `node <найденный путь>`.
 ## Команды
 ```bash
 $CC task --background --write --fresh "промпт"   # реализация (пишет файлы)
 $CC adversarial-review --background --scope working-tree "фокус ревью"
 $CC status                    # все задачи; status <job-id> — одна, с прогрессом
 $CC result <job-id>           # финальный отчёт завершённой задачи
 $CC cancel <job-id>
 $CC task-resume-candidate --json   # есть ли возобновляемый тред этой сессии
 ```
 ## Запуск через раннера-субагента — рекомендуемый путь
 Приём из `/adversarial-review`: оркестратор не зовёт CLI сам и не городит
 мониторы — фоновый субагент-раннер синхронно гоняет команду у себя, шум
 остаётся в нём, а завершение субагента само будит оркестратора.
 Ключевое правило: **раннеру — готовую команду, не постановку задачи.**
 Получив постановку, «тонкий» агент реализует её сам (ловушка форвардера).
 Промпт задачи живёт только внутри строки-аргумента команды.
 Рецепт: Agent tool, `subagent_type: "general-purpose"` (или `fast-worker`,
 если есть), `run_in_background: true`, промпт раннеру:
 ```text
 Выполни ровно одну команду Bash, ничего не решай и не делай сверх неё:
 $CC task --wait --write --fresh "<полный промпт задачи>" \
  > /tmp/<scratchpad>/codex-run-<id>.log 2>&1
 Затем верни: код возврата, путь к логу и последние ~30 строк лога.
 ```
 Так же запускается и ревью (`adversarial-review --wait ...`). Прямой вызов
 CLI с `--background` + фоновый bash-монитор (ниже) — запасной путь, когда
 раннер нежелателен (например, экономия субагентов).
 ## Ловушки (все выстраданы)
 - **Без `--write` среда Codex только на чтение.** Задача «реализуй…» без
  этого флага молча не сможет писать файлы.
 - **`task --help` не существует** — строка `--help` уходит Кодексу как промпт
  и создаёт мусорный тред. Синтаксис смотри `$CC` без аргументов.
 - **`--fresh` против `--resume-last`:** resume-last цепляет самый свежий тред,
  а им может оказаться тред ревью, не реализации. Для точечных починок надёжнее
  `--fresh` + точный промпт («добавь только X, ничего больше не меняй»).
 - **Коммит запрещай промптом** («коммит не делай — оставь в рабочем дереве»):
  ревью идёт по незакоммиченному дифу, коммитит оркестратор.
 - **Тонкому агенту-форвардеру не давай содержательный промпт.** Субагент
  `codex:codex-rescue` должен только пробросить команду; получив постановку
  задачи, он реализует её сам вместо передачи (казус 2026-07-06 — второй
  писатель в дереве). Либо зови companion напрямую из Bash, либо давай
  форвардеру только готовую команду.
 ## Мониторинг фоновых задач (запасной путь)
 При прямом `--background` уведомлений от companion нет — повесь фоновый
 bash-монитор, он разбудит оркестратора по завершении:
 ```bash
 # run_in_background: true
 for i in $(seq 1 120); do
  st=$($CC status <job-id> 2>/dev/null)
  if echo "$st" | grep -q '| running |'; then sleep 30; else echo FINISHED; exit 0; fi
 done
 ```
 Парсить plain-text: `status --json` устроен иначе, чем кажется (грабли
 2026-07-06 — монитор на JSON-поле `state` крутился вечно на `unknown`).
 ## Фоновые Claude-субагенты (Agent tool)
 - Ревьюеров запускай `model: "opus"` (экономия лимитов; ревью на Фабуле —
  ~60k токенов за прогон).
 - Фоновый агент по завершении шлёт **idle-уведомление без содержимого**.
  Финальный отчёт запроси `SendMessage`: «верни готовый результат, ничего
  нового не проверяй».
 - Проверяй, что делегат сделал именно то, что просили: `git status` до и
  после, кто и когда трогал файлы (`stat -c '%y'`), прежде чем запускать
  следующего писателя.
@@ -0,0 +1,95 @@
 # Codex через прямой `codex exec`: рецепты и ловушки
 Проверено 2026-07-09 (codex-cli 0.142.5, Windows + Git Bash); линукс-эмпирика
 прогонов 07-06/07-07 шла через companion-обёртку и отражена в уроках ниже.
 Прямой CLI надёжнее обёртки: её фоновая машина глючит (молчаливая подмена
 анализа Кодекса своим — issue #158, ломает слепое ревью; зависшие статусы),
 и её `--write`-запуски режет классификатор авторежима. Далее `$SCRATCH` =
 каталог скретчпада сессии из системного промпта (не `/tmp`: под Windows
 `/tmp` Git Bash — ловушка).
 ## Сквозные правила (любая ветка)
 - **Промпт — файлом, шум — в файлы.** Промпт пиши Write'ом в `$SCRATCH` и
  подавай через stdin (`-`); stdout/stderr — редиректами туда же. В контекст
  оркестратора читается ровно один файл — финальный отчёт из `-o`.
 - **Запуск — собственным фоновым Bash оркестратора** (`run_in_background`):
  фоновый процесс детачится, живёт сквозь ходы и будит оркестратора по
  выходу. Потолок 10 минут — только у фронтграундного Bash; фоновому таймаут
  не нужен, `timeout NNN` вокруг codex не ставь.
 - **thread_id — в первой строке stdout-JSONL** (`{"type":"thread.started",...}`).
  Забирай сразу после старта: это страховка — если процесс умер или его
  прибил хост, тред жив: `codex exec resume <id> «дай финальный отчёт»`.
 - **resume — только по явному id.** Безадресный resume цепляет последний тред
  сессии — при параллельных тредах подхватит чужой (например, read-only
  ревью-тред вместо write-треда реализации).
 - **Вердикт без находок — проверь лог: работа или отписка.** Дёшево:
  `grep -c '"command_execution"' stdout.jsonl` (счётчик выполненных команд)
  или промежуточные сообщения —
  `jq -r 'select(.item.type=="agent_message") | .item.text' stdout.jsonl`.
  Одна строка APPROVED при пустом счётчике — отписка, перезапускай.
 - **Кросс-платформенно.** Рецепты — POSIX под Git Bash (эмпирика 2026-07-09:
  `codex`, `jq`, редиректы под Windows работают). `$SCRATCH` задавай
  forward-slash-путём (`/c/Users/...`), не `C:\...`; пути в аргументах
  кавычь; в выводах под Windows возможны `\r`.
 - **Блок классификатора — решение пользователя.** Если запуск не прошёл
  permission-гейт, дай пользователю готовую команду с префиксом `!` в чат
  или попроси сменить режим разрешений. Сработавший путь — прямой exec;
  companion с `--write` блокируется и напрямую, и через раннера.
 ## Ветка «исполнитель» (пишет код)
 ```bash
 cat "$SCRATCH/task-prompt.md" | codex exec --json \
  -s workspace-write \
  -c 'approval_policy="on-request"' -c 'approvals_reviewer="auto_review"' \
  -o "$SCRATCH/task-result.md" - \
  > "$SCRATCH/task-stdout.jsonl" 2> "$SCRATCH/task-stderr.txt"
 ```
 - Право записи + авто-ревьюер аппрувов (`approvals_reviewer` в `--help` не
  документирован, но `--strict-config` его принимает — проверено 2026-07-09;
  связка отработала боевой прогон). Скоуп ограничивай промптом («коммит не
  делай», границы из файла задачи), не песочницей — жёсткий read-only лишает
  исполнителя тестов и поиска.
 - Промпт: путь к файлу задачи; мандат — в этапе 3 SKILL.md.
 - До старта сними baseline `git status --porcelain`; после — сверь отчёт
  Кодекса с деревом: правок, которых он не называл, быть не должно.
 ## Ветка «ревьюер» (свежий тред, только чтение)
 Тот же вызов, но `-s read-only` и без approvals-флагов. Свежий тред, не тот,
 что писал код. В промпте — формат «только индекс находок» (SEVERITY,
 файл:строка, суть, как проверить) и явная строка VERDICT.
 ## Ветка «триаж/починка» (тем же тредом, что писал код)
 ```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"
 ```
 - `resume` не принимает `-s`/`-C` — песочница и CWD наследуются от исходного
  треда (write-тред остаётся write); модель наследуется, но переопределяется
  `-m` при нужде.
 - Промпт — индекс находок **дословно** + «закрой перечисленное, больше
  ничего не меняй; отклонение — только аргументированно».
 ## Раннер-субагент: когда результат надо переварить
 Для запуска раннер не нужен (см. сквозные правила) — он нужен, когда сырой
 результат шумный и его стоит провалидировать или сжать до индекса, прежде
 чем показывать оркестратору. Тогда general-purpose-субагенту отдай
 **готовую команду** и правила разбора — не постановку задачи: тонкий агент,
 получив постановку, реализует её сам (казус форвардера, lessons 2026-07-06).
 Свой 10-минутный потолок на синхронный Bash раннер обходит отслеживаемым
 ожиданием: команда запускается его собственным фоновым Bash, а ждёт он
 процессом-ожидателем (`until grep -q '<маркер>' лог; do sleep 30; done` под
 `run_in_background`) — харнесс переинвоцирует его по выходу процесса.
 «Жду уведомления» без отслеживаемого процесса не будит никогда
 (эмпирика 2026-07-07).
 Companion-плагин (`codex-companion.mjs` в кэше плагинов) — только для
 ручного интерактива (`status`, `result <job-id>`); конвейер ходит прямым
 exec.
@@ -22,7 +22,7 @@
 **Казус форвардера:** субагент `codex:codex-rescue`, получив постановку
 вместо команды, реализовал задачу сам (+1227 строк). Настоящий Codex стартовал
 на уже изменённом дереве — столкновения избежали везением (форвардер успел
-закончить). Урок в SKILL.md и codex-companion.md.
+закончить). Урок в SKILL.md и codex-exec.md (раздел про раннера).
 **Слепое двойное ревью — родословные поймали разное:**
 - Клод (Опус): APPROVE; подтвердил математику поворота/коридора
@@ -88,3 +88,54 @@
 **Цифры:** реализация 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.
 **Закрыты пункты «не проверено боем» из handoff 06:** фолбэк-ревьюер
 general-purpose на Опусе — обкатан дважды (постановка и код), работает;
 триаж исполнителем — `codex exec resume` по явному id закрыл 3/3 находки,
 лишнего не тронул; узкий rerun ревьюера — SendMessage поднял того же
 Опус-агента из транскрипта, RECHECK OK за ~38 сек.
 **Эмпирический ревьюер:** Опус сам воспроизводил краевые случаи вне репо
 (UnicodeEncodeError с обрезкой файла, LF-`.cmd` через `cmd /c`) — вердикт
 заметно твёрже. Приём поощрять в промпте ревьюера («безопасные
 эмпирические проверки вне репо разрешены»).
 **Цифры:** ревью постановки ~57k токенов, ревью кода ~48k, перепроверка
 ~45k (тот же агент из транскрипта); триаж-раунд Codex — одна resume-команда.