# パターン集

SKILL.mdを簡潔に保ちながら、必要な情報を適切なタイミングで提供するための設計パターン。

## 目次

- 3段階ローディング
- ディレクトリパターン（ハイレベルガイド / ドメイン分割 / 基本と応用 / コード付き）
- 自由度パターン
- ワークフローパターン
- フィードバックループ
- テンプレートパターン
- 条件分岐パターン
- アンチパターン
- サイズ目安

---

## 3段階ローディング

```
Level 1: description（常時）     → トリガー判定（〜100トークン/スキル）
Level 2: SKILL.md（トリガー時）  → 指示・手順（〜5kトークン）
Level 3: references/（必要時）   → 詳細情報（実質無制限）
```

Level 3はファイルシステム上に存在するだけで、アクセスされるまでコンテキストを消費しない。スクリプトは実行のみで、コード自体はコンテキストに入らない（出力のみ）。

---

## ディレクトリパターン

### パターン1: ハイレベルガイド

概要＋クイックスタートをSKILL.mdに、詳細をreferences/に。

```
skill/
├── SKILL.md           # 概要 + クイックスタート
└── references/
    ├── schema.md      # 詳細スキーマ
    └── examples.md    # 使用例
```

**使用場面**: APIドキュメント、チュートリアル系

### パターン2: ドメイン分割

複数ドメインをサポート。必要なドメインのみ読む。

```
skill/
├── SKILL.md           # 選択ガイド + 共通手順
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md
```

**使用場面**: マルチプラットフォーム対応

### パターン3: 基本と応用

基本機能はSKILL.md、高度な機能はreferences/に分離。

```
skill/
├── SKILL.md           # 基本操作
└── references/
    └── advanced.md    # 高度な機能
```

**使用場面**: 基本と応用で複雑さが異なる

### パターン4: コード付きスキル

決定的処理をスクリプトで実行し、SKILL.md は目的・実行方法・出力を記載。

```
skill/
├── SKILL.md           # 目的 + 実行方法 + 出力
├── scripts/
│   └── do-something.ts  # 決定的処理
└── references/ (任意)
```

**使用場面**: ファイルシステム操作、外部ツール連携、状態管理

スクリプトの実行意図を明確にする:
- 「`analyze_form.py` を実行してフィールドを抽出」→ 実行
- 「`analyze_form.py` の抽出アルゴリズムを参照」→ 読む

---

## 自由度パターン

タスクの性質に応じて、指示の具体度を3段階で調整する。

### 高自由度（テキストベースの方針）

ヒューリスティクスが指針となり、文脈で判断が変わり、複数のアプローチが妥当な場合。

```markdown
## コードレビュー

1. コード構造と設計を分析
2. バグや境界ケースの可能性を確認
3. 可読性・保守性の改善を提案
4. プロジェクト規約への準拠を検証
```

### 中自由度（パラメータ付きの擬似コード）

設定が挙動に影響し、ある程度の変動は許容されるが、推奨パターンがある場合。

```markdown
## レポート生成

以下のテンプレートを必要に応じてカスタマイズ:

def generate_report(data, format="markdown", include_charts=True):
    # データ処理
    # 指定形式で出力
    # オプションでチャートを含める
```

### 低自由度（具体的なスクリプト、変更禁止）

操作が壊れやすく、一貫性が必須で、特定の手順を踏む必要がある場合。

```markdown
## データベースマイグレーション

以下のスクリプトをそのまま実行:

python scripts/migrate.py --verify --backup

コマンドを変更したり、フラグを追加しないこと。
```

---

## ワークフローパターン

複雑なタスクを明確なステップに分解する。チェックリストを使うとClaudeが進捗を追跡できる。

```markdown
## ワークフロー

このチェックリストをコピーして進捗を管理:

- [ ] Step 1: フォームを解析（analyze_form.py実行）
- [ ] Step 2: フィールドマッピングを作成（fields.json編集）
- [ ] Step 3: マッピングを検証（validate_fields.py実行）
- [ ] Step 4: フォームに記入（fill_form.py実行）
- [ ] Step 5: 出力を検証（verify_output.py実行）

**Step 1: フォームを解析**
実行: `python scripts/analyze_form.py input.pdf`
...

**Step 5: 出力を検証**
検証に失敗した場合、Step 2に戻る。
```

**ポイント**:
- 明確なステップがスキップを防ぐ
- チェックリストでClaudeとユーザーの双方が進捗を把握

---

## フィードバックループ

「実行 → 検証 → 修正 → 再検証」のパターン。出力品質を大幅に改善する。

### コード付きスキルの場合

```markdown
## 編集プロセス

1. `word/document.xml` を編集
2. **即座に検証**: `python scripts/validate.py unpacked_dir/`
3. 検証失敗時:
   - エラーメッセージを確認
   - XMLを修正
   - 再度検証を実行
4. **検証が通るまで次に進まない**
5. リビルド: `python scripts/pack.py unpacked_dir/ output.docx`
```

### コードなしスキルの場合

```markdown
## コンテンツレビュー

1. STYLE_GUIDE.md のガイドラインに従ってコンテンツを作成
2. チェックリストでレビュー:
   - 用語の一貫性
   - 例のフォーマット準拠
   - 必須セクションの網羅
3. 問題があれば修正して再レビュー
4. 全要件を満たすまで次に進まない
```

**ポイント**: バリデーションスクリプトのエラーメッセージは具体的に（例: 「フィールド 'signature_date' が見つかりません。利用可能: customer_name, order_total」）

---

## テンプレートパターン

出力形式を指定する。要件の厳密さに応じて表現を変える。

### 厳密な要件

```markdown
## レポート構造

必ずこのテンプレート構造を使用:

# [分析タイトル]

## 要約
[主要な発見の概要（1段落）]

## 主要な発見
- 発見1（データ付き）
- 発見2（データ付き）

## 推奨事項
1. 具体的なアクション
2. 具体的なアクション
```

### 柔軟なガイダンス

```markdown
## レポート構造

以下はデフォルト形式。分析内容に応じて判断:

# [分析タイトル]
## 要約
## 主要な発見
## 推奨事項

セクションは分析の種類に応じて調整すること。
```

---

## 条件分岐パターン

Claudeを決定ポイントで適切な分岐へ導く。

```markdown
## ドキュメント変更ワークフロー

1. 変更の種類を判定:

   **新規作成?** → 下の「作成ワークフロー」へ
   **既存の編集?** → 下の「編集ワークフロー」へ

2. 作成ワークフロー:
   - docx-jsライブラリを使用
   - ドキュメントをゼロから構築
   - .docx形式にエクスポート

3. 編集ワークフロー:
   - 既存ドキュメントを展開
   - XMLを直接修正
   - 変更ごとにバリデーション
   - 完了後にリパック
```

ワークフローが大規模になる場合は、別ファイルに分離してClaudeに適切なファイルを読ませる。

---

## アンチパターン

| 問題 | 解決 |
|------|------|
| SKILL.md 500行超え | references/に分割 |
| references/が深いネスト（2階層以上） | 1階層に平坦化 |
| 情報の重複 | 1箇所にのみ記載（SSoT） |
| descriptionにトリガーなし | トリガーフレーズ3つ以上 |
| 用語の不統一（「抽出」「取得」「取り出し」混在） | 1つの概念に1つの用語 |
| 選択肢の提示しすぎ | デフォルト1つ + 例外時の代替 |
| 時間依存情報（「2025年8月以前は〜」） | 現在の方法のみ記載 |

---

## サイズ目安

| ファイル | 推奨 | 上限 |
|----------|------|------|
| description | 〜200文字 | 1024文字 |
| SKILL.md | 〜200行 | 500行 |
| references/各ファイル | 〜300行 | 目次必須（100行超） |
