そういえば、「基本設計」は何処にいったのだろうか？と問い直してみるのだけど、拙著の場合は「基本設計」は、「概要設計」「構造設計」を示します。この手の文書の対応は、PMBOK でもそうなのですが多少揺れています。
- 概要設計と詳細設計
- 基本設計と詳細設計
- 外部設計と内部設計
要は、全体を見通したときの設計（概要設計や基本設計）と、プログラムコードに即した設計書（詳細設計や内部設計）に分けるということです。近年ではVue.jsなどを使いいきなりコーディングをすることも可能なので、詳細設計や内部設計は省略する傾向にあります。私もそれで十分だと思います。ですが、全体的な設計（概要設計、構造設計、ネットワーク設計、システム構造設計など）を省略してしまうと多人数でのプロジェクトでの意思統一が混沌となってしまったり、プロジェクト終了後の運用段階に入ったときに復旧や改修などに手間が掛かることが多いのです。その区切りとしても、概要設計は残し、詳細設計は捨てる、という線引きが重要になります。ひとりプロジェクトだとしても、構造設計なんかもざっと数ページでもよいので書いておくとベターですね。先の概要設計も、多少箇条書きにしてもでも残しておくと数年後に役に立ちます。
構造設計書を書く
構造設計書の目次はこんな感じです。
概要設計書がシステムの具体的な動きを記述するものに対して、構造設計書ではシステムの物理的な配置を記述しておきます。いわば、ネットワークの状態やデータベースの配置、システム内で利用するフレームワークやライブラリの配置です。
ネットワーク図というと今ではAWSの構成図とかを書くことが多いのですが、かつては各種ハードウェアの接続状態を示すものです。このあたり、
- 各種の機能に関して、箇条書きをしておく。
- 箇条書きから、ネットワーク図を書いて貰う。
という手順を使います。要件定義書を要約して箇条書きにしたように、概要設計を要約して箇条書きしたものをつかってもよいでしょう。少なくとも「いくつかのコンポーネントが繋がっている」ということが箇条書きで解るようにしておきます。
ChatGPTで、以下のような機能別の解説を付けて貰います。
これをもとにして、「mermaid形式でネットワーク図を書いて。」と ChatGPTに頼むと、下記のようなネットワーク図を書いてくれます。
mermaid 形式（ Mermaid | Diagramming and charting tool https://mermaid.js.org/ ）は、markdown の中にコードとしてフローチャートなどを入れ込む書式です。最初はUML一般だったのですが、だんだんと拡張されて上記のようなネットワーク図っぽいもの（実際は状態遷移図と思われる）も書くことができます。うまく工夫すると AWS のコンポーネントの組み合わせも書けるらしいので、試してみるとよいです。
基本、ChatGPT は「図」というものが書けません。レスポンスでも各種のツールを使ってください、と返してきます。ただし、この mermaid 形式だけは別で、結構な確率で中身を解釈してくれます。
のようなプロンプトを喰わせると、
このように mermaid 形式で書けるコードを返してくれます。これを、vscode の拡張機能などを使い図にします。
これをそのまま貼り付けてもよいし、文言を手直してしてもよいでしょう。
ハードウェア構成のほうは、うまくいかないのでパワポを使って手作業をしています。
visio などの専用ツールを使えば綺麗に書けるのでしょうが、ひとりプロジェクトだったり、数名の小規模プロジェクトであればこれで十分です。修正をしやすくしておくことが肝心です。修正がしにくくなると、形骸化してすぐに古くなって仕様書/設計書の手直しができなくなってしまいます。
最近では、Microsoft 365のようにクラウド上に設計書をアップしておくとがあるでしょう。そのときに綺麗なフォーマットにこだわるよりも（Office 365のWordの崩れはかなり酷いですね。Googleのほうがきれいに出力されます）、まあ、「情報がきちんと残っている」ことが重要でしょう。
