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

TL;DR: Claude Code は、ファイルにアクセスできるチャットボックスではありません。これは、31の文書化されたライフサイクルイベントを備えたプログラム可能なランタイムであり、各イベントにはモデルがスキップできないシェルスクリプトをフックできます。hooks を dispatcher に、dispatcher を skills に、skills を agents に、agents を workflows に積み重ねると、制約の適用、作業の委譲、セッションをまたぐメモリの永続化、マルチエージェントの熟議のオーケストレーションを行う自律的な開発 harness が得られます。Claude Code の動的 workflows（v2.1.154+）により、決定論的なマルチエージェント・オーケストレーションがファーストパーティのプリミティブになりました。/workflows を通じて数十から数百のバックグラウンド agents を実行できます。さらに、プラットフォームでは現在、subagents がデフォルトでバックグラウンド実行され（同時実行20、ネスト深度3）、セッション同士をピアとしてメッセージングでき（v2.1.224）、セルフホスト runner 上でクラウドセッションを実行できます。正しさを担保するのは、引き続き Hooks と evidence gates です。⁵²⁵³⁸⁷ このガイドでは、そのスタックのすべての層を扱います。単一の hook から10-agent consensus system まで。フレームワークは不要です。すべて bash と JSON だけで構成されています。

Andrej Karpathy は、LLM agent の周囲で育つものを表す言葉を作りました。claws です。agent がコンテキストウィンドウの外にある世界をつかめるようにする hooks、scripts、オーケストレーションを指します。¹ ほとんどの開発者は、AI コーディングエージェントを対話型アシスタントとして扱います。プロンプトを入力し、ファイルを編集する様子を見て、次へ進みます。その捉え方では、生産性は個人で監督できる範囲に制限されます。

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

この違いは重要です。bash commands 内の認証情報をブロックする hook は、あらゆるセッション、あらゆる agent、あらゆる自律実行を保護します。評価基準をエンコードした skill は、自分が呼び出す場合でも agent が呼び出す場合でも、一貫して適用されます。セキュリティのためにコードをレビューする agent は、見ているかどうかにかかわらず同じチェックを実行します。²

重要なポイント

• Hooks は実行を保証しますが、プロンプトは保証しません。 linting、formatting、security checks、およびモデルの動作にかかわらず毎回実行しなければならないものには hooks を使用してください。終了コード 2 はアクションをブロックします。終了コード 1 は警告するだけです。³
• Skills は自動で有効化されるドメイン専門知識をエンコードします。 description フィールドがすべてを決定します。Claude は、キーワードマッチングではなく LLM reasoning を用いて、skill を適用するタイミングを判断します。⁴
• Subagents はコンテキストの肥大化を防ぎます。 探索と分析のために分離されたコンテキストウィンドウを使うことで、メインセッションを軽量に保てます。独立した subagents は並列に実行し、worker に継続的な連携が必要な場合は agent teams を使用してください。⁵
• Memory はファイルシステムに存在します。 ファイルはコンテキストウィンドウをまたいで永続します。CLAUDE.md、MEMORY.md、rules directories、handoff documents が、構造化された外部メモリシステムを形成します。⁶
• マルチエージェントの熟議は見落としを捉えます。 単一の agent は、自身の前提に異議を唱えられません。評価の優先順位が異なる2つの独立した agents なら、quality gates では対処できない構造的な不具合を見つけられます。⁷
• harness pattern こそがシステムです。 CLAUDE.md、hooks、skills、agents、memory は独立した機能ではありません。これらは、ユーザーとモデルの間に位置し、自動化とともにスケールする決定論的なレイヤーを構成します。

このガイドの使い方

各セクションは前のセクションを土台にしています。最後にある Decision Framework には、問題の種類ごとに適切な仕組みを選ぶための参照表があります。

5分間のゴールデンパス

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

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

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

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

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

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

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

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

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

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

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

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

これで手に入るもの

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

なぜAgent Architectureが重要なのか

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

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

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

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

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

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

Harness Pattern

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 Layer: CLAUDE.mdファイルとrulesディレクトリは、エージェントがプロジェクトについて知るべき内容を定義します。セッション開始時と、すべてのcompaction後に自動で読み込まれます。これはエージェントの長期的なアーキテクチャメモリです。

Extension Layer: skillsは、コンテキストに応じて自動的に有効化されるドメイン専門知識を提供します。hooksは、対象となるすべてのツール呼び出しで起動する決定論的なゲートを提供します。memoryファイルはセッション間で状態を保持します。custom agentsは、特化したsubagent設定を提供します。

Orchestration Layer: マルチエージェントのパターンは、リサーチ、レビュー、熟議のために独立したエージェントを連携させます。spawn budgetは再帰の暴走を防ぎます。consensus validationは品質を確保します。

重要な洞察は、多くのユーザーがCore Layerだけで作業し、コンテキストの肥大化とコストの上昇を招いていることです。パワーユーザーはInstruction LayerとExtension Layerを設定し、そのうえでCore Layerをオーケストレーションと最終判断にのみ使います。²

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

2026年初頭を通じて、「独自のharnessを構築する」道だけが現実的な選択肢でした。2026年4月に状況が変わりました。Anthropicは4月8日、Claude Managed Agentsをパブリックベータとして提供開始しました。harness loop、ツール実行、sandbox container、状態永続化をREST APIとして提供し、通常のトークン料金に加えてセッション時間あたり$0.08が課金されます。OpenAIのAgents SDKアップデート（4月16日）は、同じ分離を正式化しました。harnessとcomputeを別レイヤーとして扱い、ネイティブsandbox provider（Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel）と、コンテナ喪失後も継続するためのsnapshot/rehydrateを提供します。²³²⁴

OpenAI側のより深いSDK機能は、openai-agents Python v0.14.0で提供されました（2026年4月15日リリース、4月16日発表）。AgentのSandboxAgentサブクラスであり、default_manifest、sandbox instructions、capabilitiesを備えています。また、新しいworkspaceの契約（ファイル、ディレクトリ、ローカルファイル、Gitリポジトリ、env、ユーザー、mount）を記述するManifest、sandbox client、ライブセッションの注入、manifest override、snapshot、materializationの並行数上限を実行ごとに接続するSandboxRunConfigも含まれます。組み込みcapabilitiesは、shell access、filesystem editing、image inspection、skills、sandbox memory、compactionをカバーします。sandbox memoryは、抽出した学びを実行間で保持し、段階的に開示します。workspaceはローカルファイル、Git repo entry、リモートmount（S3、R2、GCS、Azure Blob、S3 Files）をサポートし、snapshotはprovider間で持ち運べます。バックエンドは、UnixLocalSandboxClient、DockerSandboxClient、およびオプションextra経由のBlaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel向けhosted clientです。²⁴

Pythonプロジェクトで、Claude Code runtimeをライブラリとして組み込みたい場合、つまり「claudeをshell outする」と「Managed AgentsへのREST API」の間に位置する第3の選択肢が、claude-agent-sdk-pythonです。4月28日から29日のシリーズ（v0.1.69 → v0.1.71）では、バンドルされるCLIがv2.1.123へ更新され、mcp依存関係の下限が>=1.19.0へ引き上げられました。以前のバージョンでは、プロセス内MCPツールからのCallToolResult返却が暗黙に破棄され、モデルにはvalidation-error blobだけが残っていました。また、SandboxNetworkConfigはTypeScript SDKとスキーマ互換になりました（allowedDomains、deniedDomains、allowManagedDomainsOnly、allowMachLookup）。³⁰ 2026-08-12時点で、パッケージはPyPIでv0.2.137、TypeScript SDKはv0.3.229です（どちらもライブレジストリで検証済み）。0.2.x系は、ここで説明した0.1.xの機能を段階的に拡張したものです。以下のinclude_hook_events、skills、sandbox-configオプションはいずれも現在も有効であり、最近のリリースはsubprocess-cleanupとNDJSON-streamの信頼性向上に重点を置いています。⁹⁰⁸⁶

harnessにvoiceまたはrealtimeレイヤーが含まれる場合、openai-agents-python v0.17.0（2026年5月8日）は、RealtimeAgentのデフォルトをgpt-realtime-2へ更新しました。⁴¹ 既存のrealtime sessionは新しいデフォルトを自動的に取得します。評価のために以前の挙動を維持する必要がある場合は、以前のモデルを明示的に固定してください。

2026年7月には、マネージド側にもOpenAIのマルチエージェント機能が加わりました。openai-agents-python v0.18.2（7月11日）とopenai-agents-js v0.13.2（7月10日）は、ベータ版としてhosted multi-agent supportを追加しました。これは、複数のエージェントをOpenAI管理のオーケストレーションで連携させるhosted serviceであり、Multi-Agent Orchestrationセクションで扱うAnthropicのManaged Multiagent Orchestrationパブリックベータに直接対応します。⁷³ これで両ベンダーは、以下の表が単一エージェント向けに示すのと同じトレードオフをマルチエージェント層でも提供しています。ベンダーがdelegation loopを運用する代わりに、hook surfaceを手放します。

アーキテクチャ上の分岐は、いまや明確です。

どちらを選ぶべきか： セルフホストは、すでにインフラ運用力があり、自ら制御できるskills/hooksを求めるチームや、特定のworkflowを深く最適化したいチームに適しています。マネージドは、専任のplatform engineerがいないチーム、カスタマイズよりtime-to-valueを重視する場合、または永続化レイヤーを自分で構築せずにラップトップを閉じた後もagent runを確実に継続させたい場合に適しています。両者は互換性があります。セルフホストharnessからREST API経由でManaged Agentsに特定の長時間タスクをdelegatesすることもできます。

ディスク上の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を通じて共有されます。両者を合わせることで、完全なharnessが構成されます。

Skills System

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

Skill を作るタイミング

Skills は、Claude が常に利用できる知識のためのものです。Slash command は、明示的にトリガーするアクションのためのものです。どちらにすべきか迷う場合は、「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 の説明はシステムプロンプトの available_skills セクションに注入され、モデルは標準的な言語理解によって関連する skill を選択します。¹⁰

悪い 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 は、skill の実行中にのみ有効になる独自の hooks を frontmatter で定義できます。これにより、他のセッションを汚さないドメイン固有の動作を実現します。²

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

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

よくある Skill の誤り

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

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

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

SDK Skill Surface（2026年5月8日）

claude-agent-sdk-python v0.1.77+ を使用するセルフホスト型 harness では、利用可能な skills の宣言に ClaudeAgentOptions の skills オプションを使用すべきです。レガシーな allowed_tools の "Skill" 値は使用しません。³⁷ "Skill" の短縮記法は非推奨であり、専用オプションによって Claude Code は利用可能な skills についてより構造化された情報を得られます。v0.1.77 にバンドルされている CLI は v2.1.133 です。

.claude/skills/ における Plugin と Skill の収束（2026年5月29日）

Skills は以前からプロジェクトの .claude/skills/ ディレクトリから読み込まれてきました。Claude Code v2.1.157 では、このディレクトリが plugins にも拡張されました。.claude/skills/ に配置した plugin は、marketplace 登録なしで自動的に読み込まれます。また、claude plugin init <name> によって、manifest と SKILL.md がすでに接続された新しい plugin がそこにスキャフォールドされます。⁵⁸ これにより、以前は別の場所に存在していた2種類のプロジェクトツール形態、つまりリポジトリに直接コミットする素の skill と、skill、hooks、MCP server をバンドルできる一方で、以前は marketplace 経由のインストールが必要だった plugin との隔たりが解消されます。harness デザインにおける実務上の効果は、プロジェクトスコープのツールを配布するのに、もはや registry を経由する必要がないことです。書いて、コミットすれば、チームメイトは git pull で同じ surface を取得できます。Plugins は依然としてバンドルしてインストール可能にするユースケース（hooks + skills + MCP servers + agents を1つの ZIP にまとめるもの）を担います。変わったのは、プロジェクトが自分のツリーから1つを読み込むだけのために marketplace を立ち上げる必要がなくなった点です。この収束は現在、ベンダー横断の基盤も備えています。Agent Plugins 1.0.0（2026年8月6日公開）は、「AI agents のためのポータブルパッケージ形式」として、plugin.json manifest、SKILL.md フォルダからなる skills/ ディレクトリ、任意の mcp.json という同じパッケージ形状を標準化しています。公開時には VS Code、Cursor、GitHub Copilot、ChatGPT & Codex、Kiro が採用しました。これは Agent Skills と MCP を置き換えるものではなく、それらを包むパッケージングレイヤーです。なお、Agent Skills spec の著者である Anthropic は、まだこの連合に加わっていません。そのため、Claude-Code 間の外向きポータビリティは、公式の双方向契約ではなく、フォーマットレベルの互換性として扱ってください。⁸⁹

ガバナンスとしてバンドルされた Surface を隠す（2026年6月8日）

Skills は能力であり、能力は攻撃対象領域です。Claude Code v2.1.169 では、バンドルされた skills、workflows、組み込み slash commands をモデルから完全に隠す disableBundledSkills 設定（および対応する CLAUDE_CODE_DISABLE_BUNDLED_SKILLS 環境変数）が追加されました。⁶⁰ 強化された、または規制対象の harness では、これは意図的な攻撃対象領域の縮小です。特定の project skills と personal skills を監査・承認した運用者は、Anthropic が同梱するすべてを抑制できます。これにより、モデルは運用者が精査した surface についてのみ推論することになります。ツール allowlist と同じように扱ってください。デフォルトは広い能力であり、そのデフォルトを無効にすることは利便性の切り替えではなく、ガバナンス上の判断です。

ネストした .claude/skills と Closest-Wins 解決（2026年6月16日）

Claude Code v2.1.178 により、プロジェクトツールは場所を認識するようになりました。ネストした .claude/skills ディレクトリ内の skills は、リポジトリルートだけでなく、そのディレクトリ配下のファイルを作業しているときにも読み込まれます。名前が衝突する場合、ネストした skill は <dir>:<name> として表示されるため、両方にアクセスできます。⁶³ 同じリリースで、プロジェクト surface の残りの部分も作業ディレクトリに最も近いものを解決するようになりました。agent、workflow、または output-style の名前がネストした .claude/ ディレクトリ間で衝突する場合は、作業ディレクトリに最も近いものが優先されます。また、project-scope workflow の保存先は常にルートではなく、最も近い既存の .claude/workflows/ になります。⁶³ monorepo や repo-of-repos にとって、これは1つのフラットなグローバル surface と、コンテキストに応じて有効になるパッケージごとのツールの違いです。services/api/.claude/skills/ には、API 固有の skills を置けます。これらはそのツリー内で作業している間だけ表示され、同名の services/web/ skill と衝突しません。

Hook Architecture

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

利用可能なイベント

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

DirectoryAdded（v2.1.219）は、セッション途中のワークスペースにおけるギャップを解消します。 イベント一覧は MessageDisplay がv2.1.152で導入されて以降安定していましたが、DirectoryAdded はそれ以降初めて追加されたライフサイクルイベントです。/add-dir、または SDK の register_repo_root 制御リクエストで、セッション途中に新しい作業ディレクトリが登録された後に発火します。⁸⁴ このイベントが埋めるギャップは現実的なものです。これまではharnessが SessionStart でワークスペースを徹底的に検証しても、hookが一切発火しないまま2つ目のリポジトリが追加される可能性がありました。起動時にワークスペースについて検証する内容、たとえば信頼性チェック、シークレットスキャン、ツリーから導出するパススコープ規則、リポジトリごとのポリシー読み込みは、ここで再実行する必要があります。セッションのディレクトリ集合は、起動時点で固定ではなくなったためです。このイベントはブロッキングではなく情報提供用です。ゲートとしてではなく、状態の再導出とprovenanceの記録を開始するトリガーとして扱ってください。追加を絶対に許可してはならないディレクトリがある場合は、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 ツール名（mcp__server__tool など）、またはすべてのツールに対応する * といった tool_name 値に一致します。単純な名前と | 区切りのリストは完全一致です。その他の文字を含む値は、JavaScript 正規表現として扱われます。一部のイベントはmatcherをサポートせず、設定されると常に発火します。¹³ Claude Code v2.1.195以降、ハイフンを含む識別子（code-reviewer、mcp__brave-search）を含むmatcherは、誤って部分文字列に一致するのではなく完全一致します。つまり、特定のagentまたはサーバーを対象とする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は、ファイル変更のたびにformatterを実行します。formatterがすべてを正規化するため、モデルの出力は問題になりません。

{
  "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はlinterまたはテストスイートを実行し、品質チェックが失敗した場合はコミットをブロックします。

#!/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 tool hooks（type: "mcp_tool"）は、すでに接続されているMCPサーバー上のツールを呼び出します。検証ロジックがすでにMCP境界の背後にあり、別のシェルスクリプトを必要としない場合に使用します。

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

Agent hooks（type: "agent"）は、複数ターンの検証のためにツールアクセス（Read、Grep、Glob）を持つsubagentを起動します。これらは実験的な機能です。本番のゲートには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入力をURLへのPOSTリクエストとして送信し、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 Hooks

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

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

通知、telemetry、バックアップにはasyncを使用します。フォーマット、検証、または次のアクションの前に完了しなければならないものには、決してasyncを使用しないでください。

個別hooksよりdispatcher

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

解決策は、キャッシュされたstdinからhooksを順番に実行する、イベントごとに1つのdispatcherです。

#!/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を使用します。 exit code 2のstderrはエラーメッセージとしてClaudeに返されます。ブロックしないstderr（exit 1、3など）はverbose mode（Ctrl+O）でのみ表示されます。
3. jqの失敗に注意します。 誤ったJSONパスは、黙ってnullを返します。実際のtool inputに対してjq式をテストしてください。
4. exit codeを確認します。 exit 1を使用するPreToolUse hookは、動作しているように見えても強制力はまったくありません。
5. hooksを高速に保ちます。 hooksは同期的に実行されます。すべてのhookを2秒未満、理想的には500ms未満に抑えてください。

SDK側hook event streaming

claude-agent-sdk-python（v0.1.74以降、2026年5月6日）上に構築されたself-hosted harnessesでは、シェルスクリプトcallbackを経由せず、message streamから直接hook eventsを購読できます。³⁶ ClaudeAgentOptionsでinclude_hook_events=Trueを設定すると、HookEventMessageオブジェクト（PreToolUse、PostToolUse、Stopなど）がassistant messagesやtool resultsと同じiteratorからyieldされます。これはTypeScript SDKのincludeHookEventsオプションを反映したもので、bundled CLIも同じリリースでv2.1.129に引き上げられました。

event-stream patternは、harnessがすでにPython内にあり、model outputと同じcontrol flowでhook signalsを扱いたい場合に適しています。複数のtoolsを組み合わせるharnesses、Claude CodeとCodex間でhooksを共有するharnesses、またはブロックのためにexit-code semanticsを必要とする場合には、shell-script hook contract（exit codes、stdin JSON、dispatchers）が依然として適切です。

TypeScript SDKの2026年7月のseries（v0.3.205～v0.3.208）により、streamed protocol自体がより契約的になりました。⁷⁰ interruptsは現在、typed receiptsを返します。interruptは、still_queued UUIDによってどのqueued messagesがまだpendingかを通知します。また、sessionsはsystem/initでinterrupt_receipt_v1 capabilityを通知するため、coordinatorは「interruptが到達した」ことと「すでにin flightのmessageをinterruptが追い越した」ことを区別できます。command_lifecycle framesは、messageごとのqueued/started/completed/cancelled/discardedを報告します。これは、transcript inferenceなしに「送信したmessageに何が起きたか」に答える初のfirst-partyの手段です。より小さなsurfaceも追加されました。subagent completion payload用のAgentToolCompletedOutput typeと、canUseTool callbacksがupdatedInput fieldなしで{behavior: 'allow'}を返せるようになったことです。

このseriesの1行は機能ではなくsecurity floorです。v0.3.208では、pending hook中にcaller abortが到着した際、hook successへ変換される問題が修正されました。つまり、PreToolUse hookでゲートされたtoolが、callerのabort後に実行される可能性がありました。⁷⁰ harnessがSDK側hooksをpermission gateとして使用し、in-flight workのキャンセルにabortを依存している場合、v0.3.208を最低バージョンとして扱ってください。これより前では、「aborted」は確実に「blocked」を意味しませんでした。Python v0.2.127（2026年7月24日）は、1か月のうちに発生したこの形の2つ目のbypassです。query()が、background subagentsがまだ実行中であるにもかかわらず、最初のresult frameでstdinを閉じたため、それらのSDK-MCP tool callsは"Stream closed"で失敗し、さらにPreToolUse hooksを完全にbypassしました。⁸⁵ このpatternを明確にし、注意してください。SDK側hook enforcementは、hook verdictが収集される前にtransportが停止するlifecycle edges、すなわちabort、teardown、stream closeでfail openします。そしてbypassed hookは承認したhookとまったく同じに見えるため、黙って失敗します。両方のSDK floorsを固定し、証明可能なenforcementとしてshell-hook layerを維持してください。

Effortとsession provenance（2026年5月7～8日）

Claude Code v2.1.132およびv2.1.133の2つの追加により、hooksとsubprocessesは実行contextに関するより良いsignalを得られます。³⁸³⁹

• hook inputのeffort.level。 hooksは、tool_inputとsession_idを含む同じ入力でeffort.level JSON fieldを受け取るようになりました。同じ値は$CLAUDE_EFFORT env varとしてexportされるため、Bash commandsはJSONをパースせずに読み取れます。これにより、effort tierに応じてhook costを調整できます。lowでは高コストなvalidationをスキップし、xhighまたはmaxでは完全なsecurity gateを実行します。
• Bash subprocessesのCLAUDE_CODE_SESSION_ID env var。 Bash tool subprocessesは、hooksが参照するものと同じsession_id値をCLAUDE_CODE_SESSION_IDとして確認できるようになりました。これにより、sessionごとのstateを記録し、以前はsubprocess eventsとhook eventsを関連付けられなかったtoolsのprovenance gapが解消されます。

どちらのsignalもコード変更なしで利用できます。新しいfieldsを無視する既存hooksは、そのまま動作します。

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

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

ガバナンス harness で運用上注目すべき項目は、autoMode.hard_deny（新しいレバー）と MCP 消失の修正（長時間セッションを壊していた無言の障害）です。その他はすべて、使い勝手に関するクリーンアップです。

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

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

PostToolUse hook が拒否理由を Claude に返し、フローを終了せずにターンを継続すべき場合は continueOnBlock を使用します。これはセキュリティバイパスではなく、オペレーター体験の機能として扱ってください。ブロッキングゲートは、依然として安全でない結果をブロックする必要があります。

同じリリースでは、CLAUDE_PROJECT_DIR が MCP stdio サーバーに渡され、plugin configs ではコマンド内で ${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 アーキテクチャが必要になるわけではありません。

Claude Code v2.1.141 では、制御端末なしでデスクトップ通知、ウィンドウタイトル、ベルを扱うための hook-output terminalSequence フィールドが追加されました。⁵⁰ これは強制ではなく、オペレーターへのシグナルとして扱ってください。セキュリティおよび品質ゲートは、依然として通常のブロッキング契約、すなわち構造化された hook 出力と安全でない操作を防ぐ exit 動作を通じて失敗を伝える必要があります。同じリリースでは、Agent View を 1 つのディレクトリにスコープする claude agents --cwd <path>、GitHub SSH keys がない環境での plugin インストール用 CLAUDE_CODE_PLUGIN_PREFER_HTTPS、複数のワークスペースを対象とする workload-identity federation ルール用 ANTHROPIC_WORKSPACE_ID も追加されました。⁵⁰ これらはチーム harness のアーキテクチャ詳細です。より狭い運用ビュー、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 の sleep/wake とアップグレード後のクリーンアップ、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 を返して Claude にフィードバックを渡し、ターンを継続できるようになりました。レスポンスは hook エラーとしてラベル付けされません。以前は、Stop hook の実質的なレバーは exit-2 ブロックだけで、これはエラーとして扱われ、連続ブロック上限にカウントされます。品質ゲート harness にとって、これはよりクリーンなプリミティブです。「完了と言ったがテストは失敗している」と検出した Stop hook は、ハードブロックする代わりに「まだ失敗している項目はこれです。続行してください」と注入できます。真の停止条件にはブロックを使い、「まだ完了していない理由」を伝えるには additionalContext を使ってください。

クロスセッションメッセージングでは借用した権限が引き継がれなくなりました。 v2.1.166 は multi-session のケースを強化しました。別の Claude セッションから SendMessage 経由で中継されたメッセージは、発信元ユーザーの権限を引き継がなくなりました。そのため、受信セッションは中継された権限リクエストを拒否し、自動モードはそれをブロックします。オーケストレーションでエージェント同士がメッセージを送る場合、受信メッセージは認証済みの指示ではなく、信頼できないデータとして扱ってください。これは、security section がツール出力に適用している原則を、inter-agent messaging に拡張したものです。v2.1.199 時点で、Claude Code は 2 つのエージェントが同じ名前を共有しているため SendMessage が誤送信された場合も検出して警告します。これは、この権限境界を補完する信頼性対策です。同名の誤ったエージェントにメッセージが届くこと自体が、別種のオーケストレーションバグになるためです。 セッションが第一級のピアになりました（v2.1.224+）。 クロスセッションメッセージングは、リレー強化から完全な機能群へと発展しました。SendMessage/ListAgents により、macOS/Linux の各マシンにあるセッションを検出し、相互にメッセージを送信できます。受信側では crossSessionInbound による受諾／保留／拒否の制御が可能です。さらに、self-hosted runners により、Claude Code の Web・モバイルセッションを、自分で管理するハードウェア上で実行できます。harness アーキテクチャにおいて、これは「1つのセッション」をアドレス指定可能なノードへと変えます。検出、受信ポリシー、そして前述の権限境界は、もはやメールボックス用スクリプトではなくプラットフォームの基本機能です（完全な契約は Claude Code ガイド に記載されています）。⁸⁷ あわせて、運用姿勢にも1つ変更があります。Pro、Max、Team プランでは、2026年8月14日に auto mode がデフォルトの権限モードになります。Manual mode のプロンプトを human-in-the-loop の最後の防波堤として頼りにする harness では、暗黙に期待せず defaultMode を明示的に固定してください。⁸⁷

モデルのレジリエンスが第一級の設定になりました。 fallbackModel 設定では、プライマリモデルが過負荷または利用不可の際に順番に試す、最大3つのバックアップモデルを連鎖させられます。また、予期しない再試行不可の API エラーが発生した場合、ターンは fallback で1回自動再試行されます。長時間稼働する自律型 harness では、一時的なプライマリモデルの障害が実行の脱落ではなく、穏やかな機能低下に変わります。claude agents --json には、ブロックされたバックグラウンドセッションが何を待っているか（権限プロンプトなど）を示す waitingFor フィールドも追加されました（v2.1.162）。これはエージェント群をポーリングするコーディネーターにとって、可観測性の大きな改善です。

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

モデル階層について。 Claude Code v2.1.197（2026年6月30日）時点で、Claude Sonnet 5 は新規セッション向けの出荷時デフォルトモデルです。ネイティブ 1M コンテキストと、8月31日までのプロモーション価格（入力／出力それぞれ MTok あたり $2/$10）により、標準選択肢として Opus 4.8 に代わりました。本ガイドでは、Opus 5（claude-opus-5）を推奨する agentic デフォルトとして扱います。長期的でリスクの高いエージェントループこそ Opus の推論深度がコストに見合う場面であるため、意図的に別の選択をしない限り、自律型 harness ではこのモデルを使用してください。Opus 5 は 2026年7月24日に Claude Code v2.1.219 で新しいデフォルト Opus としてリリースされました。1M コンテキスト、MTok あたり $5/$25（置き換える Opus 4.8 と同額）、約2.5倍のデフォルト速度を実現する fast mode は $10/$50 です。Anthropic は、Frontier-Bench v0.1 において Opus 4.8 の2倍超の性能を示しつつ、半額で Fable 5 の CursorBench 3.2 スコアの0.5%以内に収まったと報告しています。⁸⁴⁹¹ 同価格で高性能になり、Anthropic が「作業を検証し、慎重に反復する能力がはるかに高い」と評価するモデルは、harness 作業ではコスト面の議論を必要としない稀有なアップグレードです。4.8 からの移行は ID の変更だけです。コスト重視または高スループットの作業で、速度と知能の比率が優位になる場合は Sonnet 5 に下げてください。Opus の上には Claude Fable 5（claude-fable-5）があります。2026年6月9日に登場したこの新階層は、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 classifier の Fable-5 fallback は、現在 Opus 5 に解決されます。⁸⁴

Codex が multi-agent v2 をリリースしました。 Codex CLI v0.137.0 では、実行時の選択が各スレッドに保持され、生成したエージェント向けの follow-up とメタデータのデフォルトが整理されました（hide_spawn_agent_metadata はデフォルトで true です）。また、生の親イベントを子リスナーへ伝播します。subagent モデルは明示的なままです。組み込みの default/worker/explorer agent types、TOML で定義するカスタムエージェント、そして並行実行制御（agents.max_threads のデフォルトは6、agents.max_depth のデフォルトは1）があります。同リリースでは、ターンごとの skill-catalog 解決機能を持つ v1 skills extension と、新しい thread-start/turn-error ライフサイクルコントリビューターイベントも加わりました。これにより、カーネルサンドボックスをデフォルト境界として維持しつつ、Claude Code の hook/skill 機能群との差が縮まりました。その後 Codex v0.138.0～v0.139.0 では、multi-agent v2 が本番向けに強化されています。エージェント間メッセージのペイロードは暗号化され、v2 agent config catalog と agent-residency LRU により常駐を維持するエージェントを管理できるようになりました。さらに、並行実行数は生成済みスレッドではなくアクティブな実行に基づいて数えられるため、アイドル状態のエージェントはスロットを消費しません。⁶¹ ライフサイクル API も成熟しました。close_agent は、単にハンドルを閉じるのではなく実行中のエージェントを中断することを示すため、interrupt_agent に改名されました（v0.139.0）。また、subagent が発生させた MCP 起動警告は、親のトランスクリプトへ重複して伝播せず、所有スレッドのスコープ内に留まります。⁶¹ Codex 側のオーケストレーションを構築する人にとって、これらはデモとエージェント群の違いを生みます。すなわち、暗号化されたメッセージ転送、制限された常駐、実行数に基づく並行制御、そしてスレッド境界を越えて漏れない警告です。続く Codex v0.140.0 では、クロスtool の接点が開かれました。/import は Claude Code からセットアップ、プロジェクト設定、最近のチャットを選択的に Codex へ取り込み、セッションは恒久的に削除可能になりました（確認保護付きの codex delete / /delete）。⁶⁴ /import は、運用者が harness 間を移動することを初めて公式に認めた機能です。ある 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 ファイルには、セッションをまたぐエラー、決定、パターンを記録します。VARが0のとき、bashで 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-agent協調に関する最近の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）はプロンプトキャッシュを守ります。ターンをまたいで蓄積されたキャッシュを壊さずに、セッションの作業ディレクトリを途中で変更できます。⁶⁰ それ以前は、ディレクトリを変更すると新しいセッションとコールドキャッシュが必要でした。1つのリポジトリから兄弟リポジトリへ移る長時間のセッションでは、これはmonorepoや複数サービスの作業でよくありますが、/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：フレッシュコンテキスト反復（The Ralph Loop）

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

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

1つの長いセッションと比較してみましょう。

Minute 0:   [fresh context]        -> productive
Minute 30:  [context filling]      -> somewhat productive
Minute 60:  [mostly consumed]      -> degraded
Minute 90:  [compaction pending]   -> significantly degraded
Minute 120: [compressed, lossy]    -> errors accumulate

反復ごとにフレッシュコンテキストを使うアプローチでは、反復ごとに十分な認知リソースを確保する代わりに、状態ファイルの読み取りやgit履歴の確認といったオリエンテーション作業に15〜20%のオーバーヘッドが発生します。¹⁶ コストと便益は次のとおりです。60分未満のセッションでは、1つの会話の方が効率的です。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 インスタンスです。ほとんどはクリーンなコンテキスト（メインの会話による汚染がない状態）で起動します。ただし、以下の fork タイプは例外で、意図的にすべてを継承します。指定されたツールで動作し、結果を要約として返します。調査結果によってメインの会話が肥大化することはなく、結論だけが返されます。⁵

組み込みの Subagent タイプ

カスタム Subagents の作成

.claude/agents/（プロジェクト）または ~/.claude/agents/（個人）で subagents を定義します。

---
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以降、「always allow」ルールは worktree をまたいでリポジトリルートに永続化されるため、ある worktree 内で承認したルールは同じリポジトリの兄弟 worktree にも適用されます。⁶⁹ これは並列 worktree エージェントにとって適切な使い勝手ですが、使い捨ての実験中に与えた許可が実験終了後も残ることを意味します。目の前の worktree だけでなく、リポジトリ全体を念頭に置いて許可してください。

v2.1.216では仕上げとなる対応が行われ、worktree による分離が不具合修正の段階から、強制力のある仕組みへと進化しました。⁷⁴ v2.1.210の修正により、worktree の subagents が通常の git 呼び出しを通じてメインのチェックアウトを変更することは防止されました。しかし 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 を生成できるようになり、最大5階層までネストできるようになりました。それ以前の委任は、実質的に1階層まででした。⁶² この仕様は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 と task list を介して通信し、互いの調査結果に異議を唱えることもできる複数の Claude Code インスタンスを連携させます。⁵

有効化：export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Agent Teams と subagents の使い分け：

Agent View と Goal Loops（2026年5月）

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

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

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

Workflow Tool（v2.1.147以降）

Claude Code の動的 workflows は、正式提供され、デフォルトで利用可能な機能です。v2.1.154以降、バックグラウンドで数十から数百のエージェントをオーケストレーションし、/workflows で監視できます。また、「Dynamic workflow size」の /config コントロール（v2.1.202）と、デフォルトのガイドラインが medium（特に指示がない限り、エージェント数を15未満に抑えることを目指す）に設定された workflowSizeGuideline 設定キー（v2.1.219）が用意されています。この機能は、その1つ前のv2.1.147で、CLAUDE_CODE_WORKFLOWS=1 の背後にあるデフォルト無効の Workflow tool として初登場しました。このフラグが必要だった時代はすでに過去ですが、そこで示されたアーキテクチャ上の意義は変わりません。⁵² 以前はカスタムのディスパッチスクリプト、mailbox の状態、subagent の連携規約を必要としていたフローに対し、Claude Code がファーストパーティのオーケストレーションプリミティブを提供します。

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

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

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

Session Forking と自動バックグラウンド化された 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 loop を停止させることはなくなりました。一方で、「ツールが結果を返したこと」と「ターンが続行したこと」が同じイベントではなくなるため、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で実行できます。明示された理念は「制約より分離」です。エージェントは、プロンプトではなくインフラストラクチャ層で強制される境界の内側で、高い自律性を持って動作します。²⁵ これは、異なるツールベンダー間 にサブエージェント分離の考え方を直接拡張するものです。ワークフローが Claude とOpenAIモデルにまたがる場合、Scionはエージェントごとのworktreeと認証情報の分離を備えた、初めての実用的なクロスツール・サブエージェントの参照実装です。

議論は万能薬ではありません： M3MAD-Benchの研究クラスター（2026年初頭）は、マルチエージェントの議論には頭打ちがあり、誤解を招く合意によって損なわれる可能性があることを示しました。ほかのエージェントが誤った答えを自信を持って主張すると、妥当な議論が負けてしまいます。²⁶ Tool-MADでは、各エージェントに異種のツールアクセスを与え、判定段階でFaithfulness/Relevanceスコアを使用することで、これを改善します。議論形式のオーケストレーションを構築する場合は、エージェントごとの（a）ツールの多様性と、（b）エージェント数が増えれば回答も良くなると仮定するのではなく、定量的な判定スコアリングに投資してください。

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

以下で説明する熟議インフラストラクチャを自分で構築したくない場合は、Multiagent Orchestration が2026年5月6日に Claude Managed Agentsでパブリックベータになりました。³⁵ Anthropic によると、「1つのエージェントでは十分に対応できないほど作業量が多い場合、マルチエージェント・オーケストレーションにより、リードエージェントは作業を複数の部分に分け、それぞれ独自のモデル、プロンプト、ツールを持つ専門家へ委任できます。」³⁵ 専門家は「共有ファイルシステム上で並行して作業し、リードエージェントの全体コンテキストに貢献します」。³⁵

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

対応するパブリックベータ機能が Outcomes です。Anthropic によると、「成功の姿を記述したルーブリックを作成すると、エージェントはそれに向けて作業します。別の評価者が独自のコンテキストウィンドウで基準に照らして出力を評価するため、エージェントの推論の影響を受けません。」³⁵ これは、このセクションの後半で説明する2ゲート検証パターンのマネージドサービス版です。ルーブリックが手書きのゲートに、独立した評価者がコンセンサス検証器に相当します。

検証を独自のhook surface（PreToolUseによるブロック、終了コードのセマンティクス、カスタムdispatcher）と統合する必要がある場合、またはharnessを外部依存なしで実行しなければならない場合は、セルフホストの熟議が引き続き適切な選択です。標準的な委任とルーブリック評価こそが実際に必要な契約である場合は、管理型Multiagentが適しています。

最小限で実用的な熟議

まずは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 hook）。各熟議エージェントの完了直後に実行します。 1. フェーズが少なくともRANKINGに到達していること 2. 最低2つのエージェントが完了していること（設定可能） 3. コンセンサス・スコアがタスク適応型のしきい値を満たしていること 4. いずれかのエージェントが反対した場合、懸念事項が記録されていること

ゲート2：Pride Check（Stop hook）。セッションを終了できる前に実行します。 1. 多様な手法：複数の固有ペルソナが含まれていること 2. 矛盾の透明性：反対意見に理由が記録されていること 3. 複雑さの処理：少なくとも2つの代替案が生成されていること 4. コンセンサスの信頼度：強い（0.85超）または中程度（0.70-0.84）に分類されていること 5. 改善の証拠：最終的な信頼度が初期信頼度を上回っていること

ライフサイクル上の異なる時点に配置した2つのhookは、失敗が実際に起こる形に対応します。即時に起こる失敗（低いスコア）もあれば、徐々に現れる失敗（多様性の低さ、反対意見の記録漏れ）もあります。⁷

なぜ合意は危険なのか

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の差が、群集心理のコストです。⁷

見せかけの合意を検出する

同調性検出モジュールは、真の評価をせずにエージェントが合意していることを示すパターンを追跡します。⁷

スコアの集中： 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つの検証hookを実行していました。エージェントは0.52のコンセンサス・スコア（しきい値未満）で熟議を完了し、その後20分間、無関係なタスクを続けてから、セッション終了hookが失敗を検出しました。2つのゲート（タスク完了時に1つ、セッション終了時に1つ）に分割することで、同じ問題を異なるライフサイクル時点で捉えられるようになりました。⁷

熟議のコスト

各調査エージェントは、およそ5,000トークンのコンテキストを処理し、2,000-3,000トークンの調査結果を生成します。3エージェントの場合、決定あたり15,000-24,000トークンが追加されます。10エージェントの場合は、およそ50,000-80,000トークンです。⁷

現在のOpus 5の価格（MTokあたり$5/$25）では、3エージェントによる熟議のコストはおよそ$0.23-0.30です。10エージェントによる熟議では$0.75-1.00です。システムはおよそ10%の決定で熟議をトリガーするため、すべての決定における償却コストはセッションあたり$0.08-0.10です。（以前の版では、旧来の$15/$75のOpus 4.x価格で算出した、これらの3倍の数値を掲載していました。）その価値があるかは、誤った決定にどれほどのコストがかかるかによります。

熟議すべきとき

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ではセッションが停止していたツール障害後も処理を続行します。subagentコード内の防御的なリトライラッパーは減らせますが、なくすことはできません。hookレベルのガードは維持し、プロンプト内の「ツールが失敗したら3回再試行する」という足場は削減してください。
• xhigh努力階層： Opus 4.7と同時に導入され、現在のOpusモデルでサポートされています（Opus 4.8ではv2.1.154で/effort xhighとして提供され、Opus 5にも継承されています）。highとmaxの中間に位置します。コーディングおよびagenticワークロードの推奨デフォルトです。長時間実行するsubagentでは、xhighはトークンコストの増加を抑えながらhighを大きく上回ります。単発の難しい推論には引き続きmaxが適していますが、継続的なタスクにはxhighの方が優れています。
• トークン予算の上限： output_config.task_budget（ベータヘッダーtask-budgets-2026-03-13）により、agentの実行ごとに設定できます。モデルは残り時間のカウントダウンを把握し、予期せずトークン切れになる代わりに予算に合わせて作業範囲を適切に調整します。短いプロンプトの品質を犠牲にせず、予測可能なトークン消費にしたいagenticループで使用してください。
• 暗黙的なニーズの認識： ユーザーの文字どおりの依頼だけでは実際に必要なことが十分に指定されていない場合を認識する「implicit-need」テストに合格した最初のClaudeモデルです。これにより、CLAUDE.mdの「clarifying rules」セクションの必要性は低くなります。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をブランチすること）に依存していたagentは、明示的に再設定しない限り、新しいworktreeでプッシュ前の作業へアクセスできなくなります。

enterprise可観測性向けOTelフィードバック調査（2026年5月8日）

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

コーポレートランチャーとMCP規模のパフォーマンス（2026年7月）

v2.1.207の2つの変更は、本番デプロイメントにとって重要です。⁶⁸ CLAUDE_CODE_PROCESS_WRAPPERにより、管理環境ではClaude Codeプロセスをコーポレートラッパーバイナリ経由で起動できます。これは、エンドポイントagent、起動時ポリシーチェック、すべてのプロセスを指定のsupervisor配下で実行しなければならない環境の統合ポイントです。以前にshell aliasや独自ランチャースクリプトでこれを代替していたenterpriseにとって、これはサポートされる接続点です。

同じリリースでは、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 gate

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

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

人間によるマージ権限

2026年5月の、29,585件のAI-agentプルリクエストライフサイクルを対象としたarXiv研究では、運用上のagent権限とマージのガバナンスが分けられています。⁴⁷ 実用的なアーキテクチャ上の教訓はシンプルです。agentは作業の開始、ブランチの継続、PRの作成、作業のレビュー、リスクの要約を行えますが、マージ権限は別のガバナンス境界として維持されます。

その境界をharness内で明示してください。agentにはPRの準備と証拠収集を任せ、組織に別途監査済みの自動化ポリシーがない限り、マージ、リリース、破壊的なリポジトリ操作には人間の承認を必須にします。自動化がマージを実行する場合は、実行者と、それを承認した人間またはポリシーを区別するログを残してください。

エラー処理パターン

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

blast radiusの分類

すべてのagentアクションをblast radiusで分類し、それに応じてゲートを設定してください。²

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

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

効果的な自律タスクには、目的、完了条件、コンテキストへのポインターという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ステータスコード、ファイルの存在確認などです。初期のタスクでagentに「通るテストを書いて」と依頼したところ、assert Trueとassert 1 == 1が生成されました。技術的には正しいですが、実用上は価値がありません。¹⁶

注意すべき失敗モード

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

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

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

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

3. Agentがテスト実行のためにBashを呼び出します。 PreToolUse:Bashが発火します。認証情報チェック、sandbox検証、プロジェクト検出を行います。90msです。テストが実行されます。PostToolUse:Bashが発火し、アクティビティのheartbeatを記録してドリフトを確認します。

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

5. Agentがストーリーを完了します。 Stopが発火します。quality gateは、agentが証拠を示したか、曖昧な表現を使ったか、diffにTODOコメントがあるかを確認します。いずれかのチェックに失敗した場合は終了コード2となり、agentは続行します。

6. 独立した検証： 新しいagentが、前のagentによる自己報告を信頼せずにテストスイートを実行します。

7. 3つのコードレビューagentが並列に起動します。 それぞれが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、quality gates、multi-agent review）を比較しています。

2件の認証情報漏洩では、APIキーのローテーションと下流サービスの監査が必要になり、インシデント対応に約4時間かかりました。同等の問題を防止するharnessのオーバーヘッドは、ストーリーあたり2.4秒のbashでした。Stop hookがagentによる完了報告を許可する前に独立してテストを実行したため、誤った完了率は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のステートレスターンと自己申告アイデンティティ。 MCP仕様は、2026年7月28日の改訂（現在のCurrent spec）でステートレスコア（SEP-2575）への移行を完了しました。この改訂では、以前サーバーアイデンティティを伝えていたステートフルなinitializeハンドシェイクが廃止されています。7月16日にマージされたドラフト仕様の変更（PR #3002）では、アイデンティティが任意のサーフェスとして復元されました。サーバーはレスポンスの_metaにio.modelcontextprotocol/serverInfoオブジェクトを含められ、リクエストのclientInfoは任意になります。⁷¹ セキュリティ上重要なのは、仕様が信頼について述べている点です。このアイデンティティは自己申告で未検証であり、表示とログ記録専用で、セキュリティ判断の根拠にしてはなりません。harnessがMCPサーバーの申告名をもとに許可リスト、権限ルール、ログベースの監査を行う場合、その名前は認証情報ではなく主張です。信頼はサーバー自身が名乗る内容ではなく、トランスポートと設定（自分でどのエンドポイントにどのサーバーを設定したか）に固定してください。ステートレス改訂は予定どおり2026年7月28日にリリースされました（必須のserver/discover、_metaによるプロトコルバージョンネゴシエーション、Streamable HTTPヘッダー）。上記の信頼に関するガイダンスは、リリース済みの挙動を説明しています。

Skill sandboxツール: skillsを攻撃対象領域として扱うチーム向けに、PermisoのSandyClaw（2026年4月2日リリース）は、専用Sandboxでskillsを実行し、Sigma/YARA/Nova/Snort検出に基づく証拠付き判定を提供します。skill-sandboxカテゴリで初めての製品です。²⁸

Sandbox

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

2026年5月のセキュリティ下限。 Claude Code v2.1.149では、PowerShellの作業ディレクトリ権限バイパス、複数のPowerShell許可ルールおよび古い変数による権限分析の欠落、共有git内部領域だけでなくメインリポジトリのルート全体を対象としていたgit-worktree sandboxの書き込み許可リストバグが修正されました。⁵³ harnessでPowerShellまたはworktree分離エージェントを許可する場合は、v2.1.149以降を下限とし、shellルールを狭く保ってください。広範なPowerShell(*)やリポジトリ全体への書き込み例外は、オーケストレーションの近道であって安全境界ではありません。

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

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

製品をまたぐ3つの封じ込めパターン（Anthropic、2026年5月）

Anthropicのエンジニアリング記事「How we contain Claude across products」（2026年5月25日）は、この節で断片的に教えてきた原則、つまり上記の設定レベルSandbox、worktree分離の下限、すべてを信頼できないものとして扱う姿勢について、ベンダー自身が表明したものです。⁸¹ 中核となるのは、封じ込め強度を製品サーフェスに対応付けることです。そして、この対応付け自体が教訓です。正しい分離デザインが1つあるのではなく、誰が監督できるか、何が起こり得るかに適合した分離があります。

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

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

設定サーフェスは第1原則に追いつきつつあります（v2.1.219）。 「まず環境レイヤーで封じ込める」は賛同しやすい一方、実際に設定するのは難しいものでした。Claude CodeのSandboxは、ルールでカバーできないものを質問によって解決しており、上記の93%承認という数字が認めるように、権限プロンプトは決定論的な衣装を着た確率的防御だからです。sandbox.network.strictAllowlistを設定すると、egressに関する質問を排除できます。これを設定した場合、Sandbox内コマンドによる許可リスト外ホストへのリクエストは、プロンプト表示ではなく即座に拒否されます。⁸⁴ v2.1.216のsandbox.filesystem.disabledと組み合わせると、2つの設定はトグルの寄せ集めではなく1つの態勢になります。ファイルシステムとネットワークの封じ込めは独立して選択でき、ネットワーク封じ込めは決定論的にできます。無人のharnessでは、この2つのうちegressのほうが重要です。注入された指示が情報流出に変わるのはegressであり、承認疲れの最終形は、疲れる人がキーボードの前にいないことだからです。代償は決定論的な境界に伴う通常の代償です。許可リストが正しくなければならず、忘れたホストは質問ではなく不透明な拒否として失敗します。エージェントが正当に必要とするホストを列挙してから、プロンプトを取り除いてください。

これらはいずれもhookレイヤーを置き換えるものではなく、その下に位置します。封じ込めパターンは決定論的な下限であり、このガイドのworktree強制の履歴は、その縮図として同じ教訓を示しています。境界が意味を持つのは、意図的なリダイレクトに対しても維持される場合だけです。そして維持される可能性が最も高いプリミティブは、その場のために書かれたものではありません。

権限境界

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

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

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

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

パススコープの許可ルールは作業ディレクトリにアンカーされる（2026年7月）

Claude Code v2.1.214では、パススコープの権限ルールにおける静かな過剰一致が修正されました。単一セグメントのdir/**パターン（たとえばEdit(src/**)）を持つ許可ルールは、vendor/some-package/src/や、ルール作成者が許可する意図のなかった他のすべてのネストした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、特定のstackを指定していない場合のインフラ破棄（terraform destroy、pulumi destroy、cdk destroy）です。⁶⁵ アーキテクチャ上、これは上記の起動審査およびパラメータレベルルールを補完するものです。どのツールか、どのように起動されるかをゲートするのではなく、少数の特定の不可逆コマンドを意図によってゲートします。エージェントは依然として実行できますが、自発的にはできず、明示的な指示がある場合だけ実行できます。自律的なharnessでは、同じ原則を独自のPreToolUse hooksにエンコードしてください。状態を破壊するコマンドには、明示的なオペレーターシグナルだけが解除できるデフォルト拒否ルールがふさわしいものです。

2026年7月: auto modeがエンタープライズ対応となり、1つのプロンプトは免除不可能になります。 auto modeはv2.1.207でAmazon Bedrock、Google Vertex AI、Microsoft FoundryにおいてGAとなり、disableAutoMode管理設定がエンタープライズ向けオプトアウトとして提供されました。分類器をチェックレイヤーとする姿勢は、すべてのファーストパーティエンタープライズプラットフォームで利用可能になり、無効化はプラットフォームの欠落ではなく明示的なガバナンス判断になります。⁶⁸ 続くv2.1.208では、壊滅的な削除に対するガードが絶対的なものになりました。壊滅的な削除の確認プロンプトは、--dangerously-skip-permissionsとauto modeの両方を貫通します。⁶⁸ これは注目すべき前例です。明示的なバイパスフラグを含むどの権限態勢でも免除できない、Claude Codeにおける最初の確認です。--dangerously-skip-permissionsが文字どおりプロンプトゼロを意味すると仮定していた自律harnessのデザインでは、この1つの例外を考慮すべきです。これは、無人ループが最も回復不能な損害を与えられる箇所でのみ発動します。

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

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

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

プロンプトインジェクション防御

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では、Agent toolが、subagentが読んだコンテンツに含まれる間接的なプロンプトインジェクションに対して強化されました。毒性のあるファイル、Webページ、またはsubagentが取り込んだツール結果は、委任サーフェス自体を誘導しにくくなります。⁶⁹ さらにv2.1.211では、チェーン内の人間のリンクが強化されました。権限プレビューは現在、双方向オーバーライド文字、ゼロ幅文字、見た目が似たUnicode文字を無効化するため、承認ダイアログ上では無害に表示されながら別の内容を実行するようなコマンドを作成できなくなります。⁶⁹ 2つ目の修正は、時間的プレッシャーの下で人間がレンダリング済みプレビューを承認するharnessにおいて最も重要です。表示自体もインジェクションサーフェスだったからです。どちらの変更も、上記のhookレベル防御を置き換えるものではありません。その下の下限を引き上げるものです。

Agentログとガードレールはセキュリティサーフェスである

2026年5月の2つのアドバイザリは、1つのパターンを強調しています。エージェントインフラは、機密コンテンツや実行可能ポリシーが漏えいまたは脱出する新たな場所を生み出します。GitHub Advisory GHSA-f3jg-756w-gm35は、デフォルトのログ動作下で機密ツールペイロードコンテンツがローカルSQLiteログに残る可能性があるGryph Agentsのペイロードフィルター問題を対象としています。⁴⁵ OSV GHSA-wxxx-gvqv-xp7pは、管理者保護されたプロキシエンドポイントにおけるLiteLLMのカスタムコードガードレールSandbox脱出を対象としています。⁴⁶

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

Hookセキュリティ

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

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

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

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

パターンは次のとおりです。組織的コンテキスト、倫理的判断、または戦略的方向性を必要とする決定は人間が担います。大きな可能性空間を計算的に探索することを必要とする決定はエージェントが担います。Hooksがこの境界を強制します。

再帰的なHook強制

Hooksはsubagentのアクションに対しても発火します。¹³ ClaudeがAgent toolを通じてsubagentを起動した場合、PreToolUseおよびPostToolUse hooksはsubagentが使用するすべてのツールで実行されます。再帰的なhook強制がなければ、subagentは安全ゲートをバイパスできます。SubagentStopイベントでは、subagentの完了時にクリーンアップまたは検証を実行できます。

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

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

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

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

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

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

判断フレームワーク

各メカニズムを使う場面：

Skills vs Hooks vs Subagents

よくある質問

hooks はいくつまでなら多すぎませんか？

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

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

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

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

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

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

いいえ。confidence module は、曖昧さ、複雑さ、重要度、コンテキスト依存性という 4 つの次元で判断を採点します。総合確信度が 0.70 未満の判断だけが deliberation をトリガーし、全判断のおよそ 10% に相当します。ドキュメントの修正、変数名の変更、通常の編集では deliberation を完全にスキップします。セキュリティアーキテクチャ、データベーススキーマの変更、元に戻せないデプロイでは、一貫してトリガーされます。⁷

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

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

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

3 エージェントの deliberation では、実時間で 30～60 秒追加されます（この deliberation の設計では Agent tool を通じてエージェントを逐次実行します。一方、プラットフォーム自体は v2.1.198 以降、バックグラウンドで subagents を並行実行します）。10 エージェントの deliberation では 2～4 分追加されます。consensus と pride check hooks は、それぞれ 200ms 未満で実行されます。主なボトルネックはオーケストレーションのオーバーヘッドではなく、エージェントごとの LLM 推論時間です。⁷

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

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

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

アーキテクチャの原則（決定論的なゲートとしての hooks、ドメイン専門知識としての skills、分離されたコンテキストとしての subagents、メモリとしてのファイルシステム）は、どのエージェントシステムにも概念的に適用できます。具体的な実装では、Claude Code のライフサイクルイベント、matcher パターン、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 の Frontmatter

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

終了コード

主要コマンド

ファイルの場所

変更履歴

参照