writing-plans

計画の作成

概要

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

スキルの高い開発者ではあるものの、こちらのツールセットや問題領域についてはほとんど知らないものとします。適切なテスト設計についても、あまり詳しくないものとします。

最初に告知します：「writing-plans スキルを使って、実装計画を作成します。」

**コンテキスト：**計画の作成は読み取り専用です。plan エージェントが書き込めるのは docs/plans/* と docs/specs/* のみです。現在のチェックアウト内に計画を作成してください。作業ツリーは実行時に作成されます（実装開始前に executing-plans / subagent-driven-development を実行するときに呼び出される using-git-worktrees を参照してください）。

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

• ユーザーが計画の保存先を指定している場合は、その指定を優先します。

スコープの確認

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

ファイル構成

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

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

この構成をもとに、タスクを分解します。各タスクで、単独で意味を成す変更を完了させてください。

取り組みやすいタスクの粒度

各ステップは、2～5分でできる一つの作業です。

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

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

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

# [Feature Name] Implementation Plan

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

増分ファイル書き込み（重大）

モデルは大きなファイルを1回の呼び出しで出力できません。 各編集または書き込み操作で出力できるのは約1000トークンまでです。これを超えると、API はエラー 500 で失敗します。これはベストプラクティスではなく、基盤となるモデルの厳格な制限です。

すべてのファイル作成や大規模な編集は、各ステップで新たに生成する内容が約1000トークンを超えないよう、順次、段階的に分割する必要があります。

1. ステップ1：骨組みを書く — インポート、クラス／関数のシグネチャ、型定義、セクションコメントを含むファイルを作成します。実装本体はまだ書きません。
2. ステップ2以降：セクションを一つずつ埋める — 1ステップにつき、関数、クラスメソッド、または論理的なセクションを1つ実装するようにファイルを編集します。各編集で置き換える範囲は、約1000トークン以下に絞ります。
3. 最終ステップ：最終確認 — ファイル全体を読み、一貫性を修正してからコミットします。

計画書そのものについて： 計画書は大きなファイルになることがよくあります。次のように複数回に分けて書きます。

• パス1： ヘッダー、ファイル構成マップ、タスクの概要を書く（コード本体は書かない）
• パス2以降： 各タスクのコードブロックを一つずつ埋めるように計画書を編集する（1回の編集につき約1000トークン）
• パス3： 自己レビューを行い、問題を修正して最終版を保存する

タスク構成において、大きなファイルは次のようになります。

- [ ] **Step 1: Write file skeleton**

Create `src/path/to/largefile.py` with imports, class definitions, method signatures, and TODO comments for each section.

- [ ] **Step 2: Implement Section A**

Edit `src/path/to/largefile.py` — replace the TODO for Section A with the actual implementation (~1000 tokens).

- [ ] **Step 3: Implement Section B**

Edit `src/path/to/largefile.py` — replace the TODO for Section B with the actual implementation (~1000 tokens).

- [ ] **Step 4: Final review and commit**

Read the complete file. Fix any inconsistencies. Commit.

単一のステップで約1000トークンを超える出力を生成する計画は、絶対に立てないでください。 ファイルが大きい場合、そのファイルに対して複数のステップを計画に含める必要があります。

プレースホルダー禁止

すべてのステップには、エンジニアが必要とする実際の内容を含める必要があります。次のような記述は計画の失敗にあたります。絶対に記載しないでください。

• 「TBD」、「TODO」、「後で実装する」、「詳細を記入する」
• 「適切なエラー処理を追加する」／「検証を追加する」／「エッジケースに対応する」
• 「上記のテストを書く」（実際のテストコードを含めない場合）
• 「タスクNと同様」（タスクを順不同で読むエンジニアがいるため、コードを繰り返し記載してください）
• コードの手順なのに、実行方法を示さず、何をするかだけを説明すること（コードブロックが必要です）
• どのタスクでも定義されていない型、関数、メソッドへの参照

注意事項

• ファイルパスは常に正確に記載する
• 各ステップに完全なコードを含める — ステップでコードを変更する場合は、そのコードを示す
• 期待される出力を含め、コマンドを正確に記載する
• DRY、YAGNI、TDD、頻繁なコミットを徹底する

自己レビュー

計画書全体を書き終えたら、新たな視点で仕様を見直し、計画書と照合します。これは自分で実施するチェックリストであり、サブエージェントへの依頼ではありません。

1. 仕様の網羅性： 仕様の各セクション／要件をざっと確認します。それぞれを実装するタスクを示せますか？ 抜け漏れがあれば列挙します。

2. プレースホルダーの確認： 上記の「プレースホルダー禁止」セクションに挙げたパターンなど、問題のある記述がないか計画書を検索します。見つけたら修正します。

3. 型の一貫性： 後続のタスクで使用する型、メソッドのシグネチャ、プロパティ名が、先行するタスクで定義した内容と一致しているか確認します。タスク3では clearLayers() と呼び、タスク7では clearFullLayers() と呼ぶような関数があると、バグになります。

問題が見つかった場合は、その場で修正します。改めてレビューする必要はありません。修正して先に進みます。タスクのない仕様要件が見つかった場合は、そのタスクを追加します。

実行の引き継ぎ

計画書を保存したら、実行方法を選べるようにします。

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

1. サブエージェント主導（推奨） - subagent ツールを使ってタスクごとに新しいサブエージェントを起動し、タスク間でレビューします。迅速に反復できます。

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

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

サブエージェント主導が選ばれた場合：

• 必須のサブスキル： subagent-driven-development を使用する
• タスクごとに新しいサブエージェントを起動し、仕様レビュー、品質レビューの順に実施する。セキュリティに関わるタスクでは、さらにセキュリティレビューを行う

インライン実行が選ばれた場合：

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