Урок 17.16. Артефакты и полный цикл: от идеи до merge

Дополнительные источники: https://github.com/obra/superpowers/tree/main/docs/plans, https://lzw.me/docs/opencodedocs/obra/superpowers/advanced/complete-workflow/index.html, https://lzw.me/docs/opencodedocs/obra/superpowers/faq/best-practices/index.html, https://mokevnin.github.io/agentic-coding-design-patterns/ru/superpowers.html

Зачем это нужно

Уроки 17.6–17.15 разобли цикл по шагам; этот урок собирает его целиком — через артефакты: что физически остается в репозитории после Superpowers-процесса, где это лежит и что в это пишут. Материал — на живом догфудинге: репозиторий Superpowers сам ведет свои артефакты по собственному процессу — в docs/superpowers/specs/ лежат дизайн-документы, в docs/superpowers/plans/ — планы реализаций; по ним видно, как выглядит процесс изнутри, до последнего rename.

Здесь же — «когда процесс избыточен»: best-practices из FAQ туториала о том, когда полный цикл — церемония, и каким маршрутом ее обойти (маршруты spike/bounded из урока 17.6).

Основная идея

Артефакты Superpowers делятся на два слоя: продукт процесса — то, что соглашают и хранят в git (дизайн-документ, план, коммиты, тесты), и раболее scratch-слой — журнал исполнения, брифы, пакеты ревью (каталог .superpowers/sdd/, git-игнорируемый, удаляется в конце — урок 17.9). Первый слой — долгосрочная память проекта, второй — операционная память исполнения. «Git history is the record now» — когда финальное ревью чисто, запись процесса — это коммиты.

flowchart TD A["Идея"] --> B{"Маршрут (урок 17.6)"} B -->|spike| C["Вопрос + эксперимент → ответ (throwaway)"] B -->|bounded| D["Краткий дизайн в чате → реализация, TDD"] B -->|architectural| E["Спецификация: docs/superpowers/specs/ ГГГГ-ММ-ДД-<тема>-design.md"] E --> F["План: docs/superpowers/plans/ ГГГГ-ММ-ДД-<фича>.md"] F --> G["Worktree + журнал (scratch, удаляется)"] G --> H["Задачи: TDD, ревью, фиксы"] H --> I["Финальное ревью ветки"] I --> J["Merge / PR (урок 17.12)"] D --> H

Где живут артефакты

Таблица из главы книги (сверена по репозиторию на дату среза):

Артефакт	Где лежит	Урок
Дизайн-документ (спецификация)	`docs/superpowers/specs/ГГГГ-ММ-ДД-<тема>-design.md`	17.6
План реализации	`docs/superpowers/plans/ГГГГ-ММ-ДД-<фича>.md` (расположение планов настраивается — предпочтения пользователя перекрывают дефолт)	17.8
Журнал исполнения (ledger)	`<repo-root>/.superpowers/sdd/<plan>/progress.md` — git-игнорируемый scratch	17.9
Коммиты + тесты	git-история ветки	17.10

Маршруты spike и bounded обходятся без этих файлов: спайк — это ответ, bounded — дизайн в чате; полные артефакты — только у architectural (урок 17.6).

Именование по датам (ГГГГ-ММ-ДД-) — не украшение: артефакты одной фичи (design + plan) сортируются рядом и связываются по префиксу.

Догфудинг: артефакты в репозитории Superpowers

Репозиторий Superpowers разрабатывается собственным процессом. На дату среза:

docs/superpowers/specs/ — 20 дизайн-документов: от 2026-01-22-document-review-system-design.md до 2026-08-27-diagnosing-superpowers-design.md;
docs/superpowers/plans/ — 16 планов реализаций;
docs/plans/ — ранние планы (до переноса в docs/superpowers/plans/): 2025-11-22-opencode-support-design.md, 2025-11-22-opencode-support-implementation.md, 2025-11-28-skills-improvements-from-user-feedback.md, 2026-01-17-visual-brainstorming.md.

Пары видны сразу: 2026-08-27-diagnosing-superpowers-design.md (спека) и 2026-07-15-sdd-fix-loop-redesign.md (план) — каждая крупная правка скиллов проходит полный цикл: спека → ревью → план → задачи → эвалы.

Что это доказывает практически: Superpowers — не витринная методология; артефакты процесса — рабочая практика проекта. Глава книги фиксирует это же: спека проходит самопроверку агента и ревью пользователя до начала плана.

Что внутри дизайн-документа

Структура (по реальному 2026-08-27-diagnosing-superpowers-design.md, выдержки в оригинале, пояснения по-русски):

markdown
# Diagnosing Superpowers Sessions — Design

Date: 2026-08-27
Status: approved by Jesse (in-session); spec pending review
Branch: `diagnosing-superpowers` off `dev`

## Goal

A core skill, `diagnosing-superpowers`, that a user invokes when a
superpowers session went wrong. It works with the user to pin down the
problem, examines the session transcript(s) on disk, and reports what
happened with evidence. On request it exports a scrubbed bundle ...

Заголовок спеки: дата, статус (кто и когда одобрил; ожидается ли ревью), ветка. Дальше — Goal (зачем и что), Scope decisions (решения, принятые в диалоге — «settled with Jesse»: что входит в v1, что отложено), затем функциональные разделы. Формат свободный — фиксируется не бланком, а требованием уроков 17.6: самопроверка (плейсхолдеры, согласованность, охват, двусмысленности) и ревью пользователя до перехода к плану.

Что внутри плана

План следует шаблону урока 17.8. Реальный пример — 2026-07-15-sdd-fix-loop-redesign.md (план редизайна цикла фиксов самого SDD):

markdown
# SDD Fix-Loop Redesign Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
> (recommended) or superpowers:executing-plans to implement this plan task-by-task.
> Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Make subagent-driven-development's review-fix loop convergent
and autonomous ... — with quorum eval evidence.

**Architecture:** Two repos. The `superpowers` repo (branch `sdd-fix-loop-redesign`,
already created; spec committed) gets the skill restructure ... The
`superpowers-evals` repo gets two seeded-ledger fixture helpers and three
scenarios, then a live before/after campaign.

**Tech Stack:** Markdown skill content; Bash scenario DSL ...; quorum live runs.

**Design spec:** `docs/superpowers/specs/2026-07-15-sdd-fix-loop-redesign-design.md`.
Read it before starting any task.

Дальше — разделы, показательные своей плотностью:

Global Constraints: точные, дословные из спеки правила — «Verbatim-move rule: eval-tuned sentences move unchanged»; точные форматы строк журнала («Task <N>: complete (commits <base7>..<head7>, review clean)» и остальные — сценарии их грепают); дисциплина коммитов (в каком репо что коммитится); статические гейты до живых прогонов; честная цена («live runs cost real money (~$3–15 per SDD run)»); коллизия с открытым PR #1943 и правило «не абсорбировать, а перебазировать по move-map».
File Structure: точно какие файлы создаются/правятся в двух репо — по задачам.
Задачи: Task 1 «Create the scoped re-review template» с Files/Interfaces и шагами-чекбоксами — вплоть до полного текста создаваемого шаблона в теле задачи.

Этот план — витрина принципа «план — набор решений, которые исполнитель не может принять сам»: форматы строк журнала, имена плейсхолдеров ([BRIEF_FILE], [FIX_BASE_SHA]), суммы денег, номера конфликтующих PR.

Полный цикл end-to-end

Сведем весь модуль в один проход (ссылки — на уроки):

Идея приходит в сессию; бутстрап using-superpowers уже в контексте (17.4); запрос классифицируется: spike/bounded/architectural (17.6).
Spike: вопрос + эксперимент согласованы в 2-3 предложениях → ответ-рекомендация; все построенное — throwaway. Bounded: вопросы → короткий дизайн в чате → явное «да» → реализация по TDD без документов. Architectural: далее.
Диалог brainstorming: намерение → понимание, записанное и скорректированное вами → варианты с трейд-оффами → дизайн секциями по 200-300 слов (17.6).
Дизайн-документ пишется в docs/superpowers/specs/, коммитится; самопроверка; ревью пользователя — HARD-GATE (17.6).
Worktree: изоляция, setup, зеленый бейзлайн (17.7).
План пишется в docs/superpowers/plans/: задачи 2-5 минут, Files/Interfaces, шаги RED→GREEN→Commit; самопроверка по пяти пунктам; выбор способа исполнения (17.8).
Исполнение: журнал в .superpowers/sdd/; цикл «бриф → исполнитель → отчет → ревью (spec + quality) → цикл фиксов ≤5 → scoped re-review» на каждой задаче; rulings в журнал; модели по роли (17.9).
TDD — на каждом шаге каждой задачи: падающий тест → минимальный код → suite → коммит (17.10).
Ревью между задачами и финальное — всей ветки, на самой способной модели, с Review Focus и rulings журнала (17.9, 17.11).
Финал: rulings и deferred minors — исчерпывающим списком партнеру; workspace удаляется (17.9); тесты на интегрируемом дереве → меню → merge/PR/оставить → очистка worktree (17.12).
Что осталось: спека, план, коммиты, тесты — в git; scratch удален. Если что-то пошло не так в пути — баг фиксируется через systematic-debugging (17.13), сбой самой сессии — через diagnosing-superpowers (17.14).

Чек-лист «после работы должны остаться»

[ ] дизайн-документ в docs/superpowers/specs/ (architectural) — прошедший самопроверку и ревью пользователя;
[ ] план в docs/superpowers/plans/ — с Files/Interfaces и точными значениями;
[ ] ветка: каждый шаг задач — атомарные коммиты с зеленым suite;
[ ] записи rulings — в финальном сообщении (не умерли вместе со scratch-workspace);
[ ] интеграция: merge/PR выполнены, worktree вычищен по правилам владения;
[ ] после всего: свежая верификация на интегрируемом дереве (17.12).

Когда процесс избыточен

Best-practices (FAQ туториала + правила уроков):

быстрая правка — bounded: два предложения дизайна в чате, «да», TDD; без файлов спеки и плана (17.6);
проверка идеи — spike: вопрос и способ эксперимента; результат — ответ, код throwaway (17.6);
«слишком просто для дизайна» — не существует: bounded — тоже ворота, только маленькие; масштабируется артефакт, не отсутствие согласования (17.6);
потеря бутстрапа/скилл молчит — сначала диагностика (17.14), не переустановка процесса;
главный критерий избыточности — цена ошибки и связность задач: маршрут выбирается по ним (урок 17.17 доводит критерии до сравнения инструментов).

Практика

Заведите в своем учебном проекте каталоги артефактов (docs/superpowers/specs/, docs/superpowers/plans/ или свои) и пройдите мини-цикл architectural: задача уровня «небольшая подсистема» — спека (заголовок с датой/статусом, Goal, Scope decisions) → ревью самого себя → план по шаблону урока 17.8 → 2-3 задачи по TDD → финал по уроку 17.12.
Сверьте итог с чек-листом «после работы должны остаться»: что отсутствует и почему?
В репозитории Superpowers откройте любую пару design+plan (например, 2026-07-15-sdd-fix-loop-redesign) и найдите: три Global Constraints с точными значениями; строку, где план фиксирует цену ошибки; как задачи связываются через Interfaces.

Краткое резюме

Артефакты Superpowers — два слоя: долгосрочный (спека, план, коммиты, тесты — в git) и операционный scratch (журнал, брифы, пакеты ревью — удаляется). Догфудинг — рабочая практика: 20 спек и 16 планов в самом репозитории, пары design+plan по датам.

Спека: дата/статус/ветка, Goal, Scope decisions; самопроверка и ревью пользователя до плана.
План: заголовок с REQUIRED SUB-SKILL, Global Constraints с дословными значениями, File Structure, задачи с Interfaces — решения, которые исполнитель не примет сам.
Полный цикл — 11 шагов; чек-лист «что осталось» включает rulings в финальном сообщении.
Избыточность лечится маршрутами: bounded и spike — тоже ворота, только дешевле.

Вопросы для самопроверки

Какие два слоя артефактов выделяет урок и почему scratch-слой удаляется в конце? Что остается записью процесса?
Зачем датированные имена файлов спек и планов? Покажите на паре из репозитория Superpowers.
Какие разделы обязательны в спеке и в плане? Что обязательно фиксируется в Global Constraints и почему «дословно из спеки»?
Соберите полный цикл по памяти: от классификации запроса до очистки worktree; какие HARD-GATE в нем встречаются?
Когда полный цикл избыточен и какие маршруты его замещают? Что при этом все равно остается обязательным?
Почему «record rulings в финальном сообщении» входит в чек-лист долгосрочных артефактов, хотя rulings писались в scratch?

Что дальше

Все элементы собраны; финальный урок, 17.17, — сопоставление: Superpowers против OpenSpec, Spec Kit и скиллов Мэтта Покока — и критерии выбора под ваш контекст.

Источники

https://github.com/obra/superpowers/tree/main/docs/superpowers