tomevault-io AI向け文書改修
このスキルは、AI 向け文書を新規作成、更新、整理するときに使う。 単体ファイルだけを直して終わらせず、正本、入口ファイル、補助文書、関連スキルまで含めて整合を取る。
目的
- AI 向け文書の改修で SSOT を壊さない
- 重複、矛盾、更新漏れを減らす
- 改修後のレビューラリーを短くする
対象
次のような文書を対象にする。
AGENTS.mdCLAUDE.md.github/copilot-instructions.md- AI 向けの補助ドキュメント
skills/配下の共用スキル- AI 向けテンプレート、プロンプト、規約文書
前提
AGENTS.mdは AI 向け運用ルールの正本である- 補助ファイルは、正本を複製せず参照する方向を優先する
- フォールバックは本当に必要な場合に限り、問題隠しのために追加しない
手順
1. 改修対象と正本を特定する
まず、何を変えたいのかを明確にする。
- 新しいルールを足したいのか
- 既存ルールを整理したいのか
- ツール別入口を更新したいのか
- スキルや補助文書を追加したいのか
そのうえで、どこが正本で、どこが参照先かを確認する。
2. 変更を置く場所を決める
変更内容を次のどこに置くべきか判断する。
AGENTS.mdに置くべき恒久ルール- 補助文書に置くべき詳細
- ツール固有ファイルに置くべき入口や補足
skills/に置くべき再利用可能な作業フロー
迷った場合は、まず重複を増やさない配置を選ぶ。
3. 正本を先に直す
共通ルールの変更であれば、まず正本を更新する。 補助ファイルから先に直して、後で正本を追いかける形にしない。
4. 参照先と関連ファイルを追従更新する
次を確認し、必要ならまとめて直す。
CLAUDE.mdの参照先.github/copilot-instructions.mdの説明- 補助文書内の参照パス
skills/配下の関連スキル- README など人間向け入口にある最低限の案内
単独ファイルの変更で終わると判断する前に、関連参照先を必ず確認する。
5. 重複を増やしていないか確認する
改修後に次が起きていないか確認する。
- 同じルールを複数ファイルへ書いていないか
- 既存の文書と意味が重なる新規文書を増やしていないか
- 正本を弱める例外規定を補助ファイルへ書いていないか
必要なら、既存記述を削る方向も選ぶ。
6. AI にとって明確な表現へ整える
次のような曖昧さを減らす。
- 指示対象が不明
- 優先順位が不明
- 例外条件が広すぎる
- 「適宜」「必要に応じて」だけで判断基準がない
- 参照先はあるが、いつ読むかが不明
人間向けの自然さより、AI にとっての再現性を優先する。
7. フォールバックと例外規定を見直す
改修中に追加したフォールバックや例外規定が、問題隠しになっていないか確認する。
- 接続不能を曖昧な代替手段で覆っていないか
- 更新漏れを許容する逃げ道になっていないか
- 正本の規律を崩す近道になっていないか
8. 改修後に ai-doc-review 観点で自己レビューする
編集後は、少なくとも次を見直す。
- 正本と補助ファイルの整合
- 参照切れや古いパスの有無
- 重複記載の有無
- AI に誤読されやすい曖昧表現
- スキルや補助文書の更新漏れ
ガードレール
- 単体ファイルだけ見て完了と判断しない
- 新しい文書を増やす前に、既存文書への統合余地を考える
- 重複を許容してスピード優先にしない
- 問題を隠すフォールバックを書かない
- 正本の更新を後回しにしない
出力要件
改修結果を報告するときは、少なくとも次を示す。
- 何を正本として扱ったか
- どのファイルを更新したか
- 参照や責務分離をどう維持したか
- 残る未整理点や追加レビューが必要な点
Source: yama/sokra — distributed by TomeVault.