メインコンテンツへスキップ
見出し画像

仕様駆動開発で怖いのは「仕様とコードのズレ」だ――AI実装を検証する5つの観点

    requirements.md、design.md、tasks.mdができた。AIエージェントが実装し、テストも通った。


    ここまで来ると、「仕様駆動で開発できた」と思いたくなります。


    しかし、大規模な業務システムで本当に怖いのは、仕様書が存在しないことだけではありません。仕様があるのに、実装が少しずつ別物になっていくことです。


    たとえば、仕様には「取消可能」と書かれている。コードにも取消処理はある。ところが、特定の状態では取り消せない。画面とAPIで判定条件が違う。バッチ処理だけ旧ルールのまま残っている。


    個々の成果物はそれらしく見えても、全体として仕様に適合しているとは限りません。


    2025年以降、Spec Kit、Kiro、OpenSpecなど、仕様を中心にAIコーディングを進める仕組みが急速に整ってきました。次に必要になるのは、仕様を書く技術だけではなく、仕様・設計・コード・テストが一致し続けているかを検証する技術です。


    この記事では、ツールの使い方ではなく、既存の大規模システムで「仕様とコードのズレ」をどう見つけ、どう止めるかを考えます。


    仕様駆動開発は「仕様を作る」ところから先へ進み始めた


    GitHubのSpec Kitは、仕様、技術計画、タスク、実装をつなぎ、実装後にはconvergeで収束を確認する流れを持っています。


    KiroのSpec機能も、要求、設計、タスクという3つの成果物を作り、要件分析やプロパティベーステストによるCorrectnessを提供しています。


    OpenSpecは、変更ごとに提案、仕様、設計、タスクをまとめ、構成に応じてverifyで実装が仕様に合っているかを確認できます。公式ドキュメントでは、verifyはプロファイルによって有効になる検証工程として案内されています。


    つまり、現在の仕様駆動開発は「AIに渡すプロンプトを丁寧に書く」だけではありません。要求を構造化し、実装前に合意し、実装後に検証する開発プロセスへ近づいています。


    これは大きな前進です。


    一方で、ツールが検証コマンドを備えたことと、自分たちのシステムで適合性を保証できることは同じではありません。何をもって「一致」とするかは、対象システムの業務ルール、データ、状態、非機能要件によって変わるからです。


    「仕様がある」と「仕様に適合している」は違う


    仕様とコードのズレは、少なくとも3段階で発生します。


    1. 解釈のズレ


    仕様を書いた時点で、すでに曖昧さが入ります。


    「速やかに処理する」「必要に応じて通知する」「管理者だけが変更できる」といった記述は、人にもAIにも複数の解釈を許します。


    AIは曖昧な箇所で停止するとは限りません。周辺情報から、最も自然に見える実装を補います。その補完が業務上の意図と一致している保証はありません。


    2. 変換のズレ


    要求から設計、設計からタスク、タスクからコードへ変換するたびに、情報が落ちます。


    要求にあった例外条件が設計へ移らない。設計にあった排他制御がタスクへ入らない。タスクには書かれているが、実装中のリファクタリングで別の場所へ移動する。


    成果物が段階ごとに存在していても、その間の関係が追えなければ、欠落を発見できません。


    3. 時間によるズレ


    初回実装が合っていても、保守で崩れます。


    緊急改修ではコードだけが変わる。別チームがAPIを修正する。性能対策でキャッシュを入れた結果、更新直後の見え方が変わる。仕様は後で直すつもりのまま残る。


    仕様駆動開発を導入した直後より、半年後、1年後に整合性を保てるかの方が難しいのです。


    大規模システムでは「どれが正本か」だけで解けない


    「仕様を正本にすればよい」という説明は分かりやすいものの、業務システムでは少し単純すぎます。


    業務上の意図は要求仕様にあります。技術的な制約は設計にあります。実際に動く挙動はコードにあります。利用者へ提供している現実は、本番データと運用手順にあります。


    どれか一つだけを正しいことにすると、他の成果物との差異を「誤り」として潰してしまいます。しかし、その差異が緊急対応の理由や、暗黙の業務ルールを示していることもあります。


    必要なのは単一の正本というより、何の事実について、どの成果物を正本とするかを決め、その間を追跡可能にすることです。


    たとえば、次のように分けます。


    • 利用者が得る価値・業務ルール:要求と受入条件を正本にし、画面、API、業務テストと照合する

    • 状態遷移・例外条件:機能設計と状態モデルを正本にし、ドメインロジック、DB更新、イベントと照合する

    • 技術制約・品質属性:アーキテクチャ設計を正本にし、構成、静的解析、性能・障害試験と照合する

    • 実装された挙動:コードと設定を正本にし、テスト結果、本番観測と照合する

    • 運用上の扱い:運用設計と手順を正本にし、ジョブ、監視、権限、復旧実績と照合する


    この分担を決めないまま「仕様とコードを比較する」と、比較対象が大きすぎて判定できません。


    適合性を確認する最小単位は「文書」ではなく「追跡可能な要求」


    長い仕様書とリポジトリ全体をAIへ渡し、「一致していますか」と聞いても、監査可能な答えにはなりません。


    適合性を確認する単位を小さくします。


    たとえば、次のような関係を持たせます。


    要求トレース例


    要求 R-042 → 設計判断 D-017 → 実装タスク T-108 → コード C-claim-cancel → テスト E-231 → 検証結果 V-2026-09-29


    重要なのは、IDを付けること自体ではありません。


    • 何を実現する要求なのか

    • どの設計判断がその要求を具体化したのか

    • どのコードが実装しているのか

    • どのテストが適合を証明するのか

    • どの版に対する証跡なのか


    をたどれることです。


    この連鎖があれば、要求変更時に「関連しそうなコード」を検索するだけでなく、影響を受ける設計、テスト、運用手順を候補として出せます。逆に、変更されたコードから対応する要求が見つからなければ、意図不明の変更としてレビューできます。


    検証するべき5つのズレ


    実務では、「一致/不一致」の二択より、ズレの種類を分けた方が対応しやすくなります。


    1. 網羅性のズレ


    必須要求のうち、実装またはテストの証跡がないものを探します。


    単純な件数ではなく、対象外、延期、他システム担当などの例外理由も記録します。理由がない未実装と、承認済みの対象外を同じ欠落にしないためです。


    2. 意味のズレ


    同じ用語を使っていても、意味が違う場合があります。


    「確定」が画面では承認済みを指し、バッチでは会計連携済みを指す。customerが顧客本人を指す箇所と、契約主体を指す箇所が混在する。


    Embeddingの類似度だけでは、こうした意味の差を安全に判定できません。用語の定義、状態、主体、適用範囲を比較する必要があります。


    3. 制約のズレ


    「できること」だけでなく、「してはいけないこと」を確認します。


    • 取消済みデータを再確定してはならない

    • 自分の申請を自分で承認してはならない

    • 外部送信後の金額を直接変更してはならない


    否定形の制約は正常系のデモでは見落とされやすく、権限や監査に直結します。


    4. 状態遷移のズレ


    業務システムでは、入力と出力だけでなく「いつ、どの状態から実行できるか」が仕様です。


    受付中から取消済みへ移れるのか。処理中に再実行されたら冪等になるのか。エラー後にどの状態へ戻るのか。


    状態、イベント、事前条件、事後条件を構造化すると、コードの分岐、DB更新、イベント発行、テストケースと照合しやすくなります。


    5. 版・時点のズレ


    仕様とコードが一致していても、比較した版が違えば結論は無効です。


    少なくとも、仕様の版、コミット、生成・検証に使ったモデルや設定、テスト結果、判定日時を残します。「いつの何と何を比べたか」が分からない検証結果は、再現できません。


    機械判定・AI判定・人の承認を分ける


    適合性検証をすべてLLMへ任せる設計は危険です。自然言語の意味比較は得意でも、結果が揺れ、根拠のない補完も起こるからです。


    私は、検証を3層に分けるのが現実的だと考えます。


    層1:決定的に判定できるもの


    • スキーマ制約

    • API契約テスト

    • 静的解析

    • 単体・結合・E2Eテスト

    • 権限マトリクスの自動テスト

    • 状態遷移表から生成したテスト


    同じ入力なら同じ結果になる検証は、CIで失敗させて構いません。


    層2:追跡関係の完全性


    • 必須要求に実装リンクがあるか

    • 変更コードに要求または設計判断へのリンクがあるか

    • 受入条件にテスト証跡があるか

    • 廃止した要求の参照が残っていないか


    これは「正しい実装か」を直接保証しませんが、確認すべき穴を機械的に絞れます。


    層3:意味の適合性


    • 要求と設計の解釈は一致しているか

    • 実装が例外条件を落としていないか

    • テストが要求の言い換えに留まっていないか

    • コード変更が暗黙に仕様を変えていないか


    ここでLLMを使います。ただし、判定者ではなく不一致候補と根拠を提示するレビュー支援者として使います。


    最終的な承認は、業務影響と技術影響を判断できる人が行います。特に、高リスクな業務ルールや権限制御では、AIの「一致しています」をマージ条件にしてはいけません。


    Pull Requestに入れたい適合性ゲート


    仕様駆動開発を日常運用へ入れるなら、実装後にまとめて監査するより、変更単位で確認します。


    Pull Requestでは、次の順序が扱いやすいでしょう。


    1. 変更された仕様IDと設計判断を取得する

    2. 関連するコード、設定、テスト、運用手順を展開する

    3. スキーマ、契約、静的解析、テストを実行する

    4. 追加・変更された要求に証跡があるか確認する

    5. LLMが意味上の不一致候補を、該当箇所と理由付きで提示する

    6. 人が「適合」「例外承認」「要修正」「判定不能」を選ぶ

    7. 判定結果を仕様版とコミットへ結び付ける


    判定不能を用意することも重要です。情報不足なのにAIが無理に白黒を付けるより、追加確認へ戻せる方が安全です。


    最初のPoCで作るもの


    最初から全システムの要求、設計、コードをグラフ化する必要はありません。


    一つの機能を選び、次の範囲で試せます。


    • 必須要求を10〜20件に分け、安定したIDを付ける

    • 各要求に受入条件、例外、状態、根拠を持たせる

    • 対応する設計、コード、テストへリンクする

    • 仕様変更を2〜3件入れ、影響候補が出るか確認する

    • 意図的に一つ欠落、一つ矛盾、一つ古いリンクを混ぜる

    • AIと既存テストが、何を検出し、何を見逃すか測る


    評価指標は、少なくとも次の4つです。


    • 要求カバレッジ:必須要求のうち、実装・テスト証跡がある割合

    • 変更影響の再現率:正解として用意した影響対象を、どこまで候補に出せたか

    • 不一致候補の適合率:AIが警告したもののうち、本当に確認が必要だった割合

    • レビュー負荷:人が候補を確認し、判定するまでにかかった時間


    カバレッジが高くても、誤警告が多ければ運用されなくなります。精度だけでなく、人の確認コストまで含めて評価します。


    やってはいけない4つの近道


    仕様書とコードを丸ごとAIへ渡して「合っている?」と聞く


    対象範囲と判定基準が曖昧です。結果を再現しにくく、どの要求を確認したかも残りません。


    同じAIに実装と合否判定を任せる


    生成時の誤解を、検証時にも引き継ぐ可能性があります。少なくとも、独立した入力、評価観点、テスト、承認者を持たせます。


    コードへ合わせて仕様を自動更新する


    差異が消えたように見えるだけです。意図しない実装を仕様へ逆輸入すると、誤りが正当化されます。変更理由と承認が必要です。


    テストが通れば仕様適合とみなす


    テストは、書かれた観点しか確認しません。要求からテストへの追跡がなければ、重要な条件を丸ごとテストしていない可能性があります。


    仕様駆動開発の成否は「書けたか」ではなく「ズレを止められるか」で決まる


    Spec Kit、Kiro、OpenSpecは、要求を会話の中に消さず、仕様・設計・タスクとして残す道を開きました。


    ただし、大規模システムで価値を出すには、その先が要ります。


    • 要求を追跡可能な単位へ分ける

    • 仕様、設計、コード、テスト、運用を結ぶ

    • 網羅性、意味、制約、状態、版のズレを分けて検証する

    • 決定的なテストとAIの意味レビューを使い分ける

    • 人の承認と例外理由を証跡として残す


    AIがコードを書く速度は、これからも上がります。だからこそ、仕様から外れたコードも速く増えます。


    仕様駆動開発の次の競争力は、仕様を作る速さではありません。仕様と実装の差異を、変更のたびに小さく見つけて戻せることです。




    参考資料



    この記事の続きとして、次回は「要求・設計・コード・テストを結ぶ最小メタモデル」と、適合性チェックをCIへ入れる具体例を扱います。


    関連記事


    設計書RAGは、なぜ「検索できるだけ」で止まるのか


    変更影響をたどるために、設計要素の関係・根拠・同一性をどう持つかを整理しています。


     
     
    ユーザー企業の立場から、生成AI活用、社内SE、システム企画・設計を考えます。AIエージェントの権限・検証・運用や設計情報の活かし方を、実務で使える判断基準として整理します。

    あなたへのおすすめ