第1章：従来の設計書が機能しない現実

設計書を整理して気づいたこと

先日、自分が運営しているブログシステムの設計書フォルダを整理する機会がありました。AIに依頼して様々な機能を追加してきた結果、設計書フォルダには128ファイル、11MBものドキュメントが蓄積されていました。

整理を始めてすぐに気づいたのは、これらのドキュメントの大半が「実際のコードと一致しているか不明」という状態だったことです。要件定義書、基本設計書、詳細設計書、機能仕様書といった従来型のドキュメントが存在していましたが、それらが現在のシステムの実態を反映しているかどうか、確認する術がありませんでした。

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

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

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

第2章：なぜ設計書は死ぬのか

AIは設計書を経由しない

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

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

更新する動機がない

仮に設計書を作成したとしても、変更のたびに更新する動機が存在しません。AIは明示的に依頼されない限り設計書を更新しませんし、人間も目の前の機能が動いていれば設計書の更新は後回しにしがちです。

特に問題なのは、小さな変更の積み重ねです。「ボタンの位置を変えて」「この条件を追加して」といった細かい修正は、いちいち設計書に反映されることはありません。そして気づいたときには、設計書と実装の間に大きな乖離が生じています。

読者が曖昧

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

個人開発において、自分以外の読者がいない設計書は、本当に必要なのか改めて考える必要があります。

第3章：AI時代に必要なドキュメントとは

不要になったもの

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

本当に必要なもの

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

CONTEXT.mdという考え方

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

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

設計書を整理するのではなく概念を変える

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

これはドキュメントの量を減らすことが目的ではありません。本当に機能するドキュメントだけを維持することで、ドキュメントの信頼性を高めることが目的です。死んだドキュメントの山は、ないよりも悪い場合すらあります。誤った情報を参照してしまうリスクがあるからです。

AI時代の開発において、ドキュメンテーションのあり方は根本的に変わる必要があります。この考察が、同じような課題に直面している方の一助となれば幸いです。