概要

システムの仕様をドキュメントに書き出したい時にどういった構成であるべきか考えることが偶にある。

自分的システム仕様書の構成を記す。

新しいプロジェクトの設計フェーズはもちろん、既存システムの仕様理解のためにもなる構成になっているはず。

構成

ほぼほぼファイル名通りであまり解説が必要ないのだが、特記事項だけ書き出しておく。

01_overview.md

全体概要では、仕様書の目的や概論を記述する。

• 何についての仕様書なのか
• 想定読者
• 目的/目的外
• 記事の運用方針（利用目的、更新頻度等）

02_system_architecture.md

C4 Modelをmermaidで書き残すのが個人的には好きなのだが、mermaidだとメンテナンスが難しい場合もあるので、良く考える。

最近はAIが結構頑張ってくれるので、可能な限りコード化して残せると良い。

03_data_model.md

データモデルでは、システムの抽象具象のデータ設計を記述する。

データベースであれば、概念・物理設計を記載する。

モデルの設計もあると良い。

04_web_endpoint.md

画面を返すエンドポイントについて一覧を記載する。

以下は例。

認証・認可などは該当するWebエンドポイントの関心事、システムのコンテキストなどに応じて適当に見繕う。

05_api.md

APIのエンドポイントについて一覧を記載する。

以下は例。

06_technical_detail.md

技術的な詳細について書く。

このセクションは、当該システムにおける重要な点について深堀って書く。

一番重要なセクションであり、一番手間のかかるセクション。

07_usecase.md

ユースケースの一覧について書く。

以下は複数システムを想定した例。

08_sequence.md

ユースケース一覧に応じてシーケンスを書く。

09_references.md

関連資料についてのセクション。

所感

ドキュメントが最初から整備されているならともかく、自分の理解のためにこうしたフォーマットで書くことができると、メンタルモデルを形成しやすかったり、他者と認識を揃えやすかったりする。

ケースバイケースだが、メンテナンスするのが大変なときは、ドキュメントの書き方の問題ではなくシステムの複雑性による問題だったり、といったことに気づくきっかけにもなる。