snc777 4216635369 初回コミット: パーソナル図解ツールキット

Made-with: Cursor

2026-03-20 15:51:26 +09:00

7.7 KiB

Raw Blame History

SSoT 監査ガイド

スキル作成・更新時に必ず実行する SSoT（Single Source of Truth）監査の手順。この監査を通過するまでスキルを完成扱いにしない。

SSoT 違反とは

同じ情報が2箇所以上に存在し、片方を更新しても他方が古いまま残るリスクがある状態。

スキルにおける SSoT 違反は2つの場面で発生する:

スキル内部: SKILL.md と references/ の間で情報が重複
スキル ↔ 外部: スキルが参照するファイル（スキーマ、設定、コード）の情報をスキル内にコピー

違反パターンと修正方法

パターン1: スキーマ・設定のコピー

# 違反
## 出力形式
JSONは以下の構造:
- name: string (必須)
- age: number (任意)
- email: string (必須)

# 正解
## 出力形式
SSoT: `path/to/schema.ts` の型定義を参照

パターン2: ルール一覧の転記

# 違反
## バリデーション
以下のルールでチェック:
1. nameは3文字以上
2. emailは@を含む
3. ageは0以上

# 正解
## バリデーション
SSoT: `path/to/validator.ts` のバリデーションルールに従う

パターン3: SKILL.md と references/ の重複

# 違反
SKILL.md に品質チェックリストを書き、references/exemplar.md にも同じリストがある

# 正解
チェックリストは exemplar.md のみに記載。SKILL.md は「品質チェック → exemplar.md」と参照

パターン4: 他スキルとの重複

# 違反
スキルAとスキルBの両方に同じデプロイ手順を記載

# 正解
共通手順を共有リファレンスに置き、両方から参照

監査手順

スキルの作成・更新が完了したら、以下の全ステップを実行する。

Step 1: 情報ソースの列挙

スキルが参照する外部ファイルを全て列挙する:

スキーマファイル（.ts, .json）
設定ファイル
他のスキルの references/
プロジェクトのドキュメント

Step 2: スキル内コンテンツの監査

SKILL.md と references/ 内の各テーブル・リスト・コードブロックについて問う:

「この情報の真のソース（原本）はどこか？」

スキル内が原本 → Step 3 へ
スキル外に原本がある → 違反。参照に置き換える

Step 3: 重複の検索

スキル内が原本の情報について、プロジェクト内に同じ情報がないか確認:

grep -r "キーワード" --include="*.md" --include="*.ts" --include="*.json"

重複が見つかったら:

どちらを原本にするか決定
もう片方を参照に置き換え

Step 4: スキル内部の重複チェック

SKILL.md と references/ の間で同じ情報が書かれていないか確認:

SKILL.md に書いた内容が references/ にもないか
references/ の複数ファイルに同じ情報がないか

Step 5: 最終確認

以下を全て満たすことを確認:

スキル内の全テーブル・リストが「このスキルでしか定義されていない情報」のみを含む
外部ファイルの情報をスキル内にコピーしていない
SKILL.md と references/ の間に重複がない
references/ の複数ファイル間に重複がない

判断に迷うケース

「要約」は許されるか？

原則: 方向性を示す一文は許容。詳細リストのコピーは禁止。

# OK: 方向性だけ示して参照
## 概要
核心原則に基づいてスキルを設計する。
詳細 → references/principles.md

# NG: リストのコピー（要約に見せかけた重複）
## 概要
原則:
- 洗練: 公式ドキュメントに基づく
- 簡潔性: 必要最小限の情報
- SSoT: 情報は1箇所のみ

判断基準: 「参照先が変更された時、この記述も更新が必要か？」

Yes → SSoT 違反。参照に置き換える
No → 許容

テーブルの一部引用は？

禁止。 テーブルの一部でも、元テーブルに行が追加された時に古くなる。

# NG: 一部引用
主要なイベント: afterFileEdit, stop（全一覧は references/ を参照）

# OK: 参照のみ
イベント一覧 → references/events.md

「例」としての引用は？

形式の例示は1つだけ許容。内容の列挙は禁止。

# OK: 形式を1つだけ示す
フロントマターの例:
---
name: my-skill
description: ...
---
詳細な書き方 → exemplar.md

# NG: 複数パターンの列挙（内容のコピー）
良い例:
- feat(認証): メールアドレスでのログイン機能を追加
- fix(決済): 税率計算の誤りを修正
悪い例:
- バグを修正
- 対応

ハードコード・不整合レビュー

SSoT 監査（上記 Step 1〜5）が「情報のコピー」を検出するのに対し、このレビューは ハードコードされた詳細 と 暗黙的な依存 を検出する。SSoT 監査を通過したスキルに対して追加で実行する。

チェック1: ハードコードされた詳細情報

参照先を読めばわかる具体的な値・構造・手順がスキル内に直接書かれていないか確認する。

検出対象:

ディレクトリ構造の展開（ツリー表示）
設定値・パラメータの列挙
外部ツールのコマンドオプション一覧
スキーマのフィールド名・型の網羅的リスト
ファイルパスの詳細な列挙

判断基準: 「この詳細が変更されたとき、スキルを手動で更新する必要があるか？」

Yes → 参照に置き換えるか、方向性のみの記述に変更
No → 許容

# NG: ディレクトリ構造をハードコード
## 出力先
contents/
├── 講義/
│   └── Nヶ月目/第N回/
│       ├── meta.json
│       ├── slides.json
│       └── script.md

# OK: 参照先を示す
## 出力先
`contents/講義/` 配下に、実際のディレクトリ構造に従って配置する。

チェック2: 参照先変更時の不整合リスク

スキル内の記述が参照先の内容に暗黙的に依存していないか確認する。コピーではないが、参照先の更新により事実と乖離するリスクのある記述を検出する。