# AI Doc Edit > AGENTS.md、CLAUDE.md、.github/copilot-instructions.md、AI 向け補助文書、共用スキルなどの AI 向け文書を改修するときに使う。SSOT を保ちながら、正本の見極め、参照更新、重複排除、責務分離、関連ファイルの追従修正、改修後の自己レビューまでをツール非依存で定義する。 Use when this capability is needed. - Skill: `tomevault-io/ai-doc-edit` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/ai-doc-edit` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/ai-doc-edit/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/ai-doc-edit --- # AI向け文書改修 このスキルは、AI 向け文書を新規作成、更新、整理するときに使う。 単体ファイルだけを直して終わらせず、正本、入口ファイル、補助文書、関連スキルまで含めて整合を取る。 ## 目的 - AI 向け文書の改修で SSOT を壊さない - 重複、矛盾、更新漏れを減らす - 改修後のレビューラリーを短くする ## 対象 次のような文書を対象にする。 - `AGENTS.md` - `CLAUDE.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](https://github.com/yama/sokra) — distributed by [TomeVault](https://tomevault.io).