Collection

---
name: .claude/skills/agent-architecture-patterns/SKILL.md
description: |
  マービン・ミンスキーの『心の社会』に基づくエージェントアーキテクチャパターンと
  設計原則を専門とするスキル。単一責任の原則、創発的複雑性、階層的組織化により、
  効果的なマルチエージェントシステムを設計します。

  📚 リソース参照:
  このスキルには以下のリソースが含まれています。
  必要に応じて該当するリソースを参照してください:

  - `.claude/skills/agent-architecture-patterns/resources/pattern-catalog.md`: 4つのアーキテクチャパターン（オーケストレーター・ワーカー、ハブアンドスポーク、パイプライン、ステートマシン）の詳細カタログと選択ガイド
  - `.claude/skills/agent-architecture-patterns/templates/orchestrator-worker-template.md`: オーケストレーター・ワーカーテンプレート
  - `.claude/skills/agent-architecture-patterns/templates/pipeline-template.md`: パイプラインテンプレート
  - `.claude/skills/agent-architecture-patterns/scripts/validate-architecture.mjs`: アーキテクチャ検証スクリプト (Node.js)
  - `.claude/skills/agent-architecture-patterns/scripts/validate-architecture.sh`: アーキテクチャ検証スクリプト (Shell)

  専門分野:
  - アーキテクチャパターン: オーケストレーター・ワーカー、ハブアンドスポーク、パイプライン、ステートマシン
  - 設計原則: 単一機能、創発的複雑性、階層的組織、制約による最適化、コンテキスト分離
  - パターン選択: タスク特性に基づく最適パターンの判断基準
  - 適用戦略: Society of Mind原則のClaude Codeエージェントへの適用

  使用タイミング:
  - 新しいエージェントのアーキテクチャを設計する時
  - マルチエージェントシステムの構造を決定する時
  - エージェント間の協調パターンを選択する時
  - 既存エージェントの構造をリファクタリングする時

  Use proactively when designing agent architecture, selecting collaboration patterns,
  or optimizing multi-agent system structure.
version: 1.0.0
---

# 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`): アーキテクチャの妥当性を自動検証するスクリプト

## コマンドリファレンス

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

### リソース読み取り

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

### スクリプト実行

```bash
# アーキテクチャ検証スクリプト（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>
```

### テンプレート参照

```bash
# オーケストレーター・ワーカーパターンテンプレート
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. **単一責任の検証**:

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

2. **階層の妥当性**:

   ```bash
   # エージェント間の依存関係を可視化
   .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 - エージェントの階層構造