260 lines
7.7 KiB
Markdown
260 lines
7.7 KiB
Markdown
# 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
|
||
```
|
||
|
||
### レビュー最終確認
|
||
|
||
以下を全て満たすことを確認:
|
||
|
||
- [ ] スキル内にディレクトリ構造・スキーマ・設定値のベタ書きがない
|
||
- [ ] 参照先の件数・名前に依存する表現がない
|
||
- [ ] 参照先が更新されてもスキル内の記述が正確なままである
|