Initial commit
This commit is contained in:
Zhongwei Li
341
skills/skill-granularity-convention/SKILL.md
Normal file
341
skills/skill-granularity-convention/SKILL.md
Normal file
@@ -0,0 +1,341 @@
|
||||
---
|
||||
name: skill-granularity-convention
|
||||
description: スキルの適切な粒度を定義（1スキル1目的、分割基準、結合基準）する。スキル設計時、粒度判断時、またはユーザーがスキル粒度、1スキル1目的、分割基準、結合基準、スキル設計原則に言及した際に使用する。
|
||||
---
|
||||
|
||||
# Skill Granularity Convention
|
||||
|
||||
## 概要
|
||||
|
||||
このSkillは、スキルの適切な粒度を定義し、1スキル1目的の原則を明確化する。スキルを分割すべき基準、結合すべき基準、適切な粒度の判断方法について指針を提供し、保守性と再利用性の高いスキル設計を実現することを目的とする。
|
||||
|
||||
## 責任範囲
|
||||
|
||||
このSkillは以下の範囲をカバーする:
|
||||
|
||||
- 1スキル1目的の原則の定義
|
||||
- スキル分割の基準と判断方法
|
||||
- スキル結合の基準と判断方法
|
||||
- 適切な粒度の判断指標
|
||||
- 粒度判断のベストプラクティス
|
||||
|
||||
## 基本方針
|
||||
|
||||
- 1スキル1目的を厳守する
|
||||
- 責任範囲を明確に定義する
|
||||
- 複数の目的が含まれる場合は分割を検討する
|
||||
- 過度に細分化しない（実用性を保つ）
|
||||
- コンテキストサイズを最小化する
|
||||
- 再利用性と保守性を重視する
|
||||
|
||||
## 1スキル1目的の原則
|
||||
|
||||
### 原則の定義
|
||||
|
||||
各スキルは、一つの明確な目的を持つべきである。
|
||||
|
||||
**目的の定義:**
|
||||
|
||||
- スキルが達成すべき具体的な成果物または作業内容
|
||||
- 責任範囲セクションで明確に表現できる範囲
|
||||
- ユーザーが「このスキルは〜をする」と一文で説明できる範囲
|
||||
|
||||
### 原則の適用
|
||||
|
||||
スキルの目的が明確であることを確認する:
|
||||
|
||||
- スキルのdescriptionが1行で簡潔に説明できる
|
||||
- 責任範囲が3〜5項目で列挙できる
|
||||
- ワークフローが2〜5フェーズで構成できる（Workflow Skillの場合）
|
||||
- カテゴリが2〜5個で構成できる（Convention Skillの場合）
|
||||
|
||||
良い例:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: api-designer
|
||||
description: RESTful API仕様を設計する
|
||||
---
|
||||
|
||||
## 責任範囲
|
||||
|
||||
- エンドポイントの定義
|
||||
- リクエスト/レスポンス形式の設計
|
||||
- 認証・認可方式の設計
|
||||
```
|
||||
|
||||
（目的が「API仕様を設計する」と明確）
|
||||
|
||||
悪い例:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: system-designer
|
||||
description: システム全体を設計する
|
||||
---
|
||||
|
||||
## 責任範囲
|
||||
|
||||
- アーキテクチャ設計
|
||||
- データベース設計
|
||||
- API設計
|
||||
- UI/UX設計
|
||||
- セキュリティ設計
|
||||
- パフォーマンス設計
|
||||
```
|
||||
|
||||
（目的が広すぎて、複数のスキルに分割すべき）
|
||||
|
||||
## スキル分割の基準
|
||||
|
||||
### 分割すべきケース
|
||||
|
||||
以下の場合は、スキルを分割することを検討する:
|
||||
|
||||
1. **複数の異なる目的が含まれる場合**
|
||||
- 一つのスキルで複数の成果物を生成する
|
||||
- 責任範囲が6項目以上ある
|
||||
- descriptionが2文以上必要になる
|
||||
|
||||
2. **ワークフローが複雑すぎる場合**
|
||||
- ワークフローのフェーズが6個以上ある
|
||||
- 各フェーズの実施内容が5項目以上ある
|
||||
- フェーズ間の依存関係が複雑である
|
||||
|
||||
3. **カテゴリが多すぎる場合**
|
||||
- カテゴリが6個以上ある（Convention Skillの場合）
|
||||
- 各カテゴリのルールが5項目以上ある
|
||||
- カテゴリ間の関連性が薄い
|
||||
|
||||
4. **規約部分が肥大化する場合**
|
||||
- Workflow Skillに含まれる規約が大量にある
|
||||
- 規約の説明が長く、ワークフローの理解を妨げる
|
||||
- 規約を他のスキルでも再利用したい
|
||||
|
||||
### 分割方法
|
||||
|
||||
#### パターン1: 目的別に分割
|
||||
|
||||
システム設計スキルを目的別に分割:
|
||||
|
||||
- アーキテクチャ設計スキル
|
||||
- データベース設計スキル
|
||||
- API設計スキル
|
||||
- UI/UX設計スキル
|
||||
|
||||
#### パターン2: フェーズ別に分割
|
||||
|
||||
要件定義スキルをフェーズ別に分割:
|
||||
|
||||
- 要件収集スキル
|
||||
- 要件整理スキル
|
||||
- 要件検証スキル
|
||||
|
||||
#### パターン3: 規約を分離
|
||||
|
||||
コード生成スキルから規約を分離:
|
||||
|
||||
- コード生成スキル（Workflow Skill）
|
||||
- コーディング規約スキル（Convention Skill）
|
||||
|
||||
良い例:
|
||||
|
||||
```text
|
||||
分割前:
|
||||
- system-designer（システム全体を設計する）
|
||||
|
||||
分割後:
|
||||
- architecture-designer（システムアーキテクチャを設計する）
|
||||
- database-schema-designer（データベーススキーマを設計する）
|
||||
- api-designer（RESTful API仕様を設計する）
|
||||
- ui-component-architect（UIコンポーネント構成を設計する）
|
||||
```
|
||||
|
||||
悪い例:
|
||||
|
||||
```text
|
||||
分割前:
|
||||
- api-designer（RESTful API仕様を設計する）
|
||||
|
||||
分割後:
|
||||
- endpoint-designer（エンドポイントを設計する）
|
||||
- request-designer（リクエスト形式を設計する）
|
||||
- response-designer（レスポンス形式を設計する）
|
||||
- auth-designer（認証方式を設計する）
|
||||
```
|
||||
|
||||
（過度に細分化されており、実用性が低い）
|
||||
|
||||
## スキル結合の基準
|
||||
|
||||
### 結合すべきケース
|
||||
|
||||
以下の場合は、スキルを結合することを検討する:
|
||||
|
||||
1. **スキルが小さすぎる場合**
|
||||
- 責任範囲が1〜2項目しかない
|
||||
- ワークフローが1フェーズしかない
|
||||
- 単独では実用的でない
|
||||
|
||||
2. **スキル間の依存関係が強い場合**
|
||||
- 常に一緒に実行される
|
||||
- 一方のスキルの出力が他方の入力になる
|
||||
- 分離することで理解が困難になる
|
||||
|
||||
3. **重複が多い場合**
|
||||
- 複数のスキルで同じ規約やガイドラインを記述している
|
||||
- 同じ前提条件や制約事項を持っている
|
||||
- 統合することで重複を削減できる
|
||||
|
||||
### 結合方法
|
||||
|
||||
#### パターン1: 関連する作業を統合
|
||||
|
||||
エンドポイント設計、リクエスト設計、レスポンス設計を統合:
|
||||
|
||||
- API設計スキル（すべてを含む）
|
||||
|
||||
#### パターン2: 規約を直接記述
|
||||
|
||||
コード生成スキルに規約を直接記述:
|
||||
|
||||
- コード生成スキル（規約を含む）
|
||||
|
||||
良い例:
|
||||
|
||||
```text
|
||||
結合前:
|
||||
- endpoint-designer（エンドポイントを設計する）
|
||||
- request-designer（リクエスト形式を設計する）
|
||||
- response-designer（レスポンス形式を設計する）
|
||||
|
||||
結合後:
|
||||
- api-designer（RESTful API仕様を設計する）
|
||||
```
|
||||
|
||||
悪い例:
|
||||
|
||||
```text
|
||||
結合前:
|
||||
- architecture-designer（システムアーキテクチャを設計する）
|
||||
- database-schema-designer（データベーススキーマを設計する）
|
||||
- api-designer（RESTful API仕様を設計する）
|
||||
|
||||
結合後:
|
||||
- system-designer（システム全体を設計する）
|
||||
```
|
||||
|
||||
（目的が広すぎて、1スキル1目的の原則に反する）
|
||||
|
||||
## 適切な粒度の判断方法
|
||||
|
||||
### 判断指標
|
||||
|
||||
以下の指標を使用して、スキルの粒度が適切かどうかを判断する:
|
||||
|
||||
1. **descriptionの明確さ**
|
||||
- 1行50文字以内で説明できる → 適切
|
||||
- 2文以上必要 → 分割を検討
|
||||
|
||||
2. **責任範囲の項目数**
|
||||
- 3〜5項目 → 適切
|
||||
- 1〜2項目 → 結合を検討
|
||||
- 6項目以上 → 分割を検討
|
||||
|
||||
3. **ワークフローのフェーズ数（Workflow Skill）**
|
||||
- 2〜5フェーズ → 適切
|
||||
- 1フェーズ → 結合を検討
|
||||
- 6フェーズ以上 → 分割を検討
|
||||
|
||||
4. **カテゴリ数（Convention Skill）**
|
||||
- 2〜5カテゴリ → 適切
|
||||
- 1カテゴリ → 結合を検討
|
||||
- 6カテゴリ以上 → 分割を検討
|
||||
|
||||
5. **ドキュメントサイズ**
|
||||
- 200〜400行 → 適切
|
||||
- 200行未満 → 結合を検討
|
||||
- 400行以上 → 分割を検討
|
||||
|
||||
### 判断フロー
|
||||
|
||||
```text
|
||||
1. descriptionが1行で説明できるか？
|
||||
├─ はい → 2へ
|
||||
└─ いいえ → 分割を検討
|
||||
|
||||
2. 責任範囲が3〜5項目か？
|
||||
├─ はい → 3へ
|
||||
├─ いいえ（1〜2項目） → 結合を検討
|
||||
└─ いいえ（6項目以上） → 分割を検討
|
||||
|
||||
3. ワークフロー/カテゴリが2〜5個か？
|
||||
├─ はい → 適切な粒度
|
||||
├─ いいえ（1個） → 結合を検討
|
||||
└─ いいえ（6個以上） → 分割を検討
|
||||
```
|
||||
|
||||
## ベストプラクティス
|
||||
|
||||
### 実用性を重視する
|
||||
|
||||
- 理論的に分割可能でも、実用性がなければ分割しない
|
||||
- ユーザーが使いやすい粒度を優先する
|
||||
- コマンドで組み合わせることを前提に設計する
|
||||
|
||||
### コンテキストサイズを最小化する
|
||||
|
||||
- 不要な情報を含めない
|
||||
- 規約やガイドラインは必要最小限にする
|
||||
- 他のスキルと重複する内容を避ける
|
||||
|
||||
### 再利用性を考慮する
|
||||
|
||||
- 複数のコマンドから使用されるスキルは独立させる
|
||||
- 特定のコマンド専用のスキルは統合を検討する
|
||||
|
||||
### 保守性を確保する
|
||||
|
||||
- 変更頻度が異なる内容は分離する
|
||||
- 安定した部分と変更される部分を分ける
|
||||
|
||||
## チェックリスト
|
||||
|
||||
### スキル作成時
|
||||
|
||||
- [ ] descriptionが1行50文字以内で説明できる
|
||||
- [ ] 責任範囲が3〜5項目である
|
||||
- [ ] ワークフロー/カテゴリが2〜5個である
|
||||
- [ ] 1スキル1目的の原則を守っている
|
||||
- [ ] 複数の異なる目的が含まれていない
|
||||
|
||||
### スキル分割検討時
|
||||
|
||||
- [ ] 複数の異なる目的が含まれているか確認した
|
||||
- [ ] ワークフローが複雑すぎないか確認した
|
||||
- [ ] カテゴリが多すぎないか確認した
|
||||
- [ ] 規約部分が肥大化していないか確認した
|
||||
- [ ] 分割後の各スキルが実用的であるか確認した
|
||||
|
||||
### スキル結合検討時
|
||||
|
||||
- [ ] スキルが小さすぎないか確認した
|
||||
- [ ] スキル間の依存関係が強いか確認した
|
||||
- [ ] 重複が多いか確認した
|
||||
- [ ] 結合後も1スキル1目的の原則を守れるか確認した
|
||||
|
||||
### 粒度判断時
|
||||
|
||||
- [ ] descriptionの明確さを確認した
|
||||
- [ ] 責任範囲の項目数を確認した
|
||||
- [ ] ワークフロー/カテゴリ数を確認した
|
||||
- [ ] ドキュメントサイズを確認した
|
||||
- [ ] 実用性を考慮した
|
||||
|
||||
### 最終確認
|
||||
|
||||
- [ ] 適切な粒度になっている
|
||||
- [ ] 1スキル1目的の原則が守られている
|
||||
- [ ] 実用性がある
|
||||
- [ ] コンテキストサイズが最小化されている
|
||||
- [ ] 再利用性と保守性が確保されている
|
||||
Reference in New Issue
Block a user