From 3e0498e2427e143ca1730ac77e733a314b0684c7 Mon Sep 17 00:00:00 2001 From: Dmitry Dementiev Date: Fri, 31 Jul 2026 17:03:23 +0300 Subject: [PATCH] =?UTF-8?q?docs(skills):=20=D0=BF=D0=BB=D0=B5=D0=B9=D0=B1?= =?UTF-8?q?=D1=83=D0=BA=20=E2=80=94=20=D1=81=D1=82=D1=80=D1=83=D0=BA=D1=82?= =?UTF-8?q?=D1=83=D1=80=D0=BD=D1=8B=D0=B9=20=D1=80=D0=B5=D1=84=D0=B0=D0=BA?= =?UTF-8?q?=D1=82=D0=BE=D1=80=D0=B8=D0=BD=D0=B3:=20=D0=BE=D1=81=D1=8C=20?= =?UTF-8?q?=D0=B2=D0=BA=D1=83=D1=81=D0=B0,=20=D0=B1=D1=80=D0=B8=D1=84?= =?UTF-8?q?=D1=8B,=20=D0=B4=D0=B2=D0=B0=20=D0=9E=D0=BF=D1=83=D1=81-=D0=B0?= =?UTF-8?q?=D0=B3=D0=B5=D0=BD=D1=82=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Зачем. Отдельный осознанный заход, закрывающий открытые вопросы 2026-07-26 и 2026-07-31: две ручки выбора (модель, эффорт) были про силу, вкус ими не выражался; константы линий дрейфовали через перепечатку; правила координации прогона #18 жили только в журнале; у Agent-тула нет ручки effort — карта была нереализуема разовым вызовом. Что. - Третья ось выбора — вкус: references/model-matrix.md (матрица Тео с поправкой пользователя под gpt-5.6-sol/Opus 5); разрез по подзадачам на этапе 1, сначала вкусовая часть. - «Родословная» разведена на семейство (классы находок) и свежесть (независимость); линия дефектов — по различию, уместности — по умению. - Ступень эффорта выбирается выбором агента: определений столько, сколько пар (модель, ступень) — deep-reasoner (high), craftsman (medium, исполнение брифов: реализация/ревью/перепроверки; поглотил adversarial-reviewer), fast-worker; карта с обоснованиями — SSOT в claude-agents.md. - Константы — файлами в prompts/: line-task/code/rev, self-review; line-taste — вкусовая линза с 12 запахами Фаулера из /code-review. - Правила #18 — в механизм: инкрементальная запись индекса, глубина один и проверка среды в мандате, признак жизни / другой путь вердикта замене / среда своими глазами в «Сбоях», стенд одной линии, stdin фона. - lessons дистиллирован (586→533), handoff захода — в handoffs/. Проверка. Слепое ревью Опусом по writing-great-skills: CHANGES_REQUIRED (7 MAJOR, 17 MINOR, 3 NIT) — все закрыты или отклонены с доводом в lessons; ссылки пакета проверены скриптом, битых нет. Боевой прогон новой структуры — следующим заходом (чек-лист в handoff). Co-Authored-By: Claude Fable 5 --- .../skills/claude-subagent-playbook/SKILL.md | 241 ++++++++++-------- ...731-refaktoring-tri-osi-craftsman-brify.md | 69 +++++ .../references/claude-agents.md | 79 +++++- .../references/lessons.md | 134 ++++------ .../references/model-matrix.md | 45 ++++ .../references/prompt-templates.md | 96 ++++--- .../references/prompts/line-code.md | 3 + .../references/prompts/line-rev.md | 5 + .../references/prompts/line-task.md | 4 + .../references/prompts/line-taste.md | 38 +++ .../references/prompts/review-boilerplate.md | 7 +- .../references/prompts/self-review.md | 4 + 12 files changed, 466 insertions(+), 259 deletions(-) create mode 100644 agents/.agents/skills/claude-subagent-playbook/handoffs/20260731-refaktoring-tri-osi-craftsman-brify.md create mode 100644 agents/.agents/skills/claude-subagent-playbook/references/model-matrix.md create mode 100644 agents/.agents/skills/claude-subagent-playbook/references/prompts/line-code.md create mode 100644 agents/.agents/skills/claude-subagent-playbook/references/prompts/line-rev.md create mode 100644 agents/.agents/skills/claude-subagent-playbook/references/prompts/line-task.md create mode 100644 agents/.agents/skills/claude-subagent-playbook/references/prompts/line-taste.md create mode 100644 agents/.agents/skills/claude-subagent-playbook/references/prompts/self-review.md diff --git a/agents/.agents/skills/claude-subagent-playbook/SKILL.md b/agents/.agents/skills/claude-subagent-playbook/SKILL.md index a00137c..6b86f9b 100644 --- a/agents/.agents/skills/claude-subagent-playbook/SKILL.md +++ b/agents/.agents/skills/claude-subagent-playbook/SKILL.md @@ -1,11 +1,10 @@ --- name: claude-subagent-playbook description: >- - Конвейер одной нетривиальной задачи со стороны Claude Code: постановка → - свежий взгляд → реализация Кодексом → слепое ревью по шкале риска → - триаж → приёмка. Применяй, когда пользователь даёт issue/тикет в работу - конвейером, просит делегировать реализацию Codex или устроить - независимое ревью изменений. + Конвейер одной нетривиальной задачи со стороны Claude Code — от + постановки до приёмки через слепое ревью. Применяй, когда пользователь + даёт issue/тикет в работу конвейером, просит делегировать реализацию + Codex или устроить независимое ревью изменений. --- # Плейбук: одна задача через Кодекса и слепое ревью @@ -43,76 +42,67 @@ description: >- существующий тред. Механику (правки файлов по готовым решениям, скрипты, вёрстку) — `fast-worker`'у: твоё в них только короткий список решений. **Индекс — у тебя, полезная нагрузка — файлами между - агентами**: вердикты, отчёты и промпты живут в `$SCRATCH` (обменный - temp-каталог прогона — скретчпад сессии или `mktemp -d`; детали — в - [references/prompt-templates.md](references/prompt-templates.md)) и - ведутся **на английском** — проект их не хранит, а кириллица в 1,5–2 - раза дороже по токенам; русский — только тому, что уходит в репозиторий - и пользователю. Читай их один раз, дальше передавай путями и + агентами**: вердикты, отчёты и промпты живут в `$SCRATCH` и ведутся + **на английском**; русский — только тому, что уходит в репозиторий и + пользователю (конвенция каталога и языковой хвост — в + [references/prompt-templates.md](references/prompt-templates.md)). Читай их один раз, дальше передавай путями и конкатенацией (`cat`), не переписывай Write'ом — каждое переписывание дублирует контент в твоём контексте. SendMessage возвращает эхом весь текст сообщения — teammate'у шли короткое (вердикт, путь, вопрос), длинное — файлом, который он прочтёт сам. -- **Codex** — реализация кода. У пользователя лимиты Codex больше, код он - пишет в целом лучше, но верхнеуровнево планирует хуже — поэтому - декомпозиция и постановка остаются у тебя. Механика вызова — - [references/codex-exec.md](references/codex-exec.md). -- **Ревьюеры** — до двух (шкалы — этапы 2 и 4), **разных родословных**, слепые - друг к другу: - Claude-субагент (`adversarial-reviewer`; нет в среде — `deep-reasoner` - или скептический `general-purpose`) и Codex **свежим тредом**, не тем, - что писал код. - Разные родословные ловят разные классы находок (пересечение в прогонах — - от нуля до пары тем). Обоим — руки: тесты, гипотезы, поиск, +- **Исполнители** — двое; разрез между ними задаёт этап 1 по осям + цена/интеллект/вкус + ([references/model-matrix.md](references/model-matrix.md)). `craftsman` + (Опус) — вкусовая часть; Codex — техническая: лимиты у него почти + бесплатные, код пишет отлично, а верхнеуровнево планирует хуже — + декомпозиция и постановка при любом разрезе остаются у тебя. Механика + вызова Codex — [references/codex-exec.md](references/codex-exec.md). +- **Ревьюеры** — до двух линий (шкалы — этапы 2 и 4), слепых друг к + другу. Назначение — по двум разным основаниям, это разные механизмы: + **свежая сессия** (обязательна каждой линии; не форк твоей истории — + форк убивает независимость) отвязывает от рассуждений автора; + **семейство** (Claude/GPT) определяет, какие + классы находок линия вообще видит (пересечение линий в прогонах — от + нуля до пары тем). Линию дефектов веди семейством, отличным от + исполнителя; линию уместности — моделью со вкусом, даже когда она из + семейства автора: плата — общая слепота семейства проходит дважды, её + гасят свежесть и другая линза, а при высокой цене ошибки уместность + отдай третьей модели. Claude-линии — по карте: ревью постановок + (high) штатно ведёт `deep-reasoner`, слепое ревью кода (medium) — + `craftsman` свежей сессией (нет в репозитории — предложи создать по + заготовке из + [references/claude-agents.md](references/claude-agents.md); временный + фолбэк — `deep-reasoner` ступенью выше). Codex-линия — **свежим + тредом**, не тем, что писал код. Обоим — руки: тесты, гипотезы, поиск, документация, первоисточники; запрет менять исходники и окружение — **мандатом в промпте, не урезанием песочницы** (рецепт и подстраховка — [references/codex-exec.md](references/codex-exec.md)). -- **Свежесть**: ревьюеров запускай свежими сессиями, без форка своей истории - (форк тратит токены и убивает независимость). Повторную проверку точечных - правок — **тем же** ревьюером узким вопросом «закрывают ли правки твои - находки», не полным обходом. +- **Перепроверка**: повторную проверку точечных правок — **тем же** + ревьюером узким вопросом «закрывают ли правки твои находки», не полным + обходом. - **Пределы параллельности**: глубина один — субагенты не разворачивают собственных субагентов; параллельно только работа без конфликтующих входов и общего изменяемого состояния; второй обзор добавляй ради - отдельной линии, а не ради свободного слота; реализацию и починку одного - дерева веди последовательно одним владельцем. -- **Вспомогательные Claude-субагенты** для попутного делегирования: глубокое - рассуждение — `deep-reasoner`, механика с шумным выводом — `fast-worker`. - Они репо-локальные; нет в репозитории — **предложи пользователю создать** - по заготовкам из - [references/claude-agents.md](references/claude-agents.md) и дальше - работай ими, а не разовым `general-purpose`: определение — одноразовая - цена, зато модель и effort заданы явно и переживают сессию. Молча не - заводить: `.claude/agents/` — территория пользователя. -- **Модель Claude-субагентов задавай явно**: Опус — рассуждения и ревью, - Sonnet — механика. Без явной модели субагент наследует Fable, чьи лимиты - самые дорогие — держи их для оркестрации (у `deep-reasoner`/`fast-worker` - модели пришиты в определениях). Две ручки эскалации: не хватило - глубины — повышай effort; не хватает качества суждения — повышай модель; - после двух слабых результатов подряд — свежий более сильный агент вместо - переноса неудачного контекста. -- **Effort Claude-субагентов тоже задавай явно** (решение пользователя - 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 не задокументировано — не рисковать). - Ограничение любого эффорта: от уверенной выдумки внешних фактов (форматы - артефактов, версии) не страхует — факты проверять отдельно. + отдельной линии, а не ради свободного слота; у одного дерева один + владелец — параллельная запись только разными worktree со швом по + непересекающимся файлам. +- **Субагенты — по готовым определениям** из + [references/claude-agents.md](references/claude-agents.md) + (`deep-reasoner` — рассуждения и ревью постановок; `craftsman` — + исполнение брифов: вкусовая реализация, слепое ревью, перепроверки; + `fast-worker` — механика): + ступень эффорта не задаётся в вызове (у Agent-тула такой ручки нет) — + её **выбирают выбором агента**: модель и effort пришиты фронтматтером; + разовый `general-purpose` приедет на эффорте сессии, а без явной + модели субагент наследует Fable, чьи лимиты держи для оркестрации. Карта «роль → модель и + ступень» и её основания — там же. Нет определений в репозитории — + **предложи пользователю создать** (молча не заводить: + `.claude/agents/` — территория пользователя). Эскалация: не хватило + глубины — выше effort, не хватает суждения — выше модель; после двух + слабых результатов подряд — свежий более сильный агент, не перенос + неудачного контекста. Внутри одного агента effort между резюмами не + менять (сбрасывает messages-ярус кэша). Никакой эффорт не страхует от + уверенной выдумки внешних фактов — проверяй первоисточником. ## Конвейер @@ -126,7 +116,14 @@ description: >- свежий контекст; рёбра блокировок явные. Мерка самодостаточности — тикет можно взять в отдельной сессии вообще без общего контекста. Сверка разбиения с пользователем внутри `/to-tickets` — уже первая - линия ревью постановки, засчитай её на этапе 2. Формат и место — по + линия ревью постановки, засчитай её на этапе 2. Здесь же — разрез + исполнителей по подзадачам (ось вкуса — + [references/model-matrix.md](references/model-matrix.md)): что человек + будет читать и разбирать — вкусовой части (Опус), руки — Кодексу. + Сначала вкусовая часть: она задаёт форму, имена и границы, под + которые механическая подстраивается, — обратный порядок даёт ретрофит; + параллелить части — только в рамках «Пределов параллельности». + Формат и место — по конвенции репозитория (например, `.scratch//issues/` или трекер из `docs/agents/`). Не хватает фактуры по внешним библиотекам/API — сначала `/research` и Context7 MCP, @@ -144,7 +141,7 @@ description: >- прочтёт сам), после правок — узкая проверка дельты тем же ревьюером. Шкала: тикет-срез по уже принятой спеке, без решений сверх неё — внешнюю линию пропусти, причину назови одной фразой; обычный тикет — - адверсарный ревьюер без + ревьюер роли постановок (`deep-reasoner`) без твоего контекста проверяет задачу против кода: фактические ошибки, скрытые решения-«однострочники», недостающие критерии — ловит блокеры, которые исполнитель молча реализовал бы. Постановка @@ -152,26 +149,30 @@ description: >- цена ошибки высока — сделай ревью двойным и слепым, как для кода: вторая линия — Codex свежим тредом с явной рамкой «ревьюируй постановку, не реализацию; детали реализации — только если постановка молча предрешает - решение» (без рамки зарывается в детали). Родословные и тут ловят разное: + решение» (без рамки зарывается в детали). Семейства и тут ловят разное: Codex — уровень требований (недостающие критерии, наблюдаемость, «формально отчитаться можно»), Клод — механику кода (нереализуемые формулировки, мёртвые стабы). Этап закрыт, когда каждая находка внесена в задачу **решением** или письменно отклонена — «пусть решит исполнитель» решением не считается; при пропуске внешней линии — когда причина пропуска названа. -3. **Реализация Кодексом.** Промпт: «задача самодостаточна, следуй буквально, - коммит не делай». Запуск — прямым `codex exec` **фоновым Bash - оркестратора**: шум — редиректами в файлы, в контекст читается только - файл отчёта, харнесс будит по завершении; рецепты, ветки и ловушки — +3. **Реализация — по разрезу этапа 1.** Вкусовую часть пишет + `craftsman` свежей сессией, техническую — Codex; у обоих один и тот же + файл задачи, промпт — скелет из + [references/prompt-templates.md](references/prompt-templates.md) + (мандат «следуй буквально, коммит не делай» уже в нём). Запуск + Codex — прямым `codex exec` **фоновым Bash оркестратора**: шум — + редиректами в файлы, в контекст читается только файл отчёта, харнесс + будит по завершении; рецепты, ветки и ловушки — [references/codex-exec.md](references/codex-exec.md). - Один писатель в дереве: пока Codex пишет — никто больше (казус с - форвардером — в [references/lessons.md](references/lessons.md)). + Пока исполнитель пишет — дерево его («Пределы параллельности»; казус + форвардера — в [references/lessons.md](references/lessons.md)). После отчёта — **саморевью тем же тредом** (resume, effort medium; - заготовка — [references/prompt-templates.md](references/prompt-templates.md)): + файл готов в `prompts/`): исполнитель проходит свой diff против критериев как ревьюер и сам чинит найденное, тебе — одна строка «found N, fixed N». Дёшево и снимает часть - находок до внешних глаз. Готово, когда Codex вернул отчёт, саморевью - пройдено, в дереве нет правок, которых он не называл, + находок до внешних глаз. Готово, когда каждый исполнитель вернул отчёт + и саморевью, в дереве нет правок, которых отчёты не называли, и дешёвая сквозная проверка (если она есть в репо) зелёная: гонял её исполнитель по промпту, а если ему она недоступна (docker, стенд) — ты, **до запуска ревьюеров**: иначе ревью уйдёт на код, который сквозной @@ -180,35 +181,34 @@ description: >- дальше по цене ошибки: **тривиальное** изменение (до-правка по готовому диагнозу, механика, целиком накрытое детерминированной проверкой) — внешних линий не гоняй, причину пропуска назови одной фразой; - **простое, но с заметной ценой ошибки** — один ревьюер другой - родословной, чем исполнитель (у нас — Клод при Codex-исполнителе; - одиночную линию выбирай по родословной, не по цене); **обычное и - сложнее** — два слепых ревью параллельно с разведёнными фокусами: одна - линия «по задаче» (соответствие постановке, критериям, границам и - уместность решения — точные слова в заготовке линии), другая - «по коду» (корректность, инварианты, регрессии, честность тестов) — - разность семейств даёт разные находки, разность фокусов страхует от - дублирования, когда семейства сходятся. Промпт — **общий блок один на - обе линии** плюс крошечный файл линии (линза и префикс ID); собираются - два файла с разными путями (скелет и обёртки вызова — - [references/prompt-templates.md](references/prompt-templates.md)): Codex - получает свой через stdin, Клод-субагенту в prompt — короткая обёртка - «прочитай файл X и выполни; индекс — в файл Y» (не дублируй текст - промпта в параметре — это второй полный экземпляр в твоём контексте). - Содержание: путь к задаче-файлу + фокус и префикс ID линии; мандат, - формат индекса с устойчивыми ID и поощрение эмпирических проверок уже - в готовом boilerplate. Друг про - друга не знают, твои выводы им не пересказывай. Вердикты — файлами с - **разными путями**: у Codex это его `-o`-отчёт, Клод-ревьюеру путь и - финальный акт (SendMessage только со строкой VERDICT, счётчиками и - путём) задаёт готовая обёртка из шаблонов; его idle-уведомления - результата не содержат, не жди из них ничего. После - ревью сверь дерево (`git status`). Клод-ревьюеру можно поручить смотреть - артефакты (картинки из ноутбука). Этап закрыт, когда вердикты всех + **простое, но с заметной ценой ошибки** — один ревьюер семейства, + отличного от исполнителя (линза — `line-rev`, обе в одной); **обычное + и сложнее** — два слепых ревью параллельно с разведёнными фокусами: + линию «по задаче» (`line-task` + `line-taste`: постановка, критерии, + границы, уместность и вкус) ведёт модель со вкусом, линию «по коду» + (`line-code`: корректность, инварианты, регрессии, честность + тестов) — семейство, отличное от исполнителя (основания — «Роли»). + Разность семейств даёт разные находки, разность фокусов страхует от + дублирования, когда семейства сходятся; артефакты-картинки (ноутбуки, + графики) видит только Claude-линия — учитывай при назначении. Сборка + промптов и обёртки вызова — целиком в + [references/prompt-templates.md](references/prompt-templates.md); два + правила при этом твои: пути промптов и вердиктов у линий разные, и + текст промпта в параметр вызова не дублируй — это второй полный + экземпляр в твоём контексте. Друг про друга линии не знают, твои + выводы им не пересказывай. Живой стенд двум линиям не давай: их + стражи гасят службы и роняют таблицы друг другу — стенд получает одна + линия, второй — явный запрет ломающих команд. Idle-уведомления + Клод-ревьюера результата не содержат — итог придёт строкой VERDICT и + файлом по пути из обёртки. После + ревью сверь дерево (`git status`). Этап закрыт, когда вердикты всех выбранных линий у тебя индексами и дерево нетронуто; вердикт без единой находки засчитывай только после проверки его лога — работа, не отписка (приём — в [references/codex-exec.md](references/codex-exec.md)). -5. **Синтез и триаж.** Сведи вердикты по индексам: пересечения, противоречия. +5. **Синтез и триаж.** Сведи вердикты по индексам: пересечения, + противоречия. Линии не сливай в один ранжир: оси разведены намеренно, + уверенный вердикт одной (APPROVED без находок) не закрывает находки + другой. Пофиндинговый триаж — у **исполнителя**, не у тебя (правило `/claude-team-review` и `/coordinator-loop`: судит тот, у кого контекст кода): перешли Codex индекс находок **дословно**, он чинит или @@ -221,10 +221,10 @@ description: >- NEEDS_DECISION`; два последних — решения твоего уровня, исполнитель возвращает их тебе, а не решает молча. Резолюции и доводы он пишет в свой файл отчёта, **тикет в триаже не правится**: правка тикета эхом - вкатывает весь его текст в твой контекст (пожиратель №1 прогона задачи - 13), выжимку в тикет перенесёт fast-worker на финале. Свои замечания к + вкатывает весь его текст в твой контекст — главный пожиратель + прогонов; выжимку в тикет перенесёт fast-worker на финале. Свои замечания к триажу — только шапкой. Ты судишь уровнем задачи: принять риск / вне - скоупа. Повторная проверка — узкая (см. «Свежесть»); её промпт не + скоупа. Повторная проверка — узкая (см. «Перепроверка»); её промпт не пересказывает резолюции — ссылается на файл отчёта исполнителя. Третий круг триажа — точка вмешательства: доложи пользователю, почему процесс не сходится и что меняешь (постановку, модель/effort, @@ -241,7 +241,9 @@ description: >- **своими глазами** (счётчик тестов, картинки, прогон CLI) — ревью не заменяет твою приёмку. Команды нового приёмочного сценария проверь на живом объекте до полного прогона; сложные вставки собирай файлами, не - экранированием. Чекбоксы, статус и выжимку резолюций в тикет + экранированием; фоновому запуску закрывай stdin (`< /dev/null`) — + команда, дочитывающая ввод, из терминала зелёная, а в фоне виснет + навсегда. Чекбоксы, статус и выжимку резолюций в тикет переносит fast-worker из файла отчёта исполнителя (не твой Write). Коммит — по `/conventional-commits`, пользователю — выжимка: вердикты, что принято/отклонено, что осталось — плюс короткая саморефлексия: что @@ -254,9 +256,9 @@ description: >- В отличие от `/coordinator-loop`, здесь пользователь рядом: на границах этапов давай в чат карту прогресса в 4–7 строк обычными словами -(✅ сделано / ▶ идёт / ⬜ дальше); термины плейбука — только с расшифровкой -(урок 2026-07-13: телеграфные статусы в терминах этапов потеряли -пользователя). Карта дополняет содержательную сводку, не заменяет её. +(✅ сделано / ▶ идёт / ⬜ дальше); термины плейбука — только с +расшифровкой: телеграфные статусы в терминах этапов теряют пользователя. +Карта дополняет содержательную сводку, не заменяет её. Решения по скоупу оставляй пользователю. Фоновые этапы будят тебя сами — не поллинг вручную, а отслеживаемые фоновые процессы + уведомления (механика — [references/codex-exec.md](references/codex-exec.md)). @@ -271,7 +273,13 @@ teammate-субагентов — шум, а не событие: не докл - Нет ожидаемого файла или отчёта: один запрос короткого итога в тот же тред; повторная тишина — свежий агент от сохранённых артефактов, владение - деревом — только после остановки прежнего владельца. + деревом — только после остановки прежнего владельца. Молчание — не + смерть: признак жизни — уведомление харнесса, не размер транскрипта; + замене давай **другой** путь вердикта — дубль на тот же путь затирает + находки живого. +- Отчёт агента о состоянии среды — не факт: перед приёмкой посмотри стенд + своими глазами (`docker compose ps -a`; без `-a` погашенные службы + невидимы). - Длинный рассказ пришёл сообщением: попроси сводку с путём к файлу, рассказ дальше не переноси. - Два писателя пересеклись в дереве: стоп обоим, назначь одного владельца, @@ -287,7 +295,10 @@ teammate-субагентов — шум, а не событие: не докл словарь (индекс, свежие сессии, две ручки стоимости) — общий. - `/claude-team-review` — ревью-петля, где лид сам чинит код (живёт отдельным репозиторием, в среде может быть не подключён). -- `/adversarial-review` — разовое адверсарное ревью Кодексом. +- `/adversarial-review` — разовое адверсарное ревью Кодексом (в среде + может быть не подключён). +- `codex-subagent-playbook` — близнец этого плейбука для координатора на + стороне Codex; скрыт от автовызова, зови по имени. - `/to-tickets` — разбиение на тикеты-срезы с рёбрами блокировок (этап 1); его сверка разбиения с пользователем — первая линия ревью постановки. - `/tdd` — дисциплина test-first: для задач-мелочей, которые делаешь сам, @@ -305,8 +316,12 @@ teammate-субагентов — шум, а не событие: не докл промптов: готовые boilerplate-файлы в `references/prompts/` подшиваются `cat`'ом из каталога скилла, Write'ом пишутся только параметрические блоки. +- [references/model-matrix.md](references/model-matrix.md) — оси + цена/интеллект/вкус: матрица моделей и правила применения (разрез + этапа 1, назначение линий этапа 4). - [references/lessons.md](references/lessons.md) — датированная эмпирика прогонов: что поймал каждый этап, казусы, цифры. - [references/claude-agents.md](references/claude-agents.md) — определения - репо-локальных субагентов `deep-reasoner`/`fast-worker` и конструкция + репо-локальных субагентов (`deep-reasoner`, `craftsman`, + `fast-worker`), карта «роль → модель и ступень» и конструкция оркестрации из CLAUDE.md — воссоздать в новом репозитории. diff --git a/agents/.agents/skills/claude-subagent-playbook/handoffs/20260731-refaktoring-tri-osi-craftsman-brify.md b/agents/.agents/skills/claude-subagent-playbook/handoffs/20260731-refaktoring-tri-osi-craftsman-brify.md new file mode 100644 index 0000000..51768e1 --- /dev/null +++ b/agents/.agents/skills/claude-subagent-playbook/handoffs/20260731-refaktoring-tri-osi-craftsman-brify.md @@ -0,0 +1,69 @@ +# Handoff разработки скилла: структурный рефакторинг — ось вкуса, брифы, два Опус-агента + +Дата: 2026-07-31. Контекст: не боевой прогон, а отдельный осознанный +заход на рефакторинг (решение пользователя от 2026-07-31 в lessons) — +закрыты все открытые вопросы, накопленные с 2026-07-26. Сессия шла под +`/writing-great-skills`; правки прошли слепое ревью Опусом по тому же +фреймворку (CHANGES_REQUIRED: 7 MAJOR, 17 MINOR, 3 NIT — закрыто, два +отклонения с доводами). Полный список решений и отклонений — в +`references/lessons.md`, записи «Открытый вопрос 2026-07-26 — закрыт» и +«Открытый вопрос 2026-07-31 — закрыт», здесь не дублируются. + +## Что изменилось радикально (карта для свежего агента) + +1. **Третья ось выбора исполнителя — вкус** (`references/model-matrix.md`, + матрица Тео с поправкой пользователя под gpt-5.6-sol/Opus 5). Разрез + по подзадачам на этапе 1: что читает человек — Опусу, руки — Кодексу; + сначала вкусовая часть. +2. **«Родословная» разведена на два механизма**: свежесть (независимость + от автора, обязательна каждой линии) и семейство (классы находок). + Линия дефектов — по различию семейства, линия уместности — по умению. +3. **Ступень эффорта выбирается выбором агента** (у Agent-тула ручки + effort нет — проверено по схеме). Определений ровно столько, сколько + пар (модель, ступень) в карте: `deep-reasoner` (opus/high — рассуждения + и ревью постановок, штатно), `craftsman` (opus/medium — исполнение + брифов: вкусовая реализация, слепое ревью, перепроверки), + `fast-worker` (sonnet — механика). `adversarial-reviewer` слит в + `craftsman`; роли живут в бриф-файлах, не в определениях. +4. **Константы — файлами в `prompts/`**: line-task / line-code / line-rev / + line-taste (вкусовая линза + 12 запахов Фаулера из `/code-review` + Мэтта Покока) / self-review. Разрез линз — выбором файла в `cat`. +5. **Правила координации прогона #18 поглощены в механизм**: обёртка + ревьюера (инкрементальная запись), мандат (глубина один, проверка + восстановления среды), «Сбои координации» (признак жизни — + уведомление; замене — другой путь вердикта; среда — своими глазами), + этап 4 (стенд одной линии), этап 6 (stdin фона `< /dev/null`). + +## Что проверить следующим боевым прогоном (не обкатано) + +1. **`craftsman` как единый агент** для вкусовой реализации и слепого + ревью: держит ли обобщённое определение обе стойки, не путает ли + режимы. Определений в боевых репозиториях ещё нет — создавать по + свежей заготовке из `references/claude-agents.md` (старые копии + deep-reasoner/fast-worker в репозиториях живы, craftsman — новый). +2. **Разрез по вкусу на этапе 1**: первый прогон с Опус-исполнителем; + порядок «сначала вкусовая часть», шов по файлам, ревью-оси при + Опусе-авторе (линия уместности по умению — та же родословная). +3. **`$D/access-.md`** — новый механизм ограничения второй линии + при общем стенде (prompt-templates, раздел 2): синтаксис есть, боем + не проверен. +4. **Инкрементальная запись индекса** Клод-ревьюером: реально ли пишет + по ходу (правка обёртки после казуса «молчание 59 минут»). +5. Сверить близнеца `codex-subagent-playbook` после этих правок — + перенос туда ещё не делался (прошлая сверка — 2026-07-23). + +## Ориентиры + +- Вся эмпирика и датированные решения — `references/lessons.md` (хвост: + записи 2026-07-31). +- Вердикт слепого ревью правок жил в скретчпаде сессии — не сохраняйте, + всё принятое уже в файлах, отклонения задокументированы в lessons. +- Коммит этого захода — в истории dotfiles рядом с датой handoff'а. + +## Suggested skills + +- `claude-subagent-playbook` — следующий боевой прогон с чек-листом + «что проверить» выше; после прогона — дописать lessons. +- `writing-great-skills` — если прогон потребует новых структурных + правок скилла. +- `conventional-commits` — коммиты правок в dotfiles. 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 f67f50a..6d69761 100644 --- a/agents/.agents/skills/claude-subagent-playbook/references/claude-agents.md +++ b/agents/.agents/skills/claude-subagent-playbook/references/claude-agents.md @@ -1,11 +1,37 @@ # Репо-локальные Claude-субагенты и конструкция оркестрации -`deep-reasoner` и `fast-worker` — субагенты уровня репозитория -(`.claude/agents/*.md`), не глобальные. В новом репозитории их нет — проверь -`ls .claude/agents/` и при отсутствии создай файлы ниже как есть. -У ревьюера `adversarial-reviewer` репо-локального определения намеренно -нет: рабочие фолбэки — `deep-reasoner` (обкатан ревью 2026-07-12) или -`general-purpose` со скептическим промптом (см. «Роли» в SKILL.md). +`deep-reasoner`, `craftsman` и `fast-worker` — субагенты уровня +репозитория (`.claude/agents/*.md`), не глобальные. Определений ровно +столько, сколько различных пар (модель, ступень) в карте ниже: роль +задаёт бриф-файл, определение — только ступень и модель. В +новом репозитории их нет — проверь `ls .claude/agents/` и при отсутствии +предложи пользователю создать файлы ниже как есть. Определение — не +только удобство: `effort:` во фронтматтере — единственный канал, которым +оркестратор задаёт ступень эффорта субагенту (у Agent-тула ручки effort +нет — проверено по схеме 2026-07-31; в Workflow-скриптах ступень +задаётся на вызов через `opts.effort`, но конвейер ходит субагентами); +без определения агент приедет на эффорте сессии. Поэтому роль с другой +ступенью — это другой агент, а не другой вызов. + +## Карта «роль → модель и ступень» + +По цене *тихой* ошибки этапа, не по сложности (решение пользователя +2026-07-26 под Opus 5; `xhigh` не дефолтить): + +- `high` — ревью постановок и планов: `deep-reasoner`. Дефект + каскадирует — отравляет реализацию, оба ревью и триаж. +- `medium` — слепое ревью, узкие перепроверки и вкусовая реализация: + `craftsman`. Ревью — последняя линия обороны своей линзы, пропуск + тихий, ниже не опускать даже при двух ревьюерах (линзы разные, + избыточность не дублирование); ошибка реализации громкая — за ней + саморевью, оба ревью и приёмка; вкус едет с моделью, не с эффортом. +- default — механика: `fast-worker` (Sonnet). Ошибка громкая, эффорт не + крутить вовсе. + +Карта задаёт минимум для роли, не ограничение для агента: на линии +постановок `deep-reasoner` — штатный ход, а на линии слепого ревью — +временный фолбэк при отсутствии `craftsman` (обкатан ревью 2026-07-12), +там он приедет ступенью выше карты. ## Конструкция оркестрации (фрагмент CLAUDE.md репозитория) @@ -13,9 +39,11 @@ ## Orchestration workflow You (Fable) are the orchestrator. Plan, decompose, synthesize. Reasoning-heavy phases → deep-reasoner +Human-facing work (prose, interfaces, names) → craftsman Mechanical work → fast-worker -Codex (/codex:rescue --background) is a cracked engineer on par with -deep-reasoner, from a different perspective. Treat as a peer, not a reviewer. +Codex (direct `codex exec`, see claude-subagent-playbook) is a cracked +engineer from a different model family: implementer for technical work +and an independent blind review line. High-stakes decisions: task Opus + Codex on the same problem in parallel, synthesize the best of both, without showing either the other's answer. Keep your own context lean. @@ -62,6 +90,41 @@ Lead with the conclusion. Then, only if it adds value: Keep it tight. Your value is the quality of the conclusion, not its length. ``` +## `.claude/agents/craftsman.md` + +```markdown +--- +name: craftsman +description: > + Opus at medium effort for prepared briefs: tasteful implementation of + a self-contained task file, a blind review line, a narrow re-check. + The brief carries the mandate; taste — form, proportion, naming — is + why this agent and not a mechanical one. +model: opus +effort: medium +color: blue +--- + +# Craftsman + +You execute the prepared brief the orchestrator names — a self-contained +task file or an assembled review prompt. The brief carries your mandate +and output format: follow it exactly; if something seems wrong, do what +is written and flag the doubt in your report. + +## Operating stance + +- You are chosen for taste: honest names, proportionate solutions, no + artifact that does not earn its existence. Match the repository's + conventions and voice; read a neighbouring file when unsure. +- Implementing: stay inside the task's boundaries, no commits; report + files changed with a one-line "why" each, test command and counters, + checkbox status, doubts. +- Reviewing: stay blind — judge only what the brief and the repository + give you; empirical checks beat reading; findings exactly in the + index format the brief demands. +``` + ## `.claude/agents/fast-worker.md` ```markdown diff --git a/agents/.agents/skills/claude-subagent-playbook/references/lessons.md b/agents/.agents/skills/claude-subagent-playbook/references/lessons.md index 98a1c96..157ee7e 100644 --- a/agents/.agents/skills/claude-subagent-playbook/references/lessons.md +++ b/agents/.agents/skills/claude-subagent-playbook/references/lessons.md @@ -381,31 +381,14 @@ Opus 5 по отдаче ближе к прежнему `xhigh`, а `medium` — главный предел — от уверенной выдумки внешних фактов не страхует никакой эффорт (казус CODE-1). -### Открытый вопрос 2026-07-26: чем координатор выставляет effort субагенту +### Открытый вопрос 2026-07-26 — закрыт 2026-07-31 -Правило «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 уходит). -До проверки карту не переписывать — вопрос механики, не решения. +Проверено по схеме Agent-тула: ручки `effort` у него нет — ступень +задаётся только `effort:` во фронтматтере определения агента или +`opts.effort` в Workflow. Поглощено рефакторингом 2026-07-31: карта в +SKILL.md переписана на определения, в claude-agents.md добавлена +заготовка `adversarial-reviewer` (opus, medium), фолбэк «скептический +general-purpose» снят. ### 2026-07-30: классификатор авторежима блокирует `-s danger-full-access` @@ -510,9 +493,11 @@ compose down`); отдельных событий эскалации в `--json` одно из двух ревью этого не видело. Приёмка оркестратора нашла то, чего не нашли обе линии — потому что запускала иначе. -Эти четыре правила пока живут только здесь — то есть повторяют ровно тот -отказ, который диагностирует запись выше. Поглощение — в рефакторинге -(см. открытый вопрос ниже). +Поглощено рефакторингом 2026-07-31: обёртка Клод-ревьюера +(инкрементальная запись индекса), «Сбои координации» SKILL.md (признак +жизни — уведомление; замене — другой путь вердикта; среда — своими +глазами), этап 4 (стенд одной линии), этап 6 (stdin фонового запуска), +мандат review-boilerplate (глубина один; проверка восстановления среды). **Цифры:** тикет — 20 критериев, переписан дважды (двойное ревью постановки сняло невозможный критерий: ноды кластера — шарды, не реплики). Саморевью @@ -522,65 +507,38 @@ compose down`); отдельных событий эскалации в `--json` пороге 3,4 ГБ, `make smoke-cluster` 8/8 за 7 с — и одно зависание на 23 минуты до починки. -### Открытый вопрос 2026-07-31: рефакторинг заготовок линий +### Открытый вопрос 2026-07-31 — закрыт рефакторингом того же дня -Решение пользователя: скилл важный и работает регулярно, структурные -правки — отдельной осознанной работой, не походя. Накопилось на один -заход: - -- `line-task.md` / `line-code.md` не содержат ни одного `{{...}}` — это - константы, но лежат не в `prompts/`, и оркестратор перепечатывает их - Write'ом каждый прогон. Тот самый канал дрейфа, ради которого правка - 2026-07-31 и делалась. Перенести в `prompts/`, подшивать `cat`'ом; - блок `Taste:` — отдельным файлом, тогда разрез по родословной станет - выбором файла, а не пересказом границы. -- Четыре правила координации выше поглотить в механизм: два — в обёртку - вызова Клод-ревьюера (свой путь вердикта, инкрементальная запись), два — - в «Сбои координации» SKILL.md (проверка среды своими руками, стенд не - делить между линиями). -- Заодно проверить остальные заготовки на то же расхождение «константа - живёт в документации вместо `prompts/`». -- **Третья ось выбора — вкус.** Наши две ручки (эффорт, модель) обе про - силу; матрица Тео (@t3dotgg) разводит стоимость, интеллект и вкус и - заставляет выбирать исполнителя на каждую задачу, а не наследовать - дефолт. Прогон #18 показал цену: код технически безупречен и при этом - неправильной формы. Решение пользователя 2026-07-31 — то, что читает - человек, пишет модель со вкусом (в учебном репозитории это почти всё); - Кодексу — техническая работа, где его лимиты и работают на нас; ось - ревью переворачивается. **Спроси у пользователя матрицу и примеры её - применения**: числа Тео расписаны под другой набор моделей (gpt-5.5, - opus-4.8) и требуют пересчёта под наш. - Разрез идёт не по тикету, а **по подзадачам, и назначается на этапе 1**: - что человек будет читать и разбирать — Опусу, руки (сборка образа, - обвязка проверок, повторяющиеся правки) — Кодексу. Два ограничения. - Порядок: сначала вкусовая часть — она задаёт форму, имена и границы, - под которые механическая потом подстраивается; наоборот получится - ретрофит. И один писатель в дереве остаётся в силе — либо - последовательно, либо по разным worktree, шов вести по файлам, которые - не пересекаются. -- **Под «родословной» ехали два механизма.** Различие семейств нужно для - покрытия классов ошибок, свежая сессия — для независимости от рассуждений - автора. Пока они склеены, разговор о ревью упирается в ложный выбор между - независимостью и компетентностью: «линию уместности ведёт тот, кто не - писал» звучит безупречно и при Опусе-исполнителе отдаёт вкусовую линию - Кодексу, у которого вкуса нет. Разведя механизмы, получаем два основания: - линия дефектов назначается по различию, линия уместности — по умению, - даже если умеет автор. Плата — общая слепота автора и ревьюера одной - родословной проходит дважды; гасится свежей сессией и другой линзой, но - не до конца, поэтому при высокой цене ошибки линию уместности берёт - третья модель. Принято 2026-07-31 в `AGENTS.md` стенда кликстрима; в - плейбуке этап 4 и эффорт-карта всё ещё исходят из того, что пишет всегда - Codex, — при рефакторинге решить, переносить ли. -- **Принести ревьюеру набор запахов.** В `/code-review` Мэтта Покока - (`~/dotfiles/agents/.agents/skills/code-review/SKILL.md`) есть готовая - база из двенадцати запахов Фаулера, которая вклеивается ревьюеру в - промпт целиком, с оговорками «документированный стандарт репозитория - побеждает» и «каждый запах — суждение, не нарушение». Это сильнее моих - трёх самодельных примеров в блоке `Taste:`: имена вроде Speculative - Generality или Data Clumps — слова из претрейна, они поднимают целый - пласт поведения, а пересказ своими словами — нет. Наши CODE и TASK - повторяют его оси Standards и Spec, придуманные независимо; забрать - оттуда стоит и правило «находки двух осей не сливать и не - переранжировать» — оно прямо про то, как уверенный вердикт одной линии - закрывает собой другую. Показательно, что Codex-ревьюер #18 открыл этот - файл сам первой командой прогона: механизма нет, а нужда есть. +- Константы — файлами в `prompts/`: line-task, line-code, line-rev, + self-review; вкусовая линза с базой двенадцати запахов Фаулера из + `/code-review` Мэтта Покока — `line-taste.md`, разрез — выбором файла + в `cat`. Оттуда же правило «линии не сливать в один ранжир» — этап 5. +- Третья ось — вкус: матрица Тео (@t3dotgg) получена от пользователя с + поправкой под gpt-5.6-sol/Opus 5 (интеллект вырос, вкус прежний) — + references/model-matrix.md. Разрез по подзадачам на этапе 1, сначала + вкусовая часть (задаёт форму), один писатель в дереве — в силе. +- «Родословная» разведена на **семейство** (классы находок) и + **свежесть** (независимость от автора): «Роли» и этап 4 — линия + дефектов по различию семейства, линия уместности по умению (модель со + вкусом), при высокой цене ошибки уместность — третьей модели. Перенос + из `AGENTS.md` стенда кликстрима состоялся. +- Дополнение того же дня (решение пользователя): вкусовую реализацию + ведёт `craftsman` (opus, `medium`) — ошибка реализации громкая, + конвейер ловит, вкус едет с моделью, не с эффортом; `high` на + реализации не дефолтить. +- Слепое ревью рефакторинга (Опус, по writing-great-skills): + CHANGES_REQUIRED — 7 MAJOR, 17 MINOR, 3 NIT; закрыто тем же днём. + Главное: эффорт-карта с обоснованиями демотирована в claude-agents.md + (SSOT — там, где живут `effort:`), хвост «Ролей» ужат втрое, фрагмент + CLAUDE.md приведён к прямому exec и ревью-линии Codex, критерий + этапа 3 обобщён на двух исполнителей, конфликт имён этапа 2 снят + (ревьюер постановок — `deep-reasoner`). Отклонено два: порог + «вкус ≥ 7» (содержательная граница: пропускает Sonnet, отсекает Sol) и + мандат внутри определения `craftsman` (определение уезжает в + репозитории без скилла — самодостаточность важнее дедупликации). +- Позже тем же днём (решение пользователя): три Опус-определения + избыточны — определений нужно ровно столько, сколько различных пар + (модель, ступень) в карте, а роли живут в бриф-файлах. + `adversarial-reviewer` слит в `craftsman` (opus, medium — исполнение + брифов: вкусовая реализация, слепое ревью, перепроверки); упоминание + заготовки adversarial-reviewer в записях выше — история того дня. diff --git a/agents/.agents/skills/claude-subagent-playbook/references/model-matrix.md b/agents/.agents/skills/claude-subagent-playbook/references/model-matrix.md new file mode 100644 index 0000000..5570be0 --- /dev/null +++ b/agents/.agents/skills/claude-subagent-playbook/references/model-matrix.md @@ -0,0 +1,45 @@ +# Три оси выбора исполнителя: цена, интеллект, вкус + +Эффорт и модель — ручки силы; вкус ими не выражается (прогон #18: код +технически безупречен и при этом неправильной формы). Ось вкуса задаёт +разрез по подзадачам (этап 1 SKILL.md) и линию уместности ревью +(этап 4). + +Матрица — калибровка Тео (@t3dotgg) под его стек (gpt-5.5, opus-4.8), +принята пользователем 2026-07-31 с поправкой: актуальны gpt-5.6-sol и +Opus 5, оба заметно выросли в интеллекте, вкус остался примерно тем же. +Числа — порядок, не измерение. `affordability` — практическая +доступность лимитов у нас, 9 — почти бесплатно (не публичные цены); +`intelligence` — сложность работы, которую можно отдать без надзора; +`taste` — суждение в UI/UX, качестве кода, дизайне API, именах и +тексте. + +| модель | affordability | intelligence | taste | +| ----------- | ------------: | -----------: | ----: | +| gpt-5.6-sol | 9 | ~9 | 5 | +| sonnet-5 | 5 | 5 | 7 | +| opus-5 | 4 | ~8 | 8 | +| fable-5 | 2 | 9 | 9 | + +## Правила применения + +Оценки — дефолты, не запреты. Разрешение эскалировать без вопроса +действует всегда: слабая модель выдала ниже стандарта — повтори более +сильной; суди результат, не цену модели. + +- Цена решает только там, где разница в качестве неважна. Для того, что + уйдёт в продукт, интеллект и вкус важнее цены. +- Всё, что читает человек, пишет модель со вкусом ≥ 7: интерфейсы, + проза и продуктовый текст, публичные API и контракты, имена, + архитектурные решения, задающие форму системы (в учебном репозитории + это почти всё). Дефолт вкусовой части — Опус. +- Дешёвые модели собирают, сильные судят: обследование репозитория, + чтение объёмов, механика, реализация по жёсткой спеке — дешёвым; + результат переносится сильной модели там, где нужно суждение. Токены + Fable и Опуса на объёмную работу без суждения не тратить. +- Fable держи для самого трудного: оркестрация, архитектура, задачи, + где интеллект и вкус нужны одновременно. + +Механика вызова: Claude-модели — параметром `model` (Agent/Workflow) и +определениями из [claude-agents.md](claude-agents.md); Codex — прямым +`codex exec` ([codex-exec.md](codex-exec.md)). diff --git a/agents/.agents/skills/claude-subagent-playbook/references/prompt-templates.md b/agents/.agents/skills/claude-subagent-playbook/references/prompt-templates.md index 80b0d23..dcf2628 100644 --- a/agents/.agents/skills/claude-subagent-playbook/references/prompt-templates.md +++ b/agents/.agents/skills/claude-subagent-playbook/references/prompt-templates.md @@ -6,6 +6,14 @@ - [prompts/review-boilerplate.md](prompts/review-boilerplate.md) — мандат ревьюера + формат индекса находок (этапы 2 и 4). +- [prompts/line-task.md](prompts/line-task.md) / + [prompts/line-code.md](prompts/line-code.md) / + [prompts/line-rev.md](prompts/line-rev.md) — файлы линий ревью: линза и + префикс ID (две слепые линии / одиночный ревьюер). +- [prompts/line-taste.md](prompts/line-taste.md) — вкусовая линза с базой + запахов Фаулера; подшивается к линии уместности (этап 4 SKILL.md). +- [prompts/self-review.md](prompts/self-review.md) — саморевью + исполнителя (этап 3, resume тем же тредом). - [prompts/triage-header.md](prompts/triage-header.md) — правила триажа для исполнителя (этап 5). - [prompts/recheck-header.md](prompts/recheck-header.md) — узкая @@ -29,7 +37,7 @@ переживает. Windows-кавеат из codex-exec.md в силе: путь — forward-slash, не голый `/tmp` Git Bash. - Через Write оркестратор пишет **только параметрические блоки** ниже; - плейсхолдеры `{{...}}` — значения задачи, секции «adapt» — по смыслу. + секции «adapt» — по смыслу. Сборка на прогон: `D="$SCRATCH/"` — подпапка задачи; `P` — `references/prompts` в базовом каталоге скилла (путь даётся в шапке @@ -37,10 +45,15 @@ ```bash cat "$D/task-body.md" "$P/runtime-language.md" > "$D/task-prompt.md" -cat "$D/review-params.md" "$D/line-task.md" "$P/review-boilerplate.md" \ - "$P/runtime-language.md" > "$D/review-prompt-task.md" - # вторая линия: line-code.md -> review-prompt-code.md; - # одиночный ревьюер: line-rev.md -> review-prompt.md +cat "$D/review-params.md" "$P/line-task.md" "$P/line-taste.md" \ + "$P/review-boilerplate.md" "$P/runtime-language.md" \ + > "$D/review-prompt-task.md" +cat "$D/review-params.md" "$P/line-code.md" \ + "$P/review-boilerplate.md" "$P/runtime-language.md" \ + > "$D/review-prompt-code.md" + # одиночный ревьюер: line-rev.md (+ line-taste.md) -> review-prompt.md + # line-taste.md едет с линией уместности — переставь, если её ведёт + # другая линия (назначение линий — этап 4 SKILL.md) cat "$P/triage-header.md" "$D/review-codex.md" "$D/review-claude.md" \ "$D/notes.md" "$P/runtime-language.md" > "$D/fix-prompt.md" # notes.md опционален — нет, так не включай @@ -91,15 +104,16 @@ will run it before the reviews start. Отдельным ходом после отчёта о реализации, до внешних ревью — смена рамки «автор → критик» отдельным ходом ловит больше, чем финальный пункт -чек-листа в промпте задачи: +чек-листа в промпте задачи. Текст готов файлом: -```text -Now switch roles: you are a reviewer of your own diff. Walk it against the -task's acceptance criteria and boundaries. Fix what you find, stay inside -the task scope. Return one line: SELF-REVIEW: found N, fixed N — plus one -phrase per unfixed item, if any. +```bash +cat "$P/self-review.md" | codex exec resume ... ``` +Опус-исполнителю (`craftsman`) — тот же файл продолжением его треда: +запускай его с `name` и шли SendMessage +«read and execute $P/self-review.md». + ## 2. Ревью: общий блок + файл линии Общий параметрический блок (`review-params.md`) один на обе линии и не @@ -111,17 +125,20 @@ phrase per unfixed item, if any. ```text Read {{path to this line's review prompt}} and execute it. Working directory: -{{repo root}}. Write the full findings index to +{{repo root}}. Write the 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). Keep the index -strict: ONE line per finding and per confirmation, as the boilerplate -demands — no multi-line entries. Final message: ONLY the VERDICT line, -severity counters and the file path. +it (via Write or a Bash heredoc, whichever you have). Append each finding +to that file as you go — incremental writing keeps a partial index alive +if the session dies. Keep the index strict: ONE line per finding and per +confirmation, as the boilerplate demands — no multi-line entries. Final +message: ONLY the VERDICT line, severity counters and the file path. ``` (Однострочность продублирована в обёртке не случайно: boilerplate это уже -требует, но Клод-родословная держит формат хуже Codex — эмпирика +требует, но Клод-семейство держит формат хуже Codex — эмпирика 2026-07-12/13, многострочные находки и развёрнутые confirmations.) +Замене молчащего ревьюера давай **другой** путь вердикта — правило в +«Сбоях координации» SKILL.md. ```markdown # Code review: {{ticket NN — essence}} @@ -140,36 +157,16 @@ Test command (expect {{N}} passed): {{command}} shared code}} ``` -Файлы линий (`line-task.md` / `line-code.md`), по одному на слепую линию: - -```markdown -## Your line -FINDING PREFIX: TASK -Lens: compliance with the statement, acceptance criteria, boundaries, -intended observable result. -Taste: formally correct but substantively wrong is a finding — work out of -proportion to the task, an added artifact that does not earn its -existence, a check that passes without proving its own claim. Grade a -taste finding by the cost of living with the code, not by whether it -breaks a test. -``` - -```markdown -## Your line -FINDING PREFIX: CODE -Lens: correctness, invariants, regressions, security, test honesty. -``` - -Одиночному ревьюеру (простая ступень шкалы этапа 4) — один `line-rev.md` -с обеими линзами и префиксом `REV`. По эмпирике прогонов естественное -распределение: Codex — CODE (дефекты нового кода), Клод — TASK (уровень -задачи и архитектуры). - -Блок `Taste:` едет с **родословной**, а не с буквой линии: он адресован -Клоду (решение пользователя 2026-07-23, запись в -[lessons.md](lessons.md)). При обычном распределении и у одиночного -ревьюера он уже на месте — обоих ведёт Клод. Поменялись родословными — -переставь блок целиком туда, где Клод. +Файлы линий — готовые константы в `prompts/`, оркестратор их не +перепечатывает: `line-task.md` (уместность: постановка, критерии, +границы), `line-code.md` (дефекты: корректность, инварианты, регрессии), +одиночному ревьюеру — `line-rev.md` (обе линзы, префикс `REV`). +Вкусовая линза с базой запахов — `line-taste.md`; она едет с **линией +уместности** (её ведёт модель со вкусом — назначение линий в этапе 4 +SKILL.md), поэтому разрез — выбором файла в `cat`, не пересказом +границы. Стенд делится между линиями? Явный запрет ломающих команд +второй линии — отдельным параметрическим файлом `$D/access-.md`, +подшитым после файла линии (правило — этап 4 SKILL.md). Вариант для **этапа 2** (ревью постановки, кода изменений ещё нет) — тот же boilerplate, другой параметрический блок: @@ -192,8 +189,9 @@ Code to check the statement's facts against: {{file list with why}} criteria checkable and gameable?, observability}} ``` -Файл линии — тем же механизмом: только префикс (`SPEC-A` / `SPEC-B`, -одиночному обзору — `SPEC`); линза уже задана рамкой блока. +Файл линии здесь — двухстрочный Write (`## Your line` + +`FINDING PREFIX: SPEC-A|SPEC-B|SPEC`): константного файла нет +намеренно — префикс варьируется, а линза уже задана рамкой блока. ## 3. Параметрические хвосты триажа и перепроверки diff --git a/agents/.agents/skills/claude-subagent-playbook/references/prompts/line-code.md b/agents/.agents/skills/claude-subagent-playbook/references/prompts/line-code.md new file mode 100644 index 0000000..8f4b767 --- /dev/null +++ b/agents/.agents/skills/claude-subagent-playbook/references/prompts/line-code.md @@ -0,0 +1,3 @@ +## Your line +FINDING PREFIX: CODE +Lens: correctness, invariants, regressions, security, test honesty. diff --git a/agents/.agents/skills/claude-subagent-playbook/references/prompts/line-rev.md b/agents/.agents/skills/claude-subagent-playbook/references/prompts/line-rev.md new file mode 100644 index 0000000..2d999d7 --- /dev/null +++ b/agents/.agents/skills/claude-subagent-playbook/references/prompts/line-rev.md @@ -0,0 +1,5 @@ +## Your line +FINDING PREFIX: REV +Lens: correctness, invariants, regressions, security, test honesty; plus +compliance with the statement, acceptance criteria, boundaries, intended +observable result. diff --git a/agents/.agents/skills/claude-subagent-playbook/references/prompts/line-task.md b/agents/.agents/skills/claude-subagent-playbook/references/prompts/line-task.md new file mode 100644 index 0000000..68ee9e7 --- /dev/null +++ b/agents/.agents/skills/claude-subagent-playbook/references/prompts/line-task.md @@ -0,0 +1,4 @@ +## Your line +FINDING PREFIX: TASK +Lens: compliance with the statement, acceptance criteria, boundaries, +intended observable result. diff --git a/agents/.agents/skills/claude-subagent-playbook/references/prompts/line-taste.md b/agents/.agents/skills/claude-subagent-playbook/references/prompts/line-taste.md new file mode 100644 index 0000000..b0525bc --- /dev/null +++ b/agents/.agents/skills/claude-subagent-playbook/references/prompts/line-taste.md @@ -0,0 +1,38 @@ +## Taste + +Formally correct but substantively wrong is a finding: work out of +proportion to the task, an added artifact that does not earn its +existence, a check that passes without proving its own claim. Grade a +taste finding by the cost of living with the code, not by whether it +breaks a test. + +Match the changes against this smell baseline (Fowler, _Refactoring_, +ch. 3). Two rules bind it: a documented repo standard overrides the +baseline, and every smell is a judgement call to label ("possible +Feature Envy"), never a hard violation. Skip anything tooling already +enforces. + +- **Mysterious Name** — the name hides what it does or holds → rename; + if no honest name comes, the design is murky. +- **Duplicated Code** — the same logic shape in more than one place → + extract the shared shape, call it from both. +- **Feature Envy** — a method works another object's data more than its + own → move it onto the data it envies. +- **Data Clumps** — the same few fields or params keep travelling + together → bundle them into one type, pass that. +- **Primitive Obsession** — a primitive or string stands in for a domain + concept → give the concept its own small type. +- **Repeated Switches** — the same type-dispatch cascade recurs across + the change → polymorphism, or one map both sites share. +- **Shotgun Surgery** — one logical change forces scattered edits across + many files → gather what changes together into one module. +- **Divergent Change** — one module edited for several unrelated reasons + → split so each part changes for one reason. +- **Speculative Generality** — abstraction, parameters, or hooks for + needs the spec does not have → delete; inline until a real need shows. +- **Message Chains** — long `a.b().c().d()` navigation the caller should + not depend on → hide the walk behind one method on the first object. +- **Middle Man** — a unit that mostly delegates onward → cut it, call + the real target direct. +- **Refused Bequest** — an implementer ignores or overrides most of what + it inherits → drop the inheritance, use composition. diff --git a/agents/.agents/skills/claude-subagent-playbook/references/prompts/review-boilerplate.md b/agents/.agents/skills/claude-subagent-playbook/references/prompts/review-boilerplate.md index f0b61c4..b39eaf4 100644 --- a/agents/.agents/skills/claude-subagent-playbook/references/prompts/review-boilerplate.md +++ b/agents/.agents/skills/claude-subagent-playbook/references/prompts/review-boilerplate.md @@ -5,6 +5,11 @@ 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`. +- Work alone, depth one: no subagents, no delegating parts of the review. +- Leave the environment as you found it; if you stop or restart services, + verify the restoration actually took effect (e.g. `docker compose ps + -a`) — a trap that should have restored state is not evidence that it + did. - 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. @@ -12,7 +17,7 @@ ## Findings file format — index only One line per finding, with a stable ID (FINDING PREFIX comes from your -parameter block): +line block): PREFIX-N | BLOCKER|MAJOR|MINOR|NIT | file:line (or spec/task-file section) | one-phrase essence | how to verify/reproduce diff --git a/agents/.agents/skills/claude-subagent-playbook/references/prompts/self-review.md b/agents/.agents/skills/claude-subagent-playbook/references/prompts/self-review.md new file mode 100644 index 0000000..a07f151 --- /dev/null +++ b/agents/.agents/skills/claude-subagent-playbook/references/prompts/self-review.md @@ -0,0 +1,4 @@ +Now switch roles: you are a reviewer of your own diff. Walk it against +the task's acceptance criteria and boundaries. Fix what you find, stay +inside the task scope. Return one line: SELF-REVIEW: found N, fixed N — +plus one phrase per unfixed item, if any.