300 lines
8.3 KiB
Markdown
300 lines
8.3 KiB
Markdown
# パターン集
|
||
|
||
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行超） |
|