概要

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

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

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

構成

01_overview.md             # 全体概要
02_system_architecture.md  # システム構成
03_data_model.md           # データモデル（概念設計）
04_web_endpoint.md         # Webエンドポイント一覧
05_api.md                  # API仕様（主にREST等）
06_technical_detail.md     # 技術的詳細（ライブラリ、ミドルウェアなど）
07_usecase.md              # ユースケース
08_sequence.md             # シーケンス図・処理の流れ
09_references.md           # 参考資料

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

01_overview.md

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

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

02_system_architecture.md

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

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

03_data_model.md

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

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

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

04_web_endpoint.md

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

以下は例。

| 項目           | 値                                 |
| ------------ | --------------------------------- |
| **概要**       | このエンドポイントの簡単な説明。何を表示・操作するためのものか。  |
| **パス**       | `/your/path/here`                 |
| **HTTPメソッド** | `GET` / `POST` / `PUT` / `DELETE` |
| **コントローラー**  | `Your::Controller#action`         |
| **認証**       | `authenticate_user!` など           |
| **認可**       | `authorize YourPolicy` など         |

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

05_api.md

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

以下は例。

| API名       | エンドポイント                   | メソッド                  | 説明              |
| ---------- | ------------------------- | --------------------- | --------------- |
| API名称を記載   | `/api/v1/sample_endpoint` | GET/POST/PATCH/DELETE | このAPIの概要を記載     |
| データ取得API | `/api/v1/items`           | GET                   | アイテム一覧を取得する     |
| 検索API    | `/api/v1/items/search`    | POST                  | 条件に応じてアイテムを検索する |

06_technical_detail.md

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

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

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

07_usecase.md

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

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

|   システム   |  ユーザー  |       カテゴリ       |              ユースケース               |
| ------------ | ---------- | -------------------- | --------------------------------------- |
| example       | 管理者     | 管理者機能           | 一覧表示                          |

08_sequence.md

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

09_references.md

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

所感

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

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