tomevault-io AI向け文書レビュー
このスキルは、AI 向け文書の変更をレビューするときに使う。 通常のドキュメントレビューとは分けて扱い、AI 実行時の誤読、更新漏れ、重複、優先順位崩れを重点的に見る。
目的
- AI 向け文書の正本と参照先の整合を保つ
- 重複、矛盾、曖昧さによるレビューラリーを減らす
- 人間向け文書レビューでは拾いにくい AI 固有の欠陥を見つける
対象
次のような文書を対象にする。
AGENTS.mdCLAUDE.md.github/copilot-instructions.md- AI 向けの補助ドキュメント
skills/配下の共用スキル- AI 向けテンプレート、プロンプト、規約文書
レビュー前提
- このリポジトリでは
AGENTS.mdが AI 向け運用ルールの正本である - 補助ファイルは、正本を複製せず参照する方向を優先する
- フォールバックは本当に必要な場合に限り、問題隠しのために追加しない
手順
1. 対象ファイルを特定する
まず、変更された AI 向け文書と、それに参照される関連ファイルを洗い出す。 単体ファイルだけでなく、正本、入口ファイル、補助文書、関連スキルをまとめて見る。
2. 正本と参照関係を確認する
次を確認する。
- 正本がどのファイルか明確か
- 補助ファイルが正本を参照しているか
- 参照先パスが実在するか
- 参照が古い構成や削除済みファイルを向いていないか
3. 重複と責務分離を確認する
次を確認する。
- 同じルールや規約が複数ファイルに重複していないか
- 正本に置くべき内容と補助文書に置くべき内容が混線していないか
- ツール固有の内容が共通文書へ漏れていないか
- 逆に、共通ルールがツール固有ファイルへ複製されていないか
4. 優先順位と統治ルールを確認する
次を確認する。
- どの指示が最優先か明確か
- 優先順位の説明がファイル間で矛盾していないか
- 個別文書が正本を上書きするような書き方になっていないか
5. AI にとっての明確さを確認する
人間には自然でも、AI にとって曖昧な表現を重点的に探す。
例:
- 指示対象が曖昧
- 例外条件が曖昧
- 「適宜」「必要に応じて」だけで判断基準がない
- 「基本的に」「なるべく」が多いのに優先条件がない
- 参照すべき文書が複数あるのに読む順序が不明
曖昧さを見つけたら、表現だけでなく判断基準の不足として指摘する。
6. フォールバックと例外規定を確認する
次を確認する。
- フォールバックが問題隠しになっていないか
- 例外規定が広すぎて通常ルールを無効化していないか
- 接続不能、認証不足、参照切れなどを曖昧な代替手段で覆っていないか
7. スキルや補助文書との整合を確認する
AI 向け文書が skills/ 配下や補助ドキュメントと整合しているかを見る。
- スキルの説明が
AGENTS.mdの原則と矛盾していないか - 共用スキルが特定 AI や特定ツールに不必要に依存していないか
- 文書側の変更に対して、スキル側の更新漏れがないか
8. 指摘を優先度順にまとめる
レビュー結果は、まず問題点を優先度順に並べる。 要約は後でよい。
優先して指摘するのは次の種類の問題:
- 正本との矛盾
- 参照切れや更新漏れ
- 重複による多重管理
- AI に誤読されやすい曖昧表現
- 問題隠しのフォールバック
ガードレール
- 人間向け文書レビューの観点だけで終わらせない
- 表現の好みより、運用上の誤作動リスクを優先する
- 「たぶん伝わる」で通さない
- 参照先を確認せずに整合していると判断しない
- 指摘漏れを避けるため、変更ファイルだけでなく関連参照先も見る
出力要件
レビュー結果は、問題点を先に出す。
- 問題があれば、重要度順に列挙する
- 各指摘では、対象ファイルと問題の性質を明示する
- 可能なら、なぜそれが AI 運用上のリスクになるかを短く添える
- 問題がなければ、その旨を明示し、残る軽微なリスクや確認不足があれば補足する
Source: yama/sokra — distributed by TomeVault.