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

TL;DR: Claude Code は、ファイルアクセス付きのチャットボックスではありません。29個の文書化されたライフサイクルイベントを持つプログラム可能な runtime であり、それぞれをモデルがスキップできない shell script で hook できます。hooks を dispatchers に、dispatchers を skills に、skills を agents に、agents を workflows に積み重ねると、制約を強制し、作業を委譲し、sessions をまたいで memory を永続化し、multi-agent deliberation を orchestrate する自律開発 harness になります。Claude Code v2.1.147 では、デフォルト無効の Workflow tool（CLAUDE_CODE_WORKFLOWS=1）が追加され、決定論的な multi-agent orchestration は純粋な userland scripts から first-party runtime primitive へ近づきました。v2.1.149 では、PowerShell の permission-bypass 修正と git-worktree sandbox allowlist 修正により、同じ教訓がセキュリティ面から補強されています。正しさを担うのは、今も hooks と evidence gates です。⁵²⁵³ このガイドでは、その stack のすべての層を扱います。単一の hook から、10-agent consensus system までです。frameworks は不要です。すべて bash と JSON で構成します。

Andrej Karpathy は、LLM agent の周りに育つものを claws と呼びました。agent が context window の外側の世界をつかむための hooks、scripts、orchestration です。¹ 多くの開発者は、AI coding agents を対話型アシスタントとして扱います。prompt を入力し、ファイルが編集されるのを見て、次へ進む。その捉え方では、生産性は自分が直接見守れる範囲に制限されます。

インフラとして見る mental model は違います。AI coding agent は、LLM kernel を持つプログラム可能な runtime です。モデルが行うすべての action は、自分が制御する hooks を通過します。定義するのは prompts ではなく policies です。モデルは、web server が nginx rules の中で動作するのと同じように、自分の infrastructure の中で動作します。nginx の前に座って requests を打ち込むわけではありません。設定し、deploy し、monitor します。

この違いが重要なのは、infrastructure が複利的に効くからです。bash commands 内の credentials をブロックする hook は、すべての session、すべての agent、すべての autonomous run を守ります。評価 rubric を encode した skill は、自分が呼び出しても agent が呼び出しても一貫して適用されます。security のために code を review する agent は、自分が見ているかどうかに関係なく、同じ checks を実行します。²

重要なポイント

• Hooks は実行を保証します。prompts は保証しません。 linting、formatting、security checks、そしてモデルの挙動に関係なく毎回必ず実行すべきものには hooks を使います。Exit code 2 は actions をブロックします。Exit code 1 は warning のみです。³
• Skills は、自動で有効化される domain expertise を encode します。 description field がすべてを決めます。Claude は、skill を適用するタイミングを keyword matching ではなく LLM reasoning で判断します。⁴
• Subagents は context bloat を防ぎます。 exploration や analysis 用に context windows を分離すると、main session を軽く保てます。独立した subagents は並列実行し、workers に継続的な coordination が必要な場合は agent teams を使います。⁵
• Memory は filesystem に存在します。 Files は context windows をまたいで永続化します。CLAUDE.md、MEMORY.md、rules directories、handoff documents が、構造化された外部 memory system を形成します。⁶
• Multi-agent deliberation は blind spots を見つけます。 単一の agent は、自分自身の前提を疑えません。評価の優先順位が異なる2つの独立した agents は、quality gates では対処できない構造的な失敗を見つけます。⁷
• Harness pattern こそが system です。 CLAUDE.md、hooks、skills、agents、memory は独立した機能ではありません。これらは、自分とモデルの間にある deterministic layer として組み合わさり、automation に合わせて scale します。

このガイドの使い方

各 section は、前の section を土台にしています。最後の Decision Framework には、problem type ごとに適切な mechanism を選ぶための lookup table があります。

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

ハーネスパターン

ハーネスはフレームワークではありません。これは1つのパターンであり、AIコーディングエージェントを決定論的なインフラで包み込む、ファイル・スクリプト・規約の組み合わせ可能なセットです。構成要素は次のとおりです。

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

Instruction Layer： CLAUDE.mdファイルとrulesディレクトリは、エージェントがプロジェクトについて把握する内容を定義します。これらはセッション開始時、およびコンパクション後に毎回自動で読み込まれます。これがエージェントの長期的な設計記憶となります。

Extension Layer： skillsはコンテキストに応じて自動起動するドメイン専門知識を提供します。hooksは、一致するすべてのツール呼び出しで発火する決定論的なゲートを提供します。memoryファイルはセッションをまたいで状態を永続化します。カスタムagentsは特化したsubagentの構成を提供します。

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

重要な洞察は次のとおりです。多くのユーザーはCore Layerだけで作業しており、コンテキスト膨張とコスト上昇をただ見ているだけです。一方、パワーユーザーはInstructionレイヤーとExtensionレイヤーを構成したうえで、Core Layerはオーケストレーションと最終判断のためだけに使うのです。²

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

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

OpenAI側のより深いSDK表面は、openai-agents Python v0.14.0（2026年4月15日リリース、4月16日発表）に到達しました。AgentのサブクラスであるSandboxAgentはdefault_manifest、サンドボックス命令、ケイパビリティを備え、Manifestは新規ワークスペース契約（ファイル、ディレクトリ、ローカルファイル、Gitリポジトリ、環境、ユーザー、マウント）を記述、SandboxRunConfigは実行ごとのサンドボックスクライアント配線、ライブセッション注入、マニフェストオーバーライド、スナップショット、マテリアライゼーションの並列実行上限を制御します。組み込みケイパビリティは、シェルアクセス、ファイルシステム編集、画像インスペクション、skills、サンドボックスメモリ、コンパクションをカバーします。サンドボックスメモリは抽出された教訓を実行間で永続化し、段階的に開示します。ワークスペースはローカルファイル、Gitリポジトリエントリ、リモートマウント（S3、R2、GCS、Azure Blob、S3 Files）をサポートし、スナップショットはプロバイダー間でポータブルです。バックエンドはUnixLocalSandboxClient、DockerSandboxClient、およびオプション extras 経由でBlaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel向けのホステッドクライアントを揃えます。²⁴

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

ハーネスにボイスやリアルタイム層が含まれる場合、openai-agents-python v0.17.0（2026年5月8日）はRealtimeAgentのデフォルトをgpt-realtime-2に更新しました。⁴¹ 既存のリアルタイムセッションは新しいデフォルトを自動的に取り込みます。評価のために以前の挙動を保持する必要がある場合は、明示的に旧モデルをピンしてください。

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

どちらを選ぶか： セルフホストが適しているのは、すでにインフラ運用力を持つチーム、自分で制御するskills/hooksを望むチーム、特定のワークフローを深く最適化しているチームです。マネージドが適しているのは、専任のプラットフォームエンジニアがいないチーム、カスタマイズよりも価値創出までの早さを優先する場合、あるいはエージェント実行をラップトップを閉じても確実に生き延びさせたいが、その永続化レイヤーを自前で構築したくない場合です。両者は併用可能です——セルフホストのハーネスを動かしつつ、特定の長時間タスクをそのREST API経由でManaged Agentsに委譲することができます。

ディスク上でのハーネスの姿

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

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

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

Skills System

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

Skillを作るべきタイミング

Skillsは、Claudeが常に利用できる知識のためのものです。Slash commandsは、明示的にトリガーするアクションのためのものです。どちらにするか迷う場合は、こう問いましょう。「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 descriptionsはシステムプロンプトの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）が含まれています。

Context Budget

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

Supporting Filesと構成

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から相対リンクで参照します。Claudeは、skillが有効になったときに、必要に応じてこれらのファイルを読みます。SKILL.mdは500行未満に保ち、詳細な参照資料はsupporting filesに移しましょう。¹²

GitでSkillsを共有する

Project skills（repo rootの.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を自動的に取得します。インストールも設定も不要です。チーム全体で専門知識を標準化するには、これが最も効果的な方法です。

Prompt LibraryとしてのSkills

単一目的のskillsにとどまらず、ディレクトリ構造は整理されたprompt libraryとして機能します。

~/.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がコンテキストに基づいて自動的に参照するknowledge baseになります。ジュニア開発者でも、明示的に頼まなくてもシニアレベルのガイダンスを得られます。

SkillsはHooksと組み合わせられます

Skillsは、実行中のみ有効になる独自の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は強制です。組み合わせることで、policy layerになります。

よくあるSkillの失敗

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

Budgetを奪い合うskillsが多すぎる。 Skillsが増えるほど、1%のcontext budgetをめぐってdescription同士が競合します。Skillsが有効にならないことに気づいたら、/contextで除外されているものを確認してください。曖昧なskillsを大量に持つより、少数のよく記述されたskillsを優先しましょう。

重要情報がsupporting filesに埋もれている。 ClaudeはSKILL.mdをすぐに読みますが、supporting filesには必要になったときだけアクセスします。重要情報がsupporting fileにあると、Claudeが見つけられない可能性があります。必須情報はSKILL.mdに直接入れてください。⁴

SDK Skill Surface（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/における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をそこにscaffoldします。⁵⁸ これにより、以前は別々の場所に存在していた2つのproject-tooling形態のギャップが埋まります。つまり、repoに直接commitされる素のskillと、skillにhooksやMCP serverを組み合わせてbundleするものの、以前はインストールにmarketplaceが必要だったpluginです。harness designへの実務上の効果は明確です。project-scoped toolingは、配布のためにregistryを迂回する必要がなくなりました。書いて、commitすれば、チームメイトはgit pullで同じsurfaceを得られます。Pluginsは今でも、bundle install可能なユースケース（hooks + skills + MCP servers + agentsを1つのZIPにまとめる）を担います。変わったのは、プロジェクトが自分のtreeからそれを読み込むためだけにmarketplaceを立てる必要がなくなったことです。

Governanceとして同梱Surfaceを隠す（2026年6月8日）

Skillsはcapabilityであり、capabilityはattack surfaceです。Claude Code v2.1.169では、disableBundledSkills設定（および対応するCLAUDE_CODE_DISABLE_BUNDLED_SKILLS環境変数）が追加され、同梱skills、workflows、組み込みslash commandsをモデルから完全に隠せるようになりました。⁶⁰ 強化済みまたは規制対象のharnessでは、これは意図的なattack-surface削減です。特定のproject skillsとpersonal skillsのセットを監査・承認したoperatorは、Anthropicが標準で同梱するものをすべて抑制できます。その結果、モデルはoperatorが精査したsurfaceだけを推論対象にします。これはtool allowlistと同じように扱ってください。デフォルトは広いcapabilityであり、そのデフォルトをオフにすることは、便利なtoggleではなくgovernance上の判断です。

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

Claude Code v2.1.178により、project toolingはlocation-awareになりました。ネストされた.claude/skillsディレクトリ内のskillsは、repo rootからだけでなく、そのディレクトリ配下のファイルで作業しているときにも読み込まれるようになりました。名前が衝突した場合、ネストされたskillは<dir>:<name>として表示されるため、両方に到達できます。⁶³ 同じリリースでは、project surfaceの残りもworking directoryに最も近いものを解決するようになりました。ネストされた.claude/ディレクトリ間でagent、workflow、output-style名が衝突した場合、working directoryに最も近いものが勝ちます。また、project-scope workflowの保存先は常にrootではなく、最も近い既存の.claude/workflows/になります。⁶³ Monorepoやrepo-of-reposでは、これは1つの平坦なglobal surfaceと、コンテキスト内で有効化されるpackageごとのtoolingとの差になります。services/api/.claude/skills/には、そのtreeで作業している間だけ表示されるAPI固有のskillsを置くことができ、同じ名前のservices/web/ skillとも衝突しません。

Hook Architecture

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

利用可能なイベント

このガイド更新時点で、Claude Codeは8カテゴリにわたる29個のドキュメント化されたライフサイクルイベントを公開しています。イベントリストはリリースとともに増えるため、参照ドキュメントを信頼できる情報源として扱い、本番hooksを配線する前に、現在の完全な表をチートシートで確認してください。¹³

Exit Codeのセマンティクス

exit codeによって、hooksがアクションをブロックするかどうかが決まります。³

重要: すべてのsecurity hookはexit 1ではなく、必ずexit 2を使う必要があります。Exit 1は非ブロックの警告です。危険なコマンドはそのまま実行されます。これはチーム全体で最もよくあるhookのミスです。¹⁴

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フィールドは、イベント固有の値をフィルタリングします。toolイベントでは、Bash、Edit、Write、Read、Glob、Grepなどのtool_name値、mcp__server__toolのようなMCP tool名、または全ツールを表す*に一致します。単純な名前と|区切りのリストは完全一致です。それ以外の文字を含む値はJavaScript正規表現です。一部のイベントはmatchersをサポートせず、設定されている場合は常に発火します。¹³

Hook入出力プロトコル

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

{
  "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を出力してtool入力を変更したり、コンテキストを注入したり、permission decisionsを行ったりできます。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を書く前に、必ず問いましょう。どの種類の保証が必要なのでしょうか。¹⁴

Formatting guaranteesは、事後的に一貫性を確保します。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'"
          }
        ]
      }
    ]
  }
}

Safety guaranteesは、危険なアクションが実行される前に防ぎます。Bashに対するPreToolUse hooksはコマンドを検査し、破壊的なパターンをexit code 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

Quality guaranteesは、意思決定ポイントで状態を検証します。git commitコマンドに対するPreToolUse hooksはlinterやtest suiteを実行し、品質チェックに失敗した場合はcommitをブロックします。

#!/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"）はシェルスクリプトを実行します。高速で決定的であり、token costはありません。

MCP tool hooks（type: "mcp_tool"）は、すでに接続済みのMCP server上のtoolを呼び出します。validation logicがすでにMCP境界の背後にあり、別のシェルスクリプトが不要な場合に使います。

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

Agent hooks（type: "agent"）は、tool access（Read、Grep、Glob）を持つsubagentを起動してmulti-turn verificationを行います。これは実験的です。本番gatesにはcommand hooksを優先し、agent hooksは実際のファイルやtest outputを調べる必要が本当にあるチェックに限定してください。

{
  "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はprompt textから推測せずに、security-reviewerの実行とexplorerやgeneric workerを区別できます。⁴⁹

HTTP hooks（type: "http"）は、イベントのJSON入力をPOST requestとしてURLに送り、JSONを受け取ります。webhooks、外部notification services、またはAPIベースのvalidation（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は実行をブロックせず、バックグラウンドで実行できます。notificationsやloggingのような非クリティカルな操作にはasync: trueを追加します。¹³

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

asyncはnotifications、telemetry、backupsに使います。formatting、validation、または次のアクションの前に完了しなければならないものには、絶対にasyncを使わないでください。

独立HooksよりDispatchers

同じイベントで7つのhooksがすべて発火し、それぞれがstdinを独立して読むと、race conditionsが発生します。2つのhooksが同じJSON state fileに同時に書き込むと、JSONが切り詰められます。そのファイルをparseするすべての下流hookが壊れます。²

解決策は、イベントごとに1つのdispatcherを置き、cached 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をpipeします: 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 failuresに注意します。 間違ったJSON pathsは静かにnullを返します。実際のtool inputに対してjq式をテストしてください。
4. exit codesを確認します。 exit 1を使うPreToolUse hookは、動いているように見えても強制力はゼロです。
5. hooksを高速に保ちます。 hooksは同期的に実行されます。すべてのhooksを2秒未満、理想的には500ms未満に保ちます。

SDK側のHook Event Streaming

claude-agent-sdk-python（v0.1.74+、2026年5月6日）上に構築されたself-hosted harnessesは、shell-script callbacksを経由する代わりに、message streamからhook eventsを直接subscribeできます。³⁶ 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パターンは、harnessがすでにPython内にあり、hook signalsをmodel outputと同じcontrol flowで扱いたい場合に適しています。shell-script hook contract（exit codes、stdin JSON、dispatchers）は、複数ツールを組み合わせるharnesses、Claude CodeとCodexでhooksを共有するharnesses、またはブロックにexit-code semanticsが必要なharnessesに引き続き適した答えです。

EffortとSession Provenance（2026年5月7-8日）

Claude Code v2.1.132とv2.1.133の2つの追加により、hooksとsubprocessesは実行コンテキストについてより良いsignalを得られるようになりました。³⁸³⁹

• hook input内のeffort.level。 hooksは、tool_inputとsession_idを含む同じ入力でeffort.level JSONフィールドを受け取るようになりました。同じ値は$CLAUDE_EFFORT env varとしてexportされるため、Bash commandsはJSONをparseせずに読み取れます。これを使うと、effort tierに応じてhook costを調整できます。lowでは高価なvalidationをskipし、xhighまたはmaxではfull security gateを実行します。
• Bash subprocesses上のCLAUDE_CODE_SESSION_ID env var。 Bash tool subprocessesは、hooksが見るものと同じsession_id値をCLAUDE_CODE_SESSION_IDとして参照できるようになりました。これにより、session単位の状態をlogするtoolsが、以前は不可能だったsubprocess eventsとhook eventsの相関を取れるようになり、provenance gapが解消されます。

どちらのsignalもコード変更なしで利用できます。新しいフィールドを無視する既存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 exceptionsに関係なく、無条件でブロックするAuto mode classifier rulesです。これは既存のallow/deny matchersより上にある、交渉不可のgovernance leverです。operatorが個人設定でより広いカテゴリを承認している場合でも、絶対に上書きされてはならないルール（mainへのforce-push、secretを含むファイル、production database access）に使います。
• MCP serversが/clear後に消えなくなりました。 .mcp.json、plugins、claude.ai connectorsで設定されたserversが、VS Code extension、JetBrains plugin、Agent SDKで/clearした後、active setから静かに落ちていました。この修正はv2.1.136に含まれています。「MCP server X went missing mid-session」を見た場合、これが原因でした。
• 同時refresh時のMCP OAuth refresh-token loss。 複数のremote MCP serversを使うユーザーは、毎日の再認証が不要になるはずです。同時refresh writesが互いに上書きしていました。
• Plan modeがfile writesを正しくブロックするようになりました。 一致するEdit(...) allow ruleがplan-mode write protectionを回避していました。現在はallow rulesに関係なくPlan modeが強制されます。
• PluginのStopとUserPromptSubmit hooksがセッション途中で失敗しなくなりました。 Cache cleanupが、実行中sessionでまだ使用中のplugin-version filesを削除し、特にこの2つのhook eventsを壊していました。この修正では、使用中versionsがpinされます。
• plugin.jsonのskills entry。 skillsを設定するとpluginのデフォルトskills/ directoryが隠れていました。現在はentryが正しく合成され、file pathを指した場合は静かに失敗する代わりに明示的なエラーが出ます。
• CLAUDE_ENV_FILE SessionStart hook env varsのstale化。 SessionStart hooksがCLAUDE_ENV_FILE経由でexportしたvarsが、/resumeや/clear後にstaleになっていました。v2.1.136で修正されています。これらのイベントでsessionsはenv fileを再sourceするようになりました。

governance harnessesにとって運用上重要な項目は、autoMode.hard_deny（新しいlever）とMCP消失の修正（長いsessionsを壊していたsilent failure）です。それ以外はquality-of-life cleanupです。

Structured Hook ArgumentsとBlock Continuation（2026年5月11日）

Claude Code v2.1.139では、本番harnessesにとって重要な2つのhook詳細が追加されました。command hooks向けのargs: string[] exec形式と、PostToolUse hooks向けのcontinueOnBlockです。⁴²⁴⁴ hookがdynamic valuesやpath placeholdersを必要とする場合は、argsを優先してください。shellを使わずにcommandを直接spawnするため、quotingとinjectionのミスの大きな一群を取り除けます。

PostToolUse hookが拒否理由をClaudeに返しつつ、flowを終了せずにturnを継続すべき場合は、continueOnBlockを使います。これはoperator-experience機能として扱い、security bypassとして扱わないでください。blocking gateは、危険な結果を引き続きブロックすべきです。

同じリリースでは、MCP stdio serversにCLAUDE_PROJECT_DIRが渡され、plugin configsがcommands内で${CLAUDE_PROJECT_DIR}を参照できるようになりました。⁴² MCP toolsは、serverを起動したprocess working directoryに依存せず、この値からproject-relative pathsを解決するべきです。

Claude Code v2.1.140は、主にharness operators向けのreliability releaseです。settings変更時にConfigChange hooksが発火しない問題、disableAllHooksとallowManagedHooksOnlyがsettings levelsをまたいで正しく合成されないedge cases、hook resultsが返した意図しないenvironment variablesがpermission dialogsに露出する問題を修正しています。⁴⁹ これにより、このsectionの既存governance patternsはより信頼できるものになりますが、新しいhook architectureは必要ありません。

Claude Code v2.1.141では、制御terminalなしでdesktop notifications、window titles、bellsを扱うためのhook-output terminalSequenceフィールドが追加されました。⁵⁰ これはoperator signalingとして扱い、enforcementとして扱わないでください。security gatesとquality gatesは、通常のblocking contract、つまりstructured hook outputとunsafe actionを防ぐexit behaviorを通じて失敗を伝えるべきです。同じリリースでは、Agent Viewを1つのdirectoryにscopeするclaude agents --cwd <path>、GitHub SSH keysがない環境でplugin installsに使うCLAUDE_CODE_PLUGIN_PREFER_HTTPS、複数workspaceを対象にするworkload-identity federation rules向けのANTHROPIC_WORKSPACE_IDも追加されました。これらはteam harnesses向けのarchitecture detailsです。より狭いoperational views、plugin-install assumptionsの削減、明示的なenterprise token scopingを提供します。

Claude Code v2.1.142は、hook semanticsよりもbackground-session orchestrationにとって重要です。⁵¹ claude agentsは、wrapper stateに依存せず、明示的なdirectory、settings、MCP、plugin、permission、model、effort flagsを指定してbackground sessionsをdispatchできるようになりました。Fast modeのデフォルトはOpus 4.7になりました。harnessがOpus 4.6の挙動への依存を測定済みの場合にのみ、CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1をpinしてください。Root-level plugin SKILL.md discoveryとplugin-provided LSP visibilityは、packaging ambiguityを減らします。MCP_TOOL_TIMEOUT、既存background-session worktrees、daemon sleep/wakeとpost-upgrade cleanup、plugin cache cleanupの修正により、そうでなければorchestration bugsに見えるreliability gapsが閉じられます。

Stop-hook steering、cross-session authority、multi-agent v2（2026年6月）

6月上旬の4つの変更は、harnessとmulti-agent designに関わります。⁵⁹

Stop/SubagentStop hooksにsteering channelが追加されました。 Claude Code v2.1.163以降、StopまたはSubagentStop hookはhookSpecificOutput.additionalContextを返して、hook errorとしてラベル付けされることなく、Claudeにfeedbackを渡し、turnを継続できます。これ以前は、Stop hookの実質的なleverはexit-2 blockだけでしたが、これはerrorとして読まれ、consecutive-block capにもカウントされます。quality-gate harnessにとっては、こちらのほうがよりきれいなprimitiveです。「doneと言ったがtestsがred」の検出時に、Stop hookはhard-blockする代わりに、「まだ失敗している内容はこれです。続けてください」と注入できるようになりました。本当のstop conditionsにはblockを使い、「まだ完了していない理由を伝える」場合にはadditionalContextを使ってください。

Cross-session messagingはborrowed authorityを運ばなくなりました。 v2.1.166ではmulti-session caseが強化されました。別のClaude sessionからSendMessage経由で中継されたmessagesは、originating userのauthorityを持たなくなったため、受信sessionは中継されたpermission requestsを拒否し、auto modeもそれらをブロックします。orchestrationでagents同士にmessageを送らせている場合、inbound messageはauthenticated instructionではなく、untrusted dataとして扱ってください。これはsecurity sectionがtool outputに適用している原則を、inter-agent messagingに拡張したものです。

Model resilienceがfirst-class settingになりました。 fallbackModel設定は最大3つのbackup modelsをchainできるようになり、primaryがoverloadedまたはunavailableの場合に順番に試行されます。また、予期しない非retryableなAPI errorsでは、fallbackでturnが1回auto-retryされます。長時間実行されるautonomous harnessでは、これにより一時的なprimary-model outageがdropped runではなくgraceful degradationになります。claude agents --jsonにもwaitingForフィールド（v2.1.162）が追加され、permission promptなど、blocked background sessionが何を待っているかが表面化します。agentsのfleetをpollingするcoordinatorにとって、observability上の改善です。

clean-room governanceとtroubleshootingのためのSafe mode。 Claude Code v2.1.169では、すべてのcustomizationを一括で無効にしてsessionを開始する--safe-mode flag（および対応するCLAUDE_CODE_SAFE_MODE environment variable）が追加されました。CLAUDE.md、plugins、skills、hooks、MCP serversが無効になります。⁶⁰ これはharnessの逆、つまり意図的なclean-roomです。operatorがいずれ必ず抱く問いに答えるために使います。「この挙動はmodelから来ているのか、それとも設定した何かから来ているのか」。hookが誤発火したとき、skillが発動すべきでないときに発動したとき、MCP serverがcontextを汚染したとき、--safe-modeは比較対象となる既知の空baselineを提供します。これはgovernance primitiveでもあります。通常harnessが付与するpersistent authorityを一切持たないbare modelを実行する方法であり、operator-defined scaffoldingの影響なしに結果を再現する必要がある場合に重要です。

model tiersについての注記。 このガイドでは、Opus 4.8をClaude Codeのagentic default、つまり別途選択しない限りautonomous harnessesを実行するモデルとして扱います。2026年6月9日時点で、AnthropicはClaude Fable 5（claude-fable-5）をリリースしました。これはOpusより上の新しいtierで、最も強力なmodel、「Mythos-class」systemを一般利用向けに安全化したものとして説明され、Claude Code v2.1.170で/model claude-fable-5から選択できます。⁶⁰ Opus 4.8はagentic defaultのままです。より高いtierは、raw reasoning depthがcostを正当化するdecisionで意図的に使うべきであり、fleet全体のblanket settingとして使うものではありません。

Codexがmulti-agent v2を出荷しました。 Codex CLI v0.137.0では、runtime choiceが各threadに保持され、spawned agents向けのfollow-upとmetadata defaultsがより整理され（hide_spawn_agent_metadataはデフォルトでtrue）、raw parent eventsがchild listenersに伝播されます。subagent modelは明示的なままです。built-in default/worker/explorer agent types、TOML-defined custom agents、concurrency controls（agents.max_threads default 6、agents.max_depth default 1）があります。同じリリースでは、per-turn skill-catalog resolutionと新しいthread-start/turn-error lifecycle contributor eventsを持つv1 skills extensionも追加され、kernel-sandbox postureをデフォルト境界として保ちながら、Claude Codeのhook/skill surfaceとの差を縮めています。その後、Codex v0.138.0–v0.139.0では、multi-agent v2が本番向けに強化されました。inter-agent message payloadsは暗号化され、v2 agent config catalogとagent-residency LRUがどのagentsをresidentに保つかを管理し、concurrencyはspawned threadsではなくactive executionでカウントされるため、idle agentsはslotを消費しなくなりました。⁶¹ lifecycle APIも成熟しました。close_agentはinterrupt_agent（v0.139.0）にrenameされ、単にhandleを閉じるのではなく実行中agentをinterruptすることを反映しています。また、subagentが出したMCP startup warningsは、parent transcriptに重複して上がるのではなく、owning threadにscopeされるようになりました。⁶¹ Codex側のorchestrationを構築する人にとって、これらはdemoとfleetの違いです。暗号化されたmessage transport、bounded residency、execution-counted concurrency、thread boundaryを越えて漏れないwarningsです。Codex v0.140.0では、cross-toolのseamも開かれました。/importはClaude Codeからsetup、project config、recent chatsを選択的にCodexへ取り込み、sessionsは永久削除可能になりました（codex delete / /delete、confirmation safeguards付き）。⁶⁴ /importは、operatorsがharnesses間を移動することを初めて公式に認めたものです。あるharnessのために構築したconfigurationは、もうそこに閉じ込められていません。

Memory と Context

すべての AI 会話は、有限の context window の中で動作します。会話が長くなると、システムは新しい内容のための余地を作るために、以前のターンを圧縮します。この圧縮には情報の欠落が伴います。3ターン目に記録したアーキテクチャ上の判断が、15ターン目まで残るとは限りません。⁹

Multi-Turn Collapse の3つの仕組み

MSR/Salesforce の研究では、3つの独立した仕組みが特定されています。それぞれに異なる介入が必要です。⁹

Strategy 1: Memory としてのファイルシステム

context の境界をまたいで最も信頼できる memory は、ファイルシステム上にあります。Claude Code は、すべての session 開始時と compaction 後に CLAUDE.md と memory files を読み込みます。⁶

~/.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 ファイルには、session をまたいだエラー、判断、パターンを記録します。VAR が 0 のとき、bash の set -e で ((VAR++)) が失敗することを見つけたら、それを記録します。3 sessions 後に Python で似た integer edge case に遭遇したとき、MEMORY.md のエントリがそのパターンを浮かび上がらせます。¹⁵

Auto Memory（v2.1.32+）: Claude Code は project context を自動的に記録し、呼び出します。作業中、Claude は観察内容を ~/.claude/projects/{project-path}/memory/MEMORY.md に書き込みます。Auto memory は session 開始時に先頭の200行を system prompt に読み込みます。簡潔に保ち、詳細なメモは別の topic files にリンクしてください。⁶

Memory volume より memory curation（2026年5月）: LLM-agent cooperation に関する最近の arXiv preprint は、recall の拡張を失敗モードになり得るものとして位置づけています。著者らの実験では、より長い visible history が、28の model-game settings のうち18で協調を悪化させました。⁴⁸ これは確定した法則ではなく、デザイン上の警告として扱ってください。production rule はすでに十分明確です。MEMORY.md は短く保ち、詳細へリンクし、handoffs には判断に使える要約を置きます。生の transcript dumps、tool logs、長い recall feeds は searchable storage に置くべきであり、active prompt に自動投入するものではありません。

Strategy 2: Proactive Compaction

Claude Code の /compact command は、会話を要約し、重要な判断、file contents、task state を保持しながら context space を解放します。¹⁵

compact するタイミング: - 明確な subtask が完了した後（feature implemented、bug fixed） - codebase の新しい領域に入る前 - Claude が繰り返し始めたり、以前の context を忘れ始めたりしたとき - 集中的な session では、おおよそ25〜30分ごと

CLAUDE.md の custom compaction instructions:

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

Compaction は会話を守ります。一方、/cd command（Claude Code v2.1.169）は prompt cache を守ります。これは、ターンの中で蓄積された cache を壊さずに、session を途中で新しい working directory へ移動します。⁶⁰ 以前は、directory を変更すると fresh session と cold cache が必要でした。長時間の session が、ある repository から sibling repository へ切り替わる場合、これは monorepo や multi-service work でよくありますが、/cd は高コストな cached prefix を維持したまま、filesystem context だけを差し替えます。

Strategy 3: Session Handoffs

複数 sessions にまたがる task では、全体の state を記録する handoff documents を作成します。

## 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 構造により、次の session は最小限の token cost で完全な context を受け取れます。claude -c（continue）で新しい session を始めるか、handoff document を読むだけで、そのまま implementation に進めます。¹⁵

Strategy 4: Fresh-Context Iteration（The Ralph Loop）

60〜90分を超える sessions では、iteration ごとに新しい Claude instance を起動します。state は conversational memory ではなく、ファイルシステムを通じて保持されます。各 iteration は context budget を丸ごと使えます。¹⁶

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

単一の長い session と比較します。

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

iteration ごとに fresh context を使う approach では、orient step（state files の読み込み、git history の scan）に15〜20%の overhead がかかる代わりに、各 iteration で認知リソースを完全に使えます。¹⁶ cost-benefit の計算はこうです。60分未満の sessions では、単一の conversation のほうが効率的です。90分を超えると、overhead があっても fresh-context のほうが高品質な output を生みます。

Strategy 5: Managed Memory Curation（Dreaming）

Anthropic の Claude Managed Agents は、2026年5月6日に Dreaming を Research Preview として追加しました。³⁵ Anthropic によると、「Dreaming is a scheduled process that reviews your agent sessions and memory stores, extracts patterns, and curates memories so your agents improve over time.」です。³⁵

Dreaming は sessions の間に background で実行され、critical path には入りません。これは filesystem-as-memory pattern を置き換えるのではなく、補完します。MEMORY.md ファイルは引き続き load-bearing surface です。Dreaming は curated memory entries を Managed Agents memory store に書き込み、agent は session 開始時にそれを読みます。self-hosted filesystem state と managed-side curation を組み合わせる harnesses では、この2つの patterns が共存します。

Dreaming は Research Preview のため、behavior は変わる可能性があります。上で説明した session-handoffs と CLAUDE.md patterns は、self-hosted harnesses における authoritative memory mechanism であり続けます。

Anti-Patterns

10行だけ必要なのにファイル全体を読む。 2,000行のファイルを1つ読むだけで、15,000〜20,000 tokens を消費します。line offsets を使ってください。Read file.py offset=100 limit=20 により、そのコストの大部分を節約できます。¹⁵

verbose error output を context に残し続ける。 bug を debug した後、context には失敗した iterations からの40件以上の stack traces が残ります。bug 修正後に一度 /compact するだけで、その無駄な重みを解放できます。

毎回の session を、すべてのファイルを読むことから始める。 Claude Code の glob と grep tools に、必要に応じて relevant files を見つけさせてください。不要な pre-loading による100,000+ tokens を節約できます。¹⁵

Subagent Patterns

Subagentsは、複雑なタスクを独立して処理する特化型のClaudeインスタンスです。クリーンなcontext（メイン会話からの汚染なし）で開始し、指定されたツールで動作し、結果を要約として返します。探索結果でメイン会話が肥大化することはなく、戻ってくるのは結論だけです。⁵

組み込みSubagentタイプ

Custom Subagentsの作成

.claude/agents/（project）または~/.claude/agents/（personal）で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 worktrees内で動作でき、リポジトリの完全に分離されたコピーを提供します。⁵

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

codebaseを壊す可能性がある実験的な作業では、worktree分離が不可欠です。

並列Subagents

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

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

各agentはそれぞれ独自のcontext windowで実行され、関連コードを見つけ、要約を返します。メインcontextはクリーンなままです。

Recursion Guard

spawn制限がないと、agentsがagentsへ委任し、そのagentsがさらにagentsへ委任していきます。そのたびにcontextが失われ、tokensが消費されます。recursion guardパターンは予算を強制します。¹⁶

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

重要な教訓: 深さ制限だけでなく、spawn予算を使ってください。深さベースの制限は親子チェーンを追跡します（depth 3でブロック）が、幅を見落とします。depth 1に23 agentsがいても、それはまだ「depth 1」です。spawn予算は、親ごとのアクティブな子の総数を追跡し、設定可能な最大値で上限をかけます。この予算モデルは、代理指標（ネストレベルが多すぎる）ではなく、実際の故障モード（agentsの総数が多すぎる）に対応しています。⁷

再帰的委任は、今ではfirst-partyの深さになっています。 Claude Code v2.1.172（2026年6月10日）時点で、sub-agentsは自分自身のsub-agentsをspawnでき、最大5レベルまでネストできます。以前は委任は実質的に1レベルでした。⁶² これにより、上記のrecursion guardの重要性は下がるどころか高まります。platformが、contextとtokensを消費するagents-delegating-to-agentsのチェーンをまさに許可するようになったため、spawn予算とdepth capこそが、5レベルのツリーが数百のアクティブagentsへ広がるのを防ぐ仕組みです。5レベルはplatformが許す上限であり、目指すdefaultではないと考えてください。

Auto modeはlaunch前にspawnsを審査するようになりました。 Claude Code v2.1.178では、対応するgovernance gapが解消されました。auto modeでは、subagentがlaunchされた後に行動を取り始めてからではなく、launch前にpermission classifierによってsubagent spawnsが評価されます。⁶³ 以前は、親sessionではブロックされるはずのactionを要求するためにsubagentをspawnできました。spawn自体がbypassになっていたのです。spawn時点で審査されるようになったことで、recursion guardとpermission modelがようやく接続されました。childを、policyが禁じるactionのロンダリング手段として使うことはできません。

Agent Teams（Research Preview）

Agent Teamsは、独立して作業する複数のClaude Codeインスタンスを調整し、共有mailboxとtask listを介して通信し、互いの発見に異議を唱えることもできます。⁵

有効化: 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 sessionsを1つの画面で表示します。⁴²⁴³ 公式docsでは、多数のsessionsをdispatchして管理し、各sessionが何をしているかを確認し、operator inputが必要なものを特定する方法として説明されています。⁴³ これにより、multi-agent作業には、最終要約だけでは得られないoperations viewが加わります。

subagentまたはteamパターンを昇格させるときは、Agent Viewを使ってください。どのsessionsがブロックされているか、どれがまだ実行中か、作業分配が意図したarchitectureに合っているかを確認します。ただし、品質の証明として扱ってはいけません。これはobservabilityです。作業がsoundかどうかは、tests、review gates、evidence reportsが引き続き判断します。

同じreleaseでは/goalも追加されました。これは完了条件を設定し、その条件が満たされるまでClaudeをturnをまたいで継続させます。interactive、-p、Remote Controlでの利用も含まれます。⁴² /goalは、deterministic gatesの代替ではなく、session-scoped completion loopとして扱ってください。agentをtargetに集中させ続けるには便利ですが、tests、citation checks、deploy checks、security hooksなど、failureがblockしなければならないものは、commandまたはscript backedのままにするべきです。

Workflow Tool（v2.1.147+）

Claude Code v2.1.147では、defaultではoffのWorkflowツールが追加され、deterministic multi-agent orchestrationに使えます。CLAUDE_CODE_WORKFLOWS=1で有効化します。⁵² architecture上これが重要なのは、以前はcustom dispatch scripts、mailbox state、subagent coordination conventionsが必要だったflowsに対して、Claude Codeにfirst-party orchestration primitiveを与えるためです。

その周囲のharnessを削除してはいけません。Workflowは実行を構造化できますが、safety modelを置き換えるものではありません。PreToolUseとPostToolUse hooksはblocking layerとして維持し、runaway widthを防ぐためにspawn budgetsまたはworkflow step budgetsを維持し、filesystem stateを監査可能に保ち、最終的なevidence reportsはmodelの自己評価の外側に置いてください。実務では、orchestration shapeにはWorkflowを使い、truthにはhooks、tests、review gatesを使います。

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

シングルエージェントの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 の運用ポリシーです。²¹ agent に、なぜ conventional commits を使うのかを理解させる必要はありません。必要なのは、実行すべき正確なコマンドと、「完了」がどう見えるかです。

優先順位の階層

Rules ファイルは自動的に読み込まれ、CLAUDE.md を散らかさずに構造化されたコンテキストを提供します。⁶

無視されるもの

以下のパターンは、agent の挙動に観測可能な変化をほぼ生みません。²¹

コマンドのない prose 段落。 「クリーンで十分にテストされたコードを重視します」はドキュメントであって、運用指示ではありません。agent はそれを読んだうえで、実行可能な指示がないため、テストなしでコードを書き進めます。

曖昧な指示。 「データベース migration には注意する」は制約ではありません。「migration を適用する前に alembic check を実行する。downgrade path がない場合は中止する。」であれば制約になります。

矛盾する優先順位。 「素早く進めて迅速に出荷する」に加えて、「包括的な test coverage を確保する」「runtime は 5 分未満に保つ」「すべての commit 前に full integration tests を実行する」。agent はこの 4 つを同時に満たせないため、デフォルトで verification を省略します。²¹

強制手段のない style guides。 ruff check --select D なしで「Google Python Style Guide に従う」と書いても、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/`

Escalation rules:

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

書く順序

ゼロから始める場合は、次の優先順位でセクションを追加します。²¹

1. Build と test のコマンド（agent が有用な作業をするには、まずこれが必要です）
2. Definition of done（誤った完了報告を防ぎます）
3. Escalation rules（破壊的な回避策を防ぎます）
4. タスク別に整理されたセクション（無関係な指示の解析を減らします）
5. Directory scoping（monorepo では、service ごとの指示を分離できます）

最初の 4 つが機能するまでは、style preferences は後回しにしてください。

File Imports

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

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

Import 構文は、relative（@docs/file.md）、absolute（@/absolute/path.md）、home directory（@~/.claude/file.md）です。最大深度は 5 レベルの imports です。⁶

Cross-Tool Instruction Compatibility

AGENTS.md は、主要な AI coding tool すべてに認識されるオープン標準です。²¹ チームで複数のツールを使う場合は、AGENTS.md を canonical source として書き、関連セクションをツール固有のファイルへ mirror します。

AGENTS.md のパターン（command-first、closure-defined、task-organized）は、ツールに関係なくどの instruction file でも機能します。乖離していく並列の instruction set を保守しないでください。信頼できる source を 1 つ書き、それを mirror します。

Codex Parity Notes

Codex には現在、主要な harness layer に対応する first-class equivalent があります。ただし migration は file copy ではなく、pattern translation です。Codex は作業開始前に AGENTS.md を読み込み、~/.codex からの global guidance に、project と nested repository の instructions を重ねます。³¹ Codex skills は progressive disclosure を備えた同じ SKILL.md mental model を使います。Codex はまず skill name、description、file path から始め、使うと判断したときだけ full skill を読み込みます。³² Codex には native hooks、plugin-bundled hooks、managed hooks、MCP support、明示的な subagent workflows もあります。³³³⁴

Codex v0.138.0–v0.139.0 では、非 trivial な workspace 向けに AGENTS.md discovery が強化されました。読み込みは environment の filesystem abstraction 経由になり、discovery walk 中に logical paths が保持されます。そのため、workspace が remote filesystem や symlinked tree であっても、正しいファイルが選択されます。⁶¹ これは、canonical な AGENTS.md が authoritative source であり、agent が mounted、container-materialized、または symlinked checkout 上で動作する場合に重要です。naive な path walk では、誤った instruction file を黙って選ぶか、何も選ばない可能性があるためです。1 つの authoritative な AGENTS.md を services 全体に mirror するなら、agent が実際に読み込んだファイルが自分の書いたものだと信頼するための下限として扱ってください。

Codex v0.141.0 では、remote-execution path 自体も強化されました。remote executors は authenticated かつ end-to-end encrypted な Noise-relay channels 経由で接続するようになり（control plane と executor は、その間の relay を信頼しなくなりました）、cross-platform remote execution は executor の native working directory と shell を保持し、TLS は enterprise proxies 向けに P-521 certificate signatures を受け入れます。⁶⁵ orchestration が network boundary を越えて Codex executors を動かす場合、これは trusted-relay assumption と end-to-end-encrypted assumption の違いです。remote-executor topology の baseline として扱ってください。

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

重要な違いは、Claude subagents は descriptions から自動選択され得る一方、Codex は現在 subagent workflows を明示的なものとして文書化している点です。そのため Codex で常時有効な harness behavior には、skills と hooks をデフォルトにするのが適しています。subagents は、意図的な parallel work、review、exploration のためのものです。

Instructions をテストする

agent が実際に instructions を読み、従っているかを検証します。

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

Acid test: agent に build commands を説明させてください。逐語的に再現できない場合、instructions が冗長すぎる（content が context から押し出されている）、曖昧すぎる（agent が実行可能な instructions を抽出できない）、または discovery されていない、のいずれかです。GitHub による 2,500 repositories の分析では、失敗の多くは曖昧さが原因だとされています。²¹

本番環境のパターン

Opus 4.7 の長期タスクパターン（2026年4月）

Claude Opus 4.7（2026年4月16日）には、harness が防御すべき対象を変える具体的な機能が搭載されました:²⁹

• ツール失敗への耐性: Opus 4.7 は、Opus 4.6 のセッションを停止させていたツール失敗があっても処理を継続します。subagent code の防御的な retry wrapper は減らせますが、完全にはなくせません。hook レベルのガードは残し、プロンプト内の「ツールが失敗したら3回再試行する」といった scaffolding は削減しましょう。
• xhigh effort tier（Opus-4.7 のみ）: high と max の中間に位置します。coding と agentic workload の推奨デフォルトです。長時間動作する subagents では、xhigh は high を明確に上回り、token cost の増加も比例未満に収まります。単発の難しい推論には引き続き max が適していますが、継続的なタスクには xhigh のほうが向いています。
• Token-budget ceiling: agent run ごとに output_config.task_budget（beta header task-budgets-2026-03-13）で設定できます。モデルには進行中の countdown が見えるため、突然 token が尽きるのではなく、budget に合わせて作業範囲を自然に調整します。短いプロンプトで品質を犠牲にせず、agentic loop の token spend を予測可能にしたい場合に使います。
• Implicit-need awareness: 「implicit-need」テストに合格した最初の Claude model です。つまり、ユーザーの文字どおりの依頼だけでは実際のニーズが十分に指定されていない場合でも、それを認識できます。これにより、CLAUDE.md の「clarifying rules」セクションの必要性は下がります。CLAUDE.md が「ユーザーが Y を依頼したら X も考慮する」といった guardrails で200行あるなら、すでに native にカバーされるものは整理しましょう。

Worktree Base、Sandbox Paths、Admin Settings（2026年5月7日）

Claude Code v2.1.133 では、本番環境の harness で知っておく価値のある admin-tier settings が4つ追加されました:³⁹

ユーザーに注意喚起すべきなのは worktree.baseRef の revert です。v2.1.128〜v2.1.132 の挙動（worktrees がローカル HEAD から分岐すること）に依存していた agents は、明示的に opt back in しない限り、新しい worktrees で未 push の作業にアクセスできなくなります。

Enterprise Observability 向け OTel Feedback Survey（2026年5月8日）

Claude Code v2.1.136 では、OpenTelemetry 経由で回答を取得する enterprise 向けに、セッション内の品質 survey を再度有効化する CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL が追加されました。⁴⁰ 組織が OTel events を中央の observability stack に送っている場合、この env var により survey が data path に戻り、latency や error metrics と同じ pipeline で品質シグナルが流れます。これは opt-in として扱ってください。デフォルトでは survey が抑制されており、非 OTel deployments ではそれが正しい挙動です。

品質ループ

すべての非自明な変更に必須の review process です。

1. Implement - code を書く
2. Review - すべての行を読み直します。typo、logic errors、不明瞭な箇所を見つけます
3. Evaluate - evidence gate を実行します。patterns、edge cases、test coverage を確認します
4. Refine - すべての issue を修正します。「後で」に先送りしません
5. Zoom Out - integration points、imports、adjacent code に regressions がないか確認します
6. Repeat - evidence gate criterion が1つでも失敗したら、step 4 に戻ります
7. Report - 何を変更したか、どう検証したかを列挙し、具体的な evidence を引用します

Evidence Gate

「そう思う」「そうなるはず」は evidence ではありません。file paths、test output、specific code を引用します。

どの行についても evidence を出せない場合は、Refine に戻ります。²²

人間によるマージ権限

2026年5月の arXiv study は、29,585 件の AI-agent pull-request lifecycle を分析し、operational agency と merge governance を分けて考えています。⁴⁷ そこから得られる有用な architecture lesson はシンプルです。agents は作業を開始し、branches を進め、PRs を開き、work を review し、risk を要約できます。一方で、merge authority は別の governance boundary として残します。

この boundary は harness で明示してください。agents には PRs の準備と evidence の収集を任せます。merge、release、destructive repository operations には、人間の承認を必須にします。ただし、組織が別途 audited automation policy を持っている場合は例外です。automation が merge を実行する場合は、executor と、それを承認した人間または policy を区別できる logs を残してください。

Error Handling Patterns

Atomic file writes。 複数の agents が同じ state file に同時に書き込むと、JSON が破損します。.tmp files に書き込み、その後 mv で atomic に移動します。同一 filesystem 上では、OS が mv の atomic 性を保証します。¹⁷

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

State corruption recovery。 state が破損した場合、recovery pattern では crash するのではなく、安全な defaults から再作成します:¹⁶

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 trap。 ((VAR++)) は、VAR が 0 のときに exit code 1 を返します。0++ は 0 に評価され、bash が false と扱うためです。set -e が有効だと、これで script が終了します。代わりに VAR=$((VAR + 1)) を使ってください。¹⁶

Blast Radius Classification

すべての agent action を blast radius で分類し、それに応じて gate を設定します:²

Remote Control（任意の browser や mobile app からローカルの Claude Code に接続する機能）により、「External」gate は blocking wait ではなく async notification になります。前の task をスマートフォンで review している間も、agent は次の task に取り組み続けます。²

自律実行のための Task Specification

効果的な autonomous tasks には、objective、completion criteria、context pointers の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

Criteria は machine-verifiable である必要があります。test pass/fail、linter output、HTTP status codes、file existence checks などです。初期の task で agent に「pass する tests を書く」と依頼したところ、assert True と assert 1 == 1 が生成されました。技術的には正しいですが、実用上は無価値です。¹⁶

注意すべき Failure Modes

具体的な Session Trace

5つの stories を持つ PRD を処理する autonomous run の session trace です:²

1. SessionStart fires。 Dispatcher が current date、project detection、philosophy constraints、cost tracking initialization を注入します。5つの hooks、合計180ms です。

2. Agent が PRD を読み、最初の story を計画します。 UserPromptSubmit が fire します。Dispatcher は active project context と session drift baseline を注入します。

3. Agent が tests を実行するために Bash を呼びます。 PreToolUse:Bash が fire します。Credentials check、sandbox validation、project detection。90ms。Tests が実行されます。PostToolUse:Bash が fire し、activity heartbeat が log され、drift check が行われます。

4. Agent が file を作成するために Write を呼びます。 PreToolUse:Write が fire し、file scope check が行われます。PostToolUse:Write が fire し、lint check と commit tracking が行われます。

5. Agent が story を終えます。 Stop が fire します。Quality gate が確認します。agent は evidence を引用したか。Hedging language はあるか。diff に TODO comments はあるか。check が1つでも失敗すると exit 2 となり、agent は続行します。

6. Independent verification: fresh agent が、前の agent の self-report を信頼せずに test suite を実行します。

7. 3つの code review agents が並列に spawn します。 それぞれが diff を独立して review します。reviewer のいずれかが CRITICAL を指摘した場合、story は queue に戻ります。

8. Story が pass し、次の story が load されます。 この cycle が5つすべての stories で繰り返されます。

5つの stories 全体で fire した hooks の総数は約340。hooks にかかった総時間は約12秒です。この overhead により、1回の overnight run で3件の credential leaks、1件の destructive command、2件の incomplete implementations を防ぎました。

Case Study: Overnight PRD Processing

本番環境の harness は、8回の overnight sessions で12件の PRDs（47 stories）を処理しました。Metrics は、最初の4件の PRDs（minimal harness: CLAUDE.md のみ）と、最後の8件（full harness: hooks、skills、quality gates、multi-agent review）を比較しています。

2件の credential leaks では、API keys の rotation と downstream services の audit が必要になり、incident response におよそ4時間かかりました。同等の事態を防いだ harness overhead は、story あたり2.4秒の bash でした。false completion rate が35%から4%に下がったのは、agent に完了報告を許可する前に Stop hook が独立して tests を実行したためです。

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

信頼できる Agent の5原則（Anthropic、2026年4月）

Anthropic は、2026年4月9日に Agent の信頼性に関する正式なフレームワークを公開しました。²⁷ 5つの原則は、このガイドの Evidence Gate の考え方と対応しつつ、それを拡張するものです。

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

Skill sandbox tooling: skills を攻撃対象領域として扱うチーム向けに、Permiso の SandyClaw（2026年4月2日ローンチ）は専用 sandbox 内で skills を実行し、Sigma/YARA/Nova/Snort 検出に基づく evidence-backed verdicts を提供します。skill-sandbox カテゴリー初の製品です。²⁸

Sandbox

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

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

OpenAI Agents SDK sandbox lockdown（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（manifest 適用時の SDK プロセスの現在の作業ディレクトリ）内に制約されるようになりました。⁴¹ 相対ローカルソースは base_dir から解決されます。絶対パスは、すでにその内側にあるか、grant を持っている必要があります。これにより、ローカルアーティファクト境界の問題が閉じられます。以前のバージョンでは、manifest が任意のホストパスを sandbox workspace に取り込めました。移行方法: 読み取り専用マウントには、manifest レベルで SandboxPathGrant(path=..., read_only=True) を使い、信頼済みホストルートを宣言してください。extra_path_grants は信頼済みアプリケーション設定として扱い、モデル出力や信頼できない manifest 入力から grant を生成してはいけません。

OpenAI Agents SDK follow-up floor（v0.17.3）。 0.17.1〜0.17.3 系では、sandbox とセッションの堅牢化がさらに追加されました。アーカイブ展開制限、GitRepo サブパス検証、より明確な sandbox-provider エラー、sandbox コマンドからの mountpoint credentials 排除、相対 sandbox workspace ルートの拒否、Vercel-sandbox terminal-state 処理です。⁵⁴ Claude Code hooks だけでなく OpenAI-hosted または provider-backed sandboxes を使っている場合、このセクションのパターンでは 0.17.3 を現在の下限として扱ってください。

権限境界

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

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

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

付随する管理設定 enforceAvailableModels（v2.1.175）は、モデル選択を上位から制約します。Default model を固定し、ユーザーまたはプロジェクトスコープの設定が管理対象の availableModels allowlist を広げるのを防ぎます。⁶³ この2つは組み合わせて使えます。allowlist はセッションに存在できる階層を定義し、パラメータレベルのルールは subagents がそこからどう選ぶかを制約します。

Auto-Mode の破壊的コマンド Guardrails（2026年6月）

Claude Code v2.1.183 では、作業を静かに失わせたり環境を破壊したりする操作について、auto mode の影響範囲が狭められました。auto mode は現在、セッション内で明示的に依頼されていない限り、破壊的な git 操作（git reset --hard、git checkout -- .、git clean -fd、git stash drop）、そのセッションで Agent が作成していない commit に対する git commit --amend、そして特定の stack を名指ししていない infrastructure teardown（terraform destroy、pulumi destroy、cdk destroy）を hard-block します。⁶⁵ アーキテクチャ上、これは上の spawn-vetting とパラメータレベルルールを補完するものです。どのツールか、またはどう起動されるかをゲートするのではなく、意図に基づいて少数の具体的で不可逆なコマンドをゲートします。Agent はそれらを実行できますが、自発的にではなく、明示的な指示がある場合だけです。自律型 harness では、同じ原則を自前の PreToolUse hooks にエンコードしてください。状態を破壊するコマンドには、明示的なオペレーターシグナルがある場合にだけ解除される deny-by-default ルールが必要です。

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

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 isolation は影響範囲を制限します。permissionMode: plan の subagent は、プロンプトが侵害されても変更を加えられません。

Agent Logs と Guardrails はセキュリティ表面です

2026年5月の2つの勧告は、あるパターンを補強しています。Agent infrastructure は、機密コンテンツや実行可能ポリシーが漏えいまたは脱出する新しい場所を作ります。GitHub Advisory GHSA-f3jg-756w-gm35 は、Gryph Agents の payload-filter 問題を扱っています。デフォルトの logging 動作では、機密性の高い tool-payload コンテンツがローカル SQLite ログに残る可能性がありました。⁴⁵ OSV GHSA-wxxx-gvqv-xp7p は、LiteLLM の custom-code guardrail が admin-protected proxy endpoint で sandbox escape する問題を扱っています。⁴⁶

本番運用のルールはこうです。agent transcripts、tool payloads、SQLite logs、guardrail execution は機密 infrastructure として扱ってください。永続化前に redact し、保持期間を制限し、custom guardrail code は sandbox 化してレビュー可能に保ちます。プロンプトレベルの「シークレットをログに記録しない」というルールだけでは不十分です。logging と guardrail の経路には、決定論的なテストが必要です。

Hook Security

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

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

人間と Agent の責任分界

Agent アーキテクチャのセキュリティには、人間と Agent の責任を明確に分けることが必要です。¹⁷

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

再帰的な Hook Enforcement

Hooks は subagent の行動にも発火します。¹³ Claude が Agent tool を介して subagent を起動すると、その subagent が使うすべてのツールに対して PreToolUse と PostToolUse hooks が実行されます。再帰的な hook enforcement がなければ、subagent は安全ゲートを迂回できてしまいます。SubagentStop イベントを使うと、subagent 完了時にクリーンアップや検証を実行できます。

これは任意ではありません。セキュリティ hooks なしで subagent を起動する Agent は、main に force-push したり、認証情報ファイルを読んだり、破壊的コマンドを実行したりできます。その間、ゲートはメイン会話が何もしていないのを見ているだけになります。

コストをアーキテクチャとして扱う

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

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

Agent level。 長い会話よりも新規 spawn を使います。自律実行の各 story には、クリーンなコンテキストを持つ新しい Agent を割り当てます。各 Agent が新しく始まるため、コンテキストは膨れ上がりません。memory ではなく briefing を使います。モデルは、30ステップ分の蓄積されたコンテキストをたどるよりも、明確な briefing をうまく実行します。

Architecture level。 操作が stateless なら、MCP より CLI-first です。ワンショット評価の claude --print 呼び出しはコストが低く、接続オーバーヘッドも追加しません。MCP が理にかなうのは、ツールが永続状態または streaming を必要とする場合です。

判断フレームワーク

各仕組みを使うタイミング:

Skills vs Hooks vs Subagents

FAQ

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

制約になるのは数ではなくパフォーマンスです。各 hook は同期的に実行されるため、hook の合計実行時間が、マッチしたすべての tool call に加算されます。各 hook が 200ms 未満で完了するなら、user-level と project-level の設定を合わせて 95 個の hooks があっても、目立つ遅延なく動作します。注視すべきしきい値は、PostToolUse hook がすべてのファイル編集に 500ms を超える遅延を追加する場合です。その場合、セッションが重く感じられます。デプロイ前に time で hooks をプロファイルしてください。¹⁴

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

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

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

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

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

いいえ。confidence module は、曖昧さ、複雑さ、影響度、コンテキスト依存性という 4 つの観点で決定をスコアリングします。全体の信頼度が 0.70 未満の決定だけが deliberation をトリガーし、これは全体の決定のおよそ 10% です。ドキュメント修正、変数名変更、定型的な編集では deliberation は完全にスキップされます。セキュリティアーキテクチャ、データベーススキーマ変更、取り消せないデプロイでは一貫してトリガーされます。⁷

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

成功パスと失敗パスの両方をテストします。成功とは、agents が建設的に意見を分け、合意に到達することです。失敗とは、agents が早すぎる収束をする、まったく収束しない、または spawn 予算を超えることです。End-to-end tests では、決定的な agent responses を使って各シナリオをシミュレートし、両方の validation gates が文書化されたすべての failure mode を検出することを確認します。本番の 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 hook と pride check hook は、それぞれ 200ms 未満で実行されます。主なボトルネックは orchestration overhead ではなく、agent ごとの LLM inference time です。⁷

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

各セクションは 50 行未満、ファイル全体は 150 行未満に抑えてください。長いファイルはコンテキストウィンドウで切り詰められるため、最も重要な指示を先頭に置きます。style preferences より前に、commands と closure definitions を配置してください。²¹

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

アーキテクチャ上の原則（決定的な gate としての hooks、ドメイン知識としての skills、分離コンテキストとしての subagents、memory としての filesystem）は、概念的にはどの agentic system にも適用できます。具体的な実装では、Claude Code の lifecycle events、matcher patterns、Agent tool を使っています。AGENTS.md は同じパターンを Codex、Cursor、Copilot、Amp、Windsurf に持ち込みます。²¹ 実装の詳細が tool-specific であっても、harness pattern 自体は tool-agnostic です。

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

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

Key Commands

File Locations

変更履歴

参照