ブログ

GitHub Spec-kitの内部動作から学ぶ、仕様駆動開発（SDD）

並崎功真

並崎功真

エンジニア

GitHub CopilotのようなAIコーディングエージェントの登場は、私たちの生産性を劇的に向上させました。しかし、明確な設計図なしにAIとの対話だけで実装を進める「Vibe Coding」は、アーキテクチャの一貫性の欠如、属人化（ならぬ属AI化）、そして深刻な保守性の低下という新たな技術的負債を生み出しています。

AIは非常に優秀な「実装者」ですが、「何を・なぜ作るべきか」を知りません。AIに意図した通りの高品質なコードを生成させるためには、AIが理解できる「構造化された指示書＝仕様書」が不可欠です。

この記事では、GitHubが提唱する「Spec-kit」が、いかにして「仕様」をAIと開発者の共通言語にしているのか、内部プロンプト（設計思想）から、その具体的な実践方法とレビューの勘所を解読します。

※ 私の環境ではSpec-kitのプロンプトを日本語に翻訳して使用しています。

---

1. Spec-kitが駆動する開発サイクル：8つのコマンドの役割

Spec-kitは「仕様書を書いて終わり」ではありません。仕様を「定義」し、「検証」し、「計画」に落とし込み、「実行」し、「分析」する一連の開発サイクルを回すためのツールキットです。

このサイクルは、主に以下のコマンド群によって支えられています。

  •  定義 (Define):
    • /speckit.specify: 自然言語から機能仕様書（spec.md）を作成する。
    • /speckit.clarify: 仕様書の曖昧な点を対話的に解消する。
  • 計画 (Plan):
    • /speckit.plan: 仕様書から技術計画書（plan.md）やデータモデル（data-model.md）を生成する。
  • 実行 (Execute):
    • /speckit.tasks: 仕様書と計画書から、AIが実行可能なタスクリスト（tasks.md）を生成する。
    • /speckit.implement: タスクリストに基づき、実装を実行する。
  •  統治 (Govern):
    • /speckit.constitution: プロジェクトの「憲法」（コーディング規約、技術スタックの制約など）を定義する。
    • /speckit.checklist: 「要件の単体テスト」として機能するカスタムチェックリスト（例: ux.md）を生成する。
    • /speckit.analyze: 仕様書、計画書、タスクリスト間の「整合性」を分析する。

---

2. Spec-kitのSDD vs TDD/BDD：何が違うのか？

Spec-kitが提唱するSDDは、TDDやBDDの思想を、AIとの協調を前提に、開発プロセス全体に拡張したものと言えます。

  •  TDD (テスト駆動開発):
    • 駆動源: 開発者が書く「失敗するテストコード」。
    • 目的: 実装レベルの品質担保とリファクタリング耐性。
  • BDD (振る舞い駆動開発):
    • 駆動源: ビジネス側と開発者の共通言語である「振る舞い（シナリオ）」。
    • 目的: ビジネス要件と実装のギャップを埋める。
  • SDD (Spec-kitによる仕様駆動開発):
    • 駆動源: 「構造化されたドキュメント群」（仕様書、計画書、タスクリスト、そして憲法）。
    • 目的: AIと開発者の両方を「仕様」で駆動し、要件定義から実装までの一貫性を担保する。

Spec-kitの内部設計は、この思想を強力に反映しています。

  • /speckit.checklist プロンプトは、チェックリストを「要件定義のための単体テスト」と明確に定義しています。これは、実装（コード）ではなく、要件（仕様書）の品質（明確さ、完全性、一貫性）をテストします。
  • /speckit.analyze プロンプトは、spec.md（要求）、plan.md（設計）、tasks.md（実装タスク）の3者間の不整合を検出する「結合テスト（CI）」のように機能します。

---

3. Spec-kitによる具体的な実践ステップ（内部動作から読み解く）

Spec-kitの真価は、コマンドが連携し、仕様の曖昧さを段階的に排除していくプロセスにあります。

Step 1: 憲法と仕様の定義 (/constitution & /specify)

開発は「何でも自由に作ってよい」わけではありません。まずプロジェクトのルールを定めます。

  1. /speckit.constitution:
    • プロジェクトの「憲法」（constitution.md）を定義します。これは「交渉の余地がない」絶対的なルールセットです（例：「技術スタックはRuby on Rails 7とPostgreSQL 15のみ」、「全てのAPIはOAuth2認証をMUSTとする」）。
    • この憲法は、後の /plan や /analyze コマンド実行時に参照され、違反は「クリティカル」エラーとして検出されます。
  2. /speckit.specify:
    • 開発者の自然言語（例：「ユーザー認証機能が欲しい」）から spec.md を生成します。
    • 内部動作: Spec-kitは単にテキストをコピー＆ペーストするわけではありません。
      • 「実装の詳細（How）」を排除し、「ユーザー価値（What/Why）」にフォーカスさせます。
      • 同時に checklists/requirements.md という「仕様品質チェックリスト」を自動生成し、「要件はテスト可能か？」「曖昧さがないか？」といった項目で自己検証を行います。
      • どうしてもAIだけでは判断できない曖昧な点は、[要明確化]`マーカーを残します（最大3つまで）

Step 2: 曖昧さの排除 (/clarify) と技術計画 (/plan)

曖昧な仕様書は、曖昧な実装しか生みません。次に、この曖昧さを徹底的に潰します。

  1. /speckit.clarify:
    • spec.md をスキャンし、`[要明確化]` マーカーや、「堅牢な」「直感的な」といった曖昧な形容詞を検出します。
    •  内部動作: 開発者に対し、多肢選択式または短い回答で（最大5問まで）対話的な質問を行います。
    •  得られた回答は、自動的に spec.md の適切なセクション（機能要件、非機能要件など）に直接書き戻され、仕様書が明確化されます。
  2. /speckit.plan:
    • 「明確化された spec.md」と「constitution.md（憲法）」を読み込みます。
    • 内部動作:
      • 憲法に違反する技術選定（例：憲法で禁じられているDBを使おうとする）はエラーとなります。
      • 技術計画書（plan.md）だけでなく、data-model.md（DBスキーマ）、contracts/（API定義ファイル）、research.md（技術調査が必要な項目）などを自動生成します。

Step 3: 分析とタスク生成 (/analyze & /tasks)

設計図（plan.md）ができただけでは、AIはまだ動けません。実行可能なタスクに分解し、矛盾がないか検証します。

  1. /speckit.tasks:
    • plan.md と spec.md をインプットとして、AIが実行可能な粒度の具体的なタスクリスト（tasks.md）を生成します。
    • 内部動作: タスクは「T001 [P] [US1] src/models/user.py に User モデルを作成する」のように、ID、並列可能性[P]、関連ストーリー[US1]、具体的なファイルパスまで定義されます。
  2.  /speckit.analyze:
    • （重要） 実装前に、この「読み取り専用」の分析コマンドを実行します。
    • 内部動作: 以下の3つのドキュメントを読み込み、整合性分析（クロスレビュー）を行います。
      1. spec.md (要求は何か？)
      2. plan.md (設計はどうなっているか？)
      3. tasks.md (実装タスクは揃っているか？)
    • 「仕様には存在するが、タスクに漏れている要件」や「憲法違反」などを検出し、重大度（クリティカル、高、中、低）をつけてレポートします。

Step 4: 実装と検証 (/checklist & /implement)

分析で「クリティカル」な問題がなくなったら、いよいよ実装です。

  1. /speckit.checklist:
    • 開発者は、ドメイン固有のチェックリスト（例：`/speckit.checklist "UXレビュー用の項目を作成"` → ux.md）を任意に作成できます。
    • 内部動作: このコマンドは「実装が動くか」ではなく、「要件が明確か」（例：「'目立つ表示'は、具体的なサイジングで定量化されているか？」）を問う項目を生成します。
  2. /speckit.implement:
    • tasks.md に従って、AIエージェントが実装タスクを順次実行します。
    • 内部動作（品質ゲート）:
      • implement コマンドは、コード生成を始める前に、まず checklists/ ディレクトリ（requirements.md, ux.md 等）をスキャンします。
      • 一つでも未完了の項目 (`- [ ]`) が残っている場合、AIは「いくつかのチェックリストが未完了です。それでも実装を続行しますか？ (yes/no)」と警告を発します。

---

4. 実践時の注意点とレビュー観点（Spec-kitの思想から学ぶ）

Spec-kitは強力なツールですが、その思想を理解せずに使うと「Vibe Coding」に逆戻りしてしまいます。

注意点（アンチパターン）

  •  constitution の軽視:
    • /analyze や /plan で検出される「憲法違反」を無視すると、プロジェクト全体のアーキテクチャやセキュリティポリシーが崩壊します。
  • /clarify のスキップ:
    • 曖昧な spec.md（「使いやすいUI」など）のまま /plan すると、AIが「推測」で設計を行い、結局Vibe Codingと何も変わりません。
  • /analyze の無視:
    • 整合性分析 (`/analyze`) で「クリティカル」が出ている（例：仕様漏れ）のに /implement を強行すると、その仕様は実装されません。
  • チェックリストの形骸化:
    • /implement 時の「未完了です」という警告を、常に「yes」で通過させると、品質ゲートは機能しません。

レビュー観点

Spec-kitを使った開発では、コードだけでなく「ドキュメント」もレビュー対象となります。

  •  spec.md のレビュー:
    • /checklist requirements.md の項目は全て満たされているか？
    • /clarify で解決すべき曖昧な用語（「速い」「安全な」）が残っていないか？
  • plan.md のレビュー:
    • プルリクエストには、`/analyze` を実行し、「構成（Constitution）整合性イシュー」がゼロであることを含めるべきです。
    • 技術選定の根拠（research.md）は妥当か？
  • コードレビュー（プルリクエスト）:
    • そのコードが tasks.md のどのタスクIDに対応する実装か明記されているか？
    • 関連する checklists/（例：security.md, ux.md）の項目は完了（`[x]`）しているか？

---

結論

GitHubの「Spec-kit」は、AI開発における「Vibe Coding」の課題に対し、「構造化されたドキュメント」と「厳格な検証プロセス」で立ち向かう強力なフレームワークです。

TDDが「テストコード」で実装を縛ったように、SDD (Spec-kit) は「仕様書・計画書・憲法」というドキュメント群でAIと開発者を縛り、予測可能で高品質な開発サイクルを実現します。

成功の鍵は、これらのドキュメントを「一度作って終わり」ではなく「生きたドキュメント」として常にメンテナンスし、`/analyze` や /checklist といった「検証ゲート」を形骸化させない文化づくりにあるのです。