仕様駆動型開発とは何か？仕様を真のデータ源（Source of Truth）として

仕様書は副次的なドキュメントではなく、真実の唯一の情報源であるべきです。

目次

仕様駆動型開発（Spec-Driven Development）は、ソフトウェアエンジニアが以前から追求してきたものの、努力に見合う成果が得られなくなると手放してきたアイデアの一つです。

2025年に変化したのは、AIコーディングエージェントが登場し、明示的な意図の欠如がコストの高い問題となった点です。プロンプトは一過性のものであり、エージェントのセッションはリセットされます。コードは変更されますが、その背後にある推論は消えてしまいます。仕様書（Spec）は、そのような事態を防止するためのアーティファクト（成果物）です。

What Is Spec-Driven Development – the spec as source of truth for AI coding

仕様書が真の源泉（Source of Truth）となる

ソフトウェア開発の歴史の大部分において、仕様書は仮の計画用のアーティファクトか、あるいは事後の付随物に過ぎませんでした。要件はチケットに、設計決定はチャットスレッドに保管され、コードこそが真実（ground truth）でした。ドキュメントは事後的に存在するものを記述するものでした。

仕様駆動型開発（SDD）はこの関係性を逆転させます。仕様書が一次のアーティファクトとなります。コードは仕様書に対して生成または検証されるものであり、その逆ではありません。

これは新しいアイデアではありません。形式手法（Formal methods）、契約による設計（Design-by-contract）、BDD（振る舞い駆動型開発）には、そのバリエーションが存在します。新たな点は実践的な動機にあります：AIコーディングエージェントは、正確で一貫した出力を生み出すために、明示的で持続的なコンテキストを必要とします。プロンプトは一過性すぎて不十分です。仕様書こそが、エージェントのセッション、チームメンバー、そして時間を跨って意図を運ぶことができる唯一のアーティファクトです。

仕様駆動型開発が実際に意味すること

通常SDDと略される仕様駆動型開発は、バージョン管理された仕様書が実装をガイドまたは生成するワークフローです。エージェントがコードを書く前に、仕様書は作成され、レビューされます。それは以下を捉えます：

  • 何を構築するか – ユーザーの問題、目標、および非目標（non-goals）
  • 正しい振る舞いはどのようなものか – 受理基準（acceptance criteria）、エッジケース、エラー状態
  • どのように構築するか – アーキテクチャの決定、データモデル、API契約、セキュリティ制約
  • どのように検証するか – テスト戦略、検証ルール、要件へのトレーサビリティ

最後の項目は書くのは簡単ですが、実践では簡単にスキップされてしまいます。AI開発における仕様、テスト、コードの同期では、要件へのトレーサビリティがデータとして具体的にどのようなものか（要件ID、設計決定ID、それらを実装したプルリクエストに関連付けられたテスト）が説明されています。

仕様書は一度きりの文書ではありません。現実が設計と異なる場合に更新されます。エージェントが実装中に仕様書が誤っていたことを発見した場合、仕様書は修正された上で作業が続行されます。仕様書はコードと同様に扱われるため、誠実さを保ちます。

最近の学術研究はこの枠組みを形式化しています：研究者たちは、SDDを仕様書を真の源泉とし、コードをそれに対して生成または検証するものとして記述しています。実用的な解釈としては、仕様書は、人間やAIツールが読み取り信頼できる、レビュー済みで持続的な意図の記録であるということです。

仕様利用のスペクトル上の異なる点を表す3つの用語があります：

**Spec-first（仕様ファースト）**とは、あらゆる実装を開始する前に完全な仕様書を作成することを意味します。これは最も厳格な解釈であり、注意深く行われない場合、ウォーターフォール型に近いものです。

**Spec-anchored（仕様アンカー）**とは、機能のライフサイクル全体を通じて、実装と同期された仕様書を維持することを意味します。決定が変化するにつれて仕様書が更新されます。これは多くのチームにとって最も実用的なバージョンです。

**Spec-as-source（仕様を源泉として）**とは、仕様書から実装を生成または検証することを意味します。これはAIエージェントを通じて、または仕様制約に対してコードをチェックするツールを通じて行われます。GitHub Spec KitとKiroのようなツールは、ポータビリティと統合されたIDEガイダンスの間の異なるトレードオフを持ちながら、この方向へ向かって移動しています。

なぜ今SDDが重要なのか

正直な答えは、SDDは1日で終わるスクリプトを構築する単独の開発者には魅力的ではないということです。オーバーヘッドはそれに見合うものではありません。

SDDが価値を持つようになるのは、3つの条件が揃った時です：機能が複数のセッションにまたがるほど十分に大きく、エージェントがアーキテクチャに影響を与える決定を行う必要があり、作業が他者によってレビューまたは継続される場合です。

AI支援開発では、これら3つの条件がますます一般的になっています。

LLMはプロンプトだけでなく、コンテキストを必要とします。 曖昧なプロンプトを受け取るモデルは、曖昧な決定を下します。明示的な制約、非目標、受理基準を備えたレビュー済みの仕様書を受け取るモデルは、より良い決定を下し、軌道から外れた場合に修正しやすくなります。これは、検索と表現がどのように機能するかに関連しています：エージェントにバージョン管理された仕様書を提供することは、プロジェクトの意図の構造化された検索の一種です。

コード生成は安価ですが、何を構築するかを決定することは依然として困難です。 AI支援開発におけるボトルネックは、もはやタイピングではありません。何を構築すべきか、そしてエージェントをどのように制約すべきかを知ることです。SDDは、その労力を重要な箇所にシフトします：生成が始まる前に意図を明確に指定することです。

プロンプトは一過性です。 エージェントは、最後のセッションであなたに伝えたことを覚えていません。リポジトリに保存されたバージョン管理された仕様書はそれを保持します。新しいセッションはすべて同じ仕様書を読み込み、ゼロからコンテキストを再構築することなく、同じ意図に対して実装できます。

**Vibe Codingは使い捨ての作業には速いです。SDD vs Vibe Codingでは、いつ仕様を追加し、いつ自由にプロンプティングを続けるべきかがカバーされています。

コアアーティファクト

SDDは4つのアーティファクトタイプを生成します。それぞれがエージェントがコードに触れる前に、異なる種類の曖昧性を減少させます：

  • Requirements spec（要件仕様） – 問題、ユーザー、目標、非目標、受理基準
  • Design spec（設計仕様） – この機能のためのアーキテクチャ、データモデル、API契約、セキュリティ制約
  • Task plan（タスク計画） – 依存関係と検証基準を備えた小さな実装スライス
  • Traceability record（トレーサビリティ記録） – 受理基準からテストへ、設計決定からファイルへ、タスクからコミットへマッピング

それらを1つずつどのように作成し、レビューするか（指定、計画、タスク、実装、検証）は、要件からコードへの仕様駆動型開発ワークフローでカバーされています。単純な機能では、短いマークダウンファイルで4つの領域すべてをカバーできるかもしれません。重要なのはフォーマットよりも習慣です。

SDDとドキュメンテーションの違い

最も一般的な混乱は、SDDアーティファクトをドキュメンテーションとして扱うことです。それらは従来の意味でのドキュメンテーションではありません。

ドキュメンテーションは記述します。 それはシステムが何をするか、どのように使うか、そして何を含んでいるかを伝えます。それは事後的に書かれ、システムが変更された際に更新されます。

仕様は制約します。 仕様は、エージェントが構築することを許され、また許されないものを伝えます。それは実装が始まる前に権威を持ちます。実装が完了した後に検証されます。実際に構築されたものを記述する仕様（構築すべきものを制約するのではなく）は、すでにその目的を失敗しています。

実行可能な仕様は生成と検証をガイドします。 最良のSDD仕様は、機械で読み取り可能なほど近く、エージェントがそれに対して実装し、テストスイートがそれらを検証できるものです。「エンドポイントは401レスポンスで認証されていないリクエストを拒否しなければならない」という受理基準は実行可能な仕様です。「エンドポイントは安全である」はドキュメンテーションです。

決定記録 – ADR、PDR、およびDDR – はSDDアーティファクトに補完的ですが、異なる目的を提供します。決定記録は、なぜ選択が行われ、何が却下されたかを記録します。SDD仕様は、何を構築し、どのように検証するかを記録します。両者はリポジトリに属します。一緒に、それらはAIエージェントに完全な図面を提供します：現在の意図とその背後にある推論です。

SDDとTDDの違い

テスト駆動型開発（TDD）と仕様駆動型開発は、どちらもコードが存在する前に明示的なアーティファクトを生成するため、しばしば混同されます。違いは出発点です。

TDDはテストから始まります。 望む振る舞いを記述する失敗するテストを書き、次にそれをパスさせるための最小限のコードを書きます。TDDはユニットレベルのフィードバックループです。それは良いテストを生み出しますが、正しいものを構築しているかどうかという問いには答えません。

SDDは意図から始まります。 テストが存在する前、アーキテクチャが決定される前に、仕様は次の問いに答えます：誰がこの問題を抱えているか、正しい振る舞いはどのようなものか、明確に範囲外なのは何か。仕様は次にどのテストを書くべきかを informs（情報提供）します。それが、良いSDDと良いTDDが競合するのではなく補完的なものである理由です。

それを考えるための実用的な方法：SDDがTDDを駆動します。仕様書内の受理基準がテストシナリオになります。設計仕様は、契約テストを必要とする統合境界を特定します。タスク計画は、エージェントがそれらを実装する前に、テストカバーを必要とするユニット振る舞いを特定します。

SDDとBDDの違い

振る舞い駆動型開発（BDD）は、自然言語シナリオ（通常Gherkin形式）を使用して、ユーザーの視点からの期待される振る舞いを記述します。これらのシナリオは、ビジネス意図と技術的実装の間の橋渡しをします。

SDDはより広範です。それは振る舞いの記述（BDDスタイルの言語または平文プロースを使用可能）を含みますが、アーキテクチャ決定、データモデル、セキュリティ制約、タスク計画、およびトレーサビリティもカバーします。BDDは、SDD要件仕様書内の受理基準を書くための有用なフォーマットになり得ます。仕様書はコンテナであり、BDDシナリオは内部に何を書くかを示す一つの手段です。

この区別は実践的に重要です：BDDツールはシナリオを実行可能ことに焦点を当てています。SDDプラクティスは、ツール、セッション、チームメンバーを跨って意図を持続可能にすることに焦点を当てています。

SDDと形式手法の違い

形式手法は、数学的記法と自動検証を使用して、ソフトウェアシステムの特性を証明します。それらは非常に厳格で、ほとんどの本番開発コンテキストにおいて非常にコストがかかります。

SDDは形式記法を必要としません。受理基準とアーキテクチャ決定を備えたマークダウンファイルは仕様書です。それは数学的に形式的ではないものの、制約を課します。厳格性のレベルは利害関係に応じてスケーリングします：請求サービスの仕様は、ドキュメントページの仕様よりも、より精密で、より慎重にレビューされるべきです。

この関係はスペクトルです：

  • 非公式のプロース仕様（最小限の機能SDD）
  • 受理基準と非目標を備えた構造化マークダウン
  • スキーマ検証を備えた機械で読み取り可能な仕様
  • 仕様から直接派生した契約テスト
  • 自動証明を備えた形式的仕様

ほとんどのチームはこのスペクトルの中間で運用します。目標は数学的厳格性ではありません。AIエージェントがそれに対して実装し、人間のレビュアーが結果を検証できるように、意図を十分に明示的にすることです。

仕様駆動型開発の利点

意図のドリフトの減少。 仕様書が基準です。エージェントがドリフトした場合（それはドリフトします）、レビュアーは実装と比較するためのものを持っています。仕様書なしでは、ドリフトは何か壊れるまで目に見えません。

より良いAI出力。 明示的な制約、非目標、受理基準を与えられたエージェントは、意図されたとおりに近い実装を生み出し、見逃した場合でも修正しやすくなります。コンテキストの品質は直接出力の品質を決定します。

より簡単なレビュー。 仕様書に添付されたプルリクエストは、レビュアーがコードから意図を再構築しなければならないプルリクエストよりもレビューしやすくなります。仕様書がレビューチェックリストです。

チームの調整。 複数の人々やエージェントが同じ機能に取り組んでいる場合、仕様書は共有契約です。それなしでは、各貢献者はローカルに最適化し、部品が適合しない可能性があります。

より良いテスト計画。 仕様書内の受理基準は直接テストケースにマッピングされます。テストカバー率は仕様カバー率の問題になります：すべての受理基準が少なくとも一つのテストでカバーされていますか？

持続的な手渡しの。 機能が手を変えた場合 – エンジニアの間、エージェントセッションの間、スプリントの間 – 仕様書は手渡しのアーティファクトです。それは何が決定され、何が範囲外であり、何が検証されるべきかを記録します。

仕様駆動型開発のコスト

前倒しの努力。 コードを書く前に良い仕様書を書くには時間がかかります。小さな機能では、このオーバーヘッドは実在し、時にそれに見合うものではありません。

誤った自信。 実装に対して検証されていないが存在する仕様書は、誤った正確性の感覚を与えます。古くなった仕様書は、時に仕様書がないことよりも悪いです：それらはそれらを読むレビュアーとエージェントを誤らせます。

古くなった仕様書。 チームがそれらを計画アーティファクトとしてではなく、生きたドキュメントとして扱わない場合、仕様書はドリフトします。実装が設計と異なる際に仕様書を更新することはオプションではありません – それは、蓄積して腐敗するドキュメンテーションからSDDを区別するものです。

生成された官僚主義。 AIエージェントは、網羅的なタスクリストと冗長な仕様書を迅速に生成できます。30秒で生成された200タスクの仕様書は有用な仕様書ではありません – それは官僚主義ジェネレーターです。良いSDDには、何を指定し、何を暗黙的に残すかについての判断が必要です。

ツールロックイン。 いくつかのSDDツールは、フォーマット、ファイル構造、ワークフローについて意見が強いです。プロプライエタリフォーマットで書かれた仕様書は、明確な見出しと受理基準を備えたマークダウンファイルよりも、ツール間で持ち運ぶのが困難です。

結論

仕様駆動型開発は新しいメソロジーではありません。それは、暗黙的な意図のコストがAI生成コードにおいて可視化されたため、再び実用的になった古い規律です。

その規律は単純です：エージェントがそれを構築する前に、構築することを意図するものを、レビューされ、バージョン管理された状態で書き留めます。現実が異なる際にそれを更新して、その記録を誠実なものと保ちます。それをレビュー、テスト、手渡しのための基準として使用します。

仕様書は魔法ではありません。検証されていない仕様書は、最も高価な種類のドキュメンテーション、すなわち自信を持って誤らせるものになります。良いSDDは、仕様書を誠実な状態に保つ実践です – 維持するには小さく、制約するには精密で、単一のエージェントセッションを超えて持続するのに十分な耐久性があります。

SDDは、ドキュメンテーションプラクティス、テストアーキテクチャ、コードデザインの交点に位置し – これらはすべて、決定記録、APIデザイン、データアクセスポターンと共に、App Architecture in Production クラスタでカバーされています。

有用なリンク

購読する

システム、インフラ、AIエンジニアリングの新記事をお届けします。