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

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

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

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

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

主要なポイント

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

本ガイドの使い方

各セクションは前のセクションの上に構築されています。末尾の意思決定フレームワークでは、問題の種類ごとに適切なメカニズムを選択するための早見表を提供しています。

エージェントアーキテクチャが重要な理由

Simon Willisonは、現在の状況を一つの観察に集約しています。コードを書くコストは今や安い、と。⁸ その通りです。しかし、その帰結として、検証こそが今や高コストな部分となっています。検証インフラなしに安価なコードを量産すれば、バグも大量に生まれます。投資対効果が高いのは、より良いプロンプトではありません。モデルが見落とすものを捕捉する、モデルを取り巻くシステムこそが重要なのです。

エージェントアーキテクチャを必要とする3つの力があります。

コンテキストウィンドウは有限であり、情報が失われます。ファイルの読み取り、ツール出力、会話のやり取り——すべてがトークンを消費します。Microsoft ResearchとSalesforceが15のLLMを対象に200,000件以上のシミュレーション会話でテストした結果、シングルターンからマルチターンへの移行で平均39%のパフォーマンス低下が確認されました。⁹ この劣化はわずか2ターンで始まり、予測可能な曲線を描きます。最初の30分間では正確なマルチファイル編集ができていたものが、90分後にはシングルファイルへのトンネルビジョンに退化するのです。コンテキストウィンドウを長くしても、この問題は解決しません。同じ研究の「Concat」条件（会話全体を単一プロンプトとして入力）では、同一の内容でシングルターン性能の95.1%を達成しました。劣化の原因はトークン数の制限ではなく、ターンの境界にあるのです。

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

単一の視点では多次元的な問題を見逃します。ある単一のエージェントがAPIエンドポイントをレビューし、認証の確認、入力サニタイズの検証、CORSヘッダーの検証を行いました。問題なしという結果でした。ところが、ペネトレーションテスターとして別途プロンプトされた2番目のエージェントは、そのエンドポイントが無制限のクエリパラメータを受け付けており、データベースクエリの増幅によるサービス拒否攻撃を引き起こす可能性があることを発見しました。⁷ 最初のエージェントはチェックしませんでした。その評価フレームワークにおいて、クエリの複雑性がセキュリティの攻撃面として扱われていなかったからです。この欠落は構造的なものであり、プロンプトエンジニアリングをいくら改良しても解決できません。

エージェントアーキテクチャは、これら3つすべてに対処します。Hooksが決定論的な制約を強制し、subagentsがコンテキストの分離を管理し、マルチエージェントオーケストレーションが独立した視点を提供します。これらが一体となってharnessを形成するのです。

Harnessパターン

Harnessはフレームワークではありません。パターンです。AIコーディングエージェントを決定論的なインフラで包む、組み合わせ可能なファイル、スクリプト、規約の集合体です。構成要素を見ていきましょう。

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

命令レイヤー: CLAUDE.mdファイルとrulesディレクトリが、プロジェクトに関するエージェントの知識を定義します。セッション開始時とコンパクション後に自動的に読み込まれ、エージェントの長期的なアーキテクチャメモリとして機能します。

拡張レイヤー: Skillsはコンテキストに基づいて自動的にアクティブになるドメイン専門知識を提供します。Hooksはマッチするツール呼び出しのたびに発動する決定論的なゲートを提供します。Memoryファイルはセッション間で状態を永続化します。カスタムagentsは特化したsubagent設定を提供します。

オーケストレーションレイヤー: マルチエージェントパターンが、リサーチ、レビュー、議論のために独立したエージェントを調整します。スポーン予算が暴走的な再帰を防止し、コンセンサスバリデーションが品質を保証します。

重要な洞察は、ほとんどのユーザーがコアレイヤーだけで作業し、コンテキストの肥大化とコストの増加を眺めているという点です。パワーユーザーは命令レイヤーと拡張レイヤーを設定した上で、コアレイヤーをオーケストレーションと最終判断にのみ使用します。²

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システム

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

Skillを構築すべきとき

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

Skillの作成

Skillsは4つの場所に配置でき、スコープの広い順に並べると以下のようになります。⁴

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

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

# Code Review Expertise

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

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

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

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

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

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

悪いdescriptionの例：

description: Helps with code

効果的なdescriptionの例：

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

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

コンテキストバジェット

すべてのスキルのdescriptionは、コンテキストウィンドウの2%で動的にスケーリングされるコンテキストバジェットを共有しており、フォールバック値は16,000文字です。⁴ スキルが多い場合は、各descriptionを簡潔に保ちましょう。SLASH_COMMAND_TOOL_CHAR_BUDGET環境変数でバジェットをオーバーライドすることも可能ですが、¹¹ より良い対処法はdescriptionをより短く正確にすることです。セッション中に/contextを実行すると、除外されているスキルがないか確認できます。

サポートファイルとディレクトリ構成

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

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

SKILL.md内で相対リンクを使って参照してください。Claudeはスキルがアクティベートされた際にこれらのファイルをオンデマンドで読み込みます。SKILL.mdは500行以内に収め、詳細なリファレンス資料はサポートファイルに移動しましょう。¹²

Gitによるスキルの共有

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

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

チームメイトがpullすると、スキルが自動的に利用可能になります。インストールも設定も不要です。チーム全体で専門知識を標準化する最も効果的な方法といえるでしょう。

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

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

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

各スキルがあなたの専門知識の異なる側面をエンコードしています。これらが組み合わさることで、Claudeがコンテキストに基づいて自動的に参照するナレッジベースが形成されます。ジュニア開発者は、わざわざ依頼しなくてもシニアレベルのガイダンスを受けられるようになるのです。

スキルとhooksの組み合わせ

スキルはフロントマター内に独自のhooksを定義でき、スキルの実行中のみアクティブになります。これにより、他のセッションに影響を与えないドメイン固有の振る舞いを実現できます。²

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

フィロソフィースキルはSessionStart hooksを通じて自動アクティベートし、明示的な呼び出しなしにすべてのセッションに品質制約を注入します。スキル自体がナレッジであり、hooksがその強制メカニズムです。両者が組み合わさることで、ポリシーレイヤーが形成されます。

よくあるスキルの失敗パターン

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

バジェットを奪い合う大量のスキル。 スキルが増えると、2%のコンテキストバジェットをめぐってより多くのdescriptionが競合します。スキルがアクティベートされないことに気づいたら、/contextで除外されているものがないか確認しましょう。曖昧なスキルを多数作るよりも、少数の的確に記述されたスキルを優先すべきです。

重要な情報がサポートファイルに埋もれている。 ClaudeはSKILL.mdを即座に読み込みますが、サポートファイルは必要な時にのみアクセスします。重要な情報がサポートファイルにある場合、Claudeがそれを見つけられない可能性があります。不可欠な情報はSKILL.mdに直接記載してください。⁴

Hook アーキテクチャ

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

利用可能なイベント

Claude Code は6つのカテゴリにわたる22のライフサイクルイベントを公開しています：¹³

終了コードの意味

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

重要： すべてのセキュリティ Hook では exit 2 を使用してください。exit 1 ではありません。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 フィールドはツール名にマッチする正規表現です：Bash、Write、Edit、Read、Glob、Grep、Agent、またはすべてのツールに対応する * を指定できます。UserPromptSubmit のようにツールを伴わないイベントには ""（空文字列）を使用してください。

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 を出力できます：

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

3種類の保証

Hook を書く前に、どの種類の保証が必要か考えましょう：¹⁴

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

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

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

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

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

品質保証は、意思決定のポイントで状態を検証するものです。git commit コマンドに対する PreToolUse Hooks がリンターやテストスイートを実行し、品質チェックに失敗した場合はコミットをブロックします：

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

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

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

Claude Code は3種類の Hook タイプをサポートしています：¹³

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

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

Agent Hooks（type: "agent"）はツールアクセス（Read、Grep、Glob）を持つ subagents を生成し、マルチターンの検証を行います。実際のファイルやテスト出力の検査が必要な場合に使用します：

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

非同期 Hooks

Hooks は実行をブロックせずにバックグラウンドで動作させることもできます。通知やログ記録のような重要度の低い処理には async: true を追加してください：¹³

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

非同期は通知、テレメトリ、バックアップに使用します。フォーマット、バリデーション、次のアクションの前に完了しなければならない処理には絶対に非同期を使用しないでください。

独立した Hooks よりも dispatcher を

同じイベントに対して7つの Hooks がそれぞれ独立して stdin を読み取ると、競合状態が発生します。2つの Hooks が同じ JSON ステートファイルに同時に書き込むと、JSON が切り詰められ、そのファイルを解析する後続のすべての Hooks が壊れます。²

解決策は、イベントごとに1つの dispatcher を用意し、キャッシュされた stdin から Hooks を順次実行することです：

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

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

Hooks のデバッグ

サイレントに失敗する Hooks をデバッグするための5つのテクニック：¹⁴

1. スクリプトを単独でテストする。 サンプルの JSON をパイプで渡します：echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. デバッグ出力には stderr を使用する。 stderr に書き込まれた内容は Claude のコンテキストに表示されます。
3. jq の失敗に注意する。 JSON のパスが間違っていると、エラーなく null が返されます。実際のツール入力に対して jq の式をテストしてください。
4. 終了コードを確認する。 exit 1 を使用している PreToolUse Hook は、動作しているように見えて実際にはまったく強制力がありません。
5. Hooks は高速に保つ。 Hooks は同期的に実行されます。すべての Hooks を2秒以内、理想的には500ミリ秒以内に収めてください。

メモリとコンテキスト

AIとの対話はすべて有限のコンテキストウィンドウ内で行われます。会話が長くなると、新しい内容を収めるために以前のターンが圧縮されますが、この圧縮は非可逆です。ターン3で記録したアーキテクチャ上の決定が、ターン15まで残っているとは限りません。⁹

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

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

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

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

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

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

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

戦略2：プロアクティブなコンパクション

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

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

CLAUDE.mdでのカスタムコンパクション指示：

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

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

複数セッションにまたがるタスクでは、状態全体をキャプチャするハンドオフドキュメントを作成します：

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

Status/Files/Decision/Blocked/Nextの構造により、後続セッションに対して最小限のトークンコストで完全なコンテキストを提供できます。claude -c（続行）で新しいセッションを開始するか、ハンドオフドキュメントを読み込めば、すぐに実装に取りかかれます。¹⁵

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

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

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

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

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

フレッシュコンテキスト反復アプローチでは、オリエントステップ（状態ファイルの読み込み、gitヒストリーのスキャン）に15〜20%のオーバーヘッドが発生しますが、各反復で認知リソースをフルに活用できます。¹⁶ コスト対効果の計算は次のとおりです：60分未満のセッションでは単一の会話のほうが効率的ですが、90分を超えると、オーバーヘッドがあってもフレッシュコンテキストのほうが高品質な出力を生み出します。

アンチパターン

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

冗長なエラー出力をコンテキストに残す。 バグのデバッグ後、コンテキストには失敗した反復からの40以上のスタックトレースが残っています。バグ修正後に/compactを1回実行するだけで、この不要な重荷を解放できます。

毎セッションの開始時にすべてのファイルを読み込む。 Claude Codeのglobやgrepツールに必要なファイルをオンデマンドで見つけさせることで、不要な事前読み込みによる100,000トークン以上を節約できます。¹⁵

Subagentパターン

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

組み込みSubagentタイプ

カスタムSubagentの作成

.claude/agents/（プロジェクト用）または~/.claude/agents/（個人用）にsubagentを定義します：

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

subagentは一時的な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分離は、コードベースを壊す可能性のある実験的な作業に不可欠です。

並列Subagent

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

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

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

再帰ガード

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

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

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

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

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

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

重要な教訓： 深さ制限だけでなく、スポーンバジェットを使用してください。深さベースの制限は親子チェーンを追跡します（深さ3でブロック）が、幅を見逃します。深さ1で23個のエージェントが動いていても「深さ1」のままです。スポーンバジェットは、親ごとのアクティブな子の総数を追跡し、設定可能な上限で制御します。バジェットモデルは、代理指標（ネストレベルの深さ）ではなく、実際の障害モード（エージェントの総数が多すぎる）に対応しています。⁷

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

Agent Teamsは、独立して作業し、共有メールボックスとタスクリストを介して通信し、互いの発見に異議を唱えることができる複数のClaude Codeインスタンスを調整します：⁵

有効化方法：export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Agent Teamsとsubagentsの使い分け：

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

単一エージェントのAIシステムには構造的な盲点があります。自らの仮定に疑問を投げかけることができないのです。⁷ マルチエージェント審議では、意思決定が確定する前に、複数の独立した視点からの評価が強制されます。

最小限の審議構成

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: 独立したエージェントがトピックを調査します。各エージェントには異なるペルソナが割り当てられます（テクニカルアーキテクト、セキュリティアナリスト、パフォーマンスエンジニアなど）。コンテキストの分離により、リサーチ中にエージェント同士が互いの調査結果を見ることはできません。

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. コンセンサスの信頼度：strong（0.85超）またはmoderate（0.70〜0.84）に分類されていること 5. 改善のエビデンス：最終的な信頼度が初期の信頼度を上回っていること

ライフサイクルの異なるポイントに2つの hooks を配置することで、実際に発生する障害パターンに対応できます。即座に検出されるもの（低スコア）と、徐々に顕在化するもの（多様性の欠如、反対意見の文書化漏れ）の両方をカバーします。⁷

なぜ合意は危険なのか

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に分散しました。

定型的な反対意見: エージェントが独自の反論を生成するのではなく、互いの懸念表現をコピーしている状態です。

少数派の視点の欠如: 相反する優先事項を持つペルソナ（セキュリティアナリストとパフォーマンスエンジニアなど）からの全会一致の承認は不自然です。両者がすべてに合意することは稀だからです。

同調性検出器は明白なケース（エージェントの収束が早すぎる審議の約10〜15%）を捕捉します。残りの85〜90%については、コンセンサスゲートとPride Checkゲートが十分なバリデーションを提供します。

審議で機能しなかったもの

自由形式の議論ラウンド。 データベースインデックスの議論で3ラウンドのテキストベースのやり取りを行い、7,500トークンの議論が生成されました。ラウンド1：真の意見の相違。ラウンド2：立場の再表明。ラウンド3：異なる言い回しでの同一の主張。構造化された次元スコアリングが自由形式の議論に取って代わり、ランキング品質を向上させながらコストを60%削減しました。⁷

単一のバリデーションゲート。 最初の実装ではセッション終了時に1つのバリデーション hook を実行していました。あるエージェントが0.52のコンセンサススコア（閾値以下）で審議を完了した後、無関係なタスクを20分間続け、セッション終了時の hook がようやく失敗を検出しました。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エージェントのための運用ポリシーです。²¹ エージェントは、なぜconventional commitsを使うのかを理解する必要はありません。実行すべき正確なコマンドと、「完了」の定義を知る必要があるのです。

優先順位の階層

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

無視されるもの

以下のパターンは、エージェントの動作に観測可能な変化をもたらしません。²¹

コマンドを伴わない散文的な記述。「私たちはクリーンでよくテストされたコードを重視します」はドキュメントであり、運用指示ではありません。エージェントはこれを読んでも、テストを書かないままコードを書き続けます。実行可能な指示がないからです。

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

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

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

機能するもの

コマンドファーストの指示：

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

完了の定義：

## 完了の定義
タスクが完了となるのは、以下のすべてが通過した場合のみです：
1. `ruff check .` が終了コード0で完了
2. `pytest -v` が失敗なしで終了コード0で完了
3. `mypy app/ --strict` が終了コード0で完了
4. 変更されたファイルがステージングおよびコミット済み
5. コミットメッセージが規約フォーマットに準拠：`type(scope): description`

タスク別セクション：

## コードを書くとき
- ファイル変更のたびに `ruff check .` を実行する
- すべての新規関数に型ヒントを追加する

## コードをレビューするとき
- セキュリティ問題をチェック：`bandit -r app/`
- テストカバレッジを確認：`pytest --cov=app --cov-fail-under=80`

## リリース時
- `pyproject.toml` のバージョンを更新
- フルスイートを実行：`pytest -v && ruff check . && mypy app/`

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

## ブロックされたとき
- 3回試行してもテストが失敗する場合：停止し、失敗したテストの完全な出力とともに報告する
- 依存関係が不足している場合：まず `requirements.txt` を確認し、それでも解決しなければ質問する
- 禁止事項：エラー解決のためにファイルを削除する、force pushする、テストをスキップする

記述の優先順位

ゼロから始める場合、以下の優先順位でセクションを追加しましょう：²¹

1. ビルドとテストコマンド（エージェントが何か有用なことをする前に必要）
2. 完了の定義（誤った完了を防止）
3. エスカレーションルール（破壊的な回避策を防止）
4. タスク別セクション（無関係な指示の解析を削減）
5. ディレクトリスコーピング（モノレポ：サービス指示を分離）

最初の4つが機能するまで、スタイルの好みは後回しにしてください。

ファイルインポート

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

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

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

クロスツール指示の互換性

AGENTS.mdは60,000以上のプロジェクトで採用され、すべての主要なAIコーディングツールに認識されているオープンスタンダードです。²¹ チームで複数のツールを使用している場合、AGENTS.mdを正式なソースとして記述し、関連セクションをツール固有のファイルにミラーリングしましょう：

AGENTS.mdのパターン（コマンド優先、クロージャ定義、タスク別整理）は、ツールを問わずどの指示ファイルでも機能します。乖離が生じる並行した指示セットを維持してはいけません。1つの正式なソースを書き、ミラーリングしてください。

指示のテスト

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

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

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

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

プロダクションパターン

Quality Loop

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

1. 実装 — コードを書く
2. レビュー — すべての行を読み直す。タイポ、ロジックエラー、不明瞭な箇所を発見する
3. 評価 — Evidence gateを実行する。パターン、エッジケース、テストカバレッジを確認する
4. 改善 — すべての問題を修正する。「後で」に先送りしない
5. 俯瞰 — 統合ポイント、インポート、隣接コードのリグレッションを確認する
6. 繰り返し — Evidence gateの基準が1つでも不合格なら、ステップ4に戻る
7. 報告 — 変更内容、検証方法を列挙し、具体的な証拠を引用する

Evidence Gate

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

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

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

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

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

状態破損からの復旧。 状態が破損した場合、クラッシュするのではなく、安全なデフォルト値から再作成する復旧パターンを使用します：¹⁶

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

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

影響範囲の分類

すべてのエージェントアクションを影響範囲で分類し、それに応じたゲートを設けましょう：²

Remote Control（任意のブラウザやモバイルアプリからローカルのClaude Codeに接続する機能）を使えば、「外部」ゲートをブロッキング待ちから非同期通知に変えられます。前のタスクをスマートフォンからレビューしている間も、エージェントは次のタスクの作業を続けます。²

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

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

OBJECTIVE: Implement multi-agent deliberation with consensus validation.

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

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

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

注意すべき失敗モード

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

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

1. SessionStartが発火。 Dispatcherが注入：現在の日付、プロジェクト検出、フィロソフィー制約、コスト追跡の初期化。5つのhooks、合計180ms。

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

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

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

5. エージェントがストーリーを完了。 Stopが発火。品質ゲートチェック：エージェントは証拠を引用したか？曖昧な表現はないか？diffにTODOコメントはないか？いずれかのチェックが不合格なら、exit 2でエージェントは作業を続行。

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

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

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

5つのストーリー全体で発火したhooksの合計：約340回。hooks処理の合計時間：約12秒。このオーバーヘッドにより、一晩の実行で3件の認証情報漏洩、1件の破壊的コマンド、2件の不完全な実装が防止されました。

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

サンドボックス

Claude Codeはサンドボックス内で実行され、ネットワークアクセスやファイルシステム操作が制限されます。このサンドボックスにより、モデルが任意のネットワークリクエストを送信したり、プロジェクトディレクトリ外のファイルにアクセスしたりすることを防ぎます。¹³

権限の境界

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

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

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

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

allowed-tools: Read, Grep, Glob

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

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

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

hookのセキュリティ

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

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

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

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

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

再帰的なhook適用

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

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

コストもアーキテクチャである

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

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

エージェントレベル。 長い会話より新規起動が有効です。自律実行における各ストーリーは、クリーンなコンテキストを持つ新しいエージェントで処理されます。各エージェントがゼロから開始するため、コンテキストが膨張することはありません。メモリではなくブリーフィング方式を採用しましょう。モデルは蓄積された30ステップのコンテキストを辿るよりも、明確なブリーフィングの方がはるかに効率的に実行できます。

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

判断フレームワーク

各メカニズムの使い分け：

skills vs hooks vs subagents

FAQ

hooksはいくつまでが適切ですか？

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

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

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

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

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

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

いいえ。信頼度モジュールは4つの次元（曖昧性、複雑性、影響度、コンテキスト依存性）で決定をスコアリングします。全体の信頼度が0.70を下回る決定のみが審議をトリガーし、全決定の約10%に相当します。ドキュメント修正、変数のリネーム、ルーティンな編集は審議を完全にスキップします。セキュリティアーキテクチャ、データベーススキーマの変更、不可逆なデプロイメントでは一貫して審議がトリガーされます。⁷

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

成功パスと失敗パスの両方をテストします。成功：エージェントが生産的に意見を異にし、合意に達する。失敗：エージェントが早期に収束する、合意に達しない、またはスポーン予算を超過する。エンドツーエンドテストでは決定的なエージェント応答を用いて各シナリオをシミュレーションし、検証ゲートがドキュメント化されたすべての失敗モードを検出することを確認します。本番の審議システムでは3つのレイヤーにわたる141のテストが実行されます：48のbash統合テスト、81のPythonユニットテスト、12のエンドツーエンドパイプラインシミュレーションです。⁷

審議のレイテンシへの影響はどの程度ですか？

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

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

各セクションは50行以内、ファイル全体は150行以内に収めてください。長いファイルはコンテキストウィンドウで切り詰められるため、最も重要な指示を先頭に配置しましょう。スタイルの好みよりも、コマンドやクロージャの定義を優先してください。²¹

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

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

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

Hook設定

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

Skillフロントマター

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

Subagent定義

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

Instructions for the subagent.

終了コード

主要コマンド

ファイルの配置場所

変更履歴

参考文献