From 89ebd1d3279e36afaa4143c189fdeaffab2e7fa0 Mon Sep 17 00:00:00 2001 From: Dmitriy Dementiev Date: Fri, 10 Jul 2026 12:41:09 +0300 Subject: [PATCH] =?UTF-8?q?docs(skill):=20claude-subagent-playbook=20?= =?UTF-8?q?=E2=80=94=20write-=D1=80=D0=B5=D0=B2=D1=8C=D1=8E=D0=B5=D1=80=20?= =?UTF-8?q?Codex=20=D0=B8=20=D1=83=D0=B1=D0=BE=D1=80=D0=BA=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - 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 --- .../skills/claude-subagent-playbook/SKILL.md | 52 +++++++++----- ...6-1818-rozhdenie-skilla-i-neproverennoe.md | 64 ----------------- ...20260707-2234-uroki-progona-i-codex-cli.md | 62 ---------------- ...260709-2000-progon-windows-i-codex-exec.md | 57 --------------- ...odex-revyuer-write-i-sliyanie-handoffov.md | 71 +++++++++++++++++++ .../references/claude-agents.md | 3 + .../references/codex-exec.md | 50 +++++++++---- .../references/lessons.md | 19 ++++- 8 files changed, 163 insertions(+), 215 deletions(-) delete mode 100644 agents/.agents/skills/claude-subagent-playbook/handoffs/20260706-1818-rozhdenie-skilla-i-neproverennoe.md delete mode 100644 agents/.agents/skills/claude-subagent-playbook/handoffs/20260707-2234-uroki-progona-i-codex-cli.md delete mode 100644 agents/.agents/skills/claude-subagent-playbook/handoffs/20260709-2000-progon-windows-i-codex-exec.md create mode 100644 agents/.agents/skills/claude-subagent-playbook/handoffs/20260710-codex-revyuer-write-i-sliyanie-handoffov.md diff --git a/agents/.agents/skills/claude-subagent-playbook/SKILL.md b/agents/.agents/skills/claude-subagent-playbook/SKILL.md index dd2fbc8..3450ab5 100644 --- a/agents/.agents/skills/claude-subagent-playbook/SKILL.md +++ b/agents/.agents/skills/claude-subagent-playbook/SKILL.md @@ -20,9 +20,9 @@ description: >- **Не разворачивай конвейер на мелочь.** Косметика, пара часов работы, один файл — сделай сам: накладные расходы процесса многократно превысят цену -работы (эмпирика 2026-07-06: на полировку ноутбука чуть не завели несколько -issue; пользователь справедливо остановил). Очередь зависимых issue с -автономным прогоном — это `/coordinator-loop`, не этот плейбук. +работы (эмпирика: на полировку ноутбука чуть не завели несколько issue — +пользователь остановил). Очередь зависимых issue с автономным прогоном — +это `/coordinator-loop`, не этот плейбук. ## Роли @@ -35,13 +35,13 @@ issue; пользователь справедливо остановил). Оч декомпозиция и постановка остаются у тебя. Механика вызова — [references/codex-exec.md](references/codex-exec.md). - **Ревьюеры** — два, **разных родословных**, слепые друг к другу: - Claude-субагент (adversarial-reviewer, **на Опусе** — экономия лимитов) и - Codex **свежим тредом** (не тем, что писал код). Разные родословные ловят - непересекающиеся классы находок — это центральная находка и - `/coordinator-loop` (кросс-линия), и прогона 2026-07-06 (Клод подтвердил - математику и краевые случаи, Кодекс нашёл дыры в тестах). Нет типа - `adversarial-reviewer` в среде — возьми `general-purpose` со скептическим - промптом и запретом менять репозиторий (мандат промптом, не урезанием). + Claude-субагент (`adversarial-reviewer`; нет в среде — скептический + `general-purpose`) и Codex **свежим тредом**, не тем, что писал код. + Разные родословные ловят непересекающиеся классы находок (пересечение в + прогонах — стабильно ~ноль). Обоим — руки: тесты, гипотезы, поиск, + документация, первоисточники; запрет менять исходники и окружение — + **мандатом в промпте, не урезанием песочницы** (рецепт и подстраховка — + [references/codex-exec.md](references/codex-exec.md)). - **Свежесть**: ревьюеров запускай свежими сессиями, без форка своей истории (форк тратит токены и убивает независимость). Повторную проверку точечных правок — **тем же** ревьюером узким вопросом «закрывают ли правки твои @@ -50,6 +50,10 @@ issue; пользователь справедливо остановил). Оч рассуждение — `deep-reasoner`, механика с шумным выводом — `fast-worker`. Они репо-локальные; нет в репозитории — определения для создания в [references/claude-agents.md](references/claude-agents.md). +- **Модель Claude-субагентов задавай явно**: Опус — рассуждения и ревью, + Sonnet — механика. Без явной модели субагент наследует Fable, чьи лимиты + самые дорогие — держи их для оркестрации (у `deep-reasoner`/`fast-worker` + модели пришиты в определениях). ## Конвейер @@ -57,8 +61,12 @@ issue; пользователь справедливо остановил). Оч контекста; всё нужное — в файле: цель, критерии приёмки чекбоксами, границы («что трогать нельзя»), «сначала прочитать» (спека, ADR, README с командами), команды проверки. Формат и место — по конвенции репозитория - (например, `.scratch//issues/`). Готово, когда исполнитель может - сделать задачу, не задав тебе ни одного вопроса. + (например, `.scratch//issues/`). Не хватает фактуры по внешним + библиотекам/API — сначала `/research` и Context7 MCP, выжимку — в + «сначала прочитать». Задача просится под test-first — сошлись в ней на + `/tdd` (скиллы у Codex те же — общий каталог), ключевые требования + продублируй текстом. Готово, когда исполнитель может сделать задачу, + не задав тебе ни одного вопроса. 2. **Свежий взгляд на постановку — до реализации.** Адверсарный ревьюер без твоего контекста проверяет задачу против кода: фактические ошибки, скрытые решения-«однострочники», недостающие критерии. Окупается: ловит блокеры, @@ -77,9 +85,13 @@ issue; пользователь справедливо остановил). Оч 4. **Два слепых ревью параллельно.** Каждому: путь к задаче-файлу + фокус (математика/краевые случаи, соответствие критериям, честность тестов, артефакты). Друг про друга не знают, твои выводы им не пересказывай. - Клод-ревьюеру можно поручить смотреть артефакты (картинки из ноутбука). - Этап закрыт, когда оба вердикта у тебя индексами; вердикт без единой - находки засчитывай только после проверки его лога — работа, не отписка + Обоим поощряй безопасные эмпирические проверки (воспроизвести краевой + случай вне репо, сходить в документацию) — вердикт заметно твёрже; + менять исходники и окружение нельзя, после ревью сверь дерево + (`git status`). Клод-ревьюеру можно поручить смотреть артефакты + (картинки из ноутбука). Этап закрыт, когда оба вердикта у тебя индексами + и дерево нетронуто; вердикт без единой находки засчитывай только после + проверки его лога — работа, не отписка (приём — в [references/codex-exec.md](references/codex-exec.md)). 5. **Синтез и триаж.** Сведи вердикты по индексам: пересечения, противоречия. Пофиндинговый триаж — у **исполнителя**, не у тебя (правило @@ -103,14 +115,22 @@ issue; пользователь справедливо остановил). Оч вердикты сведены), решения по скоупу оставляй ему. Фоновые этапы будят тебя сами — не поллинг вручную, а отслеживаемые фоновые процессы + уведомления (механика — [references/codex-exec.md](references/codex-exec.md)). +Подстраховка от молчаливой смерти агента — ScheduleWakeup сроком дольше +ожидаемой длительности: по пробуждению смотри логи сам, по приходу +результата таймер снимай. ## Соседние скиллы - `/coordinator-loop` — автономный цикл очереди issue на стороне Codex (координатор в Codex, worker'ы — его субагенты). Выстрадан и отлажен; словарь (индекс, свежие сессии, две ручки стоимости) — общий. -- `/claude-team-review` — ревью-петля, где лид сам чинит код. +- `/claude-team-review` — ревью-петля, где лид сам чинит код (живёт + отдельным репозиторием, в среде может быть не подключён). - `/adversarial-review` — разовое адверсарное ревью Кодексом. +- `/tdd` — дисциплина test-first: для задач-мелочей, которые делаешь сам, + и как словарь для test-first-постановки (этап 1). +- `/research` — фоновое исследование первоисточников с выжимкой-файлом; + кормит «сначала прочитать» постановки (этап 1). - `/conventional-commits` — формат коммита на финале. ## Подробнее diff --git a/agents/.agents/skills/claude-subagent-playbook/handoffs/20260706-1818-rozhdenie-skilla-i-neproverennoe.md b/agents/.agents/skills/claude-subagent-playbook/handoffs/20260706-1818-rozhdenie-skilla-i-neproverennoe.md deleted file mode 100644 index 103df57..0000000 --- a/agents/.agents/skills/claude-subagent-playbook/handoffs/20260706-1818-rozhdenie-skilla-i-neproverennoe.md +++ /dev/null @@ -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` — по завершении сессии развития обновить эту записку (или - положить рядом новую; старую можно удалить, если полностью поглощена). diff --git a/agents/.agents/skills/claude-subagent-playbook/handoffs/20260707-2234-uroki-progona-i-codex-cli.md b/agents/.agents/skills/claude-subagent-playbook/handoffs/20260707-2234-uroki-progona-i-codex-cli.md deleted file mode 100644 index fc2119a..0000000 --- a/agents/.agents/skills/claude-subagent-playbook/handoffs/20260707-2234-uroki-progona-i-codex-cli.md +++ /dev/null @@ -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 ` для раундов. -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 демо-репозитория НЕ добавлен — пользователь решил - не засорять учебный контракт, вопрос «куда класть» открыт. diff --git a/agents/.agents/skills/claude-subagent-playbook/handoffs/20260709-2000-progon-windows-i-codex-exec.md b/agents/.agents/skills/claude-subagent-playbook/handoffs/20260709-2000-progon-windows-i-codex-exec.md deleted file mode 100644 index 8fe7ff2..0000000 --- a/agents/.agents/skills/claude-subagent-playbook/handoffs/20260709-2000-progon-windows-i-codex-exec.md +++ /dev/null @@ -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` — обновить/заменить эту записку по итогам следующей сессии. diff --git a/agents/.agents/skills/claude-subagent-playbook/handoffs/20260710-codex-revyuer-write-i-sliyanie-handoffov.md b/agents/.agents/skills/claude-subagent-playbook/handoffs/20260710-codex-revyuer-write-i-sliyanie-handoffov.md new file mode 100644 index 0000000..d5d2557 --- /dev/null +++ b/agents/.agents/skills/claude-subagent-playbook/handoffs/20260710-codex-revyuer-write-i-sliyanie-handoffov.md @@ -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` — заменить эту записку по итогам следующей сессии. 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 5728982..818bcee 100644 --- a/agents/.agents/skills/claude-subagent-playbook/references/claude-agents.md +++ b/agents/.agents/skills/claude-subagent-playbook/references/claude-agents.md @@ -3,6 +3,9 @@ `deep-reasoner` и `fast-worker` — субагенты уровня репозитория (`.claude/agents/*.md`), не глобальные. В новом репозитории их нет — проверь `ls .claude/agents/` и при отсутствии создай файлы ниже как есть. +У ревьюера `adversarial-reviewer` репо-локального определения намеренно +нет: рабочий фолбэк — `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 cb1785b..05609ef 100644 --- a/agents/.agents/skills/claude-subagent-playbook/references/codex-exec.md +++ b/agents/.agents/skills/claude-subagent-playbook/references/codex-exec.md @@ -13,6 +13,12 @@ - **Промпт — файлом, шум — в файлы.** Промпт пиши Write'ом в `$SCRATCH` и подавай через stdin (`-`); stdout/stderr — редиректами туда же. В контекст оркестратора читается ровно один файл — финальный отчёт из `-o`. +- **Модель и глубину рассуждения задавай явно** (`-m`, + `-c 'model_reasoning_effort="..."'`): дефолты берутся из + `~/.codex/config.toml` и плавают за последней интерактивной сессией + пользователя. Для реализации и ревью — high; текущую боевую модель сверь + с конфигом (2026-07-10: `gpt-5.5`). Оверрайды проверены под + `--strict-config`. - **Запуск — собственным фоновым Bash оркестратора** (`run_in_background`): фоновый процесс детачится, живёт сквозь ходы и будит оркестратора по выходу. Потолок 10 минут — только у фронтграундного Bash; фоновому таймаут @@ -21,8 +27,8 @@ Забирай сразу после старта: это страховка — если процесс умер или его прибил хост, тред жив: `codex exec resume «дай финальный отчёт»`. - **resume — только по явному id.** Безадресный resume цепляет последний тред - сессии — при параллельных тредах подхватит чужой (например, read-only - ревью-тред вместо write-треда реализации). + сессии — при параллельных тредах подхватит чужой (например, ревью-тред + вместо треда реализации). - **Вердикт без находок — проверь лог: работа или отписка.** Дёшево: `grep -c '"command_execution"' stdout.jsonl` (счётчик выполненных команд) или промежуточные сообщения — @@ -40,27 +46,42 @@ ## Ветка «исполнитель» (пишет код) ```bash -cat "$SCRATCH/task-prompt.md" | codex exec --json \ - -s workspace-write \ +cat "$SCRATCH/task-prompt.md" | codex exec --json --strict-config \ + -s workspace-write -m gpt-5.5 \ + -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" ``` -- Право записи + авто-ревьюер аппрувов (`approvals_reviewer` в `--help` не - документирован, но `--strict-config` его принимает — проверено 2026-07-09; - связка отработала боевой прогон). Скоуп ограничивай промптом («коммит не - делай», границы из файла задачи), не песочницей — жёсткий read-only лишает - исполнителя тестов и поиска. +- `--strict-config` — обязателен: опечатка в `-c`-ключе упадёт громко, а не + проглотится молча (важно для `approvals_reviewer` — в `--help` он не + документирован, но strict-config его принимает; связка с + `approval_policy="on-request"` отработала боевой прогон 2026-07-09). +- Право записи + авто-ревьюер аппрувов. Скоуп ограничивай промптом («коммит + не делай», границы из файла задачи), не песочницей — жёсткий read-only + лишает исполнителя тестов и поиска. - Промпт: путь к файлу задачи; мандат — в этапе 3 SKILL.md. - До старта сними baseline `git status --porcelain`; после — сверь отчёт Кодекса с деревом: правок, которых он не называл, быть не должно. -## Ветка «ревьюер» (свежий тред, только чтение) +## Ветка «ревьюер» (свежий тред, мандат промптом) -Тот же вызов, но `-s read-only` и без approvals-флагов. Свежий тред, не тот, -что писал код. В промпте — формат «только индекс находок» (SEVERITY, -файл:строка, суть, как проверить) и явная строка VERDICT. +Тот же вызов, что у исполнителя — запись + авто-аппрув, — но **свежим +тредом**, не тем, что писал код. Read-only-песочницей ревьюера не режь: она +отнимает у него руки — тесты, проверку гипотез, поиск, документацию, +первоисточники. Защита — мандат в промпте: «исходники и окружение не менять, +правок не вносить — только находки»; Codex держит его надёжно (практика +пользователя, 2026-07-10). Дешёвая подстраховка: `git status --porcelain` +до ревью и сверка после — дерево должно остаться нетронутым. Кавеат: сеть +под workspace-write по умолчанию закрыта; что поиск/документация проходят +эскалацией через авто-аппрув — рабочая гипотеза, боем не обкатана +(см. handoff 2026-07-10). + +В промпте — формат «только индекс находок» (SEVERITY, файл:строка, суть, +как проверить), явная строка VERDICT и поощрение безопасных эмпирических +проверок вне репо (воспроизвести краевой случай, свериться с +первоисточником) — вердикт заметно твёрже (эмпирика 2026-07-09). ## Ветка «триаж/починка» (тем же тредом, что писал код) @@ -80,7 +101,8 @@ cat "$SCRATCH/fix-prompt.md" | codex exec resume --json \ Для запуска раннер не нужен (см. сквозные правила) — он нужен, когда сырой результат шумный и его стоит провалидировать или сжать до индекса, прежде -чем показывать оркестратору. Тогда general-purpose-субагенту отдай +чем показывать оркестратору. Тогда раннеру (`fast-worker`; нет в +репозитории — `general-purpose`) отдай **готовую команду** и правила разбора — не постановку задачи: тонкий агент, получив постановку, реализует её сам (казус форвардера, lessons 2026-07-06). Свой 10-минутный потолок на синхронный Bash раннер обходит отслеживаемым diff --git a/agents/.agents/skills/claude-subagent-playbook/references/lessons.md b/agents/.agents/skills/claude-subagent-playbook/references/lessons.md index ee19b80..bc85385 100644 --- a/agents/.agents/skills/claude-subagent-playbook/references/lessons.md +++ b/agents/.agents/skills/claude-subagent-playbook/references/lessons.md @@ -2,7 +2,9 @@ Датированные факты: что поймал каждый этап конвейера, казусы, цифры. Дописывай после каждого прогона — это и есть «выжимка опыта», ради которой -скилл существует. +скилл существует. Журнал накопительный, поэтому дистиллируй: когда урок +поглощён SKILL.md или references, сжимай его запись здесь до строки-факта +(дата, что случилось, куда поглощено) — иначе файл растёт бесконечно. ## 2026-07-06 — t2-ml-forecast, задача 05 «полировка витрины под демо» @@ -126,7 +128,8 @@ JSONL (19 command_execution: полный pytest, узкий прогон, usage работу. Приём «вердикт без находок — проверь лог» вписан в SKILL.md (этап 4) и codex-exec.md. -**Закрыты пункты «не проверено боем» из handoff 06:** фолбэк-ревьюер +**Закрыты давние пункты «не проверено боем» (записка 2026-07-06, ныне +поглощена):** фолбэк-ревьюер general-purpose на Опусе — обкатан дважды (постановка и код), работает; триаж исполнителем — `codex exec resume` по явному id закрыл 3/3 находки, лишнего не тронул; узкий rerun ревьюера — SendMessage поднял того же @@ -139,3 +142,15 @@ general-purpose на Опусе — обкатан дважды (постано **Цифры:** ревью постановки ~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-песочницей для поиска).