# Doc Drift Git

> gitリモートとの差分を対象にドキュメントとコードの整合性をチェックし乖離レポートを生成。

- Skill: `ousiass/doc-drift-git` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ousiass/doc-drift-git`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ousiass/doc-drift-git/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ousiass (https://skillmd.com/u/ousiass)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/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 で進捗を管理する