結合テストで見つかった障害を、AIに直してもらう。AIは報告された障害に対する修正を加え、ユニットテストも通しました。ところが次の回帰テストで、別の処理が失敗し始めます。総合テストでは、外部に送るはずのレポートが、同じ内容で2回送られていました。
どちらも、私たちがエージェント型のコーディングツールで開発を進める中で、実際に経験したことです。いずれも本番に出る前、テストの工程で見つけています。画面を一つ作る、単機能のツールを作るといった仕事なら、AIはすでに頼れる相棒です。それなのに、複数の処理や外部サービスをつなぐ段階になると、急につまずきが増える。この記事では、その理由を一つの見方で整理し、実例と、そこから導いた対策を紹介します。
AIが得意なのは、「お手本」と「採点方法」がそろった仕事
既存のAPIを呼び出す管理画面には、決まった入出力があります。よく知られたゲームには、動きやルールのお手本があります。小さなツールなら、作った人が触ってみれば、期待どおりかどうかをすぐ判定できます。
こうした仕事には、AIが参照できるお手本と、できたものを判定する採点方法がそろっています。だからAIは、書いて、試して、直す、を自分で回せます。
業務システムの連携では、この二つが欠けがちです。ただし、欠け方は一通りではありません。
- お手本には二種類あります。一つは、その現場だけの業務ルールです。「受注を確定する」が、注文を受け付けることなのか、在庫を確保することなのか、出荷を約束することなのかは、会社や部署によって違い、多くの場合どこにも書かれていません。もう一つは、冪等性のような、広く知られた設計の定石です。こちらは世の中に存在しますが、AIは依頼に書かれていなければ、自分から当てはめないことがあります。
- 採点方法の欠け方は三つあります。そもそも存在しない。存在するのに、AIに渡していない。渡しても、AIの作業環境では実行できない。画面、データベース、外部サービス、定期処理をつないで確かめる方法は、このどれかになりがちです。
それでもAIは手を止めません。書かれていない前提を、もっともらしく補いながら、短時間で大量のコードを書きます。その補い方が業務に合っているかは、つないで初めて分かる。人が開発する場合にも同じ難しさはありますが、AIの速さの分だけ、食い違いが表に出る前に広がってしまいます。しかも、この難しさを左右するのはシステムの規模だけではありません。小さな機能でも、外部サービスや既存の処理とつながれば、確かめるべきことは一気に増えます。AIが「書かれていないことは見えない」という性質は、以前の記事「AIは書かれたことしか見ていない――開発で踏んだ３つの落とし穴」でも紹介しました。
もちろん、モデルの能力やツールの進歩によって、AIが自分で補える範囲は広がっていきます。それでも、その現場だけの業務ルールや、採点方法をAIの手元に届けることは、人の側の仕事として残るはずです。
実例1：障害は直したのに、別の処理が壊れた
結合テストで障害が見つかり、その障害報告だけを入力にして、AIに調査と修正を任せました。AIは副作用を考慮しないまま、報告された障害に対する最小限の修正を加え、ユニットテストも通りました。
ところが、その後の回帰テストで、別の処理のテストが失敗しました。AIに再調査させると、原因が判明しました。最初の修正の副作用が、別の処理に及んでいたのです。こうしたケースは、一度きりではなく何度も起きていました。
採点方法はあった。ただ、AIの作業の外にあった
このときAIに渡したのは、障害報告だけでした。AIから見た採点方法は、「報告された症状が出なくなること」と、手元のユニットテストが通ることです。その基準に照らせば、AIの修正は目的を果たした、無駄のない最小限のものでした。
回帰テストという採点方法は、存在していました。実際、失敗を見つけたのは回帰テストです。足りなかったのは、それを修正の段階でAIに渡し、実行させることでした。修正した部分がほかの処理からどう使われているかも、渡した情報のどこにも書かれていませんでした。採点方法が存在するのに、AIに渡していない。先に挙げた欠け方の二つ目です。
調査の範囲を広げる。ただし、時間とコストは増える
この件は、AIに改めて横串で調査させ、全体として整合する修正を提案させてから実施させることで、解決しました。
その後は、この経験を、AIが作業のたびに参照する作業ルールに反映しています。障害の調査を頼むときは、報告された箇所だけでなく、修正が及ぶ影響範囲の調査も、調査の段階からスコープに含める、というルールです。
このルールを入れてから、同じ種類の失敗は、体感では減っています。その一方で、AIによる調査の時間とコストは、以前よりかさむようになりました。影響範囲まで調べさせれば、それだけ作業は増えます。手戻りの削減と調査の負担のどちらを取るかは、障害の重さや修正箇所によって判断を分ける必要がある、と考えています。
あわせて、判定の基準もAIの手元に閉じないようにしておくことをおすすめします。修正のたびに回帰テストを回し、業務上の期待結果に照らして確かめる。期待結果の決め方は、後の「AIに任せる前に、何をそろえるか」で紹介します。
実例2：タイムアウトで再試行したら、同じレポートが2回届いた
AIと進めていた開発で、外部にレポートを送信する処理が実装されました。同じ依頼を何度受けても結果が1回分になる、という性質（冪等性）は考慮されていませんでした。
この処理が、総合テストで障害として検知されます。外部に、同じレポートが2回送られていたのです。AIに調べさせると、原因はタイムアウト後の再試行でした。修正では、送信の状態をデータベースのトランザクションの中でフラグとして記録し、同じレポートを二重に送らないようにして、冪等性を確保しました。
タイムアウトは「失敗」ではなく「結果が分からない」
タイムアウトから分かるのは、送信元が時間内に応答を受け取れなかった、ということだけです。外部の側では、すでに受け付けが完了しているかもしれません。そこで同じ内容を送り直せば、別の依頼として処理され、2通目が届きます。AWSの設計解説も、通信が途切れた後は、処理が実行されたかどうかを呼び出し元が判断できないことを、この問題の出発点にしています。[1]
冪等性は、広く知られた設計の定石です。お手本は世の中にあります。それでも、相手の側で成功している可能性が依頼にも仕様にも書かれていなければ、実装する側は、AIでも人でも、それを考慮しないまま進みがちです。そして、正常に一度送るだけのテストでは、この問題は見つかりません。外部をテスト用の代わりの仕組みに置き換えたテストでも、応答だけが失われる状況は、意図して作らない限り起きません。定石を当てはめるきっかけも、応答が失われる状況を試す採点方法も欠けていれば、問題は外部とつなぐ段階まで表に出てこない。今回、総合テストで初めて見つかったのも、この構図によるものだと私たちは考えています。
同じ依頼を何度受けても、結果が1回分になるようにする
ここからは、この種の問題に対する一般的な対策です。中心になるのは、冪等性を持たせることです。
- 依頼ごとに識別番号を付ける。再試行では、同じ番号を使う。[1]
- 受け取る側が、処理済みの番号を記録する。同じ番号の依頼が再び来たら、処理し直さず、1回目の結果を返す。自分たちで受け取る側を作るなら、番号の記録と処理の実行が食い違わないよう、一体で確定させる。[1]
- 受け取る側に手を入れられないときは、送る側で状態を管理する。私たちの修正のように、送信の状態を記録して二重送信を防ぐ。外部サービスに重複を防ぐ仕組みや、処理結果を照会する手段があれば、それも使う。
- 結果をすぐに確定できないときは、「確認待ち」として残す。応答が失われた送信を、送ったとみなすのか、送っていないとみなすのか。外部に照会できなければ、二重に送るリスクを取って再送するか、確認待ちにして人が確かめるかの選択になります。成功か失敗かの二択に押し込まず、どちらを取るかを決めておくことが大切です。
AIへの依頼も変わります。「再試行を実装して」ではなく、「相手の側では成功したが、応答だけが失われた場合を扱って」と、状況を具体的に書く。テストでは、その状況を意図的に作り、外部に届くのが1回分に収まることまで確かめます。メールの送信、請求書の発行、外部への通知など、外に何かを送る処理は、どれも同じ構図を抱えています。
実例3：作業を分担したら、前提が食い違った
設計、実装、レビューを複数のAIに分担させる中で、前のAIの推測が、次のAIに確定した仕様として受け継がれたことがあります。前のAIが「未入力なら0を入れる想定」と、推測であることを示さずに報告し、次のAIがそれをそのまま実装したのです。気づいたのは、出来上がったプロダクトを人の手で試験したときでした。経緯は「AIは書かれたことしか見ていない」で詳しく紹介しています。
同じことは、機能を分けて作るときにも起きます。たとえば、受注画面と在庫APIを別々のAIに作らせたとします。受注画面を作ったAIは「注文の登録に成功したら、在庫も確保された」と考え、在庫APIを作ったAIは「注文の登録とは別に、在庫確保の依頼を受ける」と考える。APIの接続は成功しているのに、画面の「注文完了」と実際の在庫の状態が一致しません。作業者の間で共有するお手本が、どこにも書かれていなかったためです。
長い作業の進捗や前提をどう引き継ぐかは、AIの開発元にとっても課題です。Anthropicは、作業のたびに進捗の記録を残し、一度に一つの機能だけを実装させ、利用者と同じ操作で最後まで動作を確かめさせる進め方を紹介しています。[2]
共有する約束を書いて残し、細い流れを早く一度つなぐ
各担当に共有したいのは、APIの項目名だけではありません。「成功の応答は、何の完了を意味するのか」「在庫確保前の注文を、画面ではどう表示するのか」といった、処理の意味も含みます。それを共通の仕様として参照できる場所に置き、変更したら、その理由と、影響する画面・API・テストも記録します。過去の会話をすべて読ませるより、現在有効な決定と未決定の事項を見つけやすくしておくことが大切です。
開発の順序も変えます。すべての画面とAPIの完成を待たず、まず「一種類の商品を注文し、在庫を確保し、請求まで進める」という細い流れを、端から端まで動かします（ウォーキングスケルトンとも呼ばれる進め方です）。データの受け渡しと、各処理の意味が合っているかを、ここで確かめる。それから商品や処理の種類を増やしていけば、並行して作業を増やしても、すでに動いている流れを壊していないかを継続して確かめられます。
当てはめ例：取消ボタンの裏にある業務ルール
最後に、この見方を設計に当てはめる例を一つ挙げます。ここからは、説明のために組み立てた仮想の例です。受注・在庫・請求をつなぐB2Bシステムで、AIに「注文の登録と取消ができる受注管理を作って」と頼んだとします。
取消ボタンを押せば注文の状態が「取消済み」に変わる画面は、すぐにできるでしょう。受注画面だけを見れば、期待どおりです。ところが、在庫を確保し、請求書を発行した後で注文を取り消すと、在庫の確保も請求も残ったままになります。
では、すべて自動で元に戻せばよいのか。すでに出荷していれば、返品の手続きが必要かもしれません。請求を締めた後なら、請求書を消すのではなく、調整の記録を残すのがその会社のやり方かもしれません。取消ボタンの裏には、実装の前に決めておくべき業務ルールがあります。現場だけのお手本が書かれていなければ、AIはもっともらしく補い、機能ごとに別々の前提が入り込みます。
そこで、機能を分ける前に、関係者と状態ごとの扱いを決めておきます。
| 注文の状況 | 取消を受け付けた後の扱い |
|---|---|
| 在庫確保前 | 注文を取り消す |
| 在庫確保済み・出荷前 | 注文を取り消し、確保していた在庫を解放する |
| 出荷済み | 通常の取消とは分け、返品の手続きに進む |
| 請求処理済み | 請求の状態を確認し、決められた訂正・調整の手続きを行う |
実際には「出荷済み」と「請求処理済み」は同時に成り立つので、出荷の状態と請求の状態の組み合わせごとに扱いを決めることになります。あわせて、「取消が完了した注文には、解放されていない在庫確保を残さない」のように、処理をまたいで守る条件も書いておきます。注文、在庫、請求のどの機能がどのデータを変更する責任を持つかも決めます。
ルールのたたき台や、抜けていそうな例外を挙げる作業は、AIが得意とするところです。そこで出てきた業務上の判断を担当者が確かめ、決まったことと未決定のことを分ける。これを先に済ませておけば、各機能に渡す指示がそろいます。
AIに任せる前に、何をそろえるか
3つの実例は別々の問題に見えますが、どれも、AIにお手本か採点方法、あるいはその両方が欠けていました。
| 起きた問題 | 欠けていたもの | そろえるもの |
|---|---|---|
| 修正で別の処理が壊れた（実例1） | 採点方法をAIに渡していない（回帰テスト）。他の処理との関係も書かれていない | 調査段階からの影響範囲調査、回帰テストと業務上の期待結果 |
| 再試行で同じレポートが2回届いた（実例2） | 定石（冪等性）を当てはめるきっかけと、応答が失われる状況の採点方法 | 冪等性、確認待ちの扱い、応答が失われる状況のテスト |
| 分担すると前提が食い違った（実例3） | 作業者の間で共有するお手本 | 共通の仕様、現在の決定、細い流れの早期結合 |
当てはめ例の取消ボタンなら、欠けているのは現場だけのお手本、つまり状態ごとの扱いと、処理をまたいで守る条件です。
最初からすべての仕様を書き切る必要はありません。私たちは、次の順序で進めるのがよいと考えています。
- 一つの業務の流れと、完了したときの期待結果を決める。たとえば「一件の注文から請求まで」を対象にする。
- その流れに関わる共通のルールをそろえる。状態、データを変更する責任、取消や再試行の扱いを確認する。
- AIに小さな変更を実装してもらう。判断できない業務ルールは未決事項として取り出させ、人が確認してから進める。
- 実際につないで結果を見る。正常な流れに加え、取消、重複、通信の失敗なども確かめる。
- 決定と確認の結果を残し、次の変更に進む。得た教訓は、実例1のように、AIが毎回参照する作業ルールにも反映する。
1つ目の期待結果は、実装を読む前でも答えられる具体例にします。たとえば、注文した時点で在庫を確保すると決めた会社なら、次のようになります。
- 在庫が10個ある商品を3個注文すると、販売できる在庫は7個になる。
- 出荷前にその注文を取り消すと、販売できる在庫は10個に戻る。
- 同じ送信依頼を再送しても、外部に届くのは1回分だけである。
実装したAIとは別の担当（人や別のAI）に確認させるときも、判定の基準は、この合意済みの期待結果にします。評価を分けても、評価役のAIは、見つけた問題を「大したことはない」と自分で納得してしまったり、表面的にしか試さずに細かな不具合を見逃したりしがちだったと、Anthropicも報告しているためです。[3]
AIの作業環境も、同じ考え方で整えます。現在の仕様を参照できる、アプリを起動できる、検証用のデータがある、テストを実行できる、エラーや処理結果を確かめられる。採点方法がAIの手の届くところにあれば、AIは書いた後の確認と修正まで自分で進められます。採点方法の三つ目の欠け方、「渡しても実行できない」を防ぐための準備です。
本番に入る前には、既存データの移行や、処理が止まったときの検知と復旧も、完成の条件に含めます。たとえば送信処理が「確認待ち」になったとき、誰がどこでそれに気づき、どう解消するのか。そこまで決めて初めて、業務として使える状態になります。
システムの開発を発注する側の方へ
AIを使った開発を依頼するときに、発注する側で決めておいていただけると、手戻りが大きく減ることがあります。
- 取消、返品、訂正のときの扱い。正常な流れだけでなく、元に戻すときの業務ルールです。
- 「完了した」と言える状態を、具体的な例で。「この注文を取り消したら、在庫はこう戻る」のような例が、そのまま検証の基準になります。
- 早い段階で、細い流れを一度見る場を設けること。一件の注文から請求までが動いた時点で確認していただくと、前提の食い違いを早く見つけられます。
まとめ：お手本と採点方法を、AIに渡せる形にする
お手本と採点方法がそろった仕事なら、AIは目標を受け取り、自分で試しながら仕上げられます。私たちの経験では、システムをつなぐ開発でのつまずきは、AIの実装力そのものより、その二つが欠けたまま任せていたことに起因するものが目立ちました。
何をもって「確定」とするのか。途中で失敗したらどうするのか。どの状態になれば業務が完了したと言えるのか。これらを書いて共有し、AIが実際の処理で確かめられるようにする。機能をいくつAIに作らせるかと同じくらい、各作業が同じ業務ルールに従い、つないだ結果を確かめられるかを設計することが、AIの実装力を業務システムの完成につなげる鍵になると考えています。
参考資料
- Malcolm Featonby / AWS Builders’ Library. Making retries safe with idempotent APIs。通信が途切れた後の再試行と、呼び出し元が付ける識別番号による重複の防止。
- Anthropic. Effective harnesses for long-running agents（2025年11月26日）。複数の作業セッションにまたがる開発で、進捗の記録、一度に一つの機能、端から端までの動作確認を組み合わせる方法。
- Anthropic. Harness design for long-running application development（2026年3月24日）。実装するAIと評価するAIを分ける構成と、評価役が問題を軽く見たり表面的にしか試さなかったりした点、その調整方法。
当てはめ例の受注・在庫・請求の事例と、実例3のうち受注画面と在庫APIの例は、説明用に構成したものです。資料確認日：2026年10月15日