8.7 KiB
Как работает обвязка
Идея
Каждый инструмент отвечает за один вид памяти, и слои не пересекаются:
- Gitea помнит что делать между сессиями и неделями. Issue = фича, PR = точка человеческого контроля.
- OpenSpec помнит как система должна себя вести.
openspec/specs/— текущее состояние,openspec/changes/<id>/— дельта текущей фичи. После merge дельта архивируется и вливается в specs. - Superpowers ведёт процесс внутри одной фичи: brainstorming → writing-plans → subagent-driven-development → ревью → finishing-a-development-branch. Прогресс внутри плана живёт в ledger (
.superpowers/sdd/<plan>/progress.md), который переживает компакцию и обрыв сессии, но удаляется после завершения. - codegraph — карта кода для сабагентов:
codegraph_exploreвместо grep/Read по файлам. - Хуки — то, что нельзя доверять промпту. Superpowers просит, хуки запрещают.
Клей между слоями — global/CLAUDE.md. Superpowers сам заявляет, что инструкции пользователя выше skills, поэтому вся маршрутизация живёт там.
Цикл фичи
| # | Шаг | Кто | Артефакт |
|---|---|---|---|
| 1 | Формулируете цель одной фразой; агент заводит issue | вы + агент | issue #N |
| 2 | brainstorming: классификация spike / bounded / architectural, вопросы по одному, подходы, дизайн по частям |
агент + вы | — |
| 3 | Спека в openspec/changes/<id>/ (proposal, specs/*, design) + раздел «Decisions made without discussion»; ваше утверждение |
агент, вы | change |
| 4 | using-git-worktrees: ветка feat/N-slug |
агент | worktree |
| 5 | writing-plans: план с Global Constraints, Review Focus, полным кодом задач; Task 1 — тестовая инфраструктура; ваше утверждение |
агент, вы | docs/superpowers/plans/*.md |
| 6 | SDD: контроллер (sonnet) → implementer на задачу (haiku/sonnet) → reviewer (sonnet) → fix loop до 5 раундов → ledger | агент автономно | коммиты, ledger |
| 7 | Финальное ревью всей ветки (opus), одна волна фиксов | агент | — |
| 8 | finishing-a-development-branch: PR в Gitea с «Rulings I made» |
агент | PR |
| 9 | Ревью PR в Gitea; комментарии → receiving-code-review → правки в ветке; вы делаете merge |
вы ↔ агент | merge |
| 10 | «Закрывай»: чеклист из 6 пунктов (см. CLAUDE.md) | агент | archive, closed issue, чистый main |
Шаги 6–8 идут без остановок. Агент останавливается только на необратимой операции, вопросе безопасности, побочном эффекте вне worktree или плане, который невозможно исполнить.
Bounded-задача (флаг, фикс) идёт короче: дизайн в чате, файл .bounded в корне worktree (пропускает хук require-plan), TDD, коммит, PR. Без OpenSpec change и без плана.
Subagent-driven development
Три роли, один цикл на задачу:
- Контроллер видит план, спеку, ledger и короткие статусы. Режет план на брифы (
task-brief), запускает сабагентов, выносит рулинги, ведёт ledger. Кода не пишет. Запускается фоновым сабагентом на sonnet. - Implementer — свежий сабагент на задачу. Видит только свой бриф и интерфейсы соседних задач. TDD, коммит, отчёт в файл, статус DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED.
- Reviewer — свежий сабагент, получает бриф, отчёт и diff файлом (
review-package). Два вердикта: соответствие спеке и качество.
Fix loop: раунды 1–3 продолжают того же implementer, 4–5 — свежий на более сильной модели. После пятого контроллер адьюдицирует сам и записывает рулинг. Minor-замечания в цикл не входят, откладываются до финального ревью.
Шаблоны сабагентов входят в superpowers: implementer-prompt.md, task-reviewer-prompt.md, re-review-prompt.md, code-reviewer.md. Это роли процесса, а не доменные специалисты; доменная экспертиза приходит через бриф с кодом, проектный CLAUDE.md и доменные skills.
Решения без обсуждения
Единственное место, где видно, что агент решил за вас. Правило в CLAUDE.md: любое такое решение — на этапе спеки, плана или исполнения — пишется в openspec/changes/<id>/design.md, раздел ## Decisions made without discussion, с датой, обоснованием и ценой ошибки. Ledger удаляется, чат теряется, design.md архивируется со спекой.
Читать: спеку один раз при утверждении, раздел решений каждый раз, когда он пополняется (после спеки, после плана, в финальном отчёте SDD). Каждое решение — вопрос «согласен ли я»: согласен — ничего не делать; не согласен — сказать агенту, он поправит; непонятно — спросить.
Хуки
| Правило | Файл | Механизм |
|---|---|---|
| Никаких изменений на main / detached HEAD | guard-main.sh, PreToolUse на Edit/Write/MultiEdit/Bash |
проверяет ветку; для Bash блокирует команды, похожие на запись (>, tee, sed -i, mv, rm, git commit/push…), пропускает git worktree add; коммит/push в main разрешены только если изменены исключительно файлы в openspec/ (архивация) |
Правки в src/ только при плане или .bounded |
require-plan.sh, PreToolUse на Edit/Write/MultiEdit |
ищет план в docs/superpowers/plans/ для текущей ветки или файл .bounded |
| Тесты зелёные перед коммитом | git pre-commit в проекте (не входит в пакет) | обычный git-хук с командой тестов |
Exit 2 блокирует вызов и показывает агенту stderr, поэтому агент сам делает то, что просит сообщение. Оба обхода, замеченные на пилоте (запись через echo > вместо Write; push через detached HEAD), закрыты.
Дисциплина между сессиями
Новая сессия начинается с tea issues ls и openspec list, а не с памяти о прошлой. Незавершённый план возобновляется из ledger в worktree. Связка разваливается не на исполнении, а на закрытии — поэтому «закрывай» выполняет весь чеклист без остановок.
Стоимость
Bootstrap superpowers (~3 КБ) вставляется на каждом старте и после компакции. SDD стоит свежий контекст на задачу и на ревью; подробный план с готовым кодом позволяет отдать большинство задач haiku. Для планов до 5 задач дешевле executing-plans (Native): один контекст, одно ревью в конце.