⚡
★ 86.6k

計画の作成

基本原則：各タスクは、コンテキストを持たないエンジニアが2〜5分で完了できる程度の小ささでなければならない。

なぜ計画が重要なのか

計画とは、設計されたものと実際に構築されるものの間の契約です。計画がなければ、実行は即興となり、即興のAI支援開発は一貫性のない、未レビューの、しばしば誤った結果を生み出します。

さらに重要なのは、書かれた計画が監査証跡を作ることです。何かが間違った場合（そしてソフトウェア開発では、何かは必ず最終的に間違います）、計画は何が意図されていたかを教えてくれます。「AIが計画から逸脱した」のか「計画そのものが欠陥だった」のかを区別できるようになります。その区別はデバッグ、事後分析、そして継続的な改善において重要です。

Superpowersでは、計画はブレインストーミングフェーズの後、コードが書かれる前に作成されます。計画はその橋渡し役です。

基本原則の詳細

各タスクは、コンテキストを持たないエンジニアが2〜5分で完了できる程度の小ささでなければならない。

このルールは単純に聞こえますが、深い意味を持っています。

「コンテキストを持たない」とは、このコードベースを一度も見たことがない人にタスクの説明を渡しても、何をすべきか正確にわかるということです。タスクは自己完結しています。完了するために必要なすべての情報がタスクの説明自体に含まれています—正確なファイル、正確なコード、正確なコマンド。

「2〜5分」は強制関数です。タスクの完了にそれ以上かかる場合、タスクは大きすぎます。分解してください。30分かかるタスクには複数の下位決定と複数の失敗ポイントが含まれています。何かが間違った場合、どの部分が失敗したかわかりません。小さなタスクは早く失敗し、明確に失敗し、安価に失敗します。

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

すべての計画ドキュメントは標準化されたヘッダーで始まります：

# 実装計画：[機能名]

**日付：** [YYYY-MM-DD]
**Branch：** [git branch名]
**作成者：** [AIエージェントまたは人間]
**ステータス：** PENDING | IN_PROGRESS | COMPLETE
**仕様参照：** [承認されたブレインストーム仕様へのリンクまたは要約]

## コンテキスト
[1〜3文：この計画が何を実装しているか、なぜか？]

## スコープ
**スコープ内：**
- [構築するもの]

**スコープ外：**
- [構築しないもの — 明示的に]

## 依存関係
- [この計画を開始する前に存在しなければならない前提条件]

ヘッダーは計画をレビューする全員にとっての共通のアンカーポイントを作ります。「スコープ外」セクションは特に重要です—実行中にスコープクリープが忍び込むのを防ぎます。

タスク構造

計画の各タスクはこの形式に従います：

### タスク [N]：[タスクタイトル]

**ステータス：** PENDING
**推定時間：** 2〜5分
**ファイル：** `src/path/to/file.ts`

**何をするか：**
[変更を平易な言葉で説明する1段落]

**正確なコード：**
```typescript
// この変更のための完全なコピー＆ペースト可能なコード
// プレースホルダーなし。「ここを埋める」なし。完全なコードのみ。
export function calculateTotal(items: Item[]): number {
  return items.reduce((sum, item) => sum + item.price, 0);
}

正確なコマンド（該当する場合）：

npm run test -- --testPathPattern=calculateTotal

確認： [このタスクが成功したかどうかを判断する方法]

ロールバック： [何か問題が発生した場合にこのタスクを取り消す方法]


その構造のキーワードは**正確**です。おおよそではありません。「このような感じ」ではありません。正確なファイルパス、正確なコード、正確なコマンド。タスクが実行中に決定を行う必要がある場合、タスクは曖昧すぎます。それらの決定を計画フェーズに戻してください。

---

## 計画におけるDRY

**Don't Repeat Yourself（繰り返しを避ける）**は、コードと同様に計画にも適用されます。

複数のタスクが同じユーティリティ関数を使用する場合、計画はこのユーティリティがタスク3で作成され、後続のタスクはそれに依存することを注記すべきです。使用する各タスクにユーティリティの定義をコピー&ペーストしないでください。

複数のタスクが同じパターンに従う場合（例：「新しいAPI routeを追加する」）、パターンを一度注記し、参照します：「このタスクはタスク2で確立されたrouteパターンに従います。」

DRYな計画は短く、レビューしやすく、タスク間の矛盾が生じにくいです。

---

## 計画におけるYAGNI

**You Aren't Gonna Need It（それは必要ない）**は、計画がブレインストーム仕様で承認されたものだけをカバーすることを意味します。

計画における一般的なYAGNI違反：
- 仕様に記載されていないケースのエラーハンドリングの追加
- 「将来の使用のための」抽象化の作成
- 必要以上のloggingインフラの追加
- 今日は一つの値しかない設定のconfigurationシステムの構築

計画へのすべての追加は承認された仕様にまでトレースできなければなりません。タスクを正当化する仕様の要件を指摘できない場合、そのタスクは計画にあるべきではありません。

---

## 計画におけるTDD

Test-Driven Developmentは計画構造に組み込まれていなければなりません。慣例は：**すべての機能タスクの前にテストタスクが来る**です。

```markdown
### タスク4：注文合計計算の失敗テストを書く
**ファイル：** `src/services/__tests__/order.test.ts`
[タスク5が完了するまで失敗するテストを書く]

### タスク5：注文合計計算を実装する
**ファイル：** `src/services/order.ts`
[タスク4のテストを通過させるコードを書く]

このペアリングはオプションではありません。対応するテストタスクの直前に実装タスクが現れる計画を見た場合、その計画は不完全です。差し戻してください。

スコープ管理

計画は実行開始前にスコープのレビューを受けるべきです。このチェックリストを使用してください：

スコープクリープのシグナル：

  • ブレインストーミングで議論されなかったタスク
  • 「ついでに」とラベル付けされたタスク
  • 承認された仕様と無関係なファイルに触れるタスク
  • タスク数が予想の2倍以上

スコープ削減のシグナル：

  • 既存の機能と重複するタスク
  • 必須ではなく「あったら良い」タスク
  • フォローアップ計画に延期できるタスク

スコープクリープが検出された場合、停止してください。実行を開始しないでください。ブレインストーミングフェーズに戻り、計画を更新する前に新しいスコープの承認を得てください。

レビュープロセス

実行開始前に、計画は構造化されたレビューを経ます：

レビューステージ1：完全性

  • すべてのタスクに明確な説明、正確なコード、正確なファイルパスがあるか？
  • すべての実装タスクにテストタスクがあるか？
  • タスク間の依存関係が明確に記載されているか？
  • 各タスクのロールバックパスが明確か？

レビューステージ2：スコープの整合性

  • すべてのタスクが承認された仕様にまでトレースできるか？
  • スコープ外の項目が明示的に除外されているか？
  • 仕様が要求しているもので欠けているものはないか？

レビューステージ3：タスクサイズ

  • すべてのタスクが2〜5分で完了できるか？
  • 複数の異なる変更を行うタスクはないか？
  • 実行者が設計上の決定を行う必要があるほど曖昧なタスクはないか？

承認

計画は実行開始前に明示的な承認が必要です。ブレインストーミングゲートと同様に、計画ゲートは厳格です：承認された計画なしに実行はありません。

例：よく構造化された計画

# 実装計画：注文発送時のユーザーメール通知

**日付：** 2025-03-15
**Branch：** feature/order-ship-email
**ステータス：** PENDING
**仕様参照：** 2025-03-14承認のブレインストーム — 注文ステータスが「shipped」に変わったときにトランザクションメールを送信する

## スコープ
**スコープ内：** ステータス変更時のメールトリガー、基本メールテンプレート、テストカバレッジ
**スコープ外：** メール設定、購読解除フロー、HTMLテンプレート（プレーンテキストのみ）

---

### タスク1：メールトリガーの失敗テストを書く
**ファイル：** `src/services/__tests__/order.service.test.ts`
**コード：** [ステータスが「shipped」のときにsendEmailが呼ばれることを期待するテスト]

### タスク2：OrderServiceにメールトリガーを実装する
**ファイル：** `src/services/order.service.ts`
**コード：** [newStatus === "shipped"のときにupdateStatus()でemailService.send()を呼ぶ]

### タスク3：メールテンプレートの失敗テストを書く
**ファイル：** `src/email/__tests__/order-shipped.template.test.ts`
**コード：** [テンプレートの出力に注文IDと追跡番号が含まれることをテスト]

### タスク4：メールテンプレートを実装する
**ファイル：** `src/email/order-shipped.template.ts`
**コード：** [注文IDと追跡番号の補間を含むプレーンテキストテンプレート]

この計画は小さく（4タスク）、仕様にトレース可能で、テストファースト、各タスクは5分以内に完了可能です。

良い計画は退屈です。 計画を読んで、構築する巧みなものすべてのせいで興奮するなら、それは警告サインです。良い計画は徹底的で、正確で、明確です—興味深い決定はブレインストーミングで行われました。