読み込み中

ビルドフェーズでは、フックをガードレールとして使用し、人間が関与せずにアクションを許可またはブロックしていました(ステージ3:ビルド)。フックは確認を求めることもでき、その場合はセッションを実行している人がそれを承認するまでアクションを一時停止します。承認者がリリースマネージャーなど別の人物である場合、フックはその人の記録された承認を探し、それが存在するまでブロックします。

このプレイはステージ5:デプロイに位置づけられています。リリースゲートが最も明確な例だからですが、フックはデプロイに限定されたものではなく、Claudeが動作する場所であればどこでも実行されます。例えば、フックはステージ3:ビルドの間に変更チケットのないマイグレーションやインフラへの編集をブロックしたり、ステージ4:テストでの修正タスク中にエージェントがテストファイルを編集するのを止めたりできます。

はじめに

  • 前提条件:なし。
  • インフラストラクチャ:変更プロセスが必要とする承認の一覧を文書化したもの。

実行方法

  1. エンジニアリングリーダーシップが、チェンジマネジメントおよびコンプライアンスとともに、変更管理の承認、リリース認可、保護されたパスへの編集など、存続させるべき人間による承認ゲートを列挙します。
  2. プラットフォームエンジニアは、各ゲートをフックとして表現します。フックとは、Claudeが動作する前に実行され、許可・確認・ブロックのいずれかを行えるスクリプトです。
  3. チームのフックはGit管理下の.claude/settings.jsonに置き、交渉の余地のないフックはプラットフォームまたはIT管理者が所有するマネージド設定に置きます。これにより、個々のエンジニアがそれらを無効化することはできません。
  4. ブロックはその理由を自ら説明すべきです。そのため、フックがアクションを停止する際には、理由と承認への経路がClaudeの出力に表示されます。

実際の様子

この例は、開発環境、ステージング環境、本番環境にリリースされる保険会社のカスタマーポータルです。デプロイはMCPツールを通じて実行され、環境ごとに1つのサーバーがあり、各サーバーにはreleaseツールがあります。

以下のエントリは、プロジェクトの.claude/settings.json内の独立した例です。そのマッチャーは、すべてのサーバー上のreleaseを捕捉します。空のargsリストにより、Claude Codeはシェルを経由せずにスクリプトを直接実行します。

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__deploy-.*__release",
        "hooks": [
          { "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/release-gate.sh",
            "args": [] }
        ]
      }
    ]
  }
}

ゲート自体、.claude/hooks/release-gate.sh:

bash
#!/bin/bash
# リリースゲート。dev: 許可。staging: 確認。production: このバージョンの承認済み変更チケットが必要、なければブロック。
input=$(cat)
tool=$(jq -r '.tool_name' <<<"$input")
version=$(jq -r '.tool_input.version' <<<"$input")
ticket=$(jq -r '.tool_input.ticket // empty' <<<"$input")

decide() {   # decide <allow|ask|deny> <reason>
  jq -n --arg decision "$1" --arg reason "$2" '{hookSpecificOutput: {
    hookEventName: "PreToolUse",
    permissionDecision: $decision,
    permissionDecisionReason: $reason}}'
  exit 0
}

case "$tool" in
  mcp__deploy-dev__release)
    decide allow "dev needs no approval" ;;
  mcp__deploy-staging__release)
    [ "$GITHUB_REF" = "refs/heads/main" ] && decide allow "pipeline release from main"
    decide ask "This ships $version to staging. Approve only if you own this release." ;;
  mcp__deploy-prod__release)
    route="Open a change ticket at https://change.example.com/new for version $version, \
wait for the release manager to approve it, then call release again with that ticket number."
    [[ "$ticket" =~ ^CHG-[0-9]+$ && "$version" =~ ^[0-9a-f]{7,40}$ ]] ||
      decide deny "Production needs an approved change ticket. $route"
    if approver=$(/usr/local/bin/change-ticket show --ticket "$ticket" --format json |
        jq -er --arg v "$version" 'select(.state == "approved" and .version == $v) | .approver' 2>/dev/null); then
      decide allow "$ticket approved by $approver"
    fi
    decide deny "$ticket is not approved for version $version. $route" ;;
  *)
    decide deny "No release rule for $tool. Add one to release-gate.sh first." ;;
esac

このスクリプトでは、versionとticketはClaudeがreleaseツールに渡す入力です。change-ticketは、あなたの変更管理システム自体のコマンドラインツールを表しています。このゲートは、エージェントが自分が読み取るレコードに書き込む手段を持たないことに依存しています。

非対話型の実行では誰もaskに答えることができないため、Claude Codeはその呼び出しを拒否します。そのため、このゲートはmain上のパイプラインからのステージングを許可します。そこでは承認済みのマージが承認そのものとなります。

このゲートには限界があります。エンジニアは自分のセッションで手動でGITHUB_REFを設定できますが、そうしても、本来自分自身が答えるはずだったプロンプトをスキップするだけです。

askの理由は本人に表示されます。denyの理由はClaudeに表示されるため、ブロックメッセージはClaudeが伝えるべき承認への経路を明示します。まずステージングの結果、続いてチケットのない本番環境の結果です。

json
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "ask",
    "permissionDecisionReason": "This ships 4f2c9e1 to staging. Approve only if you own this release."
  }
}
json
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Production needs an approved change ticket. Open a change ticket at https://change.example.com/new for version 4f2c9e1, wait for the release manager to approve it, then call release again with that ticket number."
  }
}

ガバナンス上の考慮事項

フックが承認ゲートです。ゲートの条件は、誰に対しても毎回確実に適用されます。許可とブロックの判断はタイムスタンプ付きで記録されます。ゲートはまた、何が承認とみなされるかも定義します。それが承認済みの変更チケットであれ、リリースマネージャーの承認であれ同様です。

規制対象企業向けのマネージド設定

規制対象企業向けのマネージド設定は、モバイルデバイス管理(MDM)または管理コンソールを通じてプラットフォームチームによって展開されます。エンジニアはそこに含まれる設定を編集したり上書きしたりすることはできません。以下を参照してください。

json
{
  "permissions": {
    "deny": [
      "Read(.env*)", "Read(./secrets/**)",
      "WebFetch", "Bash(curl *)", "Bash(wget *)"
    ],
    "allow": [
      "Bash(git *)", "Bash(make build)",
      "Bash(make test)", "Bash(make lint)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "allowManagedPermissionRulesOnly": true,
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false,
    "network": { "allowedDomains": ["git.internal.example.com", "registry.npmjs.org"] },
    "credentials": {
      "files": [
        { "path": "~/.ssh", "mode": "deny" },
        { "path": "~/.aws/credentials", "mode": "deny" }
      ],
      "envVars": [ { "name": "GITHUB_TOKEN", "mode": "deny" } ]
    }
  },
  "allowManagedHooksOnly": true,
  "disableSideloadFlags": true,
  "allowManagedMcpServersOnly": true,
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "example-corp/approved-plugins" }
  ],
  "requiredMinimumVersion": "2.1.193"
}

これらの設定が制御の観点で何を行うか:

  • permissions.denyは、シークレットがエージェントのコンテキストに入らないようにし、ツールを通じた任意のネットワーク発信をブロックします。permissions.allowは安全な内側のループを事前承認するため、拒否リストがプロンプト疲労につながることはありません。
  • disableBypassPermissionsModeとallowManagedPermissionRulesOnlyを組み合わせることで、エンジニア、プロジェクトファイル、コマンドラインフラグのいずれもルールを広げることができなくなります。
  • sandboxは、permissionsでは対応できない部分をカバーします。WebFetchに対するツールレベルの拒否は、シェルコマンドがネットワークに到達することを止めませんが、OSレベルのドメイン許可リストは発信を完全にブロックします。つまり、この2つは異なる層で同じ目的を強制しています。failIfUnavailableとallowUnsandboxedCommandsは、サンドボックスを前提条件に変えます。つまり、サンドボックスが初期化できない場合、Claude Codeは起動を拒否し、サンドボックス内で失敗したコマンドをサンドボックス外で再試行することはできません。
  • credentialsは、拒否ルールが見落とすケースに対応します。permissions.denyはClaudeのファイルツールを制御しますが、サンドボックス化されたシェルコマンドは、デフォルトでは依然として~/.sshや~/.aws/credentialsを読み取れる可能性があります。このブロックはそれらの読み取りを拒否し、サンドボックス化されたコマンドの環境から列挙されたシークレットを取り除きます。
  • allowManagedHooksOnlyは、マネージド設定で定義されたフックのみが実行されることを意味します。ユーザー設定、プロジェクト設定、ローカル設定内のフックはブロックされ、これには上記の独立した.claude/settings.jsonの例も含まれます。このプレイの承認ゲートを確実に適用させるには、マネージドファイル自体のhooksブロック内でそれを定義してください。
  • disableSideloadFlagsとstrictKnownMarketplacesは、エンジニアのマシン上のスキル、エージェント、フック、またはMCPサーバーが、ホームディレクトリからではなく、組織が承認したプラグインマーケットプレイスを経由して入手されたものであることを意味します。マーケットプレイスの許可リストは何をインストールできるかを制御し、単一の実行のためにプラグイン、エージェント、またはMCP設定をサイドロードするようなフラグは起動時に拒否されます。
  • allowManagedMcpServersOnlyは、エージェントのツールの範囲をプラットフォームチームが所有する許可リストにします。
  • requiredMinimumVersionは、承認された下限を下回るバージョンでの起動を拒否します。これにより、制御は組織が実際に評価したビルドによって強制されます。

この例は、自分自身の環境に合わせてカスタマイズするための出発点として扱ってください。各拒否ルールは何らかの機能を取り除くものであり、適切なバランスはリポジトリのデータ分類によって異なります。設定リファレンスには、マネージド専用のものを含め、すべてのキーが文書化されています。

測定方法

フック自体については:

  • 先行指標:各承認ゲートで待機に費やされた時間。すべてのフックの判断は、タイムスタンプと許可またはブロックの判定とともにOpenTelemetryエクスポートに書き込まれるため、ゲートごとの待機時間を可視化できます。
  • 遅行指標:インシデントトラッカーから得られる、フック導入前後で本番環境に到達したゲート違反の件数。