異常系設計表で「あとから気づくバグ」を防ぐ

正常系だけ設計して、異常系は実装者まかせになっていないか

仕様書やチケットに書かれているのは、たいてい「うまくいったときに何が起きるか」だけだ。ログインが成功したらダッシュボードに遷移する、フォームを送信したら一覧に反映される——そこまでは丁寧に書かれる。だが「通信が切れたら」「権限がなかったら」「同じ操作を2回押したら」は、実装者がコードを書きながらその場で決めていることが多い。

その場判断は担当者ごとにばらつく。あるエンジニアはアラートを出し、別のエンジニアは静かに失敗させ、また別の画面ではエラーメッセージが英語のまま残る。バグ報告の少なくない割合は、この「異常系の決め忘れ」が原因だ。設計の時点で異常系を先に決めてしまえば、この手のバグはそもそも生まれない。

異常系設計表を作る

正常系のフローを書き終えたら、次の4項目を埋める表を作る。画面や API エンドポイントごとに1行ずつ増やしていけばいい。

1. 発生条件を洗い出す

「通信エラー」だけでは粒度が粗い。以下のように具体化する。

• ネットワーク切断・タイムアウト
• 認証トークンの失効
• 入力バリデーションエラー（必須項目・形式・桁数）
• 権限不足（他人のリソースへのアクセス）
• 二重送信・多重クリック
• サーバー内部エラー（5xx）

2. ユーザーに見せる文言

「エラーが発生しました」だけの文言は、ユーザーにもサポートにも何も伝えない。何が起きたか・次に何をすればいいかをセットで書く。

3. ログに残す情報

再現に必要な情報を先に決めておく。エンドポイント、ステータスコード、タイムスタンプ、リクエストID。個人情報を含む値はログに残さないことも、この段階で明記する。

4. リトライ可否

自動リトライしていいのか、ユーザー操作が必要なのか。ここを決めておかないと、実装者が「とりあえず1回だけリトライ」のようなコードを書きがちになる。

記入例

実装前にレビューする

この表は、API設計レビューや画面設計レビューの議題に必ず含める。「この画面、権限エラーのときどう見せるんでしたっけ」がレビューの場で出てくれば、それは実装前に潰せる。実装が始まってから「あ、この場合どうしよう」となるのが一番コストが高い。

表を作る手間を惜しんで「異常系は実装しながら考える」を続けると、同じ種類のバグが画面ごとに少しずつ違う形で再発する。表は一度作れば、次の機能でもコピーして条件だけ差し替えられる資産になる。

Bugoon での実践

異常系設計表を作っても、実際にその通りに動いているかは触ってみないと分からない。QA担当者がBugoonのウィジェットで画面をチェックする際、設計表の行を一つずつなぞって、想定した文言が出るか・想定した条件で発生するかを確認し、ズレていればその場でスクリーンショットと操作ステップ付きのバグレポートを送れる。

また、通信エラー系の異常系は再現性が低く、報告だけでは開発者が状況を追いにくい。Bugoonはレポート送信時にConsoleログとNetworkエラーを自動で添付するため、設計表の「ログに残す情報」欄に書いたステータスコードやタイムスタンプが、実際のレポートにそのまま残る。異常系設計表とバグレポートが同じ語彙で書かれていると、報告を受け取った側が表のどの行の話かをすぐ特定できる。