■ 1. 背景と課題
- 取り組みの概要:
- ZOZOTOWNのカート・決済・注文作成領域の一次調査を、AIエージェントのDevinに一次請けとして任せた
- 決済ドメインではミスが金銭的な事故や障害に直結するため、エージェントを任せられる状態にする工夫が主題となる
- 精度を左右したのはDevin本体よりも、ナレッジベースとプレイブックという2つの準備だった
- まだPoC段階であり、効果測定は今後実施するため具体的な数値はない
- 調査待ちによる意思決定の停滞:
- 改修のたびに影響範囲の洗い出し、実現可能性の判断、概算見積もりが必要で、毎回時間がかかる
- その間、問い合わせ元の他部門は次に進めず、調査速度が他部門の意思決定速度を決めていた
- エンジニアが向き合う問い:
- 自部門と他部門のどちらの管轄か
- 実現可能か、既存の設計と矛盾しないか
- どこに影響が及ぶか（抜け漏れなく）
- ざっくりどれくらいの工数か
- 横断調査の重さ:
- カート決済領域は複数のマイクロサービスに分かれている
- 小さな改修でも、領域内のサービスをすべて網羅しないと影響が抜け落ちる
■ 2. 設計の出発点
- 誤りの2分類:
- 許容できる誤りは、余計な指摘（偽陽性）
- 許容できない誤りは、影響範囲の見落とし（偽陰性）
- 見落としは実現可能と判断して進んだ後に発覚し、手戻りにつながる
- 精度を主目的から外す判断:
- ある程度の雑さは受け入れ、設計は見落としを潰すことだけに寄せた
- 一次調査で見積もりが大きくズレる支配的な要因は、見えていない影響の後からの発見だった
- 狙うのは個々の精度ではなく影響範囲の網羅であり、以降の設計判断はほぼすべてここから導かれる
- 一次調査の範囲:
- スコープ判定、影響範囲の洗い出し、実現可能性の判断、概算見積もりまでを指す
- 目的はエンジニアの調査コストを下げ、意思決定の入口で待たせないこと
- エージェントに渡すものの線引き:
- 見せるのはリポジトリのソースコードだけで、本番環境や顧客データには触れさせない
- この仕組みの危険箇所:
- 危ないのは調査を走らせることではなく、返ってきた結論が誤っている場合
- 誤った結論はレビューで止めない限り下流に残り、いずれ障害につながるため、人によるレビューが要となる
- Devinを選んだ理由:
- 複数リポジトリを跨いで調べられ、アクセスとcloneを代行するためローカルの準備が不要
- コマンド実行がサンドボックス内で完結する
- ここまでは他のコーディングエージェントでも実現でき、内容はDevin固有の機能に依存しない
- 決め手は社内にすでに導入済みで、横断調査用の環境を自前で用意・運用せずに始められたこと
■ 3. 準備1: ナレッジベース
- 要望をそのまま投げるだけでは不十分:
- 単一リポジトリで完結する調査なら、Devinはそのままでも十分に働く
- 領域を跨ぐ調査では、どこまで探せば足りたのかをエージェント自身が判断できない
- 登録基準:
- コードから読めるものは登録せず、1つのリポジトリを読むだけでは分からない知識だけを登録する
- 実装の詳細を書き写しても調査の質は上がらず、リプレイスが進む領域ではすぐ古びて足を引っ張る
- 登録する5つの知識:
- 共通点は、実装はコードにあるのに意味づけがどこにも書かれていないこと
- 領域の範囲とリポジトリ一覧は、「この領域は全部でこれだけ」がどこにも書かれていない
- スコープの境界は、管轄が書かれておらず、取り違えると要望が誰にも拾われず宙に浮く
- 横断の波及は、呼び出し関係が呼ぶ側にしか書かれていない
- 本番の前提は、機能フラグの本番値が設定側にあり、実際の分岐が分からない
- 守るべき設計意図は、「あえてリトライしない」理由が二重処理防止だとは書かれていない
- 5つの知識の依存関係:
- 領域の範囲とスコープの境界が土台となり、その上に残り3つが乗る
- 範囲が決まっていないと、エージェントは手元のリポジトリだけを調べて完了だと報告する
- 波及先の全体像がなければ、逆引きの表を書きようがない
- 波及の逆引き登録:
- 波及は呼び出しだけでなく、データ連携を通じて別サービスやその先のキャッシュまで届く
- 「この種の変更はどこへ波及するか」を逆引きできる形で登録する
- 「メール文面の変更だけ」に見える要望が、裏で別システムの改修を呼ぶような隠れた依存をあぶり出す
- 同じリポジトリ内はまず見落とさず、危ないのはその一歩外である
- 分かっていないことの登録:
- 答えではなく問いの形で残す
- 残っているのは、調べれば分かるが優先順位を付けて後回しにしたものばかり
- 書いておかないと、調べていないことと調べて問題がなかったことを区別できない
- 答えはすぐ変わるが、問いはほとんど変わらない
- 登録しないもの:
- テーブル一覧やクエリ全文などの実装詳細は、所在を指すポインタと辿り方の手順だけを残す
- 決済手段の種別や機能フラグの現在値などの流動的な値は、どの設定ファイルにあるかだけを残す
- 工数の人日は何も残さず、算出はプレイブックの仕事とする
- 書き写しの弊害:
- 二重管理になり、コードが変わるとナレッジが取り残される
- 整った古い一覧は、かえって誤った安心を与える
- 古い設定値が残っていると、Devinが古い前提のまま「影響なし」と誤判断しかねない
- 登録方法の振り分け:
- どの経路でも何かは登録し、違いは中身を書くか、所在だけ書くか、問いとして書くかである
■ 4. 確度タグ
- 導入の理由:
- 本来は全内容を実装で裏取りするか、チームで合意してから登録すべきだが、全部は確認しきれなかった
- 本番でどちらの分岐を通るかなど、実装からは確定できないものもある
- 代表的なタグ:
- [実装確認]は、コードを直接読んで確認した事実
- [推測]は、論理的に推論したが実装は未確認のもの
- [要確認]は、人間の確認が必要な不明点
- 実際は設定ファイル由来か、人間と合意した知識かなど、根拠の出所に応じてさらに細分化している
- 記述の形式:
- 1行が1つの事実で、行ごとにタグを付ける
- 確定した事実と未解明のことを、節を分けず同じ粒度でリストに並べ、タグだけで区別する
- 「未確認事項」という別の節にまとめると読み飛ばされる
- 推測の潰し込み:
- 残った推測を一件ずつ実装で裏取りした
- 確認できたものは[実装確認]へ格上げし、確認しきれなければ[要確認]へ格下げした
- この潰し込みで、推測はほとんど残らなくなった
- ナレッジベースの役割:
- タグ導入前は推測と事実が平坦な文章で並び、レビューで何度かヒヤッとした
- 渡した知識の確からしさを、そのままDevinの回答に引き継がせる
- 出力そのものの言い切りを抑えるのは、プレイブックの仕事である
■ 5. 準備2: プレイブック
- プレイブックの構成:
- 調査の進め方と出力フォーマットをテンプレート化し、Devinに毎回守らせる
- 影響調査用と見積もり用の2本に分けた
- 調査の途中で工数の話が混ざると、影響範囲の洗い出しが雑になるため
- 自己反証を強制する指示:
- 最終判断はエンジニアが行い、Devinは判断せず材料を網羅的に提示する
- 「見ていない範囲」を必ず明示させ、誤った安心を与えない
- レポートへの反証を2つ、最も危うい見落としを1つ挙げさせる
- 工数は単一値ではなく、楽観〜悲観のレンジで出させる
- 禁則事項:
- 「〜せよ」より「〜するな」の方が、守られたかを後から確認しやすい
- 推測で埋めず、不明点は「不明」「要確認」と明記させる
- 見ていない範囲やトレードオフ、技術的リスクを隠させない
- 致命傷の見落としリスクがある領域を「問題なし」と断定させない
- 最も恐れているのは「影響なし」という出力であり、断定の禁止が最重要
- 固定チェックリスト:
- 汎用の自己反証だけでは、どこを重点的に疑うべきかがエージェント任せになる
- シニアエンジニアが暗黙にもつ「毎回見る」観点を、固定のチェックリストとして毎回通過させる
- 金銭計算への影響として、税や割引の適用順序が変わらないかを確認する
- 二重処理を防ぐ条件や状態遷移を壊していないかを確認する
- コンプライアンス上のスコープに触れていないかを確認する
- システム間の境界を越えて波及しないかを確認する
- 探索の3観点を並列実行:
- 呼び出し元トレースは、直接・間接の呼び出し元、インタフェース実装、DI経由、イベントハンドラを追う
- 類似コード検出は、同じロジックのコピーや変数名だけ違う類似実装を探す
- データフロー下流は、DB操作、キャッシュ、イベントの下流消費者を追う
- 類似コード検出は地味だが、コピーされた実装の片方だけを直す事故を防げる
- 二段構えの効果:
- ナレッジベースに登録した勘所を、プレイブック側で毎回強制的に再確認させる
- 理解の浅いエージェントや、ドメインに不慣れなレビュアーでもベテランの確認観点を受け取れる
- 出力の型:
- スコープ判定、実現可能性、影響範囲、リスク、工数の手がかり、覆り条件、見ていない範囲の順に固定する
- Devin自身に調査の穴を開示させ、推測を言い切らせないための型である
■ 6. 運用フロー
- 一次調査はDevin、最終判断は人間:
- 要望や検討テーマを受け取る（他部門発でも自部門発でもよい）
- Devinが一次調査し、確度タグ、覆り条件、見ていない範囲を付けて出力する
- エンジニアが見落としや不確実な点を補って検証する
- 「可能」か「条件付き可能」なら回答して意思決定を速め、「不可」なら早期に足切りする
- エンジニアの仕事の変化:
- 各機能の担当への個別の問い合わせをDevinがまとめて肩代わりし、特定の人を介さず調査が回る
- エンジニアの仕事は初動調査から、たたき台のレビューに変わる
- 人手がまるごと消えるわけではなく、浮くのは初動である
- ゼロから全リポジトリを読む代わりに、Devinが挙げた候補の検証に集中できる
- 出力例のポイント:
- 施策の対象条件変更の例では、割引が税計算より前段のため課税対象額が変わる点まで挙がる
- どの項目にも確度タグが付き、最後に覆り条件と見ていない範囲が必ず添えられる
- 見ていない範囲は調査の観点ごとに書かせ、まとめると書きやすい観点だけで終わる
- エンジニアは[要確認]と見ていない範囲を起点に検証へ入れるため、当たりを付けやすい
- 自己申告のタグへの注意:
- 出力のタグにはナレッジ由来のものと、Devinが自分の調査結果へ付けた自己申告が混じる
- そのためレビューでは、特に[実装確認]の裏取りを優先する
■ 7. 工数見積もりの扱い
- 単一の人日を出させない:
- Devinはチームの生産性を把握しておらず、1点で当てにいけば構造的に外れる
- それ以上に、整った数字がそのまま事業の期日として約束されることが危うい
- レンジでの算出:
- 工数を左右する要素を分解させ、工程ごとの重みとバッファを掛けて楽観・標準・悲観のレンジを出させる
- 狙いは精度ではなく、実装以外の工程を毎回思い出させること
- テストとレビューは抜けにくいが、リリース準備、関連チームとの調整、運用手順の更新は抜け落ちがち
- 見積もり例:
- 単位は人日ではなく、実装を1.0とした相対的な作業量とする
- 実装3に対して標準は10.9となり、実装は全体の3割にも届かない
- 悲観が跳ね上がるのは覆り条件を1つ積んだためで、その差分が先に潰すべき不確実性の大きさを示す
- 数字を実際の期日に落とすのはエンジニアの仕事である
- 案の選択は人間:
- 複数案から選ぶのは人間の仕事で、エージェントには推奨する一案だけを深掘りさせる
- 採用理由、トレードオフ、固有のリスクまで調べさせる
- 当初は複数案を出させていたが、一案に絞った方が深く掘れるため外した
- プレイブックも、盛り込みすぎると現場で回らなくなる
■ 8. 効果指標と自動化の線引き
- 指標は仕組みを作る前に決める:
- 後から決めると、都合のよい数字を選んでしまう
- 判定反転率は、エンジニアの検証でDevinの結論が覆った割合を測る
- 規模感レンジ命中率は、実績がDevin起点の見積もりレンジに収まった割合を測る
- 初動リードタイムは、要望の受領から一次回答までの日数を測る
- 主指標は判定反転率:
- 偽陽性はエンジニアが切るだけで済むが、偽陰性は実装後に障害化する致命的な誤り
- スコープ判定や実現可能性を覆す主因はほぼ見落としであり、反転率の高さは見落としの多さを映す
- 反転率を十分に低く保てるかが、本格導入の判断ラインとなる
- 見落とし率による振り返り:
- レビューで追加発見した影響点を全影響点で割り、案件ごとに反転の原因を振り返る
- 全影響点は本来観測できず、エンジニアのレビューを正解とみなした近似にすぎない
- Devinとエンジニアがそろって見落とした影響点は分母に入らず、実際より小さめに出る
- リスク階層による自動化:
- 自部門と判定したスコープ判定は、おおむね低リスクでDevin主導でよい
- 対象外と判定したスコープ判定は、取りこぼしになりうるため人間が確認する
- 一般的な影響調査は、判定反転率が安定したら委譲を広げる
- 高リスク領域の影響調査は、結果によらず人間の検証を必須にする
- レビューが精度の生命線:
- 構造化された調査結果には独特の説得力があり、そのまま信じると探索範囲がDevinの枠組みに縛られる
- するとDevinの見落とし箇所を人間も一緒に見落としかねない
- Devinの出力は確定した結論ではなく「裏取りすべき手がかり」として扱う
- レビューを省いた瞬間に、仕組みはむしろ危ういものになる
■ 9. 導入の順番とコスト
- ナレッジベースが必要な領域:
- 単一リポジトリで完結する領域ならほぼ不要で、プレイブックに禁則事項を数行足すだけで足りる
- 価値が出るのは、リポジトリを跨ぐ波及があり、本番の挙動がコードから確定できない領域
- 推奨する整備順:
- まず領域の範囲と関係リポジトリの一覧を作り、これがないとエージェントは「全部見た」と言えない
- 次に他部門との紛らわしい境目の判定表を作り、管轄の取り違えという最悪の見落としを減らす
- 最後に横断の波及マップを作り、これが一番重く一番効果的である
- 最初の2つは土台であり、それだけでも仕組みは回り始める
- 波及マップは継続的な更新が要るため、誰が維持するかを決めてから着手する
- 構築コスト:
- ドメインに詳しいエンジニアの約3人日をかけた
- 対象リポジトリは15本、ナレッジベースは14ファイル4,107行、プレイブックは2本481行
- 下書きをエージェントに任せ、人間の時間は確度タグ付けと実装での裏取りに充てた
- 実行コスト:
- 一次調査1件は依頼から出力まで5分前後で、消費は1〜2ACU程度
- 準備の3人日と比べ、1件あたりの利用料は桁違いに小さい
■ 10. ナレッジの維持
- 古いナレッジの危険性:
- いま一番の課題はナレッジの更新である
- 古いナレッジはナレッジがない状態より悪く、空欄なら人は調べるが、それらしい記述があれば信じる
- コードは壊れればテストが落ちるが、ナレッジは古くなっても何も起きず、劣化が目立たない
- 定期見直しの失敗:
- 棚卸しの予定を決めても、日々の案件に押されて後回しになり機能しなかった
- 検討中の対策:
- Devinが古い記述に引きずられて間違えたら、棚卸しを待たずその場でナレッジを直す
- 判定反転率の増加は、Devinの問題ではなくナレッジ陳腐化のサインとして検知に使う
- 維持できる量に絞る:
- 量を絞ることが、維持する努力より先に来る
- 登録基準は抜け漏れ防止と同時に、量を抑えて維持コストを下げる線引きでもある
- 書き写さず、値ではなく所在を残し、答えではなく問いで書く形は、更新しなくても腐りにくい
- 人の問題:
- 作った人が異動したら止まる状態のままなら、いずれ誰も信じないドキュメントになる
■ 11. まとめ
- 効果の源泉:
- 効果的だったのはエージェントの性能そのものより、それを取り囲む準備と運用モデルである
- 目指すのは入口の判断で他部門を待たせないことであり、調査の効率化はその手段である
- 要点:
- 知識に付けた確度タグで、確からしさを出力へ引き継ぐ
- プレイブックで自己反証を強制し、断定が独り歩きしないようにする
- 主指標は判定反転率とし、人間の検証を前提にリスク階層ごとに少しずつ自動化する
- 運用上の教訓:
- 整った出力に人間が引きずられ、Devinの見落としを見逃しかけたことが一度ではなかった
- レビューを軽く見た瞬間に崩れる仕組みである
- 今後の展望:
- 現在は自部門だけの取り組みである
- 同じ枠組みを共通フォーマットとして他部門に広げれば、部門を跨いだ影響調査も見えてくる
- 各部門がばらばらの形式で作ると境界で連携できず、横展開の成否はフォーマット統一にかかっている