8.3 KiB
パターン集
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段階で調整する。
高自由度（テキストベースの方針）
ヒューリスティクスが指針となり、文脈で判断が変わり、複数のアプローチが妥当な場合。
## コードレビュー
1. コード構造と設計を分析
2. バグや境界ケースの可能性を確認
3. 可読性・保守性の改善を提案
4. プロジェクト規約への準拠を検証
中自由度（パラメータ付きの擬似コード）
設定が挙動に影響し、ある程度の変動は許容されるが、推奨パターンがある場合。
## レポート生成
以下のテンプレートを必要に応じてカスタマイズ:
def generate_report(data, format="markdown", include_charts=True):
# データ処理
# 指定形式で出力
# オプションでチャートを含める
低自由度（具体的なスクリプト、変更禁止）
操作が壊れやすく、一貫性が必須で、特定の手順を踏む必要がある場合。
## データベースマイグレーション
以下のスクリプトをそのまま実行:
python scripts/migrate.py --verify --backup
コマンドを変更したり、フラグを追加しないこと。
ワークフローパターン
複雑なタスクを明確なステップに分解する。チェックリストを使うとClaudeが進捗を追跡できる。
## ワークフロー
このチェックリストをコピーして進捗を管理:
- [ ] 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とユーザーの双方が進捗を把握
フィードバックループ
「実行 → 検証 → 修正 → 再検証」のパターン。出力品質を大幅に改善する。
コード付きスキルの場合
## 編集プロセス
1. `word/document.xml` を編集
2. **即座に検証**: `python scripts/validate.py unpacked_dir/`
3. 検証失敗時:
- エラーメッセージを確認
- XMLを修正
- 再度検証を実行
4. **検証が通るまで次に進まない**
5. リビルド: `python scripts/pack.py unpacked_dir/ output.docx`
コードなしスキルの場合
## コンテンツレビュー
1. STYLE_GUIDE.md のガイドラインに従ってコンテンツを作成
2. チェックリストでレビュー:
- 用語の一貫性
- 例のフォーマット準拠
- 必須セクションの網羅
3. 問題があれば修正して再レビュー
4. 全要件を満たすまで次に進まない
ポイント: バリデーションスクリプトのエラーメッセージは具体的に（例: 「フィールド 'signature_date' が見つかりません。利用可能: customer_name, order_total」）
テンプレートパターン
出力形式を指定する。要件の厳密さに応じて表現を変える。
厳密な要件
## レポート構造
必ずこのテンプレート構造を使用:
# [分析タイトル]
## 要約
[主要な発見の概要（1段落）]
## 主要な発見
- 発見1（データ付き）
- 発見2（データ付き）
## 推奨事項
1. 具体的なアクション
2. 具体的なアクション
柔軟なガイダンス
## レポート構造
以下はデフォルト形式。分析内容に応じて判断:
# [分析タイトル]
## 要約
## 主要な発見
## 推奨事項
セクションは分析の種類に応じて調整すること。
条件分岐パターン
Claudeを決定ポイントで適切な分岐へ導く。
## ドキュメント変更ワークフロー
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行超） |