Codexで出力したものです。
はじめに
この投稿見てやってみました。ここまでできるとは思いませんでした。感謝しかない。
システム開発では、何かを作る前に設計資料を作ることが多いと思います。
関係者の要望や意見を聞き、認識を合わせ、合意を取る。
そのための資料であれば、今でも Word、Excel、PDF、Google Docsなどのクラウド のような形式が使いやすい場面は多いです。
みなさんコメントを書き入れたり、修正指示を入れたりできますし、会議で説明するにも扱いやすいです。
つまり、合意形成のための設計書としては、従来型のドキュメントにはまだ十分な意味があると思っています。
一方で、ずっと考えているのが、実装が終わった後の設計資料です。
Markdownで書いた設計資料が、どうにも読みにくい
これまで私は、実装後の簡単な設計資料を Markdown で書くことがありました。
Gitで管理しやすいですし、差分も見やすい。
エンジニアにとって扱いやすい形式なのは間違いありません。
また、AIにMarkdown形式で設計資料を書いてもらうこともあります。
ただ、正直なところ、設計資料として読むには少しつらいと感じることがありました。
- 文章が縦に長くなりやすい
- 表や図を入れるのが面倒
- 関連する情報を行き来しにくい
- システム全体を俯瞰しにくい
- どこから読めばいいのか分かりにくい
Markdownは便利です。
ただ、システムの内部構造を理解するための資料としては、少し単調に感じることがあります。
特に、AIが生成したMarkdownの設計資料は、情報量は多いのに、人間が読むには少し重いと感じることがありました。
CodexにHTML一枚の設計資料を作らせてみた
そこで試しに、最近使っている Codex に、次のような依頼をしてみました。
このアプリの、アーキテクチャや構成を一覧できる資料を作ってください。
HTML一枚で、インタラクティブに確認できるものにしてください。
すると、思った以上に見やすい資料が出てきました。
HTML一枚なのに、画面として整理されていて、アプリの構成、主要な機能、データの流れ、画面やモジュールの関係が視覚的に確認できるようになっていました。
Markdownのように上から順番に読むだけではなく、必要なところを見に行けます。
「このシステムはどういう構成なのか」
「どこに何があるのか」
「全体像をざっくり把握したい」
そういう目的であれば、かなり実用的だと感じました。
もちろん、これだけで完全な詳細設計になるわけではありません。
より正確に確認したい場合は、最終的には実際のコードを見る必要があります。
ただ、コードを読む前の入口としては十分です。
設計資料は「合意用」と「理解用」に分けるとよさそう
設計資料は大きく2種類に分けて考えています。
1. 合意するための設計資料
これは、関係者と認識を合わせるための資料です。
まだ実装前なので、内容も固まりきっていません。
修正やコメントが入りやすく、会議で説明しやすい形式が向いています。
この用途では、Word、Excel、PDF、Google Docsなどのクラウド のような従来型の資料でよいと思っています。
2. 理解するための設計資料
これは、実装後にシステムの内部を把握するための資料です。
自分は実装前にあまり資料つくらなくなってます...
コードを読む前に、全体像をつかむための入口になります。
この用途であれば、必ずしもMarkdownにこだわる必要はないのかもしれません。
むしろ、AIにHTML一枚のインタラクティブな資料を作らせたほうが、人間にとって読みやすい場合があります。
実装後であれば、AIは実際のコードをもとに構成を整理できます。
手で頑張って設計書を更新し続けるよりも、現実のコードに近い資料を作りやすい可能性があります。
まとめ
これまで設計書というと、Word、Excel、Markdown、Google Docsのどれで書くか、という発想になりがちでした。
しかし、AIがコードを読み取り、HTML一枚の見やすい資料を作れるようになると、少し考え方が変わります。
- 合意形成のための資料は、人間同士が修正しやすい形で作る
- 実装後の理解用資料は、AIにコードから生成させる
- 必要に応じて、HTMLでインタラクティブに見られるようにする
この分け方をすると、設計資料の作成や保守がかなり楽になる気がしています。
特に、実装後の設計資料については、無理に長いMarkdownを書くよりも、AIに次のように頼むだけで、かなり実用的な資料が作れるかもしれません。
このアプリの、アーキテクチャや構成を一覧できる資料を作ってください。
HTML一枚で、インタラクティブに確認できるものにしてください。
設計資料を書くというより、
AIにシステムを読ませて、人間が理解しやすい形に変換してもらう。
今後は、こういうドキュメントの作り方どうでしょうか。
惜しいのは...AIなので毎回出力が安定していないって点です（笑）