ryonakae/doc-updater

doc-updater

概要

ドキュメントの品質基準は agents-md-creator スキルに集約されている。このスキルはセッション中の差分を分析し、更新の要否とスコープを判断した上で、agents-md-creator の基準に従って増分更新を行う。実行環境が skill の明示呼び出しをサポートしていればそれを使い、サポートしていなければこのファイルを読んで同じ手順を inline で実行する。

前提

• 差分は最小限に留める
• ドキュメントを更新したら git add でステージングに追加する
• 呼び出し元から staged file list と rename/delete context が渡されている場合は、それを優先して使う
• 呼び出し元からセッション中の失敗や修正で残すべき学びが渡された場合は反映する

スキップしてよい条件

• 呼び出し元が「このセッションで既にドキュメント更新済み」と明示している
• 呼び出し元が「更新不要と判断済み」と明示している
• ドキュメントファイルがすでに staged されていて、今回のコード変更で追加更新が不要と判断できる

スキップする場合は「ドキュメント更新は不要です」とだけ返して終了する。

1. ドキュメント構造の検出

ルート直下のエージェント指示ファイル（AGENTS.md, CLAUDE.md, GEMINI.md）のうち、シンボリックリンクでない実ファイルを特定する。symlink の場合はリンク先の実ファイルだけを編集対象にする。

分割ドキュメント構造（docs/agents/*.md など）がある場合はそれも確認する。

2. 変更の把握

git diff --cached に出力があれば staged change だけを対象にする。空の場合は git diff HEAD と未追跡ファイル（git status で ?? のもの）にフォールバックする。

以下の情報を収集する:

• 変更ファイル一覧（追加・変更・削除・リネームを含む）
• 各ファイルの差分内容（未追跡ファイルはファイル本文）
• リネームされたファイルの旧パスと新パス
• 削除されたファイルのパス（ドキュメント内に参照が残っていないか確認するため）

3. 更新要否の判定

以下は更新する。

• 機能追加、API 変更、振る舞い変更
• エージェント、スキル、フック、CLI workflow の変更
• 依存関係ファイルの変更
• ビルド、テスト、実行コマンドの変更
• 設定ファイルの変更
• ファイルやディレクトリのリネーム、削除
• README や AGENTS 系に書かれている手順、構成、制約が古くなる変更

以下は更新不要。

• 変数名変更、関数抽出、内部リファクタリングだけで仕様が変わらない
• テストやコメントだけの変更
• ドキュメントファイルだけの変更

迷ったら更新する側に倒す。

4. 更新の実行

agents-md-creator スキルの SKILL.md と references/best-practices.md を読み、その品質基準・レビュー観点・修正優先順位に従って更新する。

ただし以下は doc-updater 固有の振る舞いとしてオーバーライドする:

• リポジトリ全体の調査は行わない（ステップ2 で把握した差分が入力）
• 300 行以上になった場合は、出力に警告を含め agents-md-creator による全体整理を提案する

5. 出力

最後に次を簡潔に報告する。

• 編集対象として選択したファイル
• 更新したファイル名と変更概要
• 更新をスキップしたファイルとその理由
• エージェント指示ファイルを更新した場合は現在の行数