writing-plans

計画の作成

概要

コードベースの知識がまったくなく、好みも怪しいエンジニアを想定して、包括的な実装計画を作成します。各タスクで変更するファイル、コード、テスト、確認が必要になる可能性のあるドキュメント、テスト方法など、必要な情報をすべて記載します。計画全体を、取り組みやすい小さなタスクに分割してください。DRY。YAGNI。TDD。こまめにコミットします。

開発者は熟練しているものの、使用するツールセットや問題のドメインについてはほとんど知らないものとします。また、優れたテスト設計についても詳しくないものとします。

開始時に宣言してください: 「writing-plans スキルを使って実装計画を作成します。」

コンテキスト: これは、brainstorming スキルで作成した専用の worktree で実行してください。

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

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

スコープの確認

仕様に複数の独立したサブシステムが含まれている場合は、brainstorming の段階でサブプロジェクトごとの仕様に分割しておく必要があります。分割されていない場合は、サブシステムごとに計画を分けるよう提案してください。各計画は、それ単独で動作し、テスト可能なソフトウェアを生み出すものでなければなりません。

ファイル構成

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

• 境界が明確で、インターフェースが明確に定義された単位を設計してください。各ファイルには、明確な責任を1つだけ持たせてください。
• 一度にコンテキスト内で扱えるコードのほうが、より適切に推論できます。また、ファイルの役割が絞られているほど、編集の信頼性も高まります。大きくて多くの処理を抱えるファイルより、小さく、役割を絞ったファイルを優先してください。
• 一緒に変更するファイルは、同じ場所に配置してください。技術レイヤーではなく、責任ごとに分割してください。
• 既存のコードベースでは、確立されたパターンに従ってください。コードベースで大きなファイルを使っている場合、独断で構成を変更してはいけません。ただし、変更対象のファイルが扱いにくいほど大きくなっている場合は、計画に分割を含めてもかまいません。

この構成をもとにタスクを分解します。各タスクは、単独で意味をなす、自己完結した変更をもたらすものでなければなりません。

タスクを取り組みやすい大きさに分割する

各ステップは1つのアクションにします（2～5分）：

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

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

すべての計画は、必ず次のヘッダーから始めてください。

# [Feature Name] Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers-ruby:subagent-driven-development (recommended) or superpowers-ruby: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]

---

タスクの構成

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

- [ ] **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: Write minimal implementation**

```python
def function(input):
    return expected
```

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

プレースホルダー禁止

各ステップには、エンジニアが必要とする具体的な内容をすべて記載してください。以下は計画の不備にあたるため、絶対に書かないでください。

• 「TBD」「TODO」「後で実装する」「詳細を記入する」
• 「適切なエラー処理を追加する」「検証を追加する」「エッジケースに対応する」
• 「上記の内容のテストを書く」（実際のテストコードを示さない場合）
• 「タスクNと同様」（コードを繰り返さない場合。エンジニアがタスクを順番どおりに読んでいるとは限りません）
• どのように実行するかを示さず、何をするかだけを説明するステップ（コードを書くステップでは、コードブロックが必要です）
• どのタスクでも定義されていない型、関数、メソッドへの参照

留意事項

• ファイルパスは常に正確に記載してください
• 変更するコードは、すべてのステップで完全な形で提示してください
• 期待される出力を含め、コマンドを正確に記載してください
• DRY、YAGNI、TDD、こまめなコミット

セルフレビュー

計画をすべて書き終えたら、新たな視点で仕様を読み直し、計画と照らし合わせてください。これは自分で行うチェックリストであり、サブエージェントに依頼するものではありません。

1. 仕様の網羅性: 仕様の各セクションと要件に目を通します。それぞれを実装するタスクを示せますか？不足があれば列挙してください。

2. プレースホルダーの検索: 計画に警告対象がないか確認します。上記の「プレースホルダー禁止」にあるパターンが含まれていないか探し、見つかったら修正してください。

3. 型の一貫性: 後続のタスクで使う型、メソッドのシグネチャ、プロパティ名が、先行タスクで定義したものと一致していますか？タスク3では clearLayers()、タスク7では clearFullLayers() と呼ぶ、といった不一致はバグです。

問題が見つかったら、その場で修正してください。再レビューは不要です。仕様の要件に対応するタスクがない場合は、そのタスクを追加してください。

実行方法の選択

計画を保存した後、実行方法を選んでもらいます。

「計画が完了し、docs/superpowers/plans/<filename>.md に保存されました。実行方法は2つあります。

1. サブエージェント駆動（推奨） - タスクごとに新しいサブエージェントを割り当て、タスク間でレビューを行いながら、迅速に反復します。

2. インライン実行 - executing-plans を使用し、このセッション内でチェックポイントを設けてタスクをまとめて実行します。

どちらにしますか？」

サブエージェント駆動を選択した場合：

• 必須のサブスキル： superpowers-ruby:subagent-driven-development を使用します
• タスクごとに新しいサブエージェントを使用し、2段階のレビューを行います

インライン実行を選択した場合：

• 必須のサブスキル： superpowers-ruby:executing-plans を使用します
• レビュー用のチェックポイントを設けて、タスクをまとめて実行します