【お仕事ネタ】シバ丸印のこう書いたら楽じゃない？シリーズ第二弾：「外部連携する」と書いてある設計書が、なぜ後から燃えるのか--正常系だけ見えていても、異常系・責任分界・再送条件が見えていないと後工程で問題化しやすい話--

前回の記事では、設計書レビューで困るのは「項目があるかどうか」だけではなく、「その粒度で後工程に進めるのか」という話を書きました。

前回はこちらです。

https://note.com/shibamaru_log/n/n72513c043027

今回は、その中でも特に問題が見えにくく、後工程で影響が大きくなりやすいテーマとして、外部連携をもう少し掘ってみます。

要件定義書や基本設計書を読んでいると、よくこういう記載があります。

一見すると、外部連携について書かれているように見えます。

連携先は書いてある。
連携タイミングも書いてある。
エラー時の話にも触れている。

なので、レビュー時点ではついこう思いがちです。

もちろん、それで問題ないケースもあります。

ただし、外部連携は、仕様の詰めが甘いと後工程で問題が顕在化しやすい領域です。

特に問題になりやすいのは、正常に連携できた場合ではありません。

連携に失敗したとき。
相手先システムの応答が遅れたとき。
こちらでは失敗扱いなのに、外部側では登録できているかもしれないとき。
再送してよいのか、してはいけないのか分からないとき。

つまり、正常系の顔をした異常系フェスティバルです。

もちろん、すべての外部連携がこうなるわけではありません。

ただ、問題が起きるときは、こういう「正常に見えていた境界部分」から出てくることが多いです。

この記事で扱う外部連携の前提

先に、この記事の前提を少しだけ置いておきます。

本記事では、主に画面操作の裏で動くリアルタイム寄りの外部連携を念頭に置いています。

たとえば、予約登録、決済、在庫照会、会員情報連携など、利用者の操作や業務操作と近いタイミングで動く同期API連携、または即時性の高い非同期連携です。

一方で、実務には他にもいろいろな外部連携があります。

夜間バッチ。
ファイル連携。
メッセージキュー。
イベント駆動。
Webhook。
日次や月次の一括連携。

これらは、方式によって確認すべき粒度や復旧方法が変わります。

バッチ連携であれば、利用者へその場でメッセージを表示する話ではなく、翌朝の運用リカバリや再実行単位が主な論点になるかもしれません。

メッセージキューを使う非同期連携であれば、「処理中」という中間状態が構造的に必要になるかもしれません。

なので、本記事の内容をすべての外部連携にそのまま当てはめるのは少し乱暴です。

ただし、どの方式であっても、次の論点はかなり共通しています。

• 失敗したときに業務上どう扱うのか

• どちらのデータを正とするのか

• 再送や重複をどう扱うのか

• 誰が復旧・確認するのか

• 後工程で何を決めなければならないのか

この記事では、その共通する考え方を中心に整理します。

「外部連携する」だけでは、実はほとんど決まっていない

「外部システムへ連携する」と書かれていると、何となく決まっているように見えます。

でも、レビュー観点で見ると、この一文だけではかなり不安が残ります。

たとえば、次のようなことが分かりません。

• 何のために連携するのか

• どのデータを連携するのか

• いつ連携するのか

• 同期連携なのか、非同期連携なのか

• 連携に失敗した場合、業務状態をどう扱うのか

• 利用者には何と表示するのか

• 外部側で処理済みかどうかをどう確認するのか

• 再送してよい条件は何か

• 二重登録や重複処理をどう防ぐのか

• 復旧作業は誰が行うのか

• どちらのシステムを正と判断するのか

• 結合テストや受入テストで何を確認するのか

こうして並べると分かります。

「外部連携する」と書いてあるだけでは、外部連携の存在が分かるだけです。

後工程で必要になる判断は、まだかなり残っています。

そして、この残り方が厄介です。

単なる記載漏れではなく、業務状態、画面表示、DB設計、外部IF、運用設計、テスト設計にまたがって影響します。

つまり、外部連携の不足は、あとから局所的に直しにくい。

小さな穴に見えて、下に巨大な地下空洞があるタイプです。

外部連携で特に危ないのは「失敗したときの業務状態」

外部連携で最初に見たいのは、細かいAPI仕様ではありません。

要件定義や基本設計初期で特に見たいのは、

です。

たとえば、旅行予約サイトでホテル予約を行うケースを考えます。

利用者が予約ボタンを押した。
旅行予約サイト側では予約情報を保存した。
しかし、外部ホテル在庫管理システムへの連携に失敗した。

このとき、その予約は何扱いでしょうか。

予約完了なのか。
予約処理中なのか。
連携保留なのか。
取消なのか。
手動確認待ちなのか。
再送待ちなのか。

ここが決まらないと、後続の設計が決まりません。

予約状態が決まらなければ、DB項目も決まりません。
利用者向け表示も決まりません。
管理画面での検索条件も決まりません。
再送処理も決まりません。
問い合わせ対応も決まりません。
結合テストの期待結果も決まりません。

「エラー時はメッセージを表示する」だけでは足りない理由はここです。

メッセージを出す前に、そもそも業務として何が起きた扱いなのかを整理する必要があります。

完了なのか。
未完了なのか。
保留なのか。
復旧可能なのか。
人が見る必要があるのか。

この判断がないまま画面文言だけ決めても、後から崩れやすくなります。

文言は飾りではありません。

業務状態を利用者にどう伝えるかという、かなり重要な要件です。

「外部側では成功、こちらでは失敗」が一番いやらしい

外部連携で特に面倒なのは、単純な失敗だけではありません。

本当にいやらしいのは、片方では成功していて、片方では失敗扱いになっているケースです。

たとえば、こういう流れです。

• こちらから予約情報を送信した

• 外部システムでは予約登録に成功した

• しかし、こちらはタイムアウトで失敗扱いにした

• 利用者には「予約に失敗しました」と表示した

• 利用者がもう一度予約した

• 外部側には二重で予約が入った

簡単に流れで見ると、こういう状態です。

【タイムアウト時のデータ不整合イメージ】

1. 自社システムから外部ホテルシステムへ予約リクエストを送信

2. 外部ホテルシステム側では予約登録に成功

3. しかし、応答が遅れて自社システム側ではタイムアウト

4. 自社システム側では「失敗扱い」として処理

5. 利用者には「予約に失敗しました」と表示

6. 利用者が再度予約ボタンを押す

7. 外部ホテルシステム側では、同じ予約が二重登録される可能性

つまり、自社側では「失敗」に見えていても、外部側では「登録済み」になっていることがあります。

この状態で「失敗したので再送すればよい」と単純に扱うと、外部側ではすでに登録済みのデータに対して、もう一度登録リクエストを送ることになります。

だからこそ、外部連携では「失敗したかどうか」だけでなく、「外部側で処理済みかどうかを確認できるか」が重要になります。

利用者から見れば、失敗したと思って再操作しただけです。

システム側から見れば、外部側には登録済みの可能性があります。

業務側から見れば、在庫、決済、予約番号、キャンセル、問い合わせ対応が絡みます。

こういうケースでは、単に「再送する」だけでは危険です。

再送してよいのか。
外部側で登録済みか確認できるのか。
同じ予約IDなら重複登録されないのか。
冪等性を担保できるのか。
重複した場合はどちらを正とするのか。
利用者にはどう説明するのか。

ここでいう冪等性とは、同じ操作を複数回行っても、結果が意図せず変わらない性質のことです。

たとえば、同じ予約IDで再送した場合に、外部側で二重登録されず、同じ予約として扱えるのであれば、再送の安全性は上がります。

逆に、同じデータを送るたびに新しい予約として登録されるなら、再送はかなり慎重に扱う必要があります。

このあたりを何も決めずに「エラー時は再送する」と書いてあると、状況によっては危険です。

再送は便利です。

ただし、条件のない再送は、問題をもう一回送信するボタンになることがあります。

責任分界点が曖昧だと、障害時に揉める

外部連携では、責任分界点も重要です。

責任分界点というと少し硬いですが、要するにこういうことです。

ただし、ここで扱いたい責任分界には、少なくとも2種類あります。

1. 業務上・運用上の役割分担

たとえば、次のような話です。

• エラー発生時に誰が最初に確認するのか

• どちらのログを確認するのか

• データ不整合が起きた場合、誰が補正するのか

• 利用者や業務部門へ誰が連絡するのか

• 手動復旧が必要な場合、どのチームが対応するのか

これは、要件定義や基本設計、運用設計の中でかなり重要な論点です。

2. 契約やSLA上の責任

たとえば、次のような話です。

• 外部ベンダー側の障害時にどこまで保証されるのか

• 調査依頼の窓口はどこか

• 障害対応時間はどう定義されているのか

• SaaS側の制約をどこまで受け入れるのか

• 連携先が社内システムなのか、外部ベンダーなのか

こちらは、契約形態やプロジェクト体制によって大きく変わります。

なので、設計書レビューだけですべてを判断できるとは限りません。

ただし、少なくとも「業務上、誰が何を確認し、どこまで復旧できる必要があるのか」は見えていてほしいところです。

たとえば、予約情報を外部システムに連携する場合、次のような論点があります。

• 自システムは送信成功まで責任を持つのか

• 外部システムでの登録完了まで確認するのか

• 外部側の処理結果をどのように受け取るのか

• 外部側で登録済みかどうかを問い合わせできるのか

• エラー時の一次調査はどちらが行うのか

• データ補正はどちらが実施するのか

• 利用者への案内はどちらの業務部門が行うのか

• 障害時の連絡経路は決まっているのか

これが決まっていないと、障害時にこうなります。

こうなると、合同レビューや障害対応の場で大きな論点になりやすくなります。

この状態になると、設計書の記載を直すだけでは済みません。

業務運用、問い合わせ対応、障害対応、ログ確認、データ補正、場合によっては契約やSLAの話まで出てきます。

だからこそ、要件定義や基本設計の段階で、少なくとも責任分界の論点は見える状態にしておきたいです。

全部を完全に決めきる必要はありません。

ただし、

くらいは管理しておきたいところです。

要件定義では「決めること」と「論点として管理すること」を分ける

ここで誤解してほしくないのは、要件定義の時点で外部連携の詳細仕様をすべて決めろ、という話ではないことです。

外部システムの仕様がまだ固まっていない。
相手先ベンダーとの調整がこれから。
API仕様書がまだ出ていない。
運用担当との確認が終わっていない。
外部サービス側の制約がまだ分からない。

こういうことは普通にあります。

なので、「未確定」そのものは悪ではありません。

問題は、未確定であることが見えていない状態です。

つまり、

という話です。

要件定義や基本設計初期でやりたいのは、細かい技術仕様を無理に決め切ることではありません。

大事なのは、次の2つを分けることです。

1. この段階で決めておきたいこと

たとえば、次のようなものです。

• 何のために外部連携するのか

• どの業務タイミングで連携するのか

• 連携が失敗した場合、業務上どの状態として扱う方針か

• 利用者や運用担当者に、どのような影響が出るのか

• その外部連携が止まると、業務上どの程度困るのか

• どちらのシステムのデータを正とする考え方なのか

これは、技術仕様というより業務判断です。

ここが曖昧なままだと、基本設計、画面設計、DB設計、テスト設計、運用設計のすべてに影響します。

2. 後工程で詰める論点として管理すべきこと

一方で、次のような内容は、要件定義時点で詳細まで決まらないこともあります。

• 具体的なAPI項目

• エラーコードごとの処理

• リトライ回数や間隔

• 再送処理の実装方式

• ログ出力の詳細

• 外部側での重複判定仕様

• 監視・通知の具体的な仕組み

• 手動復旧の具体的な画面や手順

これらは、基本設計、外部IF設計、運用設計で詰める内容になることが多いです。

ただし、だからといって何も書かなくてよいわけではありません。

「この論点は未確定であり、基本設計開始前までに外部システム担当者と確認する」
「再送条件と重複防止方式は、外部IF仕様確定時に設計する」
「連携失敗時の運用対応は、運用設計で定義する」

このように、未確定事項として見える状態にしておくことが重要です。

未確定事項は、どこかに残して追えるようにする

未確定事項の管理方法は、現場によって異なります。

設計書のTBD欄に書く。
レビュー指摘票に残す。
課題管理表に起票する。
議事録のアクションアイテムにする。
Jira、Backlog、Redmine、Notionなどの管理ツールに登録する。

方法はどれでも構いません。

大事なのは、次の3つが後から追える状態になっていることです。

• 誰が確認するのか

• いつまでに確認するのか

• 何を決める必要があるのか

たとえば、次のように残します。

このくらい書かれていれば、「まだ決まっていない」こと自体は問題ではありません。

問題は、未確定事項がどこにも残らず、誰も追っていない状態です。

レビューの目的は、設計書をその場で完璧にすることではありません。

後工程で判断不能になる論点を、早めに見える場所へ出すことです。

悪い記載例と改善記載例

たとえば、外部連携について次のように書かれていたとします。

悪い例

この記載でも、「外部連携すること」自体は分かります。

ただし、後工程で必要になる判断がほとんど見えません。

• 何を連携するのか

• 失敗したら予約は何状態になるのか

• 利用者には何と表示するのか

• 管理者は復旧できるのか

• 再送してよいのか

• 二重登録をどう防ぐのか

• どの論点を基本設計までに整理するのか

改善例

改善例では、すべてを詳細に決め切っているわけではありません。

むしろ重要なのは、決まっていることと、これから整理すべき論点が分かれていることです。

レビューで見たいのは、完璧な記載ではありません。

このまま次工程に進んだときに、誰が何を判断すればよいかが見える状態になっているかです。

外部連携レビューで最低限見たい観点

外部連携のレビューでは、少なくとも次の観点を見ておくとよいです。

ただし、ここでも「要件定義で全部決める」必要はありません。

この段階で決めるべきことと、後工程で詰める論点として管理することを分けて見ます。

1. 連携目的

• 今見ること： 何のために外部連携するのか

• 後工程で： 詳細な処理方式

• 重大度の目安： 高

2. 連携タイミング

• 今見ること： どの業務操作・状態変化で連携するのか

• 後工程で： イベント発火条件、バッチ実行条件

• 重大度の目安： 高

3. 業務状態

• 今見ること： 失敗時に、完了・保留・取消・確認待ちなど、どの扱いにする方針か

• 後工程で： 詳細なステータス遷移

• 重大度の目安： 高

4. 責任分界

• 今見ること： 誰が確認・補正・連絡する必要があるのか

• 後工程で： 契約・SLA・詳細な運用手順

• 重大度の目安： 高

5. 正データ

• 今見ること： 不整合時に、どちらのシステムを正とする考え方か

• 後工程で： 照合・補正ロジック

• 重大度の目安： 高

6. 重複防止

• 今見ること： 再送・再操作で二重処理リスクがあるか

• 後工程で： 冪等性の実装方式、重複判定仕様

• 重大度の目安： 中

7. 利用者表示

• 今見ること： 利用者に、完了・処理中・失敗など、どう伝える方針か

• 後工程で： 具体的なメッセージ文言

• 重大度の目安： 中

8. 運用復旧

• 今見ること： 手動確認や再送が必要になりそうか

• 後工程で： 管理画面、再送バッチ、手順書

• 重大度の目安： 中

9. 監視・通知

• 今見ること： 失敗を検知する必要があるか

• 後工程で： アラート条件、通知先、監視ツール設定

• 重大度の目安： 中

10. テスト観点

• 今見ること： 異常系・境界系を確認対象に含めるか

• 後工程で： 具体的なテストケース、テストデータ

• 重大度の目安： 中

この観点リストで重要なのは、重大度だけではありません。

むしろ大事なのは、「どこまでを今見るか」と「どこからを後工程で詰めるか」を分けることです。

たとえば、「重複防止」は重要ですが、要件定義段階で実装方式まで決めきれないことはあります。

それでも、

という形で論点化できていれば、後工程に渡しやすくなります。

逆に、リスクがあること自体が見えていないと、結合テストや運用開始後に突然問題として出てきます。

レビュー指摘としては、どう書くか

仮に、要件定義書に次のような記載しかなかったとします。

この場合、レビュー指摘としては、たとえば次のように書けます。

この指摘で見ているのは、単なる文章の不足ではありません。

見ているのは、

です。

レビュー指摘は、細かければよいわけではありません。

ただし、外部連携のように後工程への影響が大きいところは、早めに論点を見える化したほうがよいです。

指摘重大度の例

外部連携レビューでは、指摘の重大度を分けておくと、対応優先度を判断しやすくなります。

なお、重大度はあくまで目安です。

実際の重大度は、システムの重要度や業務特性によって変わります。

特に、決済、在庫、予約、本人確認、金融取引のように、業務影響が大きい連携では重大度が上がります。

一方で、単なる通知や参照系の連携であれば、影響は限定的かもしれません。

たとえば、次のようなイメージです。

重大度：高

指摘例
連携失敗時の業務状態が未定義。

理由
画面、DB、運用、テストすべてに影響するため。

指摘例
外部側で登録済みだった場合の確認方法が未定義。

理由
二重登録、在庫不整合、問い合わせ対応に影響するため。

重大度：中

指摘例
再送してよい条件が未定義。

理由
基本設計・運用設計での検討が必要なため。

指摘例
監視通知先が未定義。

理由
運用設計で詰める内容だが、通知要否は早めに見たいもののため。

重大度：低〜中

指摘例
利用者向けメッセージの詳細文言が未定義。

理由
方針が決まっていれば後工程で詰められるため。

指摘例
ログ出力項目の詳細が未定義。

理由
詳細設計や運用設計で具体化可能なため。

大事なのは、「全部重大」にしないことです。

全部重大にすると、結局どれも重大ではなくなります。

重大度を分けることで、何を今確認し、何を次工程に持ち越せるかの判断がしやすくなります。

AIレビューに渡すなら、こういう観点を指定したい

AIに外部連携の設計書をレビューさせる場合も、単に「レビューしてください」と投げるだけだと、指摘が散らかりがちです。

たとえば、次のように観点を絞ると使いやすくなります。

あなたは熟練のITコンサルタントおよびQAリーダーです。

以下に提示する設計書または要件定義書の「外部連携」に関する記述をレビューし、後工程で問題化しやすい考慮漏れ・異常系の定義不足を抽出してください。

## レビューの視点

1. 外部連携の目的が明確か
2. 主要な連携データが分かるか
3. 連携タイミングが明確か
4. 連携失敗時、こちら側の業務ステータスが定義されているか
5. 外部側で処理済みだった場合の確認方法があるか
6. 二重送信・再送時の重複登録防止、または冪等性の考慮があるか
7. 障害発生時の責任分界点、ログ確認、データ補正、連絡先の論点があるか
8. 利用者へのエラー表示や、管理者への通知・復旧運用への考慮があるか
9. 要件定義で確定すべきことと、基本設計以降で詰めるべき論点が分けられているか
10. 結合テスト・受入テストで確認すべき異常系が見えているか

## 重大度の基準

- 高：
  このまま次工程に進めると、画面設計、DB設計、外部IF設計、運用設計、テスト設計に大きな手戻りが出る可能性があるもの

- 中：
  基本設計・外部IF設計・運用設計での具体化が必要なもの

- 低：
  詳細設計やテスト設計で補足可能なもの

## 出力形式

【重大度：高/中/低】指摘内容
- 理由：
- 修正案、または次に検討すべき論点：
- どの工程で決めるべきか：

## レビュー対象

※ここに設計書・要件定義書の該当箇所を貼り付ける。

AIレビューでは、指摘を出させること自体はそれほど難しくありません。

難しいのは、出てきた指摘が「今止めるべきもの」なのか、「次工程で詰めればよいもの」なのかを分けることです。

だからこそ、AIに渡す前に、人間側でレビュー基準を持っておく必要があります。

AIは便利です。

ただし、基準なしに使うと、指摘の仕分けに時間がかかり、かえってレビュー工数が増えることがあります。

AIに丸投げするのではなく、AIに見てもらう観点を人間が設計する。

ここもまた、レビュー設計の仕事です。

まとめ

外部連携は、「外部システムへ連携する」と書いただけでは足りません。

重要なのは、正常に連携できることだけではなく、失敗したときに業務としてどう扱うかです。

外部連携で特に見たいのは、次のような論点です。

• 何のために連携するのか

• 何を連携するのか

• いつ連携するのか

• 何をもって成功とするのか

• 失敗した場合、業務状態をどう扱うのか

• 利用者にどう見せるのか

• 管理者がどう復旧するのか

• 再送してよい条件は何か

• 二重登録や重複処理をどう防ぐのか

• 外部システムとの責任分界点はどこか

• テストでは何を確認するのか

ただし、要件定義の時点ですべてを詳細に決め切る必要はありません。

大事なのは、

を分けることです。

外部連携は、線を1本引けば終わりではありません。

その線の向こう側で何が起きるのか。
失敗したときに誰が見るのか。
どちらのデータを正とするのか。
利用者に何と伝えるのか。
復旧できるのか。
再送してよいのか。

ここまで見えて、ようやく後工程に渡しやすくなります。

設計書レビューで見たいのは、細かい実装方式そのものではありません。

この状態で次工程に進めてよいか。
後工程で判断不能になる論点が残っていないか。
未来の自分と後工程の人に、時限爆弾を渡していないか。

そこを見ることです。

外部連携は、後から問題化するとかなり面倒です。

だからこそ、早めに論点を見える化しておきたい。

迷子のレビューアを減らしたい。
後工程の「聞いてないんですけど」を減らしたい。
そして、できれば深夜の障害対応も減らしたい。

そのために、外部連携の論点は早めに見える場所へ置いておきたい。

それが今回の話です。

参考資料

本記事は、筆者の実務経験をもとにした整理です。

以下の資料は、要件定義プロセス、外部インターフェース、非機能要求、運用・保守観点を整理する際に参考になる公的資料として挙げています。

本記事は、これらの資料を直接引用・解説するものではありません。

• IPA「共通フレーム2013」

• IPA「非機能要求グレード」

• IPA「ユーザのための要件定義ガイド」

• デジタル庁「デジタル社会推進標準ガイドライン」

• デジタル庁「地方公共団体情報システム非機能要件の標準」

関連記事

前回記事

〖お仕事ネタ〗シバ丸印のこう書いたら楽じゃない？シリーズ第一弾
https://note.com/shibamaru_log/n/n72513c043027

あわせて読みたい記事

資格勉強の意義や、実務スキルの地図について書いた記事はこちらです。
https://note.com/shibamaru_log/n/n0b6a1bd787c5

妄想記事シリーズはこちらです。
https://note.com/shibamaru_log/n/n8d08f764ead1

noteマガジン・プロフィール

シバ丸ログ全体はこちらです。
https://note.com/shibamaru_log

後記

シバ丸印は、だいたいこのくらいの温度感でやっております。

外部連携は、ちゃんと見ておくと後工程が少し楽になります。

未来の誰かが少し楽になるなら、それはたぶん、今の自分も少し楽になるということです。