writing-plans

計画の作成

概要

コードベースについて前提知識がなく、判断があまり得意ではないエンジニアを想定して、包括的な実装計画を作成します。各タスクで変更するファイル、コード、テスト、確認が必要なドキュメント、テスト方法など、必要な情報をすべて記載してください。計画全体を小さなタスクに分割します。DRY。YAGNI。こまめにコミットします。

優れた開発者であることは前提としますが、使用するツールセットや問題領域についてはほとんど知らないものとします。優れたテスト設計にあまり詳しくないことも前提とします。

最初に告知します： 「実装計画を作成するため、superjawn:writing-plans スキルを使用しています。」

コンテキスト： 専用のワークツリー（superjawn:using-git-worktrees を使って設定）で実行します。

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

• ユーザーの計画保存先に関する希望は、この既定値より優先されます。

スコープの確認

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

ファイル構成

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

• 明確な境界と定義済みのインターフェースを持つ単位として設計します。各ファイルには、明確な責任をひとつだけ持たせます。
• 一度に把握できるコードほど適切に推論でき、ファイルに焦点を絞るほど編集の信頼性が高まります。大きく何でもこなすファイルよりも、小さく焦点の定まったファイルを優先してください。
• 一緒に変更するファイルは、同じ場所にまとめます。技術レイヤーではなく、責任に応じて分割してください。
• 既存のコードベースでは、確立されたパターンに従ってください。コードベースで大きなファイルが使われている場合、一方的に再構成しないでください。ただし、変更対象のファイルが扱いにくいほど肥大化している場合は、計画に分割を含めてもかまいません。

この構成をもとにタスクを分解します。各タスクでは、それだけで完結し、単独でも意味のある変更を行う必要があります。

小さなタスクへの分割

各ステップはひとつの作業（2～5分）にします：

• 現在の動作を示すチェックを実行する — 1ステップ
• 最小限の変更を実装する — 1ステップ
• 同じチェックを実行し、期待どおりの結果を確認する — 1ステップ
• コミットする — 1ステップ

再発の可能性が高い不具合、安定した契約、わかりにくいロジック、または影響の大きい動作を防ぐ場合に限り、新しいテストを追加してください。期待値は仕様または実際のデータから取得し、新しいコードの出力から取得しないでください。

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

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

# [Feature Name] Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superjawn:subagent-driven-development (recommended) or superjawn: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 (only when the task keeps a new test): `tests/exact/path/to/test.py`

**Check:** [The command that proves this task, and why it is the cheapest faithful evidence]

- [ ] **Step 1: Run the check that shows current behavior**

Use an existing test or a focused command when it proves the behavior:

Run: `python -m mypkg.cli convert sample.csv`
Expected: exit 1 with "unsupported column type: date"

When the task keeps a new test, write it first and take the expected value
from the spec or real data:

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected  # expected value from the spec or real data
```

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

- [ ] **Step 2: Write minimal implementation**

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

- [ ] **Step 3: Run the same check to verify the result**

Run: the same command as Step 1
Expected: the behavior the spec requires (for example, exit 0, or PASS)

- [ ] **Step 4: Commit**

```bash
git add src/path/file.py  # add tests/path/test.py only if the task kept a test
git commit -m "feat: add specific feature"
```

プレースホルダー禁止

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

• 「TBD」「TODO」「後で実装する」「詳細を記入する」
• 「適切なエラー処理を追加する」「検証を追加する」「エッジケースに対応する」
• 実際のテストコードを示さない「上記のテストを書く」
• 「タスク N と同様」（タスクを読む順序が前後する場合もあるため、コードを繰り返し記載してください）
• どのように作業するかを示さないステップ（コードのステップではコードブロックが必要です）
• どのタスクでも定義されていない型、関数、メソッドへの言及

忘れずに

• ファイルパスを正確に記載する
• コードを変更するステップでは、完全なコードを記載する
• 期待される出力を含む、正確なコマンドを記載する
• DRY、YAGNI、テストは適切な規模で、こまめにコミットする

セルフレビュー

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

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

2. プレースホルダーの確認： 計画内を検索し、上記の「プレースホルダーなし」セクションにあるパターンなど、問題の兆候がないか確認します。見つかったものは修正してください。

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

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

実行の引き継ぎ

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

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

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

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

どちらの方法にしますか？」

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

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

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

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