Урок 17.9. Исполнение плана: сабагенты и параллельная работа

Дополнительные источники: https://github.com/obra/superpowers/blob/main/skills/executing-plans/SKILL.md, https://github.com/obra/superpowers/blob/main/skills/dispatching-parallel-agents/SKILL.md

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

Четвертый шаг базового workflow (урок 17.5) — исполнение плана, написанного в уроке 17.8. Superpowers исполняет план в двух режимах, и это решение вы принимаете в конце этапа планирования: subagent-driven-development — свежий сабагент на каждую задачу с ревью после каждой (основательнее и дороже) или executing-plans — все задачи инлайн в текущей сессии с одним финальным ревью ветки (дешевле и быстрее). Плюс третий скилл — dispatching-parallel-agents — для параллельной работы над независимыми задачами.

Это ядро методологии и самый объемный скилл Superpowers (568 строк). Для курса он важен и как хрестоматийный образец оркестрации: курс разбирает мультиагентность в модуле 11; здесь — законченная, откалиброванная реализация: контроллер, исполнители, ревьюеры, журнал (ledger), пять раундов фиксов и предохранитель.

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

Ядро subagent-driven-development (формула скилла): «Fresh subagent per task + task review (spec + quality) + broad final review = high quality, fast iteration» — свежий сабагент на каждую задачу, ревью задачи (соответствие плану + качество кода) после каждой, широкое ревью ветки в конце. Зачем сабагенты: контроллер делегирует задачи специализированным агентам с изолированным контекстом; сабагенты никогда не наследуют историю сессии — контроллер конструирует им ровно то, что нужно; собственный контекст контроллера сохраняется для координации.

executing-plans — та же дисциплина дешевле: план уже «продумал за вас», бриф — это спека, журнал — память, TDD — ворота на каждой задаче, финальный ревьюер — вторая пара глаз.

Два режима: сопоставление

Дерево выбора из скилла: есть план → задачи в основном независимы? → (нет → исполнение вручную или назад в brainstorming) → партнер выбрал инлайн или нет тула сабагентов? → да: executing-plans; нет: subagent-driven-development.

Важная оговорка про модель: полностью специфицированный план превращает инлайн-исполнение в «транскрипцию плюс тестирование» — хорошо идет на средне-уровневой модели сессии, а самое способное место — финальное ревью (диспетчеризуется отдельно).

Общие правила обоих режимов

Эти правила повторяются в обоих скиллах дословно по смыслу:

Непрерывное исполнение. Не останавливаться «отчитаться» между задачами: партнер попросил исполнить план — исполнить. «Should I continue?» и сводки прогресса тратят его время.

Решения, а не стопы (Rulings, not stalls). Работающий план не ждет человека: конфликты, двусмысленности, дефекты плана, превышение лимитов — решаются на месте. Спека — обязательный авторитет, план — ее аргумент, суждение агента решает то, чего не отвечают оба. Каждое решение записывается в журнал: Ruling: <что решили> — <почему> — <чего это стоит, если неправильно> — и работа продолжается.

Четыре стопа — только они. (1) необратимая или разрушительная операция; (2) действие, чувствительное к безопасности; (3) сайд-эффект вне этого worktree, о котором нормы говорят спросить (merge, push в общую ветку, publish); (4) план, настолько сломанный, что каждый путь вперед — догадка.

Журнал — защита от компакции. Память разговора не переживает компакцию; контроллеры, потерявшие место, повторно диспетчеризовали целые завершенные последовательности задач — «самая дорогая наблюдаемая ошибка». Прогресс отслеживается в файле журнала, не только в todo. Формат: каждая запись — строка в progress.md.

Setup (subagent-driven)

• Worktree: через using-git-worktrees (урок 17.7); никогда не начинать реализацию на main/master без явного согласия.
• Рабочее пространство плана: каждый план владеет своим git-игнорируемым каталогом (через scripts/sdd-workspace PLAN_FILE, каталог под <repo-root>/.superpowers/sdd/): журнал, брифы, отчеты, пакеты ревью. Чужой каталог не читается и не пишется.
• Восстановление: проверка журнала <workspace>/progress.md; первая строка — идентичность плана; задачи со строкой Task <N>: complete — готовы, не диспетчеризовать их заново; возобновление с первой незавершенной. Журнал с чужим планом — оставить на месте, завести свой. «After compaction, trust the ledger and git log over your own recollection» — после компакции доверяй журналу и git log, а не своей памяти.
• Чтение плана и спеки: план один раз; Global Constraints — в заметки; todo на каждую задачу; спека — обязательный авторитет, конфликты внутри плана решаются против нее.
• Pre-flight скан: до задачи 1 — скан плана на конфликты; вывод — таблица (не вердикт): по строке на пару задач, делящих файл/интерфейс (что одна производит против того, что другая потребляет, и что найдено), и по строке на задачу (согласованы ли ее собственные тесты с ее кодом). Каждая находка — решение (ruling) в журнал до начала исполнения. «Чисто» без строк — не скан.

Цикл задачи (subagent-driven)

1. Диспетчеризация исполнителя

До диспетчеризации фиксируется BASE (git rev-parse HEAD) — от него режется диапазон ревью. Состав диспетчер-промпта (по скиллу):

• Бриф задачи: скрипт скилла извлекает полный текст задачи в отдельный файл; диспетчер содержит: (1) строку о месте задачи в проекте; (2) путь к брифу — «прочти сначала, это твои требования с точными значениями»; (3) интерфейсы и решения из ранних задач, которых бриф знать не может; (4) разрешение двусмысленностей брифа; (5) путь файла отчета и контракт отчета. Точные значения — только в брифе; целый файл плана сабагенту не дают.
• Файл отчета: рядом с брифом; исполнитель пишет полный отчет туда, возвращает только статус, коммиты, однострочную сводку тестов и concerns. Все, что вставляется в промпт или возвращается, остается в контексте контроллера до конца сессии — артефакты передаются файлами.
• Диспетчер — одна задача, не история сессии: не вставлять накопленные сводки прошлых задач (реальная сессия: диспетчер в 42k символов, из которых 99% — вставленная история).
• Контракт без сабагентов (в шаблоне исполнителя): исполнитель никогда не диспетчеризует своих сабагентов — ни хелперов, ни ревьюеров. В реальных сессиях каждый ревьюер, порожденный исполнителем, дублировал ревью контроллера — лишнее ревью-место на задачу.
• Не параллелить исполнителей: несколько исполнителей одновременно — конфликты; параллелятся независимые домены иначе (см. dispatching-parallel-agents ниже).

Шаблон — implementer-prompt.md в каталоге скилла.

2. Обработка отчета

Четыре статуса:

• DONE — собрать пакет ревью (scripts/review-package PLAN_FILE BASE HEAD; BASE — зафиксированный до диспетчеризации, никогда HEAD~1, молча теряющий все коммиты задачи кроме последнего) и диспетчеризовать ревьюера задачи.
• DONE_WITH_CONCERNS — работа сделана, но исполнитель отметил сомнения: о корректности/охвате — решить до ревью; наблюдения («файл разрастается») — в журнал и на ревью.
• NEEDS_CONTEXT — дать недостающий контекст, диспетчеризовать заново.
• BLOCKED — оценить блокер: проблема контекста → дать контекст, та же модель; нужно больше рассуждений → более способная модель; задача велика → разбить; план неверен → решение (ruling) в журнал и повторная диспетчеризация с решением в промпте. Никогда не игнорировать эскалацию и не заставлять ту же модельretry без изменений.

Если исполнитель задает вопросы — отвечать полностью, не подгоняя в реализацию.

3. Ревью задачи

Ревью задачи — ворота скоупа задачи; широкое ревью — одно, в конце. Пропускать нельзя; саморевью исполнителя ревью не заменяет. Вердиктов обязано быть два: соответствие спеке (spec compliance) и качество задачи (task quality).

Входы ревьюера: путь к брифу, путь к отчету, пакет ревью (дифф файлом) и Global Constraints, связывающие задачу. Правила контроллера: не добавлять открытых директив «проверь все случаи» без конкретной причины; не просить ревьюера перезапускать тесты, которые уже прогнал исполнитель; не предсуждать находки — «не проси ревьюера игнорировать X» (фразы «do not flag», «at most Minor», «the plan chose» в вашем промпте — стоп: вы предсуждаете, обычно чтобы сэкономить себе цикл ревью).

Находки вида «⚠️ Cannot verify from diff» — требования в неизмененном коде или между задачами — не блокируют ревью, но контроллер обязан закрыть каждый сам: он держит план и кросс-задачный контекст. Подтвержденный пробел — проваленное spec-ревью, входит в цикл фиксов.

Шаблоны — task-reviewer-prompt.md, code-reviewer.md (урок 17.11).

4. Цикл фиксов

Триггер: spec ❌, любой Critical/Important, подтвержденный «⚠️». Два выхода из цикла до его начала:

• Minor-находки — в журнал как Task <N>: minor (deferred): <однострочник> и в список для финального ревью (триаж перед merge); в цикл не входят.
• Находка «план-предписан» — конфликт находки с текстом плана — решение контроллера: взвесить находку против плана со спекой как авторитетом, записать ruling и действовать. Не отбрасывать находку «потому что план» и не диспетчеризовать фикс, противоречащий плану, без записи.

Раунды 1-3 — вернуть того же исполнителя: его контекст цел; ему передаются открытые находки дословно. Раунды 4-5 — свежий исполнитель на более способной модели: с брифом, файлом отчета, находками и рамкой «предыдущий исполнитель пробовал N раз; теперь задача твоя. Прочти файл отчета, что уже пробовалось». Цикл, выживший три возврата, обычно значит: исполнитель не видит собственной проблемы — свежие глаза плюс апгрейд модели одним ходом.

Каждый раунд: фикс + перезапуск покрывающих тестов + приложение отчета о фиксе в тот же файл отчета; затем scoped re-review (только дифф фикса; вердикт по каждой находке ADDRESSED / NOT ADDRESSED + новые поломки только в диффе фикса). Новые Critical/Important в диффе фикса — в список открытых; вне-скоуп наблюдения — в журнал как deferred minors, цикл не расширяют.

Предохранитель (breaker): после раунда 5 — стоп диспетчеризации, adjudикация каждой открытой находки контроллером:

• ревьюер неправ или спорно — припарковать: Task <N>: parked — <находка> — Ruling: <почему код стоит>;
• реально, но ничего на нем не строится — припарковать тем же способом;
• реально и несущее (later task строится на нем / дефект плана) — решение о минимальном изменении, снимающем блок, в журнал и в диспетчер следующей задачи.

Adjudикация только на предохранителе; adjudировать раньше, чтобы закрыть цикл, — предсуждение под другим именем. Каждое решение — строка журнала; молчаливый discard запрещен. Контроллер никогда не правит сам в своей сессии: правки контроллера загрязняют контекст и минуют ревью.

5. Завершение задачи

Чисто (или все открытое припарковано с ruling на предохранителе) — строка журнала в том же сообщении, что и прочий bookkeeping:

Task <N>: complete (commits <base7>..<head7>, review clean)
Task <N>: complete (commits <base7>..<head7>, <K> parked)

Переход к следующей задаче запрещен, пока у ревью есть открытые Critical/Important, не исправленные и не припаркованные с решением.

Выбор моделей

Из раздела Model Selection скилла: использовать наименее мощную модель, которая тянет роль.

• Механические задачи (изолированные функции, ясные спеки, 1-2 файла) — быстрая дешевая модель; большинство задач механичны при хорошем плане.
• Интеграция и суждение (мультифайловая координация) — стандартная.
• Архитектура и дизайн — самая способная; финальное ревью ветки — всегда самая способная модель, не дефолт сессии.
• Ревью — модель по суждению, от размера/сложности/риска диффа; scoped re-reviews маленьких диффов — дешево-средний тир.
• Эскалация цикла фиксов (4-5) — минимум на тир выше застрявшего исполнителя.
• Модель указывается явно при диспетчеризации: пропущенная модель наследует модель сессии — часто самую дорогую, молча сводя раздел на нет.
• Число ходов дороже цены токена: дешевые модели routinely берут 2-3× ходов на многошаговой работе, что дороже в итоге; средний тир — пол для ревьюеров и исполнителей по prose-описаниям. Если текст задачи уже содержит весь код — «транскрипция плюс тестирование», дешевый тир.

Финальное ревью и завершение

Финальное ревью — всей ветки: пакет через scripts/review-package PLAN_FILE MERGE_BASE HEAD (MERGE_BASE — коммит, от которого ответвились), ревьюер — самая способная модель, шаблон code-reviewer.md, вход — пакет, план, спека, Review Focus плана дословно и указатель на строки Ruling: журнала (взвесить решения контроллера). Ревьюеру передаются списки deferred-minors и припаркованных для триажа «что чинить до merge».

Находки финального ревью: один фикс-сабагент со всем списком (не по фиксеру на находку — в реальной сессии волна «по-фиксеру-на-находку» стоила дороже всех задач вместе), затем ровно один scoped re-review волны фикса, затем adjudикация остатков по правилам предохранителя. Второй волны фиксов нет: несущие остатки поднимаются партнеру на этапе finishing (урок 17.12).

Финал: до удаления чего-либо — собрать каждую строку журнала с Ruling: в финальное сообщение («Rulings I made», в порядке принятия, каждая — с ценой ошибки). Список исчерпывающий: это единственное место, где решения, принятые от имени партнера, доходят до него. «Решение, умершее вместе с workspace, — решение, принятое втайне». Финальное ревью чисто и фиксы закоммичены — удалить рабочее пространство плана («git history is the record now»), вызвать finishing-a-development-branch.

Inline-исполнение: executing-plans

Где режим отличается (все прочее — общие правила и эквиваленты):

• Бриф — спека: задача берется через scripts/task-start PLAN_FILE N (бриф и BASE одной командой); бриф читается на каждую задачу, включая «помню ее со setup» — «помните сводку, а в брифе — точные значения, сигнатуры, тест-кейсы».
• TDD — ворота задачи: скилл test-driven-development загружается до задачи 1 и правит каждый шаг; «шаги уже говорят "сначала тест" — не освобождение от его чтения».
• Сверка шагов: каждый шаг с командой имеет Expected:; три исхода — совпало → следующий; код неверен → systematic-debugging (урок 17.13); план неверен → ruling в журнал и дальше.
• Контракт завершения задачи: каждый названный брифом тест существует и прогнан в этой задаче, вывод прочитан; финальный прогон зеленый (scripts/task-done пишет команду и результат в строку журнала); каждое Expected: сверено с реальным выводом; каждое отклонение от брифа — со строкой Ruling:. Управляет заявлением verification-before-completion (урок 17.13).
• Финальное ревью: с инструментом сабагентов — свежий ревьюер на самой способной модели («the one fresh context the whole run buys» — не пропускать и не заменять собственным прочтением диффа); без тула — самому, отдельным проходом после последней задачи, с записью в журнал Final review: self-review (no subagent tool) и явным сообщением партнеру: саморевью автора слабее свежего ревьюера, и партнер решает, достаточно ли этого до merge.
• Фиксы финального ревью: Critical/Important правятся самим в ОДИН проход, каждый фикс по TDD (тест, воспроизводящий находку → RED → GREEN → весь suite), запись: Final: fixed <находка> — <имя теста> RED→GREEN, suite <N>/<N>. «Фикс без упавшего сначала теста не верифицирован».

Отмазки режима (выборка): «помню, что говорит задача N» — помните сводку; «пропущу смотрение, как тест падает» — тест, которого вы не видели падающим, ничего не доказывает; «прогоню весь suite в конце вместо каждого шага» — пошаговые прогоны сообщают, какой шаг сломал; «внимательно прочитал свой дифф — финальный ревьюер избыточен» — тот же автор, те же слепые пятна.

Параллельная работа: dispatching-parallel-agents

Скилл для 2+ независимых задач без общего состояния. Типовой случай: несколько падающих тестов в разных файлах с разными корневыми причинами — исследовать последовательно значит жечь время.

Правила:

• использование: 3+ тест-файлов падают с разными причинами; несколько подсистем сломаны независимо; каждая проблема понятна без контекста остальных; нет общего состояния;
• не использовать: падения связаны (фикс одного может починить остальные — сначала вместе); нужно понимание всей системы; агенты мешали бы друг другу (общие файлы, общие ресурсы);
• паттерн: сгруппировать по доменам → каждому агенту — скоуп (один файл/подсистема), цель, ограничения («не менять другой код»), ожидаемый выход → диспетчеризовать все в одном ответе (несколько вызовов в одном ответе = параллельно; по одному = последовательно);
• интеграция: прочитать сводки каждого, проверить, что фиксы не конфликтуют, полный suite, спот-чек («агенты делают систематические ошибки»).

Промпт-культура скилла: сфокусированный («Fix agent-tool-abort.test.ts», не «fix all the tests»), самодостаточный (вставлены сообщения об ошибках и имена тестов), с ограничениями и конкретным ожидаемым выходом («Return: summary of root cause and changes»).

Связь с subagent-driven: исполнители задач плана не параллелятся (конфликты по определению последовательного плана); параллелятся независимые домены — например, волна исследований падений.

Практика

Возьмите план из практики урока 17.8 и:

1. выберите режим исполнения и обоснуйте по критериям урока;
2. для каждой пары задач, делящих интерфейс, напишите строку pre-flight-скана;
3. проиграйте цикл одной задачи на бумаге: бриф → статус отчета → пакет ревью → вердикты; при Critical — сымитируйте раунд 1 и scoped re-review;
4. напишите финальное сообщение: список rulings и deferred minors.

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

Исполнение плана — два режима: subagent-driven (свежий исполнитель на задачу, двухступенчатое ревью каждой, широкое финальное; основательнее, дороже) и executing-plans (инлайн, TDD-ворота на задачу, одно свежее финальное ревью; дешевле). Общих правил: непрерывность (стопы — только четыре), rulings-не-стопы с записью в журнал, журнал как защита от компакции.

• Цикл задачи: бриф → отчет (4 статуса) → ревью (spec + quality, без предсуждения) → цикл фиксов ≤5 раундов (1-3 тот же исполнитель, 4-5 свежий и способнее) → scoped re-review каждый раунд.
• Предохранитель: adjudикация на капе, каждая находка — припаркована с ruling или закрыта решением; молчаливые discard запрещены.
• Модели: минимум тянущий для роли; финальное ревью — самая способная; модель указывается явно; ходы дороже токенов.
• Финал: rulings и deferred minors — исчерпывающе в финальном сообщении; git history — запись.
• Параллелятся только независимые домены, не исполнители одного плана.

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

1. По каким осям сопоставляются два режима исполнения? Когда инлайн предпочтительнее даже при наличии инструмента сабагентов?
2. Что такое журнал, зачем он нужен при компакции и почему «доверять журналу и git log, а не своей памяти»?
3. Опишите цикл фиксов: три раунда — что, четвертый-пятый — что и почему; что такое scoped re-review и что он не делает?
4. Что означает «не предсуждать находки ревьюера»? Приведите фразы-нарушители.
5. Почему финальное ревью ветки диспетчеризуется на самой способной модели и почему в inline-режиме его нельзя заменять собственным прочтением диффа?
6. Почему исполнители одного плана не диспетчеризуются параллельно, а исследования падений — можно? Критерий.

Что дальше

План исполнен задача за задачей; на каждой задаче работал скилл, которому посвящен следующий урок, 17.10: test-driven-development — цикл RED-GREEN-REFACTOR, железный закон «нет кода без упавшего теста» и антипаттерны тестирования.

Источники

• https://github.com/obra/superpowers/blob/main/skills/subagent-driven-development/SKILL.md