doc-drift-detector

ドキュメントのドリフト検出

このエージェントは、コードディレクトリとドキュメントを対応付け、Git の変更履歴を比較し、AST を使って Python の関数シグネチャを抽出し、すべての Markdown リンクとアンカーを検証することで、ドキュメントのドリフトを検出します。また、重み付けされた 0～100 のスケールで鮮度を評価します。4 つの CLI ツールはすべて Python 標準ライブラリのみを使用します。

主な機能

• ドリフトの総合分析 — ドキュメントとコードの対応付け、Git の履歴の比較、ファイル名の変更、バージョンのずれ、参照切れ、構造上の欠落を検出し、各問題をカテゴリ、重大度、修正方法で分類します。
• API ドキュメントの検証 — AST ベースで抽出した Python のシグネチャやクラスを Markdown の API ドキュメントと比較します（ドキュメント化されていない項目、実在しない項目のドキュメント、パラメーターの不一致、非推奨項目）。
• 鮮度のスコアリング — 5 つの指標で重み付けした 0～100 の鮮度スコアを算出します。CI のしきい値ゲートと README に特化したモードにも対応します。
• リンク整合性の監査 — ローカルファイル、アンカー、ドキュメント間のアンカー、画像、大文字と小文字の区別、重複アンカーを検証します。外部 URL のチェックも任意で実行できます。
• ドリフトの分類 — 構造、事実、参照、時間、意味のカテゴリに分類し、それぞれに修正の振り分け用の [AUTO]／[SEMI]／[MANUAL] を付与します。
• CI/CD との連携 — 監視を継続するためのゼロ以外の終了コード、JSON 出力、GitHub Actions と pre-commit の設定例を提供します。

使用する場面

• ドキュメントがコードと同期しなくなった場合 — ドリフトの総合分析を実行します。
• リリースの準備をする場合 — 全体の鮮度スコアをゲートとして設定します。
• CI でドキュメントのゲートを実行する場合 — ドリフトの重大度が高い／重大な PR やリンク切れがある PR を失敗させます。
• Python のソースコードに照らして API ドキュメントの正確さを監査する場合。
• リファクタリング後に README の状態とリンクの整合性を確認する場合。

最初に確認すること

検出を実行する前に、次の入力を確認してください。不明または曖昧な項目があれば、推測せずに質問してください。

• チェックの種類 — ドリフトの総合分析、鮮度スコア、API ドキュメントの検証、リンク監査のいずれか（drift_analyzer.py、doc_staleness_scorer.py、api_doc_validator.py、link_checker.py のどれを使用するかを選択します）
• リポジトリとドキュメント／ソースのパス — リポジトリ、および比較するコードとドキュメントのディレクトリ（ツールがスキャンする入力）
• しきい値とゲート — CI 失敗の最小重大度または鮮度のしきい値（--min-severity／--threshold と終了コードのゲートを設定します）

停止ルール：出力に最も大きく影響する 2～3 項目だけを質問してください。ユーザーが「とりあえず下書きして」と言った場合は作業を進め、成果物の冒頭に前提を列挙してください。

ツール

ツール	用途	コマンド
drift_analyzer.py	コードとドキュメント間のドリフトの総合分析	python scripts/drift_analyzer.py <repo> --min-severity high --json
doc_staleness_scorer.py	ドキュメントの鮮度を 0～100 で評価	python scripts/doc_staleness_scorer.py <repo> --threshold 60
api_doc_validator.py	Python のソースコード（AST）に照らした API ドキュメントの検証	python scripts/api_doc_validator.py <src> <docs> --recursive
link_checker.py	すべての Markdown リンクとアンカーの監査	python scripts/link_checker.py <repo> --broken-only

すべてのツール：Python 3.8 以降の標準ライブラリのみを使用します。--json と --help に対応し、CI 用にゼロ以外の終了コードを返します。どの OS でも利用できます。

参考資料

タスクに合った参考資料を読み込みます。このファイルは簡潔に保ち、詳細は必要に応じて参照してください。

• references/workflows-and-tool-reference.md — クイックスタート、5 つの主要ワークフロー（完全分析、API 検証、README の健全性確認、リンク監査、CI モニタリング）の出力例、GitHub Actions と pre-commit の設定例、各ツールのパラメーター／出力／終了コードの完全なリファレンスが記載されています。ツールの実行時や CI の組み込み時に参照してください。
• references/scoring-categories-and-troubleshooting.md — 古さのスコアリングモデルと重み付け、5 つのドリフトカテゴリ、自動修正と手動修正の分類、詳細な統合ポイント、アンチパターン、トラブルシューティング表、成功基準が記載されています。結果の解釈やドリフトのトリアージ時に参照してください。
• references/documentation_standards.md — README の構成、API ドキュメント、変更履歴、ADR、ドキュメント・アズ・コードの標準が記載されています。
• references/drift_prevention_guide.md — 結合戦略、CI ゲート、レビューチェックリスト、予防パターンが記載されています。

アセット

アセット	説明
ドリフトレポートテンプレート	ドリフト分析レポートのテンプレート
サンプルドリフトデータ	テストとデモ用の JSON サンプル

対象範囲と制限事項

対象範囲：

• 任意の git リポジトリにおける、git 履歴に対するドキュメントドリフトの検出
• Python API ドキュメントの AST ベース検証（関数シグネチャ、クラス定義、パラメーター、戻り値の型）
• 内部リンクの検証（ローカルファイル、Markdown アンカー、ドキュメント間アンカー、画像、大文字と小文字の区別チェックを含む）
• 重みを設定でき、CI/CD のしきい値適用に対応した多次元の古さスコアリング

対象外：

• Python 以外のソースコードの API 検証 — AST ベースのバリデーターが解析するのは Python のみです。TypeScript、Go、Rust、Java の API には、言語固有のドキュメント生成ツールを使い、リンクチェッカーと組み合わせてください。
• 外部 URL の稼働状況モニタリング — --check-external は単発の HEAD リクエストを実行しますが、継続的なモニタリングには対応していません。稼働状況ダッシュボードには senior-devops スキルを使用してください。
• ドキュメントの自動書き換え — ツールは問題を [AUTO]、[SEMI]、[MANUAL] に分類しますが、置き換え用のテキストは生成しません。AI によるドキュメント提案には code-reviewer スキルを使用してください。
• コンテンツの品質や読みやすさの評価 — 古さのスコアリングで測定するのは鮮度と構造上の完全性であり、文章の品質ではありません。文章作成のガイドラインについては standards/communication ライブラリを参照してください。

統合ポイント

スキル	統合	データフロー
code-reviewer	ドリフトレポートを PR レビューコメントに含める	drift_analyzer.py --json の出力を、ドキュメントの健全性セクションとしてレビューチェックリストに取り込みます
senior-devops	CI/CD パイプラインに古さのゲートを追加する	doc_staleness_scorer.py --threshold 50 は失敗時に終了コード 1 を返し、デプロイをブロックします
senior-qa	QA の受け入れ基準にドキュメント品質を含める	link_checker.py --json の出力を、テストカバレッジ指標と併せて QA ダッシュボードに統合します
senior-fullstack	スキャフォールド後に生成されたプロジェクトドキュメントを検証する	api_doc_validator.py をスキャフォールド済みの docs/ ディレクトリに対して実行し、生成された API ドキュメントがソースと一致することを確認します
senior-secops	セキュリティドキュメントの最新性を監査する	drift_analyzer.py --scope security/ で、セキュリティドキュメントがポリシー変更に追随していない場合に検出します
senior-architect	アーキテクチャ決定記録（ADR）の最新性を確認する	doc_staleness_scorer.py --required-sections "Status,Context,Decision,Consequences" で ADR の完全性を検証します