Codexで出力したものです。

はじめに

この投稿見てやってみました。ここまでできるとは思いませんでした。感謝しかない。

https://x.com/RoundtableSpace/status/2054943567760539879

システム開発では、何かを作る前に設計資料を作ることが多いと思います。

関係者の要望や意見を聞き、認識を合わせ、合意を取る。
そのための資料であれば、今でも Word、Excel、PDF、Google Docsなどのクラウドのような形式が使いやすい場面は多いです。

みなさんコメントを書き入れたり、修正指示を入れたりできますし、会議で説明するにも扱いやすいです。

つまり、合意形成のための設計書としては、従来型のドキュメントにはまだ十分な意味があると思っています。

一方で、ずっと考えているのが、実装が終わった後の設計資料です。

Markdownで書いた設計資料が、どうにも読みにくい

これまで私は、実装後の簡単な設計資料を Markdown で書くことがありました。

Gitで管理しやすいですし、差分も見やすい。
エンジニアにとって扱いやすい形式なのは間違いありません。

また、AIにMarkdown形式で設計資料を書いてもらうこともあります。

ただ、正直なところ、設計資料として読むには少しつらいと感じることがありました。

Markdownは便利です。
ただ、システムの内部構造を理解するための資料としては、少し単調に感じることがあります。

特に、AIが生成したMarkdownの設計資料は、情報量は多いのに、人間が読むには少し重いと感じることがありました。

そこで試しに、最近使っている Codex に、次のような依頼をしてみました。

このアプリの、アーキテクチャや構成を一覧できる資料を作ってください。
HTML一枚で、インタラクティブに確認できるものにしてください。

すると、思った以上に見やすい資料が出てきました。

HTML一枚なのに、画面として整理されていて、アプリの構成、主要な機能、データの流れ、画面やモジュールの関係が視覚的に確認できるようになっていました。

Markdownのように上から順番に読むだけではなく、必要なところを見に行けます。

「このシステムはどういう構成なのか」
「どこに何があるのか」
「全体像をざっくり把握したい」

そういう目的であれば、かなり実用的だと感じました。

もちろん、これだけで完全な詳細設計になるわけではありません。
より正確に確認したい場合は、最終的には実際のコードを見る必要があります。

ただ、コードを読む前の入口としては十分です。

設計資料は大きく2種類に分けて考えています。

これは、関係者と認識を合わせるための資料です。

まだ実装前なので、内容も固まりきっていません。
修正やコメントが入りやすく、会議で説明しやすい形式が向いています。

この用途では、Word、Excel、PDF、Google Docsなどのクラウドのような従来型の資料でよいと思っています。

これは、実装後にシステムの内部を把握するための資料です。

自分は実装前にあまり資料つくらなくなってます...

コードを読む前に、全体像をつかむための入口になります。

この用途であれば、必ずしもMarkdownにこだわる必要はないのかもしれません。
むしろ、AIにHTML一枚のインタラクティブな資料を作らせたほうが、人間にとって読みやすい場合があります。

実装後であれば、AIは実際のコードをもとに構成を整理できます。

手で頑張って設計書を更新し続けるよりも、現実のコードに近い資料を作りやすい可能性があります。

これまで設計書というと、Word、Excel、Markdown、Google Docsのどれで書くか、という発想になりがちでした。

しかし、AIがコードを読み取り、HTML一枚の見やすい資料を作れるようになると、少し考え方が変わります。

この分け方をすると、設計資料の作成や保守がかなり楽になる気がしています。

特に、実装後の設計資料については、無理に長いMarkdownを書くよりも、AIに次のように頼むだけで、かなり実用的な資料が作れるかもしれません。

このアプリの、アーキテクチャや構成を一覧できる資料を作ってください。
HTML一枚で、インタラクティブに確認できるものにしてください。

設計資料を書くというより、

AIにシステムを読ませて、人間が理解しやすい形に変換してもらう。

今後は、こういうドキュメントの作り方どうでしょうか。

惜しいのは...AIなので毎回出力が安定していないって点です（笑）