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

AIが壊したCIを直し続けるのをやめて、Agent hookで予防する

    CircleCI Japan Field Engineerの岡本です。

    コーディングエージェントに実装からコミット、pushまで任せていると、CIが落ちるたびに失敗ログを貼って直させ、通ったら次の実装に進み、しばらくするとまた落ちる、という往復が続きます。一往復は数分で、トークン代もたいした額ではありません。ただ、回数が多く、CIの様子を見ながら付き添うコマンドで捌いたとしても、捌いた分のトークンと時間は払っています。

    画像
    https://chunk.ai/

    Claude CodeのStop hookからChunk sidecarで検証を呼ぶと、手元のテストでは見えない環境の差による失敗も、pushする前にエージェントのターンの中で受け取れます。ただし、chunk initが書き出すhookのままでは検証が手元で走り、sidecarは使われません。個人の開発環境でこの構成にしたときの手順と、つまずいた点を書きます。

    失敗が返ってくるまでの距離


    画像

    手元で書いて試す内側のループと、pushしたあとにCIが検証する外側のループのうち、エージェントで速くなるのは内側のほうで、外側の速さは変わりません。そのため、検証されていない変更が外側へ流れ込む量が増えます。この切れ目は「AIで速く書けるのに出荷が増えないのは、つくり過ぎのムダだから」でも書きました。The 2026 State of Software Deliveryでは、中央値のチームでfeatureブランチのスループットが15%増えた一方、mainブランチは7%減っています。mainブランチのワークフローの成功率も70.8%まで下がり、この5年あまりで最も低い値でした。

    このとき費用を左右するのは、失敗が起きることよりも、失敗を知るタイミングです。エージェントがまだそのコードを覚えているうちに失敗が返ってくれば、修正は数往復で終わります。CIから返ってくる頃にはターンが閉じているので、何を書いたかを思い出させるところから始まり、同じ失敗でも直す費用が上がります。CIの実行時間を削ってもこの支出が減らないのはそのためで、縮めたいのは失敗が返ってくるまでの距離のほうです。

    失敗をターンの中で受け取る

    Claude Codeのhookは、セッションの決まった時点でシェルコマンドを自動実行する仕組みです。CIの失敗を手元で受け取るのに使えるイベントは、PreToolUseとStopの2つです。
    PreToolUseはツールを呼び出す直前に走り、exit 2で返すとその呼び出しがブロックされ、stderrに書いた内容がブロックの理由としてエージェントに届きます。エージェントがgit commitを実行しようとした時点でテストを走らせ、落ちたらコミットさせない、という使い方です。もう1つのStopは、エージェントが応答を終えようとしたときに走るイベントで、exit 2で返すとターンが終わらずに続きます。テストが通るまで終わらせない、という使い方です。

    自分でhookを書くときに外しやすいのが終了コードです。Unixの慣習どおり失敗をexit 1で返すと、ゲートは効きません。公式ドキュメントでは、exit 2以外の非ゼロはnon-blocking error(処理が続くエラー)の扱いで、警告は出てもツールの呼び出しやターンの終了はそのまま進むと書かれています。PostToolUseのように、ツールが実行されたあとに走るイベントはexit 2でも止められないので、どのイベントに書くかも確かめておいてください。

    hookのスクリプトが見つからないときの終了コードにも注意が必要です。bashで起動するスクリプトのパスを打ち間違えると、終了コードは127になってnon-blocking errorとして扱われ、ゲートは何も言わずに外れます。逆にpython3は、ファイルを開けないときに2を返します。そのためPreToolUseでは、スクリプトが無いだけでブロックとなり、すべてのツール呼び出しが止まります。こちらの事故は「Claude CodeのHookを相対パスで書くと、cdコマンドで詰む」に書きました。どちらの場合も、hookを書いた直後にわざと落ちる変更を入れて、期待どおりに止まるかを見ておくのが確実です。

    イベントの一覧や書き方は、日本語でも「Claude Code hooksでAIエージェントの暴走を"仕組み"で止める5レシピ」のような解説があり、exit codeの罠にも触れています。

    それでもCIは落ちる

    hookを手元のテストにつなぐと、素朴なミスはターンの中で直ります。それでも、CIが落ちなくなるわけではありません。

    残るのは環境の差です。分かりやすいのは依存関係で、npm installはlockファイルとのずれを飲み込んで進みますが、CIで使うnpm ciはlockファイルを厳密な正とするので、そこで初めて落ちます。手元でnpm testを何回走らせても、この失敗は出てきません。以前Qiitaに書いた例がまさにこれで、ローカルではすべて通ったのに、CIのインストールステップで落ちていました。macOSでは通ってLinuxでは落ちるテストや、キャッシュがあれば通ってクリーンインストールでは落ちるビルドも同じで、手元の環境で走らせている限り、hookをどう書いても見えません。

    そのため、CIと同じ環境で、pushせずに検証を走らせる手段が要ります。

    CIと同じ環境を、pushせずに呼ぶ

    Chunk sidecarは、CIの環境を模したLinuxのmicroVMです。chunk sidecar syncは.gitignoreで除外したもの以外の作業ツリーをそのまま転送するので、コミットしていない変更を含めて同期でき、commit、push、pull requestのどれもせずに検証できます。

    brew install CircleCI-Public/circleci/chunk
    chunk auth login   # ブラウザで認証する。パーソナル API トークンなら chunk auth set circleci
    chunk init         # スタックを検出して .chunk/config.json を作る

    chunk initは、検出した検証コマンド(Node.jsならnpm ciとnpm testなど)を.chunk/config.jsonに書きます。chunk validateは、この検証コマンドを手元で実行するコマンドです。--remoteを付けると、sidecarに作業ツリーを同期してから、そこで実行します。

    hookまわりの挙動は、執筆時点でバージョンによって異なります。最新リリースのv0.7.224までのchunk initは、.claude/settings.jsonにPreToolUseとStopのhookも書き出す作りです。hookから呼ばれたchunk validateは、失敗するとexit 2を返して3回までターンを続けさせます。ただ、書き出されるStop hookはリモート実行のオプションを付けずにchunk validateを呼ぶので、そのままでは検証が手元で走ります。一方、chunk initがエージェント向けのhookを書かなくなる変更(#888)は、chunk-cliのmainブランチにマージ済みです。この変更のあと、chunk validateは失敗するとexit 1を返すため、Stop hookから直接呼んでもターンが続きません。

    どちらのバージョンでも同じように動かすには、Stop hookを自分で書き、失敗をexit 2に変えるのが確実です。手元のchunk 0.7.203で、検証コマンドが失敗したときにstop-validate.shがexit 2で終わることを確かめました。

    #!/usr/bin/env bash
    # .claude/hooks/stop-validate.sh
    cd "$CLAUDE_PROJECT_DIR" || exit 2
    # 検証の出力を stderr に流し、失敗したら exit 2 でターンを続けさせる
    chunk validate --remote </dev/null >&2 || exit 2

    このスクリプトを、.claude/settings.jsonのStop hookとして登録します。

    {
      "hooks": {
        "Stop": [
          {
            "hooks": [
              {
                "type": "command",
                "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/stop-validate.sh\"",
                "timeout": 600
              }
            ]
          }
        ]
      }
    }

    0.7系のchunk validateは、hookの入力を受け取ると独自の回数で判定します。スクリプトでは標準入力を/dev/nullにしてこの判定を外し、どのバージョンでも終了コードだけで動くようにしました。0.7系のchunk initがStop hookを書き出していた場合は、上の設定に置き換えてください。検証が落ち続けた場合、Claude CodeはStop hookによる続行が8回続いた時点でターンを終わらせます。それより手前で止めたいときは、Stop hookの入力にあるstop_hook_active(Stop hookによってすでに続行しているときtrue)を見て、続行は1回までにするなどの上限を足してください。

    2回目以降の待ち時間を減らすのがsnapshotです。依存関係を入れ終わったsidecarでsnapshotを作ると、その状態がイメージとして保存されます。

    chunk sidecar snapshot create --name my-env

    イメージは.chunk/config.jsonに記録され、以降のsidecarはそのイメージから起動します。保存元のsidecarは削除されるので、作業中のsidecarで実行するときは注意してください。

    chunk validateはただのCLIなので、Claude Code以外のエージェントでも、ターンの終わりに走るhookがあれば同じように呼べます。

    動いているかは、わざと失敗させて確かめる

    導入後、sidecarを入れた個人開発の6プロジェクトで、CIの成功率を前後2週間ずつ比べました。ところが、sidecarを入れていないプロジェクトも同じ期間に成功率が上がっていて(org全体で89.1%から96.4%)、sidecarの効果は取り出せませんでした。sidecar上で検証が何回走って何回通ったかはCircleCIのusageデータに記録されないので、この比べ方ではもともと確かめようがありません。

    hookが期待どおりに動いているかどうかは、成功率を見なくても、わざと落ちる変更を入れれば確かめられます。CIで落ちるものが手元でも落ちてターンが続けば、エージェントは自分の失敗をターンの中で受け取れています。

    Chunk sidecarは執筆時点で無料プランを含むすべてのCircleCIのプランで使え、sidecarの利用料も今はかかりません(課金を始める前に告知するとされています)。ただし、上に書いたとおりhookまわりの仕様は変わり続けているので、最新はchunk-cliのリポジトリとChunkの製品ページで確認してください。

    試すなら、次の順番が早いはずです。

    1. Stop hookにテストコマンドを1つつなぎ、わざと落ちる変更でターンが続くのを確かめる(exit 2で返す。exit 1ではターンがそのまま終わります)

    2. それでもCIで落ちるものが出たら、環境の差を疑う

    3. 環境の差なら、chunk initしてStop hookからchunk validate --remoteを呼ぶ

    4. sidecarの準備を待つ時間が長いと感じたら、snapshotを作る


     
     
    開発の質と速度を底上げしよう!世界中のエンジニアが愛用する CI/CD ツール「CircleCI」の公式アカウントから日本語で最新情報をお届けします。 最新イベント・ミートアップ情報はこちら: http://circleci.connpass.com

    あなたへのおすすめ