エージェントハーネスアーキテクチャ 2026: Diagram Reference

TL;DR: Claude Codeは、ファイルアクセス付きのチャットボックスではありません。22のライフサイクルイベントを持つプログラマブルランタイムであり、各イベントにはモデルがスキップできないシェルスクリプトをフックとして設定できます。フックをディスパッチャーに、ディスパッチャーをスキルに、スキルをエージェントに、エージェントをワークフローに積み重ねることで、制約を強制し、作業を委譲し、セッション間でメモリを永続化し、マルチエージェントの審議を統合する自律型開発 harness が構築できます。本ガイドでは、単一のフックから10エージェントのコンセンサスシステムまで、このスタックのすべてのレイヤーを解説します。フレームワークは不要です。すべてbashとJSONで完結します。

Andrej Karpathyは、LLMエージェントの周囲に生まれるものを表す言葉を生み出しました。それが「claws（爪）」です。エージェントがコンテキストウィンドウの外の世界を掴むためのフック、スクリプト、オーケストレーション群を指します。¹ 多くの開発者はAIコーディングエージェントを対話型アシスタントとして扱っています。プロンプトを入力し、ファイルの編集を眺めて、次に進む。この捉え方では、自分が直接監視できる範囲に生産性が制限されてしまいます。

インフラストラクチャのメンタルモデルはまったく異なります。AIコーディングエージェントは、LLMカーネルを持つプログラマブルランタイムです。モデルが行うすべてのアクションは、開発者が管理するフックを通過します。定義するのはプロンプトではなく、ポリシーです。Webサーバーがnginxのルール内で動作するのと同じように、モデルはインフラストラクチャ内で動作します。nginxの前に座ってリクエストを手入力する人はいません。設定し、デプロイし、モニタリングするものです。

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

主なポイント

• フックは実行を保証します。プロンプトは保証しません。 リンティング、フォーマット、セキュリティチェックなど、モデルの挙動に関係なく毎回必ず実行すべき処理にはフックを使用してください。終了コード2はアクションをブロックし、終了コード1は警告のみを行います。³
• スキルはドメイン専門知識をエンコードし、自動的にアクティベートされます。 descriptionフィールドがすべてを決定します。Claudeは（キーワードマッチングではなく）LLMの推論を使って、スキルを適用すべきかを判断します。⁴
• Subagentsはコンテキストの肥大化を防ぎます。 探索や分析に独立したコンテキストウィンドウを使用することで、メインセッションを軽量に保てます。最大10個を並列実行できます。⁵
• メモリはファイルシステムに存在します。 ファイルはコンテキストウィンドウを超えて永続化されます。CLAUDE.md、MEMORY.md、rulesディレクトリ、ハンドオフドキュメントが構造化された外部メモリシステムを形成します。⁶
• マルチエージェント審議は盲点を検出します。 単一のエージェントは自身の前提を疑うことができません。異なる評価優先度を持つ2つの独立したエージェントが、quality gatesでは対処できない構造的な欠陥を発見します。⁷
• harness パターンがシステムそのものです。 CLAUDE.md、フック、スキル、エージェント、メモリは独立した機能ではありません。開発者とモデルの間に位置する決定論的レイヤーとして構成され、自動化とともにスケールします。

本ガイドの使い方

各セクションは前のセクションを基盤としています。末尾の判断フレームワークでは、問題の種類ごとに適切なメカニズムを選択するためのルックアップテーブルを提供しています。

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        │
└──────────────────────────────────────────────────────────────┘

Instruction Layer: CLAUDE.mdファイルとrulesディレクトリは、プロジェクトについてエージェントが知っておくべき内容を定義します。セッション開始時と、コンパクション後に毎回自動的にロードされます。これはエージェントの長期的なアーキテクチャメモリとなります。

Extension Layer: skillsはコンテキストに基づいて自動的に有効化されるドメインの専門知識を提供します。hooksは一致するツール呼び出しごとに実行される決定論的なゲートを提供します。メモリファイルはセッションをまたいで状態を永続化します。カスタムエージェントは特化したsubagent設定を提供します。

Orchestration Layer: マルチエージェントパターンは、リサーチ、レビュー、検討のために独立したエージェントを調整します。スポーン予算により暴走的な再帰を防ぎます。コンセンサス検証により品質を担保します。

重要な洞察は次の通りです。ほとんどのユーザーはCore Layerの中だけで作業し、コンテキストが膨れ上がり、コストが積み上がる様子を眺めているだけです。一方、パワーユーザーはInstruction LayerとExtension Layerを設定し、Core Layerはオーケストレーションと最終判断のためだけに使います。²

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

2026年初頭を通じて、「独自のハーネスを構築する」という道筋が唯一の現実的な選択肢でした。2026年4月、状況は変わります。AnthropicはClaude Managed Agentsをパブリックベータで提供開始しました（4月8日）。ハーネスループ + ツール実行 + サンドボックスコンテナ + 状態永続化をREST APIとして提供し、標準トークン料金に加えて$0.08/セッション時間で課金されます。OpenAIのAgents SDKアップデート（4月16日）では同様の分離が正式化されました。ハーネスとコンピュートを別レイヤーとして扱い、ネイティブのサンドボックスプロバイダー（Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel）に加えて、コンテナ喪失から復旧するためのスナップショット/リハイドレート機能を備えています。²³²⁴

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

どちらを選ぶべきか: セルフホストは、すでにインフラの体力があるチーム、自分たちで制御するskills/hooksを持ちたいチーム、特定のワークフローを深く最適化したいチームに依然として適しています。マネージドは、専任のプラットフォームエンジニアがいないチーム、カスタマイズ性よりも価値実現までの時間を重視する場合、あるいは自分で永続化レイヤーを構築することなくラップトップを閉じてもエージェントの実行を確実に生き残らせたい場合に適しています。両者は互換性があります——セルフホスト型ハーネスを運用しつつ、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を介して共有されます。両者が組み合わさることで、完全なハーネスが形作られます。

Skills System

skillsはモデルによって呼び出される拡張機能です。Claudeはコンテキストに基づいてskillsを自動的に発見して適用します。ユーザーが明示的に呼び出す必要はありません。⁴ 同じコンテキストをセッションをまたいで何度も説明し直している自分に気づいた瞬間こそ、skillを構築すべきタイミングです。

skillを構築すべきタイミング

skillsはClaudeが常に利用できる知識のためのものです。Slash commandsは明示的に起動するアクションのためのものです。どちらにすべきか迷ったら、こう自問してください。「Claudeにこれを自動適用させるべきか、それとも実行タイミングを自分で決めるべきか？」

skillの作成

skillsは、スコープの広い順に以下の4つの場所に配置できます。⁴

すべてのskillにはSKILL.mdファイルが必要で、YAMLフロントマターを備えます。

---
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

## セキュリティチェック
コードをレビューする際は、以下を確認してください。

### 入力検証
- データベース操作の前に、すべてのユーザー入力がサニタイズされていること
- パラメータ化クエリを使用すること（SQLへの文字列補間は禁止）
- レンダリングされるHTMLコンテンツへの出力エンコーディング

### 認証
- すべての保護されたエンドポイントでセッショントークンが検証されていること
- データ変更の前に権限チェックを行うこと
- ソースコードにハードコードされた認証情報やAPIキーが含まれていないこと

Frontmatter リファレンス

description フィールドがすべて

セッション開始時、Claude Codeはすべてのskillのnameとdescriptionを抽出し、Claudeのコンテキストに注入します。メッセージを送信すると、Claudeは言語モデルの推論を用いて、該当するskillがあるかを判断します。Claude Codeのソースコードを独自に分析した結果、この仕組みが確認されています。skillの説明はシステムプロンプトのavailable_skillsセクションに注入され、モデルは標準的な言語理解によって関連するskillを選択します。¹⁰

悪い説明：

description: Helps with code

効果的な説明：

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.

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

コンテキスト予算

すべてのskillの説明は共通のコンテキスト予算を共有しており、これはコンテキストウィンドウの2%に動的にスケールし、フォールバックは16,000文字となります。⁴ skillが多数ある場合は、各説明を簡潔に保ってください。予算はSLASH_COMMAND_TOOL_CHAR_BUDGET環境変数で上書きできますが¹¹、より良い対処法は、より短く正確な説明を書くことです。セッション中に/contextを実行すれば、除外されているskillがないか確認できます。

サポートファイルと構成

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

~/.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が起動した際に、これらのファイルをオンデマンドで読み込みます。SKILL.mdは500行以内に収め、詳細なリファレンス資料はサポートファイルに移動しましょう。¹²

Git経由でskillを共有する

プロジェクトskill（リポジトリルートの.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すると、skillが自動的に取得されます。インストールも設定も不要です。これはチーム全体で専門知識を標準化する最も効果的な方法となります。

プロンプトライブラリとしてのskill

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

~/.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

各skillは、あなたの専門知識の異なる側面をエンコードしています。これらが組み合わさることで、Claudeがコンテキストに応じて自動的に参照する知識ベースが形成されます。ジュニア開発者は、求めなくてもシニアレベルの指導を得られるのです。

skillはhooksと組み合わせられる

skillはfrontmatterで独自のhooksを定義でき、それらはskillが実行中のときだけ有効になります。これにより、他のセッションを汚染せずにドメイン固有の動作を作れます。²

---
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'"
---

哲学系のskillはSessionStarthooks経由で自動起動し、明示的な呼び出しなしに品質制約をすべてのセッションに注入します。skill自体は知識です。hookは強制力です。両者を合わせることで、ポリシーレイヤーが形成されます。

skillでよくある失敗

広すぎる説明。 あらゆるgit関連のプロンプト（rebase、merge、cherry-pick、さらにはgit statusまで）で起動するgit-rebase-helperskillは、80%のセッションでコンテキストを汚染してしまいます。解決策は、説明を絞り込むか、disable-model-invocation: trueを追加して明示的な/skill-name呼び出しを必須にすることです。⁴

予算を奪い合うskillが多すぎる。 skillが増えるほど、2%のコンテキスト予算を奪い合う説明も増えます。skillが起動しないと感じたら、/contextで除外されているものがないか確認してください。曖昧で多数のskillより、よく説明された少数のskillを優先しましょう。

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

フックアーキテクチャ

フックは、Claude Code のライフサイクルイベントによってトリガーされるシェルコマンドです。³ モデルが解釈するプロンプトではなく、LLM の外部でプレーンなスクリプトとして実行されます。モデルが rm -rf / を実行したがった場合、10行のbashスクリプトがブロックリストと照合し、シェルに到達する前に拒否します。フックはモデルの意図にかかわらず発動するのです。

利用可能なイベント

Claude Code は7つのカテゴリにわたる26以上のライフサイクルイベントを公開しています（イベントリストはリリースごとに拡張されます。最新の完全な表は cheat sheet を参照してください）。¹³

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

終了コードはフックがアクションをブロックするかどうかを決定します。³

重要： セキュリティフックはすべて exit 1 ではなく exit 2 を使用する必要があります。exit 1 は非ブロッキングの警告にすぎません。危険なコマンドは依然として実行されてしまうのです。これはチーム全体で最も多いフックのミスです。¹⁴

フック設定

フックは設定ファイルに記述します。共有フックはプロジェクトレベル（.claude/settings.json）、個人フックはユーザーレベル（~/.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 フィールドはツール名に一致する正規表現です。Bash、Write、Edit、Read、Glob、Grep、Agent、またはすべてのツールに対しては * を指定します。UserPromptSubmit のようにツールを伴わないイベントでは ""（空文字列）を使用してください。

フックの入出力プロトコル

フックは完全なコンテキストを含む JSON を stdin で受け取ります。

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

高度な制御を行う場合、PreToolUse フックは 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種類の保証

フックを書く前に、どのような保証が必要か自問してください。¹⁴

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

{
  "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 フックはコマンドを検査し、破壊的なパターンを終了コード 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 フックはリンターやテストスイートを実行し、品質チェックが失敗した場合はコミットをブロックします。

#!/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

シェルコマンド以外のフックタイプ

Claude Code は4種類のフックタイプをサポートしています。¹³

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

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

Agent フック（type: "agent"）はツールアクセス（Read、Grep、Glob）を持つサブエージェントを起動し、マルチターンの検証を行います。実際のファイルやテスト出力の検査が必要な場合に使用してください。

{
  "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
          }
        ]
      }
    ]
  }
}

非同期フック

フックは実行をブロックせずにバックグラウンドで動作できます。通知やロギングなどの重要でない操作には async: true を追加してください。¹³

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

非同期は通知、テレメトリ、バックアップに使用しましょう。次のアクションの前に完了しなければならないフォーマット、検証などには決して非同期を使用しないでください。

独立したフックよりもディスパッチャを

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

解決策は、イベントごとに1つのディスパッチャを用意し、キャッシュされた stdin からフックを順次実行することです。

#!/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

フックのデバッグ

静かに失敗するフックをデバッグするための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 フックは、一見動作しているように見えて強制力がゼロです。
5. フックを高速に保つ。 フックは同期的に実行されます。すべてのフックを2秒以内、理想的には500ms以内に抑えてください。

メモリとコンテキスト

あらゆる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でVARが0のときset -e下で((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

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

アンチパターン

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

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

すべてのセッションをすべてのファイルの読み込みから始める。 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による分離は、コードベースを壊す可能性のある実験的な作業に不可欠です。

並列サブエージェント

Claude Codeは最大10個の並列サブエージェントをサポートしています。⁵ 独立した調査タスクには並列実行を活用しましょう。

> 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隔離の議論を異なるツールベンダー間にまで直接拡張するものです。ワークフローがClaudeとOpenAIモデルにまたがるのであれば、Scionはエージェントごとのworktreeと認証情報の隔離を備えた、ツール横断型subagentの初めての本格的なリファレンス実装となります。

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

最小限で成立する審議

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. リスクの大きさ - 決定は取り消し可能か？
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：Pride Check（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%については、合意検証とPride Checkのゲートが十分な検証を提供します。

審議で機能しなかったこと

自由形式のディベート・ラウンド。 データベースのインデックス設計に関する議論で、3ラウンドの往復テキストを行ったところ、7,500トークンものディベートが生成されました。ラウンド1：真の不同意。ラウンド2：立場の再表明。ラウンド3：同じ論拠を別の言葉で反復。構造化された次元別スコアリングが自由形式のディベートを置き換え、ランキングの質を高めながらコストを60%削減しました。⁷

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

審議のコスト

各リサーチエージェントは、約5,000トークンのコンテキストを処理し、2,000〜3,000トークンの調査結果を生成します。3エージェントなら、1つの決定につき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. Build and test commands（有用な作業を行う前提として、エージェントにはまずこれが必要です）
2. Definition of done（誤った完了報告を防ぎます）
3. Escalation rules（破壊的な回避策を防ぎます）
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のパターン（コマンド優先、クロージャ定義、タスク別整理）は、ツールを問わずどの指示ファイルでも機能します。並行する指示セットが乖離していくのを放置してはいけません。正典となるソースを1つ書き、あとはミラーリングしましょう。

指示のテスト

エージェントが実際に指示を読み、従っているかを検証します：

# 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日）は、harness が防御すべき対象を変える特定の機能を備えてリリースされました。²⁹

• ツール障害への耐性： Opus 4.7 は、Opus 4.6 のセッションを停止させていたツール障害を乗り越えて処理を継続します。subagent のコード内にある防御的なリトライラッパーを削減できます（ただし完全に排除はできません）。hook レベルのガードは維持し、プロンプト内の「ツールが失敗したら3回リトライせよ」といった scaffolding は削ぎ落としましょう。
• xhigh effort 層（Opus-4.7 専用）： high と max の中間に位置します。コーディングおよび agentic ワークロードの推奨デフォルト値です。長時間動作する subagent においては、xhigh はトークンコストが比例未満のまま high を有意に上回る性能を発揮します。max は一発勝負の難問推論に依然として最適ですが、持続的なタスクには xhigh の方が適しています。
• トークン予算の上限： エージェント実行ごとに output_config.task_budget（ベータヘッダー task-budgets-2026-03-13）で設定可能です。モデルは残り時間のカウントダウンを参照しながら、予算に合わせて作業範囲を優雅に調整するため、予期せぬ枯渇を起こしません。短いプロンプトの品質を犠牲にせず、予測可能なトークン消費を実現したい agentic ループで活用してください。
• 暗黙のニーズの認識： 「暗黙のニーズ」テストをパスした初の Claude モデルです。ユーザーの文字通りのリクエストが実際に必要としているものを過小に指定している場合に、それを認識できます。これにより、CLAUDE.md の「明確化ルール」セクションの必要性は薄れます。CLAUDE.md が「Y を求められたら X も検討せよ」といったガードレールで 200行に及んでいるなら、ネイティブでカバーされるようになったものは刈り込みましょう。

The Quality Loop

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

1. Implement - コードを書く
2. Review - 一行ずつ読み直す。タイポ、ロジックエラー、不明瞭な箇所を見つける
3. Evaluate - evidence gate を実行する。パターン、エッジケース、テストカバレッジをチェックする
4. Refine - すべての問題を修正する。「あとで」に先送りしない
5. Zoom Out - 統合ポイント、import、隣接コードの回帰をチェックする
6. Repeat - evidence gate の基準のいずれかが失敗した場合、step 4 に戻る
7. Report - 何を変更したか、どう検証したかをリストアップし、具体的な根拠を引用する

The Evidence Gate

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

いずれかの行について根拠を示せない場合、Refine に戻ってください。²²

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

アトミックなファイル書き込み。 複数のエージェントが同じ state ファイルに同時書き込みすると 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"

state 破損からの復旧。 state が破損した場合、回復パターンはクラッシュせずに安全なデフォルト値から再作成します。¹⁶

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 の場合に exit code 1 を返します。これは 0++ が 0 と評価され、bash がそれを false として扱うためです。set -e が有効な状態では、これがスクリプトを強制終了させます。代わりに VAR=$((VAR + 1)) を使いましょう。¹⁶

ブラストレイディアス分類

エージェントのあらゆるアクションをブラストレイディアスで分類し、それに応じてゲートを設けましょう。²

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

自律実行のためのタスク指定

効果的な自律タスクには 3 つの要素が含まれます。objective、completion criteria、context pointers です。¹⁶

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

基準は機械検証可能でなければなりません。テストのパス/フェイル、linter の出力、HTTP ステータスコード、ファイル存在チェックなどです。初期のあるタスクでエージェントに「パスするテストを書け」と指示したところ、assert True や assert 1 == 1 が生成されました。技術的には正しい。実用上は無価値です。¹⁶

警戒すべき失敗モード

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

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

1. SessionStart が発火。 dispatcher が注入するもの：現在日時、プロジェクト検出、哲学的制約、コスト追跡の初期化。5 つの hook で合計 180ms。

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

3. エージェントが Bash を呼び出してテストを実行。 PreToolUse:Bash が発火。認証情報チェック、sandbox 検証、プロジェクト検出。90ms。テストが実行される。PostToolUse:Bash が発火：アクティビティハートビートをログ、ドリフトチェック。

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

5. エージェントがストーリーを完了。 Stop が発火。品質ゲートがチェック：エージェントは根拠を引用したか？ ヘッジ表現は？ diff 内に TODO コメントは？ いずれかのチェックが失敗すれば exit 2 となり、エージェントは処理を継続します。

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

7. 3 つのコードレビューエージェントが並列に生成される。 それぞれが独立して diff をレビューします。いずれかのレビューアーが CRITICAL をフラグ立てすれば、ストーリーはキューに戻されます。

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

5 ストーリーで発火した hook の合計：約 340。hook に費やされた合計時間：約 12 秒。そのオーバーヘッドが、ある一夜の実行だけで、3 件の認証情報漏洩、1 件の破壊的コマンド、2 件の不完全な実装を防ぎました。

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

あるプロダクション harness は、8 回の夜間セッションで 12 件の PRD（47 ストーリー）を処理しました。メトリクスは、最初の 4 件の PRD（最小 harness：CLAUDE.md のみ）と、最後の 8 件（フル harness：hooks、skills、品質ゲート、マルチエージェントレビュー）を比較しています。

2 件の認証情報漏洩は、API キーのローテーションと下流サービスの監査を要し、インシデント対応におよそ 4 時間を費やしました。同等の漏洩を防いだ harness のオーバーヘッドは、ストーリーあたり bash で 2.4 秒です。誤完了率が 35% から 4% に下がったのは、Stop hook がエージェントに完了報告を許可する前に独立してテストを実行したためです。

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

信頼できるエージェントの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

サブエージェントの分離は、被害範囲を限定します。permissionMode: planを持つサブエージェントは、プロンプトが侵害されても変更を加えることはできません。

フックのセキュリティ

ヘッダーに環境変数を展開するHTTPフックでは、任意の環境変数が流出するのを防ぐために、明示的なallowedEnvVarsリストが必要です。¹³

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

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

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

パターンは次のとおりです。人間は、組織的な文脈、倫理的判断、戦略的方向性を必要とする意思決定を担います。エージェントは、広大な可能性空間にわたる計算的探索を必要とする意思決定を担います。フックがその境界を強制するのです。

再帰的なフックの強制

フックはサブエージェントの動作に対しても発火します。¹³ ClaudeがAgentツールを介してサブエージェントをスポーンすると、そのサブエージェントが使用するすべてのツールに対して、PreToolUseおよびPostToolUseフックが実行されます。再帰的なフック強制がなければ、サブエージェントは安全ゲートを迂回できてしまいます。SubagentStopイベントにより、サブエージェントの完了時にクリーンアップや検証を実行できます。

これはオプション機能ではありません。セキュリティフックなしでサブエージェントをスポーンするエージェントとは、メイン会話を監視するゲートが何もしない間に、mainへのforce push、認証情報ファイルの読み取り、破壊的コマンドの実行ができてしまうエージェントなのです。

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

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

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

エージェントレベル。 長い会話よりも、新規スポーンを選びます。自律実行における各ストーリーは、クリーンな文脈を持つ新しいエージェントで処理されます。各エージェントが新しく始まるため、文脈が肥大化することはありません。記憶ではなくブリーフィングで動かす。モデルは、蓄積された30ステップの文脈をたどるよりも、明確なブリーフィングに従って実行するほうが得意なのです。

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

意思決定フレームワーク

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

Skills vs Hooks vs Subagents

FAQ

hookはいくつまでなら多すぎるのでしょうか？

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

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

はい、できます。PreToolUse hookは終了コード2で終了することで、あらゆるツールアクションをブロックします。Claude Codeは保留中のアクションをキャンセルし、hookの標準エラー出力をモデルに表示します。Claudeは拒否理由を確認し、より安全な代替案を提案します。終了コード1は非ブロッキングの警告であり、アクションはそのまま進行します。³

hookの設定ファイルはどこに置くべきですか？

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

あらゆる判断に熟議が必要なのでしょうか？

いいえ、必要ありません。信頼度モジュールは4つの次元（曖昧性、複雑性、重要度、コンテキスト依存性）で判断をスコアリングします。総合的な信頼度が0.70を下回る判断のみが熟議をトリガーし、それは全判断のおよそ10%にあたります。ドキュメントの修正、変数のリネーム、日常的な編集では熟議は完全にスキップされます。セキュリティアーキテクチャ、データベーススキーマの変更、不可逆なデプロイでは一貫して熟議がトリガーされます。⁷

不一致を生み出すように設計されたシステムは、どうやってテストすればよいですか？

成功パスと失敗パスの両方をテストします。成功：エージェントが建設的に不一致を示し、合意に達する。失敗：エージェントが早すぎる段階で収束する、まったく収束しない、あるいはスポーン予算を超過する。エンドツーエンドテストは決定論的なエージェント応答で各シナリオをシミュレートし、両方の検証ゲートが文書化されたすべての失敗モードを捕捉することを検証します。本番環境の熟議システムは、3層にわたって141のテストを実行しています。bash統合テスト48件、Pythonユニットテスト81件、そしてエンドツーエンドのパイプラインシミュレーション12件です。⁷

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

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

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

各セクションは50行以内、ファイル全体は150行以内に収めてください。長いファイルはコンテキストウィンドウによって切り詰められるため、最も重要な指示を前方に配置します。スタイル設定より前にコマンドとクロージャ定義を記述してください。²¹

これはClaude Code以外のツールでも機能しますか？

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

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

Hook設定

{
  "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.

終了コード

主要コマンド

ファイルの場所

変更履歴

参照