仕様書 vs コード vs プロンプト：AI時代の開発ドキュメント戦略【Claude Code対応】¶
AI時代の開発では、仕様書・コード・プロンプトのどこに情報を置くかで品質が大きく変わる。本稿ではClaude Code/Cursor/Copilotを例に、リスクとフェーズごとに使い分ける実践フレームを提示し、仕様ドリフトを防ぐ具体策をまとめた。
関連ガイドと実装ハンドブック¶
- Claude Code自動許可ガイド（運用設計）
- Claude Codeインストール＆環境構築
- GitHub Copilot カスタムインストラクション実践
- Codex CLI 承認モードの安全な使い分け
- MCPコード実行エージェントの設計パターン
- スクラム×AIコーディングの仕様管理実践ガイド
この記事でわかること
AI時代における仕様管理の3つのアプローチ（仕様ドキュメント・コード中心・プロンプト駆動） リスク・フェーズ・レイヤに応じたハイブリッド運用の指針 Interface / Contract層を活用した仕様ドリフト防止策
目次¶
Note
目次の各リンクは、見出し記法の揺れでアンカーが生成されないケースがあったため、いったんプレーンテキストにしています（見出し整理後、リンク復活予定）。
この記事のポイント¶
先に結論を述べる。どれか1つのアプローチに全振りするのはリスクが高い。現実的には、以下のハイブリッド運用が妥当である。
- 高リスク・長期保守領域 → 仕様ドキュメントを厚めに（A寄り）
- 内部モジュール・開発速度重視領域 → コード＝仕様をベースに（B寄り）
- 探索・スパイク → プロンプト駆動でフル活用し、残すと決めたものだけA/Bに引き上げる（C寄り）
そのうえで、Interface / Contract層（OpenAPI、Protobuf、GraphQL、型定義など）を「仕様・コード・AIの三者が合流する共通レイヤ」として設計しておくと、仕様ドリフトや責任の所在をコントロールしやすくなる。
ハイブリッド運用のポイント
Interface層を「仕様・コード・AIの共通言語」として設計することで、どのアプローチを採用しても検証可能な契約を維持できる。
3つのアプローチの全体像¶
アプローチA：仕様ドキュメント回帰派¶
立場：AIが実装者になるからこそ、仕様をきちんと文字に残さないと危ない。
背景にある前提は以下の通り。
- 人間の開発者は、チームの暗黙知や過去の経緯を「空気で補完」できた
- AIはセッションごとにリセットされるため、明示されていない前提を汲み取れない
- 結果として、仕様を明文化しないと、AIが毎回「ベストプラクティス風に」独自解釈してしまう
この立場が強い領域は、金融・医療・公共などの規制産業、大企業の基幹系・ミッションクリティカルシステム、複数ベンダー・オフショア・長期保守が前提のシステムである。
What（ビジネス要件）をしっかり文章で残し、場合によってはHow（設計方針）まで仕様書に含める。「動くコードがあるだけでは説明責任を果たせない」という世界観である。
アプローチB：コード＝仕様派（Living Documentation）¶
立場：仕様書とコードを二重管理するのは無駄。コードとテストこそが仕様である。
この考え方はAI以前から存在し、以下の動きと相性が良い。
- BDDのGherkinシナリオ（テスト＝仕様）
- OpenAPI / GraphQL / Protobuf などのスキーマ駆動設計
- TypeScript / Rust / Go など、型システムの強い言語による「型＝契約」志向
AI時代になると、これがさらに加速する。コードを書いたらAIにREADME / ADR / APIドキュメントを自動生成させ、仕様のソース・オブ・トゥルースはコードに一元化する方向である。
この立場が強い領域は、スタートアップ・小規模チーム・プロダクト初期フェーズ、型の強い言語やスキーマツールを活用できる環境である。
アプローチC：プロンプト＝仕様派（Prompt-Driven Development）¶
立場：AIへのプロンプト（指示文）が、そのまま仕様として機能するのではないか。
Claude Code / Cursor / Devin のようなエージェント型ツールでは、以下の流れになる。
- 自然言語でタスクを指示する
- AIが調査・設計・実装・テストまで一気通貫で行う
- プロンプトと対話ログを見れば、「なぜそう実装したか」がある程度追える
プロンプトが従来の仕様書の役割（What/制約の定義）をある程度代替する。
注意点
この「プロンプト＝仕様」という概念整理は、界隈で確立した用語というより、現象を捉えるための仮説的なフレームである。ツールチェーンも発展途上であり、現時点ではPoCやスパイク限定と割り切るのが現実的である。
本質的な違い：何をどこで固定するか¶
3つのアプローチは、「仕様書を書くかどうか」の違いではない。本質的には、どのレイヤの情報を、どの媒体で"固定"するかの違いである。
レイヤを3つに分ける。
| レイヤ | 内容 |
|---|---|
| What | 何を実現するのか（ビジネス要件、ユーザーストーリー、SLA、制約） |
| Interface / Contract | API / イベント / DB スキーマ / 型 といった「検証可能な契約」 |
| How | 内部設計、アーキテクチャパターン、実装詳細 |
各アプローチがどのレイヤをどう扱うかを整理すると以下の通り。
| レイヤ | A：仕様ドキュメント回帰 | B：コード＝仕様 | C：プロンプト＝仕様 |
|---|---|---|---|
| What | 仕様書で厚く書く | ユーザーストーリー＋テストケース | プロンプトと対話ログ |
| Interface | 仕様書＋スキーマで管理 | スキーマ（OpenAPI等）が主役 | 自動生成されたスキーマ/型 |
| How | 設計書 or サンプリングレビュー | コードとテストに内包 | AI の生成コードに内包 |
重要な点：どのアプローチも、最終的には「Interface / Contract層」を何らかの形で持つ。この層が、人間の仕様とコード、そしてAIのすべてをつなぐ中間言語として機能する。
各アプローチの強みと破綻ポイント¶
アプローチA：仕様ドキュメント回帰派¶
- 規制産業・公共・金融など、監査と説明責任が重いドメイン
- 複数社・複数チームが関わる大規模プロジェクト
- 長期保守・引き継ぎが前提のシステム
- スピード低下：仕様の合意・更新に時間がかかる
- 二重管理コスト：仕様と実装が乖離し、どちらも信用できなくなる
- 誰も読まない問題：開発者はコードとテストを見てしまい、仕様書は監査用PDFと化す
AI時代の変化として、仕様ドラフトをAIに書かせられるため「ゼロから書く」コストは下がりつつある。一方で、「仕様を誰がレビューして責任を持つか」はむしろ重くなる。
アプローチB：コード＝仕様派（Living Documentation）¶
- スタートアップ・小規模チーム・プロダクト初期フェーズ
- TypeScript / Rust / Go / Kotlin など型の強い言語
- OpenAPI / GraphQL / Protobuf / Prisma などスキーマツールとの組み合わせ
- ビジネス側への説明不足：「仕様はコードです」と言っても通じない
- 外部連携・契約上の根拠不足：「GitHubを読んでください」では契約書に載せられない
- 長期保守時の意図喪失：「なぜこの仕様になっているのか」の背景はコードから復元が難しい
AI時代の変化として、コードからREADME / ADR / APIドキュメントを自動生成する動きで、Bはさらに強くなっている。
アプローチC：プロンプト＝仕様派（Prompt-Driven Development）¶
- PoC / 実験 / スパイクタスク
- まだ要件が固まっていない探索フェーズ
- 1〜2人の個人開発に近い状況
- プロンプト履歴の分散：どの対話が「最終仕様」なのか分からなくなる
- トレーサビリティの欠如：「誰がどのプロンプトで何を生成したか」を後から追えない
- 責任の所在が不明瞭：プロンプトを書いた人・AI・レビューした人のどこに責任があるのか曖昧
現時点での限界として、プロンプトと生成物を一体でバージョン管理し、チームレベルで追跡するツールチェーンはまだ発展途上である。
使い分けの指針：リスク × フェーズ × レイヤ¶
1つのアプローチに全振りするのは危険である。リスク・フェーズ・レイヤの3軸で「どこにA/B/Cを厚く張るか」を決める。
軸の定義¶
| 軸 | 区分 |
|---|---|
| リスク | High（法的・大口顧客・金銭大）/ Mid（中口顧客・影響中）/ Low（内部ツール・PoC） |
| フェーズ | PoC・スパイク / β・成長 / 本番安定運用 / 長期保守 |
| レイヤ | What / Interface / How |
指針マトリクス¶
| 条件 | 推奨アプローチ |
|---|---|
| High × 本番・長期保守 × What・Interface | A＋B：仕様ドキュメント必須＋スキーマ連動 |
| Mid × 成長フェーズ × Interface・How | B中心：コード＝仕様、スキーマ駆動、最低限のADR |
| Low × PoC × 全レイヤ | C中心：プロンプト駆動で速度優先、残すなら後でA/Bに引き上げ |
大事なのは、「どのマスにどのアプローチを採用するか」をチームで一度言語化しておくことである。
例として以下のようなポリシーを設定する。
- 「金融系の本番APIのWhat/InterfaceはA/Bを採る」
- 「管理画面の内部UIはBだけで行く」
- 「プロトタイプはCで作り、残すと決めたものだけA/B側に引き上げる」
このレベルのポリシーがあるだけで、「なぜここは仕様を厚く書くのか／書かないのか」の説明がしやすくなる。
チェックポイント：自分たちのチームはどこにいるか¶
A/B/Cのどこに寄せるべきかを考えるための簡易チェックポイント。
質問1：一番怖いリスクは何か？
- 監査／訴訟／契約違反 → A寄り
- スピード低下／市場機会の喪失 → B/C寄り
- チーム生産性／バーンアウト → B寄り
質問2：今一番詰まっているのはどこか？
- PRレビューが詰まっている → Interface層を見直す余地
- 「何を作るか」から迷っている → A or Cで仕様の起点を明確に
- 「何が仕様か分からない」 → B寄りの逆生成アプローチを検討
質問3：プロダクトのフェーズはどこか？
- まだ顧客に触らせていない → C多めでよい
- 売上が立ち、顧客が付いている → A/Bの比率を上げるべき
- 5年以上保守する前提のコアシステム → A/Interface層への投資はほぼ必須
まとめ¶
3つのアプローチは互いに排他的ではない。
- Aだけに振り切ると、現場は重くなりすぎて動けなくなる
- Bだけに振り切ると、外向きの説明・長期保守・組織間調整で詰まる
- Cだけに振り切ると、再現性と責任の所在が曖昧になり、本番では危険
現実的な戦略は、リスク・フェーズ・レイヤに応じたハイブリッド運用である。
そのうえで、Interface / Contract層を「仕様（A）・コード（B）・AI（C）が合流する共通レイヤ」として設計しておくことで、仕様ドリフトや責任の所在をコントロールしやすくなる。
1本の「正解アプローチ」を探すよりも、自分たちのプロダクト・組織・リスクに合わせて「どこにA/B/Cを割り当てるか」を決めるフレームとして、この整理が使えれば十分である。
次のステップ
- チーム内で「どのマスにどのアプローチを採用するか」のポリシーを一度言語化する
- Interface / Contract層（OpenAPI、型定義、スキーマなど）を設計し、仕様ドリフトを防ぐ
- 定期的に仕様管理のアプローチを見直し、リスクとフェーズに応じて調整する