skill-granularity-convention

# 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（RESTfu