シーケンス図の書き方｜要件を詰める5ステップ

はじめに

画面仕様には「予約ボタンを押す」と書かれている。API仕様には「予約を登録する」と書かれている。ところが、同じ時間帯に二人が予約したらどうなるのか、決済に成功して予約登録だけ失敗したらどう戻すのかは、どちらにも書かれていない。

この抜けを見つけるのがシーケンス図である。シーケンス図は、利用者やシステムを横に並べ、メッセージを上から下へ時系列で示すUMLの図だ。画面の見た目ではなく、誰が、誰に、何を依頼し、どの応答を待って次へ進むかを表す。

IBMのシーケンス図解説でも、相互作用に参加する要素とメッセージの順序を表す図として説明されている。記法を覚えることが目的ではない。発注者、業務担当、開発者が、同じ処理順序と例外を見て合意することが目的だ。

この記事では、会議室予約を例に、シーケンス図の書き方を5ステップで整理する。

シーケンス図で使う基本記号

最初に覚える記号は多くない。

PlantUMLの公式ドキュメントでは、参加者、矢印、応答、グループ化、分岐などをテキストで記述できる。Mermaidでも同様にコード管理できる。ツールはチームが更新しやすいものを選べばよい。大切なのは、図を画像として固定せず、要件変更と一緒に直せる状態にすることだ。

シーケンス図の書き方を5ステップで整理する

ステップ1：一つの業務イベントに絞る

最初から「予約システム全体」を一枚に描かない。「空きを検索する」「予約を確定する」「予約を取り消す」のように、一つの目的へ分ける。今回は「利用者が会議室を予約し、予約番号を受け取る」までを対象にする。

開始条件と終了条件も先に書く。

• 開始：利用者がログイン済みで、日時と会議室を選んでいる
• 正常終了：予約が一件だけ登録され、予約番号が表示される
• 異常終了：予約は登録されず、利用者が次の操作を選べる

この三行がないと、図の終点が人によって変わる。通知メールまで含める人もいれば、DB登録で終わりと考える人もいるからだ。業務の前後関係はTo-Be業務フローの作り方、一つの場面のやり取りはシーケンス図と分けると読みやすい。

ステップ2：参加者を責任の境界で並べる

次に、やり取りへ参加する要素を横に並べる。会議室予約なら、利用者、予約画面、予約サービス、予約DB、通知サービスが候補になる。

要件定義の段階で内部クラスを細かく並べすぎる必要はない。発注者が判断できる責任境界を置く。特に外部サービスは独立した参加者にする。応答時間、停止、契約、再試行の条件が自社システムと異なるからだ。

参加者ごとに、次の三点を確認する。

1. 誰が管理するか
2. 読み取りと更新のどちらを行うか
3. 失敗したとき、どこまで結果を確認できるか

システム間の接点が多い場合は、先に外部インターフェース一覧を作ると漏れを減らせる。

ステップ3：正常系を具体的なメッセージで描く

参加者を並べたら、正常に終わる最短経路を上から下へ描く。矢印には「処理する」ではなく、「空き状況を照会する」「予約を登録する」のように、受け手が行う動作を書く。

この図だけでも、二つの確認が生まれる。画面表示と通知送信はどちらが先か。通知に失敗しても予約は成立するか。文章だけでは埋もれていた順序が見える。

メッセージには、必要に応じて主要な入力と出力も添える。予約要求なら、利用者ID、会議室ID、開始・終了日時、要求IDが候補だ。詳細な型やエラーコードはAPI仕様書の書き方へ分け、シーケンス図は関係と順番を読める密度に保つ。

ステップ4：分岐・タイムアウト・重複を加える

正常系を描いたら、業務上重要な例外を `alt` や `opt` で足す。すべての技術エラーを一枚へ詰め込む必要はない。利用者の結果、データの整合性、費用、権限に影響する分岐を優先する。

会議室予約なら、少なくとも次を確認したい。

• 空き確認後、登録前に別の予約が入った
• DB更新は成功したが、画面への応答がタイムアウトした
• 利用者が完了画面を待てず、予約ボタンを再度押した
• 通知サービスだけが停止している
• 利用者に対象会議室を予約する権限がない

重要なのは、タイムアウトを即座に「失敗」と決めないことだ。応答を受け取れなくても、登録自体は成功している場合がある。要求IDで処理結果を照会し、同じ要求の再送では二重登録しない仕様が必要になる。

分岐ごとに、利用者へ見せる結果と内部状態を分ける。「エラーを表示する」だけでは足りない。予約は未登録なのか、登録済みで通知待ちなのか、結果不明で照合が必要なのかを決める。状態の整理には状態遷移の考え方も使える。

ステップ5：図を受入条件へ変換する

図が完成しても、レビューで眺めるだけでは仕様にならない。各経路を受入テストへ変換する。

図中の `alt` が一つ増えたら、テストケースも一つ以上増える。逆に、テストで必要な経路が図に見つからないなら、要件が抜けている。シーケンス図と受入条件を往復させると、実装前に曖昧さを減らせる。

よくある4つの失敗

一枚に全機能を詰め込む

矢印が交差し、誰も更新しなくなる。業務イベント単位に分け、共通処理は別図へ切り出す。

画面とDBだけで描く

権限確認、外部API、通知、監査ログが消える。責任や障害条件が異なる境界は参加者として表す。

正常系だけで完成とする

本番事故は、競合、再送、タイムアウト、部分成功で起きる。影響の大きい例外を最低一つは描く。

実装後の内部構造を要件として固定する

要件定義では、利用者と外部システムから見える振る舞いを優先する。クラス名やライブラリ名まで固定すると、実装方法の変更が業務合意の変更になってしまう。

レビューで使う7つの質問

最後に、シーケンス図を次の質問で読み直す。

1. 開始条件と正常終了は明確か
2. 誰の権限で各操作を行うか
3. 外部サービスの停止や遅延を表したか
4. 同時実行でデータが競合しないか
5. タイムアウト後に結果を照合できるか
6. 再送しても二重更新にならないか
7. 各分岐を受入テストへ変換できるか

七つに答えられれば、図は説明資料から検証可能な仕様へ近づく。AIに実装やテスト生成を任せる場合も、参加者、メッセージ、分岐、終了条件が構造化されているほど解釈の余地を狭められる。AIが読める仕様書のテンプレートと組み合わせると、図の外にある目的、制約、非機能要件も補える。

シーケンス図は例外を話し合うために使う

シーケンス図の価値は、きれいな正常系を描くことではない。処理の順番を見える形にし、「この間で失敗したらどうするか」「同じ依頼が二回来たらどうするか」を実装前に話せることにある。

まず一つの業務イベントを選び、参加者を並べ、正常系を描く。次に分岐、タイムアウト、重複を足し、最後に受入条件へ変換する。この5ステップなら、発注者と開発者が同じ図を使って責任と結果を確認できる。

Atsumellでは、AI業務整理ツール「Kakusill」を使い、業務フローや既存資料を整理し、シーケンス、例外条件、受入基準までAIが読める仕様へつなげている。画面や機能の一覧はあるものの、処理順序と失敗時の動きが固まっていない場合は、対象業務を一つ選んで整理するところから相談できる。