writing-plans

計画の作成

概要

このコードベースや仕様を見たことのないエンジニア向けに、実装計画を作成します。正確なインターフェースとテストがわかれば、プロジェクトの言語に沿ったコードを書けること、また、計画で選択肢が残されている部分は妥当な判断ができることを前提とします。計画を読むだけではわからないのは、あなたが決めたことです。どのファイルを使うのか、どの名前とシグネチャにするのか、仕様のどの値を使うのか、各タスクをどのテストで証明するのかを記録してください。計画全体を、取り組みやすい小さなタスクに分けて提示します。DRY。YAGNI。TDD。こまめにコミットします。

最初に宣言: 「実装計画を作成するため、writing-plans スキルを使用します。」

コンテキスト: 隔離されたワークツリーで作業する場合は、実行時に superpowers:using-git-worktrees スキルを使って作成しておく必要があります。

計画の保存先: docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

• （計画の保存先についてユーザーの希望がある場合は、こちらを優先します）

スコープの確認

仕様が複数の独立したサブシステムを対象としている場合は、ブレインストーミングの段階でサブプロジェクトごとの仕様に分割しておく必要があります。分割されていない場合は、サブシステムごとに個別の計画を作成するよう提案してください。各計画は、それ単独で動作し、テスト可能なソフトウェアを成果物とする必要があります。

ファイル構成

タスクを定義する前に、作成または変更するファイルと、それぞれが担う役割を整理してください。ここで分解の方針を確定します。

• 境界が明確で、インターフェースが適切に定義された単位を設計してください。各ファイルが担う役割は、一つに明確に絞ります。
• 一度に把握できるコードの範囲には限りがあり、ファイルごとの役割を絞るほど編集の信頼性も高まります。多くの役割を担う大きなファイルよりも、小さく、役割を絞ったファイルを優先してください。
• 同時に変更するファイルは、近くに配置してください。技術レイヤーではなく、役割ごとに分割します。
• 既存のコードベースでは、確立されたパターンに従ってください。コードベースで大きなファイルが使われている場合、独断で再構成しないでください。ただし、変更対象のファイルが扱いにくいほど大きくなっているなら、計画に分割を含めるのは妥当です。

この構成をもとに、タスクを分解します。各タスクは、単独で意味のある自己完結した変更を成果物とする必要があります。

タスクの適切な規模

タスクとは、それ自体でテストサイクルを実施でき、新たなレビュアーによる確認に値する最小単位です。タスクの境界を決める際は、セットアップ、設定、足場づくり、ドキュメント作成の手順を、それらを必要とする成果物のタスクに含めてください。隣接するタスクを別々に承認するかどうかをレビュアーが有意義に判断できる場合に限り、分割してください。各タスクの完了時には、個別にテスト可能な成果物ができている必要があります。

ステップの粒度

各ステップは、確認可能な結果を伴う一つの作業です。

• 「失敗するテストを書く」—ステップ
• 「失敗することを確認するために実行する」—ステップ
• 「テストを通す最小限のコードを実装する」—ステップ
• 「テストを実行し、成功することを確認する」—ステップ
• 「コミットする」—ステップ

計画ドキュメントのヘッダー

すべての計画は、必ず次のヘッダーで始めます。

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

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

## Review Focus

[The five input classes or failure modes the spec implies but no task's
tests exercise that are most likely to bite a person using this software
— one line each, naming the input or condition and the behavior a
reasonable person would expect, most likely first. The spec is a vision
document: it says what the software must do, not everything it will
meet, and its silence on an input is not permission for that input to
break the program. Write the list here, once, with the spec in front of
you. Then, for each line, add the test that pins it to the task that
owns the code, in that task's own step style.]

---

タスクの構成

### 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. A task's implementer sees only their own task; this
  block is how they learn the names and types neighboring tasks use.]

- [ ] **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`**

One line on the approach when the signature and the test leave a choice
(which library call, which data structure); a code block only for an
algorithm they do not determine.

- [ ] **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"
```

ステップに含める内容

実装者がそのステップから、妥当なものをちょうど1つ書けるなら、そのステップは完了です。要件はそれだけです。曖昧でないことが重要であり、網羅的である必要はありません。各ステップには、曖昧さをなくすために必要な内容だけを含めます。

• テストのステップ： テスト名とアサーションをコードで示し、仕様の正確な値を含めます。
• コードのステップ： 正確なシグネチャ（名前、パラメーター、戻り値の型）、そのコードが置かれるファイル、仕様で固定されている具体的な値を示します。本文は実装者が書きます。本文を記載するのは、シグネチャとテストからは決まらないアルゴリズムの場合、または仕様で正確な内容が固定されているコピーの場合だけです。
• 検証のステップ： 実行するコマンドと、成功を示す出力を記載します。
• 別のタスクへの参照： 使用する内容は、そのタスクの Interfaces ブロックに記載します。計画では、そのタスクのコードを繰り返しません。

計画とは、実装者が単独では決められない事項をまとめたものです。計画が説明対象のコードより長いなら、それはコードそのものを書いてしまっています。「TBD」「エッジケースを処理する」「適切な検証を追加する」「上記のテストを書く」、あるいはどのタスクにも定義されていない型や関数のように、何も決めない行はその逆の問題です。セルフレビューでは、どちらの問題も見つけます。

セルフレビュー

計画をすべて書き終えたら、仕様を新たな視点で見直し、計画と照らし合わせます。これは自分で行うチェックリストであり、サブエージェントへの委任ではありません。

1. 仕様の網羅性： 仕様の各セクションと要件に目を通します。それぞれを実装するタスクを指し示せますか？ 抜けている項目を列挙します。

2. ステップの確認： すべてのステップで、実装者が妥当なものをちょうど1つ書ける必要があります。また、1つを超える内容を含めてはいけません。何も決めない行は不足であり、シグネチャとテストですでに決まっている関数本文は書き起こしです。両方を修正します。

3. 型の一貫性： 後のタスクで使う型、メソッドシグネチャ、プロパティ名は、前のタスクで定義したものと一致していますか？ タスク3で clearLayers() と呼んでいる関数を、タスク7で clearFullLayers() と呼んでいるのはバグです。

4. レビューの重点項目： 仕様から想定される各入力クラスまたは失敗モードについて、それをテストで検証するタスクがありますか？ 見落とされると最も問題になりそうな5つを「レビューの重点項目」セクションに記載し、それぞれのテストを該当するタスクに追加します。セクションが空なら、確認したうえで該当項目がなかったことを意味します。確認を省略したという意味ではありません。

5. 分量の釣り合い： 計画の長さを仕様の長さと比べます。実装対象の仕様より計画が何倍も長いなら、それは計画ではなく、プログラムの書き起こしです。コードブロックが文書の大部分を占める場合は、本文をシグネチャ、テスト名、アサーションに置き換え、各ステップがそれでも曖昧でないことを確認します。

問題が見つかったら、その場で修正します。再レビューは不要です。そのまま修正して先に進みます。タスクがない仕様要件を見つけた場合は、そのタスクを追加します。

実行の引き継ぎ

計画を保存してセルフレビューしたら、人間のパートナーが読めるようにリンクを共有します。実行方法がすでに明示されている場合は、その方法を計画に反映できているか確認するため、計画をレビューするよう依頼します。実装に進むのは、そのレビューが終わってからです。その後、記録された方法を使用します。それ以外の場合は、実装に進む前に計画をレビューし、実行方法を選ぶよう依頼します。

実行方法がまだ指定されていない場合：

「計画を作成し、docs/superpowers/plans/<filename>.md に保存しました。計画をレビューしてください。どの実行方法をご希望ですか？

• サブエージェント駆動 - タスクごとに新しいサブエージェントが実装し、次のタスクを始める前に別の新しいレビュアーが確認します。最後にブランチ全体をレビューします。最も徹底的ですが、タスクごと、レビューごとに新しいコンテキストが必要です。
• ネイティブ - このハーネスでの作業方法に従い、このセッションですべてのタスクを自分で実装した後、最も高性能なモデルを使う新しいレビュアーがブランチ全体を確認します。最も低コストで最速ですが、最後まで独立したレビューはありません。計画に設計が記載されているため、中程度のモデルを使うセッションでもうまく実行できます。

この計画では、<2つの方法のいずれか>をおすすめします。理由は、<タスク間でインターフェースがどの程度相互依存するか、タスクがいくつあるか、リリース時のミスがどれほどの損失につながるかを示す、計画からの一文>です。計画の内容はご希望に沿っていますか？どちらの方法で進めましょうか？」

実行方法がすでに指定されている場合：

「計画を作成し、docs/superpowers/plans/<filename>.md に保存しました。計画をレビューしてください。内容はご希望に沿っていますか？」

サブエージェント駆動が選択された場合：

• 必須のサブスキル： superpowers:subagent-driven-development を使用してください

ネイティブが選択された場合：

• 必須のサブスキル： superpowers:executing-plans を使用してください