spec-driven-development

仕様駆動開発

概要

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

使用する場面

• 新しいプロジェクトや機能を始めるとき
• 要件が曖昧、または不完全なとき
• 変更が複数のファイルやモジュールに及ぶとき
• アーキテクチャ上の決定を行おうとしているとき
• 実装に30分以上かかるタスク

使用しない場面： 1行だけの修正、誤字の訂正、または要件が明確で自己完結している変更。

ゲート付きワークフロー

仕様駆動開発には4つのフェーズがあります。これに先立ち、1つのリクエストに複数の独立してテスト可能な機能が含まれている場合にのみ、スコープ確認（フェーズ0）を行います。現在のフェーズが検証されるまで、次のフェーズに進まないでください。

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

フェーズ0：スコープ確認

ほとんどのリクエストが説明するのは1つの機能です。今回もそうであれば、このフェーズをスキップして「仕様策定」に進んでください。フェーズ0は例外のためのものであり、原則ではありません。また、単一機能の優先順位を決めるものでもありません。

検出。 1つの要件に、独立してテスト可能な複数の機能が含まれている場合は、仕様を作成する前に分解してください。

• 要件に、それぞれ独自の利用者やデータを持つ個別の機能（例：ID管理、請求、通知、レポート）が挙げられている
• 受け入れ基準が、個別にリリースして検証できるグループに分かれている
• ある機能を削除または置き換えても、他の機能の要件を書き直す必要がない

仕様を書く前に、機能マップを提案してください。 小さく、レビューしやすいものにします。プロジェクト計画ではなく、モジュールの表と構築順序を作成します。

# Capability Map: [Initiative Name]

| Module id | Responsibility | Depends on |
|---|---|---|
| identity | Accounts, sessions, SSO | — |
| billing | Plans, invoices, payments | identity |
| notifications | Email and webhook fan-out | identity |
| reporting | Usage dashboards | billing, notifications |

Build order: identity → billing, notifications → reporting

• 安定したモジュールID。 ケバブケースで一度決めたら、取り組みの途中で変更しません。どの仕様が有効か推測する代わりに、仕様、計画、後続のコマンドではこれらのIDを使って作業を選択します。
• 一方向の依存関係、循環なし。 矢印の向きは一方向にします。2つのモジュールが互いを必要とする場合は、1つのモジュールにまとめます。
• インターフェースは境界に置く。 マップには、billingがidentityに依存していることを記録します。両者間の契約は、提供側モジュールの仕様に記載します（設計方法についてはapi-and-interface-designを参照してください）。

マップにも各フェーズと同じゲートを設けます。 モジュールの仕様を書く前に、人間がモジュールの境界、依存関係の方向、構築順序をレビューします。マップを間違えると修正コストが高くつきます。10行をレビューするほうが負担は少なくて済みます。

その後、モジュールごとに繰り返します。 依存関係の順序に従って、各モジュールについて「仕様策定 → 計画 → タスク → 実装」を実行します。各モジュールには、その目標、境界、成功基準に絞った独自の仕様を用意します。承認済みのマップをプロジェクトのルートに保存し、各モジュールの仕様はその隣にモジュールIDを名前に付けて保存します（SPEC-identity.md、SPEC-billing.md）。何が存在するかを示す索引はマップであり、ファイル名から推測するものではありません。

フェーズ 1：仕様を定める

まず、ビジョンを大まかに示します。要件が具体的になるまで、人間に明確化のための質問をします。

前提をすぐに明らかにします。 仕様の内容を書く前に、何を前提としているかを列挙します。

ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Authentication uses session-based cookies (not JWT)
3. The database is PostgreSQL (based on existing Prisma schema)
4. We're targeting modern browsers only (no IE11)
→ Correct me now or I'll proceed with these.

曖昧な要件を黙って補ってはいけません。仕様の目的は、コードを書く前に誤解を明らかにすることです。前提は、最も危険な誤解の形です。

次の6つの主要項目を網羅する仕様書を作成します。

1. 目的 — 何を、なぜ構築するのですか？ユーザーは誰ですか？成功とはどのような状態ですか？

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

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

3. プロジェクト構成 — ソースコード、テスト、ドキュメントをそれぞれどこに配置するかを記載します。

   src/           → Application source code
   src/components → React components
   src/lib        → Shared utilities
   tests/         → Unit and integration tests
   e2e/           → End-to-end tests
   docs/          → Documentation
   

4. コードスタイル — スタイルを説明する3段落よりも、実際のコードスニペットを1つ示すほうが効果的です。命名規則、書式ルール、適切な出力例を含めます。

5. テスト戦略 — 使用するフレームワーク、テストの配置場所、カバレッジの期待値、懸念事項ごとにどのレベルのテストを行うかを記載します。

6. 境界 — 次の3段階の体系を定めます。

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

仕様テンプレート：

# Spec: [Project/Feature Name]

## Objective
[What we're building and why. User stories or acceptance criteria.]

## Tech Stack
[Framework, language, key dependencies with versions]

## Commands
[Build, test, lint, dev — full commands]

## Project Structure
[Directory layout with descriptions]

## Code Style
[Example snippet + key conventions]

## Testing Strategy
[Framework, test locations, coverage requirements, test levels]

## Boundaries
- Always: [...]
- Ask first: [...]
- Never: [...]

## Success Criteria
[How we'll know this is done — specific, testable conditions]

## Open Questions
[Anything unresolved that needs human input]

外部の仕様ツール： このワークフローは特定の形式に依存しません。プロジェクトですでに OpenSpec や別の仕様策定システムを使用している場合は、重複する SPEC.md を作成せず、そのシステムの成果物形式と保存規則を維持してください。このスキルが担うのは、要件の明確化、内容の策定、承認のゲートです。承認済みの仕様をどのように表現するかは、外部ツールが担います。

指示を成功条件として捉え直します。 曖昧な要件を受け取ったら、具体的な条件に置き換えます。

REQUIREMENT: "Make the dashboard faster"

REFRAMED SUCCESS CRITERIA:
- Dashboard LCP < 2.5s on 4G connection
- Initial data load completes in < 500ms
- No layout shift during load (CLS < 0.1)
→ Are these the right targets?

これにより、「速く」という言葉の意味を推測するのではなく、明確な目標に向けて、繰り返しや再試行、問題解決を行えます。

仕様を書いたら停止します（重要）。 仕様を保存したら、次の手順に従います。

1. 仕様を要約し、未解決の質問を列挙します。
2. 人間に仕様の承認、または変更の依頼を求めます。
3. ただちに今回の対応を停止します。 フェーズ 2 を開始したり、planning-and-task-breakdown を呼び出したり、この対応内でコードを書いたりしてはいけません。計画は、人間が後の対応で仕様を承認した後にのみ開始します。

フェーズ 2：計画を立てる

検証済みの仕様をもとに、技術的な実装計画を作成します。

1. 主要なコンポーネントとその依存関係を特定します。
2. 実装の順序（最初に構築する必要があるもの）を決定します。
3. リスクと緩和策を記載します。
4. 並行して構築できるものと、順次進める必要があるものを特定します。
5. フェーズ間の検証チェックポイントを定義します。

これらの手順で用いる依存関係グラフのマッピングと垂直スライスの仕組みについては、正式な情報源である planning-and-task-breakdown に従ってください。上記の箇条書きは簡潔な概要です。内容が異なる場合は、planning-and-task-breakdown を優先します。

出力規則： 計画を tasks/plan.md に保存し、planning-and-task-breakdown で定義されているタスクリストの保存先にタスクリストを記録します（デフォルトは tasks/todo.md です。プロジェクトによっては外部トラッカーを指定できます）。tasks/ が存在しない場合は作成します。後続のコマンド（/build など）は、これらのデフォルトを想定しています。

計画はレビュー可能なものにします。人間が読んで「はい、これが適切な進め方です」または「いいえ、X を変更してください」と判断できる必要があります。

フェーズ 3: タスク

計画を、個別の実装可能なタスクに分解します。

• 各タスクは、1 回の集中したセッションで完了できるようにする
• 各タスクには、明確な受け入れ基準を設ける
• 各タスクには、検証ステップ（テスト、ビルド、手動チェック）を含める
• タスクは、重要度ではなく依存関係の順に並べる
• どのタスクも、約 5 ファイルを超える変更を必要としないようにする

タスクのサイズ設定と依存関係の順序付けの詳細な仕組みについては、planning-and-task-breakdown に従ってください。これが正規の情報源です。以下のテンプレートは軽量なインライン形式であり、万一両者が矛盾する場合は、planning-and-task-breakdown が優先されます。

タスクテンプレート:

- [ ] Task: [Description]
  - Acceptance: [What must be true when done]
  - Verify: [How to confirm — test command, build, manual check]
  - Files: [Which files will be touched]

フェーズ 4: 実装

skills/incremental-implementation/SKILL.md（incremental-implementation）と skills/test-driven-development/SKILL.md（test-driven-development）に従って、タスクを 1 つずつ実行します。skills/context-engineering/SKILL.md（context-engineering）を使用して、各ステップで仕様全体をエージェントに流し込むのではなく、適切な仕様セクションとソースファイルを読み込みます。

仕様を生かし続ける

仕様は一度きりの成果物ではなく、生きたドキュメントです。

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

よくある合理化

合理化	現実
「これは簡単だから、仕様は必要ない」	簡単なタスクに長い仕様は必要ありませんが、受け入れ基準は依然として必要です。2 行の仕様で十分です。
「コードを書いた後に仕様を書く」	それはドキュメントであり、仕様ではありません。仕様の価値は、コードを書く前に明確さを強制することにあります。
「仕様は作業を遅らせる」	15 分の仕様が、何時間もの手戻りを防ぎます。15 分のウォーターフォールは、15 時間のデバッグに勝ります。
「どうせ要件は変わる」	だからこそ仕様は生きたドキュメントなのです。古くなった仕様でも、仕様がないよりはましです。
「ユーザーは自分が何を求めているか分かっている」	明確な依頼にも暗黙の前提があります。仕様はそうした前提を明らかにします。
「1 つの大きな機能だから、分割はオーバーヘッドだ」	受け入れ基準が独立してテスト可能なグループにまとまるなら、一枚岩の仕様は下流のすべてのタスクに契約全体を推論させることになります。10 行のケイパビリティマップが、低コストな代替手段です。
「計画中に分解する」	計画は仕様内のタスクを切り分けます。その時点では、すでに巨大な成果物が存在しています。モジュールの境界と依存関係の方向は、仕様を書く前に決定する必要があり、後ではいけません。

危険信号

• 書面による要件なしでコードを書き始める
• 「done」の意味を明確にする前に、「とりあえず作り始めるべきか？」と尋ねる
• どの仕様やタスクリストにも言及されていない機能を実装する
• アーキテクチャ上の決定を文書化せずに行う
• 「何を作るべきかは明らかだ」という理由で仕様を省略する
• 同じターンで仕様を書き、計画またはコードを開始する
• 要件が複数の独立してテスト可能なケイパビリティにまたがる単一の仕様
• 事前に承認されたケイパビリティマップがないために、モジュールの境界やビルド順序が実装中に暗黙的に決定される

検証

実装に進む前に、次を確認します。

• 仕様が 6 つの中核領域すべてをカバーしている
• 人間が仕様をレビューし、承認している
• 仕様を保存した後にターンが終了し、承認は後のターンで行われた
• 成功基準が具体的でテスト可能である
• 境界（Always/Ask First/Never）が定義されている
• 仕様がリポジトリ内のファイルに保存されている
• リクエストが複数の独立してテスト可能なケイパビリティをまとめている場合、モジュール仕様を書く前にケイパビリティマップ（モジュール ID、依存関係の方向、ビルド順序）が承認されている
• すべてのモジュール仕様が、承認されたマップ内のモジュール ID に紐づいている