Написание планов

Обзор

Пишите исчерпывающие планы реализации, исходя из того, что у инженера ноль контекста о нашей кодовой базе и сомнительный вкус. Документируйте всё, что ему нужно знать: какие файлы трогать в каждой задаче, код, тестирование, какую документацию стоит проверить, как это тестировать. Дайте ему весь план мелкими задачами. DRY. YAGNI. TDD. Частые коммиты.

Считайте, что это умелый разработчик, но он почти ничего не знает о нашем инструментарии и предметной области. Считайте, что он не очень хорошо знает дизайн тестов.

Объявите в начале: «Я использую скилл writing-plans, чтобы составить план реализации.»

Контекст: если работа идёт в изолированном worktree, он должен был быть создан через скилл superpowers:using-git-worktrees на этапе исполнения.

Сохраняйте планы в: docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

• (Предпочтения пользователя по расположению плана переопределяют этот путь по умолчанию)

Проверка объёма

Если спецификация охватывает несколько независимых подсистем, она должна была быть разбита на спецификации подпроектов ещё на брейнсторминге. Если нет — предложите разбить это на отдельные планы, по одному на подсистему. Каждый план должен сам по себе давать работающее, тестируемое ПО.

Структура файлов

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

• Проектируйте единицы с чёткими границами и хорошо определёнными интерфейсами. У каждого файла одна ясная ответственность.
• Вы лучше всего рассуждаете о коде, который умещается в контексте целиком, а правки надёжнее, когда файлы сфокусированы. Предпочитайте меньшие, сфокусированные файлы большим, делающим слишком много.
• Файлы, меняющиеся вместе, должны жить вместе. Делите по ответственности, а не по техническому слою.
• В существующих кодовых базах следуйте устоявшимся паттернам. Если в кодовой базе большие файлы — не перестраивайте всё в одностороннем порядке; но если файл, который вы меняете, разросся до неуправляемого, включить его разбиение в план разумно.

Эта структура определяет декомпозицию задач. Каждая задача должна давать самодостаточные изменения, осмысленные независимо.

Правильный размер задачи

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

Гранулярность мелких задач

Каждый шаг — одно действие (2–5 минут):

• «Написать падающий тест» — шаг
• «Запустить его, чтобы убедиться, что падает» — шаг
• «Написать минимальный код, чтобы тест прошёл» — шаг
• «Прогнать тесты и убедиться, что проходят» — шаг
• «Закоммитить» — шаг

Заголовок документа плана

Каждый план ОБЯЗАН начинаться с этого заголовка:

# [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]

## Global Constraints

[The spec's project-wide requirements — version floors, dependency limits,
naming and copy rules, platform requirements — one line each, with exact
values copied verbatim from the spec. Every task's requirements implicitly
include this section.]

---

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

### 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: [what this task uses from earlier tasks — exact signatures]
- Produces: [what later tasks rely on — exact function names, parameter
  and return types.]

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

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: Write minimal implementation**
- [ ] **Step 4: Run test to verify it passes**
- [ ] **Step 5: Commit**

Никаких заглушек

Каждый шаг должен содержать реальное содержимое, нужное инженеру. Это провалы плана — никогда так не пишите:

• «TBD», «TODO», «реализовать позже», «заполнить детали»
• «Добавить подходящую обработку ошибок» / «добавить валидацию» / «обработать краевые случаи»
• «Написать тесты к вышесказанному» (без реального кода тестов)
• «Аналогично задаче N» (повторите код — инженер может читать задачи не по порядку)
• Шаги, описывающие что делать, но не показывающие как (для кодовых шагов обязательны блоки кода)
• Ссылки на типы, функции или методы, не определённые ни в одной задаче

Помните

• Всегда точные пути файлов
• Полный код в каждом шаге — если шаг меняет код, покажите код
• Точные команды с ожидаемым выводом
• DRY, YAGNI, TDD, частые коммиты

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

После написания полного плана посмотрите на спецификацию свежим взглядом и сверьте план с ней. Это чек-лист, который вы прогоняете сами, а не диспетчеризация субагента.

1. Покрытие спецификации: пробегитесь по каждому разделу/требованию спецификации. Можете ли указать задачу, которая его реализует? Перечислите пробелы.

2. Скан заглушек: поищите в плане красные флаги — любые паттерны из раздела «Никаких заглушек». Исправьте их.

3. Согласованность типов: совпадают ли типы, сигнатуры методов и имена свойств в поздних задачах с тем, что вы определили в ранних? Функция clearLayers() в задаче 3, но clearFullLayers() в задаче 7 — это баг.

Если нашли проблемы — исправьте по месту. Перепроверять не нужно — просто исправьте и двигайтесь. Если нашли требование спецификации без задачи — добавьте задачу.

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

После сохранения плана предложите выбор исполнения:

«План готов и сохранён в docs/superpowers/plans/<filename>.md. Два варианта исполнения:

1. Через субагентов (рекомендуется) — я отправляю свежего субагента на каждую задачу, ревью между задачами, быстрая итерация

2. Инлайн-исполнение — выполняю задачи в этой сессии через executing-plans, пакетное исполнение с контрольными точками

Какой подход?»

Если выбрано «Через субагентов»: ОБЯЗАТЕЛЬНЫЙ САБ-СКИЛЛ — используйте superpowers:subagent-driven-development. Свежий субагент на задачу + двухэтапное ревью.

Если выбрано «Инлайн-исполнение»: ОБЯЗАТЕЛЬНЫЙ САБ-СКИЛЛ — используйте superpowers:executing-plans. Пакетное исполнение с контрольными точками для ревью.