システム遷移図とAPI仕様書は誰のために書くか——テクニカルディレクターの仕事

テクニカルディレクターが書くシステム遷移図とAPI仕様書は、「正しい図」を作るためではなく、読み手ごとの判断を早めるために書くものだと私は考えています。だから書き始める前に、まず読み手を1人決めます。読み手が決まらない図は、情報を足し続けて、最後には誰も開かなくなるからです。

同じ「遷移図」でも、読み手は3人いる

案件で「遷移図ください」と言われたとき、実際に欲しがっている人は大きく3人に分かれます。

読み手	知りたいこと	私が渡すもの
クライアント・決裁者	何ができて、どこが外部サービスか	全体の関係図1枚
デザイナー	どの画面からどこへ行けて、何が分岐か	画面遷移図
エンジニア（社内外）	どのタイミングで何を呼び、何が返るか	システム遷移図＋API仕様書

以前、1枚の図に全部を載せたことがあります。画面、API呼び出し、外部決済、メール送信、管理画面。私の頭の中では整理された図でしたが、クライアントは矢印の多さに黙り込み、エンジニアは「で、このボタンでどのエンドポイントを呼ぶんですか」と聞き返してきました。誰の問いにも答えていなかったわけです。

ソフトウェアアーキテクチャの図を抽象度ごとに分けて描くC4モデル（Simon Brown氏が考案）でも、いちばん上のSystem Context図の想定読者は、技術者か否か・開発チームの内外を問わない「全員」とされています。粒度を変えれば読み手が変わる、という整理は、小さなWeb案件でもそのまま使えると感じています。

システム遷移図は「状態」と「失敗」を書く

画面遷移図がユーザーの動線を描くのに対して、システム遷移図で私が欠かさず書くのは、画面の裏で何が起きているかです。特に抜けやすいのが次の2つです。

• 状態：未ログイン／仮登録／本登録、下書き／公開など、同じ画面でも表示が変わる条件
• 失敗したとき：APIがエラーを返した、決済がタイムアウトした、メールが届かなかった

正常系だけの図は、見積もりの段階では綺麗に見えます。ただ、実装で時間がかかるのはたいてい失敗系です。遷移図に「失敗したらどこに戻るか」の矢印を1本ずつ足しておくと、デザイナーはエラー画面の数を、エンジニアは例外処理の量を、その場で見積もれるようになります。

API仕様書は「未来の自分と、会ったことのない人」のため

API仕様書の読み手は、目の前のエンジニアだけではありません。半年後に改修する自分や、途中から入る外部の開発者も読み手です。

そのため、私は仕様書を口頭の補足なしで読める形にすることを優先しています。HTTP APIの仕様記述ではOpenAPI Specificationが広く使われていて、仕様自体も、人とコンピュータの双方がソースコードや追加ドキュメントなしにサービスの機能を理解できることを目的に掲げています。形式をそろえておけば、ドキュメント生成やモックサーバーなど周辺ツールにも流用しやすくなります。

ただ、形式より大事なのは中身の粒度だと思っています。私が最低限そろえるのは次の5つです。

1. エンドポイントとメソッド
2. 誰が呼べるか（認証の有無・権限）
3. リクエストの必須項目と型
4. 正常時のレスポンス例
5. エラー時のステータスと、画面側でどう扱うか

5つめは仕様書の範囲外に見えますが、ここを書いておくと、遷移図の「失敗したとき」の矢印と仕様書が1対1でつながります。

書く順番は、関係図 → 遷移図 → 仕様書

順番も固定しています。まずクライアントと関係図1枚で「どこまでを作るか、どこを外部に任せるか」を合意する。次に画面・システムの遷移図で動きを決める。仕様書は最後です。

仕様書から書き始めると、細部を決めた後で範囲の話がひっくり返り、書き直しが増えます。上の層で合意してから下の層に降りるほうが、結果として早く終わる実感があります。

明日から試せる一手

いま手元にある遷移図か仕様書を1つ開いて、表紙か1行目に「この資料の読み手：〇〇さん／この資料で決めること：〇〇」と書き足してみてください。

書けなかった場合、その資料は読み手が決まっていないまま育っています。読み手ごとに1枚ずつ分けるだけで、次の打ち合わせの質問の数が変わるはずです。