初回コミット: パーソナル図解ツールキット
Made-with: Cursor
This commit is contained in:
snc777
@@ -0,0 +1,321 @@
|
||||
# スキル模範例とチェックリスト
|
||||
|
||||
## 目次
|
||||
|
||||
- description の書き方
|
||||
- 汎用スキル例
|
||||
- プロジェクト固有スキル例
|
||||
- コード付きスキル例
|
||||
- スクリプトの品質
|
||||
- 評価と反復プロセス
|
||||
- チェックリスト
|
||||
|
||||
---
|
||||
|
||||
## description の書き方
|
||||
|
||||
### 三人称ルール
|
||||
|
||||
descriptionはシステムプロンプトに注入される。視点の不一致はスキル発見の問題を引き起こす。
|
||||
|
||||
```yaml
|
||||
# 良い: 三人称
|
||||
description: スキルを作成・更新・改善するスキル。「スキルを作って」「このスキルを改善して」と依頼された際に使用する。
|
||||
|
||||
# 悪い: 一人称
|
||||
description: 私がスキルの作成を手伝います。
|
||||
|
||||
# 悪い: 二人称
|
||||
description: あなたがスキルを作成する時に使えます。
|
||||
```
|
||||
|
||||
### トリガーフレーズ
|
||||
|
||||
Claudeが100+のスキルから選択する判断材料。具体的なキーワードを含める。
|
||||
|
||||
```yaml
|
||||
# 良い: トリガーフレーズ3つ以上 + 具体的なキーワード
|
||||
description: |
|
||||
Cursor Hooksを作成・設定するスキル。
|
||||
「フックを作って」「hookを追加して」「afterFileEditを設定して」と依頼された際に使用する。
|
||||
|
||||
# 悪い: トリガーがない
|
||||
description: Hooksを処理するスキル。
|
||||
|
||||
# 悪い: 抽象的すぎる
|
||||
description: 設定関連の作業を支援する。
|
||||
```
|
||||
|
||||
### 命名規則
|
||||
|
||||
gerund形式（動詞+ing）が活動を明確に伝える。
|
||||
|
||||
```
|
||||
良い: processing-pdfs, analyzing-data, managing-hooks
|
||||
許容: pdf-processing, data-analysis（名詞句）
|
||||
避ける: helper, utils, tools（曖昧）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 汎用スキル
|
||||
|
||||
プロジェクト固有の実装に依存しない。公式ドキュメント・仕様に基づく。
|
||||
|
||||
### 例: hook-creator
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: hook-creator
|
||||
description: Cursor Hooksを作成・設定するスキル。「フックを作って」「hookを追加して」「afterFileEditを設定して」と依頼された際に使用する。
|
||||
---
|
||||
|
||||
# Hook Creator
|
||||
|
||||
Cursor Hooksの作成・設定を支援する。
|
||||
|
||||
## 概要
|
||||
|
||||
Hooksはエージェントループの特定タイミングでカスタムスクリプトを実行する仕組み。
|
||||
|
||||
## クイックスタート
|
||||
|
||||
[最小限の例]
|
||||
|
||||
## フックイベント一覧
|
||||
|
||||
| イベント | タイミング | 出力 |
|
||||
|---------|-----------|------|
|
||||
| afterFileEdit | ファイル編集後 | なし |
|
||||
| stop | Agent停止時 | followup_message |
|
||||
|
||||
**詳細スキーマ** → [references/events.md](references/events.md)
|
||||
```
|
||||
|
||||
**ポイント**:
|
||||
- 公式ドキュメントの内容のみ
|
||||
- プロジェクト固有の実装パターンなし
|
||||
|
||||
---
|
||||
|
||||
## プロジェクト固有スキル
|
||||
|
||||
特定プロジェクトのワークフロー・データ構造に依存。依存先を明示する。
|
||||
|
||||
### 構造例
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: project-specific-skill
|
||||
description: プロジェクト固有の作業を行うスキル。「〇〇を作って」「〇〇を更新して」と依頼された際に使用する。
|
||||
---
|
||||
|
||||
# Project Specific Skill
|
||||
|
||||
## 依存
|
||||
|
||||
- `path/to/` 配下のディレクトリ構造
|
||||
- `config.json` スキーマ（references/schema.md）
|
||||
- 品質チェックフロー（.cursor/hooks/validate.sh）
|
||||
|
||||
## ワークフロー
|
||||
|
||||
[プロジェクト固有のワークフロー]
|
||||
|
||||
## 出力形式
|
||||
|
||||
[プロジェクト固有のスキーマ]
|
||||
```
|
||||
|
||||
**ポイント**:
|
||||
- 依存先を「依存」セクションで明示
|
||||
- 変更時の影響範囲が把握できる
|
||||
|
||||
---
|
||||
|
||||
## コード付きスキル
|
||||
|
||||
スクリプトで決定的処理を実行し、SKILL.md は仕組み・実行方法・出力を記載する。
|
||||
|
||||
### 例: hooks-toggle
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: hooks-toggle
|
||||
description: Cursorフックを一時的に無効化/有効化するスキル。「フックを止めて」「フックを無効にして」「フックを有効にして」「hooks off」「hooks on」と依頼された際に使用する。
|
||||
---
|
||||
|
||||
# Hooks Toggle
|
||||
|
||||
Cursor hooks と SDK hooks を同時に無効化/有効化する。
|
||||
|
||||
## 仕組み
|
||||
|
||||
各 `hooks-disabled` ファイルの有無でフックが動作を判定。
|
||||
- ファイルあり → フック無効
|
||||
- ファイルなし → フック有効
|
||||
|
||||
## 実行
|
||||
|
||||
bash .claude/skills/hooks-toggle/scripts/toggle-hooks.sh
|
||||
|
||||
## 出力
|
||||
|
||||
| 状態 | 出力 |
|
||||
|------|------|
|
||||
| 有効→無効 | `Hooks disabled (Cursor + SDK)` |
|
||||
| 無効→有効 | `Hooks enabled (Cursor + SDK)` |
|
||||
|
||||
## 依存
|
||||
|
||||
- `.cursor/hooks/on-quiz-edit.ts` - スキップ判定ロジック
|
||||
- `drill/tools/quiz-viewer/server/hooks/index.ts` - スキップ判定ロジック
|
||||
```
|
||||
|
||||
**ポイント**:
|
||||
- `scripts/toggle-hooks.sh` で状態管理（ファイル作成/削除）を確実に実行
|
||||
- SKILL.md は**仕組み・実行方法・出力**を記載（スクリプトの実装詳細は書かない）
|
||||
- 依存セクションでフック判定ロジックの所在を明示
|
||||
|
||||
---
|
||||
|
||||
## スクリプトの品質
|
||||
|
||||
### Solve, don't punt
|
||||
|
||||
スクリプト内でエラーを処理する。Claudeに丸投げしない。
|
||||
|
||||
```python
|
||||
# 良い: エラーを自力で処理
|
||||
def process_file(path):
|
||||
try:
|
||||
with open(path) as f:
|
||||
return f.read()
|
||||
except FileNotFoundError:
|
||||
print(f"File {path} not found, creating default")
|
||||
with open(path, "w") as f:
|
||||
f.write("")
|
||||
return ""
|
||||
|
||||
# 悪い: Claudeに丸投げ
|
||||
def process_file(path):
|
||||
return open(path).read()
|
||||
```
|
||||
|
||||
### マジックナンバー禁止
|
||||
|
||||
設定値には根拠を示す。
|
||||
|
||||
```python
|
||||
# 良い: 根拠がある
|
||||
REQUEST_TIMEOUT = 30 # HTTPリクエストは通常30秒以内に完了
|
||||
MAX_RETRIES = 3 # 大半の間欠的エラーは2回目で解消
|
||||
|
||||
# 悪い: 根拠不明
|
||||
TIMEOUT = 47 # なぜ47?
|
||||
RETRIES = 5 # なぜ5?
|
||||
```
|
||||
|
||||
### 検証可能な中間出力
|
||||
|
||||
複雑なタスクでは「計画→検証→実行」パターンでエラーを早期発見する。
|
||||
|
||||
```
|
||||
analyze → changes.json作成 → validate_changes.py → 問題なければ実行
|
||||
```
|
||||
|
||||
バリデーションスクリプトのエラーメッセージは具体的に:
|
||||
- 良い: `Field 'signature_date' not found. Available: customer_name, order_total`
|
||||
- 悪い: `Validation failed`
|
||||
|
||||
---
|
||||
|
||||
## 評価と反復プロセス
|
||||
|
||||
### 評価駆動開発
|
||||
|
||||
スキルを書く前に、まずClaudeの現状の能力を測定する。
|
||||
|
||||
1. **ベースライン計測**: スキルなしでClaudeにタスクを実行させる
|
||||
2. **Gap特定**: 失敗箇所・不足情報を文書化
|
||||
3. **評価シナリオ作成**: Gapをテストする3つ以上のシナリオを用意
|
||||
4. **最小限の記述**: Gapを埋める最小限のスキル内容を書く
|
||||
5. **反復**: 評価を実行し、ベースラインと比較し、改善
|
||||
|
||||
```json
|
||||
{
|
||||
"skills": ["pdf-processing"],
|
||||
"query": "このPDFからテキストを抽出してoutput.txtに保存して",
|
||||
"files": ["test-files/document.pdf"],
|
||||
"expected_behavior": [
|
||||
"PDFライブラリを使用してファイルを正常に読み取る",
|
||||
"全ページからテキストを漏れなく抽出する",
|
||||
"output.txtに読みやすい形式で保存する"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Claude A/B パターン
|
||||
|
||||
- **Claude A**（設計者）: スキルの内容を設計・改善する会話
|
||||
- **Claude B**（使用者）: スキルを使って実際のタスクを実行する会話
|
||||
|
||||
Claude Bの挙動を観察してClaude Aに報告し、改善する:
|
||||
|
||||
| 観察 | 対応 |
|
||||
|------|------|
|
||||
| Claudeがバンドルファイルを一度も読まない | 不要か、SKILL.mdでの参照が不十分 |
|
||||
| 同じファイルを繰り返し読む | そのコンテンツをSKILL.mdに昇格 |
|
||||
| 参照リンクをたどらない | リンクをより目立たせる |
|
||||
| 予想外の順序でファイルを読む | 構造が直感的でない可能性 |
|
||||
|
||||
### チーム展開時
|
||||
|
||||
- スキルをチームメンバーに共有し、使用状況を観察
|
||||
- 「期待通りに発動するか？」「指示は明確か？」「何が足りないか？」を確認
|
||||
|
||||
---
|
||||
|
||||
## チェックリスト
|
||||
|
||||
### 全スキル共通
|
||||
|
||||
- [ ] descriptionに「何をするか」と「いつ使うか」の両方がある
|
||||
- [ ] descriptionにトリガーフレーズ3つ以上
|
||||
- [ ] descriptionが三人称で書かれている
|
||||
- [ ] SKILL.md 500行以内
|
||||
- [ ] 冗長な説明なし
|
||||
- [ ] 一貫した用語を使用
|
||||
- [ ] 時間依存情報なし
|
||||
- [ ] 具体的な例がある
|
||||
- [ ] ワークフローに明確なステップがある
|
||||
- [ ] **SSoT 監査を通過済み**（[ssot-audit.md](ssot-audit.md) の全ステップを実行し、違反なしを確認）
|
||||
- [ ] **ハードコード・不整合レビューを通過済み**（[ssot-audit.md](ssot-audit.md) のレビュー全項目を確認）
|
||||
- [ ] 参照は1階層まで（深いネスト禁止）
|
||||
- [ ] 100行超の参照ファイルに目次がある
|
||||
|
||||
### 汎用スキル
|
||||
|
||||
- [ ] 公式ドキュメント・仕様に基づいている
|
||||
- [ ] プロジェクト固有のパターン・実装がない
|
||||
- [ ] 他プロジェクトでも使える
|
||||
|
||||
### プロジェクト固有スキル
|
||||
|
||||
- [ ] 「依存」セクションがある
|
||||
- [ ] 依存するファイル・ワークフローが明示されている
|
||||
- [ ] 依存先が変更されたときの影響範囲が分かる
|
||||
|
||||
### コード付きスキル
|
||||
|
||||
- [ ] 実行方法が SKILL.md に記載されている
|
||||
- [ ] 決定的処理がスクリプトで実装されている
|
||||
- [ ] スクリプトがエラーを自力で処理する
|
||||
- [ ] 設定値に根拠がある（マジックナンバーなし）
|
||||
- [ ] 必要なパッケージが明記されている
|
||||
|
||||
### テスト
|
||||
|
||||
- [ ] 実際のタスクでテスト済み
|
||||
- [ ] 3つ以上の評価シナリオがある
|
||||
- [ ] 使用予定の全モデルでテスト済み（Haiku/Sonnet/Opus）
|
||||
@@ -0,0 +1,299 @@
|
||||
# パターン集
|
||||
|
||||
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行超） |
|
||||
@@ -0,0 +1,119 @@
|
||||
# 核心原則
|
||||
|
||||
## 目次
|
||||
|
||||
- 洗練 (Refine)
|
||||
- 簡潔性 (Concise)
|
||||
- SSoT 厳守
|
||||
- 段階的開示・自由度
|
||||
- スキルの種類
|
||||
- 構造とフロントマター
|
||||
- コード vs プロンプトの判断
|
||||
- コンテンツガイドライン
|
||||
|
||||
---
|
||||
|
||||
## 洗練 (Refine)
|
||||
|
||||
スキルは**公式ドキュメントや安定した仕様**に基づいて書く。
|
||||
|
||||
| 良い | 避ける |
|
||||
|------|--------|
|
||||
| 公式APIスキーマ | 現在の実装コード |
|
||||
| 安定した仕様 | 変更されうるパターン |
|
||||
| 普遍的な原則 | プロジェクト固有のワークフロー |
|
||||
|
||||
**例外**: プロジェクト固有スキルは意図的に依存してよい（→ スキルの種類）
|
||||
|
||||
---
|
||||
|
||||
## 簡潔性 (Concise)
|
||||
|
||||
コンテキストウィンドウは共有資源。**本当に必要な情報だけ**を含める。
|
||||
|
||||
- 冗長な説明より簡潔な例
|
||||
- 「このトークンコストに見合う価値があるか？」「Claudeが既に知っていないか？」を問う
|
||||
|
||||
---
|
||||
|
||||
## SSoT 厳守
|
||||
|
||||
**参照先の情報をスキル内に書かない。** 情報は必ず1箇所だけに存在させ、他の箇所からは参照する。スキーマが変更された時、スキル内のコピーは古くなり、矛盾が生じる。
|
||||
|
||||
違反パターンの具体例・監査手順 → [ssot-audit.md](ssot-audit.md)
|
||||
|
||||
---
|
||||
|
||||
## 段階的開示・自由度
|
||||
|
||||
詳細 → [patterns.md](patterns.md)（3段階ローディング、自由度パターン）
|
||||
|
||||
---
|
||||
|
||||
## スキルの種類
|
||||
|
||||
### 汎用スキル
|
||||
|
||||
どのプロジェクトでも使える。公式ドキュメント・仕様に基づく。
|
||||
|
||||
**原則**: プロジェクト固有の実装パターンに依存しない
|
||||
|
||||
### プロジェクト固有スキル
|
||||
|
||||
特定プロジェクトのワークフロー・データ構造に依存。
|
||||
|
||||
**原則**: 依存先を「依存」セクションで明示し、変更時の影響範囲を把握できるようにする
|
||||
|
||||
---
|
||||
|
||||
## 構造とフロントマター
|
||||
|
||||
### ディレクトリ構造
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md (必須)
|
||||
├── scripts/ (任意)
|
||||
│ └── *.ts / *.sh
|
||||
└── references/ (任意)
|
||||
└── *.md
|
||||
```
|
||||
|
||||
### フロントマター
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: kebab-case（64文字以内、小文字・数字・ハイフンのみ）
|
||||
description: 三人称で記述。何をするか＋トリガーフレーズ3つ以上（1024文字以内）
|
||||
---
|
||||
```
|
||||
|
||||
descriptionの書き方・良い例・悪い例 → [exemplar.md](exemplar.md)（descriptionの書き方）
|
||||
|
||||
---
|
||||
|
||||
## コード vs プロンプトの判断
|
||||
|
||||
スキルの処理を **scripts/ のコード** で実装するか、**SKILL.md のプロンプト指示** に任せるか。
|
||||
|
||||
| コードを書く（scripts/） | プロンプトで指示する（SKILL.md） |
|
||||
|--------------------------|--------------------------------|
|
||||
| 決定的（毎回同じ結果が必要） | 創造的・文脈依存 |
|
||||
| ファイルシステム操作（再帰削除、ツリー構築） | コンテンツ生成・判断 |
|
||||
| 外部ツール連携（git, gh, surge） | コードレビュー・分析 |
|
||||
| 状態管理（フラグファイル、タイムスタンプ） | 対話的ワークフロー |
|
||||
| スキーマに基づくファイル生成 | 自然言語の出力 |
|
||||
|
||||
### コード作成時の規約
|
||||
|
||||
- **TypeScript**: Bun で実行。`pnpm` スクリプト経由で呼び出す（直接実行禁止）
|
||||
- **Bash**: 標準Unixツールのみ。`bash path/to/script.sh` で実行
|
||||
- SKILL.md にはスクリプトの**目的・実行方法・出力**を記載（実装詳細は書かない）
|
||||
|
||||
スクリプト品質の原則と具体例 → [exemplar.md](exemplar.md)（スクリプトの品質）
|
||||
|
||||
---
|
||||
|
||||
## コンテンツガイドライン
|
||||
|
||||
禁止事項・サイズ目安 → [patterns.md](patterns.md)（アンチパターン、サイズ目安）
|
||||
@@ -0,0 +1,259 @@
|
||||
# SSoT 監査ガイド
|
||||
|
||||
スキル作成・更新時に必ず実行する SSoT（Single Source of Truth）監査の手順。**この監査を通過するまでスキルを完成扱いにしない。**
|
||||
|
||||
## 目次
|
||||
|
||||
- SSoT 違反とは
|
||||
- 違反パターンと修正方法
|
||||
- 監査手順
|
||||
- 判断に迷うケース
|
||||
- ハードコード・不整合レビュー
|
||||
|
||||
---
|
||||
|
||||
## SSoT 違反とは
|
||||
|
||||
**同じ情報が2箇所以上に存在し、片方を更新しても他方が古いまま残るリスクがある状態。**
|
||||
|
||||
スキルにおける SSoT 違反は2つの場面で発生する:
|
||||
|
||||
1. **スキル内部**: SKILL.md と references/ の間で情報が重複
|
||||
2. **スキル ↔ 外部**: スキルが参照するファイル（スキーマ、設定、コード）の情報をスキル内にコピー
|
||||
|
||||
---
|
||||
|
||||
## 違反パターンと修正方法
|
||||
|
||||
### パターン1: スキーマ・設定のコピー
|
||||
|
||||
```markdown
|
||||
# 違反
|
||||
## 出力形式
|
||||
JSONは以下の構造:
|
||||
- name: string (必須)
|
||||
- age: number (任意)
|
||||
- email: string (必須)
|
||||
|
||||
# 正解
|
||||
## 出力形式
|
||||
SSoT: `path/to/schema.ts` の型定義を参照
|
||||
```
|
||||
|
||||
### パターン2: ルール一覧の転記
|
||||
|
||||
```markdown
|
||||
# 違反
|
||||
## バリデーション
|
||||
以下のルールでチェック:
|
||||
1. nameは3文字以上
|
||||
2. emailは@を含む
|
||||
3. ageは0以上
|
||||
|
||||
# 正解
|
||||
## バリデーション
|
||||
SSoT: `path/to/validator.ts` のバリデーションルールに従う
|
||||
```
|
||||
|
||||
### パターン3: SKILL.md と references/ の重複
|
||||
|
||||
```markdown
|
||||
# 違反
|
||||
SKILL.md に品質チェックリストを書き、references/exemplar.md にも同じリストがある
|
||||
|
||||
# 正解
|
||||
チェックリストは exemplar.md のみに記載。SKILL.md は「品質チェック → exemplar.md」と参照
|
||||
```
|
||||
|
||||
### パターン4: 他スキルとの重複
|
||||
|
||||
```markdown
|
||||
# 違反
|
||||
スキルAとスキルBの両方に同じデプロイ手順を記載
|
||||
|
||||
# 正解
|
||||
共通手順を共有リファレンスに置き、両方から参照
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 監査手順
|
||||
|
||||
スキルの作成・更新が完了したら、以下の全ステップを実行する。
|
||||
|
||||
### Step 1: 情報ソースの列挙
|
||||
|
||||
スキルが参照する外部ファイルを全て列挙する:
|
||||
|
||||
- スキーマファイル（.ts, .json）
|
||||
- 設定ファイル
|
||||
- 他のスキルの references/
|
||||
- プロジェクトのドキュメント
|
||||
|
||||
### Step 2: スキル内コンテンツの監査
|
||||
|
||||
SKILL.md と references/ 内の**各テーブル・リスト・コードブロック**について問う:
|
||||
|
||||
**「この情報の真のソース（原本）はどこか？」**
|
||||
|
||||
- **スキル内が原本** → Step 3 へ
|
||||
- **スキル外に原本がある** → 違反。参照に置き換える
|
||||
|
||||
### Step 3: 重複の検索
|
||||
|
||||
スキル内が原本の情報について、プロジェクト内に同じ情報がないか確認:
|
||||
|
||||
```bash
|
||||
grep -r "キーワード" --include="*.md" --include="*.ts" --include="*.json"
|
||||
```
|
||||
|
||||
重複が見つかったら:
|
||||
- どちらを原本にするか決定
|
||||
- もう片方を参照に置き換え
|
||||
|
||||
### Step 4: スキル内部の重複チェック
|
||||
|
||||
SKILL.md と references/ の間で同じ情報が書かれていないか確認:
|
||||
|
||||
- SKILL.md に書いた内容が references/ にもないか
|
||||
- references/ の複数ファイルに同じ情報がないか
|
||||
|
||||
### Step 5: 最終確認
|
||||
|
||||
以下を全て満たすことを確認:
|
||||
|
||||
- [ ] スキル内の全テーブル・リストが「このスキルでしか定義されていない情報」のみを含む
|
||||
- [ ] 外部ファイルの情報をスキル内にコピーしていない
|
||||
- [ ] SKILL.md と references/ の間に重複がない
|
||||
- [ ] references/ の複数ファイル間に重複がない
|
||||
|
||||
---
|
||||
|
||||
## 判断に迷うケース
|
||||
|
||||
### 「要約」は許されるか？
|
||||
|
||||
**原則: 方向性を示す一文は許容。詳細リストのコピーは禁止。**
|
||||
|
||||
```markdown
|
||||
# OK: 方向性だけ示して参照
|
||||
## 概要
|
||||
核心原則に基づいてスキルを設計する。
|
||||
詳細 → references/principles.md
|
||||
|
||||
# NG: リストのコピー（要約に見せかけた重複）
|
||||
## 概要
|
||||
原則:
|
||||
- 洗練: 公式ドキュメントに基づく
|
||||
- 簡潔性: 必要最小限の情報
|
||||
- SSoT: 情報は1箇所のみ
|
||||
```
|
||||
|
||||
判断基準: **「参照先が変更された時、この記述も更新が必要か？」**
|
||||
- Yes → SSoT 違反。参照に置き換える
|
||||
- No → 許容
|
||||
|
||||
### テーブルの一部引用は？
|
||||
|
||||
**禁止。** テーブルの一部でも、元テーブルに行が追加された時に古くなる。
|
||||
|
||||
```markdown
|
||||
# NG: 一部引用
|
||||
主要なイベント: afterFileEdit, stop（全一覧は references/ を参照）
|
||||
|
||||
# OK: 参照のみ
|
||||
イベント一覧 → references/events.md
|
||||
```
|
||||
|
||||
### 「例」としての引用は？
|
||||
|
||||
**形式の例示は1つだけ許容。内容の列挙は禁止。**
|
||||
|
||||
```markdown
|
||||
# OK: 形式を1つだけ示す
|
||||
フロントマターの例:
|
||||
---
|
||||
name: my-skill
|
||||
description: ...
|
||||
---
|
||||
詳細な書き方 → exemplar.md
|
||||
|
||||
# NG: 複数パターンの列挙（内容のコピー）
|
||||
良い例:
|
||||
- feat(認証): メールアドレスでのログイン機能を追加
|
||||
- fix(決済): 税率計算の誤りを修正
|
||||
悪い例:
|
||||
- バグを修正
|
||||
- 対応
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ハードコード・不整合レビュー
|
||||
|
||||
SSoT 監査（上記 Step 1〜5）が「情報のコピー」を検出するのに対し、このレビューは **ハードコードされた詳細** と **暗黙的な依存** を検出する。SSoT 監査を通過したスキルに対して追加で実行する。
|
||||
|
||||
### チェック1: ハードコードされた詳細情報
|
||||
|
||||
参照先を読めばわかる**具体的な値・構造・手順**がスキル内に直接書かれていないか確認する。
|
||||
|
||||
**検出対象**:
|
||||
|
||||
- ディレクトリ構造の展開（ツリー表示）
|
||||
- 設定値・パラメータの列挙
|
||||
- 外部ツールのコマンドオプション一覧
|
||||
- スキーマのフィールド名・型の網羅的リスト
|
||||
- ファイルパスの詳細な列挙
|
||||
|
||||
**判断基準**: 「この詳細が変更されたとき、スキルを手動で更新する必要があるか？」
|
||||
|
||||
- Yes → 参照に置き換えるか、方向性のみの記述に変更
|
||||
- No → 許容
|
||||
|
||||
```markdown
|
||||
# NG: ディレクトリ構造をハードコード
|
||||
## 出力先
|
||||
contents/
|
||||
├── 講義/
|
||||
│ └── Nヶ月目/第N回/
|
||||
│ ├── meta.json
|
||||
│ ├── slides.json
|
||||
│ └── script.md
|
||||
|
||||
# OK: 参照先を示す
|
||||
## 出力先
|
||||
`contents/講義/` 配下に、実際のディレクトリ構造に従って配置する。
|
||||
```
|
||||
|
||||
### チェック2: 参照先変更時の不整合リスク
|
||||
|
||||
スキル内の記述が参照先の内容に**暗黙的に依存**していないか確認する。コピーではないが、参照先の更新により事実と乖離するリスクのある記述を検出する。
|
||||
|
||||
**検出対象**:
|
||||
|
||||
- 参照先の件数に依存する表現（「3つの原則」「5つのステップ」）
|
||||
- 参照先の内容を要約した記述（要約は参照先が変われば古くなる）
|
||||
- 参照先の特定ステップ名・ラベルをインラインで使った記述
|
||||
|
||||
**判断基準**: 「参照先のファイルが更新されたとき、この記述はまだ正確か？」
|
||||
|
||||
- 不確実 → 参照先に依存しない表現に書き換える
|
||||
- 常に正確 → 許容
|
||||
|
||||
```markdown
|
||||
# NG: 参照先の個数に暗黙的に依存
|
||||
3つの核心原則に基づいてスキルを設計する。
|
||||
→ 原則が追加・削除されたら不正確になる
|
||||
|
||||
# OK: 個数に依存しない
|
||||
核心原則に基づいてスキルを設計する。
|
||||
詳細 → references/principles.md
|
||||
```
|
||||
|
||||
### レビュー最終確認
|
||||
|
||||
以下を全て満たすことを確認:
|
||||
|
||||
- [ ] スキル内にディレクトリ構造・スキーマ・設定値のベタ書きがない
|
||||
- [ ] 参照先の件数・名前に依存する表現がない
|
||||
- [ ] 参照先が更新されてもスキル内の記述が正確なままである
|
||||
Reference in New Issue
Block a user