# パターン集 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行超） |