仕様駆動開発

概要

コードを書く前に、構造化された仕様書を作成します。仕様書は、あなたと担当エンジニアの間の唯一の信頼できる情報源です。何を構築するのか、なぜするのか、完了をどのように判定するのかを定義します。仕様書のないコードは推測でしかありません。

使用する場合

• 新規プロジェクトまたは機能を開始する
• 要件が曖昧または不完全である
• 変更が複数のファイルやモジュールに影響する
• アーキテクチャ上の決定を行う直前である
• タスクの実装に30分以上かかる見込みである

使用しない場合： 単一行の修正、タイプミスの修正、要件が明確で自己完結している変更。

ゲート付きワークフロー

仕様駆動開発は4つのフェーズで構成されます。現在のフェーズが検証されるまで、次のフェーズに進まないでください。

SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
   │          │        │          │
   ▼          ▼        ▼          ▼
 Human      Human    Human      Human
 reviews    reviews  reviews    reviews

フェーズ1：仕様策定

高レベルのビジョンから始めます。要件が具体的になるまで、担当者に質問を繰り返します。

仮定を即座に明らかにしてください。 仕様書の内容を書く前に、以下のように仮定をリストアップします：

私が想定していること：
1. これはWebアプリケーション（ネイティブモバイルではない）
2. 認証はセッションベースのクッキーを使用（JWTではない）
3. データベースはPostgreSQL（既存のPrismaスキーマに基づく）
4. モダンブラウザをターゲット（IE11は不要）
→ 今すぐ訂正するか、これらの仮定で進めます。

曖昧な要件を無言で補完しないでください。仕様書の全目的は、コードが書かれる前に誤解を明らかにすることです。仮定は最も危険な誤解の形です。

以下の6つの中核領域をカバーする仕様書を作成してください：

1. 目的 — 何を構築するのか、なぜするのか？ユーザーは誰か？成功の定義は？

2. コマンド — ツール名だけでなく、フラグを含む完全に実行可能なコマンド。

   Build: npm run build
   Test: npm test -- --coverage
   Lint: npm run lint --fix
   Dev: npm run dev
   

3. プロジェクト構造 — ソースコードの場所、テストの場所、ドキュメントの場所。

   src/           → アプリケーション ソースコード
   src/components → React コンポーネント
   src/lib        → 共有ユーティリティ
   tests/         → ユニットテストと統合テスト
   e2e/           → エンドツーエンドテスト
   docs/          → ドキュメント
   

4. コードスタイル — 3段落の説明よりも、スタイルを示す実際のコードスニペット1つの方が勝ります。命名規則、フォーマット規則、良い出力の例を含めます。

5. テスト戦略 — どのフレームワークか、テストの場所、カバレッジの期待値、どの関心事にはどのテストレベルか。

6. 境界 — 3段階のシステム：

   • 常に実行： コミット前にテストを実行、命名規則に従う、入力を検証する
   • 最初に確認： データベーススキーマの変更、依存関係の追加、CI設定の変更
   • 絶対にしない： シークレットをコミット、ベンダーディレクトリを編集、失敗したテストを承認なしで削除

仕様テンプレート：

# 仕様：[プロジェクト/機能名]

## 目的
[何を構築するのか、なぜするのか。ユーザーストーリーまたは受け入れ基準。]

## テックスタック
[フレームワーク、言語、主要な依存関係とバージョン]

## コマンド
[ビルド、テスト、リント、開発 — 完全なコマンド]

## プロジェクト構造
[説明付きディレクトリレイアウト]

## コードスタイル
[スニペットの例 + 主要な規則]

## テスト戦略
[フレームワーク、テストの場所、カバレッジ要件、テストレベル]

## 境界
- 常に：[...]
- 最初に確認：[...]
- 絶対にしない：[...]

## 成功基準
[これが完了したことをどのように知るか — 具体的でテスト可能な条件]

## 未解決の質問
[人間の入力が必要な未解決事項]

指示を成功基準として再構成してください。 曖昧な要件を受け取ったときは、それを具体的な条件に変換します：

要件：「ダッシュボードを高速化する」

再構成した成功基準：
- ダッシュボード LCP < 2.5秒（4G接続時）
- 初期データロードが500ms以内に完了
- ロード中にレイアウトシフトなし（CLS < 0.1）
→ これらが正しいターゲットですか？

これにより、「高速化」が何を意味するのか推測するのではなく、明確なゴールに向かってループし、再試行し、問題を解決できます。

フェーズ2：計画

検証された仕様書を使用して、技術的な実装計画を立案します：

1. 主要なコンポーネントとその依存関係を特定する
2. 実装順序を決定する（最初に何を構築する必要があるか）
3. リスクと緩和戦略を記録する
4. 並列構築できるものと順序立てて構築する必要があるものを特定する
5. フェーズ間の検証チェックポイントを定義する

計画は検証可能であるべきです。担当者は計画を読んで「はい、それが正しいアプローチです」または「いいえ、Xを変更してください」と言えるべきです。

フェーズ3：タスク

計画を離散的で実装可能なタスクに分割します：

• 各タスクは単一の集中したセッションで完了可能である
• 各タスクは明示的な受け入れ基準を持つ
• 各タスクは検証ステップを含む（テスト、ビルド、手動チェック）
• タスクは依存関係順に順序付けされ、優先度順ではない
• タスクが5つ以下のファイルを変更する

タスクテンプレート：

- [ ] タスク：[説明]
  - 受け入れ：[完了したときに真である必要があること]
  - 検証：[確認方法 — テストコマンド、ビルド、手動チェック]
  - ファイル：[どのファイルが影響を受けるか]

フェーズ4：実装

incremental-implementation と test-driven-development スキルに従って、1度に1つのタスクを実行します。context-engineering を使用して、各ステップで適切な仕様書セクションとソースファイルを読み込み、エージェント全体に仕様書をいっぱい詰め込まないようにします。

仕様書を生きたものにする

仕様書は1回限りの成果物ではなく、生きたドキュメントです：

• 決定が変わったときに更新 — データモデルを変更する必要があることが判明した場合は、最初に仕様書を更新し、その後実装します。
• スコープが変わったときに更新 — 追加または削除された機能は仕様書に反映される必要があります。
• 仕様書をコミット — 仕様書はコードと一緒にバージョン管理に属します。
• PRで仕様書を参照 — 各PRが実装する仕様書セクションにリンクバックします。

一般的な言い訳

言い訳	現実
「これは簡単だから仕様書は不要」	簡単なタスクは長い仕様書は不要ですが、それでも受け入れ基準は必要です。2行の仕様書で十分です。
「コードを書いた後に仕様書を書きます」	それはドキュメント、仕様書ではありません。仕様書の価値はコード前に明確性を強制することです。
「仕様書は私たちを遅くします」	15分の仕様書は何時間ものやり直し作業を防止します。15分の滝のアプローチは15時間のデバッグより優れています。
「要件は変わるでしょう」	だから仕様書は生きたドキュメントです。古い仕様書は、仕様書がないより優れています。
「ユーザーは何が欲しいか知っています」	明確なリクエストでも暗黙の仮定があります。仕様書はそれらの仮定を明らかにします。

危険信号

• 書かれた要件なしでコードを書き始める
• 「何が『完了』を意味するのかを明確にする前に『構築を開始したほうがいい？』と聞く
• 仕様書またはタスクリストに記載されていない機能を実装する
• アーキテクチャ上の決定を文書化せずに行う
• 「何を構築するかは明らかだから」という理由で仕様書をスキップ

検証

実装に進む前に、以下を確認してください：

• 仕様書が6つの中核領域すべてをカバーしている
• 担当者が仕様書をレビューして承認している
• 成功基準は具体的でテスト可能である
• 境界（常に/最初に確認/絶対にしない）が定義されている
• 仕様書がリポジトリのファイルに保存されている