仕様書と Design Document （設計書）の違い

仕様書とは、現在の最新を仕様を書いたもので、Design Document は、これから作る機能の「設計書」です。

注意して欲しいのは、Design Document は仕様書ではないと言うことです。

仕様書が最新の仕様をまとめたもので、Design Document は仕様書の差分（変更箇所）を書いたものというイメージです。

なぜ Design Document を書くのか

Design Document より前に、最新の仕様書が整っていることの方が重要だと個人的には考えています。そのシステムを利用する人向けのドキュメントや、新しく開発に参加する人がないとシステムがメンテナンスできないからです。

仕様書が整っておらず、Design Document だけがある状態だと、新しくジョインした人が、全ての Design Document を読む必要があり、システムが年を重ねていくごとに、読まなければならない Design Document の量が膨大になっていきます。

Design Document については、書いたほうがいい場合と、書かなくていい場合があります。

Design Document は、既存機能の修正や新しい機能の追加の際に記載し、既存の機能がどう修正されるのかを説明したり、設計のレビューをしたりするのに使われます。また、この機能をこの設計で実装した理由も書くと良いでしょう。

そのため、比較的大きな実装で慎重にレビューした方がいい場合や、事情が複雑な設計については Design Document を更新した方が良いと言えます。

設計レビューが必要のないレベルや、修正の規模が小さい場合は、Design Document を書かずに仕様書を更新するだけでも良いでしょう。

Design Document はコードを実装する前に書くことが多いです。あるいは、実現可能性のチェックなど最低限の検証用コードを書いてから書き始めます。この時点で完璧な Design Document を書くことは不可能なので、レビューして欲しい点が明確になっていれば、ざっくりでも大丈夫です

実装していくうちに Design Document の通りにいかないことがわかり、Design Document の修正が必要になることもあるし、レビューで指摘されて修正が必要になる場合もあります。

むしろ、実装とともに完成していくイメージで書きましょう。

Design Document に決まったフォーマットはないと僕は考えています。設計レビューで特に議論したい点や、経緯として残しておきたいことを書いてください。

いくつかの要素を例として挙げます。以下の中から必要なものをピックアップして記載すると良いです。

現状のシステム構成について（レビュワーへの現状の説明のため）
現状の問題点
今回実装するものの概要
今回は実装をしないものとその理由
新機能の構成図やシーケンス図
- 図を書くのは時間がかかるので説明に必要なければ書かない選択肢もある（近年は生成AIで簡単に作れる傾向にはあるが）
API 仕様の変更点
実装の選択肢と、それぞれのメリットやデメリット
どの実装方法を採用するのかと、その理由
- 設計を議論するにあたり、設計者自身が推す選択肢が無いと議論が進まない場合があります
実装の進め方（他チームとの議論や調整が必要な場合など）
リリースの手順（リリースの手順が複雑だったり、気をつけなければいけない点がある場合）
アラート監視の方法
セキュリティ面について
法的な観点
パフォーマンスについて（特にパフォーマンスに課題がありそうな場合）
未解決の課題
- 自分がわかっていないこと
- レビューでアイデアを求めたいこと
- 負荷増大などにより問題になる可能性があるが、今回の実装では無視すること　　など
レビューの議事録
修正が必要なドキュメントについて