Spec-Driven Development×AI Coding Agent完全ガイド

Spec Kitの公式ドキュメントでは、エージェント型のSDDを「constitution → specify → clarify → plan → checklist → tasks → analyze → implement → converge」という9段階で説明しています。公式のAgentic SDDリファレンス
この流れから分かる通り、成果を分けるのは長いプロンプトではありません。Spec-Driven Developmentの勝ち筋は、意図を制約、Specification、設計、独立実行できるタスク、検証証拠へ段階的に変換し、AI Coding Agentがコードを変更する前に不可変の境界を決めることです。

個人開発でAI Coding Agentに何度も修正を指示している開発者、AIプログラミングをチーム工程へ組み込みたい技術責任者、生成コードの監査と受け入れ根拠を残したい開発チームに向いています。単純な一行修正だけなら過剰ですが、複数モジュールにまたがる機能では、仕様を先に固定する効果が大きくなります。

Spec-Driven DevelopmentとAI Coding Agentの準備を分ける

第一段階：プロジェクトの制約を先に固定する

最初に作る成果物は機能の説明ではなく、プロジェクト全体に適用する判断基準です。使用する言語とフレームワーク、ディレクトリ構成、命名規則、実行可能な検証コマンド、秘密情報の扱い、変更禁止区域、完了の定義を記録します。

Spec Kitでは、プロジェクトの原則を定めるためのconstitutionと、機能の要求を作るspecifyが別の工程になっています。公式リポジトリのコマンド一覧でも、constitution、specify、plan、tasks、implementが中核コマンドとして整理されています。

Spec-Driven Developmentはどのように始めるべきでしょうか。
まず既存リポジトリを読み込ませて、いきなりコードを書かせるのではなく、次の内容を短い文書にします。

• 採用している技術と実行環境
• 変更してよいディレクトリと変更禁止のファイル
• 認証情報、個人情報、外部APIキーの取り扱い
• 必須のテスト、静的解析、ビルド確認
• 受け入れ時に人間が確認する画面や操作
• 不明点が残った場合に実装を停止する条件

注意：制約を毎回プロンプトへ貼り付ける運用では、会話が長くなるほど重要な禁止事項が埋もれます。リポジトリ内で版管理し、すべての作業の前提として参照させる方が監査しやすくなります。

第二段階：判定可能なSpecificationへ変換する

要求文は「使いやすい画面にする」では実装できません。AI Coding Agentが判断できるSpecificationにするには、利用者の行動、入力、期待する出力、失敗時の状態、権限、非機能条件まで分けて記述します。

例えば、タスク管理画面なら次のように書き換えます。

• 利用者がタイトルを入力して保存すると、一覧に新しいタスクが表示される
• タイトルが空の場合は保存せず、入力欄の近くにエラーを表示する
• 権限のない利用者は作成APIを呼び出せず、画面にも作成操作を表示しない
• 保存に失敗した場合、入力内容を失わず再送信できる
• 受け入れ条件は、正常系、入力エラー、権限エラー、通信失敗の各シナリオで確認する

ソフトウェア仕様はどこまで細かく書けばAI Coding Agentが実行できるのでしょうか。
実装方法まで決める必要はありませんが、完了と未完了をテスト、ログ、画面確認のいずれかで判定できる粒度まで書く必要があります。ライブラリ名を先に固定するより、「何を受け取り、何を返し、どの状態を禁止するか」を先に明確にする方が、設計の選択肢を保てます。

仕様書には、次の4項目を必ず対応させます。

仕様の要素	記述する内容	確認方法
振る舞い	利用者操作とシステムの反応	結合テスト、画面確認
入出力	型、必須条件、エラー形式	単体テスト、API確認
境界条件	空値、重複、権限不足、通信失敗	異常系テスト
非機能条件	安全性、ログ、互換性、運用制約	静的解析、レビュー

設計とタスクを段階的に作る

第三段階：Specificationから設計案を作成する

仕様が固まったら、AI Coding Agentに実装を依頼する前に設計案を出させます。変更対象のファイル、データモデル、API境界、既存処理への影響、テスト方針、採用しない案を明記させると、実装途中の方針変更を減らせます。

Spec Kitの公式説明では、planは技術的な実装計画を作り、tasksは計画や関連資料から実行可能な作業一覧を生成します。公式のワークフロー説明では、タスクに依存関係、並列実行の印、対象ファイル、検証用の区切りを含める流れが示されています。

ここで重要なのは、AIの設計案をそのまま承認しないことです。次の条件に該当する場合は、仕様または設計に戻します。

• 1つのタスクがフロントエンド、API、データベースを同時に変更する
• 完了条件が「実装する」「対応する」だけで、確認方法がない
• 変更対象のファイルが特定されていない
• 既存の認証、ログ、エラー処理への影響が書かれていない
• 失敗時にどの状態へ戻すか決まっていない

第四段階：独立して検証できるタスクへ分割する

AI Coding Agentは仕様からどのようにタスクを分割すべきでしょうか。
機能の画面単位ではなく、実装と検証を一組にして分けます。例えば「タスク作成機能を作る」ではなく、「入力モデルを追加する」「作成APIの正常系を実装する」「入力エラーを実装する」「画面からAPIを呼び出す」「各シナリオを検証する」と分解します。

タスクには、目的、前提、変更範囲、依存タスク、実行するコマンド、完了条件を含めます。1回のAgent実行で広い範囲を任せるほど、文脈のずれを発見しにくくなります。小さな単位で差分を確認し、次のタスクへ進む運用が安全です。

実装前後の証拠を残す

第五段階：現在のタスクだけを渡して実装する

実装時は、プロジェクト全体の資料を毎回まとめて渡すのではなく、現在のタスクに必要なSpecification、関連ファイル、依存関係、検証コマンドだけを提示します。変更前には計画を3点程度で説明させ、変更後には差分、実行したコマンド、結果、未解決事項を出力させます。

Agent生成コードの受け入れ確認に関するガイドでも、実装前に成果物間の整合性を確認し、問題があればコードではなく、問題を所有する仕様、計画、タスクへ戻る考え方が示されています。

• [ ] 現在のタスクが変更するファイルを列挙している
• [ ] 変更禁止区域に触れないことを確認している
• [ ] 実装前の計画と採用理由を記録している
• [ ] 差分が現在のSpecificationの範囲内に収まっている
• [ ] 自動テスト、静的解析、ビルドを実行している
• [ ] 未達の受け入れ条件をタスク単位で記録している
• [ ] 次のタスクへ進む前にレビュー可能な状態にしている

analyzeのような整合性確認は、仕様、設計、タスクの食い違いを実装前に発見するために使います。公式のAgentic SDDリファレンスでは、問題があれば該当する上流工程へ戻し、再度分析する流れが説明されています。

経験上、テストが落ちたときに追加プロンプトで場当たり的に直し続けると、元の仕様から離れた修正が積み重なります。失敗の原因が要件なら仕様へ、設計なら計画へ、実装範囲ならタスクへ戻す判断を先に決めておくべきです。

仕様変更に合わせて保守する

第六段階：変更はSpecificationから始める

仕様変更後にコードが制御不能になるのをどう防ぐのでしょうか。
コードを先に直すのではなく、変更理由、影響する仕様、設計差分、タスクの再生成、既存テストへの影響を順番に記録します。仕様と実装を同じブランチやプルリクエストで扱えば、レビュー担当者はコードだけでなく、何が変わったのかを確認できます。

機能が大きい場合は、全体を一度に実装せず、独立した小さな仕様へ分割します。Spec of Specsの公式資料では、ロードマップを複数のサブ仕様へ分け、それぞれにspec.md、plan.md、tasks.mdを持たせる考え方が説明されています。

変更内容	先に更新する成果物	再確認する範囲
入力条件の変更	Specification	API、画面、異常系テスト
技術方式の変更	設計計画	依存関係、データ構造、運用
作業順の変更	タスク一覧	前提条件、並列実行、安全な順序
受け入れ条件の変更	検証項目	自動テスト、手動確認、記録

Spec Kitのアップグレード手順では、ツール更新時に統合用ファイルやテンプレートが更新対象になる一方、既存の実装計画やタスクは安全性を確認したうえで扱う方針が示されています。ツールのバージョンを固定し、更新後は生成物の差分をレビューする運用が必要です。

AI Coding Agentを導入する環境を選ぶ

仕様駆動の工程は、Agentの能力だけで完結しません。バージョン管理、再実行できるテスト環境、作業を初期状態へ戻す手段、必要な開発ツールへの権限が揃っていなければ、仕様と証拠の対応を維持できません。

運用方法	向いている条件	注意点
手元の開発環境	長期開発、物理機器への接続、細かなデバッグ	環境差分と再現手順の管理が必要
一般的なクラウド環境	チーム共有、CI連携、短期検証	OS固有のツールやGUI検証に制約が出る場合がある
Macのレンタル環境	Apple向けビルド、実機に近い検証、期間限定の開発	利用可能なツール、接続方式、リセット条件を事前確認する

現在の環境が共有サーバー中心の場合、依存パッケージの差分、権限設定、長時間ジョブ後の状態残り、GUI操作の検証不足が問題になりやすいです。Apple向けの開発や自動化テストでは、必要なOS環境を短期間だけ確保できるかが判断材料になります。ZutcloudのMacレンタル環境の案内では、利用目的に応じた環境確認を進められます。

一方、長期にわたり同じ構成で高負荷処理を続ける場合や、物理ポート・専用機器を常時使う場合は、自社所有のMacや既存設備の方が適しています。短期の検証、チームの一時的な開発環境、AI Coding Agentの実行基盤を早く用意したい場合には、レンタルの方が初期構築と撤去の負担を抑えやすい選択肢です。利用条件や接続方法に不明点がある場合は、Zutcloudのヘルプセンターで確認してから環境を決めると、仕様検証の途中で作業基盤を変更するリスクを避けられます。

関連記事

• AIエージェントのファイルシステム設計と安全な実行環境
• 複数のAIエージェントを並列開発するためのタスク分解と統合手順
• AIエージェントの役割分担と状態管理を設計するフレームワーク比較