doc-drift

プロジェクトのドキュメントと実際の実装を突き合わせ、乖離（ドリフト）を検出してレポートにまとめるスキル。

仕様書を正（Single Source of Truth）として扱う。 乖離があった場合、基本的に実装側の問題として報告する。

引数

•引数なし: カレントディレクトリのプロジェクト全体をチェック
•パス指定: 特定のドキュメントやディレクトリに絞ってチェック

実行プロセス

フェーズ1: ドキュメント探索

•
プロジェクトルートから以下のドキュメントソースを探索する
- •README.md（ルート直下および主要ディレクトリ）
- •docs/ ディレクトリ配下のファイル
- •spec/ ディレクトリ配下のファイル
- •ARCHITECTURE.md, CONTRIBUTING.md, CHANGELOG.md など
- •CLAUDE.md などのプロジェクト固有の説明ファイル
- •その他 .md / .rst / .txt のドキュメントファイル
•各ドキュメントの内容を読み取り、記述されている主張・仕様を把握する
•ドキュメントが見つからない場合や、チェック範囲が不明確な場合はユーザーに確認する
•TodoWrite でチェック対象のドキュメント一覧をタスク化する

フェーズ2: 実装との突き合わせ

各ドキュメントに対して以下を実行する：

チェック観点

カテゴリ	チェック内容
API / インターフェース	ドキュメントに記載されたエンドポイント、関数シグネチャ、CLI引数が実装と一致するか
データモデル / ER	ドキュメントのER図・テーブル定義・リレーション・カラム情報がマイグレーションやモデル定義と一致するか
設定・環境変数	記載された設定項目・環境変数が実際に使われているか、デフォルト値は正しいか
ディレクトリ構成	記載されたファイル構成・ディレクトリ構成が実態と一致するか
依存関係	記載されたライブラリ・バージョンが実際の依存定義と一致するか
使用例・コードスニペット	ドキュメント中のコード例が現在のAPIで動作するか
機能説明	記載された機能・振る舞いが実装に存在するか
セットアップ / デプロイ手順	記載されたインストール手順・ビルド手順・デプロイ手順が実際のスクリプトや設定と一致するか
Git Hooks (husky)	ドキュメントに記載された Git Hooks の設定（husky の pre-commit での lint/format、pre-push での build など）が `.husky/` 配下の実際の設定と一致するか
エラーコード / ステータスコード	ドキュメントに記載されたエラーコード・HTTPステータス・レスポンス例が実装と一致するか
権限 / 認証・認可	記載されたロール・権限・認証フローが実装の認証・認可ロジックと一致するか
削除・廃止	実装から削除された機能がドキュメントに残っていないか
未文書化	実装に存在するがドキュメントに記載されていない主要な機能はないか

手順

•ドキュメント内の具体的な主張（関数名、パス、設定値、振る舞いなど）を抽出する
•Explore エージェントや Grep / Glob で対応する実装コードを探す
•主張と実装を比較し、一致・不一致を判定する
•不一致があれば、具体的な箇所（ドキュメント側の行と実装側のファイル:行）を記録する

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

•
出力先を判定する
- •gh コマンドが利用可能かつ git リポジトリ内 → GitHub Issue として作成する（タイトルは review: ドキュメント乖離レポート(<ブランチ名>, <YYYY-MM-DD>) の形式）
- •上記が使えない場合 → プロジェクトルートに doc-drift-report.md を生成する
•レポートの要約（乖離件数、重大度の内訳、特に注意すべき点）をユーザーに報告する

レポート形式

markdown

# Doc Drift Report

> 生成日時: YYYY-MM-DD HH:MM
> 対象プロジェクト: <プロジェクト名>

## サマリー

| 指標 | 値 |
|-----|-----|
| チェックしたドキュメント数 | N |
| 検出した乖離数 | N |
| うち未実装 | N |
| 重大度 🔴 | N |
| 重大度 🟠 | N |
| 重大度 🟡 | N |
| 重大度 🟢 | N |

## 乖離一覧

### 🔴 重大（実装と矛盾）

#### 1. <乖離のタイトル>
- **ドキュメント**: `<ファイルパス>` L<行番号>
  > ドキュメントの該当記述を引用
- **実装**: `<ファイルパス>:<行番号>`
  > 実装の実態を簡潔に説明
- **推奨アクション**: 実装を仕様に合わせる / 仕様書を実装に合わせて更新する / 仕様の承認が必要（未承認の実装） / 未実装（実装待ち） / 要確認

### 🟠 重要（古い情報・欠落）

...

### 🟡 提案（改善の余地あり）

...

### 🟢 軽微（表記ゆれ・些細な不正確さ）

...

### 📋 未実装（仕様書に定義済み・実装待ち）

...

## チェック済みドキュメント

- [x] `README.md` — 乖離 N 件
- [x] `docs/setup.md` — 乖離なし
- ...

重大度の基準

重大度	基準
🔴 重大	仕様書に定義された機能・振る舞いが実装されていない、または実装が仕様と明確に矛盾している
🟠 重要	仕様書にない機能が実装に存在する（未承認の実装）、または仕様の一部が不完全に実装されている
🟡 提案	実装は仕様を満たしているが、仕様書の記述を補足・改善すると利用者体験が向上する
🟢 軽微	表記ゆれ、バージョン番号の古さ、些細な不正確さ

ルール

•推測で乖離を報告しない。実装コードを実際に確認して裏付けを取ること
•乖離の報告には必ずドキュメント側と実装側の両方の具体的な箇所を示すこと
•レポートは事実ベースで書く。修正の判断はユーザーに委ねる
•仕様書を正とするが、実装側が妥当で仕様書が古いと判断できる場合は「仕様書を更新」を推奨アクションとして提示する
•🔴（重大）または🟠（重要）の乖離は必ずレポートに含める
•🟡（提案）や🟢（軽微）は、明確なメリットがある場合のみレポートに含める
•大規模プロジェクトの場合は、主要なドキュメントから優先的にチェックする
•コード内のコメントや docstring はチェック対象外とする（外部向けドキュメントのみ）
•各フェーズの進捗は TodoWrite ツールで管理する