エージェントアーキテクチャ：AIを活用した開発ハーネスの構築

要約： Claude Code は、ファイルにアクセスできるチャットボックスではありません。文書化された30のライフサイクルイベントを備え、各イベントにモデルが回避できないシェルスクリプトの hooks を設定できる、プログラム可能なランタイムです。hooks を dispatcher に、dispatcher を skills に、skills をエージェントに、エージェントをワークフローに積み重ねることで、制約の適用、作業の委任、セッションをまたぐメモリの永続化、multi-agent deliberation のオーケストレーションを行う自律開発 harness が完成します。Claude Code v2.1.147 では、デフォルトで無効な Workflow ツール（CLAUDE_CODE_WORKFLOWS=1）が追加され、決定論的な multi-agent オーケストレーションは、純粋なユーザーランドスクリプトからファーストパーティのランタイムプリミティブへと移行し始めました。v2.1.149 では、PowerShell の権限回避に関する修正と git-worktree サンドボックスの許可リスト修正により、セキュリティ面からも同じ教訓が強調されています。正確性を担うのは、引き続き hooks と evidence gate です。⁵²⁵³ このガイドでは、単一の hook から10エージェントによる合意形成システムまで、このスタックの全レイヤーを解説します。フレームワークは一切不要です。すべて bash と JSON だけで構築できます。

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

インフラストラクチャとして捉えると、見え方は変わります。AI コーディングエージェントとは、LLM カーネルを備えたプログラム可能なランタイムです。モデルが行うすべてのアクションは、制御下にある hooks を通過します。定義するのはプロンプトではなく、ポリシーです。Web サーバーが nginx のルール内で動作するのと同じように、モデルも構築したインフラストラクチャ内で動作します。nginx の前に座ってリクエストを入力することはありません。設定し、デプロイし、監視するものです。

この違いが重要なのは、インフラストラクチャの効果が積み重なるためです。bash コマンドに認証情報が含まれるのをブロックする hook は、すべてのセッション、すべてのエージェント、すべての自律実行を保護します。評価基準を組み込んだ skill は、自分で呼び出してもエージェントが呼び出しても、一貫して適用されます。セキュリティの観点からコードをレビューするエージェントは、監視の有無にかかわらず同じチェックを実行します。²

要点

• hooks は実行を保証しますが、プロンプトは保証しません。 lint、フォーマット、セキュリティチェックなど、モデルの振る舞いにかかわらず毎回必ず実行すべき処理には hooks を使用します。終了コード2はアクションをブロックします。終了コード1は警告のみです。³
• skills は、自動的に有効化されるドメイン知識を組み込みます。 すべてを左右するのは description フィールドです。Claude は、キーワード一致ではなく LLM reasoning を用いて、skill を適用するタイミングを判断します。⁴
• subagents はコンテキストの肥大化を防ぎます。 調査と分析に独立したコンテキストウィンドウを使うことで、メインセッションを軽量に保てます。独立した subagents は並列実行し、ワーカー同士に継続的な連携が必要な場合はエージェントチームを使用します。⁵
• メモリはファイルシステムに保存されます。 ファイルはコンテキストウィンドウをまたいで保持されます。CLAUDE.md、MEMORY.md、rules ディレクトリ、引き継ぎ文書によって、構造化された外部メモリシステムが形成されます。⁶
• multi-agent deliberation は見落としを発見します。 単一のエージェントは、自らの前提を自力で覆すことができません。評価の優先順位が異なる2つの独立したエージェントを使えば、quality loop では対処できない構造的な問題を発見できます。⁷
• harness パターンそのものがシステムです。 CLAUDE.md、hooks、skills、エージェント、メモリは、それぞれ独立した機能ではありません。これらを組み合わせることで、ユーザーとモデルの間に決定論的なレイヤーが形成され、自動化の拡大に合わせてスケールします。

このガイドの使い方

各セクションは、それ以前の内容を土台として構成されています。最後の判断フレームワークには、問題の種類ごとに適切な仕組みを選ぶための参照表があります。

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__を形作るのです。

harness パターン

harness はフレームワークではありません。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 レイヤー： CLAUDE.md ファイルと rules ディレクトリは、エージェントがプロジェクトについて把握する内容を定義します。セッション開始時と compaction のたびに自動で読み込まれます。これはエージェントの長期的なアーキテクチャ記憶となります。

Extension レイヤー： skills は、コンテキストに基づいて自動的に有効化される専門知識を提供します。hooks は、一致するツール呼び出しのたびに発動する決定論的なゲートとして機能します。メモリファイルはセッションをまたいで状態を保持します。カスタムエージェントでは、専用の subagents 設定を定義できます。

Orchestration レイヤー： マルチエージェントパターンは、調査、レビュー、審議に取り組む独立したエージェントを連携させます。spawn の上限により、制御不能な再帰を防ぎます。合意検証によって品質を確保します。

重要なのは、ほとんどのユーザーが Core レイヤーだけで作業し、コンテキストの肥大化とコストの増加を見守ることになっている点です。熟練したユーザーは Instruction レイヤーと Extension レイヤーを設定し、Core レイヤーはオーケストレーションと最終判断にだけ使用します。²

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

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

OpenAI 側のより充実した SDK 機能は、openai-agents Python v0.14.0（2026年4月15日リリース、4月16日発表）で導入されました。Agent のサブクラスである SandboxAgent には、default_manifest、サンドボックス向けの指示、ケイパビリティが用意されています。Manifest は、新規ワークスペースの契約（ファイル、ディレクトリ、ローカルファイル、Git リポジトリ、環境、ユーザー、マウント）を記述します。SandboxRunConfig は、サンドボックスクライアント、ライブセッションの注入、マニフェストのオーバーライド、スナップショット、マテリアライズの並行処理上限を実行ごとに設定するためのものです。組み込みのケイパビリティとして、シェルアクセス、ファイルシステム編集、画像検査、skills、サンドボックスメモリ、compaction が用意されています。サンドボックスメモリは、抽出した知見を実行間で保持し、段階的に開示します。ワークスペースでは、ローカルファイル、Git リポジトリエントリ、リモートマウント（S3、R2、GCS、Azure Blob、S3 Files）を使用でき、スナップショットはプロバイダー間で移植可能です。バックエンドには、UnixLocalSandboxClient、DockerSandboxClient のほか、オプションの追加パッケージを介して利用できる Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel 向けのホスト型クライアントがあります。²⁴

Python プロジェクトで、Claude Code ランタイムをライブラリとして組み込みたい場合には、claude-agent-sdk-python という3つ目の選択肢があります。これは、「claude をシェルから呼び出す」方法と「Managed Agents の REST API を利用する」方法の中間に位置します。4月28〜29日の一連のリリース（v0.1.69 → v0.1.71）では、同梱の CLI が v2.1.123 に更新され、mcp 依存関係の最低バージョンが >=1.19.0 に引き上げられました。旧バージョンでは、プロセス内の MCP ツールが返す CallToolResult が通知なく破棄され、モデルには検証エラーの塊しか渡されませんでした。また、SandboxNetworkConfig が TypeScript SDK のスキーマ（allowedDomains、deniedDomains、allowManagedDomainsOnly、allowMachLookup）と同等になりました。³⁰ 2026-08-01 時点で、このパッケージは PyPI の v0.2.128（Claude CLI v2.1.220 を同梱し、mcp の最低バージョンは現在 >=1.23.0）で、TypeScript SDK は v0.3.220 です。0.2.x 系列は、ここで説明した 0.1.x の機能を段階的に拡張したものです。以下の include_hook_events、skills、サンドボックス設定オプションは現在も有効で、最近のリリースではサブプロセスのクリーンアップと NDJSON ストリームの信頼性向上に重点が置かれています。⁸⁶

harness に音声またはリアルタイムレイヤーが含まれる場合、openai-agents-python v0.17.0（2026年5月8日）では、RealtimeAgent のデフォルトが gpt-realtime-2 に更新されています。⁴¹ 既存のリアルタイムセッションにも新しいデフォルトが自動的に適用されます。評価のために従来の動作を維持する必要がある場合は、以前のモデルを明示的に固定してください。

2026年7月には、OpenAI 側のマネージドサービスにもマルチエージェント機能が加わりました。openai-agents-python v0.18.2（7月11日）と openai-agents-js v0.13.2（7月10日）では、ベータ版の ホスト型マルチエージェントサポート が追加されています。これは複数のエージェントのオーケストレーションを OpenAI がホスト型サービスとして管理するもので、マルチエージェントオーケストレーションのセクションで取り上げる、Anthropic の Managed Multiagent Orchestration パブリックベータに直接対応する機能です。⁷³ 両ベンダーは、単一エージェントについて下表で示すのと同じトレードオフを、マルチエージェント層でも提供するようになりました。ベンダーが委任ループを実行する代わりに、hooks を利用できる範囲は狭まります。

アーキテクチャ上の分岐は、今や明確なものとなっています。

どちらを選ぶべきか： すでにインフラストラクチャの運用能力があり、自分たちで制御できる skills/hooks を求めているチームや、特定のワークフローを徹底的に最適化したいチームには、引き続きセルフホスト型が適しています。専任のプラットフォームエンジニアがいないチーム、カスタマイズ性よりも価値を得るまでの速さを重視する場合、あるいは永続化レイヤーを自作せずに、ノートパソコンを閉じてもエージェントの実行を確実に継続させたい場合には、マネージド型が適しています。両者は併用できます。セルフホスト型 harness から REST API を介して、特定の長時間タスクを Managed Agents に委任することも可能です。

ディスク上の harness の構成

~/.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 を介して共有されます。この2つを合わせたものが、完全な harness です。

Skills システム

skills はモデルが呼び出す拡張機能です。Claude は、明示的に呼び出さなくても、コンテキストに基づいて skills を自動的に検出し適用します。⁴ セッションをまたいで同じコンテキストを繰り返し説明していることに気づいたら、skill を作るべきタイミングです。

Skill を作るタイミング

skills は、Claude が常に利用できる知識のためのものです。スラッシュコマンドは、明示的に実行するアクションのためのものです。どちらにするか迷ったら、「Claude が自動的に適用すべきか、それとも実行するタイミングを自分で決めるべきか」と考えてください。

Skill の作成

skills は、適用範囲が広い順に、次の4か所へ配置できます。⁴

すべての skill には、YAML frontmatter を含む 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

Frontmatter リファレンス

Description フィールドがすべてを左右する

セッション開始時に、Claude Code は各 skill の name と description を抽出し、Claude のコンテキストへ注入します。メッセージを送信すると、Claude は言語モデルの推論を使って、関連する skill があるかどうかを判断します。Claude Code のソースを独立して分析した結果からも、この仕組みが確認されています。skill の description はシステムプロンプトの available_skills セクションに注入され、モデルは通常の言語理解によって関連する 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）が含まれています。

なお、自動有効化は調整できる仕組みであり、絶対的なルールではありません。v2.1.215以降、Claude は同梱の /verify と /code-review skills を自動呼び出ししなくなり、明示的に呼び出した場合にのみ実行されます。これは、要求されていない実行では得られる価値よりコストが上回る重量級のレビュー skillsについて、description 主導の有効化を意図的に後退させた変更です。⁷⁴

コンテキスト予算

すべての skill の description は、コンテキストウィンドウの1%に動的に調整される共通のコンテキスト予算を使用し、フォールバックは8,000文字です。⁴ 多数の skills がある場合は、各 description を簡潔にし、主要なユースケースを最初に記載してください。SLASH_COMMAND_TOOL_CHAR_BUDGET 環境変数で予算を上書きできますが、¹¹ よりよい解決策は、description を短く正確にすることです。セッション中に /context を実行し、除外されている skills がないか確認してください。

補助ファイルと構成

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

~/.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 から相対リンクで参照してください。skill が有効になると、Claude は必要に応じてこれらのファイルを読み取ります。SKILL.md は500行未満に抑え、詳細な参照資料は補助ファイルへ移してください。¹²

Git による Skills の共有

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

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

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

~/.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 がコンテキストに応じて自動的に参照する知識ベースになります。ジュニア開発者でも、求めることなくシニアレベルのガイダンスを得られます。

Skills と Hooks の組み合わせ

skills の frontmatter には、その skill の実行中にのみ有効になる独自の hooks を定義できます。これにより、ほかのセッションを汚さずに、ドメイン固有の動作を実現できます。²

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

哲学を定めた skills は SessionStart hooks を通じて自動的に有効になり、明示的に呼び出さなくても、すべてのセッションへ品質上の制約を注入します。skill 自体が知識であり、hook はその強制手段です。両者を組み合わせることで、ポリシーレイヤーが形成されます。

Skill でよくある間違い

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

コンテキスト予算を奪い合う skills が多すぎる。 skills が増えるほど、1%のコンテキスト予算をめぐって競合する description も増えます。skills が有効にならない場合は、/context で除外されているものを確認してください。曖昧な skills を多数用意するより、適切な description を持つ少数の skills を優先しましょう。

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

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

claude-agent-sdk-python v0.1.77以降を利用するセルフホスト型 harness では、利用可能な skills を宣言する際に、allowed_tools の従来の "Skill" 値ではなく、ClaudeAgentOptions の skills オプションを使用してください。³⁷ "Skill" という短縮表記は非推奨です。専用オプションを使うことで、利用可能な skills について、より構造化された情報を Claude Code に提供できます。v0.1.77に同梱される CLI はv2.1.133です。

.claude/skills/ におけるプラグインと Skill の統合（2026年5月29日）

skills は以前から、プロジェクトの .claude/skills/ ディレクトリから読み込まれていました。Claude Code v2.1.157では、このディレクトリがプラグインにも拡張されています。.claude/skills/ に配置したプラグインは、マーケットプレイスへ登録しなくても自動的に読み込まれるようになりました。また、claude plugin init <name> を実行すると、manifest と SKILL.md があらかじめ接続された新しいプラグインが、この場所に生成されます。⁵⁸ これにより、以前は別々の場所に存在していた2種類のプロジェクトツール構成の隔たりが解消されます。一方はリポジトリへ直接コミットする単体の skill、もう一方は skill、hooks、MCP サーバーをまとめて提供できるものの、これまではインストールにマーケットプレイスが必要だったプラグインです。harness のデザインに与える実務的な効果として、プロジェクト単位のツールを提供するためにレジストリを経由する必要がなくなりました。作成してコミットすれば、チームメンバーも git pull で同じサーフェスを利用できます。プラグインは引き続き、まとめてインストールできるユースケース（hooks + skills + MCP サーバー + agents を1つの ZIP に格納）を担います。今回の変更点は、プロジェクトが自身のツリーからプラグインを1つ読み込むだけのために、マーケットプレイスを用意する必要がなくなったことです。

ガバナンスとして同梱サーフェスを非表示にする（2026年6月8日）

skills は機能であり、機能は攻撃対象領域でもあります。Claude Code v2.1.169では、同梱の skills、workflows、組み込みスラッシュコマンドをモデルから完全に隠す disableBundledSkills 設定（および対応する CLAUDE_CODE_DISABLE_BUNDLED_SKILLS 環境変数）が追加されました。⁶⁰ セキュリティを強化した harness や規制対象の harness にとって、これは意図的な攻撃対象領域の縮小です。特定のプロジェクト skills と個人 skills を監査・承認した運用者は、Anthropic に標準搭載されているすべての機能を抑制できます。これにより、モデルが推論対象とするのは、運用者が検証したサーフェスだけになります。ツールの allowlist と同様に扱ってください。デフォルトでは幅広い機能が有効であり、それを無効にすることは、利便性のための切り替えではなくガバナンス上の判断です。

ネストされた .claude/skills と最寄り優先の解決（2026年6月16日）

Claude Code v2.1.178では、プロジェクトツールが配置場所を認識するようになりました。リポジトリルートだけでなく、ネストされた .claude/skills ディレクトリ内の skills も、そのディレクトリ配下のファイルを扱っているときに読み込まれます。同名の skill が競合した場合は、ネストされた skill が <dir>:<name> として表示されるため、どちらにもアクセスできます。⁶³ 同じリリースでは、プロジェクトサーフェスのほかの要素も、作業ディレクトリに最も近いものを解決するようになりました。ネストされた .claude/ ディレクトリ間で agent、workflow、output-style の名前が競合した場合、作業ディレクトリに最も近いものが優先されます。また、プロジェクトスコープの workflow を保存すると、常にルートではなく、最も近い既存の .claude/workflows/ が保存先になります。⁶³ monorepo や複数のリポジトリを内包するリポジトリでは、これにより、単一のフラットなグローバルサーフェスから、コンテキストに応じて有効になるパッケージごとのツール構成へ移行できます。たとえば、services/api/.claude/skills/ に API 固有の skills を配置すれば、そのツリーで作業している間だけ表示され、同名の services/web/ skill とも競合しません。

Hook Architecture

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

利用可能なイベント

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

DirectoryAdded（v2.1.219）は、セッション途中で生じるワークスペースの監視漏れを解消します。 v2.1.152でMessageDisplayが追加されて以来、イベント一覧は変わっていませんでした。DirectoryAddedはそれ以降で初めて追加されたライフサイクルイベントであり、/add-dir、またはSDKのregister_repo_root制御リクエストによって、セッション途中に新しい作業ディレクトリが登録された後に発火します。⁸⁴ これまで、この監視漏れは現実的な問題でした。harnessがSessionStartでワークスペースを徹底的に検証しても、その後hookが一切発火しないまま2つ目のリポジトリが追加される可能性があったのです。起動時にワークスペースについて検証した内容（信頼性チェック、シークレットのスキャン、ディレクトリツリーから導出したパススコープのルール、リポジトリ単位のポリシー読み込みなど）は、ここで再実行する必要があります。セッションが扱うディレクトリの集合は、起動時に固定されるものではなくなったためです。このイベントはブロック用ではなく情報提供用です。そのため、ゲートとしてではなく、状態を再導出して出所を記録するトリガーとして扱ってください。決して追加を許可してはならないディレクトリがある場合は、hookで拒否しようとせず、設定で拒否します。SDK側の対応も同じリリースで導入されました（TypeScript v0.3.219では、制御プロトコルのライフサイクルイベントにDirectoryAddedが追加されています）。これにより、SDKでホストされるharnessでも、CLIと同様にこのイベントを利用できます。⁸⁵

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

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

Hookの設定

hooksは設定ファイルに記述します。共有hooksにはプロジェクトレベル（.claude/settings.json）、個人用hooksにはユーザーレベル（~/.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、Edit、Write、Read、Glob、Grep、mcp__server__toolのようなMCPツール名、または全ツールを表す*などのtool_name値と照合します。単純な名前と|区切りのリストは完全一致として扱われ、それ以外の文字を含む値はJavaScript正規表現になります。一部のイベントはmatchersに対応しておらず、設定されていれば必ず発火します。¹³ Claude Code v2.1.195以降、ハイフンを含む識別子（code-reviewer、mcp__brave-search）を指定したmatchersは、誤って部分一致するのではなく完全一致するようになりました。これにより、特定のエージェントやサーバーを対象とするhookが、その文字列を含むだけの名前すべてに発火することはなくなりました。ハイフンを含むMCPサーバーの全ツールを対象にするには、明示的なパターンmcp__brave-search__.*を記述してください。⁶⁶ v2.1.214では、同じ厳密さがパスパターンにも適用されました。単一セグメントのdir/**パターンを使用するhookのif:条件は、ツリー内のあらゆる場所にあるdirという名前のディレクトリではなく、<cwd>/dirだけに一致するようになりました。深さを問わず一致させたい場合は、**/dir/**と記述してください。v2.1.195の変更と同様、この修正では意図しない広範な一致を避け、宣言した意図を優先しています。従来の任意階層への一致動作に暗黙的に依存していたhook条件がないか、監査してください。

Hookの入出力プロトコル

hooksは、完全なコンテキストを含む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 hooksが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 hooksは、ファイルが変更されるたびにフォーマッターを実行します。フォーマッターがすべてを正規化するため、モデルがどのような出力を生成したかは問題になりません。

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

#!/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 hooks（type: "command"）はシェルスクリプトを実行します。高速かつ決定論的で、トークンコストもかかりません。 MCP ツール hooks（type: "mcp_tool"）は、接続済みの MCP サーバー上のツールを呼び出します。検証ロジックがすでに MCP 境界の内側にあり、別のシェルスクリプトを必要としない場合に使用します。

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

Agent hooks（type: "agent"）は、ツール（Read、Grep、Glob）へのアクセス権を持つ subagent を起動し、複数ターンにわたる検証を行います。これは実験的な機能です。production の gate には command hooks を優先し、agent hooks は実際のファイルやテスト出力を調べる必要があるチェックに限って使用してください。

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

Claude Code v2.1.140 以降、agent hook の入力には subagent_type が含まれます。これにより、共有 hook はプロンプトのテキストから推測することなく、security-reviewer の実行と explorer や汎用 worker を区別できます。⁴⁹

HTTP hooks（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
          }
        ]
      }
    ]
  }
}

非同期 Hooks

Hooks は、実行をブロックせずにバックグラウンドで動作できます。通知やログ記録など、重要ではない処理には async: true を追加します。¹³

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

非同期処理は、通知、テレメトリー、バックアップに使用します。フォーマット、検証、または次のアクションまでに完了する必要がある処理には、決して使用しないでください。

個別の Hooks より Dispatchers

同じイベントで7つの hooks を実行し、それぞれが独立して stdin を読み取ると、競合状態が発生します。2つの hooks が同じ JSON 状態ファイルへ同時に書き込むと、JSON が途中で切り詰められます。そのファイルを解析する後続の hooks は、すべて動作しなくなります。²

解決策は、イベントごとに1つの dispatcher を用意し、キャッシュした stdin を使って hooks を順番に実行することです。

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

Hooks のデバッグ

何も通知せずに失敗する hooks をデバッグするための5つのテクニックです。¹⁴

1. スクリプトを単独でテストします。 サンプルの JSON をパイプで渡します：echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. デバッグ出力には stderr を使用します。 終了コード2の stderr は、エラーメッセージとして Claude に返されます。ブロックしない stderr（終了コード1、3など）は、詳細モード（Ctrl+O）でのみ表示されます。
3. jq の失敗に注意します。 JSON のパスが間違っていると、通知されずに null が返されます。実際のツール入力を使って jq 式をテストしてください。
4. 終了コードを確認します。 exit 1 を使用する PreToolUse hook は、動作しているように見えても、強制力がまったくありません。
5. Hooks を高速に保ちます。 Hooks は同期的に実行されます。すべての hooks を2秒未満、理想的には500ms未満に抑えてください。

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

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

イベントストリームのパターンは、harness がすでに Python 上で動作しており、モデル出力と同じ制御フローで hook のシグナルを扱いたい場合に適しています。一方、複数のツールを組み合わせる harness、Claude Code と Codex の間で hooks を共有する harness、またはブロックに終了コードのセマンティクスが必要な harness では、シェルスクリプトによる hook の契約（終了コード、stdin の JSON、dispatchers）が引き続き適切です。

TypeScript SDK の2026年7月シリーズ（v0.3.205〜v0.3.208）では、ストリーミングプロトコル自体の契約がより明確になりました。⁷⁰ 割り込みは、型付きの receipt を返すようになりました。割り込み時にまだ待機中のキューメッセージが still_queued UUID で通知され、セッションは system/init で interrupt_receipt_v1 capability を提示します。これにより coordinator は、「割り込みが受理された」場合と「割り込みが、すでに処理中のメッセージに間に合わなかった」場合を区別できます。command_lifecycle frame は、メッセージごとに queued/started/completed/cancelled/discarded を報告します。これは、transcript から推測せずに「送信したメッセージに何が起きたのか」を把握できる、初のファーストパーティーによる仕組みです。より小規模な機能も追加されました。subagent の完了 payload 用の AgentToolCompletedOutput 型と、updatedInput フィールドなしで {behavior: 'allow'} を返せる canUseTool callback です。

このシリーズに含まれる1つの変更は、機能ではなくセキュリティの最低基準です。v0.3.208 では、保留中の hook の実行中に呼び出し元から abort が届くと、hook の成功として扱われる問題が修正されました。この問題により、PreToolUse hook で gate されているツールが、呼び出し元による abort の後に実行される可能性がありました。⁷⁰ SDK 側の hooks を permission gate として使用し、処理中の作業をキャンセルするために abort に依存している場合は、v0.3.208 を最低バージョンとしてください。それより前のバージョンでは、「aborted」が「blocked」を確実に意味するとは限りませんでした。Python v0.2.127（2026年7月24日）は、1か月以内に発生した同種の2つ目の bypass です。query() が最初の result frame で stdin を閉じましたが、その時点でもバックグラウンドの subagents は実行中でした。その結果、subagents による SDK-MCP ツール呼び出しが "Stream closed" で失敗したうえ、PreToolUse hooks を完全に bypass しました。⁸⁵ このパターンを認識し、警戒してください。SDK 側の hook による強制は、abort、teardown、stream close といったライフサイクルの境界で、フェイルオープンになります。hook の判定結果が回収される前に通信が切断されるためです。しかも、bypass された hook は承認した hook とまったく同じように見えるため、通知なしに失敗します。両方の SDK の最低バージョンを固定し、実効性を証明できる強制レイヤーとして shell-hook 層を維持してください。

Effort とセッションの Provenance（2026年5月7〜8日）

Claude Code v2.1.132 と v2.1.133 で追加された2つの機能により、hooks と subprocesses は実行コンテキストをより正確に把握できるようになりました。³⁸³⁹

• hook 入力の effort.level。 Hooks は、tool_input と session_id を含む入力と同じ場所に、effort.level JSON フィールドも受け取るようになりました。同じ値が $CLAUDE_EFFORT env var としてエクスポートされるため、Bash commands は JSON を解析せずに値を読み取れます。これを使って、effort tier に応じて hook のコストを調整できます。low では高コストな検証を省略し、xhigh または max では完全な security gate を実行します。
• Bash subprocesses の CLAUDE_CODE_SESSION_ID env var。 Bash ツールの subprocesses でも、hooks が参照するものと同じ session_id 値を CLAUDE_CODE_SESSION_ID として利用できるようになりました。これにより、セッション単位の状態を記録するツールが subprocess イベントと hook イベントを関連付けられなかった provenance の欠落が解消されます。

どちらのシグナルもコードを変更せずに利用できます。新しいフィールドを無視する既存の hooks も、そのまま動作します。

autoMode.hard_deny と v2.1.136 の Hook/Plugin 修正（2026年5月8日）

Claude Code v2.1.136 では、auto mode に新しい hard-deny tier が追加され、長時間稼働する harness に影響していた plugin と MCP に関する一連の問題が修正されました。⁴⁰ - settings.autoMode.hard_deny。 ユーザーの意図や許可の例外にかかわらず、無条件でブロックする auto mode classifier ルールです。既存の許可／拒否マッチャーより上位に位置し、妥協できないガバナンスの制御手段として機能します。個人設定でオペレーターがより広いカテゴリーを許可している場合でも、決して上書きされてはならないルール（main への force-push、シークレットを含むファイル、本番データベースへのアクセス）に使用してください。 - autoMode.classifyAllShell（v2.1.193）。 デフォルトでは、auto-mode classifier は任意コード実行パターンに一致するシェルコマンドのみを審査します。この設定を使うと、すべての Bash／PowerShell コマンドが classifier を経由します。これは、統制された harness において最大限の範囲をカバーする構成です。また、同じリリースで拒否の理由がトランスクリプト、トースト、/permissions に表示されるようになり、理由の見えないブロックが監査可能な判断に変わりました。Codex も v0.142.2 で同等の仕組みを強化しています。安全性 classifier が検査できない実行可能な AST 領域を含む PowerShell コマンドは、黙って通過するのではなく承認を要求するようになりました。⁶⁶ - Hook の ask が classifier の下限を設定（v2.1.211）。 hook と auto mode の優先順位に関する問題は、これで決着しました。ask という権限判断を返す PreToolUse hook は、最終結果の下限を確認プロンプトに設定します。つまり、サンドボックス化されていない Bash コマンドを auto mode が許可へ引き上げることはできません。⁶⁹ 統制された harness にとって、これは欠けていた保証レベルです。完全自動の権限構成でも、hook の ask は確実に人間を判断ループへ介在させる停止点として機能します。拒否ではなく人間の判断を求めたい操作には、exit-2 によるブロックだけでなく ask を使用してください。 - classifier モデルはセッション単位で固定（v2.1.210）。 auto-mode classifier のデフォルトは Sonnet 5 で、セッション中はこのモデルに固定されます。そのため、セッション途中でモデルを切り替えても、権限分類を行うモデルは変わりません。分類の一貫性はガバナンス上の特性であり、この変更により目立たないドリフト要因が取り除かれました。 - MCP サーバーが /clear 後に消えなくなりました。 .mcp.json、plugins、claude.ai connectors で設定されたサーバーが、VS Code extension、JetBrains plugin、Agent SDK で /clear を実行した後、アクティブなセットから暗黙のうちに外れていました。この修正は v2.1.136 に含まれています。「セッション途中で MCP server X が消えた」という現象が起きていた場合、これが原因でした。 - MCP OAuth の同時更新による refresh-token 消失。 複数のリモート MCP サーバーを使用している場合でも、毎日再認証する必要がなくなりました。同時に行われた更新の書き込みが、互いを上書きしていたことが原因です。 - Plan mode がファイル書き込みを正しくブロックするようになりました。 一致する Edit(...) 許可ルールによって、plan-mode の書き込み保護が迂回されていました。現在は許可ルールにかかわらず Plan mode が適用されます。 - Plugin の Stop および UserPromptSubmit hooks がセッション途中で失敗しなくなりました。 キャッシュのクリーンアップ処理が、実行中のセッションでまだ使用されている plugin バージョンのファイルを削除し、特にこの2つの hook イベントを壊していました。修正後は、使用中のバージョンが固定されます。 - plugin.json の skills エントリ。 skills を設定すると、plugin のデフォルトの skills/ ディレクトリが表示されなくなっていました。現在はエントリが正しく合成され、ファイルパスを指定した場合も黙って失敗せず、明示的なエラーが表示されます。 - CLAUDE_ENV_FILE の SessionStart hook 環境変数が古くなる問題。 SessionStart hooks が CLAUDE_ENV_FILE 経由でエクスポートした変数は、/resume または /clear の後に古い状態となっていました。v2.1.136 で修正されています。現在は、これらのイベント時にセッションが環境変数ファイルを再度読み込みます。

ガバナンス用 harness の運用面で特に注目すべき項目は、autoMode.hard_deny（新しい制御手段）と MCP が消える問題の修正（長時間のセッションを壊していた目立たない障害）です。それ以外は、使い勝手を向上させるための整理です。

構造化された Hook 引数とブロック後の継続（2026年5月11日）

Claude Code v2.1.139 では、本番環境の harness にとって重要な hook の詳細が2つ追加されました。コマンド hooks 向けの args: string[] exec 形式と、PostToolUse hooks 向けの continueOnBlock です。⁴²⁴⁴ hook で動的な値やパスのプレースホルダーが必要な場合は、args を使用してください。シェルを介さずコマンドを直接起動するため、クォートやインジェクションに関する一連のミスを排除できます。

PostToolUse hook がフローを終了するのではなく、拒否理由を Claude に返してターンを続行させる場合は、continueOnBlock を使用してください。これはオペレーター体験を改善する機能であり、セキュリティを迂回する手段ではありません。ブロッキングゲートは、引き続き安全でない結果を阻止する必要があります。

同じリリースでは、CLAUDE_PROJECT_DIR が MCP stdio サーバーへ渡され、plugin 設定のコマンド内で ${CLAUDE_PROJECT_DIR} を参照できるようになりました。⁴² MCP ツールは、たまたまサーバーを起動したプロセスの作業ディレクトリではなく、この値を基準にプロジェクト相対パスを解決する必要があります。2026年7月上旬のリリース（v2.1.203〜v2.1.206）では、同じ原則がプロトコルレベルにも拡張されました。MCP roots/list にセッションの追加作業ディレクトリが含まれ、変更時には roots/list_changed 通知が送られるようになっています。これにより、MCP roots に対応するサーバーは単一のプロジェクトディレクトリを前提とせず、実際の複数ディレクトリからなるワークスペース構成を追跡できます。⁶⁸

Claude Code v2.1.140 は、主に harness オペレーター向けの信頼性向上リリースです。設定変更時に ConfigChange hooks が発火しない問題、設定レベルをまたいだ disableAllHooks と allowManagedHooksOnly の組み合わせが正しく機能しないエッジケース、hook の結果として返された意図しない環境変数が権限ダイアログに表示される問題を修正しています。⁴⁹ このセクションで説明している既存のガバナンスパターンがより確実に機能するようになりますが、新しい hook architecture は必要ありません。

Claude Code v2.1.141 では、制御端末がない場合でもデスクトップ通知、ウィンドウタイトル、ベルを扱える hook 出力の terminalSequence フィールドが追加されました。⁵⁰ これはオペレーターへのシグナルとして扱い、強制手段には使用しないでください。セキュリティゲートと品質ゲートでは、通常のブロック契約を通じて障害を伝える必要があります。つまり、構造化された hook 出力と、安全でない操作を防ぐ終了動作を使用します。同じリリースでは、Agent View の対象を1つのディレクトリに限定する claude agents --cwd <path>、GitHub SSH キーがない環境で plugin をインストールするための CLAUDE_CODE_PLUGIN_PREFER_HTTPS、複数のワークスペースを対象とする workload-identity federation ルール向けの ANTHROPIC_WORKSPACE_ID も追加されました。⁵⁰ これらはチーム用 harness に関する architecture 上の詳細です。運用ビューを絞り込み、plugin インストール時の前提を減らし、エンタープライズトークンの適用範囲を明示できます。

Claude Code v2.1.142 は、hook のセマンティクスよりも、バックグラウンドセッションのオーケストレーションにとって重要です。⁵¹ claude agents では、ラッパーの状態に依存せず、ディレクトリ、設定、MCP、plugin、権限、モデル、effort の各フラグを明示してバックグラウンドセッションをディスパッチできるようになりました。このリリースでは fast mode のデフォルトが Opus 4.7 となり、Opus 4.6 の動作に対する依存性が実測されている harness では、CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 で固定できました。v2.1.219 時点では、Opus 4.7 は fast mode の対象から完全に外れ、/fast は Opus 5 と Opus 4.8 に適用されます。⁸⁴ ルートレベルでの plugin SKILL.md の検出と、plugin が提供する LSP の可視化により、パッケージングの曖昧さが軽減されます。MCP_TOOL_TIMEOUT、既存のバックグラウンドセッション用 worktrees、daemon のスリープ／ウェイクとアップグレード後のクリーンアップ、plugin キャッシュのクリーンアップに関する修正により、オーケストレーションのバグに見えかねない信頼性の問題も解消されました。

Stop-hook によるステアリング、セッションをまたぐ権限、multi-agent v2（2026年6月）

6月上旬の4つの変更は、harness と multi-agent のデザインにとって重要です。⁵⁹

Stop/SubagentStop hooks にステアリングチャネルが追加されました。 Claude Code v2.1.163 以降、Stop または SubagentStop hook は hookSpecificOutput.additionalContext を返すことで、応答が hook エラーとして扱われることなく Claude にフィードバックを渡し、ターンを続行できるようになりました。これまでは、Stop hook が実質的に使える唯一の制御手段は exit-2 ブロックでした。しかし、これはエラーとして表示され、連続ブロック回数の上限にも加算されます。品質ゲート用 harness では、今回追加された仕組みのほうが適しています。「完了したと言っているが、テストは失敗している」と検出した Stop hook は、ハードブロックする代わりに「まだ失敗している項目はこれです。続行してください」と指示できるようになりました。本当に停止すべき条件にはブロックを使い、「まだ完了していません。その理由はこれです」という場合には additionalContext を使用してください。

セッションをまたぐメッセージが、借用した権限を引き継がなくなりました。 v2.1.166 では、複数セッションを使うケースが強化されました。別の Claude セッションから SendMessage 経由で中継されたメッセージは、送信元ユーザーの権限を引き継ぎません。そのため、受信側セッションは中継された権限リクエストを拒否し、auto mode もブロックします。agents 同士がメッセージを送るオーケストレーションでは、受信メッセージを認証済みの指示ではなく、信頼できないデータとして扱ってください。これは、セキュリティセクションでツール出力に適用している原則を、agents 間のメッセージングへ拡張したものです。v2.1.199 以降、同名の agents が2つ存在するために SendMessage が誤ってルーティングされた場合も、Claude Code が検出して警告します。これは権限境界を信頼性の面から補完する変更です。メッセージが誤った同名の agent に届くこと自体が、オーケストレーションにおける独立した種類のバグだからです。 モデルのレジリエンスが正式な設定項目になりました。 fallbackModel 設定では最大3つのバックアップモデルを連鎖させ、プライマリモデルが過負荷または利用不能になった場合に、指定した順序で試せるようになりました。また、予期しない再試行不能の API エラーが発生した場合、フォールバックモデルでターンが1回自動再試行されます。長時間稼働する自律型 harness では、プライマリモデルの一時的な障害によって実行が失われるのではなく、機能を穏やかに縮退させて継続できます。claude agents --json には、ブロック中のバックグラウンドセッションが何を待っているのか（権限プロンプトなど）を示す waitingFor フィールドも追加されました（v2.1.162）。エージェント群をポーリングするあらゆるコーディネーターにとって、可観測性の向上につながります。

クリーンルームでのガバナンスとトラブルシューティングに使えるセーフモード。 Claude Code v2.1.169では、すべてのカスタマイズを一括で無効化してセッションを開始する --safe-mode フラグ（および対応する CLAUDE_CODE_SAFE_MODE 環境変数）が追加されました。無効になるのは、CLAUDE.md、プラグイン、skills、hooks、MCP サーバーです。⁶⁰ これは harness の対極にある、意図的なクリーンルームです。すべての運用者がいずれ抱く「この挙動はモデルによるものなのか、それとも自分の設定によるものなのか」という疑問に答えるために使えます。hook が誤作動したとき、skill が意図せず有効になったとき、あるいは MCP サーバーによってコンテキストが汚染されたとき、--safe-mode を使えば、比較対象となる既知の空のベースラインを得られます。ガバナンスの基本要素としても有用です。通常は harness によって付与される永続的な権限を一切持たない素のモデルを実行できるため、運用者が定義した足場の影響を排除して結果を再現する必要がある場合に重要となります。

モデル階層について。 Claude Code v2.1.197（2026年6月30日）以降、Claude Sonnet 5が新規セッションに同梱されるデフォルトモデルとなりました。ネイティブの1Mコンテキストを備え、8月31日までは100万トークンあたり$2/$10のプロモーション価格が適用され、初期設定の選択肢としてOpus 4.8を置き換えています。このガイドでは、Opus 5（claude-opus-5）を推奨するエージェント向けデフォルトとして扱います。意図的に別のモデルを選ばない限り、自律型 harness を実行するモデルです。長期間にわたる高リスクなエージェントループは、まさにOpusの深い推論がコストに見合う領域だからです。Opus 5は2026年7月24日、Claude Code v2.1.219の新しいデフォルトOpusとしてリリースされました。1Mコンテキストを備え、価格は100万トークンあたり$5/$25（置き換え対象のOpus 4.8と同額）、fast modeは約2.5倍の速度で$10/$50です。さらにAnthropicによると、Frontier-Bench v0.1ではOpus 4.8のスコアを2倍以上に伸ばし、CursorBench 3.2では半分のコストでFable 5のスコアとの差を0.5%以内に収めています。⁸⁴⁸⁷ 同じ価格で能力が高まり、Anthropicが「自身の作業を検証し、慎重に反復する能力がはるかに高い」と評するモデルです。harness 用途ではコスト面の説明すら不要な、まれに見るアップグレードといえます。4.8からの移行に必要なのはIDの変更だけです。コスト重視の作業や大量処理では、速度と知能のバランスに優れるSonnet 5へ切り替えてください。Opusの上位には、2026年6月9日に登場したClaude Fable 5（claude-fable-5）があります。Anthropicが最も強力なモデルであり、一般利用に向けて安全性を確保した「Mythos-class」システムと説明する新しい階層で、Claude Code v2.1.170では/model claude-fable-5から選択できます。⁶⁰ この上位階層はエージェント群の一律設定にするのではなく、生の推論力がコストに見合う意思決定で、意図を持って選びましょう。Opus 5への移行には、運用上の変更が2点あります。Opus 4.7はfast modeの対象外となり（/fastはOpus 5とOpus 4.8に適用されます）、v2.1.176以降「利用可能な最良のOpusモデル」とされてきたauto-mode分類器のFable-5フォールバックは、今後Opus 5に解決されます。⁸⁴

Codexでmulti-agent v2がリリースされました。 Codex CLI v0.137.0では、ランタイムの選択を各スレッドに持たせたまま、生成されたエージェント向けのフォローアップとメタデータのデフォルトが整理されました（hide_spawn_agent_metadataのデフォルトはtrueになりました）。また、未加工の親イベントが子リスナーへ伝播されます。subagentモデルは引き続き明示的です。組み込みのdefault/worker/explorerエージェントタイプ、TOMLで定義するカスタムエージェント、同時実行制御（agents.max_threadsのデフォルトは6、agents.max_depthのデフォルトは1）で構成されます。同じリリースには、ターンごとのskillカタログ解決と、スレッド開始時およびターンエラー時に発生する新しいライフサイクルコントリビューターイベントを備えたv1 skills拡張も追加されました。これにより、カーネルサンドボックスをデフォルトの境界とする姿勢を維持しつつ、Claude Codeのhook/skillサーフェスとの差を縮めています。続くCodex v0.138.0〜v0.139.0では、multi-agent v2が本番運用向けに強化されました。エージェント間のメッセージペイロードが暗号化され、v2エージェント設定カタログとエージェント常駐用LRUによって常駐するエージェントが管理されるようになりました。また、同時実行数は生成されたスレッド数ではなく、実行中の処理を基準に計測されるため、アイドル中のエージェントはスロットを消費しません。⁶¹ ライフサイクルの API も成熟しました。close_agentは、単にハンドルを閉じるのではなく、実行中のエージェントを中断するという実態を反映してinterrupt_agentへ改名されました（v0.139.0）。また、subagentが発した MCP 起動警告は、その所有スレッド内に限定されるようになり、親のトランスクリプトへ重複して表示されることもありません。⁶¹ Codex側でオーケストレーションを構築する場合、これらはデモとエージェント群を分ける重要な要素です。暗号化されたメッセージ転送、上限付きの常駐管理、実行数に基づく同時実行制御、そしてスレッド境界を越えて漏れない警告が揃います。続くCodex v0.140.0では、異なるツールをつなぐ接点が開かれました。/importを使うと、セットアップ、プロジェクト設定、最近のチャットをClaude CodeからCodexへ選択的に取り込めます。また、セッションを完全に削除できるようになりました（確認による安全対策を備えたcodex delete / /delete）。⁶⁴ /importは、運用者が複数のharness間を移動するという事実を公式に認めた初めての機能です。一方のために構築した設定が、そこに閉じ込められることはもうありません。

メモリとコンテキスト

すべての 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 行をシステムプロンプトへ読み込みます。簡潔に保ち、詳細なメモはトピック別のファイルへリンクしてください。⁶ v2.1.210 以降では、サイズ制限を超える MEMORY.md への書き込みは、警告なく切り捨てられるのではなく、エラーになります⁶⁹。そのため、メモリエントリがひそかに消えるのではなく、書き込み時に失敗が表面化します。harness でメモリへの書き込みを自動化している場合は、このエラーを処理してください。これは再試行を求めるものではなく、ファイルの整理が必要だというプラットフォームからの通知です。

メモリ量よりもメモリの整理（2026年5月）： LLM エージェント間の協力に関する最近の arXiv プレプリントでは、呼び出せる情報の拡大が失敗要因になり得ると指摘されています。著者らの実験では、モデルを用いたゲームの 28 設定中 18 設定で、表示される履歴が長くなるほど協力の質が低下しました。⁴⁸ これは確立された法則ではなく、デザイン上の警告として受け止めてください。本番環境での原則は、すでに十分明確です。MEMORY.md は短く保ち、詳細へリンクし、引き継ぎには意思決定にすぐ使える要約を含めます。未加工の会話記録、ツールログ、長大な呼び出し情報は検索可能なストレージに保存し、アクティブなプロンプトへ自動的に含めないようにします。

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

圧縮が会話を守るのに対し、/cd コマンド（Claude Code v2.1.169）はプロンプトキャッシュを守ります。このコマンドを使うと、ターンを通じて蓄積されたキャッシュを壊さずに、セッションの途中で新しい作業ディレクトリへ移動できます。⁶⁰ 以前は、ディレクトリを変更すると新しいセッションと空のキャッシュが必要でした。長時間実行しているセッションで、あるリポジトリから同階層の別リポジトリへ移る場合、特にモノレポや複数サービスを扱う作業では、/cd によってコストの高いキャッシュ済みプレフィックスを維持しながら、ファイルシステムのコンテキストを切り替えられます。

戦略 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 Loop）

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 のメモリストアへ書き込みます。エージェントはそれをセッション開始時に読み込みます。セルフホスト型のファイルシステム状態と、管理サービス側の整理機能を組み合わせる harness では、この 2 つのパターンを併用できます。

Dreaming は Research Preview のため、動作が変更される可能性があります。前述したセッション引き継ぎと CLAUDE.md のパターンは、セルフホスト型 harness における正式なメモリメカニズムであり続けます。

アンチパターン

10 行しか必要ないのに、ファイル全体を読み込むこと。 2,000 行のファイルを 1 つ読み込むだけで、15,000〜20,000 トークンを消費します。行オフセットを使用してください。Read file.py offset=100 limit=20 なら、そのコストの大部分を削減できます。¹⁵

冗長なエラー出力をコンテキストに残すこと。 バグのデバッグ後、失敗した反復による 40 件以上のスタックトレースがコンテキストに残ることがあります。バグを修正した後に /compact を 1 回実行すれば、その不要な情報を取り除けます。

各セッションの開始時に、すべてのファイルを読み込むこと。 Claude Code の glob と grep ツールを使って必要なファイルを必要なときに探せば、不要な事前読み込みによる 100,000 トークン以上の消費を防げます。¹⁵

Subagent パターン

Subagents は、複雑なタスクを独立して処理する特化型の Claude インスタンスです。汚染されていない新しいコンテキスト（メインの会話からの影響がない状態）で開始し、指定されたツールを使用して、結果を要約として返します。調査結果によってメインの会話が肥大化することはなく、結論だけが返されます。⁵

組み込みの Subagent タイプ

カスタム Subagents の作成

Subagents は .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.

Subagent の設定フィールド

Worktree による分離

Subagents は一時的な 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 v2.1.210 では、worktree で分離された subagents がメインのチェックアウトを変更できてしまう不具合が修正されました。これは、まさにこの仕組みが防ぐために存在する問題です。⁶⁹ isolation: worktree を単なる利便性ではなく安全境界として利用する場合は、v2.1.210 を最低要件としてください。一方、同時期の権限変更は反対方向に作用します。v2.1.211 以降、「常に許可」ルールは worktree をまたいでリポジトリルートに保持されるため、ある worktree 内で承認されたルールは、同じリポジトリの兄弟 worktree にも適用されます。⁶⁹ 並列 worktree エージェントにとっては適切な操作性ですが、使い捨ての実験中に与えた許可が実験終了後も残ることを意味します。目の前の worktree だけではなく、リポジトリ全体を念頭に置いて許可してください。

v2.1.216 でこの対応が完了し、worktree による分離は不具合修正の域を越えて、強制力のある仕組みになりました。⁷⁴ v2.1.210 の修正では、通常の git 呼び出しを通じて worktree の subagents がメインのチェックアウトを変更することを防ぎました。しかし、git 自体には明示的なリダイレクト手段があります。git -C <path>、--git-dir、そして GIT_DIR/GIT_WORK_TREE 環境変数を使えば、worktree で分離された subagent でも共有チェックアウトを指定できました。現在では、これらの抜け道はすべて塞がれています。同じリリースでは、worktree セッションが別のプロジェクトに残された worktree へ誤って入ることがある問題、.claude に置かれたプロジェクト外へのシンボリックリンクを workflow やスケジュール済みタスクの書き込みがたどる問題も修正され、/rewind はシンボリックリンクとハードリンクをたどらないようになりました。4つの修正に共通する原則は同じです。分離境界は、デフォルトの動作だけでなく、git 環境変数によるオーバーライドやシンボリックリンクの設置といった意図的なリダイレクトに対しても維持されなければなりません。harness において isolation: worktree が利便性ではなく安全境界である場合、現在の最低要件は v2.1.216 です。

並列 Subagents

互いに連携する必要のない独立した調査タスクには、並列 subagents を使用します。⁵

> 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」です。生成予算では、親ごとのアクティブな子の総数を追跡し、設定可能な上限を適用します。予算モデルは、代理指標（ネストレベルが多すぎること）ではなく、実際の障害モード（エージェント総数が多すぎること）に対応しています。⁷

ネスト深度のデフォルト値は3回変わっています。これを前提に構築してはいけません。 Claude Code v2.1.172（2026年6月10日）では、sub-agents が自身の sub-agents を生成できるようになり、以前は実質1階層だった委任が最大5階層までネスト可能になりました。⁶² この状態は v2.1.172 から v2.1.216 まで続きました。v2.1.217（2026年7月21日）では1に減らされ、ネストした生成がデフォルトで無効になりました。その後、v2.1.219（2026年7月24日）では中間に落ち着きました。「Subagents はデフォルトで深さ3までネストした subagents を生成できるようになりました（従来は1）。ネストを無効にするには CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 を設定します」。⁸⁴ 5、1、3と変わり、直近2回の変更は3日以内に行われています。

ここから読み取るべきなのは、いずれかの数値が正しいということではありません。プラットフォームが適切なデフォルトをまだ模索しているため、harness が「出荷時の値」をそのまま継承するのは誤りだということです。ネスト深度は明示的な予算項目として扱ってください。CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH には、アーキテクチャで実際に必要な深度（多くのオーケストレーションでは1または2）を設定し、アップグレードによってフリートの委任深度がひそかに変わらないようにします。こうした変更があっても、基本的な主張は変わりません。エージェントからエージェントへ委任するチェーンは、結果を生み出す以上の速さでコンテキストとトークンを消費します。深度は積極的に活用すべき機能ではなく、予算化すべきリスクです。上記の再帰ガードは、今後デフォルトがどちらへ動いても、深いツリーが数百体のアクティブなエージェントへ扇状に広がるのを防ぎます。また、次のリリース後も想定どおりの意味を保つ深度の数値は、自分で設定した制限だけです。

Auto mode では、生成前の審査が行われるようになりました。 Claude Code v2.1.178 では、対応するガバナンス上の抜け穴が塞がれました。auto mode では、subagent が動作を開始してからだけでなく、起動する前に権限分類器によって生成が評価されます。⁶³ 以前は、親セッションではブロックされる動作を要求するために subagent を生成でき、生成自体が迂回手段になっていました。生成時に審査することで、再帰ガードと権限モデルがようやく接続されました。ポリシーで禁止された動作を実行するためのロンダリング手段として、子を利用することはできません。

プラットフォームにネイティブの生成予算が搭載されました。 Claude Code v2.1.212（2026年7月）では、暴走ループに対するファーストパーティのガードレールが追加されました。セッションごとの subagent 生成数はデフォルトで200に制限され（CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION で調整でき、/clear でカウンターがリセットされます）、WebSearch もセッションごとに200回までとなります（CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION）。⁶⁹ このセクションで v1.0 からユーザーランドスクリプトとして説明してきた生成予算パターンが、プラットフォームから提供されるようになりました。これは、深度モデルより予算モデルが適切であることの裏付けです。ただし、調整値には注意してください。200回という生成数は、上記設定の12体という予算より1桁多い値です。ネイティブの上限は、アーキテクチャに合わせて調整された予算ではなく、実際に暴走したループを止めるためのヒューズです。親ごとの予算、深度の追跡、オーケストレーションが実際に行うべきことに即した制限には、引き続きユーザーランドのガードを使用してください。プラットフォームの上限には、そこをすり抜けたものを捕捉させます。

ファーストパーティのガードレール群は、現在4つの軸を網羅しています。 そのうち3つは、このセクションのユーザーランドガードが追跡する項目をそのまま補完します。セッションごとの総生成数（v2.1.212、上限200、CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION）、ネスト深度（CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH。現在のデフォルトは3ですが、不安定であることが実証されています）、同時実行数（v2.1.217、デフォルト20、CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS。1つのメッセージから無制限にバックグラウンドエージェントを展開できなくなりました）です。⁷⁸⁸⁴ v2.1.219 では、ユーザーランドガードには通常なかった4つ目の軸、オーケストレーションの幅が追加されました。これは1つの計画済み workflow に含められるエージェント数で、デフォルトのガイドラインとして「エージェント数は15体未満を目指す」が提供され、任意の設定ファイルから workflowSizeGuideline で指定できます（後述の Workflow Tool セクションで説明します）。生成予算パターンは、設計対象だったすべての軸に加え、対象外だった1つの軸でも補完されるようになりました。

調整値に関する注意は依然として当てはまりますが、均一ではありません。200回の生成と20体の同時実行エージェントはヒューズです。上記設定にある12体の deliberation 予算より1桁多く、アーキテクチャを形作るのではなく、暴走ループを捕捉するために設定されています。幅のガイドラインは、実際の予算と同じ尺度にある初めてのネイティブな数値です。workflow ごとの15体という値は、このガイドの12体と隣り合う水準です。プラットフォームのデフォルトを採用しても問題がないほど近く、異なる値を選ぶなら明確な理由が必要になります。3つのヒューズには説明可能な値を設定し、幅のガイドラインには意図したオーケストレーションの形を反映してください。

Agent Teams（Research Preview）

Agent Teams は、独立して動作しながら共有 mailbox とタスクリストを通じてやり取りし、互いの調査結果に異議を唱えることもできる複数の Claude Code インスタンスを連携させます。⁵

有効化：export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

agent teams と subagents の使い分け：

Agent View と Goal Loops（2026年5月）

Claude Code v2.1.139 では Agent View が追加されました。これは claude agents で起動する Research Preview のインターフェースで、実行中、ブロック中、完了済みの Claude Code セッションを1つの画面に表示します。⁴²⁴³ 公式ドキュメントでは、多数のセッションを割り当てて管理し、各セッションの動作を確認しながら、オペレーターの入力が必要なものを特定する手段と説明されています。⁴³ これにより、最終要約だけでは得られない運用ビューをマルチエージェント作業に提供できます。

subagent や team のパターンを本格導入するときは Agent View を使用し、ブロックされているセッション、まだ実行中のセッション、作業分担が意図したアーキテクチャに合っているかを確認してください。ただし、品質の証明として扱ってはいけません。これは可観測性のための機能です。作業が健全かどうかは、引き続きテスト、レビューゲート、エビデンスレポートで判断します。

同じリリースでは /goal も追加されました。完了条件を設定すると、その条件を満たすまで Claude が複数のターンにわたって処理を継続できます。対話モード、-p、Remote Control でも利用できます。⁴² /goal は、決定論的なゲートの代替ではなく、セッションスコープの完了ループとして扱ってください。エージェントを目標へ集中させるのには役立ちますが、失敗時に処理をブロックする必要があるテスト、引用チェック、デプロイチェック、セキュリティ hooks は、引き続きコマンドまたはスクリプトで実行すべきです。

Workflow Tool（v2.1.147以降）

Claude Code v2.1.147 では、決定論的なマルチエージェントオーケストレーションに使用する Workflow tool が追加されました。デフォルトでは無効で、CLAUDE_CODE_WORKFLOWS=1 を設定すると有効になります。⁵² アーキテクチャ上、この機能は重要です。以前はカスタムのディスパッチスクリプト、mailbox の状態、subagent の連携規約が必要だったフローに対し、Claude Code がファーストパーティのオーケストレーションプリミティブを提供するためです。

ただし、その周囲にある harness を削除してはいけません。Workflow は実行を構造化できますが、安全モデルの代わりにはなりません。ブロック層として PreToolUse と PostToolUse hooks を維持し、幅の暴走を防ぐために生成予算または workflow ステップ予算を残し、ファイルシステムの状態を監査可能に保ち、最終的なエビデンスレポートはモデルの自己評価から切り離してください。実際には、オーケストレーションの形には Workflow を、真偽の判定には hooks、テスト、レビューゲートを使用します。

Dynamic workflows には、幅に関する方針が組み込まれるようになりました（v2.1.219）。 Dynamic workflows のデフォルトは中規模のガイドライン、つまり「エージェント数は15体未満を目指す」です。/config の Dynamic workflow size では、ほかのサイズや無制限のオプションも選択でき、実行中の workflow のステータス行には現在のガイドラインが表示されます。⁸⁴ この数値は強制ではなく助言であり、幅の広い計画をブロックするのではなく、プランナーを誘導します。設定する価値があるのは、その提供方法です。新しい workflowSizeGuideline 設定キーは、managed settings やプロジェクト設定を含む任意の設定ファイルから指定でき、v0.3.219 以降は TypeScript SDK の設定型にも含まれています。そのため、オーケストレーションの幅を、オペレーターごとに再発見するものではなく、チームや組織で標準化できるようになります。⁸⁵ プロジェクトレベルで設定し、コードベースの作業が実際にどのように分解されるかを表現してください。オペレーター向けの注意点が2つあります。設定ファイルによって値が指定されている間は /config の行が非表示になります。これは正しい動作ですが、理由を知らなければ設定項目が欠落しているように見えます。また、このガイドラインは実行を制限するのではなくプランナーを誘導するものなので、安全性ではなく形の項目に属します。幅の暴走を止める役割は、引き続き生成数の上限が担います。

重要なのは、これがファーストパーティのガードレールにおける4つ目の軸、つまり生成数、ネスト深度、同時実行数に並ぶオーケストレーションの幅であり、Anthropic が暴走防止用のヒューズではなく、現実的な作業規模として初めて調整した数値だという点です。workflow ごとの15体は、このガイドが v1.0 から使用している12体の deliberation 予算と同じ桁です。プラットフォームのデフォルトと独自の予算が別々の方向から収束したなら、こうした数値としては独立した裏付けに最も近いものと言えるでしょう。

セッションの Fork と MCP の自動バックグラウンド化（2026年7月）

Claude Code v2.1.212 では、2つのオーケストレーションプリミティブが再構成されました。⁶⁹ /fork は現在、会話の現時点の状態から新しいバックグラウンドセッションを作成します。fork された分岐は独立して実行され、元のセッションも作業を継続します。以前のセッション内での動作は /subtask に改名されました。この違いは、オーケストレーションの設計で重要です。/subtask は1つのセッションのライフサイクル内で行う範囲限定の寄り道ですが、/fork は完全なコンテキストを継承する並列バックグラウンドセッションを低コストで生成する手段であり、subagent より Ralph-loop の生成に近いものです。harness のスクリプトが /fork をセッション内に留まるものと想定していた場合、現在はバックグラウンド作業をディスパッチすることになります。

同じリリースでは、遅い MCP 呼び出しも自動的にバックグラウンド化されます。2分を超えて実行される MCP tool の呼び出しは、自動的にバックグラウンド実行へ移されます（しきい値は CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS で調整できます）。⁶⁹ 遅い MCP サーバーが agentic ループを停止させることはなくなりました。しかし同時に、「ツールが結果を返したこと」と「ターンが続行されたこと」は同じイベントではなくなります。MCP の同期的な完了を前提としていた hooks やスクリプトは、ターンの境界ではなくツールの結果を基準にしてください。

ヘッドレスなオーケストレーション向けには、v2.1.211 で --forward-subagent-text（環境変数：CLAUDE_CODE_FORWARD_SUBAGENT_TEXT）が追加され、subagent のアシスタントテキストを stream-json 出力へ転送できるようになりました。⁶⁹ 親のストリームを処理するコーディネータープロセスは、トランスクリプトをポーリングしたり最終要約を待ったりせずに、subagent の進捗を直接観測できます。これは、デフォルトでバックグラウンド実行される subagents を可観測性の面で補完する機能です。v2.1.219 では、この機能が第1階層より先にも拡張されました。深さ2以降で生成された subagents のテキストも、生成元の Agent tool_use id をキーとして転送ストリームに表示されます。⁸⁴ 実装の基盤とすべきなのは、このキーです。ネストが再びデフォルトで有効になったことで、subagent のテキストを平坦なストリームに流すだけでは曖昧になります。この id があれば、どの親がどの子を生成したのかをコーディネーターが把握でき、委任ツリーを推測せずにストリームから再構築できます。ストリームの処理側が1階層の subagents を前提に作られている場合、存在を認識していなかったエージェントのテキストも受け取るようになります。転送されたすべての行が直接の子に属すると仮定せず、生成元の tool_use id ごとにグループ化してください。

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

シングルエージェントの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 は、人間向けの README ではなく、AI agent の運用ポリシーです。²¹ conventional commits を使用する「理由」を agent が理解する必要はありません。実行すべき正確なコマンドと、何をもって「完了」とするかを把握する必要があります。

優先順位

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

無視されるもの

次のパターンを記述しても、agent の動作には一貫して目に見える変化が現れません。²¹

コマンドを含まない説明文。 「クリーンで十分にテストされたコードを重視します」は運用指示ではなく、単なる説明です。実行可能な指示がないため、agent はこれを読んでもテストを書かずにコーディングを進めます。

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

矛盾する優先事項。 「素早く開発してリリースする」「包括的なテストカバレッジを確保する」「実行時間を5分未満に抑える」「コミットの前に毎回、完全な統合テストを実行する」。agent はこの4つを同時に満たせないため、デフォルトでは検証を省略します。²¹

強制手段のないスタイルガイド。 「Google Python Style Guide に従ってください」と記載しても、ruff check --select D がなければ、agent には準拠を検証する手段がありません。

効果的な書き方

コマンドを先に示す指示：

## 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. ディレクトリごとの適用範囲（monorepos：サービスごとの指示を分離します）

最初の4つが機能するまでは、スタイルの好みに関する指示を省いてください。

現在では、プラットフォームが CLAUDE.md を監査してくれます。 2026年7月上旬のリリース（v2.1.203〜v2.1.206）以降、/doctor は CLAUDE.md を分析し、コードベース自体からモデルが推測できる内容を削るよう提案します。たとえば、ディレクトリ構成の言い換え、コードにすでに表れているフレームワークの規約、package scripts と重複するコマンド一覧などです。⁶⁸ これは、このセクションの主張を公式に裏付けるものです。指示にトークンを割く価値があるのは、agent が推測「できない」内容（ポリシー、しきい値、完了条件）を記述するときであり、ディスクから読み取れる内容ではありません。CLAUDE.md が大幅に増えたら /doctor を実行し、削減案を出発点として扱ってください。ただし、「推測可能」と判定された運用ルールでも、単なる説明ではなく不可欠な制約である場合は残しましょう。

ファイルのインポート

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つ作成し、そこから反映しましょう。

Codex との対応に関する注意事項

Codex には主要な harness レイヤーに対応する第一級の機能が揃っていますが、移行はファイルのコピーではなく、パターンの変換として行う必要があります。Codex は作業開始前に AGENTS.md を読み込み、~/.codex のグローバルな指示に、プロジェクトおよびリポジトリ内の階層ごとの指示を重ねます。³¹ Codex skills も、段階的開示を採用した同じ SKILL.md の考え方を使用します。Codex はまず skill の名前、説明、ファイルパスを確認し、その skill を使用すると判断した場合にのみ全文を読み込みます。³² Codex には、ネイティブ hooks、プラグインに同梱された hooks、managed hooks、MCP のサポート、明示的な subagents ワークフローもあります。³³³⁴

Codex v0.138.0〜v0.139.0 では、複雑なワークスペースにおける AGENTS.md の検出が強化されました。読み込みが環境のファイルシステム抽象化を経由するようになり、検出時の走査でも論理パスが維持されます。そのため、ワークスペースがリモートファイルシステムやシンボリックリンクを使用したツリーでも、適切なファイルが選択されます。⁶¹ 正規の AGENTS.md を信頼できる情報源とし、agent がマウント済み、コンテナ内に展開済み、またはシンボリックリンクされたチェックアウト上で動作する場合には、これが重要です。単純なパス走査では、誤った指示ファイルを選んだり、何も見つけられなかったりするケースだからです。信頼できる1つの AGENTS.md を複数のサービスへ反映する場合、agent が実際に読み込んだファイルと作成したファイルが一致すると信頼するための最低条件として、このバージョンを扱ってください。

続く Codex v0.141.0 では、リモート実行パス自体が強化されました。リモート executor は、認証済みでエンドツーエンド暗号化された Noise-relay channels を介して接続するようになり、コントロールプレーンと executor は、その間にある relay を信頼する必要がなくなりました。また、クロスプラットフォームのリモート実行では executor 固有の作業ディレクトリとシェルが維持され、TLS は企業プロキシ向けの P-521 証明書署名を受け入れます。⁶⁵ オーケストレーションによって Codex executor をネットワーク境界の外側で動作させる場合、これは信頼済み relay を前提とする構成と、エンドツーエンド暗号化された構成を分ける重要な違いです。リモート executor を使用するあらゆるトポロジーの基準として扱ってください。

2026年7月のリリースを見ると、2つのランタイムが異なる方向から同じ基本要素へ収束していることが分かります。⁷² Codex v0.143.0 では、MCP ツールがデフォルトで tool search 経由で読み込まれるようになりました。ツールスキーマを最初からコンテキストへ投入せず、必要になった時点で取得します。これは、Claude Code が ToolSearch サーフェスで提供する遅延ツール読み込みと同じパターンであり、MCP ツールが多い場合のコンテキスト肥大化に対する、両ランタイム共通の適切な解決策です。Codex v0.144.0 では、writes app-approval mode が追加されました。読み取り専用の操作は確認なしで実行され、書き込みには承認が必要となります。これは、読み取り専用と自動承認の中間に位置する、まったく新しい権限モードの基本要素です。Claude Code のモード一覧には直接対応するものがありません。最も近いのは plan mode ですが、書き込みごとに確認するのではなく、書き込みを完全にブロックします。同じリリースで、MCP の対話型認証が GA となりました。さらに v0.144.5 では危険なコマンドの検出範囲が拡大され、Claude Code が v2.1.183 と v2.1.208 で導入した破壊的コマンドに対するガードレールと同様の仕組みが実装されました。ランタイムをまたぐ harness の設計で重要なのは、この収束です。ツールの遅延読み込み、段階的な書き込み承認、意図レベルでの危険なコマンドのブロックは、ベンダーごとの差別化要素ではなく、当然備えるべき機能になりつつあります。

Codex v0.145.0 では、2つの側面でこの収束がさらに進みました。⁷⁶ オプトインの multi-agent V2 サーフェスが安定化し、sub-agent のモデル、推論レベル、同時実行数を設定できるようになりました。以前削除された agent ロールも復元されています。これは、.claude/agents/ の frontmatter で subagent ごとにモデルと effort を設定する仕組みに対する、Codex 側の回答です。また、/import は harness 間の完全な移行機能へと発展しました。v0.140.0 で導入された Claude Code の設定インポートに加え、Claude Code と Cursor の両方から設定を移行できるようになりました。MCP サーバー、プラグイン、セッション、コマンド、プロジェクト固有のメモリも対象です。両方のランタイムを運用するチームにとって、一方向の移行コストは低下し続けています。Claude Code 上で構築した harness レイヤー（サーバー、コマンドとしての skills、メモリ）は、ベンダーロックインではなく、持ち運び可能な状態へと変わりつつあります。

実際の対応関係は次のとおりです。

重要な違いは、Claude subagents は説明に基づいて自動的に選択される可能性がある一方、Codex では現在、subagent ワークフローを明示的に実行するものとして文書化している点です。そのため、Codex で常時適用する harness の動作には、skills と hooks をデフォルトとして使用するのが適切です。subagents は、意図的な並列作業、レビュー、探索に使用します。

指示をテストする

agent が指示を実際に読み、それに従っていることを検証してください。

# 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?"

決定的なテスト： agent にビルドコマンドを説明させてください。そのまま正確に再現できなければ、指示が冗長すぎる（コンテキストから内容が押し出されている）、曖昧すぎる（実行可能な指示を抽出できない）、または検出されていないかのいずれかです。2,500件のリポジトリを対象とした GitHub の分析では、ほとんどの失敗は曖昧さが原因だと判明しています。²¹

本番環境のパターン

Opus 4.7の長期実行パターン（2026年4月）

Claude Opus 4.7（2026年4月16日）では、harnessで対策すべき対象を変える特有の機能が導入されました。²⁹

• ツール障害への耐性： Opus 4.7は、Opus 4.6ではセッションが停止していたツール障害が発生しても処理を継続します。subagentsのコードに含まれる防御的な再試行ラッパーは減らせますが、完全には排除できません。hookレベルのガードは維持しつつ、プロンプト内の「ツールが失敗した場合は3回再試行する」といった足場は削減してください。
• xhigh effort階層（Opus-4.7のみ）： highとmaxの中間に位置し、コーディングやエージェント型ワークロードの推奨デフォルトです。長時間実行するsubagentsでは、xhighはhighを明確に上回る性能を発揮しながら、トークンコストの増加は性能向上率よりも小さく抑えられます。単発の難しい推論には引き続きmaxが適していますが、継続的なタスクにはxhighのほうが適しています。
• トークン予算の上限： エージェントの実行ごとにoutput_config.task_budget（ベータヘッダーtask-budgets-2026-03-13）で設定できます。モデルには残り予算のカウントダウンが表示されるため、予期せぬトークン切れを起こす代わりに、予算内に収まるよう作業範囲を適切に調整できます。短いプロンプトの品質を犠牲にせず、トークン消費量を予測可能にしたいエージェント型ループで使用してください。
• 暗黙的なニーズの認識： ユーザーの明示的な依頼だけでは実際のニーズが十分に表現されていないことを認識する「implicit-need」テストに初めて合格したClaudeモデルです。これにより、CLAUDE.mdの「確認ルール」セクションの必要性が低下します。CLAUDE.mdが「ユーザーがYを依頼した場合はXも考慮する」といったガードレールで200行に及ぶなら、モデルがネイティブに対応できるようになったものは削除してください。

Worktreeのベース、Sandboxのパス、管理者設定（2026年5月7日）

Claude Code v2.1.133では、本番環境のharnessで把握しておくべき4つの管理者階層設定が追加されました。³⁹

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

エンタープライズ可観測性向けOTelフィードバック調査（2026年5月8日）

Claude Code v2.1.136では、OpenTelemetryを通じて回答を収集する企業向けに、セッション内の品質調査を再有効化するCLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTELが追加されました。⁴⁰ 組織がOTelイベントを中央の可観測性スタックへ送信している場合、この環境変数によって調査がデータ経路へ戻され、品質シグナルがレイテンシーやエラーの指標と同じパイプラインを流れるようになります。オプトインとして扱ってください。デフォルトでは調査が抑制されており、OTelを使用しないデプロイではこの動作が適切です。

企業向けランチャーとMCP規模のパフォーマンス（2026年7月）

v2.1.207では、本番環境へのデプロイに影響する変更が2つあります。⁶⁸ CLAUDE_CODE_PROCESS_WRAPPERを使用すると、管理対象環境で企業指定のラッパーバイナリを介してClaude Codeプロセスを起動できます。エンドポイントエージェント、起動時のポリシーチェック、すべてのプロセスを指定されたスーパーバイザーの配下で実行しなければならない環境との統合ポイントです。これまでシェルエイリアスやフォークしたランチャースクリプトで代用していた企業には、正式にサポートされる接続点となります。

同じリリースでは、harnessへの影響が最も大きいランタイムオーバーヘッドも削減されました。MCPツールの数が多いセッションでは、ツール使用ラウンドが最大7倍高速化され、セッションのトランスクリプトは79分の1に縮小されています。⁶⁸ これにより、アーキテクチャとしてのコストの指針は覆らないものの、影響が緩和されます。ステートレスな単発処理では引き続きCLI優先が有利ですが、多数のMCPツールを抱えるharnessでも、春先ほどのラウンド単位のペナルティは発生しなくなりました。また、長時間の自律実行でトランスクリプトの保存が隠れたコストになることもなくなります。

quality loop

重要な変更すべてに必須となるレビュープロセスです。

1. 実装 - コードを記述します
2. レビュー - すべての行を読み直し、誤字、ロジックエラー、不明瞭な箇所を見つけます
3. 評価 - evidence gateを実行し、パターン、エッジケース、テストカバレッジを確認します
4. 改善 - すべての問題を修正します。「後で」に先送りしてはいけません
5. 俯瞰 - 統合ポイント、import、隣接するコードにリグレッションがないか確認します
6. 反復 - evidence gateの基準を1つでも満たさない場合は、手順4へ戻ります
7. 報告 - 変更内容と検証方法を列挙し、具体的なevidenceを示します

evidence gate

「そう思う」や「そのはず」はevidenceではありません。ファイルパス、テスト出力、具体的なコードを示してください。

いずれかの行についてevidenceを提示できない場合は、改善へ戻ってください。²²

人間によるマージ権限

2026年5月に発表された29,585件のAIエージェントによるプルリクエストのライフサイクルを対象としたarXivの研究では、運用上の権限とマージのガバナンスを分けています。⁴⁷ アーキテクチャ上の教訓は明快です。エージェントは作業を開始し、ブランチで作業を進め、PRを作成し、成果物をレビューし、リスクを要約できます。一方、マージ権限は独立したガバナンス境界として維持します。

harnessでは、この境界を明示してください。エージェントにはPRの準備とevidenceの収集を許可しますが、組織に別途監査済みの自動化ポリシーがない限り、マージ、リリース、リポジトリに対する破壊的操作には人間の承認を必須とします。自動化によってマージを実行する場合は、実行主体と、承認した人間またはポリシーを区別できるログを保存してください。

エラー処理パターン

アトミックなファイル書き込み。 複数のエージェントが同じ状態ファイルへ同時に書き込むと、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が0の場合、0++の評価結果が0になり、bashではfalseとして扱われるため、((VAR++))は終了コード1を返します。set -eが有効だと、これによってスクリプトが終了します。代わりにVAR=$((VAR + 1))を使用してください。¹⁶

影響範囲の分類

エージェントによるすべての操作を影響範囲ごとに分類し、それに応じたゲートを設けます。²

Remote Control（任意のブラウザやモバイルアプリからローカルの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

基準は、テストの合否、linterの出力、HTTPステータスコード、ファイルの存在確認など、機械的に検証できるものでなければなりません。初期のタスクでエージェントに「合格するテストを書く」よう依頼したところ、assert Trueとassert 1 == 1が生成されました。技術的には正解ですが、実用上は無価値です。¹⁶

注意すべき失敗パターン

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

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

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

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

3. エージェントがBashを呼び出してテストを実行します。 PreToolUse:Bashが発火し、認証情報のチェック、Sandboxの検証、プロジェクト検出を行います。所要時間は90msです。テストが実行されます。続いてPostToolUse:Bashが発火し、アクティビティのハートビートを記録してドリフトを確認します。

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

5. エージェントがストーリーを完了します。 Stopが発火します。品質ゲートでは、エージェントがevidenceを示したか、曖昧な表現がないか、diffにTODOコメントがないかを確認します。いずれかのチェックに失敗すると終了コード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のオーバーヘッドは、ストーリーあたり2.4秒のbash実行にすぎません。Stop hookがエージェントの完了報告を許可する前に独立してテストを実行したことで、誤った完了報告率は35%から4%へ低下しました。

セキュリティ上の考慮事項

信頼できるエージェントの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と共同管理）に加わりました。これにより、エージェント相互運用性の標準はベンダー中立となっています。²⁷

MCPのステートレスなターンと自己申告ID（2026年7月）。 MCP仕様は現在、ステートレスなコア（SEP-2575）への移行途中にあります。これにより、従来サーバーIDを伝えていたステートフルな初期化ハンドシェイクが廃止されます。7月16日にマージされたドラフト仕様の変更（PR #3002）では、IDが任意のサーフェスとして復活しました。サーバーはレスポンスの_metaにio.modelcontextprotocol/serverInfoオブジェクトを含められ、リクエストのclientInfoは任意となります。⁷¹ セキュリティ上重要なのは、仕様が信頼について述べている内容です。このIDは自己申告であり、検証されていません。表示とログ記録のみに使用し、セキュリティ上の判断には使用すべきではありません。harnessの許可リスト、権限ルール、ログベースの監査をMCPサーバーの申告名に基づかせている場合、その名前は認証情報ではなく、単なる主張です。信頼は、サーバー自身が名乗る名前ではなく、トランスポートと設定（どのサーバーをどのエンドポイントに設定したか）に固定してください。最終版のステートレス仕様改訂は2026年7月28日に予定されています。このセクションのプロトコルレベルの詳細は、次回の更新で固まる見込みです。

Skillサンドボックスツール： skillsを攻撃対象として扱うチーム向けに、PermisoのSandyClaw（2026年4月2日公開）はskillsを専用サンドボックス内で実行し、Sigma/YARA/Nova/Snortによる検出に基づいた証拠付きの判定を提供します。skillサンドボックスというカテゴリ初の製品です。²⁸

サンドボックス

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

2026年5月時点のセキュリティ下限。 Claude Code v2.1.149では、PowerShellの作業ディレクトリ権限を回避できる問題、PowerShellの許可ルールと古い変数に関する複数の権限分析上の不備、共有されるgit内部データだけでなくメインリポジトリのルート全体を対象としていたgit worktreeサンドボックスの書き込み許可リストのバグが修正されました。⁵³ harnessでPowerShellまたはworktree分離型エージェントを許可する場合は、v2.1.149以降を最低ラインとし、シェルルールを狭く保ってください。広範なPowerShell(*)やリポジトリ全体への書き込み例外は、オーケストレーション上の近道にすぎず、安全境界ではありません。

OpenAI Agents SDKのサンドボックス強化（v0.17.0、2026年5月8日）。 OpenAI側では、openai-agents-python v0.17.0によって並列する境界も強化されました。LocalFile.srcとLocalDir.srcは、マニフェスト適用時のマテリアライズ用base_dir（SDKプロセスの現在の作業ディレクトリ）内に制限されます。ただし、Manifest.extra_path_grantsでSandboxPathGrantを使用し、ソースを明示的に許可した場合は除きます。⁴¹ 相対パスのローカルソースはbase_dirを基準に解決されます。絶対パスは、すでにその内部にあるか、許可が付与されていなければなりません。これはローカルアーティファクト境界の問題を解消するものです。以前のバージョンでは、マニフェストを通じてホスト上の任意のパスをサンドボックスのワークスペースへ取り込めました。移行時には、読み取り専用マウントとして信頼するホストルートを、マニフェストレベルでSandboxPathGrant(path=..., read_only=True)を使って宣言してください。extra_path_grantsは信頼済みのアプリ設定として扱い、モデルの出力や信頼できないマニフェスト入力から許可を設定してはいけません。

OpenAI Agents SDKの追加下限（v0.17.3）。 0.17.1～0.17.3では、サンドボックスとセッションがさらに強化されました。アーカイブ展開の制限、GitRepoサブパスの検証、より明確なサンドボックスプロバイダーエラー、サンドボックスコマンドからのマウントポイント認証情報の分離、相対パスによるサンドボックスワークスペースルートの拒否、Vercelサンドボックスの終了状態処理などです。⁵⁴ Claude Code hooksだけでなく、OpenAIホスト型またはプロバイダー提供のサンドボックスを使用している場合は、このセクションのパターンにおける現時点の最低ラインを0.17.3としてください。

製品横断の3つの封じ込めパターン（Anthropic、2026年5月）

Anthropicのエンジニアリング記事「How we contain Claude across products」（2026年5月25日）は、このセクションで個別に説明してきた原則、つまり前述の設定レベルのサンドボックス、worktree分離の最低ライン、あらゆるものを信頼できないものとして扱う姿勢について、ベンダー自身が体系的に示したものです。⁸¹ その中核は、封じ込めの強度を製品のサーフェスに対応づけることにあります。この対応関係自体が重要な教訓です。唯一の正しい分離設計があるわけではなく、監視する人と起こり得る問題に応じた分離が必要なのです。

• 一時的なgVisorコンテナ（claude.ai）。 サーバー側の実行は、分離されたインフラストラクチャ上のgVisorコンテナで行われ、セッションごとに一時的なファイルシステムが用意されます。脅威モデルはインフラストラクチャとテナントの分離です。ユーザーのマシンには到達できないため、ローカル環境を防御する必要はありません。
• 人間参加型のOSサンドボックス（Claude Code）。 前述のサンドボックスで説明したパターンを、ポリシーとして明文化したものです。macOSではSeatbelt、Linuxではbubblewrapを使用し、読み取りは許可、書き込みはワークスペース内に限定、ネットワークはデフォルトで拒否します。境界でカバーできない操作は人間が承認します。Anthropicはランタイム（sandbox-runtime）をオープンソース化し、境界を監査可能にしました。この記事は弱点についても率直です。権限プロンプトのおよそ93%が承認されています。実行前に過剰な動作の約83%を検出しながら、承認プロンプトを84%削減するauto-mode分類器が存在するのは、承認疲れがUX上の不満ではなく、セキュリティ特性そのものだからです。これは、このガイドがv2.1.193以降追跡してきたチェックレイヤーの姿勢です。
• 封印されたVM（Claude Cowork）。 プラットフォームのハイパーバイザー（macOSではApple Virtualizationフレームワーク、WindowsではHCS）上で完全な仮想マシンを実行し、選択したワークスペースと.claudeフォルダーだけをマウントします。ホスト上のそれ以外のデータは一切見えません。認証情報がVMに入ることもありません。認証情報はホストのキーチェーンに保持され、各セッションにはスコープが限定され、個別に取り消し可能なトークンが渡されます。VM内の防御的なMITMプロキシがこれを強制し、VM自身にプロビジョニングされたセッショントークンを含むリクエストだけを通過させます。攻撃者が埋め込んだキーは境界で拒否されます。出所を把握しているのはVMだけだからです。

この分類体系の根底にあるデザイン原則こそ、別の環境にも応用できる部分です。まず環境レイヤーで封じ込め、次にモデルレイヤーで誘導してください。 確率的な防御には必ずゼロではない見逃し率があるため、プロンプトレベルの誘導が見逃したものを、決定論的な境界で捕捉しなければなりません。このガイドの「hooksは実行を保証する」という主張を、ベンダー自身が言い換えたものです。分離の強度は、ユーザーの監督能力に合わせてください。 開発者ならbashコマンドを承認前に評価できますが、ナレッジワーカーにはできません。そのため、Codeには権限ダイアログがあり、Coworkには封印されたVMがあります。独自の分離コードではなく、実績あるプリミティブを優先してください。 ハイパーバイザー、seccomp、コンテナランタイムは、Anthropic独自の許可リストプロキシや設定パーサーよりも、敵対的な検証に耐えてきました。プロジェクトローカルの設定とツール出力を、信頼できないものとして扱ってください。 記事では、プロジェクトを開く処理や設定を読み込む処理を、インターネットから届くあらゆる受信リクエストと同様に扱い、ツール自体が信頼できる場合でもツール出力を攻撃対象として扱うよう求めています。これは、このガイドがエージェント間メッセージ、subagentが読み取ったコンテンツ、自己申告されたMCPのIDに適用している姿勢と同じです。認証情報はサンドボックスの外に置いてください。 エージェントが漏えいさせ得る常設キーではなく、スコープが限定され、取り消し可能なセッション単位のトークンを使用します。

設定サーフェスも第1原則に追いつきつつあります（v2.1.219）。 「まず環境レイヤーで封じ込める」という方針には賛同しやすい一方、実際の設定は扱いにくいものでした。Claude Codeのサンドボックスは、ルールでカバーされない操作について確認を求めていたからです。前述の93%という承認率が示すとおり、権限プロンプトは決定論的な衣装をまとった確率的防御にすぎません。sandbox.network.strictAllowlistは、外向き通信におけるこの確認をなくします。これを設定すると、サンドボックス化されたコマンドから許可リストにないホストへのリクエストは、プロンプトを表示せず即座に拒否されます。⁸⁴ v2.1.216のsandbox.filesystem.disabledと組み合わせれば、2つの設定は単なるトグルの寄せ集めではなく、一貫したセキュリティ態勢を構成します。ファイルシステムとネットワークの封じ込めを個別に選択でき、ネットワークの封じ込めは決定論的に設定できるようになりました。無人のharnessでは、この2つのうちネットワークの方が重要です。外向き通信によって、注入された命令が情報流出へと変わるからです。また、承認疲れの究極の状態とは、疲れる人すらキーボードの前にいないことです。代償として、決定論的な境界には通常どおり正確な許可リストが必要になります。登録し忘れたホストへのアクセスは質問されず、不透明な拒否として失敗します。エージェントが正当に必要とするホストを列挙したうえで、プロンプトをなくしてください。

これらはいずれもhookレイヤーの代替ではなく、その下層に位置します。封じ込めパターンは決定論的な最低ラインです。このガイドで扱ってきたworktree強制の歴史も、同じ教訓を小さく示しています。境界と呼べるのは意図的な迂回に耐えられるものだけであり、最も耐えられる可能性が高いのは、その場しのぎで作られたものではないプリミティブです。

権限境界

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

パラメータレベルの権限ルール（2026年6月）

Claude Code v2.1.178では、権限ルールがツールレベルからパラメータレベルまで拡張されました。Tool(param:value)はツールの入力パラメータと照合し、*をワイルドカードとして使用します。代表的な例はAgent(model:opus)で、特定のモデル階層を使用したsubagentsの起動をブロックするルールです。⁶³ アーキテクチャ上、これは前述の4段階の表では表現できなかった隙間を埋めます。以前はツール全体を許可または拒否できても、どのように呼び出すかまでは制限できませんでした。現在は、「subagentsの起動は許可するが、Fable 5階層では許可しない」や「Bashは許可するが、このフラグ付きでは許可しない」といったガバナンスポリシーを、プロンプトレベルの要求ではなく、決定論的なルールとして指定できます。

付随する管理設定enforceAvailableModels（v2.1.175）は、モデル選択を上位から制限します。Defaultモデルを固定し、ユーザーまたはプロジェクトスコープの設定によって、管理対象のavailableModels許可リストが拡張されるのを防ぎます。⁶³ この2つは組み合わせて機能します。許可リストはセッション内に存在できる階層を定義し、パラメータレベルのルールはsubagentsがそこからモデルを選ぶ方法を制限します。v2.1.196以降、管理者は組織コンソールから組織全体のデフォルトモデルも設定できます。これは/modelに「Org default」と表示され、各オペレーターが個別に固定しなくても、組織全体に管理されたデフォルトが適用されます。許可リストの上限を補完する最低ラインとなります。

パススコープの許可ルールは作業ディレクトリを基準とする（2026年7月）

Claude Code v2.1.214では、パススコープの権限ルールにおける目立ちにくい過剰一致が修正されました。Edit(src/**)のような、単一セグメントのdir/**パターンを持つ許可ルールは、以前は任意の深さにあるsrcという名前のあらゆるディレクトリへの編集を自動承認していました。これには、ルール作成者が許可するつもりのなかったvendor/some-package/src/や、その他すべてのネストされたsrc/も含まれていました。現在、こうしたルールは<cwd>/dirだけを基準とします。本当に深さを問わず一致させたい場合は、**/dir/**で宣言してください。⁷⁴ 拒否ルールと確認ルールは、意図的に従来の深さを問わない一致を維持しています。この非対称性は、フェイルセーフ設計として正しいものです。許可ルールの一致範囲が狭すぎても安全側に失敗し、プロンプトが表示されます。一方、拒否ルールの一致範囲が狭すぎると危険側に失敗し、ブロック対象のパスがすり抜けます。そのため、許可は厳格化され、拒否は広いまま維持されました。単一セグメントの許可パターンでネストされたパスまでカバーしていた設定は、v2.1.214で暗黙に機能しなくなっています。これは修正が意図どおり機能している結果ですが、許可リストを見直し、実際に必要な範囲を改めて宣言する価値があります。

Auto Modeの破壊的コマンドに対するガードレール（2026年6月）

Claude Code v2.1.183では、作業内容を暗黙に失わせたり環境を破棄したりする操作について、auto modeの影響範囲が狭められました。セッション内で明示的に要求しない限り、auto modeは次の操作を強制的にブロックします。破壊的なgit操作（git reset --hard、git checkout -- .、git clean -fd、git stash drop）、そのセッションでエージェントが作成したものではないコミットへのgit commit --amend、特定のスタックを指定していないインフラストラクチャの破棄（terraform destroy、pulumi destroy、cdk destroy）です。⁶⁵ アーキテクチャ上、これは前述の起動時の検査とパラメータレベルのルールを補完します。どのツールを使うか、またはどのように起動するかを制御するのではなく、少数の具体的で取り消せないコマンドを意図に基づいて制御します。エージェントは引き続き実行できますが、自発的には実行できず、明示的な指示が必要です。自律型harnessでも、同じ原則を独自のPreToolUse hooksに組み込んでください。状態を破壊するコマンドには、明示的なオペレーターの合図がある場合にのみ解除される、デフォルト拒否ルールが必要です。

2026年7月：auto modeがエンタープライズ対応となり、1つのプロンプトが回避不能に。 v2.1.207では、auto modeがAmazon Bedrock、Google Vertex AI、Microsoft FoundryでGAとなり、エンタープライズ向けのオプトアウトとしてdisableAutoMode管理設定が追加されました。分類器をチェックレイヤーとして使用する姿勢が、すべてのファーストパーティエンタープライズプラットフォームで利用可能になりました。無効化はプラットフォーム上の制約ではなく、明示的なガバナンス判断となります。⁶⁸ 続くv2.1.208では、壊滅的な削除に対するガードが絶対的なものになりました。壊滅的な削除に対する確認プロンプトは、--dangerously-skip-permissionsとauto modeの両方を貫通して表示されます。⁶⁸ これは注目すべき先例です。明示的なバイパスフラグを含め、どのような権限態勢でも回避できない、Claude Code初の確認となります。--dangerously-skip-permissionsが文字どおりプロンプトを完全になくすと想定していた自律型harnessの設計では、この例外を考慮してください。無人ループが最も回復不能な損害を与え得る場面でのみ発動します。

捏造防止ガードレール（2026年7月）

v2.1.203～v2.1.206のリリースでは、エージェントが自身の監査証跡を捏造できる2つの経路が閉じられました。⁶⁸ まず、auto-modeのルールによってトランスクリプトファイルの改ざんがブロックされるようになり、セッション記録を同じセッションのツール呼び出しで書き換えられなくなりました。次に、バックグラウンドタスクの通知には、タスクの実行中に人間からの入力がなかったことが明記されるようになりました。後者は巧妙な失敗を対象としています。以前は、バックグラウンドタスクを要約するモデルが、実際には存在しなかったトランスクリプト内の「承認」を提示（または捏造）しても、通知側にそれを否定する情報がありませんでした。現在は、通知そのものが反証となります。

このアーキテクチャ上の教訓は、Evidence Gate全般に当てはまります。トランスクリプト、通知、ログは監査サーフェスであり、監査対象自身が監査サーフェスへ書き込めてはいけません。プラットフォームは現在、独自のトランスクリプトに対してこれを強制しています。同じルールをharnessにも適用し、証拠レポート、テスト出力、deliberationの記録をモデルが書き込めるパスの外に置いてください。

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

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は、プロンプトが侵害されても変更を加えられません。

2026年7月にプラットフォームの最低ラインが引き上げられました。 Claude Code v2.1.210では、subagentが読み取ったコンテンツを経由する間接的なプロンプトインジェクションに対してAgent toolが強化されました。subagentが取り込んだ汚染ファイル、Webページ、ツール結果によって、委任サーフェス自体が誘導されにくくなっています。⁶⁹ また、v2.1.211では人間が関わる部分も強化されました。権限プレビューで、双方向テキストの上書き、ゼロ幅文字、類似したUnicode文字を無害化するようになり、承認ダイアログでは無害に見えながら、実際には別の処理を実行するコマンドを作れなくなりました。⁶⁹ 2つ目の修正は、時間的なプレッシャーのもとで人間がレンダリングされたプレビューを承認するharnessにとって特に重要です。表示自体もインジェクションの攻撃対象だったのです。どちらの変更も前述のhookレベルの防御を置き換えるものではなく、その下にある最低ラインを引き上げます。

エージェントログとガードレールはセキュリティサーフェス

2026年5月の2件のアドバイザリは、あるパターンを改めて示しています。エージェントインフラストラクチャは、機密コンテンツや実行可能なポリシーが漏えいしたり、境界を脱したりする新たな場所を生み出します。GitHub Advisory GHSA-f3jg-756w-gm35は、Gryph Agentsのペイロードフィルターに関する問題を扱っており、デフォルトのログ動作では、機密性の高いツールペイロードの内容がローカルのSQLiteログに残る可能性がありました。⁴⁵ OSV GHSA-wxxx-gvqv-xp7pは、管理者によって保護されたプロキシエンドポイントにおける、LiteLLMのカスタムコードガードレールのサンドボックスエスケープを扱っています。⁴⁶

本番環境での原則は、エージェントのトランスクリプト、ツールペイロード、SQLiteログ、ガードレールの実行を機密インフラストラクチャとして扱うことです。永続化する前に機密情報を編集し、保持期間を制限して、カスタムガードレールコードをサンドボックス内でレビュー可能な状態に保ってください。プロンプトレベルの「シークレットをログに記録しない」というルールだけでは不十分です。ログとガードレールの経路には、決定論的なテストが必要です。

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を起動すると、subagentが使用するすべてのツールに対してPreToolUseとPostToolUse hooksが実行されます。再帰的なhookの強制がなければ、subagentは安全ゲートを迂回できてしまいます。SubagentStopイベントを使用すると、subagentの完了時にクリーンアップや検証を実行できます。

これは任意ではありません。セキュリティhooksを適用せずにsubagentを起動するエージェントは、メインの会話を監視するゲートが何もできない間に、mainへのforce-push、認証情報ファイルの読み取り、破壊的コマンドの実行を行えるエージェントです。

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

コストはアーキテクチャ上の意思決定であり、運用時に後から考えるものではありません。² 3つのレベルがあります。

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

エージェントレベル。 長い会話よりも新規起動を優先します。自律実行では、各ストーリーにクリーンなコンテキストを持つ新しいエージェントを割り当てます。各エージェントが新しい状態から開始するため、コンテキストが膨れ上がることはありません。メモリではなくブリーフィングを使用してください。モデルは、蓄積された30ステップのコンテキストをたどるよりも、明確なブリーフィングを正確に実行できます。

アーキテクチャレベル。 操作がステートレスな場合は、MCPよりもCLIを優先します。1回限りの評価にclaude --printを呼び出す方が低コストで、接続オーバーヘッドも発生しません。MCPが適しているのは、ツールに永続的な状態またはストリーミングが必要な場合です。

判断フレームワーク

各仕組みを使う場面は次のとおりです。

Skills vs Hooks vs Subagents

FAQ

hooks はいくつあると多すぎますか？

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

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

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

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

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

すべての判断に deliberation が必要ですか？

いいえ。confidence module は、判断を4つの次元（曖昧さ、複雑さ、重要度、コンテキスト依存性）でスコアリングします。全体の信頼度が0.70を下回る判断だけが deliberation をトリガーし、これは全判断のおよそ10%です。ドキュメント修正、変数名変更、定型的な編集では deliberation を完全にスキップします。セキュリティアーキテクチャ、データベーススキーマ変更、取り返しのつかないデプロイでは、一貫してトリガーされます。⁷

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

成功パスと失敗パスの両方をテストします。成功とは、agents が生産的に意見を分け、合意に到達することです。失敗とは、agents が早すぎる収束をする、まったく収束しない、または spawn 予算を超えることです。エンドツーエンドテストでは、決定的な agent 応答を使って各シナリオをシミュレートし、両方の検証ゲートが文書化されたすべての失敗モードを検出することを確認します。本番の deliberation system は3層で141個のテストを実行します。内訳は、48個の bash integration tests、81個の Python unit tests、12個の end-to-end pipeline simulations です。⁷

deliberation のレイテンシへの影響はどれくらいですか？

3-agent deliberation は、実時間で30〜60秒追加します（agents は Agent tool を通じて順番に実行されます）。10-agent deliberation では2〜4分追加されます。consensus hooks と pride check hooks は、それぞれ200ms未満で実行されます。主なボトルネックは orchestration overhead ではなく、agent ごとの LLM 推論時間です。⁷

CLAUDE.md ファイルの長さはどれくらいが適切ですか？

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

これは Claude Code 以外のツールでも使えますか？

アーキテクチャ上の原則（決定的なゲートとしての hooks、ドメイン知識としての skills、分離コンテキストとしての subagents、memory としてのファイルシステム）は、概念的にはあらゆる agentic system に適用できます。具体的な実装では、Claude Code のライフサイクルイベント、matcher patterns、Agent tool を使っています。AGENTS.md は同じパターンを Codex、Cursor、Copilot、Amp、Windsurf に持ち込みます。²¹ 実装の詳細がツール固有であっても、harness pattern 自体はツール非依存です。

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

Hook Configuration

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

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

Subagent Definition

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

Exit Codes

主要コマンド

ファイルの場所

変更履歴

参照