majiayu000 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の場合）
良い例:
---
name: api-designer
description: RESTful API仕様を設計する
---
## 責任範囲
- エンドポイントの定義
- リクエスト/レスポンス形式の設計
- 認証・認可方式の設計
（目的が「API仕様を設計する」と明確）
悪い例:
---
name: system-designer
description: システム全体を設計する
---
## 責任範囲
- アーキテクチャ設計
- データベース設計
- API設計
- UI/UX設計
- セキュリティ設計
- パフォーマンス設計
（目的が広すぎて、複数のスキルに分割すべき）
スキル分割の基準
分割すべきケース
以下の場合は、スキルを分割することを検討する:
複数の異なる目的が含まれる場合
- 一つのスキルで複数の成果物を生成する
- 責任範囲が6項目以上ある
- descriptionが2文以上必要になる
ワークフローが複雑すぎる場合
- ワークフローのフェーズが6個以上ある
- 各フェーズの実施内容が5項目以上ある
- フェーズ間の依存関係が複雑である
カテゴリが多すぎる場合
- カテゴリが6個以上ある（Convention Skillの場合）
- 各カテゴリのルールが5項目以上ある
- カテゴリ間の関連性が薄い
規約部分が肥大化する場合
- Workflow Skillに含まれる規約が大量にある
- 規約の説明が長く、ワークフローの理解を妨げる
- 規約を他のスキルでも再利用したい
分割方法
パターン1: 目的別に分割
システム設計スキルを目的別に分割:
- アーキテクチャ設計スキル
- データベース設計スキル
- API設計スキル
- UI/UX設計スキル
パターン2: フェーズ別に分割
要件定義スキルをフェーズ別に分割:
- 要件収集スキル
- 要件整理スキル
- 要件検証スキル
パターン3: 規約を分離
コード生成スキルから規約を分離:
- コード生成スキル（Workflow Skill）
- コーディング規約スキル（Convention Skill）
良い例:
分割前:
- system-designer（システム全体を設計する）
分割後:
- architecture-designer（システムアーキテクチャを設計する）
- database-schema-designer（データベーススキーマを設計する）
- api-designer（RESTful API仕様を設計する）
- ui-component-architect（UIコンポーネント構成を設計する）
悪い例:
分割前:
- api-designer（RESTful API仕様を設計する）
分割後:
- endpoint-designer（エンドポイントを設計する）
- request-designer（リクエスト形式を設計する）
- response-designer（レスポンス形式を設計する）
- auth-designer（認証方式を設計する）
（過度に細分化されており、実用性が低い）
スキル結合の基準
結合すべきケース
以下の場合は、スキルを結合することを検討する:
スキルが小さすぎる場合
- 責任範囲が1〜2項目しかない
- ワークフローが1フェーズしかない
- 単独では実用的でない
スキル間の依存関係が強い場合
- 常に一緒に実行される
- 一方のスキルの出力が他方の入力になる
- 分離することで理解が困難になる
重複が多い場合
- 複数のスキルで同じ規約やガイドラインを記述している
- 同じ前提条件や制約事項を持っている
- 統合することで重複を削減できる
結合方法
パターン1: 関連する作業を統合
エンドポイント設計、リクエスト設計、レスポンス設計を統合:
- API設計スキル（すべてを含む）
パターン2: 規約を直接記述
コード生成スキルに規約を直接記述:
- コード生成スキル（規約を含む）
良い例:
結合前:
- endpoint-designer（エンドポイントを設計する）
- request-designer（リクエスト形式を設計する）
- response-designer（レスポンス形式を設計する）
結合後:
- api-designer（RESTful API仕様を設計する）
悪い例:
結合前:
- architecture-designer（システムアーキテクチャを設計する）
- database-schema-designer（データベーススキーマを設計する）
- api-designer（RESTful API仕様を設計する）
結合後:
- system-designer（システム全体を設計する）
（目的が広すぎて、1スキル1目的の原則に反する）
適切な粒度の判断方法
判断指標
以下の指標を使用して、スキルの粒度が適切かどうかを判断する:
descriptionの明確さ
- 1行50文字以内で説明できる → 適切
- 2文以上必要 → 分割を検討
責任範囲の項目数
- 3〜5項目 → 適切
- 1〜2項目 → 結合を検討
- 6項目以上 → 分割を検討
ワークフローのフェーズ数（Workflow Skill）
- 2〜5フェーズ → 適切
- 1フェーズ → 結合を検討
- 6フェーズ以上 → 分割を検討
カテゴリ数（Convention Skill）
- 2〜5カテゴリ → 適切
- 1カテゴリ → 結合を検討
- 6カテゴリ以上 → 分割を検討
ドキュメントサイズ
- 200〜400行 → 適切
- 200行未満 → 結合を検討
- 400行以上 → 分割を検討
判断フロー
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目的の原則が守られている
- 実用性がある
- コンテキストサイズが最小化されている
- 再利用性と保守性が確保されている