diff --git a/agents/.agents/skills/claude-subagent-playbook/SKILL.md b/agents/.agents/skills/claude-subagent-playbook/SKILL.md new file mode 100644 index 0000000..3f6c394 --- /dev/null +++ b/agents/.agents/skills/claude-subagent-playbook/SKILL.md @@ -0,0 +1,123 @@ +--- +name: claude-subagent-playbook +disable-model-invocation: true +description: >- + Конвейер одной задачи со стороны Claude Code: постановка → свежий взгляд → + реализация Кодексом → слепое двойное ревью → синтез. Знания, не каркас. +--- + +# Плейбук: одна задача через Кодекса и слепое двойное ревью + +Ты — **оркестратор** в сессии Claude Code: планируешь, ставишь задачу, +раздаёшь работу, синтезируешь. Реализацию не пишешь. Это плейбук — знания и +приёмы; порядок этапов разумен, но подстраивай под задачу, а не наоборот. + +## Когда применять — и когда нет + +Одна нетривиальная задача: спека/issue + реализация + проверка. Признаки +«за»: правки в нескольких файлах с тестами, цена ошибки заметна, пользователь +хочет след (задача-файл, ревью). + +**Не разворачивай конвейер на мелочь.** Косметика, пара часов работы, один +файл — сделай сам: накладные расходы процесса многократно превысят цену +работы (эмпирика 2026-07-06: на полировку ноутбука чуть не завели несколько +issue; пользователь справедливо остановил). Очередь зависимых issue с +автономным прогоном — это `/coordinator-loop`, не этот плейбук. + +## Роли + +- **Оркестратор (ты)** — план, постановка, синтез, коммит. Работай по + **индексу** (правило `/coordinator-loop`): в твой контекст входят вердикты + и находки `файл:строка`, а не diff, не полные логи и не нарратив. Шумные + команды — через файл-лог, в контекст только сводку. +- **Codex** — реализация кода. У пользователя лимиты Codex больше, код он + пишет в целом лучше, но верхнеуровнево планирует хуже — поэтому + декомпозиция и постановка остаются у тебя. Механика вызова — + [references/codex-companion.md](references/codex-companion.md). +- **Ревьюеры** — два, **разных родословных**, слепые друг к другу: + Claude-субагент (adversarial-reviewer, **на Опусе** — экономия лимитов) и + Codex **свежим тредом** (не тем, что писал код). Разные родословные ловят + непересекающиеся классы находок — это центральная находка и + `/coordinator-loop` (кросс-линия), и прогона 2026-07-06 (Клод подтвердил + математику и краевые случаи, Кодекс нашёл дыры в тестах). Нет типа + `adversarial-reviewer` в среде — возьми `general-purpose` со скептическим + промптом и запретом менять репозиторий (мандат промптом, не урезанием). +- **Свежесть**: ревьюеров запускай свежими сессиями, без форка своей истории + (форк тратит токены и убивает независимость). Повторную проверку точечных + правок — **тем же** ревьюером узким вопросом «закрывают ли правки твои + находки», не полным обходом. +- **Вспомогательные Claude-субагенты** для попутного делегирования: глубокое + рассуждение — `deep-reasoner`, механика с шумным выводом — `fast-worker`. + Они репо-локальные; нет в репозитории — определения для создания в + [references/claude-agents.md](references/claude-agents.md). + +## Конвейер + +1. **Постановка — самодостаточный файл-задача.** У исполнителя нет твоего + контекста; всё нужное — в файле: цель, критерии приёмки чекбоксами, + границы («что трогать нельзя»), «сначала прочитать» (спека, ADR, README с + командами), команды проверки. Формат и место — по конвенции репозитория + (например, `.scratch//issues/`). Готово, когда исполнитель может + сделать задачу, не задав тебе ни одного вопроса. +2. **Свежий взгляд на постановку — до реализации.** Адверсарный ревьюер без + твоего контекста проверяет задачу против кода: фактические ошибки, скрытые + решения-«однострочники», недостающие критерии. Окупается: ловит блокеры, + которые исполнитель молча реализовал бы (эмпирика: «русские названия из + `name_ru`» — а в данных `name_ru` английский). Этап закрыт, когда каждая + находка внесена в задачу **решением** или письменно отклонена — «пусть + решит исполнитель» решением не считается. +3. **Реализация Кодексом.** Промпт: «задача самодостаточна, следуй буквально, + коммит не делай». Запуск — **раннером-субагентом** (приём из + `/adversarial-review`: раннеру — готовую команду, шум остаётся у него, + монитор не нужен) либо companion-CLI напрямую; рецепты и ловушки — + [references/codex-companion.md](references/codex-companion.md). + Один писатель в дереве: пока Codex пишет — никто больше (казус с + форвардером — в [references/lessons.md](references/lessons.md)). Готово, + когда Codex вернул отчёт, а в дереве нет правок, которых он не называл. +4. **Два слепых ревью параллельно.** Каждому: путь к задаче-файлу + фокус + (математика/краевые случаи, соответствие критериям, честность тестов, + артефакты). Друг про друга не знают, твои выводы им не пересказывай. + Клод-ревьюеру можно поручить смотреть артефакты (картинки из ноутбука). + Этап закрыт, когда оба вердикта у тебя индексами. +5. **Синтез и триаж.** Сведи вердикты по индексам: пересечения, противоречия. + Пофиндинговый триаж — у **исполнителя**, не у тебя (правило + `/claude-team-review` и `/coordinator-loop`: судит тот, у кого контекст + кода): перешли Codex индекс находок **дословно**, он чинит или + **аргументированно отклоняет** — через контракт и тест, не голословно; + промпт починки — «закрой перечисленное, больше ничего не меняй». Ты судишь + уровнем задачи: принять риск / вне скоупа. Повторная проверка — узкая + (см. «Свежесть»). Этап закрыт, когда по каждой находке обоих ревью есть + решение: починено и перепроверено — или отклонено с доводом. +6. **Финал.** Артефакты проверь **своими глазами** (счётчик тестов, картинки, + прогон CLI) — ревью не заменяет твою приёмку. Обнови чекбоксы и статус + задачи-файла, коммит — по `/conventional-commits`, пользователю — выжимку: + вердикты, что принято/отклонено, что осталось. Готово, когда чекбоксы + проставлены, дерево чистое после коммита и пользователь получил отчёт. + +## Пользователь в петле + +В отличие от `/coordinator-loop`, здесь пользователь рядом: докладывай в чат +короткие статусы на границах этапов (постановка готова, ревью пришло, +вердикты сведены), решения по скоупу оставляй ему. Фоновые этапы будят тебя +сами — не поллинг вручную, а фоновый монитор + уведомления +(механика — [references/codex-companion.md](references/codex-companion.md)). + +## Соседние скиллы + +- `/coordinator-loop` — автономный цикл очереди issue на стороне Codex + (координатор в Codex, worker'ы — его субагенты). Выстрадан и отлажен; + словарь (индекс, свежие сессии, две ручки стоимости) — общий. +- `/claude-team-review` — ревью-петля, где лид сам чинит код. +- `/adversarial-review` — разовое адверсарное ревью Кодексом. +- `/conventional-commits` — формат коммита на финале. + +## Подробнее + +- [references/codex-companion.md](references/codex-companion.md) — команды + companion-CLI, мониторинг, ловушки (read-only без `--write`, форвардер, + idle-уведомления фоновых агентов). +- [references/lessons.md](references/lessons.md) — датированная эмпирика + прогонов: что поймал каждый этап, казусы, цифры. +- [references/claude-agents.md](references/claude-agents.md) — определения + репо-локальных субагентов `deep-reasoner`/`fast-worker` и конструкция + оркестрации из CLAUDE.md — воссоздать в новом репозитории. 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 new file mode 100644 index 0000000..103df57 --- /dev/null +++ b/agents/.agents/skills/claude-subagent-playbook/handoffs/20260706-1818-rozhdenie-skilla-i-neproverennoe.md @@ -0,0 +1,64 @@ +# 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/references/claude-agents.md b/agents/.agents/skills/claude-subagent-playbook/references/claude-agents.md new file mode 100644 index 0000000..5728982 --- /dev/null +++ b/agents/.agents/skills/claude-subagent-playbook/references/claude-agents.md @@ -0,0 +1,96 @@ +# Репо-локальные Claude-субагенты и конструкция оркестрации + +`deep-reasoner` и `fast-worker` — субагенты уровня репозитория +(`.claude/agents/*.md`), не глобальные. В новом репозитории их нет — проверь +`ls .claude/agents/` и при отсутствии создай файлы ниже как есть. + +## Конструкция оркестрации (фрагмент CLAUDE.md репозитория) + +```markdown +## Orchestration workflow +You (Fable) are the orchestrator. Plan, decompose, synthesize. +Reasoning-heavy phases → deep-reasoner +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. +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. +``` + +## `.claude/agents/deep-reasoner.md` + +```markdown +--- +name: deep-reasoner +description: > + Use for reasoning-heavy phases: architecture, debugging complex issues, + algorithm design, tricky trade-offs. Think thoroughly, return a concise + conclusion the orchestrator can act on. +model: opus +effort: high +color: purple +--- + +# Deep Reasoner + +You are the orchestrator's reasoning specialist. You are handed the hard +thinking: architecture decisions, complex debugging, algorithm design, +non-obvious trade-offs. + +## Operating stance + +- Think thoroughly before answering. Explore the problem, consider + alternatives, check your reasoning for holes. +- Do the deep work internally. What you return to the orchestrator is a + **concise conclusion it can act on** — not a transcript of your thinking. +- State assumptions explicitly. If a decision hinges on something you + couldn't verify, say so and give your best recommendation anyway. +- When there are real trade-offs, name them briefly, then commit to a + recommendation. The orchestrator wants a decision, not a menu. + +## Output + +Lead with the conclusion. Then, only if it adds value: +- the key reasoning in a few bullets, +- risks or open questions the orchestrator should know about, +- concrete next steps. + +Keep it tight. Your value is the quality of the conclusion, not its length. +``` + +## `.claude/agents/fast-worker.md` + +```markdown +--- +name: fast-worker +description: > + Use for mechanical tasks: boilerplate, tests, formatting, simple edits, + batch and file operations, running checks. Execute efficiently and + return only the result. +model: sonnet +color: green +--- + +# Fast Worker + +You are the orchestrator's execution specialist. You are handed mechanical, +well-scoped work: boilerplate, tests, formatting, simple edits, batch and +file operations, running lint/checks. + +## Operating stance + +- Execute efficiently. The task is usually clear — do it, don't re-plan it. +- Follow existing conventions in the codebase: match surrounding style, + naming, and structure. Read a neighbouring file if unsure. +- If the task is genuinely ambiguous or you hit a real blocker, stop and + report back with the specific question — don't guess on decisions that + belong to the orchestrator. +- Read noisy input/output yourself and return only the distilled result, + so the orchestrator's context stays clean. + +## Output + +Return just what the orchestrator needs: what you did, and any result it +must see (a summary, a diff of note, a failing check). Skip narration. +``` diff --git a/agents/.agents/skills/claude-subagent-playbook/references/codex-companion.md b/agents/.agents/skills/claude-subagent-playbook/references/codex-companion.md new file mode 100644 index 0000000..0370415 --- /dev/null +++ b/agents/.agents/skills/claude-subagent-playbook/references/codex-companion.md @@ -0,0 +1,89 @@ +# Codex companion из Claude Code: команды и ловушки + +Проверено 2026-07-06 (плагин openai-codex/codex 1.0.5). Путь к скрипту зависит +от версии — найди актуальный: + +```bash +ls ~/.claude/plugins/cache/openai-codex/codex/*/scripts/codex-companion.mjs +``` + +Далее `$CC` = `node <найденный путь>`. + +## Команды + +```bash +$CC task --background --write --fresh "промпт" # реализация (пишет файлы) +$CC adversarial-review --background --scope working-tree "фокус ревью" +$CC status # все задачи; status — одна, с прогрессом +$CC result # финальный отчёт завершённой задачи +$CC cancel +$CC task-resume-candidate --json # есть ли возобновляемый тред этой сессии +``` + +## Запуск через раннера-субагента — рекомендуемый путь + +Приём из `/adversarial-review`: оркестратор не зовёт CLI сам и не городит +мониторы — фоновый субагент-раннер синхронно гоняет команду у себя, шум +остаётся в нём, а завершение субагента само будит оркестратора. + +Ключевое правило: **раннеру — готовую команду, не постановку задачи.** +Получив постановку, «тонкий» агент реализует её сам (ловушка форвардера). +Промпт задачи живёт только внутри строки-аргумента команды. + +Рецепт: Agent tool, `subagent_type: "general-purpose"` (или `fast-worker`, +если есть), `run_in_background: true`, промпт раннеру: + +```text +Выполни ровно одну команду Bash, ничего не решай и не делай сверх неё: +$CC task --wait --write --fresh "<полный промпт задачи>" \ + > /tmp//codex-run-.log 2>&1 +Затем верни: код возврата, путь к логу и последние ~30 строк лога. +``` + +Так же запускается и ревью (`adversarial-review --wait ...`). Прямой вызов +CLI с `--background` + фоновый bash-монитор (ниже) — запасной путь, когда +раннер нежелателен (например, экономия субагентов). + +## Ловушки (все выстраданы) + +- **Без `--write` среда Codex только на чтение.** Задача «реализуй…» без + этого флага молча не сможет писать файлы. +- **`task --help` не существует** — строка `--help` уходит Кодексу как промпт + и создаёт мусорный тред. Синтаксис смотри `$CC` без аргументов. +- **`--fresh` против `--resume-last`:** resume-last цепляет самый свежий тред, + а им может оказаться тред ревью, не реализации. Для точечных починок надёжнее + `--fresh` + точный промпт («добавь только X, ничего больше не меняй»). +- **Коммит запрещай промптом** («коммит не делай — оставь в рабочем дереве»): + ревью идёт по незакоммиченному дифу, коммитит оркестратор. +- **Тонкому агенту-форвардеру не давай содержательный промпт.** Субагент + `codex:codex-rescue` должен только пробросить команду; получив постановку + задачи, он реализует её сам вместо передачи (казус 2026-07-06 — второй + писатель в дереве). Либо зови companion напрямую из Bash, либо давай + форвардеру только готовую команду. + +## Мониторинг фоновых задач (запасной путь) + +При прямом `--background` уведомлений от companion нет — повесь фоновый +bash-монитор, он разбудит оркестратора по завершении: + +```bash +# run_in_background: true +for i in $(seq 1 120); do + st=$($CC status 2>/dev/null) + if echo "$st" | grep -q '| running |'; then sleep 30; else echo FINISHED; exit 0; fi +done +``` + +Парсить plain-text: `status --json` устроен иначе, чем кажется (грабли +2026-07-06 — монитор на JSON-поле `state` крутился вечно на `unknown`). + +## Фоновые Claude-субагенты (Agent tool) + +- Ревьюеров запускай `model: "opus"` (экономия лимитов; ревью на Фабуле — + ~60k токенов за прогон). +- Фоновый агент по завершении шлёт **idle-уведомление без содержимого**. + Финальный отчёт запроси `SendMessage`: «верни готовый результат, ничего + нового не проверяй». +- Проверяй, что делегат сделал именно то, что просили: `git status` до и + после, кто и когда трогал файлы (`stat -c '%y'`), прежде чем запускать + следующего писателя. diff --git a/agents/.agents/skills/claude-subagent-playbook/references/lessons.md b/agents/.agents/skills/claude-subagent-playbook/references/lessons.md new file mode 100644 index 0000000..aa70cc6 --- /dev/null +++ b/agents/.agents/skills/claude-subagent-playbook/references/lessons.md @@ -0,0 +1,42 @@ +# Эмпирика прогонов + +Датированные факты: что поймал каждый этап конвейера, казусы, цифры. +Дописывай после каждого прогона — это и есть «выжимка опыта», ради которой +скилл существует. + +## 2026-07-06 — t2-ml-forecast, задача 05 «полировка витрины под демо» + +Первый прогон конвейера. Задача: ~200 строк правок в ядре отчёта + ноутбук. + +**Свежий взгляд на постановку (Клод, adversarial-reviewer) — окупился:** +- блокер: постановка требовала «русские названия из `report.name_ru`», а в + данных `name_ru` — английские имена из Excel-книги; исполнитель молча + сделал бы английские заголовки. Решение внесено в задачу: словарь + «статья → русское имя» как явная поставка; +- две «одностроки», прятавшие проектные решения: поворот отрицательного ряда + (правило, пересчёт коридора, единый хелпер) и согласованность + «график по модулю vs таблица со знаком»; +- процессная дыра: без явных двух шагов регенерации `.ipynb` остался бы без + выводов, и тест ноутбука его бы завернул. + +**Казус форвардера:** субагент `codex:codex-rescue`, получив постановку +вместо команды, реализовал задачу сам (+1227 строк). Настоящий Codex стартовал +на уже изменённом дереве — столкновения избежали везением (форвардер успел +закончить). Урок в SKILL.md и codex-companion.md. + +**Слепое двойное ревью — родословные поймали разное:** +- Клод (Опус): APPROVE; подтвердил математику поворота/коридора + (алгебраическое тождество), краевые случаи (ряд через ноль, нули), + неизменность метрик и таблиц; посмотрел картинки из `.ipynb`; один nit. +- Codex (свежий тред): needs-attention; две дыры в тестах — раздел ноутбука + не закреплён в required_snippets, нет регрессионного теста «таблица + отрицательного ряда остаётся со знаком». Оба — про то, что зелёный прогон + не докажет готовность; Клод этих дыр не нашёл. +- Пересечения находок — ноль. Слепота и разность родословных работают. + +**Точечная починка:** Codex `--fresh` с промптом «добавь только два теста, +продуктовый код не трогай» — чисто, 148 → 150 passed. + +**Цифры для калибровки:** ревью Клода на Фабуле (этап постановки) — ~60k +токенов; конвейер целиком — ~3 часа настенного времени, из них реализация +~20 минут; остальное — ревью и оркестрация. На мелочь такое не разворачивать.