斜めから見たカラフルなコードのプログラミング画面
設計と運用

Claude Code v2.1.328のhooksでCI品質ゲートを止める方法

目次を見る

CI/CDパイプラインにClaude Code(Anthropic製のターミナル常駐型AIコーディングエージェント)を組み込んでいるチームに向けた内容です。自動化フローにAIエージェントを混ぜると、失敗時にどこで処理を止めるかが曖昧になりがちです。v2.1.328で追加された挙動を手掛かりに、品質ゲートの作り方を整理します。

今回のリリースの中心はmcp_toolフック(Claude Codeが外部ツールを呼ぶ際に発火する検査処理)に"onFailure": "block"オプションが追加された点です。MCP(Model Context Protocol、AIモデルと外部ツールを繋ぐ標準規格)経由のツール呼び出しも、コマンドフックやHTTPフックと同じように「検査が失敗したらアクションごと止める」挙動を選べるようになりました。CI/CDパイプラインでAIエージェントの出力をゲートにしたいテスト担当者にとって、見逃せない変更です。

この手順でできるようになること

Claude Codeのhooks機能を使い、MCPツール呼び出しの前後に品質チェックを挟んで、チェックが失敗したら処理を強制停止する設定を組みます。

あわせて、OpenTelemetry(分散トレーシングやメトリクス収集の業界標準規格)のエクスポート設定漏れを検知する新しい警告表示の確認方法も扱います。CIログの品質メトリクスが実は送信されていなかった、という事故を防ぐための確認ポイントです。

前提条件

  • Claude Code v2.1.328以降(claude --versionで確認)
  • MCPサーバーを1つ以上接続済みであること(.mcp.jsonまたはclaude mcp listで確認可能)
  • フックを記述するsettings.jsonへの書き込み権限
  • CI環境でOpenTelemetryエクスポーターを使う場合は、エンドポイントのURLと認証情報

バージョンが古い場合は、リリースノートの該当バージョン以降にアップデートしてから進めてください。

フック設定ファイルの場所を確認する

まずsettings.jsonの場所を把握します。プロジェクト単位・ユーザー単位どちらにも置けます。

claude doctor

claude doctorを実行すると、読み込まれている設定ファイルのパスと、現在の構成に警告があるかどうかが一覧表示されます。v2.1.328からは、OpenTelemetryエクスポーターにエンドポイントが設定されていない場合、ここに通知が出るようになりました。品質メトリクスをCIダッシュボードに送っているつもりが実は未送信だった、というケースをこの時点で発見できます。

mcp_toolフックにblockを設定する

次に、MCPツール呼び出しを監視するフックを定義します。例として、MCP経由でテスト実行ツールを呼ぶ前にリンターを走らせ、失敗したら呼び出し自体をブロックする設定です。

hooks:
  mcp_tool:
    - matcher: "*"
      hooks:
        - type: command
          command: "npm run lint:check"
          onFailure: "block"

ここでのonFailure: "block"が今回追加された挙動です。これまでコマンドフックやHTTPフックでは失敗時にブロックできましたが、MCPツール向けのフックは同じ制御ができていませんでした。CIパイプラインの途中でAIエージェントが外部のテストランナーやデプロイツールをMCP経由で呼ぶ構成を組んでいる場合、品質チェックに失敗したツール呼び出しがそのまま実行されてしまうリスクがあったわけです。

権限プロンプトをスキップするセッションの扱いを確認する

CIの自動実行では、権限確認を都度求められると処理が止まってしまうため、権限プロンプトをスキップするモードで動かすケースが多いはずです。v2.1.328では、こうしたセッションからのメッセージがクラウド側のセッションで保留・破棄される可能性がある場合に警告が出るようになりました。

claude -p --permission-mode bypassPermissions "run the test suite and report coverage"

このコマンドを実行した際、ターミナルに保留・破棄の警告が表示されたら、CIのログ出力先やクラウドゲートウェイ側の設定を見直すサインです。テスト結果のレポートがパイプラインの途中で欠落する原因になり得ます。

動作確認の方法

設定したblockフックが機能しているかは、意図的に失敗するコマンドで検証します。

npm run lint:check -- --force-fail

このように失敗を強制した状態でMCPツール呼び出しを含むセッションを実行し、ツール呼び出しがブロックされてエラー終了することを確認します。あわせて/statusコマンドをセッション中に実行し、OpenTelemetryのエンドポイント警告が出ていないかも合わせて見ておくと安心です。

ハマりやすいポイント

onFailureの設定はフックの種類ごとに別々に書く必要があります。コマンドフックでblockを設定していても、同じsettings.json内でMCPツールフックの設定を書き忘れると、そちらは従来通り素通りしてしまいます。

mcp_tool・command・httpの3種類のフックそれぞれにonFailureを明示したか、settings.jsonを見直して確認してください。

特にMCP経由でデプロイ系のツールを呼んでいる構成では、ここを見落とすとリンターやテストの失敗を無視したままデプロイが進んでしまいます。CIのYAMLレビュー時に、hooks定義のセクションだけでも目を通すチェックリストに加えておくと見落としを防げます。

導入前に確認すること

今回の変更を自分のパイプラインに取り入れる前に、次の3点を確認しておくと手戻りが減ります。

  • claude --versionでv2.1.328以降か確認し、古ければアップデートする
  • MCPツールを使っているフローがあるか、.mcp.jsonの有無で判断する
  • claude doctorでOpenTelemetryのエンドポイント警告が出ていないか確認する

MCPを使っていない構成であれば、今回のonFailure: "block"拡張はそのまま恩恵がありません。一方でコマンドフックやHTTPフックだけで品質ゲートを組んでいる場合も、将来MCPツールを追加する際にこの挙動差を知っておくと設計がぶれずに済みます。

参考

claude-code v2.1.328

AI 駆動開発のご相談は forva AI へ。

まずはお気軽にどうぞ。