Plugin Architecture Convention

Plugin Architecture Convention

概要

このSkillは、プラグイン全体のアーキテクチャ設計原則を定義する。プラグインを構成する要素（エージェント、スキル、コマンド）の役割分担、依存関係管理、独立性の確保、汎用性の維持について明確な指針を提供し、再利用可能で保守性の高いプラグイン設計を実現することを目的とする。

責任範囲

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

• プラグイン要素（エージェント、スキル、コマンド）の定義と役割
• 要素間の依存関係管理の原則
• 独立性の原則（他要素への参照禁止ルール）
• 汎用性の原則（固有名詞の使用禁止ルール）
• スキルの分類（Workflow Skill / Convention Skill）
• コマンドの責任範囲と役割
• プラグイン要素の命名と記述のガイドライン

基本方針

• すべてのエージェントおよびすべてのスキルは互いに依存しない
• 各要素は独立した要素として確立される
• 依存関係についてはすべてコマンドが引き受ける
• 固有名詞を含めず、汎用的な表現を使用する
• 1スキル1目的の原則を厳守する
• 再利用可能で保守性の高い設計を重視する

プラグインの構造

ディレクトリ構成

プラグインは以下のディレクトリ構造を持つ:

[プラグイン名]/
├── agents/
│   └── [エージェント名].md
├── skills/
│   ├── [Convention Skill名]/
│   │   └── SKILL.md
│   │   ※ Convention Skillはtemplates/ディレクトリを持たない
│   ├── [Workflow Skill (テンプレートなし)名]/
│   │   └── SKILL.md
│   └── [Workflow Skill (テンプレートあり)名]/
│       ├── SKILL.md
│       └── templates/
│           ├── [テンプレート1].md
│           └── [テンプレート2].md
└── commands/
    └── [コマンド名].md

注釈:

• Convention Skillは規約を定義するだけで、templates/ディレクトリを持たない
• Workflow Skillは、ドキュメント生成を含む場合のみtemplates/ディレクトリを持つ
• テンプレートファイルは、ユーザーのプロジェクトにコピーされ使用される

ファイルの配置ルール

エージェント

• 配置場所: [プラグイン名]/agents/[エージェント名].md
• ファイル名: エージェント名をケバブケースで記述（例: plugin-development-agent.md）
• ファイル形式: マークダウン（.md）

スキル

• Convention Skill配置場所: [プラグイン名]/skills/[スキル名]/SKILL.md
• Workflow Skill配置場所: [プラグイン名]/skills/[スキル名]/SKILL.md
• スキル名: ケバブケースで記述（例: command-generator）
• ファイル名: 必ず SKILL.md とする（大文字）
• テンプレートファイル: Workflow Skillの場合、必要に応じて templates/ ディレクトリを同じディレクトリ内に作成

コマンド

• 配置場所: [プラグイン名]/commands/[コマンド名].md
• ファイル名: コマンド名をケバブケースで記述（例: generate-agent.md）
• ファイル形式: マークダウン（.md）

出力パスの記述形式

コマンドやスキルのドキュメント内で出力先を記述する際は、以下の形式を使用する:

• [プラグインディレクトリ]/agents/[エージェント名].md
• [プラグインディレクトリ]/skills/[スキル名]/SKILL.md
• [プラグインディレクトリ]/commands/[コマンド名].md

プレースホルダー [プラグインディレクトリ] は、ユーザーが実際に使用するプラグインのルートディレクトリを指す。固有のプラグイン名を含めず、汎用的な表現を維持する。

プラグイン要素の定義

エージェント（Agent）

エージェントは責任範囲が定義されている要素である。

特徴:

• 「誰が何に対して責任を持つか」を明確にする
• 具体的な作業内容やワークフローは定義されていない
• フェーズ全体を統括する役割を担う

例:

• Requirements Agent: 要件定義フェーズ全体に対する責任を持つ
• Design Agent: 詳細設計フェーズ全体に対する責任を持つ

スキル（Skill）

スキルは単一作業のワークフローが記述されている要素である。

特徴:

• 一つの明確な目的を持った作業の手順が定義されている
• その作業に必要な規約やガイドラインも含まれている
• 1スキル1目的の原則に従う

例:

• Code Generator: 設計仕様からソースコードを生成する
• API Designer: API仕様を設計する
• Coding Convention: コーディング規約を定義する

コマンド（Command）

コマンドはエージェントと複数のスキルを組み合わせて作業を行うためのワークフローが定義されている要素である。

特徴:

• ユーザーが実際に実行する指示である
• 一つのコマンドが複数のスキルを適切な順序で呼び出す
• フェーズ全体の作業を進める

例:

• requirements: 要件定義フェーズの開始から完了までを管理
• design: 詳細設計フェーズの開始から完了までを管理

スキルの分類

スキルは以下の2種類に分類される。

Workflow Skill（ワークフロースキル）

実際にワークフローに沿って具体的な作業を実行するスキルである。

特徴:

• アウトプットを生成することが主な目的
• 作業の手順が明確に定義されている
• 具体的な成果物を作成する

例:

• Code Generator: 設計仕様からソースコードを生成する
• API Designer: API仕様を設計する
• Database Schema Designer: データベーススキーマを設計する

テンプレートファイル:

• Workflow Skillがドキュメント生成を含む場合、skills/[スキル名]/templates/配下にテンプレートファイルを配置する
• テンプレートファイルは、ユーザーのプロジェクトにコピーされ、プロジェクト固有の情報を入力する際に使用される
• テンプレートファイルを持たないWorkflow Skillも存在する（例: データ変換、分析処理など）

テンプレートファイルを持つ例:

• requirement-analysis-workflow: templates/requirements-document.md
• test-specification-workflow: templates/test-specification.md, templates/test-case.md

テンプレートファイルを持たない例:

• data-transformation-workflow: データ変換処理のみを実行
• code-analysis-workflow: コード分析のみを実行

Convention Skill（コンベンションスキル）

規約やガイドラインが定義されているスキルである。

特徴:

• ワークフロースキル内に規約を記述すると内容が肥大化する場合に分割
• 基本はワークフロースキルの中に規約を直接記述する
• スキルの肥大化を避ける目的で分離する

例:

• Coding Convention: 変数命名規則、インデントルールなど
• API Design Guideline: RESTful設計原則、エンドポイント命名規則など
• Documentation Standard: ドキュメント記述標準、構造の標準化など

テンプレートファイル:

• Convention Skillは規約・ガイドラインを定義するだけで、テンプレートファイルを持たない
• Convention Skill Generator（スキル生成時）はconvention-skill-template-*.mdを使用してSKILL.mdを生成するが、生成されたConvention Skill自体にはtemplates/ディレクトリを作成しない

依存関係管理の原則

コマンドが依存関係を管理する

すべてのエージェントおよびすべてのスキルは互いに依存しない。コマンドが以下の責任を持つ:

• どのエージェントがどのスキルを使用するかを定義
• 成果物のファイルパスやディレクトリ構造を定義
• スキル間のデータの受け渡しを定義
• 実行順序とワークフローを定義

エージェントとスキルの独立性

エージェントとスキルは再利用可能な独立したコンポーネントとして設計される。

原則:

• エージェントは他のエージェントに依存しない
• スキルは他のスキルに依存しない
• エージェントは特定のスキルに依存しない
• スキルは特定のエージェントに依存しない

要素の責任分担原則

プラグイン開発において、Analyzer（分析スキル）とGenerator（生成スキル）の責任範囲を明確に分離する。

Analyzerの責任範囲

Analyzerは分析と特定に責任を持つ。

責任:

• 必要な要素（機能、スキル、テンプレートなど）を分析する
• 何が必要かを特定し、リストとして出力する
• 要素間の関係を分析する
• テンプレートファイルの必要性を特定する
• どのスキルにどのテンプレートが必要かを分析する

禁止事項:

• ファイルを生成してはいけない
• ファイルを配置してはいけない
• 実装作業を行ってはいけない

例:

• domain-analyzer: 業務領域を分析し、必要な機能とテンプレートファイルリストを出力する
• workflow-analyzer: 作業フローを分析し、必要なスキルとテンプレートファイルリストを出力する

Generatorの責任範囲

Generatorは生成と配置に責任を持つ。

責任:

• 分析結果に基づいてファイルを生成する
• 生成したファイルを適切な場所に配置する
• SKILL.mdファイルを生成する
• テンプレートファイルを生成する（Workflow Skillでドキュメント生成を含む場合）
• markdownlint検証を実施する

原則:

• Analyzerの出力（テンプレートファイルリスト）を入力として受け取る
• Convention Skillにはテンプレートファイルを生成しない
• Workflow Skillには、必要に応じてテンプレートファイルを生成し、skills/[スキル名]/templates/配下に配置する

例:

• convention-skill-generator: Convention SkillのSKILL.mdを生成する（テンプレートファイルは生成しない）
• workflow-skill-generator: Workflow SkillのSKILL.mdを生成し、必要に応じてテンプレートファイルも生成する

責任分担の具体例

ケース1: 仕様書作成プラグインの開発

1. domain-analyzer（分析）:

   • 「要件定義書作成」機能を特定
   • requirements-document.md テンプレートが必要と判断
   • テンプレートファイルリストを出力: [{skill: "requirement-analysis-workflow", templates: ["requirements-document.md"]}]

2. workflow-skill-generator（生成）:

   • requirement-analysis-workflow/SKILL.md を生成
   • requirement-analysis-workflow/templates/requirements-document.md を生成・配置

ケース2: コーディング規約プラグインの開発

1. domain-analyzer（分析）:

   • 「コーディング規約定義」機能を特定
   • Convention Skillと判断
   • テンプレートファイルリストを出力: [] （空）

2. convention-skill-generator（生成）:

   • coding-conventions/SKILL.md を生成
   • テンプレートファイルは生成しない（Convention Skillのため）

独立性の原則（他要素への参照禁止）

参照禁止ルール

エージェントとスキルのドキュメント内で、他のエージェント、スキル、コマンドを参照してはいけない。

重要: この制限はエージェントとスキルのみに適用される。コマンドは依存関係を管理する役割を持つため、エージェントとスキルを明示的に参照することが求められる。

理由:

• 参照先の要素が存在しない環境では使用できない
• 参照先の要素が変更されると、参照元も影響を受ける
• 要素単体での再利用が困難になる
• 他のプロジェクトへの移植性が低下する

必要な情報の記述方法

必要な規約やガイドラインは、各エージェント・スキルのドキュメント内に直接記述するか、汎用的な表現で記載する。

エージェント・スキルの場合:

良い例:

コーディングルールに従う
（具体的なルールは当該スキル内に記述）

ドキュメント記述標準に従う
（具体的な標準は当該スキル内に記述）

要件定義フェーズに対する責任を持つ
（他のエージェントに言及しない）

設計完了後に実行する
（コマンド名を明示しない）

ユーザーとの対話パターンに従う
（具体的なパターンは当該スキル内に記述）

悪い例:

コーディングルールは coding-convention スキルに従う
（他のスキルを参照している）

詳細は documentation-standards スキルを参照
（他のスキルを参照している）

Requirements Agent と連携して動作する
（他のエージェントを参照している）

design コマンドを実行してから使用する
（他のコマンドを参照している）

interaction-guidelines スキルで定義された対話パターンを使用する
（他のスキルを参照している）

コマンドの場合:

良い例:

version-control-agentがversion-control-guidelinesスキルを使用して、現在の変更状況を確認する
（コマンドは依存関係を管理するため、エージェントとスキルを明示的に参照する）

design-agentがapi-design-guidelinesスキルとdocumentation-standardsスキルを使用して、API仕様書を作成する
（複数のスキルを組み合わせて使用することを明示）

汎用性の原則（固有名詞禁止）

固有名詞の使用禁止

すべてのエージェント、スキル、コマンドにおいて、固有名詞を含めない。

対象:

• 組織名、チーム名、企業名
• プロジェクト名、製品名、サービス名
• 特定の技術スタックやツールの名前（汎用的な場合を除く）

理由:

• 再利用性: 他のプロジェクトやチームでも使用できる汎用的な要素にする
• 独立性: 特定の環境やコンテキストに依存しない独立した要素として設計する
• 保守性: 組織名やプロジェクト名が変更されても、要素の更新が不要になる
• 移植性: 異なる環境や組織に簡単に移植できる

コード例やサンプルにおける固有名詞

コード例やサンプルにおいても、固有名詞の使用を避ける。代わりに、以下のような汎用的なプレースホルダーを使用する:

• YourProject: プロジェクト名のプレースホルダー
• YourCompany: 組織名のプレースホルダー
• example.com: ドメイン名のプレースホルダー

良い例（エージェントの記述）:

このエージェントは、すべての要件定義フェーズに対する責任を持つ。

悪い例（エージェントの記述）:

このエージェントは、XYZ社プロジェクトの要件定義フェーズに対する責任を持つ。

良い例（スキルの記述）:

このSkillは、開発されるすべての.NETプロジェクトに適用されるコーディング規約を定義する。

悪い例（スキルの記述）:

このSkillは、ABC社で開発されるすべての.NETプロジェクトに適用されるコーディング規約を定義する。

良い例（コマンドの記述）:

このコマンドは、要件定義フェーズ全体を管理し、要件定義書を生成する。

悪い例（コマンドの記述）:

このコマンドは、XYZ社の要件定義フェーズ全体を管理し、要件定義書を生成する。

良い例（コード例）:

namespace YourProject.Orders;

public class OrderProcessor
{
    // 実装
}

悪い例（コード例）:

namespace RevTechStudio.Orders;

public class OrderProcessor
{
    // 実装
}

コマンドの責任範囲

コマンドの役割

コマンドは以下の責任を持つ:

• どのエージェントがどのスキルを使用するかを定義
• 成果物のファイルパスやディレクトリ構造を定義
• スキル間のデータの受け渡しを定義
• 実行順序とワークフローを定義

コマンドの粒度

各フェーズでは1〜2個のコマンドに抑えることで、ユーザーが覚えるべきコマンド数を最小限にする。

例:

• requirements: 要件定義フェーズ全体を管理
• design: 詳細設計フェーズ全体を管理し、設計書の出力先を指定
• task: 設計完了後にタスク分割を実行し、タスクリストの出力先を指定

チェックリスト

エージェント定義時

• 責任範囲が明確に定義されている
• 他のエージェント、スキル、コマンドを参照していない
• 固有名詞を含めていない
• 具体的な作業内容やワークフローを記述していない
• フェーズ全体を統括する役割が明確である
• [プラグイン名]/agents/[エージェント名].md の形式で配置されている
• ファイル名がケバブケースで記述されている

スキル定義時

• 1スキル1目的の原則を守っている
• 単一作業のワークフローが明確に定義されている
• 他のエージェント、スキル、コマンドを参照していない
• 固有名詞を含めていない
• 必要な規約やガイドラインをスキル内に直接記述している
• Workflow SkillまたはConvention Skillのいずれかに分類できる
• Convention Skillの場合、templates/ディレクトリを作成していない
• Workflow Skillでドキュメント生成を含む場合、templates/ディレクトリにテンプレートファイルを配置している
• テンプレートファイルのフロントマターが適切に定義されている（name, about, title等）
• [プラグイン名]/skills/[スキル名]/SKILL.md の形式で配置されている
• ファイル名が SKILL.md（大文字）になっている
• ディレクトリ名がケバブケースで記述されている

コマンド定義時

• どのエージェントがどのスキルを使用するかが定義されている
• 成果物のファイルパスやディレクトリ構造が定義されている
• スキル間のデータの受け渡しが定義されている
• 実行順序とワークフローが定義されている
• ユーザーが覚えやすい簡潔な名前である
• 固有名詞を含めていない
• [プラグイン名]/commands/[コマンド名].md の形式で配置されている
• ファイル名がケバブケースで記述されている
• 成果物のパスが [プラグインディレクトリ]/... の形式で記述されている

最終確認

• すべての要素が互いに依存していない
• 依存関係がコマンドで管理されている
• 他要素への参照が含まれていない
• 固有名詞が使用されていない
• 再利用可能で保守性の高い設計になっている
• ドキュメントが明確で理解しやすい
• プラグイン全体が標準のディレクトリ構造に従っている
• すべてのファイルが正しい配置場所に配置されている
• 出力パスの記述が標準形式に従っている