ousiass/doc-drift

doc-drift

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

前提条件

• Claude Code 環境
• gh CLI（GitHub Issue 出力時）

引数

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

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

1. プロジェクトルートから以下を探索する
   • README.md（ルート直下・主要ディレクトリ）
   • docs/, spec/ 配下
   • ARCHITECTURE.md, CONTRIBUTING.md, CHANGELOG.md, CLAUDE.md
   • その他 .md / .rst / .txt
2. 各ドキュメントの内容を読み取り、主張・仕様を把握する
3. ドキュメントが見つからない場合はユーザーに確認する
4. TaskCreate でチェック対象をタスク化する

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

各ドキュメントに対してチェック観点（references/check-criteria.md を参照）に基づき突き合わせる。

手順

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

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

1. AskUserQuestion で出力先をユーザーに確認する：
   • GitHub Issue に作成（推奨）: タイトル review: ドキュメント乖離レポート(<ブランチ名>, <YYYY-MM-DD>)
   • ローカル MD ファイルに保存: プロジェクトルートに doc-drift-report.md を生成
   • コンソール出力: レポートをそのまま会話に出力
2. レポート形式は templates/report.md を参照
3. 要約をユーザーに報告する

ルール

• 推測で乖離を報告しない。実装コードを確認して裏付けを取る
• 乖離にはドキュメント側と実装側の両方の箇所を示す
• レポートは事実ベース。修正判断はユーザーに委ねる
• 仕様書を正とするが、実装が妥当で仕様が古い場合は「仕様書を更新」を推奨
• 🔴🟠 は必ずレポートに含める。🟡🟢 は明確なメリットがある場合のみ
• コード内のコメントや docstring はチェック対象外
• TaskCreate/TaskUpdate で進捗を管理する