Spec-Driven Development ワークフロー詳解

GitHub Spec Kitの公式ドキュメントは、Spec-Driven Developmentを「Spec → Plan → Tasks → Implement」の流れとして提供し、35のAIコーディング環境との連携を案内しています。 (github.github.com)

症状： AI Coding Agentへ要件をそのまま渡すと、仕様の抜け、過剰な実装、失敗後に戻れない長時間タスクが発生します。 最短解： 仕様を管理する軌道と、コード変更を進める軌道を分離し、バージョン、タスク識別子、テスト結果で結びます。一度の指示で完成コードを生成させるのではなく、承認可能な成果物を順番に交接してください。

この内容は、実際のリポジトリへSpec-Driven Developmentを組み込みたい開発チーム向けです。AIが生成したコードを複数人で審査する責任者や、長時間動作するAI Coding Agentの作業を追跡したい開発者にも適しています。

まず採用すべきは「二つの軌道」です

Spec-Driven Developmentを単なるプロンプトの書き方として導入すると、Specificationを書いた後も、どのコードへ影響するのか、誰が承認したのか、何をテストしたのかが曖昧になります。実務では、次の二つを別々に管理してください。

仕様軌道は「何を満たすべきか」を固定し、コード軌道は「既存の構成でどう実現したか」を記録します。両者を同じ識別子で結べば、レビュー時に「このコードはどの要件に対応するのか」「この仕様の例外経路は実装されたのか」を確認できます。

GitHub Spec Kitでも、各段階で生成されたMarkdown成果物を次の段階へ渡す考え方が採用されています。公式の概要では、構造化された成果物がAI Coding Agentへ文脈を提供すると説明されています。 (github.github.com)

要件レビューで境界を確定する

最初の成果物は、実装案ではなく、判定可能な要件です。担当者は次の項目を埋め、曖昧な要望をそのままSpecificationへ送らないようにします。

• 対象ユーザーと利用前提
• ユーザーが実行する主要な行動
• 成功とみなす状態
• 明確に実装しない範囲
• 権限、互換性、性能、データ保護に関する制約
• エラー時や入力不備時の振る舞い
• まだ確認できていない事項

たとえば「管理画面を改善する」では、完了条件を判定できません。「管理者が一覧画面から対象を絞り込み、詳細画面へ移動できる」のように、利用者、行動、結果を分ける必要があります。

ここでの交接条件は、レビュー担当者が同じ入力に対して同じ完了判定をできることです。受け入れ条件が「使いやすくする」「高速化する」のような評価語だけなら、技術計画へ進めず、計測方法や判定基準を追加してください。

Specificationと技術計画を混ぜない

Specificationは、システムが示すべき振る舞いを定義する文書です。データ項目、インターフェース、異常時の処理、受け入れ条件を構造化し、元の要件識別子へ関連付けます。

一方、技術計画は、既存のリポジトリへ変更を適用するための設計です。両者を混ぜると、技術上の都合で要件が無断変更され、後から「仕様にない機能が追加された」状態になります。

GitHub Spec Kitでは、specify、plan、tasks、implementが主要な流れとして示されています。現在の公式リポジトリでは、必要に応じてclarifyやanalyzeなどの補助コマンドも案内されています。具体的なコマンド名や連携方式は更新される可能性があるため、導入時は公式リポジトリのコマンド一覧を確認してください。 (github.com)

リポジトリ準備で先に固定するもの

AI Coding Agentを実行する前に、リポジトリ上の作業場所と成果物の保存先を決めます。既存のGitフローへ接続する場合は、次のような構成が扱いやすいです。

• 仕様、計画、タスクを機能単位のディレクトリへ保存する
• 要件、Specification、タスク、ブランチ、プルリクエストに同じ識別子を付ける
• 生成された差分だけでなく、実行した検証コマンドと結果も保存する
• 秘密情報をAgentの入力やログへ含めない
• 仕様変更とコード変更を同じレビュー単位で追跡する

並行作業が多い場合は、同じリポジトリから複数の作業ツリーを作るgit worktreeも候補になります。公式マニュアルでは、複数のブランチを同時にチェックアウトでき、作業ツリーごとにHEADやインデックスなどを分離できると説明されています。 (git-scm.com)

ただし、環境変数、依存パッケージ、データベース接続先を作業ツリー間で共有すると、Agent同士が同じ検証環境を変更する危険があります。コードの分離だけでなく、実行環境、ログ、テストデータ、権限も作業単位で分けてください。

注意： ワークフローに自動実行のシェル工程を追加する場合、実行権限を過信しないでください。Spec Kitの公式ワークフロー資料でも、シェル工程はローカル権限で動作し、サンドボックスを提供するものではないと説明されています。 (github.com)

AI Coding Agentのタスクを小さく交接する

AI Coding Agentへ渡すタスクには、最低限、次の情報を含めます。

• 対応するSpecificationの識別子
• 変更対象となるファイルまたはディレクトリ
• 変更してはいけない範囲
• 実行するテスト、静的解析、ビルドのコマンド
• 完了と失敗を判定する条件
• 変更後に残してはいけない仮実装やデバッグ出力

タスクの大きさは、作業時間ではなく、失敗時にどこまで戻せるかで決めます。複数の機能、データ移行、認証変更を一つの長い指示へまとめると、失敗箇所が分からず、レビューも差分確認も困難になります。

判断条件は次のように置いてください。

• 対象ファイル、検証命令、完了条件を明記できるなら、その単位でAI Coding Agentへ渡します。
• 複数コンポーネントを変更するが、各変更を独立して検証できるなら、検証可能な単位へ分割します。
• データ移行や権限変更を含むなら、実装タスクの前に調査タスクと人間の承認工程を置きます。
• 失敗後に成果物を再利用できないなら、チェックポイントを追加してから実行します。
• 仕様が未確定なら、コード実装を始めず、確認事項をSpecificationへ戻します。

公式のワークフロー資料では、レビュー用のゲートを置き、承認または却下によって次工程の実行を制御する例が示されています。さらに、実行状態、入力、ステップごとのログを保存し、停止や失敗後に再開できる仕組みも説明されています。 (github.com)

コードレビューでは差分と仕様を同時に見る

コードレビューで確認するのは、文法、可読性、テストの有無だけではありません。次の観点を同じレビュー記録へ残してください。

• 仕様にある正常系が実装されているか
• 仕様にある例外系や権限条件が抜けていないか
• Specificationにない機能をAgentが追加していないか
• テストが受け入れ条件を検証しているか
• 実行したコマンド、成功結果、未解決事項が記録されているか
• 依存関係やデータ形式の変更が技術計画と一致しているか

GitHubでは、ステータスチェックを保護ブランチの必須条件に設定でき、テストやビルドが通らないプルリクエストをマージ前に止められます。 (docs.github.com) また、CODEOWNERSを使えば、特定のファイルやディレクトリを変更したプルリクエストへ責任者を自動的に割り当てられます。 (docs.github.com)

レビュー担当者へ渡すAgentの出力は、次の形式に統一すると確認が速くなります。

• 変更したファイルと差分の要約
• 対応したSpecificationの識別子
• 実行した検証コマンドと結果
• 仕様上または技術上の未解決事項
• 追加変更を見送った理由

Gitと継続的デリバリーへ接続する

既存のGitフローへ組み込むときは、仕様ファイルを単なる作業メモとして扱わないことが重要です。仕様、計画、タスク、コード、テスト結果を同じ変更単位で確認できるようにします。

仕様変更が発生した場合は、先にSpecificationを更新し、影響する技術計画とタスクを再生成します。コードだけを先に修正すると、現在の実装が正しいのか、旧仕様に対する暫定対応なのかを判断できなくなります。

Spec Kitのアップグレード資料では、実装計画、タスク、ソースコード、Git履歴はアップグレード時に保護される対象として説明されています。ただし、導入済みの連携ファイルや拡張機能は更新手順の確認が必要です。 (github.com)

実務では、マージ前に次の交接条件を確認してください。

• 仕様の識別子とプルリクエストが一致している
• 技術計画と実際の変更範囲が一致している
• 受け入れ条件に対応するテスト結果がある
• 未解決事項がレビュー担当者へ明示されている
• リリース後の不具合を仕様へ戻す担当が決まっている

既存環境とMac環境を比べる最後の確認

既存のローカル環境や一般的なクラウド開発環境でも、このワークフロー自体は実行できます。ただし、長時間のAI Coding Agent運用では、作業環境が一時停止する、ログが保持されない、作業ツリーの復元が手作業になる、レビュー担当者が安全に接続できない、といった問題が起きると、仕様とコードの二軌道を保てません。

一時的な検証やチーム外の担当者によるレビューでは、Mac環境を固定して使えるレンタル方式が実務に合う場合があります。kvmbootのヘルプセンターで、リポジトリ隔離、ログ保存、スナップショット復元、接続権限を確認し、必要なら日本向けの利用案内で条件を比較してください。長期にわたり常時稼働する重い処理や物理機器への接続が必要なら、自社管理のMacや専用環境のほうが適しています。

Spec-Driven Developmentの成否は、Agentの性能だけでは決まりません。仕様ファイル、コード差分、テスト結果、復旧可能な実行ログを一つの交接単位として保管できるかを確認してから、チームの既存フローへ導入してください。