システムの詳細設計の書き方｜処理設計で迷わない構成例

システムの詳細設計は「何を書くか」で迷いやすい

システムの詳細設計を書くときに、意外と迷うのが「結局、設計書に何を書けばいいのか」というところだと思います。

詳細設計といっても、システム構成を書くのか、業務フローを書くのか、DB設計を書くのか、画面仕様を書くのかで内容はかなり変わります。しかも現場によってフォーマットも違いますし、人によって書き方の癖もあります。

なので今回は、あくまで僕が普段書いているシステムの詳細設計の構成を紹介します。

細かい注意点や、もっと具体的な書き方については別の記事で紹介するつもりです。この記事では、まず「詳細設計書をどういう見出しで組み立てているか」というざっくりした構成に絞って書きます。

今回扱うのは「処理の詳細設計」

最初に前提をそろえておきます。

今回紹介するのは、システム構成図や業務フローではなく、画面ごとの処理を整理するための詳細設計です。

たとえば、ある登録画面にアクセスしたときに何を表示するのか、保存ボタンを押したらどんな処理をするのか、モーダルを開いたら何が起きるのか、といった部分です。

個人的には、詳細設計は「実装者が処理を迷わず組める状態にするための資料」だと考えています。

もちろん、設計書だけですべてを完璧に表現するのは難しいです。ただ、少なくとも画面上で起きる処理の流れや、データの取得元、表示先、クリック時の挙動は整理しておいた方が、実装もレビューもかなりやりやすくなると思います。

大前提：僕は画面単位で詳細設計書を書く

僕は基本的に、詳細設計書を画面単位で書いています。

もう少し具体的に言うと、「ページパス単位」で設計書を分けるイメージです。

たとえば、会社一覧画面、会社詳細画面、会社編集画面があるなら、それぞれ別の設計対象として整理します。

画面単位にしておくと、その画面に来たときの初期表示、入力項目、クリックイベントなどをひとまとまりで見られるので、実装者が読みやすいと感じています。

逆に、複数画面の処理をまとめて書きすぎると、「この処理はどの画面の話だっけ？」となりやすいです。僕も過去にそういう設計書を見て、読む側として少し苦労したことがあります。

僕が書いている詳細設計の基本構成

僕がシステムの詳細設計を書くときは、だいたい以下の構成にしています。

1. ページパス
2. ワイヤー
3. フォームの仕様
4. 初期画面の表示
5. クリックイベント

この構成にしている理由は、画面の場所、見た目、入力仕様、初期表示、ユーザー操作時の処理を順番に追えるからです。

特にWebシステムの場合、画面を開いて、入力して、ボタンを押す、という流れが多いので、この順番で書いておくと自然に読めると思います。

1. ページパス

まず最初に、その画面のページパスを書きます。

ここはシンプルに、その画面のURLパスを書くだけです。

例👇

slugやIDなど、画面によって変わる値がある場合は、僕は{company_code}のような形で書いています。

この書き方にしておくと、「ここは固定のパスではなく、会社コードによって変わる部分なんだな」と一目で分かります。

ページパスは地味ですが、設計書の入口としてけっこう大事です。どの画面について書いているのかが曖昧だと、その後の処理説明も全部読みにくくなってしまうからです。

2. ワイヤー

次にワイヤーを載せます。

僕の場合、ワイヤーはFigmaで引いているので、詳細設計書にはFigmaのリンクを書くことが多いです。

ここで大事なのは、設計書だけで画面の見た目を全部説明しようとしすぎないことです。

もちろん、テキストで補足する部分はあります。ただ、画面の配置や見た目はワイヤーを見た方が早いので、詳細設計書にはワイヤーへの導線を置いておくのが良いと考えています。

個人的には、ワイヤーと詳細設計は役割を分けた方がいいと思っています。

ワイヤーは「見た目や配置を確認するもの」、詳細設計は「その画面でどんな処理をするかを確認するもの」というイメージです。

3. フォームの仕様

その画面に入力フォームが含まれている場合は、フォームの仕様を書きます。

フォームの仕様は、テーブル形式で整理することが多いです。

例👇

僕がよく書いている列は、以下です。

• 項目名
• キー
• 必須
• 選択肢
• 初期表示
• 備考

キーには、その項目が対応するカラム名やリクエストパラメータ名を書きます。

プルダウンやラジオボタンのように選択肢がある項目は、選択肢も書いておきます。編集画面の場合は、初期表示として何が入っているのかも書きます。

フォームは実装時に認識違いが起きやすい部分なので、画面上の項目名とデータ上のキーを対応させることを意識しています。

ここが曖昧だと、画面には「会社名」と出ているけど、APIではどのキーで送ればいいのか分からない、という状態になりやすいです。

4. 初期画面の表示

次に、その画面に来たときにどんな処理をするかを書きます。

初期画面の表示では、DBからデータを取得する処理がメインになることが多いです。

たとえば詳細画面なら、URLに含まれるcompany_codeを使って会社情報を取得し、その結果を画面に表示します。

このとき僕は、「何を取得するか」と「どこに表示するか」を分けて整理します。

例👇

個人的には、初期表示の設計では取得処理だけで終わらせないことが大事だと思っています。

「DBから会社情報を取得する」とだけ書いてある設計書もありますが、それだと取得したデータを画面のどこにどう表示するのかが分かりません。

実装する側からすると、取得するデータだけでなく、表示先まで書いてある方がかなり助かります。

特に一覧テーブル、詳細エリア、フォームの初期値などが混ざる画面では、表示先を明確にしておいた方が認識ズレを防ぎやすいです。

5. クリックイベント

最後に、クリックイベントを書きます。

クリックイベントでは、画面上のクリックできる箇所について、それをクリックしたらどんな処理をするのかを整理します。

主にボタンが対象になることが多いですが、テーブル内の操作ボタン、リンク、モーダルを開くアイコンなども対象になります。

クリックイベントは、詳細設計の中でもかなり重要な部分だと思います。

なぜなら、ユーザーの操作によってシステムがどう動くのかを具体的に書く場所だからです。

保存するのか、検索するのか、モーダルを表示するのか、別画面に遷移するのか、テーブルの行を追加するのか。こういう挙動を一つずつ整理しておくと、実装時の迷いが減ります。

僕は、画面上でクリックできるものは基本的に全部拾うようにしています。

特に、テーブル操作は抜けやすいです。行追加、行削除、並び替え、詳細表示など、ボタンとしては小さくても処理としては重要なものが多いので、忘れずに書くようにしています。

この構成で書くと、画面の処理が追いやすい

ここまでの内容をまとめると、僕が書いている詳細設計の構成は以下です。

この構成にしておくと、画面を開いたときの状態から、ユーザーが操作したときの処理までを順番に追えます。

詳細設計は、ただ細かく書けばいいわけではないと思っています。読む人が「この画面では何が起きるのか」を理解しやすい構成になっていることが大事です。

その意味で、僕は画面単位で、初期表示とイベントを分けて書くやり方が使いやすいと感じています。

今回紹介したのはあくまで僕のフォーマットです

ここまで、僕が普段使っているシステムの詳細設計の書き方を紹介しました。

もちろん、これが唯一の正解ではありません。プロジェクトの規模、チームのルール、使っている技術、開発体制によって、必要な項目は変わると思います。

ただ、画面単位で処理の詳細設計を書く場合は、今回の構成をベースにするとかなり整理しやすいです。

特に、以下のような人には使いやすい形だと思います。

• 詳細設計書に何を書けばいいか迷っている人
• 画面ごとの処理を整理したい人
• 実装者に伝わる設計書を書きたい人
• 初期表示やクリックイベントの書き漏れを減らしたい人

細かい書き方や、各項目で気をつけていることについては、別の記事で詳しく書こうと思います。

今回はまず、システムの詳細設計を書くときのざっくりした構成として、「ページパス、ワイヤー、フォームの仕様、初期画面の表示、クリックイベント」という流れを紹介しました。

個人的には、このくらいの粒度で整理しておくと、実装する側も確認する側も迷いにくくなると考えています。