Agent Architecture Patterns

概要

このスキルは、マービン・ミンスキーが『心の社会』で提唱した原則に基づき、 Claude Codeエージェントの効果的なアーキテクチャパターンと設計原則を提供します。

人間の知性が無数の小さなエージェントの相互作用から創発するように、 Claude Codeエージェントも単一責任を持つ特化型エージェント群の協調により、 複雑な知的活動を実現します。

主要な価値:

• 適切なアーキテクチャパターンの選択により、保守性と拡張性が向上
• 単一責任原則により、エージェントの役割が明確化
• 階層的組織により、複雑なタスクを管理可能な単位に分割
• 制約の明確化により、エージェントの性能が最適化

対象ユーザー:

• エージェントを設計する.claude/agents/meta-agent-designer.md
• マルチエージェントシステムを構築する開発者
• 既存エージェントをリファクタリングするチーム

リソース構造

agent-architecture-patterns/
├── SKILL.md                               # 本ファイル（パターンと設計原則）
├── resources/
│   └── pattern-catalog.md                # 4つのパターンの詳細カタログ
├── templates/
│   ├── orchestrator-worker-template.md   # オーケストレーター・ワーカーパターンテンプレート
│   └── pipeline-template.md              # パイプラインパターンテンプレート
└── scripts/
    └── validate-architecture.sh          # アーキテクチャ検証スクリプト

リソース種別

• パターンカタログ (resources/pattern-catalog.md): 4つのアーキテクチャパターンの詳細説明、適用条件、実装例
• オーケストレーター・ワーカーテンプレート (templates/orchestrator-worker-template.md): オーケストレーター・ワーカーパターンの実装テンプレート
• パイプラインテンプレート (templates/pipeline-template.md): パイプラインパターンの実装テンプレート
• アーキテクチャ検証スクリプト (scripts/validate-architecture.sh): アーキテクチャの妥当性を自動検証するスクリプト

コマンドリファレンス

このスキルで使用可能なリソース、スクリプト、テンプレートへのアクセスコマンド:

リソース読み取り

# パターンカタログ（4つのアーキテクチャパターンの詳細）
cat .claude/skills/agent-architecture-patterns/resources/pattern-catalog.md

スクリプト実行

# アーキテクチャ検証スクリプト（TypeScript）
node .claude/skills/agent-architecture-patterns/scripts/validate-architecture.mjs <agent-file-path>

# 例: skill-librarianエージェントのアーキテクチャを検証
node .claude/skills/agent-architecture-patterns/scripts/validate-architecture.mjs .claude/agents/skill-librarian.md

# シェルスクリプト版
bash .claude/skills/agent-architecture-patterns/scripts/validate-architecture.sh <agent-file-path>

テンプレート参照

# オーケストレーター・ワーカーパターンテンプレート
cat .claude/skills/agent-architecture-patterns/templates/orchestrator-worker-template.md

# パイプラインパターンテンプレート
cat .claude/skills/agent-architecture-patterns/templates/pipeline-template.md

# テンプレートをコピーして新規エージェントを作成
cp .claude/skills/agent-architecture-patterns/templates/orchestrator-worker-template.md .claude/agents/new-agent.md

いつ使うか

シナリオ1: 新規エージェントのアーキテクチャ設計

状況: 新しいエージェントを作成する際、適切な構造を決定したい

適用条件:

• タスクが複数のステップで構成される
• 他エージェントとの協調が必要
• 役割分担を明確にしたい

期待される成果: タスク特性に最適なアーキテクチャパターンの選択

シナリオ2: マルチエージェントシステムの設計

状況: 複数エージェントの協調システムを構築する

適用条件:

• 3つ以上のエージェントが連携する
• 協調パターンが不明確
• スケーラビリティが重要

期待される成果: 階層的で管理可能なシステム構造

シナリオ3: 既存エージェントのリファクタリング

状況: 既存エージェントの構造を改善したい

適用条件:

• エージェントが複数の責務を持っている
• 保守性が低下している
• 拡張が困難になっている

期待される成果: 単一責任原則に基づく構造改善

前提条件

必要な知識

• Claude Codeエージェントシステムの基本理解
• マルチエージェント協調の概念
• ソフトウェアアーキテクチャの基本原則

必要なツール

• Read: 既存エージェントの構造分析
• Grep: パターン検索

環境要件

• .claude/agents/ディレクトリが存在する
• 既存エージェントが分析可能

ワークフロー

Phase 1: タスク特性の分析

目的: タスクの性質を理解し、適切なパターンを選択する基礎情報を収集

ステップ:

1. タスクの分解:

   • タスクを構成する主要ステップを特定
   • 各ステップの依存関係を明確化
   • 並列実行可能な部分を識別

2. 複雑度の評価:

   • ステップ数（単純: 1-3、中程度: 4-7、複雑: 8+）
   • 分岐の複雑さ（条件分岐、エラーハンドリング）
   • 状態管理の必要性

3. 協調の必要性:

   • 他エージェントとの連携が必要か
   • 情報の受け渡しが必要か
   • 並行処理が有効か

判断基準:

• タスクが3つ以上のステップに分解されているか？
• 各ステップの依存関係が明確か？
• 複雑度レベルが特定されているか？

リソース: resources/pattern-selection-guide.md

Phase 2: アーキテクチャパターンの選択

目的: タスク特性に最適なパターンを選択

4つのパターン:

パターン1: オーケストレーター・ワーカー

適用条件:

• 中央集権的な制御が必要
• 複数のサブタスクを並列実行可能
• 全体の進捗管理が重要

構造:

オーケストレーター
  ├─ ワーカー1（専門タスクA）
  ├─ ワーカー2（専門タスクB）
  └─ ワーカー3（専門タスクC）

利点: 全体制御が容易、並列化が自然 欠点: オーケストレーターがボトルネック

パターン2: ハブアンドスポーク

適用条件:

• 複数のエージェントが共通リソースにアクセス
• データの一元管理が必要
• エージェント間の直接通信を避けたい

構造:

      ハブ（データ管理）
       ↑↓
  ┌────┼────┐
エージェント1  エージェント2  エージェント3

利点: データ整合性が保たれる、疎結合 欠点: ハブが単一障害点

パターン3: パイプライン

適用条件:

• データが段階的に変換される
• 各ステップが独立している
• ストリーム処理が有効

構造:

入力 → エージェント1 → エージェント2 → エージェント3 → 出力

利点: 各ステージが独立、テストが容易 欠点: 柔軟性が低い、エラーの伝播

パターン4: ステートマシン

適用条件:

• 明確な状態遷移がある
• 条件分岐が複雑
• エラーからのリカバリーが重要

構造:

状態A ─(条件1)→ 状態B ─(条件2)→ 状態C
  ↑                              ↓
  └──────(エラー時)──────────────┘

利点: 状態が明確、エラー処理が容易 欠点: 複雑な遷移は管理困難

判断フロー:

タスクの性質は？
├─ 並列処理が主 → オーケストレーター・ワーカー
├─ データ共有が主 → ハブアンドスポーク
├─ 段階的変換が主 → パイプライン
└─ 状態遷移が主 → ステートマシン

判断基準:

• パターンがタスク特性に合致しているか？
• スケーラビリティが確保されているか？
• 保守性が高いか？

リソース: resources/pattern-catalog.md

Phase 3: 設計原則の適用

目的: 5つの設計原則を適用し、パターンを最適化

5つの設計原則:

原則1: 単一機能の原則 (Single Function Principle)

定義: 各エージェントは明確に定義された単一の機能のみを持つ

適用方法:

• エージェントの責務を1文で表現できるか確認
• 複数の動詞が必要な場合は分割を検討
• 「〇〇と△△を行う」→ 2つのエージェントに分割

チェックリスト:

• エージェントの目的が1文で表現できるか？
• 責務が明確で境界が定義されているか？
• 他のエージェントと責務が重複していないか？

原則2: 創発的複雑性の原則 (Emergent Complexity Principle)

定義: 単純なエージェントの組み合わせで複雑な知的活動を実現

適用方法:

• 個々のエージェントはシンプルに保つ
• 複雑さは組み合わせで対応
• do-everything型エージェントを作らない

チェックリスト:

• 各エージェントが十分にシンプルか？
• 組み合わせで複雑なタスクを実現できるか？
• 新しいエージェントの追加が容易か？

原則3: 階層的組織の原則 (Hierarchical Organization Principle)

定義: オーケストレーター（上位）とワーカー（下位）の明確な階層構造

適用方法:

• 上位: 戦略的判断、進捗管理、統合
• 下位: 具体的実行、専門タスク
• 階層は3レベルまでに制限

チェックリスト:

• 階層が明確に定義されているか？
• 上位と下位の役割分担が適切か？
• 階層が3レベル以内か？

原則4: 制約による最適化の原則 (Constraint-Based Optimization Principle)

定義: 役割、ツール、責務の制約を明確にすることで性能が向上

適用方法:

• ツール権限を最小限に制限
• 責務範囲を明確に定義
• 「しないこと」を明示

チェックリスト:

• ツール権限が必要最小限か？
• 責務範囲が明確に定義されているか？
• 「しないこと」が列挙されているか？

原則5: コンテキスト分離の原則 (Context Isolation Principle)

定義: 各エージェントは独立したコンテキストウィンドウを持つ

適用方法:

• エージェント間でコンテキストを共有しない
• 必要な情報のみを明示的に受け渡す
• 長大なコンテキストを避ける

チェックリスト:

• 各エージェントが独立して動作可能か？
• コンテキスト汚染を避けているか？
• 情報の受け渡しが明示的か？

リソース: resources/design-principles.md

Phase 4: 構造の検証と最適化

目的: 設計した構造が原則に準拠しているか検証

検証項目:

1. 単一責任の検証:

   # 各エージェントの責務を1文で表現できるかチェック
   grep "^## 役割定義" .claude/agents/*.md
   

2. 階層の妥当性:

   # エージェント間の依存関係を可視化
   .claude/skills/agent-architecture-patterns/scripts/analyze-agent-structure.sh
   

3. 制約の明確性:

   • ツール権限が最小限か
   • 禁止事項が明示されているか

4. コンテキスト効率:

   • トークン使用量の見積もり
   • Progressive Disclosureの適用

判断基準:

• 全5つの設計原則に準拠しているか？
• パターンが適切に適用されているか？
• スケーラビリティが確保されているか？
• 保守性が高いか？

リソース: resources/design-principles.md

リソースへの参照

詳細な知識は以下のリソースファイルを参照してください:

• ミンスキーの思想詳細: resources/minsky-society-of-mind.md

  • 『心の社会』の核心概念
  • エージェント理論の基礎
  • Claude Codeへの適用方法

• パターンカタログ: resources/pattern-catalog.md

  • 4つのパターンの詳細説明
  • 適用条件と判断基準
  • 実装例とアンチパターン

• パターン選択ガイド: resources/pattern-selection-guide.md

  • タスク特性の分析フレームワーク
  • パターン選択の判断フロー
  • トレードオフの評価

• 設計原則詳細: resources/design-principles.md

  • 5つの原則の理論的背景
  • 適用方法とチェックリスト
  • 違反パターンと修正方法

ベストプラクティス

すべきこと

1. パターンの一貫性:

   • プロジェクト全体で一貫したパターンを使用
   • 例外を最小限に抑える
   • パターン変更は明示的に記録

2. 段階的な構築:

   • 最初はシンプルなパターンから開始
   • 必要に応じて段階的に複雑化
   • オーバーエンジニアリングを避ける

3. アーキテクチャ決定の記録:

   • なぜそのパターンを選択したか記録
   • トレードオフを明示
   • 将来の見直しのための情報を残す

避けるべきこと

1. do-everything型エージェント:

   • ❌ すべてを1つのエージェントで実装
   • ✅ 責務ごとに分割し、協調させる

2. 不適切なパターン選択:

   • ❌ タスク特性を無視したパターン適用
   • ✅ タスク分析に基づく適切な選択

3. 過度な階層化:

   • ❌ 5レベル以上の深い階層
   • ✅ 3レベル以内のフラットな構造

トラブルシューティング

問題1: エージェントの責務が不明確

症状: エージェントが複数の異なるタスクを実行している

原因: 単一責任原則の違反

解決策:

1. エージェントの動作を列挙
2. 異なる責務を特定
3. 責務ごとに分割
4. 協調プロトコルを定義

予防策: 設計時に責務を1文で表現できるか確認

問題2: オーケストレーターがボトルネック

症状: オーケストレーターエージェントの処理時間が長い

原因: 過度な集中制御

解決策:

1. ワーカーに権限委譲
2. パイプラインパターンへの変更を検討
3. 並列処理の最適化

予防策: 設計時にボトルネック分析を実施

問題3: エージェント間の通信が複雑

症状: エージェント間の依存関係が網の目状

原因: 適切なパターンが適用されていない

解決策:

1. 依存関係を可視化
2. ハブアンドスポークパターンの適用を検討
3. 共通データ管理層の導入

予防策: 設計時に依存関係図を作成

関連スキル

• .claude/skills/multi-agent-systems/SKILL.md (.claude/skills/multi-agent-systems/SKILL.md): エージェント間協調の詳細
• .claude/skills/agent-persona-design/SKILL.md (.claude/skills/agent-persona-design/SKILL.md): エージェントのペルソナ設計
• .claude/skills/agent-dependency-design/SKILL.md (.claude/skills/agent-dependency-design/SKILL.md): 依存関係設計
• .claude/skills/progressive-disclosure/SKILL.md (.claude/skills/progressive-disclosure/SKILL.md): コンテキスト最適化

詳細リファレンス

詳細な実装ガイドとツールは以下を参照:

• パターンカタログ (resources/pattern-catalog.md)
• オーケストレーター・ワーカーテンプレート (templates/orchestrator-worker-template.md)
• パイプラインテンプレート (templates/pipeline-template.md)
• アーキテクチャ検証スクリプト (scripts/validate-architecture.sh)

メトリクス

アーキテクチャ品質スコア

評価基準:

• 単一責任準拠: 0-10点
• 階層の適切性: 0-10点
• 制約の明確性: 0-10点
• コンテキスト効率: 0-10点

目標: 平均8点以上

パターン適用率

測定方法: (適切なパターンを使用しているエージェント数 / 総エージェント数) × 100

目標: >90%

保守性スコア

評価基準:

• 責務の明確性
• 変更の容易性
• テストの容易性

目標: 平均8点以上

使用上の注意

このスキルが得意なこと

• エージェントアーキテクチャパターンの選択
• 設計原則の適用と検証
• マルチエージェントシステムの構造設計
• 既存エージェントの構造改善

このスキルが行わないこと

• エージェントの実際の実装
• 具体的なコード生成
• プロジェクト固有のビジネスロジック

推奨される使用フロー

1. タスク特性の分析（Phase 1）
2. アーキテクチャパターンの選択（Phase 2）
3. 設計原則の適用（Phase 3）
4. 構造の検証と最適化（Phase 4）

参考文献

• 『The Society of Mind』 Marvin Minsky著
  • Chapter 1: Prologue - エージェント概念の導入
  • Chapter 6: Agents and Agencies - エージェントの階層構造