doc-claim-validator

ドキュメントの主張の検証

ドキュメントに書かれている内容が実際に正しいかを、検証可能な主張を抽出してコードベースと照合することで確認します。構造の健全性を扱う doc-maintenance を補完し、意味の正確さを確認します。

使用するタイミング

• 大幅なコード変更（リファクタリング、名前変更、API の変更）の後
• リリース前 — 削除または変更された動作を説明するドキュメントを検出します
• 新しい開発者から「ドキュメントの内容が間違っている」と報告されたとき
• プロジェクトのドキュメントの信頼性を定期的に監査するとき
• 構造チェックだけでなく、さらに踏み込んで確認するために doc-maintenance を実行した後

クイックリファレンス

リソース	目的	読み込むタイミング
scripts/extract_claims.py	Markdown から決定論的に主張を抽出	常に（フェーズ 1）
scripts/verify_claims.py	コードベースに対する自動検証	常に（フェーズ 2）
references/claim-taxonomy.md	例を含む主張タイプの完全な分類	判別しにくい主張をトリアージするとき

---

ワークフローの概要

Phase 1: Extract    → Pull verifiable claims from docs (deterministic script)
Phase 2: Verify     → Check claims against codebase (automated + AI)
Phase 3: Report     → Classify failures by severity and type
Phase 4: Remediate  → Fix or flag broken claims

---

フェーズ 1：主張の抽出

抽出スクリプトを実行して、すべての Markdown ファイルを解析し、検証可能な記述を取り出します。

python3 skills/doc-claim-validator/scripts/extract_claims.py [--json] [--root PATH] [--scope docs|manual|all]

スクリプトは、Markdown から次のタイプの主張を抽出します。

タイプ	抽出する内容	ドキュメント内の例
file_path	ファイルパスのパターンに一致するインラインコード	`src/auth/login.ts`
command	コードブロックまたはシェルコマンドを含むインラインコード	`npm run build`
code_ref	インラインコード内の関数、クラス、メソッドへの参照	`authenticate()`
import	コードブロック内の import／require 文	import { Router } from 'express'
config	設定キー、環境変数、設定項目	`MAX_RETRIES=3`
url	外部リンク（http/https）	[docs](https://example.com)
architectural	技術、統合、アーキテクチャパターンに関する、動詞を起点とする文章中の主張	「キャッシュに Redis を使用」「アクターモデルに従う」「Auth0 に委任」
dependency	パッケージ／ライブラリ名に関する主張	「キャッシュに Redis を使用」
behavioral	コードの動作に関する主張	「システムは 3 回再試行します」

最初の 7 タイプは決定論的に抽出されます。スクリプトは architectural に対して、動詞を起点とする正規表現を使用します（uses X、built with X、follows the X pattern、delegated to X、via X、depends on X などのルール）。これにより、以前は検出されずに残っていた、アンカーのない文章中の主張も検出できます。

最後の 2 タイプ（dependency、behavioral）には AI による分析が必要で、フェーズ 2 で処理されます。特に behavioral は、正規表現では抽出されません。行動に関する主張は「ユーザーがログアウトするとキャッシュが無効になる」のように自由形式の文章であり、明確なパターンに一致させるのが難しいためです。行動検証ツールは、1 回の処理でそのような主張を検出し、検証します。

出力： 主張の構造化リスト。各項目には、ソースファイル、行番号、主張タイプ、および主張の文面が含まれます。

---

フェーズ 2：主張の検証

ステップ 2a — 自動検証

抽出した主張に対して検証スクリプトを実行します。

python3 skills/doc-claim-validator/scripts/verify_claims.py [--json] [--root PATH] [--claims-file PATH] [--check-staleness]

Git に基づく差分分析を有効にするには、--check-staleness を渡します（詳細は後述）。

スクリプトは、主張のタイプごとに異なる方法で検証します。

主張タイプ	検証方法	合格条件
file_path	os.path.exists()	参照先のパスにファイルが存在する
command	shutil.which() + スクリプトの確認	バイナリまたはスクリプトファイルが存在する
code_ref	関数名／クラス名を grep -r で検索	コードベース内にシンボルが見つかる
import	モジュールがプロジェクト内または依存関係に存在するか確認	モジュールを解決できる
config	ソース内で設定キーを grep 検索	設定ファイルまたはコード内にキーが見つかる
url	HTTP HEAD リクエスト（任意、デフォルトでは無効）	2xx／3xx を返す

URL の検証を有効にするには、--check-urls を渡します（時間がかかり、ネットワークが必要です）。

ステップ 2b — AI を活用した検証

自動処理の後、スクリプトでは検証できない主張を検証するエージェントをディスパッチします。 4 つの検証担当エージェントのうち 3 つは、general-purpose + sonnet で実行します。振る舞い、アーキテクチャ、コード例の検証には、複数ファイルにまたがる推論が必要であり、haiku の抜粋を読むパターンでは対応が難しいためです。依存関係の検証担当エージェントは、マニフェストファイルとの単純なパターンマッチングのみを行うため、Explore + haiku のままにします。

ディスパッチ戦略：ドキュメントファイル単位のバッチ処理

振る舞いおよびアーキテクチャの検証担当エージェントについては、該当する種類の主張を含む Markdown ファイルごとに、sonnet の呼び出しを 1 回ディスパッチし、そのファイル内のすべての主張を 1 つのプロンプトにまとめます。これにより、各呼び出しのコンテキスト予算を少数の関連する主張に充てられ（ドキュメント内で相互参照することで検証の精度が向上します）、呼び出し総数を主張数ではなくドキュメントセットの規模に応じた数に抑えられます。ドキュメントが約 50 件、アーキテクチャに関する主張が約 150 件のプロジェクトでは、sonnet の呼び出しは約 10～20 回を見込んでください（主張を含むドキュメントのみが呼び出しの対象となり、150 回ではありません）。

精度がコストより重要なリリース監査では、主張単位のディスパッチを実行します。主張ごとに sonnet の呼び出しを 1 回行い、それぞれにドキュメント全体をコンテキストとして渡します。コストは高くなりますが、精度も高くなります。

検証担当

検証担当 1 — 依存関係の主張の検証（subagent_type: "Explore"、 model: "haiku"）： package.json、requirements.txt、go.mod、Cargo.toml、または同等の依存関係マニフェストを読みます。ライブラリ、フレームワーク、サービスの使用に関するドキュメント内の主張を相互参照します。プロジェクトに含まれていない依存関係に言及する主張を報告します。マニフェストとのパターン照合に sonnet の推論能力は不要なため、haiku を使用します。

検証担当 2 — 動作に関する主張の検証（subagent_type: "general-purpose"、 model: "sonnet"、ドキュメントファイルごと）： 対象範囲内の各 Markdown ファイルについて、そのファイルの内容を渡して sonnet エージェントを起動します。エージェントは、（a）ファイル内の動作に関する主張（「3 回再試行する」「5 分間キャッシュする」「処理前に入力を検証する」「ユーザーがログアウトするとキャッシュが無効になる」など）を見つけ、（b）grep／codanna／Read を使って関連コードを探し、（c）主張が実装と一致するかを検証します。各主張について、confirmed／contradicted／unverifiable／conditional のステータスとともに報告します。動作の検証では複数のファイル（ハンドラー → ミドルウェア → 設定）をたどり、正常系とエラー系の動作を区別する必要があるため、sonnet が必要です。

検証担当 3 — アーキテクチャに関する主張の検証（subagent_type: "general-purpose"、model: "sonnet"、ドキュメントファイルごと）： 抽出された architectural の主張がある各 Markdown ファイルについて、ファイルの内容と事前に抽出された主張の一覧を渡して sonnet エージェントを起動します。エージェントは、各主張を次の方法で検証します。

• uses／built／depends／via のフレームについて：依存関係マニフェスト、設定ファイル、ソースの import で、指定された技術を確認します。
• delegated のフレームについて：指定されたサービスに対応する SDK の import や HTTP 連携を確認します。
• follows／uses_pattern のフレームについて：ディレクトリ構成、クラス名、コードの構成を確認し、指定されたアーキテクチャパターン（例：CQRS ならコマンド／クエリのハンドラーとイベントストアの分離、ヘキサゴナルアーキテクチャならアダプター／ポートのディレクトリ、Saga なら名前付きの遷移を持つオーケストレータークラス）を確認します。

各主張について、confirmed／contradicted／unverifiable／conditional のステータスとともに報告します。アーキテクチャパターンは単一のファイルに 1 対 1 で対応するわけではなく、パターンを認識するにはコードベースを十分に読む必要があるため、sonnet が必要です。

検証担当 4 — コード例の検証（subagent_type: "general-purpose"、 model: "sonnet"、ドキュメントファイルごと）： 使用例を示すドキュメント内のコードブロックについて、関数シグネチャ、パラメーター名、戻り値の型、import パスが現在のコードベースと一致するかを検証します。コピーして貼り付けると失敗する例を報告します。シグネチャの確認には、現在の実装を読み、比較する必要があります。haiku で抜粋を読むだけでは不十分なため、sonnet が必要です。

検証担当 1、2、3、4 を並行して起動します。検証担当 2／3／4 内のドキュメントファイルごとの処理は、順次実行します（コストが許せば、小規模な並列バッチで実行してもかまいません）。

ステップ 2c — Git の陳腐化スコアの算出

存在確認に合格した主張について、古くなっている可能性の高い主張を見つけるためにドリフトスコアを算出します。

python3 skills/doc-claim-validator/scripts/verify_claims.py --check-staleness

合格した各主張について、スクリプトは次の処理を行います。

1. ドキュメントファイルの最終 Git 更新日時を取得します
2. 対象ファイルの最終 Git 更新日時を取得します
3. ドキュメントの最終編集後に対象ファイルを変更したコミット数を数えます
4. ドリフトスコアを割り当てます：低（1～3 コミット）、中（4～9）、高（10 以上）

ドリフトの大きい主張は、AI によるレビューの最有力候補です。対象ファイルが大幅に変更されている一方、ドキュメントは更新されていないため、古い動作を説明している可能性が高いからです。

陳腐化レポートは、スコアの降順で並べたランキング表として追加されます。

---

フェーズ 3：レポート

自動検出の結果と AI の検出結果を、単一のレポートに統合します。失敗した主張をそれぞれ分類します。

重大度

レベル	意味	例
P0	ユーザー向けドキュメントの記述に従うと問題が発生する	チュートリアルで削除済みの API エンドポイントを示している
P1	開発者向けドキュメントで、存在しないコード構造を参照している	README が名前変更済みの auth.validate() を参照している
P2	動作に関する記述が実態と合わなくなっている	「3 回再試行する」とあるが、再試行ロジックは削除されている
P3	依存関係やインポートに関する記述が古くなっている	「Express を使用」とあるが、Fastify に移行済み
P4	軽微で見た目上の不正確さ	設定キーの名前は変更されたが、動作に変更はない

問題のカテゴリ

カテゴリ	説明
missing_target	参照先のファイル、関数、シンボルが存在しない
wrong_signature	関数は存在するが、シグネチャがドキュメントの記述と異なる
stale_behavior	動作に関する記述が実装と一致しない
dead_dependency	ドキュメントがプロジェクトに含まれていない依存関係を参照している
phantom_pattern	アーキテクチャに関する記述（「CQRS を使用」「アクターモデルに従う」など）がコードベースで裏付けられていない
wrong_integration	ドキュメントで言及されているサービス／SDK（「Auth0 に委任」など）が実際には統合されていない
broken_example	コード例を実行すると失敗する
dead_url	外部リンクが 4xx／5xx を返す
phantom_config	ドキュメントで参照されている設定オプションがコードに存在しない

---

フェーズ 4：修正

問題が確認された記述ごとに、対応を決定します。

対応	適用する場合	方法
ドキュメントを更新	コードは正しく、ドキュメントが古い	コードに合わせてドキュメントを編集する
レビュー対象としてフラグを付ける	コードとドキュメントのどちらが誤っているか不明	人によるレビュー用の Issue を作成する
記述を削除	参照先の機能が削除されている	該当セクションを削除するか、書き換える
例を更新	コード例が古くなっている	現在のコードに合わせて例を書き直す

doc-maintenance の規約に従い、適切なエージェントに修正を割り当てます。

• API／CLI リファレンスドキュメントには reference-builder
• アーキテクチャおよび開発者向けドキュメントには technical-writer
• ユーザー向けチュートリアルおよびガイドには learning-guide

---

doc-maintenance との統合

このスキルは、doc-maintenance の後に実行するよう設計されています。

doc-maintenance  →  Structural health (links, orphans, folders, staleness)
doc-claim-validator  →  Semantic accuracy (do claims match reality?)

この 2 つのスキルは、同じ重大度の基準と修正担当エージェントの割り当て方法を共有しています。両方の結果をまとめて、単一のドキュメント健全性レポートにできます。

---

アンチパターン

• 動作に関する記述を自動修正しないでください。意図に関する人の判断が必要です。
• インラインコードの参照をすべてファイルパスとして扱わないでください（`true` はファイルではありません）。
• アーカイブ済みのドキュメント（docs/archive/）の記述を検証しないでください。これらは過去の記録です。
• 任意機能や条件付き機能をエラーにしないでください。代わりに「条件付き」として記録してください。
• デフォルトでは URL を確認しないでください。時間がかかり、動作も不安定なためです。確認する場合のみ明示的に有効にしてください。
• `` comment と記されたコードブロックは検証しないでください。

---

同梱リソース

スクリプト

• scripts/extract_claims.py — Markdown ファイルから記述を決定論的に抽出します
• scripts/verify_claims.py — 抽出した記述をコードベースに照らして自動検証します

リファレンス

• references/claim-taxonomy.md — 記述タイプの完全な分類。抽出パターンと例を含みます