Claude Code 実践アーキテクチャ — Teams/Subagents で開発を加速する設計パターン

毎日 Claude Code を使っていると、やがて「単一セッションの壁」に突き当たる。複雑なリファクタリングの途中でコンテキストが劣化し、以前の判断と矛盾した提案が出始める。大規模な並列タスクを投げると、会話が重くなって推論の精度が下がる。このボトルネックを突き破るのが、Subagents と Agent Teams を活用したマルチエージェント設計だ。

本記事は Claude Code の基本操作を毎日使いこなしているエンジニア向けに、「なぜその設計が有効か」という根拠と「どう設計すべきか」という実践論を一気に解説する。

1. なぜマルチエージェント設計が必要か — 単一セッションの限界

コンテキスト劣化の科学的根拠

Addy Osmani は自身のブログでこう述べた。

“LLMs perform worse as context expands”

これは単なるトークン制限の問題ではない。コンテキストウィンドウに無関係な情報が蓄積すると、モデルの「注意力」が分散し、推論品質そのものが低下する現象だ。長いセッションで Claude が「以前の決定と矛盾した提案」をしてくるのは、このメカニズムによる。

Anthropic のマルチエージェント研究でも同様の知見が得られている。単一の Opus 4 セッションと比較して、Opus 4 がリードし Sonnet 4 がサブエージェントを担当する構成では、90.2% のパフォーマンス向上が確認された。注目すべきは「上位モデルへのアップグレード」よりも「マルチエージェント構成への変更」の方が改善効果が大きかったという点だ。

同研究では、トークン使用量・ツール呼び出し数・モデル選択の3要素がパフォーマンス分散の95%を説明することも判明している。つまり、単一セッションに何でも押し込む設計は、この3要素をすべて悪化させる。

マルチエージェントで何が変わるか

【単一セッション】
  全コンテキスト（探索・実装・テスト・デバッグ）が1つのウィンドウに蓄積
  → コンテキスト後半では推論品質が劣化

【マルチエージェント設計】
  各エージェントが「自分の担当領域」のみに集中
  → 各ウィンドウが常に最適な状態を維持

2026年2月にリリースされた Agent Teams 機能は、この設計思想を実装レベルで実現した。複数の Claude Code インスタンスが独立したコンテキストウィンドウを持ち、共有タスクリストとメールボックスで協調動作する。

2. Star Topology — Leader/Advisor/Teammate 3層アーキテクチャ

設計思想

Agent Teams の最も重要な設計判断は「情報フローの形状」だ。全エージェントがフラットに通信する Mesh Topology ではなく、Star Topology — すべての通信が Leader を経由する構成 — を採用することで、情報の矛盾と散逸を防止する。

Team Leader (Opus)
    ↕ 仕様照会・蒸留情報受け取り
Advisor (Sonnet) ── 仕様書・コードベースを読解・蒸留
    ↓
Teammates (Sonnet × N) ── 実装に専念

Leader は情報の集積地点ではなく、情報の交差点として機能する。何を保持し、何を捨てるかの設計が、チーム全体のパフォーマンスを決定する。

Leader がやること / やらないこと

Leader がやること	Leader がやらないこと
タスク分解・依存関係管理	直接のコード実装
品質検証（テスト実行・型チェック）	仕様書の直接参照
Teammate へのフィードバック	コードベースの全体把握
進捗管理・ボトルネック検出	Teammate 間の直接調整の許可

これが Star Topology の「逆説的な強さ」を生む。Leader が仕様書を読まないことで、Leader のコンテキストウィンドウは進行管理と品質検証に完全に集中できる。

Advisor 層 — 情報の蒸留専門家

Advisor の役割を一言で言えば「情報の蒸留専門家」だ。大量の仕様書やコードベースを読み込み、Leader が必要とする構造化情報だけを抽出して返す。

Leader: 「T04 の実装に必要な仕様を教えて。型定義・DoD を含めて」
          ↓
Advisor: spec/ を読み → 蒸留した構造化情報を Leader に返す
          ↓
Leader: Advisor の返答を Teammate へのメッセージに転記

Advisor の制約: 読み取り専用。ファイルの書き込み・編集は一切行わない。Advisor が書き込み権限を持つと、情報フローの一貫性が崩れる。

Teammate の動作原則

Teammate の設計で最も重要なのは「仕様書を読まない」という原則だ。これは直感に反するが、理由は明確だ。

Teammate が仕様書を直接読むと、仕様の解釈が Teammate ごとにばらつく。Leader が Advisor から得た蒸留情報を Teammate へのメッセージに直接記述することで、全 Teammate が同じ解釈の上で実装を進められる。

実装時の Teammate の行動原則:

Leader の指示内容のみで実装する（指示にない追加機能は不要）
曖昧な点は自己判断せず Leader に確認を求める
完了報告には変更ファイル・テスト結果・型チェック結果・未解決課題を含める
spec/ 配下のファイルは読まない（Leader が必要情報を伝達する）

情報フロー制約

【許可される通信】
  Leader  ↔ Advisor  : 仕様照会・蒸留情報の受け取り
  Leader  → Teammate : 実装指示・フィードバック
  Teammate → Leader  : 完了報告・質問

【禁止される通信】
  Teammate → Teammate : 直接メッセージ（Leader 経由のみ）
  Teammate → Advisor  : 直接メッセージ（Leader 経由のみ）
  Leader   → spec/    : ファイル直接読み込み（Advisor に委譲）

なぜこの設計が有効か

Anthropic のマルチエージェント研究では「モデル選択」がパフォーマンスに最も大きく影響することが示された。Opus を Leader に集中配置し、Sonnet を多数の Teammate として並列実行する構成は、コスト効率と品質の両面で最適解に近い。

また Star Topology は「情報の矛盾を防止する最小構成」でもある。エージェント数が増えると指数関数的に増加するコミュニケーションパスを、Leader という単一ハブに集約することで管理可能な範囲に収める。

3. DAG 駆動のタスク設計 — 並列化の科学

タスクを DAG で管理する

Agent Teams のタスクリストは Directed Acyclic Graph (DAG) — 有向非巡回グラフ — として設計することで、タスク間の依存関係を明示的に管理できる。

{
  "tasks": [
    { "id": "T01", "name": "認証スキーマ設計", "blocked_by": [] },
    { "id": "T02", "name": "API エンドポイント実装", "blocked_by": ["T01"] },
    { "id": "T03", "name": "フロントエンド実装", "blocked_by": ["T01"] },
    { "id": "T04", "name": "統合テスト", "blocked_by": ["T02", "T03"] }
  ]
}

この例では T02 と T03 が並列実行可能で、T04 は両方の完了を待つ。DAG を設計することで「何が並列化できるか」が一目でわかる。

Wave 実行パターン

依存関係で区切られたタスクグループを「Wave」と呼ぶ。Wave 単位で実行することで、並列化の恩恵を最大化しながら依存関係の整合性を保てる。

Wave 1: 調査・設計（すべて並列実行可能）
  ├─ Teammate A: フロントエンドの現状調査
  ├─ Teammate B: バックエンド API の現状調査
  └─ Teammate C: テスト戦略の立案
       ↓ Wave 1 完了後

Wave 2: 実装（ファイル分離が前提）
  ├─ Teammate A: フロントエンド実装（src/components/ 配下）
  └─ Teammate B: バックエンド API 実装（src/api/ 配下）
       ↓ Wave 2 完了後

Wave 3: 統合テスト（順次実行）
  └─ Teammate C: 統合テスト実行・品質検証

Wave 設計のポイントは「同一 Wave 内のタスクが互いに依存しない」ことを保証することだ。ファイルレベルで重複がないか事前に確認する。

タスクサイジングの原則

サイズ感	問題点
小さすぎる（1ファイル以下）	調整オーバーヘッドが実行コストを上回る
大きすぎる（1週間以上）	長時間チェックインなし・手戻りリスク増大
適切	明確な成果物を持つ自己完結ユニット

実践的な目安として、1 Teammate あたり 5〜6 タスクが推奨されている。適切なバッチサイズがコンテキスト切り替えを防止し、Teammate が「自分の担当」を意識しながら実装を進められる。

ファイルロックと競合回避

Anthropic の C コンパイラプロジェクト（16エージェント並列、10万行 Rust コード）では、独自のファイルロック機構でタスクの競合を防止した。各エージェントが current_tasks/ ディレクトリにロックファイルを書き込んでタスクをクレームし、Git の組み込み競合解決で異なるエージェントが異なるタスクに自然に誘導される仕組みを使った。

# エージェントがタスクをクレームする例
echo "$AGENT_ID" > current_tasks/task-$TASK_ID.lock
git add current_tasks/task-$TASK_ID.lock
git commit -m "claim: task-$TASK_ID"

この「分散型クレーム」アプローチにより、中央のオーケストレーターなしに競合を回避できる。

品質ゲートの自動化

TaskCompleted フックと TeammateIdle フックを使うと、タスク完了・Teammate 停止のタイミングで品質チェックを自動実行できる。

{
  "hooks": {
    "TaskCompleted": [{
      "hooks": [{
        "type": "command",
        "command": "./.claude/hooks/quality-gate.sh"
      }]
    }],
    "TeammateIdle": [{
      "hooks": [{
        "type": "command",
        "command": "./.claude/hooks/verify-output.sh"
      }]
    }]
  }
}

#!/bin/bash
# .claude/hooks/quality-gate.sh
set -e
npm test      || { echo "テストが失敗しました" >&2; exit 2; }
npm run lint  || { echo "Lint が失敗しました" >&2; exit 2; }
npm run build || { echo "ビルドが失敗しました" >&2; exit 2; }
exit 0

exit 2 で返すと Claude にエラーメッセージが通知され、Teammate が自動的に問題修正に取り組む。TeammateIdle は Teammate が停止する直前に実行されるため、品質基準を満たさない限り停止できないゲートとして機能する。

4. コンテキスト管理の極意 — 80/20 ルールとその先

80/20 ルール

コンテキスト管理の基本原則はシンプルだ。

複雑なマルチファイルタスクでは、コンテキストウィンドウの最後の 20% を使わない。

200K トークンのウィンドウなら、167K（83.5%）到達時点で自動コンパクションが走る。この直前から推論品質が顕著に低下する。ステータスバーのトークン使用率を常時確認し、70〜80% を超えたら手動でコンパクションを検討する。

コンパクション戦略 — いつ、どのように圧縮するか

コンパクションの推奨タイミング:

主要機能の完成後
探索フェーズから実装フェーズへの切り替え前
Claude が以前の質問を繰り返したり、過去の判断と矛盾したとき
タスクの自然な区切り点（Wave の境界）

避けるべきタイミング:

デバッグの途中（特定のエラーメッセージが重要な間）
複雑なリファクタリング中（ファイル間の依存関係を追跡中）

Subagents による探索の隔離

コンテキスト保護において最も効果的な戦術の一つが、「探索タスクを Subagent に委譲する」ことだ。

メインコンテキスト
  └─ 「認証モジュールの現状を調査してください」
          ↓ Subagent に委譲
  Subagent コンテキスト（独立）
    ├─ src/auth/ を全読み込み
    ├─ テストファイルを解析
    └─ 依存関係を追跡
          ↓ 要約のみ親に返却
  メインコンテキスト
    └─ 「認証モジュールは JWT + Redis セッション管理。主要関数は...」

数百ファイルを読んでも、Subagent のコンテキストで完結する。メインコンテキストには要約だけが入る。

30分スプリント戦略

実践的なコンテキスト管理として「30分スプリント」が有効だ。30分ごとにタスクを区切り、完了時点でコンパクションまたは /clear を実施する。長時間連続でセッションを継続するより、短いサイクルで新鮮な状態から始める方が、最終的な出力品質が高くなることが多い。

Leader のコンテキスト設計

タスク状態	Leader が保持する情報	Leader が捨てる情報
COMPLETED	task_id・status・成果物パス	実装詳細・テスト詳細・往復メッセージ
IN_PROGRESS	Teammate への指示内容・進行状況	タスク定義全文（Advisor に再クエリ可能）
PENDING	task_id・blocked_by・wave	タスク定義（Advisor に都度クエリ）

Leader のコンテキストは「状態の要約」のみを保持し、詳細は Advisor に都度クエリする設計が理想だ。Advisor は何度読み直しても Advisor 自身のコンテキスト内で完結するため、Leader のコンテキストを消費しない。

5. CLAUDE.md 最適化戦術 — 300行の予算をどう使うか

「Less is More」原則

HumanLayer のリサーチによると、最先端の LLM が一貫して従える指示の上限は 150〜200 個だ。しかし Claude Code のシステムプロンプトはすでに約50の指示を含んでいる。CLAUDE.md に使えるバジェットは実質 100〜150 指示に限られる。

推奨: ルートファイルは 300行以内、理想は 60行以下。

CLAUDE.md の長さと「Claude が重要なルールを無視する確率」は正比例する。長い CLAUDE.md では、重要なルールが埋もれて実質的に機能しなくなる。

Claude がすでにできることは書かない

CLAUDE.md に「クリーンなコードを書くこと」「エラーハンドリングを忘れずに」といった指示を書くのは、トークン予算の無駄だ。Claude がすでに正しく動作していることは書かない。

書くべき内容の判断基準:

このルールがなくても Claude は正しく動作するか？ → Yes なら削除
プロジェクト固有の情報か、Claude が元々知っている情報か？ → 後者なら削除
頻繁に変わる情報ではないか？ → 変わるなら削除

コードスタイルは Linter に委譲し、Hooks で強制する

“Never send an LLM to do a linter’s job.”

フォーマット・Lint・型チェックは決定論的なツール（Biome, ESLint, tsc）に任せ、Hooks で自動実行すべきだ。LLM に非決定論的に実行させると一貫性が失われる。

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "npm run lint --fix && npm run format"
      }]
    }]
  }
}

コードスタイルの指示を CLAUDE.md から削除し、このフック設定に置き換えることで、トークン予算を節約しながら確実な品質保証を実現できる。

Progressive Disclosure パターン

CLAUDE.md の肥大化を防ぐパターンが「Progressive Disclosure」だ。全セッションで必要な情報はルートに書き、特定の文脈でのみ必要な情報はリンクで示す。

# CLAUDE.md（ルート — 60行以内）

## 技術スタック
- Astro 5.18.0 + Tailwind CSS 4.2.0 + Cloudflare Pages
- TypeScript 5.9.x（厳格モード）

## コマンド
- ビルド: `npm run build`
- 型チェック: `npx tsc --noEmit`
- Lint: `npm run lint`

## 詳細ドキュメント（オンデマンドで参照）
- API 設計規約: @.claude/rules/api-conventions.md
- Git ワークフロー: @.claude/rules/branching.md
- デプロイ手順: @.claude/rules/deployment.md

@path/to/file 構文でインポートされたファイルは、Claude が必要と判断したときにオンデマンドで読み込まれる。

階層的 CLAUDE.md の設計

~/.claude/CLAUDE.md          # 全プロジェクト共通（個人設定）
  ./CLAUDE.md                 # プロジェクトルート（チーム共有）
    ./.claude/rules/api.md    # API 開発時のみロード
    ./.claude/rules/test.md   # テスト作成時のみロード
    src/components/CLAUDE.md  # コンポーネント開発時のみロード

子ディレクトリの CLAUDE.md は、そのディレクトリのファイルを扱うときにオンデマンドでロードされる。機能領域ごとに専門的な指示を分離することで、ルートの CLAUDE.md をシンプルに保てる。

6. Skills 設計パターン — オンデマンド知識注入

CLAUDE.md から Skills への分離基準

Skills は .claude/skills/{skill-name}/SKILL.md に配置する専門知識パッケージだ。CLAUDE.md との使い分けは明確だ。

CLAUDE.md → 全セッションで常時必要な情報
  例) ビルドコマンド・技術スタック・ブランチ命名規則

Skills → 特定タスクや文脈でのみ必要な情報
  例) API 設計規約・デプロイ手順・特定ドメインの専門知識

Skills はオンデマンドロードなので、毎セッション全情報をロードして CLAUDE.md を肥大化させる問題を回避できる。

仕様を Skills 化する — SDD レイヤーアーキテクチャ

大規模プロジェクトでは仕様書全体を CLAUDE.md に入れることはできない。このプロジェクト（rick-brick）では SDD（Software Design Document）を6レイヤー（L0〜L5）に分割し、各レイヤーをスキルとして定義している。

.claude/skills/
  spec-l0-core/          # 常時ロード（技術スタックの判断基準）
  spec-l1-1-vision/      # L1: ビジョン・問題定義
  spec-l1-6-content-types/  # L1: コンテンツタイプ分類
  spec-l4-1-content-schema/ # L4: Frontmatter スキーマ定義
  spec-l4-3-article/     # L4: 記事テンプレート・埋め込み要素
  generate-thumbnail/    # サムネイル生成ワークフロー
  common-doc-writer/     # ファイル出力ワークフロー

エージェントが Skill("spec-l4-1-content-schema") と呼び出すと、Content Collections スキーマの詳細定義が注入される。Advisor はこの仕組みで必要な仕様だけをオンデマンドに読み込み、Leader のコンテキストを汚染せずに情報を蒸留できる。

Subagents への Skills 注入

Subagent は親会話から Skills を継承しない。必要な Skills を frontmatter に明示的にリストアップする必要がある。

---
name: api-developer
description: チーム規約に従った API エンドポイントを実装する専門エージェント
tools: Read, Edit, Write, Bash
skills:
  - api-conventions
  - error-handling-patterns
  - security-checklist
---

あなたはシニアバックエンドエンジニアです。
上記スキルで定義されたチーム規約に厳密に従いながら実装してください。

`context: fork` による独立実行

Skills の frontmatter で context: fork を設定すると、スキルが独立したサブエージェントとして実行される。

---
name: security-audit
description: セキュリティ監査を実行する。コード変更後に使用する
context: fork
allowed-tools: Read, Grep, Glob
disable-model-invocation: false
---

context: fork のスキルは親コンテキストを消費しない。大量のファイルを読む監査・レビュー系タスクに特に有効だ。

7. Hooks による決定論的制御 — 品質の自動保証

CLAUDE.md（助言的）vs Hooks（決定論的）

Claude Code における品質保証の二重構造を理解することが重要だ。

	CLAUDE.md	Hooks
従う確率	約80%（助言的）	100%（決定論的）
適した用途	設計方針・コンテキスト提供	フォーマット・Lint・セキュリティチェック
実行タイミング	セッション開始時に読み込み	ライフサイクルイベントで自動実行

「毎回必ず実行すべきこと」は Hooks に書く。CLAUDE.md に「型チェックを必ず実行すること」と書いても 20% の確率で無視される。Hooks なら必ず実行される。

Agent Teams 品質ゲート

Agent Teams では以下の2つの Hook イベントが特に重要だ。

TeammateIdle: Teammate がアイドル状態（停止）になる直前に実行される。exit 2 を返すとフィードバックメッセージが Teammate に送信され、作業を継続させられる。

TaskCompleted: タスクが完了としてマークされる直前に実行される。exit 2 を返すと完了が阻止される。

#!/bin/bash
# .claude/hooks/verify-output.sh（TeammateIdle 用）

# テスト実行
if ! npm test 2>&1; then
  echo "テストが失敗しました。修正してから停止してください。" >&2
  exit 2
fi

# 型チェック
if ! npx tsc --noEmit 2>&1; then
  echo "TypeScript の型エラーが残っています。" >&2
  exit 2
fi

echo "品質チェック通過" >&2
exit 0

この仕組みにより、「テストが通らない限り Teammate が停止できない」という自動品質ゲートが実現する。

セキュリティ制御 — PreToolUse での危険コマンドブロック

#!/bin/bash
# .claude/hooks/block-dangerous.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# 危険なコマンドパターンをチェック
DANGEROUS_PATTERNS=("rm -rf /" "DROP TABLE" "git push --force.*main" "chmod 777")

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if echo "$COMMAND" | grep -qE "$pattern"; then
    echo "危険なコマンドをブロックしました: $pattern にマッチ" >&2
    exit 2  # exit 2 でブロック + Claude にフィードバック
  fi
done

exit 0

exit 2 パターン — ブロック + フィードバック

Hooks の終了コードは3種類だ。

exit 0  → 成功・許可
exit 2  → ブロック（stderr の内容が Claude へのフィードバックとして渡される）
その他  → エラー（non-blocking、verbose モードにのみ表示）

exit 2 の強力な点は、ブロックするだけでなく Claude に文脈情報を渡せることだ。「なぜブロックされたか」を伝えることで、Claude が別のアプローチを自律的に試せる。

8. 実践事例 — Anthropic と業界の最前線

Anthropic C コンパイラ: 16エージェント・10万行 Rust コード

Anthropic が自社で Agent Teams を使って C コンパイラを開発したプロジェクトは、マルチエージェント開発の現時点での最大規模事例だ。

規模: 16エージェント並列・2,000 セッション・2億トークン
成果: 100,000行 Rust コード・Linux 6.9 カーネルのビルド成功（x86/ARM/RISC-V 対応）
技術的工夫:
- 各エージェントを独立した Docker コンテナで隔離
- Git のファイルロックを使った競合防止
- 専門エージェント（コード重複排除・パフォーマンス最適化・ドキュメント維持）の分業

このプロジェクトから得られた最重要の教訓: 「タスク検証器がほぼ完璧でなければ Claude は間違った問題を解く」。エージェントは測定可能な成功指標を自律的に最大化しようとするため、テストの品質がチーム全体の方向性を決定する。

Anthropic マルチエージェント研究: 15倍のトークンで90%性能向上

Anthropic の研究システムでの実証データは、マルチエージェント設計の有効性を数値で示している。

単一エージェントと比較してマルチエージェントシステムは通常 15倍 のトークンを使用
Opus 4 単一 vs Opus 4 リード + Sonnet 4 サブエージェントで 90.2% のパフォーマンス向上
モデルアップグレードの効果 < アーキテクチャ変更の効果

コストは大幅に増加するが、それを補って余りある品質向上が得られる — というのが現時点での Anthropic の知見だ。

並列コードレビューの実践プロンプト

Agent Team で PR #142 をレビューしてください。3つの独立した観点でレビュワーを生成します:

- Reviewer-Security: 認証・認可・入力検証・シークレット露出のみに集中
- Reviewer-Performance: DB クエリ効率・N+1 問題・キャッシュ戦略に集中
- Reviewer-Testing: テストカバレッジ・エッジケース・モック品質に集中

各レビュワーは独立してレビューし、最後に相互の発見事項を Leader に報告してください。
Leader は3つの観点を統合した優先度付きフィードバックを作成してください。

競合仮説デバッグの実践プロンプト

ユーザーが「ログイン後に画面が白くなる」と報告しています。
5人の調査エージェントを生成し、異なる仮説を並列で調査してください:

- Agent-Auth: JWT の有効期限・署名検証に問題はないか
- Agent-State: 状態管理（Redux/Context）の更新タイミングに問題はないか
- Agent-Route: ルーティング設定でリダイレクトが無限ループしていないか
- Agent-Error: エラーバウンダリがエラーを隠蔽していないか
- Agent-Network: API レスポンスのタイミングに問題はないか

各エージェントは証拠を収集し、他のエージェントの仮説を否定できる証拠も探してください。
最終的に最も証拠の強い仮説に収束してください。

Doctolib: フィーチャー出荷 40% 高速化

医療予約プラットフォームの Doctolib は Claude Code をエンジニアリングチーム全体に展開し、レガシーテストインフラを数時間で置換、フィーチャー出荷速度が 40% 高速化した。

2026年時点で、86% の組織が本番コードへのエージェント活用を展開しているというデータがある。「AI が書いたコードをどう信頼するか」という問いへの答えは、テスト・レビュー・Hooks の組み合わせによる自動品質保証の確立だ。

9. アンチパターンと失敗から学ぶ

キッチンシンクセッション — コンテキスト汚染

症状: 無関係なタスクを同一セッションで実行し続け、Claude の回答品質が徐々に低下する。

根本原因: コンテキストが無関係な情報で汚染されている。バグ修正のデバッグ情報が残ったまま新機能を実装すると、Claude は両方の情報を考慮しようとして焦点がぼける。

対策: タスク間で /clear を積極的に使用する。「前回の会話を継続したい」という気持ちをグッと抑えて、新しいタスクは新しいコンテキストで始める。

修正の繰り返し — 失敗コンテキストの蓄積

症状: Claude が同じ間違いを繰り返し、修正しても改善しない。

根本原因: 失敗した試みがコンテキストに蓄積し、Claude が「これは失敗した方法」という情報を過剰に参照している。

対策: 2回の修正失敗後は /clear してまったく新しいプロンプトで再開する。失敗の経緯を引き継がず、「何を達成したいか」だけを伝え直す。

過剰な Agent Teams 活用 — トークン対効果の判断

Agent Teams はマルチエージェントシステムが通常の 15倍のトークンを消費する。すべてのタスクに Agent Teams を適用すれば、コストは 15倍に膨れ上がる。

Agent Teams が不適切なケース:

同一ファイルを複数エージェントが編集する必要があるタスク
順次処理で十分な直線的なタスク
短時間で完了するシンプルな実装

「問題がツールを選ぶべき」であり、「ツールに合わせて問題を作らない」ことが重要だ。

ハンドオフでのコンテキスト喪失

複雑なマルチエージェントシステムを構築すると、各 Teammate のハンドオフでコンテキストが失われ、「調整のためのトークン消費」が「実際の作業のためのトークン消費」を上回るケースが発生する。

これを防ぐには、Teammate への指示に「何を達成したか」だけでなく「なぜその設計にしたか」も含める。次の Teammate が前の Teammate の判断根拠を理解できることが、コンテキスト喪失のリスクを下げる。

並列収束問題 — 全エージェントが同じバグに集中

Anthropic の C コンパイラプロジェクトで実際に起きた問題だ。Linux カーネルコンパイルが単一のモノリシックタスクになったとき、16エージェント全員が同一バグに収束し、互いの修正を上書きし続けるデッドロック状態に陥った。

対策: タスクを「分離可能な単位」に分解し、各エージェントが担当する問題を明確に区切る。「GCC を参照実装（オラクル）として使い、どのファイルで差異が出るかを特定し、その差異を個別タスクとして各エージェントに割り当てる」という手法が有効だった。

テスト検証の軽視 — 品質保証なしの信頼

教訓: エージェントは「測定可能な成功指標」を最大化しようとする。テストが弱ければ、テストをパスするが本質的に間違った実装を生成する。

テスト品質がチームの方向性を決定する。Agent Teams を使うなら、テスト設計に人間が最も多くの時間を投資すべきだ。

「マルチエージェントは常に高速」という神話

マルチエージェントシステムは「並列実行による高速化」が売りのように見えるが、実態はより複雑だ。

エージェント間のコミュニケーションオーバーヘッドが発生する
Leader のコンテキスト管理コストが増大する
タスクの競合・待機時間が発生する

実際のメリット: 高速化ではなく「コンテキストの新鮮さを維持した状態での品質向上」だ。単一セッションではコンテキスト汚染で失敗するような複雑なタスクを、マルチエージェントで分割することで「実現可能」にする。

10. 導入ロードマップ — Phase 1 から Phase 4 へ

段階的な導入により、各フェーズで確実な効果を得ながら次のフェーズの基盤を作る。

Phase 1: 基盤整備（CLAUDE.md 最適化 + Hooks）

まず「使っているのに効果が出ていない」状態を解消する。

実施内容:

/init で CLAUDE.md を自動生成し、300行以内に絞り込む
Claude がすでに正しく動作しているルールを削除する
PostToolUse Hooks で Lint・フォーマットを自動化する
PreToolUse Hooks で危険なコマンドをブロックする

期待効果: CLAUDE.md の品質向上により推論の精度が上がる。Hooks による品質保証で人間のレビュー工数が減る。

完了基準: CLAUDE.md が 300行以内・Hooks でコード品質チェックが自動化されている。

Phase 2: Subagents 活用（調査隔離 + コードレビュー）

コンテキスト保護の実践的な効果を体感する。

実施内容:

読み取り専用の code-reviewer サブエージェントを定義する
「重い調査タスク」を Subagent に委譲してメインコンテキストを保護する
context: fork を使って探索系スキルを独立実行する

---
name: code-reviewer
description: セキュリティ・可読性・パフォーマンスの観点でコードをレビューする
tools: Read, Grep, Glob
model: sonnet
---

コードレビューを実施します。以下の観点で分析してください:
1. セキュリティ（入力検証・シークレット漏洩・権限確認）
2. 可読性（命名・重複・コメント）
3. パフォーマンス（N+1・不要な再計算）
4. テストカバレッジ

フィードバックは Critical / Warning / Suggestion の優先度で整理してください。

完了基準: メインコンテキストを消費せずに大規模調査・コードレビューができる。

Phase 3: Agent Teams 導入（読み取り専用タスクから）

最初は「失敗しても安全な」読み取り専用タスクから始める。

実施内容:

PR レビュー・バグ調査などの読み取り専用タスクから試す
3〜5 Teammates から始め、1 Teammate 5〜6 タスクを目安にする
TeammateIdle + TaskCompleted Hooks で品質ゲートを自動化する

完了基準: Agent Teams で並列レビューが動作し、品質ゲートが自動化されている。

Phase 4: 本格オーケストレーション（3層アーキテクチャ）

Leader/Advisor/Teammate の3層アーキテクチャを本番実装タスクに適用する。

実施内容:

Orchestrator ファイル（.claude/orchestrators/*.md）で実行計画を定義する
Advisor 用エージェント定義（仕様読解専門）を作成する
DAG ベースのタスク依存関係を設計する
Wave 単位での進捗管理・品質検証フローを確立する

# feature-x Orchestrator

## Team Structure
- Leader: Opus（進行管理・品質検証）
- Advisor: Sonnet（仕様書読解・情報蒸留）
- Teammates: Sonnet × 3（実装）

## Wave 計画
Wave 1: T01（DB スキーマ設計）← 並列不可、Advisor の仕様確認後に開始
Wave 2: T02（API 実装）+ T03（フロントエンド実装）← 並列実行
Wave 3: T04（統合テスト）← Wave 2 完了後

完了基準: 複雑な機能開発がマルチエージェントで自律実行できる。品質ゲートが各フェーズで機能し、人間の介入なしに品質基準を維持できる。

まとめ — 設計の本質

Claude Code の高度活用を突き詰めると、「コンテキストの設計」という一点に集約される。

どのエージェントが何を知るべきか。どの情報を保持し、どの情報を捨てるか。どのタスクを並列化し、どのタスクを順次実行するか。この設計判断が、マルチエージェントシステムの品質とコストのすべてを決定する。

Star Topology は「情報の集中管理」による品質向上、DAG は「依存関係の明示化」による並列化効率、80/20ルールは「コンテキストの新鮮さ」による推論品質維持 — それぞれが「コンテキスト設計」の異なる側面だ。

Anthropic が C コンパイラを 16エージェントで実装し、10万行の Rust コードを書き、Linux カーネルをビルドできたのは、「正しいコンテキスト設計」があったからだ。テストという「正確な検証器」が各エージェントの方向性を定め、Docker コンテナという「隔離された実行環境」が各エージェントのコンテキストを保護し、ファイルロックという「競合回避機構」が並列実行の安全性を保証した。

Phase 1 の CLAUDE.md 最適化から始め、自分のユースケースに合ったペースで Phase 4 まで進んでほしい。マルチエージェント設計が開放する可能性は、現在の Claude Code の日常的な活用から想像するよりずっと大きい。

Claude Code 実践アーキテクチャ — Teams/Subagents で開発を加速する設計パターン

Claude Code 実践アーキテクチャ — Teams/Subagents で開発を加速する設計パターン

1. なぜマルチエージェント設計が必要か — 単一セッションの限界

コンテキスト劣化の科学的根拠

マルチエージェントで何が変わるか

2. Star Topology — Leader/Advisor/Teammate 3層アーキテクチャ

設計思想

Leader がやること / やらないこと

Advisor 層 — 情報の蒸留専門家

Teammate の動作原則

情報フロー制約

なぜこの設計が有効か

3. DAG 駆動のタスク設計 — 並列化の科学

タスクを DAG で管理する

Wave 実行パターン

タスクサイジングの原則

ファイルロックと競合回避

品質ゲートの自動化

4. コンテキスト管理の極意 — 80/20 ルールとその先

80/20 ルール

コンパクション戦略 — いつ、どのように圧縮するか

Subagents による探索の隔離

30分スプリント戦略

Leader のコンテキスト設計

5. CLAUDE.md 最適化戦術 — 300行の予算をどう使うか

「Less is More」原則

Claude がすでにできることは書かない

コードスタイルは Linter に委譲し、Hooks で強制する

Progressive Disclosure パターン

階層的 CLAUDE.md の設計

6. Skills 設計パターン — オンデマンド知識注入

CLAUDE.md から Skills への分離基準

仕様を Skills 化する — SDD レイヤーアーキテクチャ

Subagents への Skills 注入

context: fork による独立実行

7. Hooks による決定論的制御 — 品質の自動保証

CLAUDE.md（助言的）vs Hooks（決定論的）

Agent Teams 品質ゲート

セキュリティ制御 — PreToolUse での危険コマンドブロック

exit 2 パターン — ブロック + フィードバック

8. 実践事例 — Anthropic と業界の最前線

Anthropic C コンパイラ: 16エージェント・10万行 Rust コード

Anthropic マルチエージェント研究: 15倍のトークンで90%性能向上

並列コードレビューの実践プロンプト

競合仮説デバッグの実践プロンプト

Doctolib: フィーチャー出荷 40% 高速化

9. アンチパターンと失敗から学ぶ

キッチンシンクセッション — コンテキスト汚染

修正の繰り返し — 失敗コンテキストの蓄積

過剰な Agent Teams 活用 — トークン対効果の判断

ハンドオフでのコンテキスト喪失

並列収束問題 — 全エージェントが同じバグに集中

テスト検証の軽視 — 品質保証なしの信頼

「マルチエージェントは常に高速」という神話

10. 導入ロードマップ — Phase 1 から Phase 4 へ

Phase 1: 基盤整備（CLAUDE.md 最適化 + Hooks）

Phase 2: Subagents 活用（調査隔離 + コードレビュー）

Phase 3: Agent Teams 導入（読み取り専用タスクから）

Phase 4: 本格オーケストレーション（3層アーキテクチャ）

まとめ — 設計の本質

`context: fork` による独立実行