| name | doc-updater |
| description | 対象の変更がドキュメントに与える影響を判断し、必要な更新だけを行うスキル。呼び出し元から対象ファイル集合が渡されればそれを使い、無ければ staged change、さらに無ければ git diff HEAD と未追跡ファイルにフォールバックする。commit-push スキルから呼び出された場合、またはユーザーが /doc-updater と明示的に指示した場合にのみ実行し、自律的には起動しない。 |
doc-updater
概要
ドキュメントの品質基準は agents-md-creator スキルに集約されている。このスキルは対象差分を分析し、更新の要否とスコープを判断した上で、agents-md-creator の基準に従って増分更新を行う。
前提
- 差分は最小限に留める
- このスキル自身では
git add しない。stage の判断は呼び出し元の責務
- 呼び出し元からセッション中の失敗や修正で残すべき学びが渡された場合は反映する
1. 対象の把握
対象ファイル集合は次の優先順で決める。
- 呼び出し元から渡された対象ファイル一覧(rename の旧/新パス、削除パスを含む)
git diff --cached に出力があれば staged change
git diff HEAD と未追跡ファイル(git status で ?? のもの)
その上で以下を収集する。
- 各ファイルの差分内容(未追跡ファイルはファイル本文)
- リネームされたファイルの旧パスと新パス
- 削除されたファイルのパス(ドキュメント内に参照が残っていないか確認するため)
2. ドキュメント構造の検出
ルート直下のエージェント指示ファイル(AGENTS.md, CLAUDE.md, GEMINI.md)のうち、シンボリックリンクでない実ファイルを特定する。symlink の場合はリンク先の実ファイルだけを編集対象にする。
分割ドキュメント構造(docs/agents/*.md など)がある場合はそれも確認する。
README.md などの人間向けドキュメントと、エージェント向け指示ファイルは役割が違う。片方が対象差分に含まれていることは、もう一方を確認済みとする根拠にならない。特にコマンド、検証手順、ファイル構成、重要パス、設定、CLI workflow の変更では両方を確認する。
3. 更新要否の判定
以下は更新する。
- 機能追加、API 変更、振る舞い変更
- エージェント、スキル、フック、CLI workflow の変更
- 依存関係ファイルの変更
- ビルド、テスト、実行コマンドの変更
- 設定ファイルの変更
- ファイルやディレクトリのリネーム、削除
- README や AGENTS 系に書かれている手順、構成、制約が古くなる変更
以下は更新不要。
- 変数名変更、関数抽出、内部リファクタリングだけで仕様が変わらない
- テストやコメントだけの変更
- ドキュメントファイルだけの変更
- 該当するドキュメント更新が、このセッション内で既に済んでいる
- 呼び出し元が「更新済み」または「更新不要と判断済み」と明示している
迷ったら更新する側に倒す。古い手順や重要パスを残して次回の作業を誤らせるリスクの方が、余分な更新より大きい。
すべて更新不要なら、その旨だけを返して終了する。
4. 更新の実行
agents-md-creator スキルの SKILL.md と references/best-practices.md を読み、その品質基準・レビュー観点・修正優先順位に従って更新する。
ただし以下は doc-updater 固有の振る舞いとしてオーバーライドする。
- リポジトリ全体の調査は行わない(ステップ1 で把握した差分が入力)
- 300 行を超えたファイルがある場合は、
警告: <file> が 300 行を超えています を報告し、agents-md-creator による全体整理を提案する
更新したファイルのパスを呼び出し元に伝える。判定根拠・変更概要・行数は書かない。