はじめに

株式会社アールピーシーの加藤です。
皆さんは「設計って何から始めればいいんだろう」「どういった順番で考えればいいんだろう」と悩んだことはないでしょうか。
本記事が、設計の進め方に悩んでいる方の一助になればと思い、私が普段意識している設計の進め方について紹介します。

私が設計で意識していること

成果物として画面設計書やAPI設計書が求められていると、ついそこから書き始めてしまうこともあるかと思います。

私自身、以前は
「画面設計書を作って」と言われれば画面設計書を、「API設計書を作って」と言われればAPI設計書を書き始めていました。

しかしこの進め方をしていると後になって

「この機能は別の画面でも使われるじゃないか」
「1つのAPIに処理を寄せすぎてしまった。責務を分けるべきだった」
「このデータはどこが管理するんだろう」
「外部システムとの連携を考慮できていなかった」

といった問題に気付き、設計を見直し、設計書を書き直す手戻りが何度もありました。

現在、私が設計で意識しているのが、
細部（設計書）から書き始めず、まずは全体像（設計図）を描くことです。
まずは設計対象の全体像を描き、システムを構成する要素や関係性を整理してから、画面設計書やAPI設計書といった細部へ落とし込む、という進め方です。

本記事では私がなぜこの順番で設計しているのか、実際にどのような図を描いているのかを紹介します。

本記事では全体像、細部を以下のように定義します。
全体像＝設計対象の構成要素や関係性、処理の流れを俯瞰するための図
細部　＝個々の仕様を定義する設計書

設計書から始めると手戻りしやすい理由

設計書から書き始めること自体は問題ではありません。
問題は全体像を把握しないまま個々の設計書から書き始めることです。

例えば、「ECサイトの商品検索画面の画面設計書を作成する」というタスクがあったとします。
画面設計書から書き始めようとすると、

何を表示するか
どこに配置するか
入力項目は何か
検索する際にどのAPIを呼び出すか

といった、その画面に必要なことを中心に考えます。
もちろん画面設計書を作るうえでは正しい考え方です。
しかし、その画面だけを見ていると、

同じAPIを利用する画面は他にないか
同じデータを利用する機能は他にないか
APIの責務は適切か
DBや外部システムまで含めたデータの流れは正しいか

といった、画面の外側にある関係性を見落としやすくなります。
例えば商品検索画面だけを想定して検索APIを設計した後で、別の画面からも同じAPIを利用することが分かれば、APIのリクエスト項目や処理範囲を見直す必要が出てくるかもしれません。

その結果、
設計書を書く → 問題が見つかる → 設計を見直す → 設計書を書き直す
という手戻りが発生します。

これは設計力だけの問題ではなく、考える順番の問題でもあると私は考えています。

細部から考え始めると、どうしてもその細部を起点にシステムを見ることになります。
もちろん経験を積むことで頭の中で全体の関係性を整理できることもあります。
ただ関係する画面やAPI、データ、外部システムが増えるほど頭の中だけですべての関係性を把握することは難しくなります。

そのため私は、設計書を書く前に一度全体像を図として描き、
「どのような要素が登場するのか」「何と何が関係しているのか」
を整理してから細部の設計に入るようにしています。

設計は全体から細部へ

「木を見て森を見ず」ということわざがあります。
一本の木（細部）に目を向けるあまり、まわりの森（全体）が見えなくなっている状態を指します。
設計においても同様だと、私は考えています。

画面設計書から始めれば、その画面の仕様を中心に考えます。
API設計書から始めれば、そのAPIの仕様を中心に考えます。

しかし、「その画面がどの機能や画面とつながっているのか」「そのAPIを誰が利用するのか」といった周囲との関係は、個々の設計書だけでは見えにくくなります。
細部だけを見ていると、その設計単体では正しく見えても、システム全体として妥当なのか判断しづらくなります。

先に全体像を描く目的の一つは、頭の中にある情報を図として視覚化し、設計上の違和感に気付くことです。
図にして構成要素同士をつないでいくと、

必要な構成要素が抜けている
データの流れがおかしい
どこが責務を持つのか分からない

といった問題が見えてきます。
構成要素を線でつなごうとして迷うところは、まだ設計が十分に整理できていないところかもしれません。

私はこのような違和感を早い段階で見つけるために、設計対象の粒度に応じていくつかの図を使い分けています。

全体像は具体的に何を描くのか

私が主に描くのは以下です。
ただし、毎回すべてを描くわけではなく、設計対象や変更規模に応じて必要な図を選んでいます。

図	主に整理すること	範囲	ツール例
システム構成図	何があるのか	システム全体	Excel / PowerPoint / draw.io
画面＋API＋データ連携図	何と何がつながっているのか	アプリ・機能全体	Excel / PowerPoint / draw.io
シーケンス図	どのような順番で処理されるのか	機能単位	Excel / sequencediagram / mermaid

私は図を描きながら構成要素の配置や関係を頻繁に変更するため、使い慣れていて自由に配置できるExcelを使うことが多いです。

ここからは、外部SaaSを利用したログイン機能を例に、システム全体 → 構成要素の関係 → 処理の流れと、徐々に解像度を上げながらそれぞれの図を紹介します。

システム構成図

システム構成図では、サーバーやクラウドサービス、外部システムなどの構成要素と、それらの通信経路を整理します。まず、システム全体がどのような要素で構成されているのかを把握するために描いています。

どんな時に描くか

新規にシステムを構築するとき
サーバーやクラウドサービス、外部SaaSなど、システムを構成する要素を追加・変更するとき
システム間の通信経路を追加・変更するとき
ネットワークやインフラを含めて、構成変更の影響範囲を整理したいとき

描くときに何を気にしているか

システムを構成する主要な要素を描く
各構成要素がどこに配置されているのか分かるようにする
インターネット／VPC／サブネットなどの境界を描く
構成要素同士の通信経路を描く
「何があるか」だけではなく、必要に応じて各構成要素の用途や役割も記載する

画面＋API＋データ連携図

※「画面＋API＋データ連携図」は一般的な図の名称ではなく、本記事では便宜上このように呼んでいます。

画面遷移だけを描くのではなく、その画面が利用するAPIやデータまで一緒に描くようにしています。これにより、画面単体ではなく、機能を実現するために必要な構成要素をまとめて確認できます。
特に既存機能の改修では、対象画面だけを見るのではなく、その画面が利用するAPIやデータをたどることで、変更の影響範囲を整理する際にも役立ちます。

どんな時に描くか

複数の画面・API・データが関係する機能を追加・変更するとき
画面・API・データの変更による影響範囲を整理したいとき
既存の画面・API・データの関係を整理してから設計に入りたいとき

描くときに何を気にしているか

主要な画面遷移を描く
各画面が利用するAPIを描く
APIが利用するDB・サービス・外部システムを描く
画面・API・データの利用関係を確認し、変更時の影響範囲を把握する
メール・バッチ・認証など画面以外の処理も必要に応じて載せる

シーケンス図

システム構成図や画面＋API＋データ連携図で構成要素同士の関係を整理した後、必要に応じてシーケンス図で処理の順番を掘り下げます。

どんな時に描くか

複数の構成要素をまたぐ処理の流れを整理したいとき
処理の順番が重要な機能を設計するとき
データを「いつ／どこで生成・取得・保持・検証するのか」を整理したいとき
画面＋API＋データ連携図だけでは表現しきれない、機能内部の処理を掘り下げたいとき

描くときに何を気にしているか

誰を起点に処理が始まるのかを明確にする
画面・API・DB・外部システムなど、各構成要素間の呼び出し順を描く
処理で利用するデータを「いつ／どこで生成・取得・保持・検証するのか」を明確にする
- 例えば「保持しているIDを使って○○する」という処理がある場合、そのIDをいつ、どこで保持したのかまで追えるようにする
処理だけでは意図が伝わりにくい場合は、必要に応じて背景や理由をメモとして記載する
- 図を描いた本人には分かっていても、読む人が同じ前提知識を持っているとは限らない
正常系を中心に描き、必要に応じて主要な異常系は別の図に分ける

全体像を描くことのメリット

メリット	内容
抜け漏れに気付きやすい	構成要素とその関係を図にすることで、「この画面はどのAPIを使うのか」「このデータはどこから取得するのか」など、考慮できていない箇所に早い段階で気付きやすくなります。結果として、細部へ落とし込んだ後の手戻りを減らすことにつながります。
影響範囲を把握しやすい	画面、API、DB、外部システムなどの関係が見えるため、機能追加や変更を行った際に、どこまで影響するのかを追いやすくなります。
責務を整理しやすい	処理やデータの流れを俯瞰することで、「この処理はどこが担当するのか」「1つのAPIに責務が集中していないか」などを考えやすくなります。
レビューしやすい	個々の設計書を確認する前に全体像を共有することで、レビューする側も構成要素の関係やシステム全体への影響を把握しやすくなります。
認識を合わせやすい	図を使ってシステムや機能の関係を共有できるため、開発メンバーだけでなく、企画担当者や業務担当者とも認識を合わせやすくなります。

全体像を描くことのデメリット

デメリット	内容
作成する時間が必要	設計書へ落とし込む前に図を描くため、その分の作業時間が必要になります。ただし、後工程での手戻りを減らすための時間と考えることもできます。
メンテナンスが必要	システムや仕様が変更された場合、設計書だけでなく図も更新する必要があります。更新されないまま放置すると、実際のシステムとの差異が生まれます。
詳細に描きすぎると管理が大変	処理単位まで細かく図にすると変更のたびに修正が必要になります。そのため、全体像では「何があり、何とつながっているか」を中心に描き、詳細は設計書に任せることが重要です。
小さな改修では過剰になることがある	影響範囲が限定された小規模な改修でも毎回詳細な図を作ると、設計よりも図の作成・更新に時間がかかってしまいます。

すべての開発案件で同じ種類・粒度の図を作る必要はありません。変更規模や影響範囲に応じて、必要な図を必要な粒度で描くことが重要だと考えています。

全体像を描くときの注意点

一番注意したいのは、図を作ること自体を目的にしないことです。重要なのは、図を描く過程で抜け漏れや責務の曖昧さ、データの流れの違和感を見つけることです。

また、細かく描けば描くほど良いわけでもありません。詳細な仕様は設計書で定義し、全体像では「何があり、何と何が関係しているのか」が分かる粒度に留めるようにしています。

最後に

私は設計するとき、必要に応じて、
システム構成図で「何があるのか」を整理する
↓
画面＋API＋データ連携図で「何と何がつながっているのか」を整理する
↓
シーケンス図で「どのような順番で処理されるのか」を整理する
↓
画面設計書やAPI設計書などの細部へ落とし込む

というように、システム全体 → 構成要素の関係 → 処理の流れ → 個々の仕様と、徐々に解像度を上げながら設計しています。
もちろん、すべての開発案件でこれらすべての図を作る必要はありません。小さな開発案件であれば簡単な図でも十分です。

また、全体像を描くことは、設計書とは別の成果物を増やすことが目的ではありません。図を描く過程で設計上の違和感に気付き、細部へ入る前に問題を見つけることが重要だと考えています。

これが、私が設計するときに大切にしている考え方です。