メインコンテンツへスキップ
見出し画像

Explore agent で改修前事前監査 ─ 「動くだろう」で本番投入を止める仕組み

    「これで動くだろう」で本番に流したら、本番でこけた。ロールバックに 1-2 時間。設計レビューも通したのに、なぜ抜けたんだろう。

    たぶん同じ経験のある人は多いと思う。自分も、つい先日まさにこれをやらかして、Mac OS が panic するところまで行った。

    そこからの教訓で、いまは「改修を本番投入する前に、Explore agent に構造化テンプレで事前監査をさせる」ループを挟んでいる。これを入れてから、本番事故が一回も出ていない。今日はその監査ループの設計の話をする。

    設計レビューを通しても、本番では落ちる

    8 チャンネル並列で月 1200 本動画を出していて、最近、VOICEVOX(音声合成エンジン)を 4 ポート並列起動して N 倍速にする改修をやった。

    設計レビューはちゃんとした。チームの感覚として「これで動くだろう」と全員が思った。本番投入した。15 分後、Mac OS が panic で落ちた。原因は、4 つの VOICEVOX エンジンが共有しているユーザー辞書ファイルへの並列書込で JSON が壊れて、エンジンが全クラッシュ、launchd が無限再起動ループでメモリ枯渇、というやつだった。

    画像
    設計レビュー通過でも本番投入で OS panic、ロールバック1-2時間

    ロールバックに 1 時間半。直してもう一回投入する判断をするまでに、計 3 時間ぶんの可動を失った。月 1200 本ペースだと、これは 5 本ぶんの空き枠に相当する。痛い。

    事故ったあとに振り返って、「設計レビューは何を見ていたのか」と冷静に考えた。並列化のやり方、ポート設計、エンドポイント分散、これは全部レビューしてた。だけど「エンジンが共有している OS リソース」という観点を、誰も見ていなかった。仕様書には載らないからだ。

    「動くだろう」を機械可読な事実検証に置き換える

    そこで、改修案ができた段階で、本番投入の前に Explore agent に監査をかけるループを入れた。Explore agent は、Anthropic の Agent SDK で簡単に作れる、コードベース読取りに特化した子エージェントだ。

    ポイントは、監査の出力を「機械可読な事実検証」にすることだった。「たぶん大丈夫」「リスクはあるかも」みたいな曖昧な所感じゃなくて、コードのどこに何が書いてあるか、共有リソースは何か、ロックの粒度は保護対象と一致しているか、という具体の事実を JSON みたいな形で返させる。

    画像
    監査プロンプトの構造化テンプレ:現状事実+TOP3候補+修正案+Phase判定

    監査プロンプトのテンプレはこんな構造にした。

    1. 現状事実(コード読取り):対象ファイル、関数、変数、共有リソース、ロックの粒度

    2. リスク TOP3 候補:致命/高度/中度の 3 段階で具体的な事故シナリオ

    3. 修正案:各リスクに対するパッチ案(コード差分相当)

    4. Phase 判定:A=即本番OK / B=要修正後本番 / C=設計やり直し

    これを毎回、改修前に Explore agent に投げる。返ってくる JSON 相当のレポートを人間が 5 分で読んで、Phase 判定で本番投入するかどうかを決める。

    TOP3 候補方式が一番効いた

    最初の数回は「リスクを全部挙げてくれ」というプロンプトにしていた。これは失敗だった。Explore agent は素直なので、20 個でも 30 個でもリスクを並べてくる。読むほうの認知が破綻する。「全部対応するのは無理」と判断して、結局どれも対応しない、みたいな最悪の運用になりそうだった。

    そこで「致命/高度/中度の TOP3 だけ返せ」という制約を入れた。これが効いた。Explore agent 側で重要度の順位付けが強制されるので、人間が読むコストが固定化される。3 個なら必ず読める。

    画像
    TOP3 候補方式:致命/高度/中度に絞ってAIに順位付けさせる

    副次効果として、Explore agent 側の出力品質も上がった。3 個に絞ろうとすると、agent 内部で「どれが本当にやばいか」を比較考量するから、出てくる 3 個の質が高い。20 個並べさせていたときは、明らかに埋め草の薄いやつが半分混じっていた。

    これは小さな仕様だけど、自分のなかで結構効いた発見だった。「絞れ」という制約は、agent の精度を上げる。

    Phase A/B/C 判定基準を明文化した

    Phase 判定は、最初は agent に任せた。「あなたの判断で A/B/C を返して」と書いた。これも失敗だった。同じ改修案でも、A と B を行ったり来たりする。判定基準が agent 内部で揺らぐから、出力の再現性が低い。

    そこで、判定基準を明文化してプロンプトに埋めた。

    • Phase A(即本番OK):TOP3 のうち致命ゼロ、高度ゼロ、中度のみ。中度はモニタリングで吸収可能

    • Phase B(要修正後本番):TOP3 に高度が 1 個以上、ただし致命はゼロ。修正案を適用してから本番

    • Phase C(設計やり直し):TOP3 に致命が 1 個以上、または「ロックの粒度が保護対象と一致しない」など根本欠陥

    画像
    Phase A/B/C判定基準を明文化:致命/高度の数で機械的に分岐

    これを入れたら、判定の再現性が一気に上がった。同じ改修案を 2 回連続で監査させても、同じ Phase が返ってくる。判定基準が agent 内部の主観じゃなくて、テンプレ側に書かれた客観基準になっているからだ。

    実例を出すと、VOICEVOX 並列化の追加改修で「ロックの粒度がチャンネル別になっている」という欠陥が見つかった。これは Phase C 判定で返ってきた。理由は明文化した基準の「ロックの粒度が保護対象と一致しない」に該当するから。これが Phase A や B で返ってきていたら、また OS panic を踏んでいた。

    smoke test と監査済み改修フローで本番投入する

    Explore agent には、コード読取りだけじゃなくて smoke test の設計も依頼している。改修案に対して「ユーザーが本番でいちばんよく踏むシナリオを 1 個選んで、それを 30 秒のスクリプトで再現せよ」と頼む。VOICEVOX のときは agent が「異なるチャンネル 2 つを同時に走らせて、同じ user_dict.json に並列書込させる」を選んだ。修正前のコードでは並列書込が走って、修正後のコードでは直列化された。30 秒の検証で、本番投入の安全性が分かる。

    画像
    smoke testでrace再現:30秒で本番投入の安全性を確認

    このやり方の何が嬉しいかというと、人間が「動くだろう」と思っている部分を、agent が機械的に「本当に動くか」を実行で確認してくれる、という点だ。レビューが「読んで考える」から「動かして確かめる」に変わる。

    いまは、改修案を本番投入する前のフローがこう変わっている。

    1. 改修案ドラフトを書く(本人 or 試作 agent)

    2. Explore agent に構造化テンプレで監査依頼

    3. 現状事実 + TOP3 + 修正案 + Phase 判定が返ってくる(5-10 分)

    4. Phase A なら即本番、B なら修正適用後に本番、C なら設計やり直し

    5. agent が smoke test を走らせて race 検証

    6. 本番投入

    画像
    監査済み改修フロー:agent監査→Phase判定→smoke test→本番投入

    これを入れてから、本番事故がゼロになった。改修前監査で発見できた欠陥は、直近で 5 個。うち 2 個は致命級で、Phase C 判定で本番投入を止めた。残り 3 個は Phase B で修正してから投入した。1 個でも本番に流れていたら、たぶんまた OS panic していたと思う。

    監査自体のコストは、1 改修あたり Explore agent の API 呼出 5-10 分、人間の読み込み 5 分、計 15 分弱。これでロールバック作業 1-2 時間 + 失った可動枠を毎回防げるなら、ROI として完全に黒字だ。

    最後に 1 個書いておくと、監査 agent そのものにも「本番コードを書き換えない」という security 制約を明示している。Explore agent は読み取り専用ツール(Read/Grep/Glob)しか持たせず、書込ツールは渡さない。監査の途中で「ついでに直してみました」が起きると、それが新しい事故の温床になるからだ。改修と監査は分離する。試作する人(prototyper)と監査する人(Explore agent)は、別々の権限で別々のスコープで動かす、というのが、自分のなかで固まった原則だ。

    このあたりの監査プロンプトテンプレや、Phase A/B/C の具体基準、smoke test 設計の依頼の仕方は、別記事で 1 個ずつ深掘りします。事故ベースで生まれたテンプレなので、由来から書きます。

    設計テンプレをプレゼントします

    改修前監査の構造化テンプレと、Explore agent の監査依頼プロンプトを PDF にまとめました。実際に自分のところで動いているものの抜粋です。明日から自分の改修フローに乗せられます。

    画像
    設計テンプレを受け取る

    公式 LINE に登録してくれた方にお送りします。

    公式 LINE に登録する

    法人のご相談はこちら

    自社の AI 開発フローに監査ループを組み込みたい、Claude Code 運用を支援してほしい、というご相談は、別途お受けしています。

    画像
    法人のお問い合わせはこちら

    あなたへのおすすめ