The Engineering of Intent 第11章:エージェント型デバッグの技法

本記事は、私の著書The Engineering of Intent(英語版)を1章ずつ読み解くシリーズの第11回です。前回の記事では、構造的な問題を捕まえる5層の品質ゲートのスタックを順に見てきました。本章が扱うのは、そこをすり抜けるバグ──ローカルでは再現せず、原因が自分では書いていない何百ものファイルに散らばっているバグです。


AIネイティブ時代のデバッグは考古学である

AIネイティブな体制において、デバッグは考古学です。そのコードは、あなたがゆるく監督していたエージェントが書いたものかもしれません。コミットメッセージは、あの火曜日の午後にあなたが実際に考えていたことを説明していないかもしれません。第11章は、事後に因果関係を再構築するための道具を提供します──それが今や、仕事の大半なのです。


自己修正ループ

再現し、完全なトレースを取得し、エージェントに渡し、仮説と診断方法を求め、繰り返す。このループは、人間が修正を受け入れる前に根本原因の特定を求め続ければ、数回の反復で収束します。人間が「とにかく直して」と言った時点で、ループは失敗します。

💡 ポイント: コードを読み直す前に、エージェントに制御フローのMermaid図を生成させてください。テキストでは見えなかった多くのバグが、図にするとひと目でわかります。この小技ひとつで、私はこの1年で何十時間も節約してきました。しかも、本章で最も安上がりな一手です。

二分探索、オブザーバビリティ、そしてキャッシュのハイゼンバグ

本章が「譲れない」と主張する規律が2つあります。

  • git bisectを体に叩き込むこと。 よくある失敗モードに対して二分探索を自動化するスクリプトは、1か月以内に元が取れます。AIネイティブなコードベースでは、問題のコミットが間接的な原因にすぎないことも少なくありません。まずbisectでコミットを特定し、それからエージェントを使って真の原因をたどってください。
  • 基盤としてのオブザーバビリティ。 エージェント型デバッグの質は、与えられるトレースの質で決まります。構造化ログ、分散トレース、状態イベントの履歴。報告されたバグについて、一連のイベントをひとつのクエリですべて取り出せないなら、バグを直す前にオブザーバビリティを直してください。

「ある1社の顧客でだけ断続的に起きるバグ。何時間もの手作業の調査でも、何も見つかりませんでした。エージェントにリクエスト履歴とキャッシュ設定を与えると、キャッシュキーの計算にエッジケースがあり、IDの違いが末尾の空白だけのユーザー同士が混同されている、という仮説を立てました。15分で再現し、さらに20分で修正し、このクラスのバグを起こりえなくする『境界でトリムする』という規約を明文化しました。」


デバッグにおける3つのアンチパターン

  • 「とにかく直して」アンチパターン(just-fix-it anti-pattern) ── 根本原因を確認しないまま修正を受け入れること。
  • コンテキスト過積載アンチパターン(context-overflow anti-pattern) ── 問いそのものがおかしいのに、ファイルを追加し続けること。
  • モデル乗り換えアンチパターン(swap-the-model anti-pattern) ── 問題を言い直す代わりに、別のモデルに手を伸ばすこと。
⚠ 障害対応の最中にやってはいけないこと: 人間の確認なしに、エージェントに本番環境で自律的にコマンドを実行させないこと。デバッグしながらリファクタリングしないこと──それはひとつの作業ではなく、2つの作業です。同じクラスのバグを防ぐための規約を更新する前に、インシデントをクローズしないこと。規約の更新なしにクローズしたインシデントは再発します。たいていはより悪い形で、たいていはもっと都合の悪い週に。

次回 ── 第12章「GenDDポッド」 本書の第V部:エンタープライズ規模とチームの進化では、視点を個人とコードベースからチームへと引いていきます。同章では、AIネイティブな仕事を持続的に出荷できるチーム構造であるGenDDポッドと、この2年間で職務記述が最も大きく変わったいくつかの役割を紹介します。


📖 さらに詳しく知りたい方へ

本書の第11章では、再現 → 仮説 → 診断 → 根本原因 → 修正という完全なループ、高速な開発ペースの下での二分探索のプレイブック、オブザーバビリティのチェックリスト、キャッシュのハイゼンバグのケーススタディの全容、3つのデバッグのアンチパターンとその立て直し方、そして障害対応のランブックを解説しています。

The Engineering of Intent をAmazonで購入する →(英語版)

2026-04-27

下田 昌平

開発に関するインプットをアウトプットしています。