Spec-Driven Development 完全ガイド：ソフトウェア仕様で AI Coding Agent に開発を完遂させる方法

公式のクイックスタートでは、Spec-Driven Developmentの短縮経路は5段階、品質ゲートを含む完全経路は9段階で示されています。公式クイックスタートの手順が示す通り、勝者は「長いプロンプトを書く方法」ではなく、意図を仕様、設計、実行可能なタスク、検証証拠へ段階的に変換する方法です。個人開発では最小経路、チーム開発や監査が必要な案件ではレビュー工程を含む経路を選ぶと、AI Coding Agentの返工、文脈の漂移、受け入れ時の争議を抑えやすくなります。

本記事は、AI Coding Agentを使うたびに修正指示を繰り返している個人開発者、チームへAI開発を導入したい技術責任者、生成コードの監査と受け入れ根拠を必要とする開発チーム向けです。単なるプロンプト作成術ではなく、仕様を起点に開発成果物を追跡する手順を扱います。

最初に固定する：AI Coding Agentが触れてよい範囲

Spec-Driven Developmentを始める前に、プロジェクトの制約を一度ファイルへ記録します。技術スタック、ディレクトリ構成、命名規則、利用可能な依存関係、秘密情報の扱い、変更禁止区域、テスト方法、完成の定義を明文化してください。

この工程を省くと、AI Coding Agentは毎回の会話から前提を推測するため、次のような問題が起きます。

• 既存の認証処理を新しい方式へ置き換えてしまう
• 指定されたディレクトリ規則を無視してファイルを追加する
• テストを通すためだけに検証を弱める
• 設定ファイルや環境変数へ秘密情報を直接書き込む
• 変更範囲が不明なまま、関係のないモジュールまで修正する

プロジェクト全体で長期間使う制約と、今回の機能だけに属する要件は分けます。公式のSpec Kitでは、プロジェクトの原則や開発方針をconstitution.mdへまとめ、後続の仕様、計画、実装で参照する流れが採用されています。Spec-Driven Developmentの基本原則でも、仕様を中心成果物として扱い、コードをその実装結果として管理する考え方が説明されています。

Spec-Driven Developmentはどこから始めればよいか。
最初にプロンプトを書くのではなく、次のチェック項目を埋めるところから始めます。

• [ ] 採用中の言語、フレームワーク、ビルドコマンドを記録する
• [ ] 変更してよいディレクトリと禁止区域を分ける
• [ ] 認証、個人情報、秘密情報に関する安全境界を定義する
• [ ] 必須の静的解析、単体テスト、統合テストを列挙する
• [ ] 完成とみなす条件を、コード以外の確認項目も含めて記録する
• [ ] 仕様、計画、タスク、テストを同じバージョン管理の流れで保存する

注意： プロジェクト制約は細かければよいわけではありません。毎回変わる実装上の判断まで固定すると、古いルールがAI Coding Agentの足かせになります。安定した境界だけを共通ルールに残します。

仕様を判定可能にする：Specificationへ変換する

ユーザーの要望をそのまま「管理画面を作る」と書いても、実装の完了条件は決まりません。Specificationには、少なくとも対象となる利用者の行動、入力、期待する出力、失敗時の挙動、権限、保存条件、非機能要件を含めます。

例えば「画像をアルバムへ整理する」という要望は、次のように分解できます。

• 利用者は画像を選択して既存アルバムへ追加できる
• アルバム名が空の場合は保存を拒否する
• 同一画像を再登録した場合は重複扱いを明示する
• 権限のない利用者は他人のアルバムを変更できない
• 保存に失敗した場合、画面上の表示だけを成功状態へ変更しない
• 主要な操作は自動テストまたは手動確認で判定できる

ソフトウェア仕様はどの程度まで書けばAI Coding Agentが実行できるか。
Agentが実装方法を推測しなくても、入力と結果の対応を判断できる程度まで書きます。一方で、Specificationの段階から具体的なクラス名やデータベース製品を強制すると、「何を実現するか」と「どう実装するか」が混ざります。公式のクイックスタートでも、仕様段階では何を作るかと理由に集中し、技術スタックや構成は計画段階で決める流れが案内されています。

仕様には、検証方法も隣接させます。

要件：利用者はアルバムへ画像を追加できる
入力：認証済み利用者、既存アルバム、対応形式の画像
成功：画像が一覧に表示され、再読み込み後も保持される
失敗：未認証、存在しないアルバム、未対応形式では保存されない
検証：単体テスト、API確認、画面上の手動確認

この形なら、実装後に「何となく動く」ではなく、仕様ごとに証拠を集められます。性能や処理時間など、実測しない数値をSpecificationへ入れるのは避け、必要な場合は測定方法と許容条件を先に決めます。

設計からタスクへ進む：一度に広げすぎない

Specificationができたら、AI Coding Agentへすぐ実装を指示しません。まず技術計画を作り、既存モジュールへの影響、データ構造、API境界、テスト方針、移行やロールバックの要否を確認します。

公式Spec KitのCLIリファレンスでは、プロジェクト初期化からワークフロー管理までを段階的に扱う構成が整理されています。仕様作成、計画作成、タスク分解、実装の流れを分けることで、Agentにすべてを一度に依頼するより、判断の境界を保ちやすくなります。さらに、要件の曖昧さを整理するclarify、成果物間の整合性を確認するanalyze、実装後の不足を調べるconvergeも用意されています。

タスクは「画面を作る」のような大きな単位ではなく、実装と検証を一つの流れとして完結できる単位へ分けます。

• データモデルと保存処理を追加する
• 認証済み利用者の権限判定を追加する
• 画像追加APIの成功系を実装する
• 入力不備と重複登録の失敗系を実装する
• 一覧画面へ結果を表示する
• 仕様に対応するテストと手動確認項目を追加する

各タスクには、前提、変更対象、完了条件、実行する検証コマンド、依存関係を持たせます。複数の無関係なモジュールを一度に変更するタスクは、レビュー範囲が広がり、失敗時にどこへ戻るべきか分からなくなるため避けます。

AI Coding Agentは仕様に沿ってどのようにタスクを分解するか。
「実装して」とだけ指示せず、Specificationと計画を入力にして、依存順、独立して検証できる単位、変更ファイル、完了条件を出力させます。公式のAgentic SDDリファレンスでは、計画から実行可能なタスクを生成し、段階ごとに実装と検証を進める運用が説明されています。

実装を進める：一回の指示を一つの検証単位にする

実装段階では、毎回すべての資料をAI Coding Agentへ渡す必要はありません。現在のタスクに必要な仕様、関連ファイル、依存タスクの結果、検証コマンドだけを渡します。これにより、過去の会話や不要な設計案が現在の判断へ混ざるのを防げます。

変更前には、Agentに次の内容を短く提示させます。

• 変更対象となるファイル
• 仕様のどの項目を満たす変更か
• 既存コードへの影響
• 実行予定のテストや静的解析
• 変更しない範囲と、判断が必要な点

変更後は、差分、実行結果、未解決事項を出力させます。テストが失敗した場合、エラーを隠すためにテストを変更するのではなく、仕様、計画、実装のどの層に原因があるかを切り分けます。

経験則： 大きな機能を一回の実装指示で完成させようとすると、Agentの文脈だけでなくレビュー担当者の確認範囲も膨張します。大規模機能は段階ごとに実装し、各段階を検証してから次へ進める方が、差分の原因を追跡しやすくなります。

受け入れを行う：仕様へ証拠を戻す

受け入れでは、テストが成功したという結果だけを見ません。元のSpecificationに対して、どの証拠がどの要件を満たすかを対応付けます。

確認対象	確認する証拠	不合格時の戻り先
利用者の行動	画面操作と期待結果	Specification
入力と出力	API確認、単体テスト	Specificationまたは実装タスク
権限と安全境界	権限別の確認、ログ	設計またはタスク
既存機能への影響	回帰テスト	実装タスク
完成条件	チェック項目の記録	未完了タスク

公式のクイックスタートでは、checklistを仕様の完全性を確認する品質ゲート、analyzeをspec.md、plan.md、tasks.md間の矛盾や欠落を確認する工程として扱っています。analyzeの詳細は公式ワークフロー説明で確認できます。

convergeは実装後に仕様、計画、タスクとコードを照合し、不足があればタスクへ追加します。問題を一時的な追加指示で隠さず、原因を持つ成果物へ戻して修正してください。

受け入れの終了条件は「Agentが完了と言った」ではありません。仕様項目ごとに、テスト結果、静的解析結果、APIの確認、画面の手動確認、レビュー記録のいずれかが存在し、未確認項目が明示されている状態です。

仕様を変更する：コードではなく影響範囲から更新する

Specificationの変更後にコードの失控を防ぐにはどうすればよいか。
先にコードへ追記せず、仕様を更新し、変更理由、影響する設計、既存タスク、テスト、後方互換性を確認します。その後に計画とタスクを再生成し、完了済みタスクを再実行するのか、新しいタスクだけを追加するのかを決めます。

大規模な機能を一つの仕様へ詰め込むと、Agentが途中で全体像を失いやすくなります。公式のSpec of Specsでは、大きな機能を独立した小さな仕様へ分割し、それぞれに仕様、計画、タスク、実装の流れを適用する方法が説明されています。

変更の種類	先に確認するもの	実装の扱い
表示文言や画面配置	画面仕様、手動確認	影響する画面タスクのみ更新
入力条件の変更	API仕様、失敗系テスト	既存テストと契約を更新
データ構造の変更	移行方法、互換性	移行タスクを独立させる
権限ルールの変更	安全境界、監査ログ	実装前にレビューゲートを置く
機能範囲の拡大	上位仕様、依存関係	独立したサブ仕様へ分割

仕様をバージョン管理へ保存すると、コードレビューで「この変更はどの要求に対応するのか」を確認できます。仕様とコードのずれを継続的に確認する考え方は、Spec Kitのアップグレードガイドでも説明されています。仕様をチャット履歴だけへ置くと、担当者が変わった時点で根拠と変更履歴が失われます。

実行環境を選ぶ：ローカル開発とMac環境の比較

仕様駆動の流れ自体は、ローカル環境でもクラウド環境でも実行できます。ただし、AI Coding Agent、依存関係、テスト、画面確認を同じ状態で繰り返すには、環境を再構築できることが重要です。

Spec Kitの公式ドキュメントでは、ワークフローを自動化し、人によるレビューゲートで一時停止・再開する方式も説明されています。公式ワークフローのリファレンスを使えば、手動で同じコマンドを繰り返す運用から、再現可能な開発手順へ移行しやすくなります。

選択肢	向いている条件	注意点
手元の開発機	長期開発、物理機器との接続、常時利用	環境差分とマシン占有が残る
一般的なクラウド開発環境	短期検証、チーム共有、初期構築の簡略化	OS固有の確認や画面操作に制約が出る場合がある
Macのレンタル環境	Apple向けビルド、CI/CD、遠隔テスト、期間限定の検証	長期の高負荷運用や物理インターフェース依存には不向き

仕様とテストを保存していても、実行環境が毎回異なれば再現性は下がります。ZutcloudのMacレンタル環境を検討する場合は、必要なSDK、署名情報、テスト用アカウント、リセット手順、接続方式を先にチェックしてください。導入前の条件確認にはZutcloudのヘルプセンターも利用できます。

現在の開発環境を使い続ける方法は、長期にわたり同じマシンを占有でき、物理インターフェースや常時稼働が必要な場合に合理的です。一方で、共有端末の順番待ち、環境差分、OS更新による再現性低下、短期間だけ必要なMac実機の調達負担が残ります。Apple向けの一時的なビルド、AI Coding Agentを使った検証、複数担当者の再現テストが目的なら、必要な期間だけZutcloudのMac環境を借りる方が、専用機を購入するより判断しやすいケースがあります。

仕様書を作っただけでは、AI Coding Agentの出力は安定しません。プロジェクト制約を固定し、判定可能なSpecificationへ変換し、設計とタスクを分離し、実装後の証拠を元の仕様へ戻すことが、返工と受け入れ争議を減らす中心的な運用です。次に環境を整える段階では、バージョン管理、テストツール、秘密情報の分離、そしていつでも初期状態へ戻せるMac実行環境が揃っているかを確認してください。短期の検証やApple向け開発環境が必要な場合は、Zutcloudのサービス案内から利用条件を確認できます。