318 lines
10 KiB
Markdown
318 lines
10 KiB
Markdown
---
|
||
name: element-definition-convention
|
||
description: プラグイン要素の定義ルール（命名規則、必須項目、記述フォーマット）を定義する。プラグイン要素作成時、エージェント・スキル・コマンド定義時、またはユーザーが命名規則、フロントマター、必須項目、記述フォーマットに言及した際に使用する。
|
||
---
|
||
|
||
# Element Definition Convention
|
||
|
||
## 概要
|
||
|
||
このSkillは、プラグイン要素（エージェント、スキル、コマンド）の定義ルールを明確化する。命名規則、フロントマターの必須項目、必須セクション、ドキュメント記述フォーマットについて標準を定義し、一貫性のあるプラグイン要素の作成を実現することを目的とする。
|
||
|
||
## 責任範囲
|
||
|
||
このSkillは以下の範囲をカバーする:
|
||
|
||
- プラグイン要素（エージェント、スキル、コマンド）の命名規則
|
||
- フロントマターの必須項目と記述ルール
|
||
- 必須セクション（概要、責任範囲、基本方針など）の定義
|
||
- ドキュメント記述フォーマットと記述原則
|
||
- チェックリストの作成ガイドライン
|
||
|
||
## 基本方針
|
||
|
||
- 命名はケバブケース（kebab-case）を使用する
|
||
- フロントマターにはname、descriptionを必須とする
|
||
- 必須セクションを統一し、一貫性を保つ
|
||
- ドキュメントは日本語・常体で記述する
|
||
- 簡潔で明確な文章を使用する
|
||
- 箇条書きを活用して情報を整理する
|
||
|
||
## 命名規則
|
||
|
||
### エージェントの命名
|
||
|
||
エージェントの役割を表す名前を使用する。
|
||
|
||
**命名パターン:**
|
||
|
||
- `[役割]-agent`の形式を使用する
|
||
- 責任範囲が明確にわかる名前にする
|
||
- ケバブケース（例: requirements-agent, design-agent）を使用する
|
||
|
||
良い例:
|
||
|
||
```text
|
||
requirements-agent
|
||
design-agent
|
||
implementation-agent
|
||
test-agent
|
||
```
|
||
|
||
悪い例:
|
||
|
||
```text
|
||
RequirementsAgent (キャメルケースは使用しない)
|
||
req-agent (省略形は避ける)
|
||
requirements_agent (スネークケースは使用しない)
|
||
agent-requirements (順序が逆)
|
||
```
|
||
|
||
### スキルの命名
|
||
|
||
スキルの目的を表す名前を使用する。
|
||
|
||
**Workflow Skillの命名パターン:**
|
||
|
||
- 動詞を含む名前にする（例: code-generator, api-designer）
|
||
- 「何を生成するか」「何を設計するか」を明確にする
|
||
- ケバブケース（例: database-schema-designer）を使用する
|
||
|
||
**Convention Skillの命名パターン:**
|
||
|
||
- 規約の対象を表す名前にする（例: coding-conventions, documentation-standards）
|
||
- 複数形を使用することが多い（conventions, standards, guidelinesなど）
|
||
- ケバブケース（例: security-guidelines）を使用する
|
||
|
||
良い例（Workflow Skill）:
|
||
|
||
```text
|
||
code-generator
|
||
api-designer
|
||
database-schema-designer
|
||
requirements-structurer
|
||
```
|
||
|
||
良い例（Convention Skill）:
|
||
|
||
```text
|
||
coding-conventions
|
||
documentation-standards
|
||
security-guidelines
|
||
interaction-guidelines
|
||
```
|
||
|
||
悪い例:
|
||
|
||
```text
|
||
CodeGenerator (キャメルケースは使用しない)
|
||
api_designer (スネークケースは使用しない)
|
||
gen-code (省略形は避ける)
|
||
generator (目的が不明確)
|
||
```
|
||
|
||
### コマンドの命名
|
||
|
||
コマンドの機能を表す名前を使用する。
|
||
|
||
**命名パターン:**
|
||
|
||
- ユーザーが覚えやすい簡潔な名前にする
|
||
- 動詞または名詞を使用する（例: requirements, design, generate）
|
||
- ケバブケース（例: test-run）を使用する
|
||
- 複数単語の場合は、意味が明確になるようにする
|
||
|
||
良い例:
|
||
|
||
```text
|
||
requirements
|
||
design
|
||
task
|
||
implement
|
||
test-run
|
||
generate-plugin
|
||
```
|
||
|
||
悪い例:
|
||
|
||
```text
|
||
req (省略形は避ける)
|
||
RequirementsCommand (キャメルケースは使用しない)
|
||
requirements_command (スネークケースは使用しない)
|
||
command-requirements (順序が逆)
|
||
```
|
||
|
||
## フロントマターの定義
|
||
|
||
すべてのプラグイン要素のマークダウンファイルには、フロントマターを記述する。
|
||
|
||
**必須項目:**
|
||
|
||
- `name`: 要素の名前（ケバブケース）
|
||
- `description`: 要素の簡潔な説明（1行、50文字以内を目安）
|
||
|
||
**フォーマット:**
|
||
|
||
```markdown
|
||
---
|
||
name: 要素名（ケバブケース）
|
||
description: 簡潔な説明（1行、50文字以内）
|
||
---
|
||
```
|
||
|
||
良い例:
|
||
|
||
```markdown
|
||
---
|
||
name: code-generator
|
||
description: 設計仕様からソースコードを生成する
|
||
---
|
||
```
|
||
|
||
悪い例:
|
||
|
||
```markdown
|
||
---
|
||
name: CodeGenerator
|
||
description: このスキルは、設計仕様書を入力として受け取り、それに基づいてソースコードを自動的に生成するための機能を提供します。生成されるコードは、プロジェクトのコーディング規約に準拠し、テストケースも含まれます。
|
||
---
|
||
（nameがキャメルケース、descriptionが長すぎる）
|
||
```
|
||
|
||
## 必須セクションの定義
|
||
|
||
### エージェントの必須セクション
|
||
|
||
1. **概要**: エージェントの目的と役割を簡潔に説明（1〜2段落）
|
||
2. **責任範囲**: エージェントが責任を持つ範囲を箇条書き（3〜5項目）
|
||
3. **基本方針**: エージェントの行動指針（該当する場合のみ）
|
||
|
||
### スキルの必須セクション
|
||
|
||
1. **概要**: スキルの目的と実行内容を簡潔に説明（1〜2段落）
|
||
2. **責任範囲**: スキルがカバーする範囲を箇条書き（3〜5項目）
|
||
3. **基本方針**: スキルの実行原則（該当する場合のみ）
|
||
4. **ワークフロー/カテゴリ**:
|
||
- Workflow Skill: フェーズごとの実施内容
|
||
- Convention Skill: カテゴリ別の規約・ガイドライン
|
||
5. **アウトプット**: スキルが生成する成果物（Workflow Skillの場合）
|
||
6. **チェックリスト**: 各フェーズ/カテゴリのチェック項目
|
||
|
||
### コマンドの必須セクション
|
||
|
||
1. **概要**: コマンドの目的と機能を簡潔に説明（1〜2段落）
|
||
2. **使用するエージェント**: コマンドが使用するエージェント
|
||
3. **使用するスキル**: コマンドが使用するスキルのリスト
|
||
4. **実行フロー**: スキルの実行順序とデータの受け渡し
|
||
5. **成果物**: コマンド実行後の出力先とファイル構成
|
||
|
||
## ドキュメント記述の原則
|
||
|
||
プラグイン要素のドキュメント記述時は、以下の原則に従う:
|
||
|
||
- 日本語・常体で記述する
|
||
- 簡潔で明確な文章を使用する
|
||
- 箇条書きを活用して情報を整理する
|
||
- 具体例を記述する場合は、良い例/悪い例の形式を使用する
|
||
|
||
良い例:
|
||
|
||
```markdown
|
||
## 概要
|
||
|
||
このSkillは、設計仕様からソースコードを生成する。コーディング規約に準拠したコードを自動生成し、開発効率を向上させることを目的とする。
|
||
|
||
## 責任範囲
|
||
|
||
このSkillは以下の範囲をカバーする:
|
||
|
||
- 設計仕様の解析とコード構造の決定
|
||
- コーディング規約に準拠したソースコードの生成
|
||
- 生成コードの検証とフォーマット
|
||
```
|
||
|
||
悪い例:
|
||
|
||
```markdown
|
||
## 概要
|
||
|
||
このSkillは、設計仕様書を入力として受け取り、それに基づいてソースコードを自動的に生成するための機能を提供します。生成されるコードは、プロジェクトのコーディング規約に準拠し、テストケースも含まれます。また、コードレビューの観点からも最適化されており、保守性の高いコードを生成することができます。
|
||
|
||
## 責任範囲
|
||
|
||
このSkillは以下の範囲をカバーします:
|
||
|
||
・設計仕様の解析
|
||
・コード生成
|
||
・検証
|
||
```
|
||
|
||
（文章が冗長、敬体を使用、箇条書きのマーカーが不統一）
|
||
|
||
## チェックリストの作成ガイドライン
|
||
|
||
### チェックリストの構成
|
||
|
||
- フェーズごと/カテゴリごとにチェックリストを作成する
|
||
- 最終確認用のチェックリストを含める
|
||
- 具体的で検証可能な項目を記述する
|
||
- 各項目は明確で検証可能にする（「〜を確認した」「〜が含まれている」のような表現）
|
||
|
||
良い例:
|
||
|
||
```markdown
|
||
### フェーズ1完了時
|
||
|
||
- [ ] 設計仕様書を読み込んだ
|
||
- [ ] コード構造を決定した
|
||
- [ ] 必要なファイルパスを特定した
|
||
|
||
### 最終確認
|
||
|
||
- [ ] 生成コードがコーディング規約に準拠している
|
||
- [ ] すべてのファイルが正しいパスに配置されている
|
||
- [ ] 構文エラーがない
|
||
```
|
||
|
||
悪い例:
|
||
|
||
```markdown
|
||
### チェックリスト
|
||
|
||
- [ ] 設計仕様を確認
|
||
- [ ] コード生成
|
||
- [ ] 良いコードになっている
|
||
```
|
||
|
||
（フェーズ分けがない、項目が曖昧、検証不可能な表現）
|
||
|
||
## チェックリスト
|
||
|
||
### 命名規則確認時
|
||
|
||
- [ ] ケバブケース（kebab-case）を使用している
|
||
- [ ] エージェント名は責任範囲が明確である
|
||
- [ ] スキル名は目的が明確である（Workflow Skillは動詞を含む、Convention Skillは規約の対象を表す）
|
||
- [ ] コマンド名は簡潔で覚えやすい
|
||
- [ ] 省略形を避けている
|
||
|
||
### フロントマター作成時
|
||
|
||
- [ ] nameフィールドがケバブケースで記述されている
|
||
- [ ] descriptionフィールドが1行50文字以内である
|
||
- [ ] descriptionが簡潔で要素の目的を明確に説明している
|
||
|
||
### 必須セクション作成時
|
||
|
||
- [ ] 概要セクションが1〜2段落で簡潔に記述されている
|
||
- [ ] 責任範囲が箇条書きで3〜5項目記述されている
|
||
- [ ] 基本方針が明確である（該当する場合）
|
||
- [ ] ワークフロー/カテゴリが適切に構成されている
|
||
- [ ] チェックリストが作成されている
|
||
|
||
### ドキュメント記述確認時
|
||
|
||
- [ ] 日本語・常体で記述されている
|
||
- [ ] 簡潔で明確な文章を使用している
|
||
- [ ] 箇条書きを活用して情報が整理されている
|
||
- [ ] リストのインデントがスペース2個で統一されている
|
||
- [ ] 良い例/悪い例が具体的で実用的である（該当する場合）
|
||
|
||
### 最終確認
|
||
|
||
- [ ] すべての命名規則が守られている
|
||
- [ ] フロントマターが正しく記述されている
|
||
- [ ] 必須セクションがすべて含まれている
|
||
- [ ] ドキュメント記述の原則に従っている
|
||
- [ ] チェックリストが適切に作成されている
|