From 357896faaaa029f208e80f6c53eb781b796d299c Mon Sep 17 00:00:00 2001 From: Dmitry Dementiev Date: Sun, 26 Jul 2026 19:06:01 +0300 Subject: [PATCH] =?UTF-8?q?docs(skills):=20=D1=8D=D1=84=D1=84=D0=BE=D1=80?= =?UTF-8?q?=D1=82-=D0=BA=D0=B0=D1=80=D1=82=D0=B0=20=D1=81=D1=83=D0=B1?= =?UTF-8?q?=D0=B0=D0=B3=D0=B5=D0=BD=D1=82=D0=BE=D0=B2=20=D0=BF=D0=B5=D1=80?= =?UTF-8?q?=D0=B5=D1=81=D1=87=D0=B8=D1=82=D0=B0=D0=BD=D0=B0=20=D0=BF=D0=BE?= =?UTF-8?q?=D0=B4=20Opus=205?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - скилл писался под Opus 4.8; у Opus 5 усилия распределены иначе, high — верхняя рабочая ступень, xhigh дефолтить смысла нет. - Что: - карта в SKILL.md сдвинута на ступень вниз (high — ревью постановок, medium — слепое ревью и узкие перепроверки, default — механика), нижняя граница ревью опущена с high до medium. - добавлены оговорки: неравномерность сдвига, deep-reasoner остаётся на high, механика едет на Sonnet и эффорт там не крутится. - в lessons.md записано решение 2026-07-26, помечена как пересмотренная запись 2026-07-21 и заведён открытый вопрос: чем координатор вообще выставляет effort (у Agent-тула такого параметра нет). - пункт про вспомогательных субагентов переписан активно: нет в репо — предложить создать по заготовке и работать ими. - Проверка: - git diff HEAD~1 -- agents/.agents/skills/claude-subagent-playbook/; сверить, что xhigh в SKILL.md больше не упоминается. Co-Authored-By: Claude Opus 5 --- .../skills/claude-subagent-playbook/SKILL.md | 32 +++++++--- .../references/lessons.md | 61 ++++++++++++++++++- 2 files changed, 83 insertions(+), 10 deletions(-) diff --git a/agents/.agents/skills/claude-subagent-playbook/SKILL.md b/agents/.agents/skills/claude-subagent-playbook/SKILL.md index 4d9b52e..5a2439b 100644 --- a/agents/.agents/skills/claude-subagent-playbook/SKILL.md +++ b/agents/.agents/skills/claude-subagent-playbook/SKILL.md @@ -78,8 +78,12 @@ description: >- дерева веди последовательно одним владельцем. - **Вспомогательные Claude-субагенты** для попутного делегирования: глубокое рассуждение — `deep-reasoner`, механика с шумным выводом — `fast-worker`. - Они репо-локальные; нет в репозитории — определения для создания в - [references/claude-agents.md](references/claude-agents.md). + Они репо-локальные; нет в репозитории — **предложи пользователю создать** + по заготовкам из + [references/claude-agents.md](references/claude-agents.md) и дальше + работай ими, а не разовым `general-purpose`: определение — одноразовая + цена, зато модель и effort заданы явно и переживают сессию. Молча не + заводить: `.claude/agents/` — территория пользователя. - **Модель Claude-субагентов задавай явно**: Опус — рассуждения и ревью, Sonnet — механика. Без явной модели субагент наследует Fable, чьи лимиты самые дорогие — держи их для оркестрации (у `deep-reasoner`/`fast-worker` @@ -88,13 +92,23 @@ description: >- после двух слабых результатов подряд — свежий более сильный агент вместо переноса неудачного контекста. - **Effort Claude-субагентов тоже задавай явно** (решение пользователя - 2026-07-21), по цене *тихой* ошибки этапа, не по сложности: `xhigh` — - ревью постановок и планов (дефект каскадирует: отравляет реализацию, оба - ревью и триаж — казус CODE-1 в xray-proxy 04); `high` — слепое ревью - (последняя линия обороны своей линзы, пропуск тихий); `medium`/default — - узкие перепроверки и механика (за ними приёмка оркестратора, ошибка - громкая). Ревью ниже high не опускать даже при двух ревьюерах: линзы - разные, избыточность — не дублирование. Внутри одного агента effort между + 2026-07-26 под Opus 5: усилия распределены иначе, чем у 4.8, — `high` + верхняя рабочая ступень, `xhigh` не дефолтить; условно `high` у Opus 5 + ближе к прежнему `xhigh`, `medium` — чуть ниже прежнего `high`, то есть + ступени сдвинулись неравномерно), по цене *тихой* ошибки этапа, не по + сложности: `high` — ревью постановок и планов (дефект каскадирует: + отравляет реализацию, оба ревью и триаж); `medium` — слепое ревью + (последняя линия обороны своей линзы, пропуск тихий) и узкие + перепроверки; default — механика (за ней приёмка оркестратора, ошибка + громкая; она и так идёт Sonnet-агентом — эффорт там не крутить вовсе). + Ревью ниже medium не опускать даже при двух ревьюерах: линзы разные, + избыточность — не дублирование. У `deep-reasoner` `high` пришит + фронтматтером и понижению не подлежит: он специалист по рассуждению, а + в роли фолбэк-ревьюера просто приедет ступенью выше карты — карта + задаёт минимум для роли, а не ограничение для агента. Ступеней меньше, + чем этапов, — это нормально: эффорт задаёт лишь глубину поверх + выбранной модели, тонкая настройка идёт промптом. Внутри одного агента + effort между резюмами не менять (у Claude смена thinking-конфига сбрасывает messages-ярус кэша; про effort не задокументировано — не рисковать). Ограничение любого эффорта: от уверенной выдумки внешних фактов (форматы diff --git a/agents/.agents/skills/claude-subagent-playbook/references/lessons.md b/agents/.agents/skills/claude-subagent-playbook/references/lessons.md index e9a3c56..63727da 100644 --- a/agents/.agents/skills/claude-subagent-playbook/references/lessons.md +++ b/agents/.agents/skills/claude-subagent-playbook/references/lessons.md @@ -261,7 +261,8 @@ git (`git show HEAD:path`) + повторным наложением право SKILL.md — эффорт-карта Claude-субагентов): реализация по отревьюированному тикету → medium допустим; Claude-субагентам effort задавать явно — xhigh постановки/планы, high слепое ревью, medium - перепроверки; ревью ниже high не опускать. + перепроверки; ревью ниже high не опускать. **Пересмотрено 2026-07-26** + (см. ниже) — карта сдвинута на ступень вниз под Opus 5. ## Прогон 2026-07-21: yantar-dags, предразметка — этап постановки @@ -347,3 +348,61 @@ claude-reviews-code-meaningfulness): 1) в линзу Claude-ревьюера д Попутно: образец заражает — исполнитель добавлял прозаические тесты, следуя уже существующим в файле (жанр «тест на фразу README» там был до него). Чистка легаси-жанра — отдельным issue (#24), не в ветке фичи. + +## Решение пользователя 2026-07-26: эффорт-карта Claude-субагентов под Opus 5 + +Скилл писался под Opus 4.8; у Opus 5 усилия распределены иначе, и `high` +стал верхней рабочей ступенью — выше неё смысл появляется редко. Карта в +SKILL.md сдвинута на ступень вниз: `high` — ревью постановок и планов +(было `xhigh`); `medium` — слепое ревью (было `high`) и узкие +перепроверки; default — механика. Нижняя граница ревью опущена с `high` +до `medium`. + +Сдвиг неравномерный (оценка пользователя, заведомо условная): `high` у +Opus 5 по отдаче ближе к прежнему `xhigh`, а `medium` — чуть ниже +прежнего `high`. То есть на ревью постановок потеря близка к нулю, а на +слепом ревью просадка есть, но меньше, чем выглядит по названию ступени. + +Следствие: ступеней теперь меньше, чем этапов, — слепое ревью и узкие +перепроверки делят `medium`. Это осознанно: эффорт задаёт лишь потолок +глубины поверх выбранной модели, тонкая настройка идёт промптом. + +`deep-reasoner` остаётся на `high` (решение пользователя): понижать +специалиста по рассуждению не надо. В роли фолбэк-ревьюера он приедет +ступенью выше карты — принято осознанно, карта задаёт минимум для роли, +а не потолок для агента. + +Оси не путать: механика едет на Sonnet (`fast-worker`, модель пришита в +определении), и ярус «default» там означает «эффорт не крутить», а не +дешёвый режим Опуса. + +Не изменилось: эффорт Codex (`references/codex-exec.md`) — там своя +шкала, по сложности; запрет менять effort между резюмами одного треда; и +главный предел — от уверенной выдумки внешних фактов не страхует никакой +эффорт (казус CODE-1). + +### Открытый вопрос 2026-07-26: чем координатор выставляет effort субагенту + +Правило «effort задавай явно» предполагает, что ручка у оркестратора +есть. По схеме Agent-тула в текущем харнессе её нет: параметры вызова — +`model`, `subagent_type`, `isolation`, `run_in_background`, но не +`effort`. Достоверно ступень задаётся двумя путями: фронтматтером в +определении агента (`effort:` — как у `deep-reasoner`) и `opts.effort` в +скрипте Workflow. Значит для разового вызова без определения — вариант +«скептический `general-purpose`» из SKILL.md, этап 4 — карта +нереализуема: агент приедет на эффорте сессии. + +Обход, доступный уже сейчас (решение пользователя): нужного субагента +нет в репозитории — **предложи пользователю его создать** по заготовке +из [claude-agents.md](claude-agents.md) (в том числе роль с нужным +`effort:` во фронтматтере) и дальше работай уже им, а не разовым +`general-purpose`. Определение — одноразовая цена, ступень и модель +после него заданы явно и переживают сессию. Заводить молча не надо: +файлы в `.claude/agents/` — территория пользователя. + +Пользователь предполагал, что ручка координатору доступна, — проверить +на ближайшем прогоне. Если подтвердится, что нет, это тема рефакторинга +скилла: либо карта явно расписывается «через определение агента / через +Workflow», либо для каждой роли карты заводится определение с пришитым +эффортом (и фолбэк «скептический general-purpose» из этапа 4 уходит). +До проверки карту не переписывать — вопрос механики, не решения.