Agent Dependency Design

概要

このスキルは、エージェント依存関係とインターフェース設計の包括的なガイドラインを提供します。 スキル、コマンド、他エージェントとの依存関係を適切に設計し、 循環依存を防ぎながら効果的な協調を実現します。

主要な価値:

• スキル参照の標準化により、知識の再利用性が向上
• ハンドオフプロトコルにより、エージェント間の情報受け渡しが明確化
• 循環依存の検出と解消により、システムの健全性が保たれる
• 依存関係マトリクスにより、全体像が可視化される

リソース構造

agent-dependency-design/
├── SKILL.md
├── resources/
│   └── dependency-patterns.md
├── scripts/
│   ├── check-circular-deps.sh
│   └── check-circular-deps.mjs
└── templates/
    └── handoff-protocol-template.json

コマンドリファレンス

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

リソース読み取り

# 依存関係パターン（スキル参照、循環依存解消策）
cat .claude/skills/agent-dependency-design/resources/dependency-patterns.md

スクリプト実行

# 循環依存検出スクリプト（TypeScript）
node .claude/skills/agent-dependency-design/scripts/check-circular-deps.mjs <agents-directory>

# 例: .claude/agents/内の全エージェントの循環依存をチェック
node .claude/skills/agent-dependency-design/scripts/check-circular-deps.mjs .claude/agents

# シェルスクリプト版
bash .claude/skills/agent-dependency-design/scripts/check-circular-deps.sh <agents-directory>

テンプレート参照

# ハンドオフプロトコルテンプレート（JSON形式）
cat .claude/skills/agent-dependency-design/templates/handoff-protocol-template.json

# テンプレートをコピーして新規ハンドオフ定義を作成
cp .claude/skills/agent-dependency-design/templates/handoff-protocol-template.json ./handoff-config.json

いつ使うか

シナリオ1: スキル参照設計

状況: エージェントが外部スキルを参照する必要がある

適用条件:

• 詳細な専門知識が必要
• 知識の再利用が有効
• Progressive Disclosureを適用したい

期待される成果: 効率的なスキル参照プロトコル

シナリオ2: エージェント間協調

状況: 複数エージェントが連携してタスクを実行する

適用条件:

• タスクが複数エージェントに分割される
• 情報の受け渡しが必要
• 進捗管理が重要

期待される成果: 標準化されたハンドオフプロトコル

ワークフロー

Phase 1: スキル依存関係の設計

目的: エージェントが使用するスキルを定義

スキル参照の3段階:

ステップ1: スキル依存関係マトリクス作成

テンプレート:

| スキル名 | 参照タイミング | 参照方法 | 必須/推奨 |
| -------- | -------------- | -------- | --------- |
| skill-1  | Phase X        | cat ...  | 必須      |
| skill-2  | Phase Y        | cat ...  | 推奨      |

判断基準:

• 必須: エージェントが機能するために絶対必要
• 推奨: 品質向上のために望ましい
• オプション: 特定シナリオでのみ使用

ステップ2: スキル参照コマンドの記述

基本形式:

cat .claude/skills/[skill-name]/SKILL.md

相対パスの原則:

• スキル名のみ（❌）: .claude/skills/knowledge-management/SKILL.md
• フルパス（✅）: .claude/skills/knowledge-management/SKILL.md

ステップ3: 参照タイミングの明確化

指定方法:

• どのPhase/ステップで参照するか
• なぜそのタイミングで必要か
• 取得する知識の内容

リソース: resources/skill-reference-protocol.md

Phase 2: コマンド連携の設計

目的: エージェントが実行するコマンドを定義

コマンド実行マトリクス:

| コマンド名 | 実行タイミング | 実行方法 | 必須/推奨 |
| ---------- | -------------- | -------- | --------- |
| /cmd-1     | Step X         | /cmd...  | 必須      |

期待される動作の定義:

• コマンドが何を実行するか
• 期待される出力
• エラー時の対応

リソース: resources/command-integration-guide.md

Phase 3: エージェント間協調の設計

目的: 他エージェントとの連携を定義

協調関係の種類:

• 前提エージェント: このエージェントの前に実行されるべき
• 後続エージェント: このエージェントの後に実行されるべき
• 並行エージェント: 並行して実行可能
• サブエージェント: このエージェントが委譲する対象

ハンドオフプロトコル設計:

{
  "from_agent": "this-agent",
  "to_agent": "next-agent",
  "status": "completed|partial|failed",
  "summary": "実施内容サマリー",
  "artifacts": ["file1.md", "file2.py"],
  "context": {
    "key_decisions": [],
    "unresolved_issues": [],
    "next_steps": []
  },
  "metadata": {
    "duration": "5m30s",
    "model_used": "sonnet",
    "token_count": 15420
  }
}

必須情報:

• from_agent, to_agent: 送信元と宛先
• status: 完了状態
• summary: 実施内容の要約
• artifacts: 生成された成果物
• context: 引き継ぎコンテキスト
• metadata: メタ情報

リソース: resources/handoff-protocol-design.md

Phase 4: 循環依存の検出と解消

目的: 依存関係グラフから循環を検出し、解消する

検出方法:

.claude/skills/agent-dependency-design/scripts/detect-circular-dependencies.sh

循環パターンの例:

A → B → C → A （循環！）

解消策:

1. 依存の方向性を再検討:

   • 本当にその依存が必要か
   • 逆方向にできないか

2. 共通依存を上位に抽出:

   A → D ← C
   ↓       ↓
   B ← ─ ─ ┘
   

3. エージェントの責務を再分割:

   • 循環の原因となる責務を分離
   • 新しいエージェントを作成

リソース: resources/circular-dependency-resolution.md

ベストプラクティス

すべきこと

1. 相対パスの徹底:

   • すべてのスキル参照は相対パス
   • .claude/skills/[skill-name]/SKILL.md

2. 依存関係の可視化:

   • 依存関係マトリクスを作成
   • グラフで表現

3. ハンドオフの標準化:

   • JSON形式で統一
   • 必須情報を明示

避けるべきこと

1. 循環依存の放置:

   • ❌ A → B → A
   • ✅ 早期検出と解消

2. 曖昧な依存関係:

   • ❌ 「関連するスキル」とだけ記載
   • ✅ 具体的なパスと参照タイミング

3. 過度な依存:

   • ❌ 10個以上のスキルに依存
   • ✅ 必要最小限（3-5個）

トラブルシューティング

問題1: スキルが見つからない

症状: cat .claude/skills/xxx/SKILL.md が失敗

原因: 相対パスが間違っている

解決策:

1. パスを確認
2. スキルが実際に存在するか確認
3. 相対パスの基準を確認

問題2: 循環依存が発生

症状: 依存関係が複雑で管理困難

原因: 適切な設計がされていない

解決策:

1. 依存関係グラフを可視化
2. 循環を特定
3. 解消策（3つ）のいずれかを適用

関連スキル

• .claude/skills/multi-agent-systems/SKILL.md (.claude/skills/multi-agent-systems/SKILL.md): エージェント間協調
• .claude/skills/agent-architecture-patterns/SKILL.md (.claude/skills/agent-architecture-patterns/SKILL.md): アーキテクチャパターン
• .claude/skills/progressive-disclosure/SKILL.md (.claude/skills/progressive-disclosure/SKILL.md): スキル設計
• .claude/skills/knowledge-management/SKILL.md (.claude/skills/knowledge-management/SKILL.md): 知識の体系化

詳細リファレンス

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

• 依存関係パターン (resources/dependency-patterns.md)
• ハンドオフプロトコルテンプレート (templates/handoff-protocol-template.json)
• 循環依存検出スクリプト (scripts/check-circular-deps.sh)

メトリクス

依存関係の健全性

評価基準:

• 循環依存数: 0個（必須）
• 平均依存数: 3-5個
• 深さ: 最大3レベル

目標: 循環依存ゼロ、適度な依存数

使用上の注意

このスキルが得意なこと

• スキル参照プロトコルの設計
• ハンドオフプロトコルの標準化
• 循環依存の検出と解消
• 依存関係の可視化

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

• エージェントの実際の実装
• 具体的なコード生成
• スキルの作成（.claude/agents/skill-librarian.mdの役割）