markdown 設計書を作ってみた。AI 時代、設計書はもう契約書じゃない
はい、どうもこんにちは、佐藤です！
最近、AI 時代の設計書について考えることが多くなってきました。
AI で高速に作れる時代になりましたよね。そうなると、どうしても気になってきます。設計書って、なんの意味があるんだろう？
考えた末に作ったのが、いま実際に使っている基本設計書のテンプレートです。
ai-md-design-document-template（GitHub）
結論から言うと……。
設計書に書くのは、ドメイン同士の関係と振る舞いだけ。
あとはソースからリバースするか、その都度 AI に作らせれば十分機能します。
今回は、この設計書の哲学について語っていきますね！
設計書は、もう契約書として効いていない
まずは、設計書が何のためにあったのかという話から。
SIer 業界にいた方なら分かると思いますが、設計書は契約書でした。
- 設計書に書いたことは、実装しないとならない
- 設計書に書いていないことは、実装してはいけない
この 2 つが大前提です。窮屈に見えますよね？
でも、これは自分たちを守る盾でもありました。顧客から「これもやってほしい」と言われたら、こう返せたのです。
「設計書に書いていないことはできません。追加するなら、コストと期日をいただきます」
範囲が決まっているから、完成に責任を持てる。範囲の外は、追加の見積もりで受ける。請負の開発は、この交渉で成り立っていました。
一通り作った後に、要件が増えていく
では、最近のシステム開発はどうでしょうか？
一通り作り終わったあとに、「これも必要」「あれも必要」と要件が増えていきます。設計書を盾にして交渉するより先に、作りながら決めていく。そんな案件、心当たりがありませんか？
原因は、システムが複雑になりすぎて、基本設計で決めきれないことが多いからなのでしょうね。
画面の動き、外部サービスとの連携、権限の組み合わせ。触ってみて初めて「ここは違う」と分かることが、どうしても残ります。基本設計の段階で全部を言い当てるのは、もう無理なのです。
後輩くんと「それずるいよねー」って何回言ったことか、でも運用回らないならやらないとならないしで……。 もう、地獄っす。
決めきれないなら、作り込まなくていい
設計書が契約書として効かないなら、何が残るでしょうか。
残るのは、メンテの工数だけです。
要件が変わるたびに、設計書を直す。コードを直して、また設計書に合わせる。決めきれない設計書を細部まで作り込むほど、直す場所が増えていきます。
だったら、そんなに作り込まなくても良いよね、という話になってきますよね。
契約の側から見た話は、AI 時代、請負開発は限界に来ているのではないだろうか で書きました。今回は、作る側から見た設計書の話です。
API 仕様書も DB 設計書も、コードから出てくる
では、製造の視点からはどうでしょうか？ 作る側にとって、本当に必要な設計書は何なのか。
一つずつ見ていきます。
- API 仕様書 … OpenAPI でソースコードにコメントを書いてしまえば、それが API 仕様書になる
- DB 設計書 … A5:SQL Mk-2 でテーブルとカラムに適切にコメントを書いておけば、データベースから DB 設計書がそのまま出力できる
- 画面設計書 … 設計書を作る前に、画面ができている……
画面設計書は、ちょっと笑ってしまいますよね。AI に頼めば、動くモックがすぐに出てきます。紙の上で画面を描いているあいだに、本物の画面ができてしまうのです。
「お前はもう、できている」ってケンシロウになってしまいますわ！
つまり、この 3 つはコードが正になりました。コードから出せるものを、わざわざ別に書いて二重に持つ理由はありません。
残るのは、ドメイン同士の関係と振る舞い
では、必要なものは何か。
このブログで散々言ってきたところです。ドメイン同士の関係と振る舞い。ここが分かれば、作ることができます。
ドメイン駆動開発の革新は、アグリゲートだったのではないか や AIコーディング時代だからこそ、BEAM分析と状態遷移図が大活躍する で書いてきたことを、そのまま設計書の形にしたのが今回のテンプレートです。
テンプレートは、ドメイン駆動設計を前提にしています。置いてあるのは次の 5 種類だけ。
| テンプレート | 書くこと |
|---|---|
| アグリゲート | 不変条件、エンティティとルート、属性、状態、イベント、状態遷移図 |
| ユースケース | 入力と出力、使うアグリゲート、例外 |
| 帳票 | 出力条件と帳票項目 |
| 決定記録（ADR） | なぜそう決めたか、選ばなかった案 |
| 汎用 | 何を作るか、なぜ必要か、影響範囲 |
画面設計書、API 仕様書、DB 設計書のテンプレートはありません。 コードから出てくるので、置いていないのです。
中心はアグリゲート
いちばん厚いのは、アグリゲートのテンプレートです。
- 不変条件 … このアグリゲートの中で常に成り立つこと
- 状態とイベント … 何が起きると、どの状態に変わるか
- 状態遷移図 … 上の 2 つを mermaid の図にしたもの
1 ファイルに 1 アグリゲートにしています。不変条件は複数のエンティティにまたがるので、エンティティ単位に分けると書く場所がなくなるからです。
ユースケースのほうは、難しいロジックがあるときだけ書くルールにしました。そのかわり、使うアグリゲートを「読むだけか、書き換えるか」まで必ず埋めます。ここを見れば、影響範囲が読めるようにするためです。
なぜそう決めたのかは、決定記録に残します。このあたりは AI に一括修正を任せて事故った。だから ADR を書く で書いた話ですね。
それ以外は、リバースか都度作成で足りる
関係と振る舞いさえ押さえておけば、あとは困りません。
- 詳細が知りたければ、ソースからリバースする
- 説明資料が必要になったら、その都度 AI に作らせる
これで十分機能します。
設計書を守り続けるより、都度作るほうが現実的
最後に、メンテ性の話です。
AI があるので、メンテそのものには苦労しなくなりました。コードを直すのも、設計書を直すのも、頼めばやってくれます。
でも、メンテしたものを人間が読む負担は計り知れません。
AI が直したコードと、AI が直した設計書。「両方が合っているか確認して」と言われたら……大変ではないでしょうか？
しかも、設計書にはテストコードを書けません。
コードなら、テストが通れば動いていると言えます。でも設計書が正しいかどうかは、誰かが読んで確かめるしかない。結果、最終レビューに回ってくる設計書の品質は苦しく、レビューする側が苦労することになります。
というか、AI で都度都度資料が作れるのです。設計書として用意しておく必要が、なくなってきているのですよ。
実際に使ってみて：リバースでも穴が見つけやすい
このテンプレートを実際に使ってみて、良かったところがあります。
リバースで作っても、穴が見つけやすいのです。
未決の欄はそういう意味でも作っています。
既存のコードから AI に設計書を起こさせても、埋まらない欄が浮かび上がってきます。箱が先に決まっているから、足りないものが見えるわけです。
顧客折衝は、まだ手探り
一方で、顧客との折衝にはまだ使っていません。
もともと、このテンプレートは開発者向けです。製造に入る前に、設計の中身を確認するためのものなので、顧客への説明に使うことは想定していません。
顧客とのやり取りをどうするかは、正直まだ手探りです。
ただ、ネットを見ると、モックで画面設計を調整している案件も出てきています。顧客とは動く画面で合意して、開発者は関係と振る舞いの設計書で作る。この分け方は、良いところを狙っているんじゃないかなと思っています。
まとめ
というわけで、markdown 設計書を作ってみたよ！って話でした！
あ。正確には、設計書に書くのは、コードから出てこないものだけって感じですねっ。
設計書は、もう契約書として効いていません。決めきれない要件を細部まで書き込むほど、メンテの重さだけが残ります。API も DB も画面もコードが正になった今、人間が持っておくべきなのは、ドメイン同士の関係と振る舞いです。
テンプレートは GitHub に置いてあります。ぜひみなさんも、自分の設計書から「コードから出せるもの」を引き算してみてください！