エージェントアーキテクチャ：AI駆動の開発ハーネスを構築する

TL;DR: Claude Codeはファイルアクセス機能を備えたチャットボックスではありません。29個の文書化されたライフサイクルイベントを持つプログラマブルなランタイムであり、それぞれにモデルがスキップできないシェルスクリプトをフックできます。フックをディスパッチャに、ディスパッチャをスキルに、スキルをエージェントに、エージェントをワークフローに積み重ねれば、制約を強制し、作業を委譲し、セッションを越えてメモリを永続化し、マルチエージェントの熟議をオーケストレーションする自律的な開発ハーネスが完成します。本ガイドでは、単一のフックから10エージェントのコンセンサスシステムまで、そのスタックのすべての層を解説します。フレームワークは一切不要。すべてbashとJSONで構成されています。

Andrej Karpathy氏は、LLMエージェントの周囲に育つものを表す用語としてclaws（爪）を提唱しました。コンテキストウィンドウの外側の世界をつかむためにエージェントに与えられる、フック、スクリプト、オーケストレーションのことです。¹ 多くの開発者は、AIコーディングエージェントを対話型アシスタントとして扱っています。プロンプトを入力し、ファイルを編集する様子を眺め、次へ進む。この捉え方では、生産性は自分が直接監督できる範囲に制限されてしまうのです。

インフラ思考のメンタルモデルはまったく異なります。AIコーディングエージェントとは、LLMカーネルを備えたプログラマブルなランタイムなのです。モデルが取るすべてのアクションは、あなたが制御するフックを通過します。プロンプトではなく、ポリシーを定義する。Webサーバーがnginxのルール内で動作するのと同じように、モデルはあなたのインフラの中で動作します。nginxの前に座ってリクエストを打ち込む人はいません。設定し、デプロイし、監視するものです。

この区別が重要なのは、インフラには複利効果があるからです。bashコマンド内の認証情報をブロックするフックは、すべてのセッション、すべてのエージェント、すべての自律実行を保護します。評価ルーブリックをエンコードしたスキルは、あなたが呼び出してもエージェントが呼び出しても一貫して適用されます。コードのセキュリティをレビューするエージェントは、あなたが見ていようがいまいが同じチェックを実行するのです。²

重要なポイント

• フックは実行を保証するが、プロンプトは保証しない。 Lint、フォーマット、セキュリティチェックなど、モデルの挙動に関係なく毎回実行されるべきものにはフックを使いましょう。終了コード2はアクションをブロックします。終了コード1は警告のみです。³
• スキルは自動的に有効化されるドメイン知識をエンコードする。 descriptionフィールドがすべてを決定します。Claudeは（キーワードマッチングではなく）LLMの推論を用いて、スキルを適用すべきタイミングを判断します。⁴
• サブエージェントはコンテキストの肥大化を防ぐ。 探索や分析のために隔離されたコンテキストウィンドウを使うことで、メインセッションを軽量に保てます。独立したサブエージェントは並列実行し、ワーカー間で持続的な連携が必要な場合はエージェントチームを活用しましょう。⁵
• メモリはファイルシステムに存在する。 ファイルはコンテキストウィンドウを越えて永続します。CLAUDE.md、MEMORY.md、rulesディレクトリ、ハンドオフドキュメントが、構造化された外部メモリシステムを形成するのです。⁶
• マルチエージェントの熟議は盲点を捉える。 単一エージェントは自身の前提に異議を唱えることができません。評価の優先順位が異なる2つの独立したエージェントは、品質ゲートでは対処できない構造的な失敗を捕捉します。⁷
• ハーネスパターンこそがシステムである。 CLAUDE.md、フック、スキル、エージェント、メモリは、それぞれ独立した機能ではありません。これらが組み合わさって、あなたとモデルの間に決定論的なレイヤーを構成し、自動化とともにスケールしていくのです。

本ガイドの使い方

各セクションは前のセクションを土台にしています。末尾のDecision Frameworkは、問題の種類ごとに適切なメカニズムを選ぶためのルックアップテーブルとして機能します。

5分間のゴールデンパス

詳細に入る前に、ゼロから動作する__TERM_1__を構築する最短の道のりをご紹介します。1つのhook、1つのskill、1つのsubagent、そして1つの成果。

ステップ1：セキュリティhookの作成（2分）

.claude/hooks/block-secrets.shを作成します。

#!/bin/bash
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$CMD" | grep -qEi '(AKIA|sk-|ghp_|password=)'; then
    echo "BLOCKED: Potential secret in command" >&2
    exit 2
fi

.claude/settings.jsonで配線します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".claude/hooks/block-secrets.sh" }]
      }
    ]
  }
}

結果： Claudeが実行するすべてのbashコマンドが、漏洩した認証情報についてスクリーニングされるようになります。モデルはこのチェックをスキップできません。

ステップ2：コードレビューskillの作成（1分）

.claude/skills/reviewer/SKILL.mdをフロントマター（name: reviewer、description: Review code for security issues, bugs, and quality problems. Use when examining changes, reviewing PRs, or auditing code.、allowed-tools: Read, Grep, Glob）とチェックリスト（SQLインジェクション、XSS、ハードコードされたシークレット、エラーハンドリングの欠如、50行を超える関数）とともに作成します。

結果： review、check、auditについて言及するたびに、Claudeがこの専門知識を自動的に有効化します。

ステップ3：subagentの生成（30秒）

任意のClaude Codeセッションで、別のエージェントを使って直近の3つのコミットをセキュリティ問題についてレビューするようClaudeに依頼します。ClaudeはExploreエージェントを生成し、差分を読み、レビューskillを適用し、サマリーを返します。メインコンテキストはクリーンに保たれます。

これで手に入るもの

3層の__TERM_1__です。決定論的なセキュリティゲート（hook）、自動的に有効化されるドメイン専門知識（skill）、そしてコンテキストを保護する隔離された分析（subagent）。以下の各セクションでは、この3層のいずれかを掘り下げていきます。

なぜAgent Architectureが重要なのか

Simon Willisonは現在の状況を1つの観察で捉えています。コードを書くことは今や安価になったのです。⁸ そのとおりです。しかし、その裏返しとして、検証こそが高価な作業となりました。検証インフラのない安価なコードは、バグを大量生産します。投資の見返りをもたらすのは、より良いプロンプトではありません。モデルが見逃すものを捕捉する、モデルを取り巻くシステムなのです。

Agent Architectureを必要とする3つの力があります。

コンテキストウィンドウは有限かつ劣化する。 ファイル読み込み、ツール出力、会話のターンはすべてトークンを消費します。Microsoft ResearchとSalesforceは15種類のLLMを20万件以上のシミュレーション会話でテストし、シングルターンからマルチターンへの移行で平均39%の性能低下を確認しました。⁹ 劣化はわずか2ターンで始まり、予測可能な曲線をたどります。最初の30分で正確だった複数ファイル編集が、90分後には単一ファイルへの視野狭窄へと退化していくのです。コンテキストウィンドウが長くなってもこの問題は解決しません。同じ研究の「Concat」条件（会話全体を1つのプロンプトとして扱う）では、同一内容でシングルターンの95.1%の性能を達成しました。劣化はトークン制限ではなく、ターンの境界から生じているのです。

モデルの挙動は確率的であり、決定論的ではない。 「ファイル編集後は必ずPrettierを実行する」とClaudeに指示しても、およそ80%の確率でしか機能しません。³ モデルは忘れるかもしれないし、速度を優先するかもしれないし、変更が「小さすぎる」と判断するかもしれません。コンプライアンス、セキュリティ、チーム標準において、80%は許容できません。hookは実行を保証します。EditやWriteが起きるたびにフォーマッタが起動し、例外はありません。決定論は確率論に勝るのです。

単一の視点は多次元の問題を見落とす。 単一のエージェントがAPIエンドポイントをレビューし、認証を確認し、入力サニタイズを検証し、CORSヘッダーを確認しました。問題なしとの診断です。2番目のエージェントが、別途ペネトレーションテスターとしてプロンプトされ、そのエンドポイントが無制限のクエリパラメータを受け付けており、データベースクエリ増幅によってサービス拒否を引き起こしうることを発見しました。⁷ 最初のエージェントが確認しなかったのは、その評価フレームワークの中にクエリの複雑さをセキュリティ面として扱う仕組みがなかったからです。このギャップは構造的なものです。どれほどプロンプトエンジニアリングを積み重ねても解消されません。

Agent Architectureは、この3つすべてに対処します。hookは決定論的な制約を強制し、subagentはコンテキスト分離を管理し、マルチエージェントのオーケストレーションは独立した視点を提供します。これらが合わさって__TERM_1__を形作るのです。

ハーネスパターン

ハーネスはフレームワークではありません。AIコーディングエージェントを決定論的なインフラで包み込む、コンポーザブルなファイル、スクリプト、規約のセット — それがパターンとしてのハーネスです。構成要素は次のとおりです。

┌──────────────────────────────────────────────────────────────┐
│                      THE HARNESS PATTERN                      │
├──────────────────────────────────────────────────────────────┤
│  ORCHESTRATION                                                │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐             │
│  │   Agent     │  │   Agent    │  │  Consensus │             │
│  │   Teams     │  │  Spawning  │  │  Validation│             │
│  └────────────┘  └────────────┘  └────────────┘             │
│  Multi-agent deliberation, parallel research, voting          │
├──────────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │  Skills   │  │  Hooks   │  │  Memory  │  │  Agents  │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
│  Domain expertise, deterministic gates, persistent state,     │
│  specialized subagents                                        │
├──────────────────────────────────────────────────────────────┤
│  INSTRUCTION LAYER                                            │
│  ┌──────────────────────────────────────────────────────┐    │
│  │     CLAUDE.md  +  .claude/rules/  +  MEMORY.md       │    │
│  └──────────────────────────────────────────────────────┘    │
│  Project context, operational policy, cross-session memory    │
├──────────────────────────────────────────────────────────────┤
│  CORE LAYER                                                   │
│  ┌──────────────────────────────────────────────────────┐    │
│  │           Main Conversation Context (LLM)             │    │
│  └──────────────────────────────────────────────────────┘    │
│  Your primary interaction; finite context; costs money        │
└──────────────────────────────────────────────────────────────┘

インストラクションレイヤー: CLAUDE.mdファイルとrulesディレクトリは、エージェントがプロジェクトについて知るべき内容を定義します。これらはセッション開始時、および各コンパクション後に自動的にロードされます。エージェントの長期的なアーキテクチャメモリと言える存在です。

エクステンションレイヤー: skillsはコンテキストに応じて自動的に有効化されるドメイン知識を提供します。hooksはマッチするツール呼び出しごとに発動する決定論的なゲートを提供します。メモリファイルはセッションを越えて状態を永続化します。カスタムエージェントは特化したsubagentの設定を提供します。

オーケストレーションレイヤー: マルチエージェントパターンは、リサーチ、レビュー、熟議のために独立したエージェント群を協調させます。スポーン予算は暴走再帰を防ぎます。コンセンサス検証は品質を担保します。

ここで重要な洞察があります。多くのユーザーはコアレイヤーだけで作業し、コンテキストの肥大化とコストの上昇をただ眺めることになります。一方、パワーユーザーはインストラクションレイヤーとエクステンションレイヤーを構成し、コアレイヤーはオーケストレーションと最終的な意思決定にのみ使うのです。²

マネージド型 vs. セルフホスト型ハーネス（2026年4月）

2026年初頭を通じて、「自前のハーネスを構築する」道が事実上唯一の選択肢でした。これが2026年4月に変わります。AnthropicはClaude Managed Agentsをパブリックベータとしてリリース（4月8日）。ハーネスループ、ツール実行、サンドボックスコンテナ、状態永続化を1本のREST APIとして提供し、課金は標準トークン料金にセッション時間あたり$0.08が加算されます。OpenAIのAgents SDKアップデート（4月16日）も同じ分離を公式化しました。ハーネスとコンピュートを別レイヤーとして扱い、ネイティブなサンドボックスプロバイダー（Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel）と、コンテナ消失を乗り越えるためのスナップショット／リハイドレートをサポートしています。²³²⁴

OpenAI側のより深いSDK面は、openai-agents Python v0.14.0（2026年4月15日リリース、4月16日発表）で実装されました。AgentのサブクラスであるSandboxAgentはdefault_manifest、sandbox instructions、capabilitiesを備え、Manifestはフレッシュワークスペース契約（ファイル、ディレクトリ、ローカルファイル、Gitリポジトリ、env、ユーザー、マウント）を記述します。SandboxRunConfigはサンドボックスクライアント、ライブセッション注入、manifest上書き、スナップショット、materialization並列度の上限を実行ごとに設定できます。組み込みのcapabilitiesにはシェルアクセス、ファイルシステム編集、画像インスペクション、skills、sandbox memory、コンパクションが含まれます。Sandbox memoryは抽出された教訓を実行を越えて永続化し、段階的に開示します。ワークスペースはローカルファイル、Gitリポジトリエントリ、リモートマウント（S3、R2、GCS、Azure Blob、S3 Files）をサポートし、スナップショットはプロバイダー間でポータブルです。バックエンドはUnixLocalSandboxClient、DockerSandboxClient、そしてオプションのextrasを介したBlaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel向けのホスト型クライアントです。²⁴

Claude Codeランタイムをライブラリとして埋め込みたいPythonプロジェクト — 「claudeをシェルアウトする」と「Managed AgentsへREST APIする」の中間 — には、第3の選択肢としてclaude-agent-sdk-pythonがあります。4月28〜29日のシリーズ（v0.1.69 → v0.1.71）では、同梱のCLIをv2.1.123に引き上げ、mcp依存の下限を>=1.19.0に引き上げました（古いバージョンはin-process MCPツールから返されるCallToolResultを黙って取りこぼし、モデルにバリデーションエラーのblobを残していたためです）。さらにSandboxNetworkConfigをTypeScript SDKとスキーマ的に揃えました（allowedDomains、deniedDomains、allowManagedDomainsOnly、allowMachLookup）。³⁰

アーキテクチャの分岐は現実のものとなりました。

どちらを選ぶか: セルフホストが適しているのは、すでにインフラ運用力を持つチーム、自前でskills/hooksを完全に管理したいチーム、特定のワークフローを深く最適化しているチームです。マネージドが適しているのは、専任のプラットフォームエンジニアを抱えていないチーム、カスタマイズよりもtime-to-valueを重視する場合、あるいは永続化レイヤーを自前で構築せずに、ノートPCのクローズを越えてエージェント実行を確実に生存させたい場合です。両者は両立可能で、特定の長時間タスクをREST API経由でManaged Agentsに委譲するセルフホスト型ハーネスを運用することもできます。

ディスク上のハーネスはどう見えるか

~/.claude/
├── CLAUDE.md                    # Personal global instructions
├── settings.json                # User-level hooks and permissions
├── skills/                      # Personal skills (44+)
│   ├── code-reviewer/SKILL.md
│   ├── security-auditor/SKILL.md
│   └── api-designer/SKILL.md
├── agents/                      # Custom subagent definitions
│   ├── security-reviewer.md
│   └── code-explorer.md
├── rules/                       # Categorized rule files
│   ├── security.md
│   ├── testing.md
│   └── git-workflow.md
├── hooks/                       # Hook scripts
│   ├── validate-bash.sh
│   ├── auto-format.sh
│   └── recursion-guard.sh
├── configs/                     # JSON configuration
│   ├── recursion-limits.json
│   └── deliberation-config.json
├── state/                       # Runtime state
│   ├── recursion-depth.json
│   └── agent-lineage.json
├── handoffs/                    # Session handoff documents
│   └── deliberation-prd-7.md
└── projects/                    # Per-project memory
    └── {project}/memory/MEMORY.md

.claude/                         # Project-level (in repo)
├── CLAUDE.md                    # Project instructions
├── settings.json                # Project hooks
├── skills/                      # Team-shared skills
├── agents/                      # Team-shared agents
└── rules/                       # Project rules

この構造の中の各ファイルには、それぞれ明確な役割があります。~/.claude/ツリーはすべてのプロジェクトに適用される個人インフラです。各リポジトリ内の.claude/ツリーはプロジェクト固有で、gitを介して共有されます。両者が組み合わさって、完全なハーネスを構成します。

スキルシステム

スキルとは、モデルが呼び出す拡張機能のことです。Claude がコンテキストに応じて自動的に発見・適用するため、明示的に呼び出す必要はありません。⁴ 同じコンテキストをセッションごとに何度も説明し直していると気づいたら、それがスキルを構築すべきタイミングです。

スキルを構築すべきとき

スキルとは、Claude が常に利用可能な状態にしておく知識のためのものです。スラッシュコマンドは、明示的にトリガーするアクションのためのものです。どちらにすべきか迷ったら、こう問いかけてください。「Claude に自動適用させるべきか、それとも実行タイミングを自分で決めるべきか？」

スキルの作成

スキルは、スコープが広いものから狭いものまで、4つの場所に配置できます。⁴

すべてのスキルには、YAML フロントマターを持つ SKILL.md ファイルが必要です。

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Security Checks
When reviewing code, verify:

### Input Validation
- All user input sanitized before database operations
- Parameterized queries (no string interpolation in SQL)
- Output encoding for rendered HTML content

### Authentication
- Session tokens validated on every protected endpoint
- Permission checks before data mutations
- No hardcoded credentials or API keys in source

フロントマターのリファレンス

description フィールドがすべてを決める

セッション開始時、Claude Code はすべてのスキルの name と description を抽出し、Claude のコンテキストに注入します。メッセージを送信すると、Claude は言語モデルの推論を用いて、関連するスキルがあるかどうかを判断します。Claude Code ソースの独立した分析によって、このメカニズムが確認されています。スキルの description はシステムプロンプトの available_skills セクションに注入され、モデルは標準的な言語理解能力を用いて関連するスキルを選択するのです。¹⁰

悪い description：

description: Helps with code

効果的な description：

description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.

効果的な description には次の要素が含まれます。何をするか（特定の問題タイプに対するコードレビュー）、いつ使うか（変更の検査、PR、品質分析）、そしてユーザーが自然に入力するトリガーフレーズ（review、audit、check）です。

コンテキスト予算

すべてのスキルの description は、コンテキストウィンドウの1%で動的にスケールするコンテキスト予算を共有しており、フォールバックは8,000文字となっています。⁴ スキルを多く持つ場合は、各 description を簡潔に保ち、主要なユースケースを最初に記述してください。SLASH_COMMAND_TOOL_CHAR_BUDGET 環境変数で予算を上書きできますが、¹¹ より良い対応策は、より短く、より正確な description を書くことです。セッション中に /context を実行すれば、除外されたスキルがないか確認できます。

サポートファイルと構成

スキルは同じディレクトリ内の追加ファイルを参照できます。

~/.claude/skills/code-reviewer/
├── SKILL.md                    # Required: frontmatter + core expertise
├── SECURITY_PATTERNS.md        # Referenced: detailed vulnerability patterns
└── PERFORMANCE_CHECKLIST.md    # Referenced: optimization guidelines

SKILL.md から相対リンクで参照します。Claude はスキルが有効化されたときに、これらのファイルをオンデマンドで読み込みます。SKILL.md は500行未満に保ち、詳細なリファレンス資料はサポートファイルへ移しましょう。¹²

Git によるスキルの共有

プロジェクトスキル（リポジトリルートの .claude/skills/）は、バージョン管理を通じて共有されます。⁴

mkdir -p .claude/skills/domain-expert
# ... write SKILL.md ...
git add .claude/skills/
git commit -m "feat: add domain-expert skill for payment processing rules"
git push

チームメイトが pull すれば、スキルは自動的に取得されます。インストールも設定も不要です。これがチーム全体で専門知識を標準化する最も効果的な方法となります。

プロンプトライブラリとしてのスキル

単一目的のスキルにとどまらず、ディレクトリ構造は整理されたプロンプトライブラリとして機能します。

~/.claude/skills/
├── code-reviewer/          # Activates on: review, audit, check
├── api-designer/           # Activates on: design API, endpoint, schema
├── sql-analyst/            # Activates on: query, database, migration
├── deploy-checker/         # Activates on: deploy, release, production
└── incident-responder/     # Activates on: error, failure, outage, debug

それぞれのスキルが、自分の専門知識の異なる側面をエンコードしています。これらが集まることで、Claude がコンテキストに応じて自動的に参照する知識ベースが形成されるのです。ジュニアデベロッパーでも、求めずしてシニアレベルのガイダンスを得られます。

スキルとフックの組み合わせ

スキルは、スキル実行中のみ有効化される独自のフックをフロントマターで定義できます。これによって、他のセッションを汚染することなく、ドメイン固有の振る舞いを実現できます。²

---
name: deploy-checker
description: Verify deployment readiness. Use when preparing to deploy,
  release, or push to production.
hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: "bash -c 'INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r \".tool_input.command\"); if echo \"$CMD\" | grep -qE \"deploy|release|publish\"; then echo \"DEPLOYMENT COMMAND DETECTED. Running pre-flight checks.\" >&2; fi'"
---

哲学スキルは SessionStart フックを介して自動有効化され、明示的に呼び出さなくても、すべてのセッションに品質制約を注入します。スキル自体は知識です。フックは強制力です。両者が組み合わさることで、ポリシー層が形成されるのです。

スキルでよくある失敗

範囲が広すぎる description。 Git 関連のあらゆるプロンプト（rebase、merge、cherry-pick、さらには git status まで）で有効化される git-rebase-helper スキルは、80%のセッションでコンテキストを汚染します。対処法は、description を絞り込むか、disable-model-invocation: true を追加して明示的な /skill-name 呼び出しを必須にすることです。⁴

予算を取り合うスキルが多すぎる。 スキルが多いほど、1%のコンテキスト予算を取り合う description が増えていきます。スキルが有効化されないと感じたら、/context で除外されているものを確認してください。曖昧なスキルを多く持つよりも、よく記述された少数のスキルを優先しましょう。

重要な情報がサポートファイルに埋もれている。 Claude は SKILL.md をすぐに読み込みますが、サポートファイルは必要なときにのみアクセスします。重要な情報がサポートファイルに入っていると、Claude が見つけられない可能性があります。本質的な情報は SKILL.md に直接記述してください。⁴

SDK のスキルサーフェス（2026年5月8日）

claude-agent-sdk-python v0.1.77+ のセルフホスト型ハーネスでは、利用可能なスキルを宣言する際に、allowed_tools のレガシーな "Skill" 値ではなく、ClaudeAgentOptions の skills オプションを使用すべきです。³⁷ "Skill" ショートハンドは非推奨となっており、専用オプションは利用可能なスキルに関するより構造化された情報を Claude Code に提供します。v0.1.77 にバンドルされている CLI は v2.1.133 です。

Hookアーキテクチャ

HookはClaude Codeのライフサイクルイベントによってトリガーされるシェルコマンドです。³ モデルが解釈するプロンプトではなく、LLMの外側で通常のスクリプトとして実行されます。モデルがrm -rf /を実行したい? わずか10行のbashスクリプトがブロックリストに対してコマンドをチェックし、シェルが目にする前に拒否します。Hookはモデルの意思に関係なく発火するのです。

利用可能なイベント

このガイド更新時点で、Claude Codeは8つのカテゴリにわたる29個のドキュメント化されたライフサイクルイベントを公開しています。イベントリストはリリースとともに増えていくため、リファレンスドキュメントを情報源として扱い、本番環境でhookを組み込む前にチートシートで最新の完全な表を確認してください:¹³

終了コードのセマンティクス

終了コードによってhookがアクションをブロックするかどうかが決まります:³

重要: すべてのセキュリティhookはexit 1ではなくexit 2を使用しなければなりません。Exit 1は非ブロッキングの警告です。危険なコマンドはそのまま実行されてしまいます。これは各チームで最も多く見られるhookのミスです。¹⁴

Hookの設定

Hookは設定ファイルに定義します。共有hookはプロジェクトレベル（.claude/settings.json）、個人用hookはユーザーレベル（~/.claude/settings.json）に配置します:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [[ \"$FILE_PATH\" == *.py ]]; then black --quiet \"$FILE_PATH\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

matcherフィールドはイベント固有の値をフィルタリングします。toolイベントの場合、Bash、Edit、Write、Read、Glob、Grepなどのtool_name値、mcp__server__toolのようなMCPツール名、またはすべてのツールを対象とする*にマッチします。シンプルな名前と|区切りリストは完全一致で、その他の文字を含む値はJavaScript正規表現として扱われます。一部のイベントはmatcherをサポートせず、設定されていれば常に発火します。¹³

Hookの入出力プロトコル

Hookは標準入力から完全なコンテキストを含むJSONを受け取ります:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123",
  "agent_id": "main",
  "agent_type": "main"
}

高度な制御を行う場合、PreToolUse hookはJSONを出力してツール入力を変更したり、コンテキストを注入したり、権限の判断を下したりできます。hookSpecificOutputラッパーを使用してください — 古いトップレベルのdecision/reason形式はPreToolUseでは非推奨となっています:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Command validated and modified",
    "updatedInput": {
      "command": "npm test -- --coverage --ci"
    },
    "additionalContext": "Note: This database has a 5-second query timeout."
  }
}

3種類の保証

hookを書く前に、自分に問いかけてください: どんな種類の保証が必要なのか?¹⁴

フォーマッティング保証は事後的に一貫性を担保します。Write/Edit時のPostToolUse hookが、ファイル変更のたびにフォーマッターを実行します。フォーマッターがすべてを正規化するため、モデルの出力内容は問題になりません。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [[ \"$FILE_PATH\" == *.py ]]; then black --quiet \"$FILE_PATH\" 2>/dev/null; elif [[ \"$FILE_PATH\" == *.js ]] || [[ \"$FILE_PATH\" == *.ts ]]; then npx prettier --write \"$FILE_PATH\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

安全性保証は危険なアクションが実行される前に防止します。Bash時のPreToolUse hookがコマンドを検査し、破壊的なパターンを終了コード2でブロックします:

#!/bin/bash
# validate-bash.sh — block dangerous commands
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "rm\s+-rf\s+/|git\s+push\s+(-f|--force)\s+(origin\s+)?main|git\s+reset\s+--hard|DROP\s+TABLE"; then
    echo "BLOCKED: Dangerous command detected: $CMD" >&2
    exit 2
fi

品質保証は判断ポイントで状態を検証します。git commitコマンド時のPreToolUse hookがリンターやテストスイートを実行し、品質チェックに失敗するとコミットをブロックします:

#!/bin/bash
# quality-gate.sh — lint before commit
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "^git\s+commit"; then
    if ! LINT_OUTPUT=$(ruff check . --select E,F,W 2>&1); then
        echo "LINT FAILED -- fix before committing:" >&2
        echo "$LINT_OUTPUT" >&2
        exit 2
    fi
fi

シェルコマンド以外のhookタイプ

Claude Codeは5種類のhookタイプをサポートしています:¹³

Commandフック（type: "command"）はシェルスクリプトを実行します。高速で決定的、トークンコストがかかりません。

MCPツールフック（type: "mcp_tool"）は既に接続済みのMCPサーバー上のツールを呼び出します。検証ロジックが既にMCP境界の背後にあり、別途シェルスクリプトを必要としない場合に使用してください。

Promptフック（type: "prompt"）は高速なClaudeモデルにシングルターンのプロンプトを送信します。モデルは許可するなら{ "ok": true }を、ブロックするなら{ "ok": false, "reason": "..." }を返します。正規表現では表現できないニュアンスのある評価に使用してください。

Agentフック（type: "agent"）はマルチターン検証のために、ツールアクセス（Read、Grep、Glob）を持つsubagentを生成します。実験的機能であり、本番環境のゲートにはcommand hookを優先し、agent hookは実際のファイルやテスト出力を検査する必要が本当にあるチェックに限って使用してください:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests pass. Run the test suite and check results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

HTTPフック（type: "http"）はイベントのJSON入力をPOSTリクエストとしてURLに送信し、JSONを受け取ります。Webhook、外部通知サービス、APIベースの検証（v2.1.63+）に使用してください。SessionStartイベントではサポートされていません:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://your-webhook.example.com/hook",
            "headers": { "Authorization": "Bearer $WEBHOOK_TOKEN" },
            "allowedEnvVars": ["WEBHOOK_TOKEN"],
            "timeout": 10
          }
        ]
      }
    ]
  }
}

非同期hook

Hookは実行をブロックすることなくバックグラウンドで実行できます。通知やロギングなど、クリティカルでない操作にはasync: trueを追加してください:¹³

{
  "type": "command",
  "command": ".claude/hooks/notify-slack.sh",
  "async": true
}

非同期は通知、テレメトリ、バックアップに使用してください。フォーマッティング、検証、または次のアクションの前に完了する必要があるものに非同期を使用してはいけません。

独立hookよりもディスパッチャーを

同じイベントで7つのhookがすべて発火し、それぞれがstdinを独立して読み取ると、競合状態が発生します。同じJSON状態ファイルに同時に書き込む2つのhookはJSONを切り詰めてしまいます。そのファイルをパースする下流のhookすべてが壊れることになります。²

解決策: イベントごとに1つのディスパッチャーを設け、キャッシュされたstdinからhookを順次実行します:

#!/bin/bash
# dispatcher.sh — run hooks sequentially with cached stdin
INPUT=$(cat)
HOOK_DIR="$HOME/.claude/hooks/pre-tool-use.d"

for hook in "$HOOK_DIR"/*.sh; do
    [ -x "$hook" ] || continue
    echo "$INPUT" | "$hook"
    EXIT_CODE=$?
    if [ "$EXIT_CODE" -eq 2 ]; then
        exit 2  # Propagate block
    fi
done

Hookのデバッグ

サイレントに失敗するhookをデバッグするための5つのテクニックがあります:¹⁴

1. スクリプトを独立してテストする。 サンプルJSONをパイプで渡します: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. デバッグ出力にはstderrを使う。 終了コード2のstderrはエラーメッセージとしてClaudeに渡されます。非ブロッキングのstderr（exit 1、3など）はverboseモード（Ctrl+O）でのみ表示されます。
3. jqの失敗に注意する。 間違ったJSONパスはサイレントにnullを返します。jq式は実際のツール入力に対してテストしてください。
4. 終了コードを確認する。 exit 1を使うPreToolUse hookは、機能しているように見えても実際の強制力はゼロです。
5. hookは高速に保つ。 Hookは同期的に実行されます。すべてのhookは2秒以内、理想的には500ms以内に収めてください。

SDK側のhookイベントストリーミング

claude-agent-sdk-python（v0.1.74+、2026年5月6日）上に構築されたセルフホスト型ハーネスは、シェルスクリプトのコールバックを経由せず、メッセージストリームから直接hookイベントをサブスクライブできます。³⁶ ClaudeAgentOptionsにinclude_hook_events=Trueを設定すると、HookEventMessageオブジェクト（PreToolUse、PostToolUse、Stopなど）がアシスタントメッセージやツール結果と同じイテレーターから生成されます。これはTypeScript SDKのincludeHookEventsオプションを反映したもので、同じリリースで同梱のCLIもv2.1.129に更新されました。

イベントストリームパターンは、ハーネスが既にPythonに存在し、モデル出力と同じ制御フローでhookシグナルを扱いたい場合に最適です。シェルスクリプトのhook契約（終了コード、stdin JSON、ディスパッチャー）は、複数のツールを組み合わせるハーネス、Claude CodeとCodexでhookを共有するハーネス、またはブロッキングのために終了コードのセマンティクスを必要とするハーネスにとって、依然として正しい答えとなります。

Effortとセッションの来歴（2026年5月7-8日）

Claude Code v2.1.132およびv2.1.133の2つの追加機能により、hookとサブプロセスは実行コンテキストに関するより良いシグナルを得られるようになりました:³⁸³⁹

• hook入力のeffort.level。 Hookは現在、tool_inputやsession_idを運ぶのと同じ入力でeffort.levelJSONフィールドを受け取ります。同じ値が$CLAUDE_EFFORT環境変数としてエクスポートされるため、BashコマンドはJSONをパースせずに読み取れます。これを使ってhookのコストをeffortティアに合わせてスケールしてください: lowでは高価な検証をスキップし、xhighやmaxでは完全なセキュリティゲートを実行します。
• BashサブプロセスのCLAUDE_CODE_SESSION_ID環境変数。 Bashツールのサブプロセスは現在、hookが見るのと同じsession_id値をCLAUDE_CODE_SESSION_IDとして参照できます。これにより、セッションごとの状態をログに記録するツールにとっての来歴ギャップが解消され、これまでサブプロセスイベントとhookイベントを相関付けることができなかった問題が解決されます。

両シグナルともコード変更なしで利用可能であり、新しいフィールドを無視する既存のhookも引き続き動作します。

メモリとコンテキスト

すべてのAI対話は、有限のコンテキストウィンドウ内で動作します。会話が長くなるにつれて、システムは新しいコンテンツのためのスペースを確保するために、過去のターンを圧縮します。この圧縮は不可逆的なものです。ターン3で文書化されたアーキテクチャ上の決定事項が、ターン15まで残っているとは限りません。⁹

マルチターン崩壊の3つのメカニズム

MSR/Salesforceの研究では、3つの独立したメカニズムが特定されており、それぞれ異なる対処が必要となります。⁹

戦略1：メモリとしてのファイルシステム

コンテキスト境界を越えて最も信頼できるメモリは、ファイルシステム上に存在します。Claude Codeはセッション開始時、および圧縮の後ごとに、CLAUDE.mdとメモリファイルを読み込みます。⁶

~/.claude/
├── configs/           # 14 JSON configs (thresholds, rules, budgets)
│   ├── deliberation-config.json
│   ├── recursion-limits.json
│   └── consensus-profiles.json
├── hooks/             # 95 lifecycle event handlers
├── skills/            # 44 reusable knowledge modules
├── state/             # Runtime state (recursion depth, agent lineage)
├── handoffs/          # 49 multi-session context documents
├── docs/              # 40+ system documentation files
└── projects/          # Per-project memory directories
    └── {project}/memory/
        └── MEMORY.md  # Always loaded into context

MEMORY.mdファイルは、セッションを越えてエラー、決定事項、パターンを記録します。たとえば、bashでset -eが有効なときにVARが0だと((VAR++))が失敗することを発見したら、それを記録しておきます。3セッション後、Pythonで類似の整数のエッジケースに遭遇したとき、MEMORY.mdのエントリがそのパターンを浮かび上がらせてくれるのです。¹⁵

Auto Memory（v2.1.32以降）： Claude Codeは、プロジェクトのコンテキストを自動的に記録・呼び出しします。作業を進めるなかで、Claudeは観察結果を~/.claude/projects/{project-path}/memory/MEMORY.mdに書き込みます。Auto memoryは、セッション開始時に最初の200行をシステムプロンプトに読み込みます。簡潔に保ち、詳細なメモは個別のトピックファイルにリンクするとよいでしょう。⁶

戦略2：プロアクティブな圧縮

Claude Codeの/compactコマンドは、会話を要約し、重要な決定事項、ファイル内容、タスクの状態を保持しながら、コンテキスト領域を解放します。¹⁵

圧縮すべきタイミング： - 個別のサブタスクが完了したとき（機能の実装、バグの修正） - コードベースの新しい領域に着手する前 - Claudeが同じことを繰り返したり、過去のコンテキストを忘れ始めたとき - 集中的なセッション中、おおよそ25〜30分ごと

CLAUDE.md内のカスタム圧縮指示：

# Summary Instructions
When using compact, focus on:
- Recent code changes
- Test results
- Architecture decisions made this session

戦略3：セッションハンドオフ

複数のセッションにまたがるタスクには、完全な状態を捕捉するハンドオフドキュメントを作成します。

## Handoff: Deliberation Infrastructure PRD-7
**Status:** Hook wiring complete, 81 Python unit tests passing
**Files changed:** hooks/post-deliberation.sh, hooks/deliberation-pride-check.sh
**Decision:** Placed post-deliberation in PostToolUse:Task, pride-check in Stop
**Blocked:** Spawn budget model needs inheritance instead of depth increment
**Next:** PRD-8 integration tests in tests/test_deliberation_lib.py

Status/Files/Decision/Blocked/Nextという構造は、最小限のトークンコストで、後続のセッションに完全なコンテキストを引き継いでくれます。claude -c（continue）で新しいセッションを開始するか、ハンドオフドキュメントを読むだけで、すぐに実装に取りかかれるのです。¹⁵

戦略4：フレッシュコンテキスト反復（Ralphループ）

60〜90分を超えるセッションでは、反復ごとに新しいClaudeインスタンスを起動しましょう。状態は会話のメモリではなく、ファイルシステムを通じて永続化されます。各反復で、コンテキスト予算をフルに使えるのです。¹⁶

Iteration 1: [200K tokens] -> writes code, creates files, updates state
Iteration 2: [200K tokens] -> reads state from disk, continues
Iteration 3: [200K tokens] -> reads updated state, continues
...
Iteration N: [200K tokens] -> reads final state, verifies criteria

これを単一の長時間セッションと比較してみましょう。

Minute 0:   [200K tokens available] -> productive
Minute 30:  [150K tokens available] -> somewhat productive
Minute 60:  [100K tokens available] -> degraded
Minute 90:  [50K tokens available]  -> significantly degraded
Minute 120: [compressed, lossy]     -> errors accumulate

反復ごとにフレッシュコンテキストを使うアプローチは、オリエントステップ（状態ファイルの読み込み、git履歴のスキャン）に15〜20%のオーバーヘッドを支払う代わりに、反復ごとに完全な認知リソースを得られます。¹⁶ コストとベネフィットの計算は次の通りです。60分未満のセッションでは、単一の会話のほうが効率的です。90分を超えると、オーバーヘッドがあってもフレッシュコンテキストのほうが高品質な出力を生み出します。

戦略5：マネージドメモリのキュレーション（Dreaming）

AnthropicのClaude Managed Agentsでは、2026年5月6日にResearch PreviewとしてDreamingが追加されました。³⁵ Anthropicによれば、「Dreamingはエージェントセッションとメモリストアをレビューし、パターンを抽出し、メモリをキュレーションするスケジュール済みプロセスであり、エージェントが時間とともに改善されていきます」とのことです。³⁵

Dreamingはセッション間でバックグラウンド実行され、クリティカルパス上にはありません。ファイルシステムをメモリとして使うパターンを置き換えるのではなく、補完するものです。MEMORY.mdファイルは依然として中核となる接地面であり、DreamingはキュレーションされたメモリエントリをManaged Agentsのメモリストアに書き込み、エージェントがセッション開始時にそれを読み込みます。この2つのパターンは、セルフホストのファイルシステム状態とマネージド側のキュレーションを組み合わせるハーネスにおいて共存します。

DreamingはResearch Previewのため、挙動が変わる可能性があります。上記で文書化したセッションハンドオフとCLAUDE.mdのパターンは、セルフホストハーネスにとって信頼できるメモリメカニズムであり続けます。

アンチパターン

10行で済むときに、ファイル全体を読み込む。 2,000行のファイルを1回読み込むだけで、15,000〜20,000トークンを消費します。行オフセットを使いましょう。Read file.py offset=100 limit=20なら、そのコストの大部分を節約できます。¹⁵

冗長なエラー出力をコンテキストに保持し続ける。 バグをデバッグした後、コンテキストには失敗した反復から40件以上のスタックトレースが残っているものです。バグ修正後に/compactを1回実行すれば、そのデッドウェイトを解放できます。

毎セッション、すべてのファイルを読み込むことから始める。 Claude Codeのglobとgrepツールに任せて、必要に応じて関連ファイルを見つけさせましょう。これで不要な事前読み込みのトークンを10万以上節約できます。¹⁵

サブエージェントパターン

サブエージェントは、複雑なタスクを独立して処理する特化型のClaudeインスタンスです。クリーンなコンテキスト（メイン会話からの汚染なし）で開始し、指定されたツールで動作し、結果を要約として返します。探索結果はメイン会話を肥大化させず、結論のみが返されます。⁵

組み込みサブエージェントタイプ

カスタムサブエージェントの作成

サブエージェントは .claude/agents/（プロジェクト）または ~/.claude/agents/（個人）で定義します。

---
name: security-reviewer
description: Expert security code reviewer. Use PROACTIVELY after any code
  changes to authentication, authorization, or data handling.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

You are a senior security engineer reviewing code for vulnerabilities.

When invoked:
1. Identify the files that were recently changed
2. Analyze for OWASP Top 10 vulnerabilities
3. Check for secrets, hardcoded credentials, SQL injection
4. Report findings with severity levels and remediation steps

Focus on actionable security findings, not style issues.

サブエージェント設定フィールド

Worktree 隔離

サブエージェントは一時的な git worktree で動作でき、リポジトリの完全に隔離されたコピーが提供されます。⁵

---
name: experimental-refactor
description: Attempt risky refactoring in isolation
isolation: worktree
tools: Read, Write, Edit, Bash, Grep, Glob
---

You have an isolated copy of the repository. Make changes freely.
If the refactoring succeeds, the changes can be merged back.
If it fails, the worktree is discarded with no impact on the main branch.

Worktree 隔離は、コードベースを破損させる可能性のある実験的な作業に不可欠です。

並列サブエージェント

互いに調整する必要がない独立した調査タスクには、並列サブエージェントを使用します。⁵

> Have three explore agents search in parallel:
> 1. Authentication code
> 2. Database models
> 3. API routes

各エージェントは独自のコンテキストウィンドウで実行され、関連するコードを見つけて要約を返します。メインコンテキストはクリーンに保たれます。

再帰ガード

スポーン制限がないと、エージェントがエージェントに委任し、さらにそのエージェントに委任するという連鎖が発生し、それぞれがコンテキストを失いトークンを消費します。再帰ガードパターンは予算を強制します。¹⁶

#!/bin/bash
# recursion-guard.sh — enforce spawn budget
CONFIG_FILE="${HOME}/.claude/configs/recursion-limits.json"
STATE_FILE="${HOME}/.claude/state/recursion-depth.json"

MAX_DEPTH=2
MAX_CHILDREN=5
DELIB_SPAWN_BUDGET=2
DELIB_MAX_AGENTS=12

# Read current depth
current_depth=$(jq -r '.depth // 0' "$STATE_FILE" 2>/dev/null)

if [[ "$current_depth" -ge "$MAX_DEPTH" ]]; then
    echo "BLOCKED: Maximum recursion depth ($MAX_DEPTH) reached" >&2
    exit 2
fi

# Increment depth using safe arithmetic (not ((VAR++)) with set -e)
new_depth=$((current_depth + 1))
jq --argjson d "$new_depth" '.depth = $d' "$STATE_FILE" > "${STATE_FILE}.tmp"
mv "${STATE_FILE}.tmp" "$STATE_FILE"

重要な教訓: 深さ制限だけでなく、スポーン予算を使用してください。深さベースの制限は親子チェーン（深さ 3 でブロック）を追跡しますが、幅は見逃します。深さ 1 にエージェントが 23 個あっても、それは依然として「深さ 1」です。スポーン予算は、親ごとのアクティブな子の総数を追跡し、設定可能な最大値で上限を設けます。予算モデルは、プロキシメトリック（ネストレベルが多すぎる）ではなく、実際の失敗モード（エージェントの総数が多すぎる）にマッピングされます。⁷

Agent Teams（リサーチプレビュー）

Agent Teams は、独立して動作する複数のClaude Codeインスタンスを連携させ、共有メールボックスとタスクリストを介して通信し、互いの調査結果に異議を唱えることができます。⁵

有効化方法: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Agent Teams とサブエージェントの使い分け:

マルチエージェントオーケストレーション

シングルエージェントのAIシステムには構造的な盲点があります。自身の前提を検証できないという点です。⁷ マルチエージェントによる審議では、意思決定が確定する前に、複数の視点から独立した評価を強制的に行います。

クロスツール・オーケストレーション（2026年4月）： Googleは4月7日に Scion をオープンソース化しました。Claude Code、Gemini CLI、その他の「ディープエージェント」を並行プロセスとして実行するマルチエージェント・ハイパーバイザーで、各エージェントには分離されたコンテナ、git worktree、認証情報が割り当てられます。ローカル、ハブ、またはKubernetesで動作します。明示的な思想は「制約よりも分離」というもので、エージェントはプロンプト内ではなくインフラ層で強制される境界の内側で、高い自律性を持って動作します。²⁵ これは subagent-isolation の主張を異なるツールベンダー間にまで直接拡張するものです。ワークフローが Claude とOpenAIモデルにまたがる場合、Scion はエージェント単位の worktree と認証情報の分離を備えたクロスツール subagent の最初の実用的なリファレンス実装です。

ディベートは万能薬ではありません： M3MAD-Bench研究クラスター（2026年初頭）では、マルチエージェント・ディベートには頭打ちがあり、誤解を招くコンセンサスによって覆される可能性があることが判明しました。妥当な議論であっても、他のエージェントが自信たっぷりに誤った答えを主張すると敗れてしまうのです。²⁶ Tool-MADはこの点を改善しており、各エージェントに異種のツールアクセスを与え、判定段階でFaithfulness（忠実度）/Relevance（関連性）スコアを使用します。ディベート型のオーケストレーションを構築する場合は、（a）エージェントごとのツールの異質性と、（b）「エージェントを増やせば答えが良くなる」と仮定するのではなく定量的な判定スコアリング、この2点に投資しましょう。

マネージド・マルチエージェント・オーケストレーションとOutcomes（パブリックベータ）

以下に述べる審議インフラを自前で構築したくない場合、Multiagent Orchestration が2026年5月6日に Claude Managed Agents でパブリックベータに入りました。³⁵ Anthropic によれば「単一エージェントではうまくこなせないほどの作業がある場合、マルチエージェント・オーケストレーションでは、リードエージェントがジョブを分割し、それぞれを独自のモデル、プロンプト、ツールを持つスペシャリストに委譲できます」とのことです。³⁵ スペシャリストは「共有ファイルシステム上で並行して作業し、リードエージェントの全体的なコンテキストに貢献します」。³⁵

トレーシングは標準で組み込まれています。Anthropic によれば「Claude Console ですべてのステップをトレースすることもできます。どのエージェントが、どの順序で、なぜ何を行ったのかが分かり、タスクがどのように委譲・実行されたかを完全に可視化できます」。³⁵

これと組み合わさるパブリックベータ機能が Outcomes です。Anthropic によれば「成功とは何かを記述したルーブリックを書くと、エージェントはそれに向けて作業します。別個のグレーダー（採点者）が、独立したコンテキストウィンドウであなたの基準に照らして出力を評価するため、エージェントの推論に影響を受けることがありません」。³⁵ これは、本セクションの後半で説明する2ゲート検証パターンのマネージドサービス版です。手書きのゲートをルーブリックが置き換え、コンセンサス・バリデーターを別個のグレーダーが置き換えます。

セルフホスト型審議が正解となるのは、検証を自前のフック面（PreToolUse のブロッキング、終了コードのセマンティクス、カスタムディスパッチャー）と統合する必要がある場合や、harness が外部依存なしで動作しなければならない場合です。Managed Multiagent が正解となるのは、標準的な委譲とルーブリックによる採点こそが実際に必要な契約である場合です。

最小実用審議（Minimum Viable Deliberation）

2エージェントと1つのルールから始めましょう。エージェントは互いの作業を見る前に、独立して評価しなければならないというルールです。⁷

Decision arrives
  |
  v
Confidence check: is this risky, ambiguous, or irreversible?
  |
  +-- NO  -> Single agent decides (normal flow)
  |
  +-- YES -> Spawn 2 agents with different system prompts
             Agent A: "Argue FOR this approach"
             Agent B: "Argue AGAINST this approach"
             |
             v
             Compare findings
             |
             +-- Agreement with different reasoning -> Proceed
             +-- Genuine disagreement -> Investigate the conflict
             +-- Agreement with same reasoning -> Suspect herding

このパターンで価値の80%をカバーできます。それ以外はすべて段階的な改善にすぎません。

コンフィデンス・トリガー

すべてのタスクに審議が必要なわけではありません。コンフィデンス・スコアリング・モジュールは4つの次元を評価します。¹⁷

1. 曖昧さ - クエリには複数の有効な解釈があるか？
2. ドメインの複雑さ - 専門知識を必要とするか？
3. 重要度（Stakes） - 意思決定は可逆か？
4. コンテキスト依存性 - より広範なシステムへの理解を必要とするか？

スコアは3つのレベルに対応します。

しきい値はタスクの種類に応じて適応します。セキュリティに関する意思決定では0.85のコンセンサスが必要です。ドキュメントの変更では0.50で十分です。これにより単純なタスクの過剰設計を防ぎつつ、リスクのある意思決定にはきちんと精査が入るようにします。⁷

ステートマシン

7つのフェーズがあり、それぞれが前段階によってゲートされます。⁷

IDLE -> RESEARCH -> DELIBERATION -> RANKING -> PRD_GENERATION -> COMPLETE
                                                                    |
                                                              (or FAILED)

RESEARCH： 独立したエージェントがトピックを調査します。各エージェントには異なるペルソナ（Technical Architect、Security Analyst、Performance Engineer、その他）が割り当てられます。コンテキストの分離により、リサーチ中にエージェントが互いの発見を見られないようにします。

DELIBERATION： エージェントはすべてのリサーチ結果を見て、代替案を生成します。Debate エージェントが矛盾を特定します。Synthesis エージェントが矛盾しない発見を統合します。

RANKING： 各エージェントは、提案されたすべてのアプローチを5つの加重次元で採点します。

2ゲート検証アーキテクチャ

2つの検証ゲートが、異なる段階で問題を捕捉します。⁷

ゲート1：コンセンサス検証（PostToolUse フック）。各審議エージェントが完了した直後に実行されます。 1. フェーズが少なくともRANKINGに到達していること 2. 最低2エージェントが完了していること（設定可能） 3. コンセンサススコアがタスク適応型のしきい値を満たすこと 4. 反対したエージェントがいた場合、その懸念が文書化されていること

ゲート2：プライドチェック（Stop フック）。セッションが終了する前に実行されます。 1. 多様な手法：複数のユニークなペルソナが代表されている 2. 矛盾の透明性：反対意見には文書化された理由がある 3. 複雑性への対応：少なくとも2つの代替案が生成されている 4. コンセンサスの確信度：strong（0.85超）またはmoderate（0.70-0.84）に分類されている 5. 改善のエビデンス：最終コンフィデンスが初期コンフィデンスを上回っている

ライフサイクルの異なる時点に2つのフックを置く構成は、実際に発生する障害の在り方に合致しています。瞬時に分かるもの（スコアの低さ）もあれば、徐々に明らかになるもの（多様性の欠如、反対意見の文書化漏れ）もあります。⁷

なぜ合意は危険なのか

Charlan Nemeth は1986年から少数派の異議について研究を続け、2018年の著書 In Defense of Troublemakers に結実させました。反対者がいるグループは、すぐに合意に至るグループよりも優れた意思決定を行います。反対者は正しくある必要はありません。異議を唱えるという行為そのものが、多数派に対し本来なら飛ばしてしまう前提の検証を強いるのです。¹⁸

Wu らは LLM エージェントが本当にディベートできるかを検証し、不一致への構造的なインセンティブがなければ、エージェントは正しさにかかわらず最も自信ありげに聞こえる初期回答へ収束していくことを発見しました。¹⁹ Liang らはその根本原因を「Degeneration-of-Thought（思考の退化）」と特定しました。一度 LLM がある立場に確信を抱くと、自己内省では新しい反論を生成できなくなり、マルチエージェント評価が構造的に必要となるのです。²⁰

独立性こそが決定的な設計上の制約です。同じデプロイ戦略を、互いの発見が見える状態で評価した2つのエージェントのスコアは0.45と0.48でした。同じエージェントを互いに見えない状態で動かすと、スコアは0.45と0.72に広がりました。0.48と0.72の差こそ、群れ行動（herding）のコストなのです。⁷

偽の合意を検出する

コンフォーミティ検出モジュールは、エージェントが本物の評価なしに同意していることを示すパターンを追跡します。⁷

スコアのクラスタリング： 10点満点のスケールで全エージェントのスコアが0.3ポイント以内に収まるのは、独立した評価ではなく共有コンテキストの汚染を示すシグナルです。認証リファクタリングを評価した5エージェント全員のセキュリティリスクスコアが7.1〜7.4に収まっていた事例で、新鮮なコンテキスト分離で再実行したところ、スコアは5.8〜8.9に分散しました。

ボイラープレート反対意見： エージェントが独立した異論を生成する代わりに、互いの懸念表現をコピーしている状態です。

少数派視点の不在： 優先順位が衝突するペルソナ（Security Analyst と Performance Engineer がすべてに同意することは稀です）からの全会一致の承認。

コンフォーミティ検出は分かりやすいケース（エージェントが早く収束しすぎる審議のおよそ10〜15%）を捕捉します。残りの85〜90%については、コンセンサスゲートとプライドチェックゲートが十分な検証を提供します。

審議でうまくいかなかったこと

自由形式のディベートラウンド。 データベースのインデックス設計議論で3ラウンドの往復テキストを行ったところ、7,500トークン分のディベートが生まれました。ラウンド1：本物の不一致。ラウンド2：立場の言い直し。ラウンド3：同じ主張を別の言葉で。構造化された次元スコアリングが自由形式のディベートを置き換え、コストを60%削減しつつランキング品質を向上させました。⁷

単一の検証ゲート。 最初の実装ではセッション終了時に1つの検証フックを実行していました。あるエージェントは0.52のコンセンサススコア（しきい値以下）で審議を完了し、その後20分間も無関係なタスクを続けてからセッション終了フックが失敗を検知しました。これを2つのゲート（タスク完了時と、セッション終了時）に分割することで、同じ問題を異なるライフサイクル時点で捕捉できるようになりました。⁷

審議のコスト

各リサーチエージェントは約5,000トークンのコンテキストを処理し、2,000〜3,000トークンの調査結果を生成します。3エージェントなら、意思決定あたり追加で15,000〜24,000トークン。10エージェントならおよそ50,000〜80,000トークンとなります。⁷

現行のOpus料金では、3エージェント審議のコストはおよそ $0.68〜0.90、10エージェント審議は $2.25〜3.00 です。本システムは意思決定のおよそ10%で審議をトリガーするため、全意思決定にわたって平均化したコストはセッションあたり $0.23〜0.30 となります。これに見合うかどうかは、誤った意思決定がどれだけのコストを生むかに依存します。

審議すべき場面

CLAUDE.md の設計

CLAUDE.md は AI エージェント向けの運用ポリシーであり、人間向けの README ではありません。²¹ エージェントは、conventional commits を使う理由を理解する必要はありません。エージェントが知るべきなのは、実行すべき正確なコマンドと「完了」の定義です。

優先順位の階層

ルールファイルは自動的に読み込まれ、CLAUDE.md を煩雑にすることなく構造化されたコンテキストを提供します。⁶

無視されるもの

以下のパターンは、エージェントの動作にほぼ確実に観測可能な変化を生みません。²¹

コマンドのない散文段落。「私たちはクリーンでテスト済みのコードを大切にしています」はドキュメントであり、運用指示ではありません。エージェントはこれを読んでも、実行可能な指示がないためテストなしでコードを書き続けます。

曖昧な指示。「データベースマイグレーションには注意してください」は制約ではありません。「マイグレーションを適用する前に alembic check を実行してください。ダウングレードパスがない場合は中止してください」は制約です。

矛盾する優先事項。「素早く動いて速くデプロイする」「包括的なテストカバレッジを確保する」「実行時間を 5 分以内に保つ」「すべてのコミット前にフルの統合テストを実行する」。エージェントはこれら 4 つを同時に満たすことができず、デフォルトで検証をスキップします。²¹

強制力のないスタイルガイド。「Google Python Style Guide に従う」と書いても、ruff check --select D がなければエージェントには遵守を検証する手段がありません。

機能するもの

コマンド優先の指示:

## Build and Test Commands
- Install: `pip install -r requirements.txt`
- Lint: `ruff check . --fix`
- Format: `ruff format .`
- Test: `pytest -v --tb=short`
- Type check: `mypy app/ --strict`
- Full verify: `ruff check . && ruff format --check . && pytest -v`

完了の定義:

## Definition of Done
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
4. Changed files have been staged and committed
5. Commit message follows conventional format: `type(scope): description`

タスク別に整理されたセクション:

## When Writing Code
- Run `ruff check .` after every file change
- Add type hints to all new functions

## When Reviewing Code
- Check for security issues: `bandit -r app/`
- Verify test coverage: `pytest --cov=app --cov-fail-under=80`

## When Releasing
- Update version in `pyproject.toml`
- Run full suite: `pytest -v && ruff check . && mypy app/`

エスカレーションルール:

## When Blocked
- If tests fail after 3 attempts: stop and report the failing test with full output
- If a dependency is missing: check `requirements.txt` first, then ask
- Never: delete files to resolve errors, force push, or skip tests

記述順序

ゼロから始める場合は、以下の優先順序でセクションを追加してください。²¹

1. ビルドとテストコマンド（エージェントが有用な作業をする前に必要）
2. 完了の定義（誤った完了報告を防ぐ）
3. エスカレーションルール（破壊的な回避策を防ぐ）
4. タスク別に整理されたセクション（無関係な指示の解析を減らす）
5. ディレクトリスコープ（モノレポ：サービスごとの指示を分離する）

最初の 4 つが機能するまで、スタイルの好みは後回しにしましょう。

ファイルのインポート

CLAUDE.md 内から他のファイルを参照できます。

See @README.md for project overview
Coding standards: @docs/STYLE_GUIDE.md
API documentation: @docs/API.md
Personal preferences: @~/.claude/preferences.md

インポート構文：相対パス（@docs/file.md）、絶対パス（@/absolute/path.md）、ホームディレクトリ（@~/.claude/file.md）。最大深度はインポート 5 階層までです。⁶

ツール間の指示互換性

AGENTS.md は、すべての主要な AI コーディングツールが認識するオープン標準です。²¹ チームで複数のツールを使用している場合は、AGENTS.md を正規のソースとして記述し、関連するセクションをツール固有のファイルにミラーリングしてください。

AGENTS.md のパターン（コマンド優先、完了定義、タスク別整理）は、ツールに関わらずあらゆる指示ファイルで機能します。乖離していく並行した指示セットを維持してはいけません。権威ある単一のソースを書き、ミラーリングしましょう。

Codex との同等性に関する注記

Codex は主要な harness レイヤーすべてに対してファーストクラスの同等機能を備えるようになりましたが、移行はファイルコピーではなくパターンの翻訳です。Codex は作業開始前に AGENTS.md を読み、~/.codex のグローバルガイダンスをプロジェクトおよびネストされたリポジトリの指示と重ねて適用します。³¹ Codex の skills は同じ SKILL.md メンタルモデルとプログレッシブディスクロージャーを使用します。Codex はまず skill 名、説明、ファイルパスから始め、使用を決定したときにのみ完全な skill を読み込みます。³² Codex はネイティブの hooks、プラグインバンドル hooks、マネージド hooks、MCP サポート、明示的な subagent ワークフローも備えています。³³³⁴

実用的なマッピングは以下のとおりです。

重要な違い：Claude subagents は説明から自動的に選択できますが、Codex は現在 subagent ワークフローを明示的なものとしてドキュメント化しています。そのため、Codex において常時稼働の harness 動作には skills と hooks がデフォルトとして適切であり、subagents は意図的な並列作業、レビュー、探索のためのものです。

指示のテスト

エージェントが実際に指示を読み、それに従っているか検証してください。

# Check active instructions
claude --print "What instructions are you following for this project?"

# Verify specific rules are active
claude --print "What is your definition of done?"

決定的なテスト： エージェントにビルドコマンドを説明するよう求めてください。一字一句正確に再現できない場合、指示が冗長すぎる（コンテキストから押し出されている）、曖昧すぎる（エージェントが実行可能な指示を抽出できない）、または発見されていないかのいずれかです。GitHub による 2,500 リポジトリの分析では、曖昧さがほとんどの失敗の原因であることが判明しています。²¹

プロダクションパターン

Opus 4.7のロングホライズンパターン（2026年4月）

Claude Opus 4.7（2026年4月16日）には、ハーネスが防御すべき対象を変える特定の機能が搭載されています。²⁹

• ツール障害への耐性： Opus 4.7は、Opus 4.6のセッションを停止させていたツール障害を乗り越えて処理を継続します。サブエージェントコード内の防御的なリトライラッパーは削減できます（ただし完全には排除できません）。フックレベルのガードは残しつつ、プロンプト内の「ツールが失敗したら3回再試行する」といったスキャフォールディングは削ぎ落としましょう。
• xhighエフォート層（Opus-4.7専用）： highとmaxの中間に位置します。コーディングおよびエージェント型ワークロードの推奨デフォルトです。長時間稼働するサブエージェントでは、xhighはhighを有意に上回り、トークンコストの増加は比例以下に抑えられます。maxは単発の難しい推論タスクに依然として適していますが、持続的なタスクにはxhighが優れています。
• トークン予算の上限： output_config.task_budget（ベータヘッダーtask-budgets-2026-03-13）を介して、エージェント実行ごとに設定可能です。モデルは残り時間カウントダウンを参照し、突然枯渇するのではなく、予算内に作業をうまく収めます。短いプロンプトの品質を犠牲にすることなく、トークン消費を予測可能にしたいエージェントループに使用してください。
• 暗黙的ニーズの認識： 「暗黙的ニーズ」テストに合格した最初のClaudeモデルです。ユーザーの文字通りのリクエストが、実際に必要なものを十分に表現していない場合を認識します。これにより、CLAUDE.mdの「明確化ルール」セクションの必要性が低下します。CLAUDE.mdが「ユーザーがYを求めたときにはXも考慮する」といったガードレールで200行に及ぶ場合、ネイティブにカバーされるようになったものを削除しましょう。

Worktreeベース、サンドボックスパス、管理者設定（2026年5月7日）

Claude Code v2.1.133では、プロダクションハーネスにとって把握しておく価値のある管理者層の設定が4つ追加されました。³⁹

worktree.baseRefの差し戻しは、ユーザーに注意喚起すべき点です。v2.1.128～v2.1.132の動作（worktreeがローカルHEADから分岐する）に依存していたエージェントは、明示的にオプトインしない限り、新しいworktreeで未プッシュの作業にアクセスできなくなります。

クオリティループ

すべての非自明な変更に対する必須のレビュープロセスです。

1. 実装 - コードを書く
2. レビュー - すべての行を読み直す。タイポ、ロジックエラー、不明瞭な箇所をキャッチする
3. 評価 - エビデンスゲートを実行する。パターン、エッジケース、テストカバレッジを確認する
4. 改善 - すべての問題を修正する。「後回し」にしてはならない
5. ズームアウト - 統合ポイント、インポート、隣接コードのリグレッションを確認する
6. 繰り返し - エビデンスゲートのいずれかの基準が失敗したら、ステップ4に戻る
7. 報告 - 何が変わったか、どう検証したかをリストアップし、具体的なエビデンスを引用する

エビデンスゲート

「だと思う」や「〜のはずだ」はエビデンスではありません。ファイルパス、テスト出力、または具体的なコードを引用してください。

いずれかの行のエビデンスを提示できない場合は、改善ステップに戻ってください。²²

エラーハンドリングパターン

アトミックなファイル書き込み。 複数のエージェントが同じステートファイルに同時に書き込むと、JSONが破損します。.tmpファイルに書き込んでから、mvでアトミックに移動しましょう。OSは同一ファイルシステム上でmvがアトミックであることを保証します。¹⁷

# Atomic state update
jq --argjson d "$new_depth" '.depth = $d' "$STATE_FILE" > "${STATE_FILE}.tmp"
mv "${STATE_FILE}.tmp" "$STATE_FILE"

ステート破損からの復旧。 ステートが破損した場合、復旧パターンはクラッシュするのではなく、安全なデフォルト値から再構築します。¹⁶

if ! jq -e '.depth' "$RECURSION_STATE_FILE" &>/dev/null; then
    # Corrupted state file, recreate with safe defaults
    echo '{"depth": 0, "agent_id": "root", "parent_id": null}' > "$RECURSION_STATE_FILE"
    echo "- Recursion state recovered (was corrupted)"
fi

((VAR++))のbashトラップ。 ((VAR++))は、VARが0のときに終了コード1を返します。0++が0と評価され、bashはそれをfalseとして扱うためです。set -eが有効になっていると、これがスクリプトを終了させます。代わりにVAR=$((VAR + 1))を使用してください。¹⁶

ブラスト半径の分類

すべてのエージェントアクションをブラスト半径で分類し、それに応じてゲートを設けましょう。²

リモートコントロール（任意のブラウザやモバイルアプリからローカルのClaude Codeに接続する機能）により、「外部」ゲートはブロッキング待機から非同期通知へと変わります。エージェントは次のタスクに取り組み続け、その間にスマートフォンから前のタスクをレビューできます。²

自律実行のためのタスク仕様

効果的な自律タスクには、目的、完了基準、コンテキストポインターという3つの要素が含まれます。¹⁶

OBJECTIVE: Implement multi-agent deliberation with consensus validation.

COMPLETION CRITERIA:
- All tests in tests/test_deliberation_lib.py pass (81 tests)
- post-deliberation.sh validates consensus above 70% threshold
- recursion-guard.sh enforces spawn budget (max 12 agents)
- No Python type errors (mypy clean)

CONTEXT:
- Follow patterns in lib/deliberation/state_machine.py
- Consensus thresholds in configs/deliberation-config.json
- Spawn budget model: agents inherit budget, not increment depth

基準はマシンによって検証可能でなければなりません。テストの合否、リンターの出力、HTTPステータスコード、ファイル存在チェックなどです。あるエージェントに「通るテストを書いて」と頼んだ初期のタスクでは、assert Trueやassert 1 == 1が生成されました。技術的には正しい。実用的には無価値です。¹⁶

注意すべき失敗モード

具体的なセッショントレース

5つのストーリーを含むPRDを処理する自律実行のセッショントレースです。²

1. SessionStartが発火。 ディスパッチャーが現在の日付、プロジェクト検出、哲学的制約、コスト追跡の初期化を注入します。フック5個、合計180ms。

2. エージェントがPRDを読み、最初のストーリーを計画。 UserPromptSubmitが発火します。ディスパッチャーがアクティブなプロジェクトコンテキストとセッションドリフトのベースラインを注入します。

3. エージェントがBashを呼び出してテストを実行。 PreToolUse:Bashが発火します。クレデンシャルチェック、サンドボックス検証、プロジェクト検出。90ms。テストが実行されます。PostToolUse:Bashが発火し、アクティビティのハートビートが記録され、ドリフトチェックが行われます。

4. エージェントがWriteを呼び出してファイルを作成。 PreToolUse:Writeが発火し、ファイルスコープチェックが行われます。PostToolUse:Writeが発火し、リントチェックとコミット追跡が行われます。

5. エージェントがストーリーを完了。 Stopが発火します。クオリティゲートが確認します。エージェントはエビデンスを引用したか？曖昧な表現はないか？差分にTODOコメントはないか？いずれかのチェックが失敗すると、exit 2となりエージェントは続行します。

6. 独立した検証： 新しいエージェントが、前のエージェントの自己申告を信用せずにテストスイートを実行します。

7. 3つのコードレビューエージェントが並列で起動。 それぞれが差分を独立してレビューします。いずれかのレビュアーがCRITICALをフラグした場合、ストーリーはキューに戻されます。

8. ストーリーがパス。次のストーリーをロード。 このサイクルが5つのストーリーすべてで繰り返されます。

5つのストーリーで発火したフックの合計：約340個。フック内で消費した合計時間：約12秒。このオーバーヘッドにより、たった1回の徹夜実行で、3件のクレデンシャル漏洩、1件の破壊的コマンド、2件の不完全な実装を防ぎました。

ケーススタディ：徹夜のPRD処理

あるプロダクションハーネスは、8回の徹夜セッションにわたって12個のPRD（47ストーリー）を処理しました。指標は最初の4個のPRD（最小限のハーネス：CLAUDE.mdのみ）と、最後の8個（フルハーネス：フック、skills、クオリティゲート、マルチエージェントレビュー）を比較しています。

2件のクレデンシャル漏洩では、APIキーのローテーションと下流サービスの監査が必要となり、おおよそ4時間のインシデント対応となりました。同等の事象を防いだハーネスのオーバーヘッドは、ストーリーあたり2.4秒のbashにすぎません。誤完了率が35%から4%に低下したのは、Stopフックがエージェントに完了報告を許可する前に独立してテストを実行したためです。

セキュリティに関する考慮事項

信頼できるエージェントの5原則（Anthropic、2026年4月）

Anthropicは2026年4月9日、エージェントの信頼性に関する正式なフレームワークを公開しました。²⁷ この5原則は、本ガイドのEvidence Gateの考え方と並行し、さらに拡張するものです。

Anthropicはまた、MCPをLinux FoundationのAgentic AI Foundationに寄贈し、AGENTS.md（現在はOpenAI、Google、Cursor、Factory、Sourcegraphとの共同管理）に加わりました。エージェントの相互運用性標準は、ベンダーニュートラルなものとなったのです。²⁷

skillサンドボックスツール： skillsを攻撃対象領域として扱うチーム向けに、PermisoのSandyClaw（2026年4月2日リリース）は、専用サンドボックスでskillsを実行し、Sigma/YARA/Nova/Snort検出によるエビデンスベースの判定を提供します。skillサンドボックスカテゴリーでの初の製品です。²⁸

サンドボックス

Claude Codeはオプションのサンドボックスモード（settings.jsonまたは/sandboxコマンドで有効化）をサポートしており、OSレベルの分離（macOSではseatbelt、Linuxではbubblewrap）を使用してネットワークアクセスとファイルシステム操作を制限します。有効にすると、サンドボックスはモデルが任意のネットワークリクエストを行ったり、プロジェクトディレクトリ外のファイルにアクセスしたりすることを防ぎます。サンドボックスを使用しない場合、Claude Codeは個別のツール呼び出しを承認または拒否する権限ベースのモデルを使用します。¹³

権限境界

権限システムは、複数のレベルで操作をゲートします。

プロンプトインジェクション対策

skillsとhooksは、プロンプトインジェクションに対する多層防御を提供します。

ツール制限付きのskillsは、侵害されたプロンプトが書き込みアクセスを取得することを防ぎます。

allowed-tools: Read, Grep, Glob

PreToolUse hooksは、モデルがどのようにプロンプトされたかに関わらず、すべてのツール呼び出しを検証します。

# Block credential file access regardless of prompt
if echo "$FILE_PATH" | grep -qE "\.(env|pem|key|credentials)$"; then
    echo "BLOCKED: Sensitive file access" >&2
    exit 2
fi

subagentの分離は影響範囲を制限します。permissionMode: planのsubagentは、プロンプトが侵害されても変更を加えることはできません。

hookセキュリティ

環境変数をヘッダーに挿入するHTTP hooksでは、任意の環境変数の漏洩を防ぐため、明示的なallowedEnvVarsリストが必要です。¹³

{
  "type": "http",
  "url": "https://api.example.com/notify",
  "headers": {
    "Authorization": "Bearer $MY_TOKEN"
  },
  "allowedEnvVars": ["MY_TOKEN"]
}

人間とエージェントの責任分担

エージェントアーキテクチャにおけるセキュリティには、人間とエージェントの責任の明確な分担が必要です。¹⁷

パターンはこうです。人間は、組織的なコンテキスト、倫理的判断、戦略的方向性を必要とする意思決定を担います。エージェントは、大規模な可能性空間に対する計算的探索を必要とする意思決定を担います。hooksがその境界を執行するのです。

再帰的なhook執行

hooksはsubagentのアクションに対しても発火します。¹³ ClaudeがAgent toolを介してsubagentをスポーンすると、PreToolUseおよびPostToolUse hooksは、そのsubagentが使用するすべてのツールに対して実行されます。再帰的なhook執行がなければ、subagentが安全ゲートをバイパスできてしまいます。SubagentStopイベントでは、subagentが完了したときにクリーンアップやバリデーションを実行できます。

これはオプションではありません。セキュリティhooksなしでsubagentをスポーンするエージェントとは、メイン会話ではゲートが見守る一方で、mainへのフォースプッシュ、認証情報ファイルの読み取り、破壊的コマンドの実行ができてしまうエージェントなのです。

アーキテクチャとしてのコスト

コストはアーキテクチャ上の意思決定であり、運用上の後付けではありません。² 3つのレベルがあります。

トークンレベル。 システムプロンプトの圧縮です。チュートリアル的なコード例を削除し（モデルはAPIを理解しています）、ファイル間で重複するルールを統合し、説明を制約に置き換えます。「機密パスにマッチするツール呼び出しを拒否する」は、認証情報を読み取るべきでない理由を15行で説明するのと同じ働きをします。

エージェントレベル。 長い会話よりも新しいスポーンを優先します。自律実行における各ストーリーは、クリーンなコンテキストを持つ新しいエージェントを取得します。各エージェントが新しく開始するため、コンテキストが膨らむことはありません。メモリではなくブリーフィングを使うのです。モデルは、累積された30ステップのコンテキストをナビゲートするよりも、明確なブリーフィングをよりよく実行するものです。

アーキテクチャレベル。 操作がステートレスな場合は、MCPよりもCLIファーストを優先します。ワンショット評価のためのclaude --print呼び出しはコストが低く、接続オーバーヘッドも追加しません。MCPは、ツールが永続的な状態やストリーミングを必要とする場合に意味を持ちます。

意思決定フレームワーク

各メカニズムをいつ使うか。

Skills vs Hooks vs Subagents

FAQ

フックは何個までなら多すぎになりますか？

制約となるのはパフォーマンスであり、個数ではありません。各フックは同期的に実行されるため、フックの合計実行時間は、マッチしたツール呼び出しのたびに加算されます。ユーザーレベルとプロジェクトレベルの設定にまたがる95個のフックでも、各フックが200ms以内で完了すれば、目立った遅延なく動作します。注意すべき閾値は次のとおりです。PostToolUseフックがファイル編集ごとに500ms以上を追加する場合、セッションは重く感じられます。デプロイ前に time を使ってフックをプロファイリングしましょう。¹⁴

フックで Claude Code がコマンドを実行するのをブロックできますか？

はい、できます。PreToolUseフックは終了コード2で終了することで、任意のツール動作をブロックします。Claude Code は保留中の動作をキャンセルし、フックのstderr出力をモデルに表示します。Claude は拒否理由を確認し、より安全な代替案を提案します。終了コード1はノンブロッキング警告で、動作はそのまま続行されます。³

フック設定ファイルはどこに置けばよいですか？

フック設定は、プロジェクトレベルのフックの場合は .claude/settings.json に（リポジトリにコミットされ、チームと共有されます）、ユーザーレベルのフックの場合は ~/.claude/settings.json に置きます（個人用で、すべてのプロジェクトに適用されます）。両方が存在する場合、プロジェクトレベルのフックが優先されます。作業ディレクトリの問題を避けるため、スクリプトファイルには絶対パスを使ってください。¹⁴

すべての決定にdeliberationが必要ですか？

いいえ。confidenceモジュールは、4つの次元（曖昧さ、複雑さ、リスク、コンテキスト依存性）にわたって決定をスコアリングします。総合confidenceが0.70未満の決定のみがdeliberationをトリガーし、これは全決定のおよそ10%にあたります。ドキュメントの修正、変数のリネーム、日常的な編集はdeliberationを完全にスキップします。セキュリティアーキテクチャ、データベーススキーマの変更、不可逆なデプロイは一貫してこれをトリガーします。⁷

意見の不一致を生み出すよう設計されたシステムをどうテストすればよいですか？

成功パスと失敗パスの両方をテストします。成功とは、エージェントが建設的に意見を異にし、合意に達することです。失敗とは、エージェントが収束しすぎる、まったく収束しない、またはspawn予算を超過することです。エンドツーエンドのテストでは、決定論的なエージェント応答で各シナリオをシミュレートし、両方の検証ゲートが文書化されたすべての失敗モードを捕捉することを確認します。本番のdeliberationシステムは、3つのレイヤーにわたって141個のテストを実行します。48個のbash統合テスト、81個の Python ユニットテスト、12個のエンドツーエンドのパイプラインシミュレーションです。⁷

deliberationによるレイテンシへの影響はどの程度ですか？

3エージェントのdeliberationは、ウォールクロック時間で30〜60秒を追加します（エージェントはAgent toolを通じて順次実行されます）。10エージェントのdeliberationは2〜4分を追加します。consensusフックとpride checkフックはそれぞれ200ms以内で実行されます。主なボトルネックは、オーケストレーションのオーバーヘッドではなく、エージェントごとの LLM の推論時間です。⁷

CLAUDE.mdファイルはどのくらいの長さにすべきですか？

各セクションは50行未満、ファイル全体は150行未満に保ちましょう。長いファイルはコンテキストウィンドウによって切り詰められるため、最も重要な指示を前方に配置してください。スタイルの好みよりも、コマンドとclosure定義を先に書きます。²¹

Claude Code 以外のツールでもこのアプローチは機能しますか？

アーキテクチャ上の原則（決定論的なゲートとしてのフック、ドメイン専門知識としてのskills、隔離されたコンテキストとしてのsubagents、メモリとしてのファイルシステム）は、どのエージェント型システムにも概念的に適用できます。具体的な実装は Claude Code のライフサイクルイベント、マッチャーパターン、Agent toolを使っています。AGENTS.mdは同じパターンをCodex、Cursor、Copilot、Amp、Windsurfに引き継ぎます。²¹ 実装の詳細はツール固有でも、harnessパターン自体はツールに依存しないのです。

クイックリファレンスカード

フック設定

{
  "hooks": {
    "PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "script.sh"}]}],
    "PostToolUse": [{"matcher": "Write|Edit", "hooks": [{"type": "command", "command": "format.sh"}]}],
    "Stop": [{"matcher": "", "hooks": [{"type": "agent", "prompt": "Verify tests pass. $ARGUMENTS"}]}],
    "SessionStart": [{"matcher": "", "hooks": [{"type": "command", "command": "setup.sh"}]}]
  }
}

Skillのフロントマター

---
name: my-skill
description: What it does and when to use it. Include trigger phrases.
allowed-tools: Read, Grep, Glob
---

Subagentの定義

---
name: my-agent
description: When to invoke. Include PROACTIVELY for auto-delegation.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

Instructions for the subagent.

終了コード

主なコマンド

ファイルの配置場所

変更履歴

参考文献