この記事は、2026年6月時点での自分の考えを整理したものです。

世の中の開発手法や、設計書の作り方を否定したいわけではありません。
ウォーターフォール開発、アジャイル開発、受託開発、社内開発など、現場によって必要なドキュメントは違うと思っています。

あくまで、AIエージェントや生成AIを使いながら開発する中で、今の自分にはこう見えている、という話です。

はじめに

最近、AIにコードを読ませて設計資料を作ることを試しています。

きっかけとしては、Codexにアプリの構成を読ませて、HTML一枚の設計資料を作らせてみたことでした。

最初は、

AIで設計資料を作るのが楽になる

くらいに考えていました。

実際、かなり便利でした。

コードをもとに、アーキテクチャ、画面構成、データの流れ、主要な機能を整理してくれる。
Markdownで長々と書かれた資料よりも、HTML一枚で見られる資料の方が、全体像をつかみやすい場面もありました。

ただ、少し考えているうちに、これは単に「設計資料を楽に作れる」という話だけではない気がしてきました。

AIで実装後のコードから設計資料を作れるなら、そもそも今まで通りの詳細設計書は何のために必要なのか。

実装前に細かく書く設計書と、実装後にコードから作れる理解用資料は、同じものとして考えなくてよいのではないか。

そんなことを考えるようになりました。

この記事では、AI時代の設計書は、「詳細を書くもの」から「合意を残すもの」へ少しずつ役割が変わっていくのではないか という話を整理してみます。

設計書には、少なくとも2つの役割がある

これまで設計書というと、ひとまとめに「設計書」と呼んでいた気がします。

でも、最近は少し分けて考えた方がよいのではないかと思っています。

大きく分けると、設計書には少なくとも2つの役割があります。

1つは、合意するための設計書です。

もう1つは、理解するための設計書です。

この2つは似ていますが、目的が違います。

合意するための設計書は、これから何を作るのか、何を作らないのか、どこまでを今回の範囲にするのかを関係者で確認するためのものです。

一方で、理解するための設計書は、すでにあるシステムがどういう構成になっているのか、コードを読む前に全体像をつかむためのものです。

この2つを同じ形式、同じ粒度、同じ更新方法で扱おうとすると、少し無理が出るのではないかと思っています。

役割	主な目的	誰のためか	向いている形式
合意するための設計書	何を作るか、何を作らないかを決める	顧客、関係者、チーム	コメントしやすい文書、表、議事録、合意メモ
理解するための設計書	実装後の構造を把握する	開発者、保守担当、引き継ぎ担当	Markdown、HTML、図、コードから生成した資料

どちらも大事です。

ただ、役割が違うなら、作り方も違ってよいはずです。

合意するための設計書は、今でも必要だと思う

AIで設計資料を作れるようになっても、合意するための設計書はなくならないと思っています。

なぜなら、AIがコードから資料を作れるのは、基本的には「すでに何かがある」場合だからです。

でも、開発では実装前に決めなければいけないことがあります。

何を作るのか
何を作らないのか
誰が使うのか
どこまでを今回の範囲にするのか
どの仕様は後回しにするのか
どの制約を受け入れるのか
どこで顧客や関係者の確認を取るのか

こういうものは、コードから逆生成できません。

コードは、すでに決まった結果を表しています。
でも、なぜそう決めたのかまでは、コードだけでは分からないことが多いです。

たとえば、ある機能が実装されていないとします。

それが漏れなのか。
今回のスコープ外として合意したのか。
将来対応にしたのか。
コストの都合で削ったのか。
運用でカバーすることにしたのか。

これは、コードだけを見ても分かりません。

だから、合意の履歴は必要です。

自分が今後も残すべきだと思っているのは、すべての細かい処理を先に書き切る詳細設計書というより、関係者と何を合意したのかを後から追える資料です。

ここで言っている「合意を残す」というのは、単に承認印をもらうとか、設計書にサインをもらうという意味ではありません。

自分の中では、次のようなものを残すイメージです。

残すもの	なぜ残すのか
決めたこと	実装や判断の前提を後から確認するため
決めなかったこと	「未対応」なのか「意図的に保留」なのかを区別するため
スコープ外にしたこと	あとから「入っていると思っていた」を防ぐため
その理由	判断の背景をコードだけでは追えないため
誰と確認したか	合意した相手や責任範囲を明確にするため
いつ見直すか	保留事項を放置しないため
未決事項	次に確認すべき論点を残すため

特に大事なのは、「決めたこと」だけではなく、決めなかったことやスコープ外にしたことも残すことだと思っています。

あとから問題になるのは、実装の細部よりも、むしろ「これは今回やる話だったのか」「なぜこの仕様になったのか」「誰が確認したのか」が分からなくなる場面だったりします。

コードから実装内容を読み取ることは、AIによってかなり楽になっていくかもしれません。
でも、何を合意したのか、なぜそう判断したのかは、コードだけでは復元しにくいです。

理解するための設計書は、コードから逆生成できるようになってきた

一方で、実装後の理解用資料は、AIによってかなり作り方が変わる気がしています。

これまで、実装後の設計書を手で更新し続けるのは大変でした。

最初にきれいな設計書を書いても、実装が進むとコードが変わります。
仕様変更が入ります。
例外処理が増えます。
画面やデータの流れも変わります。

そして、気づくと設計書が古くなっている。

これはかなりよくある話だと思います。

でも、AIにコードを読ませて資料を作れるようになると、少し状況が変わります。

実装後のコードをもとに、

アプリの構成
主要な画面
モジュールの関係
データの流れ
APIやDBとの接続
処理の入口と出口
影響範囲の概要

のようなものを整理してもらえます。

これは、従来の意味での「先に書く設計書」とは逆です。

コードを書く前に設計書を作るのではなく、実装されたコードから理解用の設計資料を逆生成する。

この考え方は、AI時代にはかなり現実的になってきた気がします。

もちろん、AIが生成した資料をそのまま信じるのは危険です。
実際のコードと照らし合わせる必要がありますし、セキュリティや仕様判断の背景までは勝手に理解できません。

それでも、コードを読む前の入口としては十分に役に立ちます。

少なくとも、実装後の理解用資料を人間が全部手で書いて、ずっと保守し続けるよりは、AIにコードを読ませて作り直した方が現実に近い場面が増えそうです。

詳細設計書を先に全部書く意味は、少し変わってきたのかも

ここで考えたいのが、いわゆる詳細設計書の役割です。

もちろん、詳細設計書が必要な現場はあります。

規制が強いシステム。
大規模な受託開発。
外部委託が多い開発。
厳密なレビューや承認が必要な現場。
実装担当と設計担当が分かれている現場。

こういう場面では、詳細な設計書が必要になることもあると思います。

ただ、すべての開発で、今まで通りの詳細設計書を先に作る必要があるのかと言われると、少し疑問があります。

AIエージェントを使うと、実装の試行錯誤が速くなります。
プロトタイプも作りやすくなります。
修正も速くなります。
コードから資料を作ることもできます。

そうなると、実装前にすべてを細かく書き切るよりも、まず合意すべきことを明確にして、実装後の理解用資料はコードから生成する方が合っている場面も増えるのではないかと思います。

最初は、

AIで詳細設計書を楽に作れる

と思っていました。

でも、少し考えると、これは詳細設計書を効率化する話ではなく、従来の詳細設計書の役割を見直す話なのかもしれません。

AIで設計書を楽に書けるから、今までと同じ設計書を大量に作る。

それも一つの使い方です。

でも、自分としては、それよりも、

そもそも何のためにその設計書を書くのか

を見直した方がよい気がしています。

設計書は、詳細を書くものから合意を残すものへ

自分が今、一番しっくりきているのは、設計書を「詳細を書くもの」ではなく、合意を残すものとして見る考え方です。

もちろん、詳細が不要という意味ではありません。

ただ、実装の細かい部分は、最終的にはコードに表れます。
そして、実装後の理解用資料はAIでコードから作りやすくなってきています。

一方で、合意はコードだけでは残りません。

なぜこの仕様にしたのか
なぜこの機能を作らないことにしたのか
なぜこの画面遷移にしたのか
どの制約を受け入れたのか
どのリスクを許容したのか
誰と、いつ、何を確認したのか

こういう情報は、コードには残りにくいです。

でも、後からかなり重要になります。

仕様変更が起きたとき。
トラブルが起きたとき。
担当者が変わったとき。
「なぜこうなっているのか」を説明するとき。

必要になるのは、細かい処理の説明だけではなく、当時の判断の履歴です。

だから、AI時代の設計書では、実装の詳細をすべて書き切ることよりも、合意の履歴を残すことの重要性が上がるのではないかと思っています。

アジャイル開発でも、設計書は「未来の固定」より「合意の履歴」に近いのかも

これは、アジャイル開発にもつながる話だと思っています。

アジャイル開発では、最初からすべてを固定するのは難しいです。

作りながら分かることがあります。
ユーザーに見せて初めて分かることがあります。
優先順位が変わることもあります。
実装してみて、思っていたより難しいと気づくこともあります。

そのため、最初に詳細設計書を完璧に作って、それを最後まで守るという考え方は、現実に合わない場面があります。

ただし、だからといって何も残さなくてよいわけではありません。

むしろ、アジャイルだからこそ、何を合意したのかを残すことは重要だと思います。

今回は何を作るのか
何は作らないのか
どこまでできたら完了なのか
どの仕様は後で見直すのか
誰が何を確認したのか
どの判断をいつ変えたのか

こういうものが残っていないと、後から経緯が分からなくなります。

アジャイルにおける設計書は、未来を固定するためのものではなく、その時点での合意を残すためのものに近いのかもしれません。

そして、実装後の構造理解は、コードとAI生成資料に任せる。

このように分けると、アジャイル開発におけるドキュメントの考え方も少し整理しやすくなる気がします。

AI時代のドキュメントは、合意と理解をつなぐものになるのかも

AI時代のドキュメントは、人間だけが読むものではなくなっていく気がしています。

人間が合意したことを残す。
AIがコードを読むときの前提になる。
新しく参加した人がシステムを理解する入口になる。
レビューするときの判断材料になる。
過去の経緯を追うためのログになる。

そう考えると、ドキュメントは単なる納品物ではなく、合意と理解をつなぐコンテキストになっていくのかもしれません。

設計書も同じです。

今までのように、

設計書を書く
その通りに実装する
実装が変わったら設計書を保守する

という流れだけで考えると、AI時代には少しつらくなる気がします。

むしろ、

合意は人間が残す
実装はコードに残る
理解用資料はAIで生成する
判断の背景は合意履歴として残す

という分け方の方が、自分には自然に見えます。

つまり、設計書は一つの巨大な文書である必要はないのかもしれません。

合意メモ。
議事録。
仕様の決定履歴。
スコープの確認。
コードから生成した構成資料。
README。
画面一覧。
API一覧。
変更理由。

そういうものが組み合わさって、設計の文脈になる。

AI時代の設計書は、そういう形に近づいていくのではないかと思っています。

おわりに

AIにHTML一枚の設計資料を作らせてみたとき、最初は単純に便利だと思いました。

Markdownより見やすい。
コードの全体像をつかみやすい。
実装後の理解用資料としてかなり使えそう。

そんな感想でした。

でも、そこから少し考えると、設計書の役割そのものを見直す話につながってきました。

AIで実装後のコードから設計資料を逆生成できるなら、従来の詳細設計書をすべて先に作る必要は薄くなるのかもしれません。

もちろん、合意は必要です。
顧客や関係者と認識を合わせる資料は必要です。
何を作るのか、何を作らないのか、どこまでを今回の範囲にするのかは残すべきです。

ただ、それは実装の細部をすべて先に固定する詳細設計書というより、合意の履歴に近いものかもしれません。

実装後の理解用資料は、コードからAIに生成してもらう。
人間同士の判断や合意は、履歴として残す。

そう分けて考えると、設計書は「実装を縛るもの」ではなく、合意と理解をつなぐものとして見直せる気がしています。

まだ自分の中でも試行錯誤中です。

ただ、今の自分には、AI時代の設計書は、

詳細を書くものから、合意を残すものへ

少しずつ役割が変わっていくように見えています。