Element Relationship Analyzer

概要

このSkillは、プラグイン内の要素（エージェント、スキル、コマンド）間の依存関係や呼び出し順序を分析する。プラグインの整合性を確認し、循環依存やアーキテクチャ違反を検出して、適切な依存関係の構築を支援する。

責任範囲

このSkillは以下の範囲をカバーする:

• プラグイン要素（エージェント、スキル、コマンド）の収集
• 要素間の依存関係の分析
• 要素の呼び出し順序の分析
• 循環依存の検出と報告
• アーキテクチャ規約違反の検出
• 依存関係の最適化提案

ワークフロー

フェーズ1: 要素収集

プラグインディレクトリから全ての要素を収集し、基本情報を抽出する。

実施内容:

1. プラグインディレクトリ構造を確認する
2. エージェントファイルを収集する
3. スキルファイルを収集する
4. コマンドファイルを収集する
5. 各要素のフロントマター情報を抽出する

収集対象:

• エージェント: agents/[agent-name].md
• スキル: skills/*/SKILL.md
• コマンド: commands/[command-name].md

抽出情報:

• name（要素名）
• description（説明）
• tools（エージェントのみ）
• 依存する要素の参照（本文中のエージェント名、スキル名、コマンド名）

良い例:

【要素収集結果】

プラグイン名: database-design-plugin
プラグインディレクトリ: D:\projects\database-design-plugin

エージェント (1個):
- database-design-agent
  - 説明: データベース設計フェーズ全体に対する責任を持つ
  - tools: "*"

スキル (7個):
ワークフロースキル:
- entity-definition-collector
  - 説明: エンティティ定義を収集する
- normalization-processor
  - 説明: 正規化を実施する
- er-diagram-generator
  - 説明: ER図を生成する
- table-definition-writer
  - 説明: テーブル定義書を作成する
- ddl-script-generator
  - 説明: DDLスクリプトを生成する

コンベンションスキル:
- database-naming-conventions
  - 説明: データベース命名規則を定義
- normalization-rules
  - 説明: 正規化ルールを定義

コマンド (2個):
- design-database
  - 説明: データベース設計全体を実行
- generate-schema
  - 説明: スキーマ定義のみを生成

悪い例:

【要素収集結果】

何かある

フェーズ2: 依存関係分析

各要素が参照する他の要素を分析し、依存関係を明確にする。

実施内容:

1. 各要素のドキュメント本文を解析する
2. 他の要素への参照を検出する
3. 依存関係マップを作成する
4. 依存の種類を分類する（必須依存、オプション依存）
5. 依存の方向を確認する（エージェント→スキル、スキル→スキル、コマンド→エージェント/スキル）

依存関係の検出方法:

• エージェント: 本文中のスキル名参照
• スキル: 本文中の他のスキル名参照（※プラグインアーキテクチャ規約では推奨されない）
• コマンド: 「使用するエージェント」「使用するスキル」セクションからの参照

良い例:

【依存関係分析結果】

コマンド: design-database
- 使用するエージェント:
  - database-design-agent（必須）
- 使用するスキル:
  - entity-definition-collector（必須）
  - normalization-processor（必須）
  - er-diagram-generator（必須）
  - table-definition-writer（必須）
  - ddl-script-generator（必須）
  - database-naming-conventions（必須）
  - normalization-rules（必須）

コマンド: generate-schema
- 使用するエージェント:
  - database-design-agent（必須）
- 使用するスキル:
  - entity-definition-collector（必須）
  - normalization-processor（必須）
  - database-naming-conventions（必須）
  - normalization-rules（必須）

エージェント: database-design-agent
- 依存するスキル: なし
  ※アーキテクチャ規約に従い、エージェントは直接スキルを参照しない

スキル: entity-definition-collector
- 依存するスキル: なし
  ※アーキテクチャ規約に従い、スキルは他のスキルを参照しない

スキル: normalization-processor
- 依存するスキル: なし

スキル: er-diagram-generator
- 依存するスキル: なし

スキル: table-definition-writer
- 依存するスキル: なし

スキル: ddl-script-generator
- 依存するスキル: なし

スキル: database-naming-conventions
- 依存するスキル: なし

スキル: normalization-rules
- 依存するスキル: なし

悪い例:

【依存関係分析結果】

いろいろ依存している

フェーズ3: 呼び出し順序分析

コマンドにおけるスキルの呼び出し順序を分析する。

実施内容:

1. 各コマンドの「実行フロー」セクションを解析する
2. スキルの実行順序を抽出する
3. 並列実行可能なスキルを特定する
4. 順次実行が必要なスキルを特定する
5. 実行順序の妥当性を検証する

分析基準:

• スキルの実行順序が明確であるか
• 依存関係に基づいた順序になっているか
• 並列実行可能なスキルが適切に識別されているか
• データの受け渡しが明確であるか

良い例:

【呼び出し順序分析結果】

コマンド: design-database

実行フロー:
1. database-design-agent が entity-definition-collector を使用してエンティティ定義を収集
   - 入力: ユーザーからの要求、既存システムの情報
   - 出力: エンティティ一覧、属性リスト
   - 並列実行: 不可（最初のステップ）

2. database-design-agent が normalization-processor を使用して正規化を実施
   - 入力: エンティティ定義（ステップ1の出力）
   - 出力: 正規化されたテーブル定義
   - 並列実行: 不可（ステップ1に依存）
   - 使用する規約: normalization-rules

3. database-design-agent が以下のスキルを並列実行:
   - er-diagram-generator: ER図を生成
     - 入力: 正規化されたテーブル定義（ステップ2の出力）
     - 出力: ER図（Mermaid形式）
   - table-definition-writer: テーブル定義書を作成
     - 入力: 正規化されたテーブル定義（ステップ2の出力）
     - 出力: テーブル定義書（Markdown形式）
   - ddl-script-generator: DDLスクリプトを生成
     - 入力: 正規化されたテーブル定義（ステップ2の出力）
     - 出力: DDLスクリプト
   - 並列実行: 可能（全てステップ2の出力を使用、相互依存なし）

妥当性: OK
- 各ステップの入力と出力が明確
- 依存関係に基づいた順序
- 並列実行可能なステップが適切に識別されている

コマンド: generate-schema

実行フロー:
1. database-design-agent が entity-definition-collector を使用してエンティティ定義を収集
2. database-design-agent が normalization-processor を使用して正規化を実施

妥当性: OK
- 最小限のステップのみ実行
- 依存関係が明確

悪い例:

【呼び出し順序分析結果】

順番に実行する

フェーズ4: 循環依存検出

要素間の循環依存を検出し、報告する。

実施内容:

1. 依存関係グラフを構築する
2. 循環依存を検出するアルゴリズムを実行する
3. 検出された循環依存を報告する
4. 循環依存の影響を評価する
5. 循環依存の解消方法を提案する

検出方法:

• 深さ優先探索（DFS）による循環検出
• トポロジカルソートによる順序確認

良い例:

【循環依存検出結果】

循環依存: 検出されませんでした

依存関係グラフ:

design-database コマンド
  ↓
database-design-agent エージェント
  ↓
entity-definition-collector スキル
normalization-processor スキル
er-diagram-generator スキル
table-definition-writer スキル
ddl-script-generator スキル
database-naming-conventions スキル
normalization-rules スキル

generate-schema コマンド
  ↓
database-design-agent エージェント
  ↓
entity-definition-collector スキル
normalization-processor スキル
database-naming-conventions スキル
normalization-rules スキル

トポロジカルソート結果:
1. database-naming-conventions（コンベンション、依存なし）
2. normalization-rules（コンベンション、依存なし）
3. entity-definition-collector（ワークフロー、コンベンションに依存可能）
4. normalization-processor（ワークフロー、コンベンションに依存可能）
5. er-diagram-generator（ワークフロー、依存なし）
6. table-definition-writer（ワークフロー、依存なし）
7. ddl-script-generator（ワークフロー、依存なし）
8. database-design-agent（エージェント、スキルを使用）
9. design-database（コマンド、エージェントとスキルを使用）
10. generate-schema（コマンド、エージェントとスキルを使用）

アーキテクチャ規約遵守: OK
- エージェントは他の要素を参照していない
- スキルは他のスキルを参照していない
- コマンドのみがエージェントとスキルを参照している

悪い例（循環依存が存在する場合）:

【循環依存検出結果】

循環依存: 検出されました

循環1:
skill-a → skill-b → skill-c → skill-a

問題: スキルが他のスキルを参照している（アーキテクチャ規約違反）
影響: スキルの独立性が損なわれ、再利用性が低下
解消方法:
- スキル間の参照を削除する
- 共通の処理をコンベンションスキルに分離する
- コマンドで依存関係を管理する

循環2:
command-a → agent-b → command-a

問題: コマンドとエージェントが相互参照している
影響: 無限ループの可能性
解消方法:
- エージェントからコマンドへの参照を削除する
- エージェントはスキルのみを使用するようにする

フェーズ5: 推奨提示

分析結果をまとめ、改善提案をユーザーに提示する。

実施内容:

1. 分析結果をサマリー化する
2. 検出された問題をリストアップする
3. アーキテクチャ規約の遵守状況を報告する
4. 改善提案を作成する
5. 次のステップを案内する

提示形式:

【要素関係分析レポート】

プラグイン名: database-design-plugin
分析日時: 2025-11-15

【サマリー】

要素数:
- エージェント: 1個
- スキル: 7個（ワークフロー: 5個、コンベンション: 2個）
- コマンド: 2個

依存関係:
- 総依存数: 14個
- 循環依存: 0個
- アーキテクチャ規約違反: 0個

品質評価: 優良
- 循環依存なし
- アーキテクチャ規約遵守
- 依存関係が明確

【詳細分析結果】

依存関係マップ:
- design-database → database-design-agent, 5つのワークフロースキル, 2つのコンベンションスキル
- generate-schema → database-design-agent, 2つのワークフロースキル, 2つのコンベンションスキル

呼び出し順序:
- design-database: 3ステップ（ステップ3は3つのスキルを並列実行）
- generate-schema: 2ステップ（順次実行）

循環依存: なし

アーキテクチャ規約遵守:
- ✓ エージェントは他の要素を参照していない
- ✓ スキルは他のスキルを参照していない
- ✓ コマンドのみがエージェントとスキルを参照している
- ✓ 依存関係の方向が正しい（コマンド→エージェント→スキル）

【改善提案】

改善点: なし

このプラグインは適切に設計されています。

【推奨事項】

1. 定期的に要素関係を分析し、循環依存が発生していないか確認する
2. 新しい要素を追加する際は、アーキテクチャ規約を遵守する
3. コマンドの実行フローを明確に記述する
4. 並列実行可能なスキルを適切に識別する

【次のステップ】

1. プラグイン全体の品質検証（plugin-validator スキルを使用）
2. プラグインのパッケージング（plugin-packager スキルを使用）

良い例:

分析結果が明確で、問題点、改善提案、推奨事項が示されている。

悪い例:

【要素関係分析レポート】

分析した
問題なし

アウトプット

このスキルは以下を生成する:

• 依存関係マップ: 要素間の依存関係を整理したマッピング
• 呼び出し順序図: コマンドにおけるスキルの呼び出し順序を図示したドキュメント
• 循環依存レポート: 検出された循環依存とその解消方法
• 要素関係分析レポート: 分析結果、問題点、改善提案をまとめたレポート

想定されるエラーと対処法

エラー1: 循環依存が検出された

検出例:

skill-a → skill-b → skill-a

対処法:

• スキル間の参照を削除する
• 共通の処理をコンベンションスキルに分離する
• コマンドで依存関係を管理する

エラー2: アーキテクチャ規約違反

検出例:

エージェントがスキルを直接参照している
スキルが他のスキルを参照している

対処法:

• エージェントからスキルへの直接参照を削除する
• スキル間の参照を削除する
• コマンドで依存関係を管理する

エラー3: 呼び出し順序が不明確

検出例:

実行フロー: スキルを実行する

対処法:

• 実行フローを明確に記述する
• スキルの実行順序を番号付きで記述する
• 並列実行可能なスキルを明示する

ベストプラクティス

• 定期的に要素関係を分析する
• 循環依存を早期に検出して解消する
• アーキテクチャ規約を遵守する
• 依存関係を明確に文書化する
• 呼び出し順序を明示する
• 並列実行可能なスキルを適切に識別する

チェックリスト

要素収集完了時

• プラグインディレクトリ構造が確認されている
• エージェントファイルが収集されている
• スキルファイルが収集されている
• コマンドファイルが収集されている
• 各要素のフロントマター情報が抽出されている

依存関係分析完了時

• 各要素のドキュメント本文が解析されている
• 他の要素への参照が検出されている
• 依存関係マップが作成されている
• 依存の種類が分類されている
• 依存の方向が確認されている

呼び出し順序分析完了時

• 各コマンドの「実行フロー」セクションが解析されている
• スキルの実行順序が抽出されている
• 並列実行可能なスキルが特定されている
• 順次実行が必要なスキルが特定されている
• 実行順序の妥当性が検証されている

循環依存検出完了時

• 依存関係グラフが構築されている
• 循環依存検出アルゴリズムが実行されている
• 検出された循環依存が報告されている
• 循環依存の影響が評価されている
• 循環依存の解消方法が提案されている

推奨提示完了時

• 分析結果がサマリー化されている
• 検出された問題がリストアップされている
• アーキテクチャ規約の遵守状況が報告されている
• 改善提案が作成されている
• 次のステップが案内されている
• ユーザーの承認を得ている

最終確認

• 依存関係マップが作成されている
• 呼び出し順序図が作成されている
• 循環依存レポートが作成されている（該当する場合）
• 要素関係分析レポートが作成されている
• すべてのアウトプットが明確で理解しやすい
• ユーザーが次のステップに進める状態になっている