ousiass/doc-drift-git

doc-drift-git

差分内の変更同士を突き合わせる。 プロジェクト全体のドキュメント走査はしない。 PR 作成前にドキュメントの更新漏れがないか確認するのに最適。

前提条件

• Claude Code 環境
• git, gh CLI

引数

• 引数なし: 現在のブランチと origin/develop との差分を対象
• ブランチ指定: 比較先のリモートブランチを指定（例: origin/main）

フェーズ1: 差分の取得と分類

1. git fetch origin
2. 比較元ブランチを決定（引数あり → 引数使用 / なし → origin/develop）
3. マージベースを取得（git merge-base <比較元> HEAD）
4. 差分ファイル一覧（git diff --name-status <merge-base>...HEAD）
5. コミット一覧（git log --oneline <merge-base>..HEAD）
6. 差分ファイルを分類:
   • ドキュメント: .md, .rst, .txt（README、docs/、spec/ 等）
   • コード: ソースコード、設定、マイグレーション、依存定義
   • その他: 画像、バイナリ等（対象外）
7. ドキュメントとコードの両方が差分に含まれるか確認
8. TaskCreate でチェック対象をタスク化

フェーズ2: ドキュメント差分の分析

各ドキュメントの差分を取得し、追加・変更・削除された記述を抽出。何に関連するか（API、設定、構成等）を特定。

フェーズ3: コード差分の分析

コード差分からドキュメント反映が必要な変更を特定する。チェック観点は references/check-criteria.md を参照。

フェーズ4: 突き合わせと乖離検出

| パターン | 状態 | 重大度の目安 | |---------|------|------------| | コード変更あり・ドキュメント更新なし | 更新漏れ | 影響度に応じて 🔴〜🟡 | | ドキュメント変更あり・コード変更なし | 先行更新 or 不要変更 | 🟡〜🟢 | | 両方変更あり・内容が矛盾 | 不一致 | 🔴〜🟠 | | 両方変更あり・内容が整合 | 正常 | — |

手順

1. コード差分の「反映必要な変更」に対して、ドキュメント差分に対応更新があるか確認
2. ドキュメント差分の記述変更に対して、コード差分に対応変更があるか確認
3. 両方に変更がある場合、内容が整合しているか確認
4. 乖離は具体的な箇所（コード側のファイル:行、ドキュメント側のファイル:行）を記録

フェーズ5: レポート生成

1. AskUserQuestion で出力先確認:
   • GitHub Issue（推奨）: review: ドキュメント乖離レポート(<ブランチ名> → <比較先>, <YYYY-MM-DD>)
   • ローカル MD: doc-drift-git-report.md
   • コンソール出力: レポートをそのまま会話に出力
2. レポート形式は templates/report.md を参照
3. 要約をユーザーに報告

重大度の基準

| 重大度 | 基準 | |-------|------| | 🔴 重大 | API・データモデル・認証等の重要変更にドキュメントが追随していない、または明確に矛盾 | | 🟠 重要 | 設定・依存関係・セットアップ手順等の変更にドキュメントが追随していない | | 🟡 提案 | 軽微な機能変更の反映漏れ、ドキュメント補足で利用者体験が向上するもの | | 🟢 軽微 | 表記ゆれ、バージョン番号の古さ、些細な不正確さ |

ルール

• 差分に集中。 差分に含まれないドキュメントやコードは対象外
• 推測で乖離を報告しない。実際の差分で裏付ける
• 乖離にはコード側とドキュメント側の両方の箇所を示す
• レポートは事実ベース。修正判断はユーザーに委ねる
• 周辺コンテキスト（関数全体、呼び出し元等）も確認
• 🔴🟠 は必ずレポートに含める。🟡🟢 は明確なメリットがある場合のみ
• コード内のコメントや docstring はチェック対象外
• TaskCreate/TaskUpdate で進捗を管理する