120 lines
3.7 KiB
Markdown
120 lines
3.7 KiB
Markdown
# 核心原則
|
||
|
||
## 目次
|
||
|
||
- 洗練 (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)（アンチパターン、サイズ目安）
|