⟐ Claude Code/2026-04-01上級

Claude Code HTTP Hooks × GitHub Actions 完全統合ガイド — 自動コードレビュー・テスト・デプロイを実現する本番設計パターン

Claude Code の HTTP Hooks を GitHub Actions と統合し、自動コードレビュー・品質チェック・デプロイまでを一気通貫で自動化する本番設計パターンを詳細なコード付きで解説します。

Claude Code²⁶⁵HTTP HooksGitHub Actions¹² CI/CD¹⁹ 自動化⁸⁷ コードレビュー⁵ DevOps³

✦ プレミアム記事

HTTP Hooks が変える開発ワークフロー

Claude Code のフック機能は、AIエージェントの動作を外部システムと連携させるための強力な仕組みです。中でも HTTP Hooks は、ローカルスクリプト（stdio hooks）では実現できなかった「クラウドネイティブな自動化」を可能にします。

GitHub Actions をはじめとする CI/CD パイプラインと HTTP Hooks を組み合わせることで、次のようなワークフローが実現できます。

プルリクエストが作成された瞬間、Claude Code が自動でコードレビューを実施
コミットのたびにセキュリティスキャンと品質チェックが走る
テスト失敗時に Claude Code が原因を特定して修正案を提示
ステージング環境へのデプロイ後、Claude Code が回帰テストを自動実行

本記事は、これらのパターンを本番環境で運用できるレベルの実装として解説します。stdio hooks や基本的な CI/CD の知識があることを前提に、HTTP Hooks 特有の設計上の注意点や実装パターンに踏み込んで説明していきます。

HTTP Hooks のアーキテクチャを理解する

stdio hooks との根本的な違い

Claude Code のフックには 2 種類あります。

stdio hooks: ローカルプロセスとして動作し、JSON を標準入出力でやりとりする
HTTP hooks: 指定した URL（Webhook エンドポイント）に JSON を POST し、レスポンスを受け取る

Claude Code Hooks と自動化の基本ガイドでは stdio hooks の基礎を解説していますが、HTTP Hooks はそこから一歩進んで外部サービスとのリアルタイム統合を可能にします。

Claude Code のフック実行フロー（HTTP Hooks）

[Claude Code] -- JSON payload --> [HTTP エンドポイント]
                                         |
                              [外部サービスへの連携]
                              (GitHub / Slack / Jira など)
                                         |
                              [レスポンス JSON] --> [Claude Code が判断]

フックイベントの種類と使い分け

HTTP Hooks で受信できるイベントは次の通りです。

PreToolUse: ツール実行前（ファイル書き込みや bash コマンドの前）
PostToolUse: ツール実行後（結果を受けて追加処理）
Notification: Claude からの通知（長いタスクの進捗報告など）
Stop: Claude がセッションを停止した際
SubagentStop: サブエージェントが停止した際

CI/CD 統合で特に重要なのは PostToolUse と Stop です。PostToolUse でファイル変更を検知してリアルタイムに品質チェックを走らせ、Stop でレポートをまとめて GitHub に投稿する、という使い方が実践的です。

CLAUDE.md による HTTP Hooks の設定

HTTP Hooks の設定は CLAUDE.md または .claude/settings.json で行います。

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "http",
            "url": "https://your-webhook-server.example.com/hooks/file-changed",
            "method": "POST",
            "headers": {
              "Authorization": "Bearer ${CLAUDE_HOOK_SECRET}",
              "Content-Type": "application/json"
            },
            "timeout": 10000
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://your-webhook-server.example.com/hooks/session-complete",
            "method": "POST",
            "headers": {
              "Authorization": "Bearer ${CLAUDE_HOOK_SECRET}",
              "Content-Type": "application/json"
            },
            "timeout": 30000
          }
        ]
      }
    ]
  }
}

${CLAUDE_HOOK_SECRET} のような環境変数展開は Claude Code が自動で行います。ローカル環境では .env ファイルに、CI 環境では GitHub Actions の Secrets に定義します。

✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること

✦HTTP Hooks のアーキテクチャを理解し、GitHub Actions との双方向連携を実装できる

✦コードレビュー・テスト・デプロイを Claude Code で自動化する本番グレードのパイプライン設計を習得できる

✦セキュリティ・認証・エラーリトライを含む堅牢な Webhook サーバーの構築パターンを習得できる

Stripe による安全な決済 · いつでもキャンセル可能

✦

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または

メンバーシップなら全記事が読み放題 →

Webhook サーバーの設計と実装

本番グレードの Webhook サーバー（Node.js / Hono）

Webhook を受信するサーバーは、セキュリティ・信頼性・スケーラビリティを考慮して設計する必要があります。ここでは Hono（Cloudflare Workers 対応の軽量フレームワーク）を使った実装を紹介します。

// webhook-server/src/index.ts
import { Hono } from "hono";
import { cors } from "hono/cors";
import { bearerAuth } from "hono/bearer-auth";
import { Octokit } from "@octokit/rest";
 
type Bindings = {
  CLAUDE_HOOK_SECRET: string;
  GITHUB_TOKEN: string;
  REPO_OWNER: string;
  REPO_NAME: string;
};
 
const app = new Hono<{ Bindings: Bindings }>();
 
// CORS設定（必要な場合のみ）
app.use("*", cors({ origin: "https://claude.ai" }));
 
// ─── ファイル変更フック ───────────────────────────────────
app.post("/hooks/file-changed", bearerAuth({ token: (c) => c.env.CLAUDE_HOOK_SECRET }), async (c) => {
  const payload = await c.req.json();
 
  // ペイロードの型チェック
  const { tool_name, tool_input, tool_response, session_id } = payload;
  if (!tool_name || !session_id) {
    return c.json({ error: "Invalid payload" }, 400);
  }
 
  // 変更されたファイルパスを取得
  const filePath: string = tool_input?.path || tool_input?.file_path || "";
  const content: string = tool_response?.content || "";
 
  // .ts / .tsx ファイルの変更のみ処理
  if (!filePath.match(/\.(ts|tsx|js|jsx)$/)) {
    return c.json({ decision: "proceed", message: "Non-JS file, skipping check" });
  }
 
  // 簡易品質チェック（本番ではより高度なチェックを実装）
  const issues: string[] = [];
 
  // console.log の検出
  if (content.includes("console.log(")) {
    issues.push("⚠️ console.log が残っています");
  }
  // TODO コメントの検出
  const todoCount = (content.match(/\/\/ TODO/g) || []).length;
  if (todoCount > 3) {
    issues.push(`⚠️ TODO コメントが ${todoCount} 個あります`);
  }
  // ハードコードされたシークレットの簡易検出
  if (content.match(/["']([A-Za-z0-9+/]{40,})["']/)) {
    issues.push("🚨 ハードコードされたシークレットの可能性があります");
  }
 
  if (issues.length > 0) {
    return c.json({
      decision: "block",
      reason: `コード品質の問題を検出しました:\n${issues.join("\n")}`,
    });
  }
 
  return c.json({ decision: "proceed" });
});
 
// ─── セッション完了フック ──────────────────────────────────
app.post("/hooks/session-complete", bearerAuth({ token: (c) => c.env.CLAUDE_HOOK_SECRET }), async (c) => {
  const payload = await c.req.json();
  const { session_id, transcript_path } = payload;
 
  // GitHub PR へのコメント投稿（PR番号は環境変数経由）
  const prNumber = parseInt(process.env.GITHUB_PR_NUMBER || "0");
  if (prNumber > 0) {
    const octokit = new Octokit({ auth: c.env.GITHUB_TOKEN });
    await octokit.issues.createComment({
      owner: c.env.REPO_OWNER,
      repo: c.env.REPO_NAME,
      issue_number: prNumber,
      body: `## 🤖 Claude Code レビュー完了\n\nセッション ID: \`${session_id}\`\n\n自動レビューが完了しました。詳細はトランスクリプトを確認してください。`,
    });
  }
 
  return c.json({ success: true });
});
 
export default app;

decision フィールドによる Claude Code の制御

HTTP Hooks のレスポンスに decision フィールドを含めることで、Claude Code の動作を制御できます。

"proceed": 処理を続行する（デフォルト）
"block": ツールの実行をブロックし、reason の内容を Claude に伝える
"approve": 確認プロンプトを自動承認する

"block" を返すとそのツール呼び出しはキャンセルされ、reason に記載した内容が Claude のコンテキストに注入されます。Claude はその理由を見て対処方法を判断します。これにより、AI 自身が品質基準を理解しながら修正を繰り返すという高度なフィードバックループを作ることができます。

GitHub Actions との統合パターン

パターン 1：PR 作成時に Claude Code が自動コードレビューを実施

このパターンでは、PR が作成・更新されたときに GitHub Actions が Claude Code を起動し、レビュー結果を PR コメントとして投稿します。

# .github/workflows/claude-code-review.yml
name: Claude Code Review
 
on:
  pull_request:
    types: [opened, synchronize]
 
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
 
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
 
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "22"
 
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
 
      - name: Get changed files
        id: changed-files
        run: |
          CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | head -20)
          echo "files<<EOF" >> $GITHUB_OUTPUT
          echo "$CHANGED" >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT
 
      - name: Run Claude Code review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          CLAUDE_HOOK_SECRET: ${{ secrets.CLAUDE_HOOK_SECRET }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITHUB_PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          # レビュー対象ファイルのリストを生成
          CHANGED_FILES="${{ steps.changed-files.outputs.files }}"
 
          # Claude Code によるレビュー実行（HTTP Hooks 付き）
          claude --dangerously-skip-permissions \
            --print \
            --settings .claude/settings.json \
            "以下の変更されたファイルをコードレビューしてください。
            バグ・セキュリティ問題・パフォーマンス問題・コーディング規約違反を重点的に確認し、
            改善点を具体的に指摘してください。
 
            変更ファイル:
            $CHANGED_FILES
 
            レビュー完了後、github_pr_comment ツールを使って結果をPRに投稿してください。" \
            2>&1 | tee review-output.txt
 
      - name: Post review results
        if: always()
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const output = fs.readFileSync('review-output.txt', 'utf8').slice(-3000);
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## 🤖 Claude Code 自動レビュー\n\n\`\`\`\n${output}\n\`\`\``
            });

パターン 2：テスト失敗時に Claude Code が自動修正を提案

CI でテストが失敗したとき、Claude Code がエラーログを解析して修正案を PR に投稿します。

# .github/workflows/claude-auto-fix.yml
name: Claude Code Auto Fix
 
on:
  workflow_run:
    workflows: ["Tests"]
    types: [completed]
 
jobs:
  auto-fix:
    if: github.event.workflow_run.conclusion == 'failure'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      issues: write
 
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      - name: Download test logs
        uses: actions/download-artifact@v4
        with:
          name: test-results
          run-id: ${{ github.event.workflow_run.id }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
 
      - name: Analyze failures with Claude Code
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          CLAUDE_HOOK_SECRET: ${{ secrets.CLAUDE_HOOK_SECRET }}
        run: |
          TEST_LOG=$(cat test-results.txt 2>/dev/null || echo "テストログを取得できませんでした")
 
          claude --dangerously-skip-permissions \
            --print \
            "以下のテスト失敗ログを解析してください。
 
            ===テストログ===
            $TEST_LOG
            ===
 
            1. 失敗の根本原因を特定してください
            2. 修正方法を具体的に説明してください
            3. 可能であれば修正コードのスニペットを提示してください
 
            回答は GitHub の PR コメントとして読みやすいマークダウン形式で出力してください。" \
            > fix-suggestion.txt 2>&1
 
      - name: Post fix suggestion
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const suggestion = fs.readFileSync('fix-suggestion.txt', 'utf8');
 
            // 最初のオープンな PR を探す
            const prs = await github.rest.pulls.list({
              owner: context.repo.owner,
              repo: context.repo.repo,
              state: 'open',
              head: context.ref
            });
 
            if (prs.data.length > 0) {
              await github.rest.issues.createComment({
                issue_number: prs.data[0].number,
                owner: context.repo.owner,
                repo: context.repo.repo,
                body: `## 🔧 Claude Code テスト失敗分析\n\n${suggestion}`
              });
            }

パターン 3：Semantic Versioning を Claude Code が自動判断

コミットメッセージや変更内容から、Claude Code がセマンティックバージョンのバンプ種別（patch / minor / major）を判断します。

# .github/workflows/claude-version-bump.yml
name: Claude Code Version Bump
 
on:
  push:
    branches: [main]
 
jobs:
  version-bump:
    runs-on: ubuntu-latest
    permissions:
      contents: write
 
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 10
          token: ${{ secrets.GITHUB_TOKEN }}
 
      - name: Determine version bump
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          COMMITS=$(git log --oneline -10)
          DIFF=$(git diff HEAD~5..HEAD --stat)
 
          BUMP_TYPE=$(claude --dangerously-skip-permissions --print \
            "以下のコミット履歴と差分から、セマンティックバージョニングに基づいて
            バージョンバンプの種別を判断してください。
            必ず 'patch', 'minor', 'major' のいずれか1語だけを出力してください。
 
            ルール:
            - 破壊的変更（Breaking Change）→ major
            - 新機能追加（後方互換あり）→ minor
            - バグ修正・リファクタリング → patch
 
            コミット履歴:
            $COMMITS
 
            変更ファイル統計:
            $DIFF" 2>&1 | tr -d '[:space:]')
 
          # 想定外の出力の場合はデフォルトを patch に
          if [[ "$BUMP_TYPE" != "patch" && "$BUMP_TYPE" != "minor" && "$BUMP_TYPE" != "major" ]]; then
            BUMP_TYPE="patch"
          fi
 
          echo "BUMP_TYPE=$BUMP_TYPE" >> $GITHUB_ENV
          echo "決定されたバージョンバンプ: $BUMP_TYPE"
 
      - name: Bump version
        run: |
          npm version ${{ env.BUMP_TYPE }} --no-git-tag-version
          git config user.email "bot@example.com"
          git config user.name "Claude Code Bot"
          git add package.json package-lock.json
          git commit -m "chore: bump version [${{ env.BUMP_TYPE }}] by Claude Code"
          git push

セキュリティ設計：本番運用で押さえるべき要点

認証と認可

HTTP Hooks のエンドポイントは外部から到達可能である必要がありますが、誰でもリクエストを送れる状態は危険です。以下の多層防御が重要です。

Bearer Token 認証（最低限）

// Webhook ペイロードを受信する前にトークンを検証
const authHeader = request.headers.get("Authorization");
if (!authHeader || authHeader !== `Bearer ${env.CLAUDE_HOOK_SECRET}`) {
  return new Response("Unauthorized", { status: 401 });
}

HMAC 署名検証（より堅牢）

import { createHmac, timingSafeEqual } from "crypto";
 
function verifyHmacSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const hmac = createHmac("sha256", secret);
  hmac.update(payload);
  const expected = `sha256=${hmac.digest("hex")}`;
  // タイミング攻撃を防ぐため timingSafeEqual を使用
  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}
 
// 使用例
const signature = request.headers.get("X-Claude-Signature") || "";
const body = await request.text();
if (!verifyHmacSignature(body, signature, env.CLAUDE_HOOK_SECRET)) {
  return new Response("Invalid signature", { status: 401 });
}

IP アドレス制限

Claude Code を実行する CI 環境の IP 範囲が既知であれば、ファイアウォールレベルで制限を加えます。GitHub Actions のランナー IP レンジは GitHub のメタ API から取得できます。

シークレット管理

HTTP Hooks の設定ファイルに直接シークレットを書かないでください。

// ✅ 正しい：環境変数を参照
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "http",
            "url": "${WEBHOOK_URL}",
            "headers": {
              "Authorization": "Bearer ${CLAUDE_HOOK_SECRET}"
            }
          }
        ]
      }
    ]
  }
}

// ❌ 誤り：シークレットをハードコード（GitHub Secret Scanning に検出される）
{
  "headers": {
    "Authorization": "Bearer YOUR_SECRET_TOKEN_HERE"
  }
}

CI/CD 環境では、シークレットは必ず GitHub Actions の Secrets（secrets.CLAUDE_HOOK_SECRET）または AWS Secrets Manager / GCP Secret Manager などのマネージドサービスに保管してください。

高度なパターン：Claude Code のフィードバックループ設計

Block → Rewrite → Verify のループ

最も強力な HTTP Hooks の活用パターンは、Claude Code が自ら品質チェックを通過するまでコードを書き直す自律的なループです。

[Claude Code がファイルを書く]
         ↓
[PostToolUse HTTP Hook 発火]
         ↓
[Webhook サーバーが品質チェック実行]
         ↓
  問題あり → decision: "block" + reason 返却
         ↓
[Claude Code が reason を受けて修正]
         ↓
[再度ファイルを書く → フック発火 → チェック...]
         ↓
  問題なし → decision: "proceed" 返却
         ↓
[Claude Code が次のステップへ進む]

この設計のポイントは、品質基準をコードではなく Webhook サーバーのロジックに集約することです。Claude Code は「何が問題か」を reason から学習し、自律的に対処します。

// 高度な品質チェック例：ESLint + TypeScript 型チェック
async function runQualityCheck(filePath: string, content: string): Promise<{
  pass: boolean;
  issues: string[];
}> {
  const issues: string[] = [];
 
  // 1. ESLint チェック（メモリ上で実行）
  const eslintResult = await runEslint(content, filePath);
  if (eslintResult.errorCount > 0) {
    eslintResult.messages
      .filter((m) => m.severity === 2)
      .forEach((m) => issues.push(`ESLint エラー (L${m.line}): ${m.message}`));
  }
 
  // 2. TypeScript 型チェック（incremental）
  const tsResult = await runTsc(filePath, content);
  if (tsResult.errors.length > 0) {
    tsResult.errors
      .slice(0, 3) // 最大3件まで返す（過多なフィードバックを防ぐ）
      .forEach((e) => issues.push(`TypeScript エラー: ${e.messageText}`));
  }
 
  // 3. セキュリティパターンチェック
  const securityIssues = checkSecurityPatterns(content);
  issues.push(...securityIssues);
 
  return { pass: issues.length === 0, issues };
}

Notification フックによる Slack 通知連携

長時間のタスク実行中、進捗を Slack に投稿することでチーム全体がリアルタイムで状況を把握できます。

// Notification フックのハンドラー
app.post("/hooks/notification", bearerAuth(...), async (c) => {
  const { message, session_id } = await c.req.json();
 
  // Slack の Incoming Webhook に転送
  await fetch(c.env.SLACK_WEBHOOK_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: `🤖 *Claude Code 進捗通知*\nセッション: \`${session_id}\`\n\n${message}`,
      channel: "#dev-automation",
    }),
  });
 
  return c.json({ success: true });
});

デプロイとインフラ構成

Cloudflare Workers へのデプロイ（推奨）

HTTP Hooks のエンドポイントは、レスポンスが速く可用性が高い点が肝心です。Cloudflare Workers は世界 300 拠点以上のエッジで動作し、コールドスタートがなく（最大で数ミリ秒程度）、無料プランでも月 10 万リクエストまで利用できます。

# wrangler.toml
name = "claude-hooks-server"
main = "src/index.ts"
compatibility_date = "2026-03-01"
 
[vars]
REPO_OWNER = "your-org"
REPO_NAME = "your-repo"
 
# シークレットは wrangler secret put で設定
# CLAUDE_HOOK_SECRET
# GITHUB_TOKEN
# SLACK_WEBHOOK_URL

# デプロイコマンド
wrangler deploy
 
# シークレットの設定
wrangler secret put CLAUDE_HOOK_SECRET
wrangler secret put GITHUB_TOKEN

ローカル開発時の ngrok 活用

ローカル開発中に HTTP Hooks をテストするには、ngrok でローカルサーバーを外部公開します。

# ローカルサーバーを起動
npm run dev  # localhost:8787 で起動
 
# ngrok でトンネル作成
ngrok http 8787
 
# .claude/settings.json の URL を ngrok URL に変更
# "url": "https://xxxx.ngrok-free.app/hooks/file-changed"

モニタリングとデバッグ

構造化ログによる可視性の確保

HTTP Hooks を本番環境で稼働させるには、Webhook サーバーの動作を可視化することが不可欠です。構造化 JSON ログにより、クエリ・アラート・トレースが容易になります。

// webhook-server/src/logger.ts
type LogLevel = "info" | "warn" | "error" | "debug";
 
interface LogEntry {
  timestamp: string;
  level: LogLevel;
  event: string;
  session_id?: string;
  tool_name?: string;
  decision?: string;
  duration_ms?: number;
  [key: string]: unknown;
}
 
export function log(level: LogLevel, event: string, meta: Partial<LogEntry> = {}) {
  const entry: LogEntry = {
    timestamp: new Date().toISOString(),
    level,
    event,
    ...meta,
  };
  // Cloudflare Workers では console.log が Workers Logs にストリーム出力される
  console.log(JSON.stringify(entry));
}
 
// 使用例
const start = Date.now();
const result = await runQualityCheck(filePath, content);
log("info", "quality_check_complete", {
  session_id,
  tool_name,
  filePath,
  decision: result.pass ? "proceed" : "block",
  issue_count: result.issues.length,
  duration_ms: Date.now() - start,
});

Datadog、Axiom、Cloudflare Workers Logs などに構造化ログを流し込むことで、次のような指標をダッシュボードで確認できます。

block と proceed の比率（品質基準の通過率）
ファイル種別ごとの品質問題の発生頻度
Webhook サーバーのレイテンシ（p50 / p95 / p99）
品質チェックを通過するまでに Claude が要した平均イテレーション数

セッション ID によるエンドツーエンドのトレース

HTTP Hooks のすべてのペイロードには session_id が含まれます。これをトレース ID として活用することで、Claude Code の一回のセッション全体を複数のサービスをまたいで追跡できます。

// session_id を下流サービスへのヘッダーとして伝播する
async function callDownstreamService(
  url: string,
  payload: unknown,
  sessionId: string
) {
  return fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Session-Id": sessionId,
    },
    body: JSON.stringify(payload),
  }).then((r) => r.json());
}

障害モードへの対応

Webhook サーバーが一時的に停止した場合、Claude Code はタイムアウト待機後にツール実行をブロックします。CI パイプラインの冒頭にヘルスチェックを挟み、サーバーが落ちている場合はフック依存のステップをスキップする設計が堅牢です。

# ヘルスチェックジョブ
check-webhook-health:
  runs-on: ubuntu-latest
  outputs:
    healthy: ${{ steps.health.outputs.healthy }}
  steps:
    - id: health
      run: |
        STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
          https://your-webhook-server.example.com/health)
        if [ "$STATUS" = "200" ]; then
          echo "healthy=true" >> $GITHUB_OUTPUT
        else
          echo "healthy=false" >> $GITHUB_OUTPUT
          echo "⚠️ Webhook サーバー障害（ステータス $STATUS）— フックなしで続行"
        fi

本番運用チェックリスト

HTTP Hooks 統合を本番環境に移行する前に、以下の項目を確認してください。各項目は実際の本番トラブルから学んだ教訓です。

Webhook サーバーのセキュリティ

すべてのエンドポイントで Bearer Token または HMAC 署名検証を実装している
シークレットはすべてシークレット管理サービスに保管されている（ハードコードなし）
HTTPS のみ許可（HTTP は拒否）
CI ランナーの IP が固定であれば IP 制限を追加している
ヘルスチェックエンドポイント（/health）が 200 を返している

信頼性・耐障害性

すべてのフックハンドラーがタイムアウト時間（デフォルト 10 秒）内にレスポンスを返す
重い処理（型チェック・セキュリティスキャン）は非同期化または最適化済み
下流サービス呼び出しにエクスポネンシャルバックオフを実装している
ハンドラーが冪等（同じペイロードを 2 回処理しても安全）
Webhook サーバー障害時に CI がグレースフルデグラデーションできる設定になっている

可観測性

session_id を相関フィールドとした構造化 JSON ログを出力している
レスポンスが遅いフック（3 秒超）に対してアラートを設定している
decision: "block" イベントを定期的に確認し、品質ルールを調整している
トレースが Claude Code から Webhook サーバーを経て下流サービスまで一貫している

品質ルールの設計

block レスポンスの reason は具体的かつ実行可能な内容になっている（曖昧な記述は禁止）
最大リトライ回数を明示的に設定し、無限ループを防いでいる
品質ルールは Webhook サーバーのコードとともにバージョン管理されている
ルールはステージング環境で検証してから本番適用している

CI/CD 統合

GitHub Actions Secrets のスコープを最小限のリポジトリに絞っている
ANTHROPIC_API_KEY を不必要なワークフロー間で共有していない
--dangerously-skip-permissions はCI 環境のみで使用し、開発者マシンでは使わない
どの Claude Code セッションがレビューを行ったか PR に記録されている

よくある疑問（FAQ）

Q1. HTTP Hooks と stdio hooks はどちらを使うべきですか？

単一マシンで完結する処理（ファイルフォーマッター、ローカルリンターなど）は stdio hooks が適しています。一方、GitHub・Slack・Jira などの外部サービスと連携したり、チーム全員が共有するルールを一元管理したりする場合は HTTP Hooks が優れています。本番 CI/CD 環境では HTTP Hooks を選択するのが一般的です。

Q2. Webhook のタイムアウト時間の目安は？

Claude Code は HTTP Hooks のデフォルトタイムアウトを 10 秒に設定しています（設定でカスタマイズ可能）。Webhook サーバーはこの時間内にレスポンスを返す必要があります。ESLint や TypeScript の型チェックは通常 1〜3 秒で完了しますが、複雑なセキュリティスキャンは非同期処理に切り出すことを検討してください。

Q3. `decision: "block"` で Claude が無限ループに陥ることはありますか？

Claude Code は同一のツール呼び出しに対して最大 3 回まで再試行します（設定変更可能）。また、reason の内容が明確でないと Claude は正しく修正できないため、具体的で実行可能なフィードバックを返す点が肝心です。「問題があります」ではなく「L15 の console.log を削除してください」のように指示することで、ループを最小化できます。

Q4. 機密情報が HTTP Hooks のペイロードに含まれますか？

PostToolUse のペイロードには tool_input（ファイルの新しい内容）が含まれます。機密情報を扱うリポジトリでは、Webhook サーバーの通信を TLS で保護し、ログに内容を出力しないよう注意してください。また、エンドポイントを Cloudflare Access などの SSO 認証で保護することも推奨します。

Q5. GitHub Actions 以外の CI/CD ツールでも使えますか？

はい。HTTP Hooks は汎用的な Webhook 仕様なので、GitLab CI、CircleCI、Bitbucket Pipelines、AWS CodePipeline など、どの CI ツールとも組み合わせられます。基本的なアプローチは同じで、CI のジョブ内で Claude Code を実行し、Webhook エンドポイントを公開した状態にするだけです。

まとめ

Claude Code の HTTP Hooks は、AI エージェントを既存の開発ワークフローに組み込む「のり代」として機能します。本記事で解説した内容をまとめます。

HTTP Hooks は外部サービスとの双方向連携を実現し、decision フィールドで Claude の動作を制御できる
Webhook サーバーには HMAC 署名検証・Bearer Token 認証・IP 制限を組み合わせた多層防御が重要
GitHub Actions との統合パターンは「コードレビュー自動化」「テスト失敗分析」「セマンティックバージョニング判断」の 3 種類が特に実用的
Block → Rewrite → Verify のフィードバックループで、Claude Code が自律的に品質基準を満たすコードを生成するパイプラインを実現できる
Cloudflare Workers はエッジでの低レイテンシ・高可用性を実現する理想的なデプロイ先

Claude Code の並列開発マスターと組み合わせることで、複数のエージェントが並行してコードを書き、それぞれのアウトプットを HTTP Hooks でリアルタイムに検証するさらに高度なワークフローを構築できます。

まずは小さなステップとして、既存の CI パイプラインに Claude Code のコードレビューステップを 1 つ追加することから始めてみてください。その体験を通じて、どのポイントで HTTP Hooks が最も効果を発揮するかが見えてくるはずです。

DevOps と AI エージェントの融合は、まだ始まったばかりです。HTTP Hooks を入口として、開発チームのフローを継続的に改善していきます。

お読みいただきありがとうございます

Claude Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

✦コピー&ペーストで使える実装コード付き
✦毎日新しい上級ガイドを追加
✦¥580/月または ¥1,480 の永久アクセス

メンバーシップを見る →