writing-plans

計画の作成

概要

コードベースについての予備知識がなく、判断もあまり頼りにならないエンジニアを想定して、包括的な実装計画を作成します。知っておく必要があることをすべて記載してください。タスクごとに変更するファイル、コード、テスト、確認が必要なドキュメント、テスト方法を明記します。計画全体を、取り組みやすい小さなタスクに分割してください。DRY。YAGNI。TDD。こまめにコミットします。

エンジニアは熟練した開発者ですが、当社のツールセットや問題領域についてはほとんど知らないものとします。また、適切なテスト設計についても、あまり詳しくないものとします。

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

コンテキスト: これは、brainstorming スキルで作成した専用の worktree で実行します。

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

• 計画の保存場所に関するユーザーの希望を尊重してください。この既定の保存先は上書きされる場合があります。

スコープの確認

仕様が複数の独立したサブシステムを対象としている場合は、brainstorming の段階でサブプロジェクトごとの仕様に分割しておく必要があります。分割されていない場合は、サブシステムごとに1つずつ、別々の計画に分けることを提案してください。各計画は、それだけで動作し、テスト可能なソフトウェアを完成させるものとします。

ファイル構成

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

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

この構成をもとに、タスクを分割します。各タスクは、それ単体で意味のある、独立した変更を生み出すものとします。

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

各ステップは1つの作業とし、所要時間は2～5分を目安にします。

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

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

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

# [Feature Name] Implementation Plan

> **For agentic workers:** Use /build or your project's plan execution skill 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() になっているのはバグです。

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

実行の引き継ぎ

計画を保存した後、実行方法を選ぶように案内します。

「計画を完了し、ai-workspace/plans/<filename>.md に保存しました。実行方法は 2 つあります：

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

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

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

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

• 計画のコンテキストを使って、タスクごとに新しいサブエージェントを割り当てます
• 次に進む前に、出力をレビューします

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

• /build（またはプロジェクトの計画実行スキル）を使用します
• レビュー用のチェックポイントを設けて、まとめて実行します