AI時代の設計書考察｜従来ドキュメントが機能しなくなった理由と新しい形

更新日：2025年12月13日

AIを活用した開発が当たり前になる中で、従来の設計書が形骸化している現象が各所で報告されている。設計書フォルダに大量のドキュメントが存在しながら、そのほとんどが実際のコードと一致しているか不明という状況は、もはや珍しくない。これはAI時代における設計書のあり方そのものを再考する必要があるのではないかと考え、調査・考察してみた。同じような課題を感じている方の参考になれば幸いである。

1. 従来の設計書が機能しない現実

AIを活用してシステム開発を進めると、設計書フォルダには様々なドキュメントが蓄積されていく。要件定義書、基本設計書、詳細設計書、機能仕様書といった従来型のドキュメントが次々と生成される。しかし、ある時点でこれらのドキュメントを見返すと、大半が「実際のコードと一致しているか不明」という状態になっていることに気づく。

1.1 AI開発における設計書の実態

従来のソフトウェア開発では、設計書作成、実装、設計書との整合性確認、というサイクルが想定されていた。ウォーターフォールモデルでもアジャイル開発でも、何らかの形で設計と実装の整合性を保つ仕組みが組み込まれていた。

しかしAIを活用した開発では、「これを作って」と依頼すると即座に実装が完了する。設計書を書く工程が存在しないか、あるいは実装後に「ドキュメントも作って」と依頼して形式的に作成されるだけになる。その結果、設計書は作成時点のスナップショットに過ぎず、その後の変更が反映されることはほとんどない。

典型的な状況
AI開発プロジェクトでは、設計書の約70%がコードとの一致が不明、約20%が作成時点のスナップショット、実際に参照されているものは約10%に過ぎないというケースが少なくない。

1.2 従来の開発サイクルとの乖離

Table 1に従来の開発とAI開発における設計書の位置づけの違いを示す。

観点 従来の開発 AI時代の開発
設計の記録 設計書が正式な記録 会話履歴が設計の記録
実装の指針 設計書に基づいて実装 会話中に仕様決定・即実装
更新タイミング 実装と同期して更新 更新されないことが多い
読者 開発チームメンバー 不明確

Table 1 従来の開発とAI開発における設計書の位置づけ

2. 設計書が形骸化するメカニズム

設計書が形骸化する原因は、AI開発のワークフローそのものに内在している。本章では、形骸化が発生するメカニズムを分析する。

2.1 AIは設計書を経由しない

最も根本的な原因は、AI開発において設計書が開発プロセスの中に位置づけられていないことである。従来の開発では、設計書は開発者間のコミュニケーションツールであり、実装の指針であった。しかしAI開発では、人間とAIの会話の中で仕様が決定され、即座に実装される。

従来の開発フロー
要件定義 → 基本設計書作成 → 詳細設計書作成 → 実装 → 設計書との整合性確認 → 設計書更新
AI時代の開発フロー
会話で要件伝達 → AIが即座に実装 → 動作確認 → 修正依頼 → 完了（設計書は作成されないか形式的）

会話履歴そのものが設計の記録となり、別途設計書を作成する必要性が薄れる。むしろ設計書を作成することは、同じ内容を二重に管理することになり、非効率とさえ言える。

2.2 更新する動機の欠如

仮に設計書を作成したとしても、変更のたびに更新する動機が存在しない。AIは明示的に依頼されない限り設計書を更新しないし、人間も目の前の機能が動いていれば設計書の更新は後回しにしがちである。特に問題なのは、小さな変更の積み重ねである。「ボタンの位置を変えて」「この条件を追加して」といった細かい修正は、いちいち設計書に反映されることはない。

2.3 読者の不在

設計書を書くとき、誰のために書いているのかという問いがある。自分のためか、AIのためか、それとも将来の他の開発者のためか。この問いに明確な答えがないまま、漫然と設計書を作成してしまうと、誰にとっても役に立たないドキュメントが生まれる。

設計書が形骸化する3つの原因

  • プロセスに組み込まれていない：AI開発では会話が設計の記録になり、設計書を経由しない
  • 更新の動機がない：動く実装があれば設計書は後回しになり、小さな変更は反映されない
  • 読者が不在：誰のために書いているか明確でなく、結果として誰も読まない

3. AI時代に必要なドキュメントの形

AI時代において、従来型の設計書の多くは不要になったと考えられる。詳細設計書はコードを見れば分かる。画面設計書は実際に動かせば見える。処理フロー図よりもコードそのものが真実を語る。これらを別途ドキュメント化することは、二重管理のコストを生むだけである。

3.1 不要になったドキュメント

AI時代において役割を終えたと考えられるドキュメントには、詳細設計書（コードが真実）、画面設計書（実装を見れば分かる）、処理フロー図（コードで確認可能）、データフロー図（コードが正確）などがある。これらはコードと二重管理になるだけでなく、乖離が発生すると誤った情報源となるリスクがある。

3.2 AI時代に必要な4つのドキュメント

一方で、AI時代だからこそ必要なドキュメントがある。それは「AIに渡すための前提情報」と「人間が実際に手を動かすときの手順」である。Table 2にAI時代に必要なドキュメントを示す。

ドキュメント 目的 内容例
CONTEXT.md AIに渡す前提情報 システム概要、制約、ファイル構成、注意点
HOWTO.md 運用手順 デプロイ手順、環境構築、定期作業
TROUBLESHOOT.md トラブル対応 エラー時の対処法、復旧手順、連絡先
SECRETS.md 認証情報の場所 APIキーの格納場所、接続情報（値は記載しない）

Table 2 AI時代に必要なドキュメント

3.3 CONTEXT.mdの重要性

特に重要なのがCONTEXT.mdである。これはAIに作業を依頼する際に最初に渡す前提情報をまとめたものである。システムの概要、ファイル構成、制約事項、注意点などを簡潔にまとめておくことで、AIとの会話がスムーズになる。

従来の設計書が「人間が人間に伝えるため」のものだったとすれば、CONTEXT.mdは「人間がAIに伝えるため」のものである。この視点の転換が、AI時代のドキュメンテーションの核心ではないかと考えている。

新しいドキュメント構成の例
設計フォルダには、CONTEXT.md、HOWTO.md、TROUBLESHOOT.md、SECRETS.md、実際に使うテンプレート、実際に使うツールだけを置く。それ以外の従来型設計書は削除するか、アーカイブとして分離する。

3.4 設計書の概念を変える

最終的に行き着いた結論は、「設計書を整理する」のではなく「設計書の概念を変える」必要があるということである。従来の設計書の大半を削除し、本当に使うものだけを残す。そして新しい形式のドキュメントを最小限に作成する。

これはドキュメントの量を減らすことが目的ではない。本当に機能するドキュメントだけを維持することで、ドキュメントの信頼性を高めることが目的である。形骸化したドキュメントの山は、ないよりも悪い場合すらある。誤った情報を参照してしまうリスクがあるからである。AI時代の開発において、ドキュメンテーションのあり方は根本的に変わる必要がある。

参考・免責事項
本記事は2025年12月13日時点の情報に基づいて作成されています。個人差があるため、効果を保証するものではありません。記事内容は個人的な考察に基づくものであり、専門的な判断については関連分野の専門家にご相談ください。重要な決定については、複数の情報源を参考にし、自己責任で行ってください。