仕様駆動開発で「どれが正しい仕様？」がわからなくなったので、管理方針を決めた話

仕様駆動開発で「どれが正しい仕様？」がわからなくなったので、管理方針を決めた話

こんにちは、サーバーワークスで生成AIの活用推進を担当している針生です。

AI-DLC（AI-Driven Development Life Cycle）で開発を進めていると、サイクルごとに要件書・設計書・コードが生成されます。しかし、サイクルを重ねるにつれて「結局どれが正しい仕様なのか？」という疑問が出てきました。

本記事では、Spec-Driven Development（SDD）の知見を取り入れつつ、AI-DLCプロジェクトにおけるドキュメント管理方針を策定した過程を共有します。

要約

• AI-DLCで開発を進めると、サイクルごとに要件書・設計書・コードが生成されるが、「どれが正しい仕様か」はフレームワーク側で定義されていない
• 業界ではSpec-Driven Development（SDD）が台頭し、仕様の厳密さに応じてspec-first / spec-anchored / spec-as-sourceの3段階が定義されている
• AI-DLCの「Always rerun」ルール（Reverse Engineeringを毎サイクル再実行）を活用し、spec-anchored寄りのドキュメント管理方針を策定した

背景：AI-DLCで複数サイクルの開発を進めた

あるプロジェクトをAI-DLCワークフローで開発しています。複数の機能モジュールを持つ中規模のアプリケーションです。

開発は複数サイクルで進めました。

1. 初回構築：コア機能の実装
2. 機能追加：新しいモジュールの追加

2サイクル目を終えた時点で、ふと疑問が浮かびました。

「このプロジェクトの正式な仕様書は何なのか？」

問題：仕様ドキュメントが散在する

AI-DLCは各サイクルで以下のような成果物を生成します。

• Requirements（要求仕様）：なぜその機能を作るか
• Application Design（設計書）：どのように実装するか
• Functional Design（詳細設計）：ビジネスロジックの定義

サイクルが増えるたびにドキュメントが蓄積されます。初回のrequirements.mdと2回目のfeature-b-requirements.mdが並存し、どちらも「仕様書」ですが、スコープが異なります。個別のRequirementsは各サイクルの要求しかカバーしないため、システム全体の現在の仕様を示すドキュメントがどこにもありません。

「今のシステムの仕様を知りたい」とき、どこを見ればいいのでしょうか？

調査：業界ではどう管理しているのか

「正式な仕様」をどう定義するかという問題は、自分だけが抱えているわけではないはずです。業界全体の動向を調査しました。

Spec-Driven Development（SDD）の3段階

martinfowler.comの記事やプレプリント（査読前論文、arXiv:2602.00180）では、仕様運用の厳密さに応じた3段階が示されています。

Spec-first（仕様第一）

• 実装前に仕様を書き、コード完成後は廃棄される
• コードが事実上のSource of Truth
• プロトタイプや一度限りの開発向け

Spec-anchored（仕様連動）

• 仕様をコードと共に進化させる「生きた文書」
• 仕様とコードの両方がSource of Truth
• 「ほとんどの本番システムに最適」とプレプリントで推奨

Spec-as-source（仕様＝ソースコード）

• 仕様のみ人が編集し、コードは完全に自動生成
• 仕様がSource of Truth（コード編集禁止）
• Simulink等のモデルベース開発の実績がある成熟した領域向け

GitHub spec-kit Discussionの議論

GitHub spec-kitのDiscussion #152では、まさに「仕様をどう進化させるか」が活発に議論されています。

主な対立軸は以下の通りです。

• 「機能別に仕様書を作り履歴保持」派 vs 「単一マスター仕様を維持」派
• 複数仕様書が存在すると「システムの現在の状態を理解するために複数の文書を読む必要がある」という認知負荷の問題
• 解決策として「仕様の圧縮」（複数の変更仕様を統合して現在の状態を示す単一仕様に変換）が提案

また「LLMにコードそのものを読ませればいい。完全にコードを生成できるまでは、仕様をSource of Truthとすべきでない」という実用主義的な意見もありました。

AI-DLCとSDDの関係

参考として、LinkedIn上のDerick Chen氏の投稿では、AI-DLCとSDDは「根本的に対立するものではない」という見解が示されています。SDDが個人〜小規模チーム向けなのに対し、AI-DLCは「分散型の成果物管理」と「チーム横断コラボレーション」に設計されているとのことです。両者とも仕様ドキュメントを基盤とする点は共通しています。

分析：SDDの観点でAI-DLCを見直す

SDDの3段階という判断軸を得た上で、AI-DLCフレームワーク自体を分析しました。

まず確認したのは、AI-DLCが仕様書の管理ポリシーを定義しているかどうかです。結論として、明示的な定義はありませんでした。フレームワークが定義しているのは「どの成果物をいつ生成するか」というワークフローだけで、「どれが正式な仕様か」「古い仕様をどうするか」は各プロジェクトに委ねられています。

しかし、AI-DLCのReverse Engineeringルールファイルを読み進めると、重要な記述を見つけました。

Rerun behavior: Always rerun when brownfield project detected, even if artifacts exist. This ensures artifacts reflect current code state

つまり、既にReverse Engineering成果物が存在していても、新サイクル開始時には常に再実行して上書き更新するということです。

これをSDDの分類に照らすと、コード起点で仕様を継続更新するspec-anchored寄りの運用と捉えられます。

• 差分更新ではなく全置換：仕様の部分的な陳腐化が構造的に起きない
• コードからの逆生成：仕様とコードの乖離を最小化しやすい
• 毎サイクル自動実行：手動同期の手間がない

ただし、これは「実行ルール」であって「管理ポリシー」ではありません。「Reverse Engineering成果物を正式な仕様とする」と明示的に宣言する必要がありました。

結論：策定したドキュメント管理方針

これらの調査と分析を踏まえ、以下の方針を策定しました。

Source of Truthの定義

区分	成果物	役割
正式版（現行仕様）	Reverse Engineering成果物	コードから自動生成。毎サイクル上書き更新
履歴（意思決定記録）	Requirements / Design成果物	サイクル単位で不変保存。「なぜ作ったか」の記録

まず初回のReverse Engineeringを実行し、現行コードからシステム全体の仕様を生成します。以降のサイクルでは「Always rerun」ルールに従い、毎回再生成して正式版を最新に保ちます。

ライフサイクル

新サイクル開始
  |
  +-- Reverse Engineeringを実行（正式版を最新化 = spec-anchored寄りの同期）
  |
  +-- 新Requirementsを作成（今回の要求 = 履歴として蓄積）
  |
  +-- Design/Code/Test実行
  |
  +-- サイクル完了
       +-- Reverse Engineering成果物 --> 次サイクルで再生成
       +-- Requirements/Design --> 履歴として不変保存

仕様の確認方法

質問	参照先
今のシステムは何ができるか？	Reverse Engineering成果物（正式版）
なぜこの機能を作ったか？	該当サイクルの requirements.md
どのような設計判断をしたか？	該当サイクルの design 成果物
過去の仕様状態は？	Git履歴

採用しなかった選択肢

選択肢	不採用の理由
Spec-first	実装後に仕様が廃棄され長期運用に不向き
Spec-as-source	現時点でコード全自動生成は非現実的
機能別に仕様書を分割し統合管理	小規模プロジェクトには過剰
仕様の差分更新	全再生成の方がシンプルで乖離リスクがない

まとめ

AI-DLCは開発ワークフローとしては優秀ですが、「正式な仕様の定義」は各プロジェクトで明示的に決める必要があります。SDDの3段階分類は判断に役立つフレームワークになります。

本プロジェクトでは、AI-DLCの「Always rerun」ルールを活かし、Reverse Engineeringを実行してその成果物を正式版（spec-anchored）、Requirements/Designを履歴とする方針に落ち着きました。シンプルですが、根拠のある判断ができたと思います。

AI-DLC等で仕様駆動開発を進めている方は、早い段階で「正式な仕様はどこか」を決めておくことをおすすめします。

この記事のまとめイラスト

参考リンク

• AI-Driven Development Life Cycle (AWS DevOps Blog)
• Understanding Spec-Driven-Development (Birgitta Böckeler, martinfowler.com)
• Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants (arXiv)
• Evolving specs - GitHub spec-kit Discussion #152
• How AI-DLC differs from SDD (Derick Chen, LinkedIn)

針生 泰有(執筆記事の一覧)

サーバーワークスで生成AIの活用推進を担当