ousiass doc-drift-git
差分内の変更同士を突き合わせる。 プロジェクト全体のドキュメント走査はしない。 PR 作成前にドキュメントの更新漏れがないか確認するのに最適。
前提条件
- Claude Code 環境
git,ghCLI
引数
- 引数なし: 現在のブランチと
origin/developとの差分を対象 - ブランチ指定: 比較先のリモートブランチを指定（例:
origin/main）
フェーズ1: 差分の取得と分類
git fetch origin- 比較元ブランチを決定（引数あり → 引数使用 / なし →
origin/develop） - マージベースを取得（
git merge-base <比較元> HEAD） - 差分ファイル一覧（
git diff --name-status <merge-base>...HEAD） - コミット一覧（
git log --oneline <merge-base>..HEAD） - 差分ファイルを分類:
- ドキュメント:
.md,.rst,.txt（README、docs/、spec/ 等） - コード: ソースコード、設定、マイグレーション、依存定義
- その他: 画像、バイナリ等（対象外）
- ドキュメント:
- ドキュメントとコードの両方が差分に含まれるか確認
- TaskCreate でチェック対象をタスク化
フェーズ2: ドキュメント差分の分析
各ドキュメントの差分を取得し、追加・変更・削除された記述を抽出。何に関連するか（API、設定、構成等）を特定。
フェーズ3: コード差分の分析
コード差分からドキュメント反映が必要な変更を特定する。チェック観点は references/check-criteria.md を参照。
フェーズ4: 突き合わせと乖離検出
| パターン | 状態 | 重大度の目安 |
|---|---|---|
| コード変更あり・ドキュメント更新なし | 更新漏れ | 影響度に応じて 🔴〜🟡 |
| ドキュメント変更あり・コード変更なし | 先行更新 or 不要変更 | 🟡〜🟢 |
| 両方変更あり・内容が矛盾 | 不一致 | 🔴〜🟠 |
| 両方変更あり・内容が整合 | 正常 | — |
手順
- コード差分の「反映必要な変更」に対して、ドキュメント差分に対応更新があるか確認
- ドキュメント差分の記述変更に対して、コード差分に対応変更があるか確認
- 両方に変更がある場合、内容が整合しているか確認
- 乖離は具体的な箇所（コード側のファイル:行、ドキュメント側のファイル:行）を記録
フェーズ5: レポート生成
AskUserQuestionで出力先確認:- GitHub Issue（推奨）:
review: ドキュメント乖離レポート(<ブランチ名> → <比較先>, <YYYY-MM-DD>) - ローカル MD:
doc-drift-git-report.md - コンソール出力: レポートをそのまま会話に出力
- GitHub Issue（推奨）:
- レポート形式は
templates/report.mdを参照 - 要約をユーザーに報告
重大度の基準
| 重大度 | 基準 |
|---|---|
| 🔴 重大 | API・データモデル・認証等の重要変更にドキュメントが追随していない、または明確に矛盾 |
| 🟠 重要 | 設定・依存関係・セットアップ手順等の変更にドキュメントが追随していない |
| 🟡 提案 | 軽微な機能変更の反映漏れ、ドキュメント補足で利用者体験が向上するもの |
| 🟢 軽微 | 表記ゆれ、バージョン番号の古さ、些細な不正確さ |
ルール
- 差分に集中。 差分に含まれないドキュメントやコードは対象外
- 推測で乖離を報告しない。実際の差分で裏付ける
- 乖離にはコード側とドキュメント側の両方の箇所を示す
- レポートは事実ベース。修正判断はユーザーに委ねる
- 周辺コンテキスト（関数全体、呼び出し元等）も確認
- 🔴🟠 は必ずレポートに含める。🟡🟢 は明確なメリットがある場合のみ
- コード内のコメントや docstring はチェック対象外
- TaskCreate/TaskUpdate で進捗を管理する