Урок 17.8. Writing-plans: план для исполнителя без контекста

Дополнительный источник: https://lzw.me/docs/opencodedocs/obra/superpowers/core-workflows/planning-workflow/index.html

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

Третий шаг базового workflow (урок 17.5): спека согласована (урок 17.6), рабочее дерево изолировано и бейзлайн зеленый (урок 17.7). Теперь план. Общие принципы планирования курса разбирались в модуле 4; здесь — перевод скилла writing-plans, и его специфика в том, что план пишется не для человека и не для «вас с агентом вместе», а для исполнителя, который не видел ни кодовую базу, ни обсуждение. Это прямое следствие исполнения сабагентами (урок 17.9): свежий сабагент на каждую задачу имеет только то, что вы ему дали, — и план обязан это компенсировать.

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

Формула скилла из Overview (перевод): пишите план для инженера, который не видел ни кодовую базу, ни спеку. Предполагайте, что он пишет идиоматичный код, зная точный интерфейс и точный тест, и примет разумное решение там, где план оставляет выбор открытым. Чего он знать не может — ваших решений: какие файлы, какие имена и сигнатуры, какие значения из спеки, какие тесты доказывают каждую задачу. Вот это документируйте. Весь план — задачи-укусы (bite-sized). DRY. YAGNI. TDD. Частые коммиты.

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

Планы сохраняются в docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md (предпочтения пользователя перекрывают путь). Скилл объявляется в начале: «I'm using the writing-plans skill to create the implementation plan».

Структура плана: заголовок

Каждый план обязан начинаться с заголовка (шаблон скилла, выдержка в оригинале):

markdown
# [Feature Name] 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:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

**Spec:** [path to the spec/design doc this plan implements — the plan
argues from the spec, so the spec travels with it; executors read both]

Разделы заголовка, требующие пояснения:

Global Constraints — проектные требования из спеки: минимальные версии, лимиты зависимостей, правила именования, платформенные требования — по строке на требование, с точными значениями дословно из спеки. Каждая задача неявно включает этот раздел.
Review Focus — до пяти классов входных данных или режимов отказа, которые спека подразумевает, но ни один тест задач не проверяет: по строке на каждый, с названием входа/условия и поведения, которого ждет разумный человек. Спозиционировано так: «спека — документ видения: молчание спеки про вход — не разрешение этому входу ломать программу». Для каждой строки добавляется тест, закрепленный за задачей, владеющей кодом.

Задачи: right-sizing и гранулярность шагов

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

Гранулярность шага. Каждый шаг — одно действие с проверяемым результатом; пять шагов — канонический цикл TDD:

«Написать падающий тест» — шаг;
«Запустить и убедиться, что падает» — шаг;
«Реализовать минимальный код, чтобы тест прошел» — шаг;
«Запустить тесты и убедиться, что проходят» — шаг;
«Закоммитить» — шаг.

Структура задачи

Шаблон задачи (выдержка в оригинале):

markdown
### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`

**Interfaces:**
- Consumes: [что задача берет из предыдущих — точные сигнатуры]
- Produces: [на что опираются следующие — точные имена функций,
  параметры и типы. Исполнитель видит только свою задачу; этот блок —
  то, как он узнает имена и типы соседних задач.]

- [ ] **Step 1: Write the failing test**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

- [ ] **Step 2: Run test to verify it fails**

Run: `pytest tests/path/test.py::test_name -v`
Expected: FAIL with "function not defined"

- [ ] **Step 3: Implement `function(input: InputType) -> ResultType` in `exact/path/to/file.py`**

- [ ] **Step 4: Run test to verify it passes**

Run: `pytest tests/path/test.py::test_name -v`
Expected: PASS

- [ ] **Step 5: Commit**

```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```

Блок Interfaces — сердце задачи: исполнитель видит только свою задачу; Produces/Consumes — единственный способ узнать имена и типы, которые используют соседи. Отсюда же правило File Structure (см. ниже): решение о разбиении файлов фиксируется здесь, до задач.

Что содержит шаг

Шаг выполним, когда исполнитель может написать по нему ровно одну разумную вещь. По типам шагов:

Тестовый шаг: имя теста и его утверждения — кодом, с точными значениями из спеки.
Кодовый шаг: точная сигнатура (имя, параметры, тип результата), файл, конкретные значения, которые спека закрепляет. Тело пишет исполнитель; тело появляется в плане только для алгоритма, который сигнатура и тесты не определяют.
Верификационный шаг: команда для запуска и вывод, который означает успех.
Ссылка на другую задачу: интерфейс той задачи говорит, что использовать; план не повторяет ее код.

Встречные крайности (обе — ошибки): строка, которая ничего не решает (пробел) и тело функции, уже определенное сигнатурой и тестами (транскрипт).

Структура файлов до задач

До определения задач планируется, какие файлы создаются/меняются и за что каждый отвечает. Здесь фиксируются решения о декомпозиции:

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

Scope check: спека с несколькими независимыми подсистемами должна была быть разбита еще в brainstorming (урок 17.6); если нет — предложить разбиение на отдельные планы, по плану на подсистему, каждый дает работающее тестируемое ПО сам по себе.

Самопроверка плана

После написания — взгляд на спеку свежими глазами (чек-лист, который прогоняет сам автор плана, не сабагент):

Покрытие спеки: на каждый раздел/требование можно указать задачу, которая его реализует; пробелы — в список.
Скан шагов: каждый шаг позволяет написать ровно одну разумную вещь; строка, ничего не решающая, — пробел; тело, определенное сигнатурой и тестами, — транскрипт. Исправить оба.
Согласованность типов: сигнатуры и имена из поздних задач совпадают с определенными в ранних. «Функция clearLayers() в задаче 3, но clearFullLayers() в задаче 7 — баг».
Review Focus: для каждого подразумеваемого класса входов есть задача, чьи тесты его проверяют; пять самых кусачих непроверенных — в Review Focus, и каждый получает тест в задаче-владельце. Пустой раздел означает «проверил, не нашел», а не «пропустил проверку».
Пропорция: план, в разы длиннее спеки, которую он реализует, — транскрипт программы, а не план. Если кодовые блоки — большая часть документа, заменить тела сигнатурами, именами тестов и утверждениями.

Найдено — исправляется инлайн, без перепроверки; требование спеки без задачи — добавить задачу.

Передача исполнения

После сохранения и самопроверки план передается партнеру: ссылка на файл и просьба ревьюить. Если способ исполнения еще не выбран — дословная формула скилла (сокращенный перевод):

Plan complete and saved to `docs/superpowers/plans/<filename>.md`.
Please review the plan. Which execution approach would you prefer?

- Subagent-driven — свежий сабагент на каждую задачу и свежий ревьюер
  перед следующей; в конце — ревью всей ветки. Основательнее всего;
  платит свежим контекстом за каждую задачу и каждое ревью.
- Native — я реализую все задачи сам в этой сессии, затем один свежий
  ревьюер на самой способной модели проверяет всю ветку. Дешевле и
  быстрее; независимого ревью до конца нет. Хорошо идет на средне-уровневой
  модели сессии: план несет дизайн.

Для этого плана я рекомендую <один из двух>, потому что <строка из плана:
насколько задачи зависят от интерфейсов друг друга, сколько их, чего стоит
ошибка>. План отражает то, что вы хотите, и какой подход используем?

Если способ уже задан — вопрос только о том, что план отражает желаемое. Выбор «Subagent-driven» подключает subagent-driven-development, «Native» — executing-plans; оба — урок 17.9.

Практика

Возьмите небольшую согласованную задачу (или сделайте дизайн bounded-правки из практики урока 17.6) и напишите план по шаблону скилла:

Заголовок: Goal, Architecture, Tech Stack, Spec; Global Constraints с точными значениями.
File Structure: какие файлы, кто за что отвечает.
Две-три задачи с блоками Files/Interfaces и шагами RED→GREEN→Commit.
Прогоните самопроверку по пяти пунктам; найденные пробелы закройте инлайн.

Сверьте результат с критерием: может ли исполнитель, не видевший обсуждения, написать по каждой задаче ровно одну разумную вещь?

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

writing-plans пишет план для исполнителя без контекста: ваши решения (файлы, имена, значения, тесты) — документируются; остальное — оставлено исполнителю. Задачи — минимальные единицы с собственным циклом тестов; шаги — однозначные действия с проверяемым результатом, канонический цикл — пять шагов TDD.

Заголовок плана: Goal, Architecture, Tech Stack, Spec + Global Constraints (точные значения) + Review Focus (непроверенные классы входов получают тесты).
Блок Interfaces — канал связи между задачами: исполнитель видит только свою.
План длиннее кода — транскрипт; строка без решений — пробел: самопроверка ловит оба.
Завершается выбором способа исполнения: subagent-driven или native (executing-plans).

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

Кому адресован план и какие категории решений обязан фиксировать автор, а какие оставлять исполнителю?
Что означает «шаг однозначен, а не полон»? Приведите строку-нарушитель каждого из двух типов.
Зачем задачам блок Interfaces и как он связан с тем, что сабагент-исполнитель видит только свою задачу?
Перечислите пять пунктов самопроверки; что проверяет «пропорция»?
Какие два способа исполнения предлагает скилл и от чего зависит рекомендация?

Что дальше

План готов и способ исполнения выбран — урок 17.9 разбирает оба режима: subagent-driven development с двухступенчатым ревью каждой задачи и executing-plans с одним финальным ревью ветки, плюс параллельную диспетчеризацию независимых задач.

Источники

https://github.com/obra/superpowers/blob/main/skills/writing-plans/SKILL.md