| name | doc-drift-detector |
| description | 既存ドキュメント（仕様書・README・ランブック・ADR・OpenAPI）とコードベースの乖離（ドリフト）を検出するスキル。「ドキュメントの乖離を検出して」「仕様書とコードのズレを確認して」「READMEが古くなってないか確認して」「ドキュメントの鮮度をチェックして」「仕様と実装の差分を調べて」などで発動する。検証可能な記述を抽出してコードと突き合わせ、ドキュメント陳腐化・実装の仕様違反・要確認に分類した根拠付きレポートを出す。新規ドキュメントの作成は technical-writer / code-to-specs を使う。 |
| metadata | {"version":"1.0.0","tier":"experimental","category":"documentation","tags":["documentation","drift-detection","verification","maintenance","freshness"]} |
doc-drift-detector
既存ドキュメントとコードベースを突き合わせ、事実として食い違っている箇所を証拠付きで検出する。ドキュメントは書いた瞬間から腐り始める — このスキルは code-to-specs（コード→仕様書の生成）の逆方向にあたる「検証」を担う。
設計思想: 「全文を読み直すレビューではなく、検証可能な主張だけを機械的に潰す。文体・構成の良し悪しは見ない」
| 境界 | 使うスキル |
|---|
| 仕様書をゼロから逆生成したい | code-to-specs |
| README・ガイドを新規作成したい | technical-writer |
| ドキュメントの品質・読みやすさをレビューしたい | agent-reviewer（document 観点） |
| 既存ドキュメントが今のコードと一致しているか検証したい | 本スキル |
設計原則
- 事実ドリフトのみ — パス・コマンド・API・設定値・手順など検証可能な記述だけを対象にする。文体・誤字・構成は指摘しない
- 証拠ペア必須 — すべての指摘に
[DOC: ファイル:行] と [CODE: ファイル:行]（または「該当なし」）の両方を付ける。証拠を示せない指摘は出さない
- 読み取り専用がデフォルト — まずレポートを出し、修正はユーザー承認後に行う
- 優先度駆動 — 全ドキュメントを均等に舐めず、git 履歴から「腐っている可能性が高い順」に検証する
ワークフロー
Step 1: 対象ドキュメントの棚卸し
- ドキュメントを探索する:
README*・docs/**・CONTRIBUTING*・ランブック・ADR・OpenAPI/AsyncAPI・*.md のコードコメント外文書
- 種別（仕様書 / README / ランブック / ADR / API仕様）と検証優先度を付けた一覧をユーザーに提示し、スコープを確定する
- 対象が多い場合は「最終更新が古い順 + 参照頻度が高そうな順」で上位を提案する
Step 2: 検証可能な主張（claim）の抽出
各ドキュメントから以下の種別の主張を抽出し、.drift-work/claims.json に記録する:
| 種別 | 例 | 検証方法 |
|---|
path | 「設定は config/app.yaml にある」 | ファイル・ディレクトリの実在確認 |
command | 「npm run build でビルド」 | マニフェスト（package.json 等）の scripts と照合 |
api | 「POST /v1/orders が注文を作成」 | ルーター実装・OpenAPI 定義と照合 |
config | 「タイムアウトは 30 秒」「環境変数 API_KEY」 | 設定ファイル・環境変数読み取りコードと照合 |
dependency | 「React 17 を使用」 | lockfile・マニフェストの実バージョンと照合 |
structure | 「認証は middleware 層で行う」 | 該当モジュールの実在と責務の確認 |
procedure | 手順書のステップ列 | 各ステップ内のパス・コマンドを個別検証 |
Step 3: コードとの突き合わせ
- claim ごとに Step 2 の検証方法で実体を確認し、
verified / drifted / unverifiable を記録する
- 広域の確認（structure 系）は
Explore エージェント等の探索を活用する
- 動的にしか検証できない主張（実行時挙動）は推測で断定せず
unverifiable とする
Step 4: git 履歴による疑い箇所の優先度付け
- 各ドキュメントの最終更新コミットを特定する:
git log -1 --format=%H -- <doc>
- それ以降に、ドキュメントが言及するコード領域へ入った変更量を集計する:
git log --stat <doc最終更新>..HEAD -- <言及パス>
- 「ドキュメント更新を伴わない大きな実装変更」があった領域の claim を優先的に深掘りする
Step 5: 分類と判定
drifted となった claim を以下に分類する:
| 分類 | 意味 | 是正の向き |
|---|
DOC-STALE | コードが正、ドキュメントが古い | ドキュメントを更新 |
CODE-DRIFT | ドキュメント（仕様）が正、実装が逸脱 | コードを修正（要ユーザー判断） |
UNKNOWN | どちらが正か判断できない | [ASK SME] として要確認リストへ |
正誤の判断に迷う場合は安易に DOC-STALE へ倒さず UNKNOWN とする。severity は critical（手順が壊れる・誤動作を招く）/ major（誤解を招く）/ minor（軽微な不整合）。
Step 6: レポート出力と是正提案
.drift-work/drift-report.md に出力する:
# ドキュメントドリフトレポート
## サマリ
| ドキュメント | claim数 | verified | drifted | unverifiable | 鮮度スコア |
|---|---|---|---|---|---|
## 指摘一覧
### D-001 [DOC-STALE / critical] ビルドコマンドが存在しない
- 主張: 「`npm run build:prod` でビルドする」 [DOC: README.md:42]
- 実体: scripts に `build:prod` は存在せず `build` のみ [CODE: package.json:12]
- 是正案: README.md:42 を `npm run build` に修正
## 要確認リスト（UNKNOWN）
## 検証不能リスト（unverifiable）
是正の実行（ユーザー承認後）:
DOC-STALE → 修正パッチを適用する。大規模な書き直しは technical-writer、章の再生成は code-to-specs へ委譲するCODE-DRIFT → 修正方針をユーザーに確認してから着手する（必要なら systematic-debugging へ）UNKNOWN → 要確認リストとして提示し、勝手に解決しない
連携スキル
code-to-specs — 陳腐化した仕様書の章を再生成するtechnical-writer / runbook-author — README・手順書の書き直しagent-reviewer — 事実性以外（構成・読みやすさ）のレビューcommit-pr-writer — 是正コミット・PR の説明文生成
ガードレール
| 制限 | 内容 |
|---|
| 事実性 | 証拠ペアのない指摘を出さない。検証できない主張を「ドリフト」と断定しない |
| スコープ | 文体・誤字・構成の指摘はしない（事実ドリフトのみ） |
| 変更権限 | レポートまでは読み取り専用。修正はユーザー承認後、DOC-STALE のみ自動適用可 |
| 機密 | レポートに秘匿値（鍵・トークン）を転記しない |
再開プロトコル
「ドリフト検出を再開して」と言われたら .drift-work/claims.json の検証済み claim をスキップし、未検証分から続行する。
