ドキュメント検証スキル

プロジェクトドキュメントの品質を自動的かつインタラクティブに検査するための /doc:* コマンドのセット。

クイックスタート

# コミット前の迅速なチェック
/doc:lint

# リンク関係グラフの検査
/doc:links

# 完全監査（すべての検査）
/doc:review

コマンド

/doc:lint — フォーマット検査

モデル: haiku（高速、低コスト） 所要時間: 100ファイルで 30秒以下

検査内容:

• 破損した内部リンク [text](file.md)
• ナビゲーション内の存在しないファイル
• ネーミング規則への違反（ルートの NN_TITLE.md 形式など）
• 空のセクション（## でコンテンツなし）
• issueへのリンクがない TODO/FIXME
• 必須セクションの不足

出力例:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 [LINT-001] 破損したリンク
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 03_REQUIREMENTS.md:45
   > [アーキテクチャを参照](architecture/MISSING.md)

❌ ファイルが存在しません: architecture/MISSING.md

[f]ix  [s]kip  [i]gnore  [e]dit  [g]ithub issue  [x]plain
> _

/doc:links — リンク関係グラフ

モデル: haiku 所要時間: 100ファイルで 30秒以下

検査内容:

• オーファンドキュメント（受け入れリンクがない）
• デッドエンド（出力リンクがない）
• 循環依存
• README内のナビゲーション完全性

除外対象（orphans/dead-endsと見なされない）:

• README.md、CHANGELOG.md
• /GLOSSARY.md、/INDEX.md
• .docvalidate.yml で設定可能

出力例:

 ドキュメントグラフ
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ドキュメント総数: 35
リンク総数: 128

⚠️ オーファン（受け入れリンクなし）:
  - research/old_analysis.md
  - data/transaction-analysis.md

⚠️ デッドエンド（出力リンクなし）:
  - architecture/wallet/COMPONENTS.md

✅ README ナビゲーション: 28/35 ドキュメント（80%）

/doc:terms — 用語管理 ✅

モデル: sonnet（または基本的な検査の場合 haiku） 必須: 02_GLOSSARY.md のグロッサリ

検査内容:

• グロッサリーの用語が一貫して使用されている
• 禁止された同義語の検出（wallet/ウォレット/財布など）
• グロッサリーにない新しい用語（太字で表示）
• グロッサリーのカバレッジ（使用されている用語の%）

出力例:

 グロッサリを読み込みました: 16 用語
 禁止された同義語: 5 グループ

24 ファイルをスキャン中...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 [TERM-001] 禁止された同義語
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 08_KEY_SECURITY.md:82
   禁止された同義語: "wallet" → 「ウォレット」を使用してください

 グロッサリーのカバレッジ
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  使用済み: 14/16 用語（87%）

/doc:viewpoints — 成果物 ✅

モデル: sonnet

viewpoint別チェック:

Viewpoint	成果物	優先度
Data	STATE_MACHINES.md	must
Data	DATA_FLOWS.md	should
Business Rules	BUSINESS_RULES.md	must
Security	THREAT_MODEL.md	must（暗号化向けは重要）
Integration	EVENT_CATALOG.md	should
Traceability	RTM.md	should

出力例:

## Viewpoint カバレッジ

| Viewpoint | 成果物 | ステータス | ファイル |
|-----------|--------|------------|----------|
| Data | STATE_MACHINES | ✅ | architecture/STATE_MACHINES.md |
| Data | DATA_FLOWS | ❌ | architecture/DATA_FLOWS.md |
| Security | THREAT_MODEL | ✅ | architecture/THREAT_MODEL.md |

 全体的な viewpoint カバレッジ: 3/6（50%）

 Security viewpoint が完全にカバーされていません — 暗号化システムにとって重要です！

/doc:contradictions — 矛盾検出 ✅

モデル: sonnet（ローカル分析） 所要時間: 100ファイルで 60秒以下

検査内容:

• 矛盾する値（同じパラメータに異なる数値）
• 相互に排他的な要件
• 制約に矛盾するソリューション
• 異なるドキュメント間での数値パラメータの不一致

出力例:

⚡ /doc:contradictions — 矛盾の検出

 ドキュメントからパラメータを抽出中...
   25 ファイルで 194 個のパラメータが見つかりました

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 重大な矛盾
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 [CONTRADICTION-001] パラメータ「confirmations」に異なる値があります
    03_REQUIREMENTS.md:45 → 3
    architecture/FLOWS.md:128 → 6
   ⚠️ 差分: 100%

 [CONTRADICTION-002] パラメータ「hot_wallet_limit」に異なる値があります
    03_REQUIREMENTS.md:52 → 10%
    08_KEY_SECURITY.md:23 → 5%
   ⚠️ 差分: 100%

 合計: 8 個の重大問題、10 個の警告

/doc:gaps — 完全性 ✅

モデル: sonnet（ローカル分析） 所要時間: 100ファイルで 60秒以下

検査内容:

• 言及されているが展開されていないトピック
• アクセプタンスクライテリアがない要件
• 完全な成果物説明がない実体
• イベントカタログがない統合

出力例:

️ /doc:gaps — カバレッジ完全性の分析

 ドキュメントのギャップをスキャン中...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 警告（注目が必要）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 [GAP-001] 統合（69）が見つかりましたが、イベントカタログがありません
    architecture/EVENT_CATALOG.md — 存在しません
    推奨: イベントを文書化するために EVENT_CATALOG.md を作成してください

 合計: 0 個の重大問題、1 個の警告

/doc:review — 完全監査 ✅

モデル: すべて（カスケード） 所要時間: 100ファイルで 5分以下

すべての検査を最適な順序で実行します:

1. lint + links（フェーズ 1: 基本）
2. terms + viewpoints（フェーズ 2: セマンティック）
3. contradictions + gaps（フェーズ 3: 詳細分析）

機能:

• すべてのコマンド結果の集約
• カテゴリ別の概要表
• 前回の実行との比較
• 優先度別の推奨事項
• 全体品質スコア（0-100）

出力例:

╔══════════════════════════════════════════════════════════════╗
║                DOC:REVIEW 最終レポート                      ║
╚══════════════════════════════════════════════════════════════╝

┌────────────────┬──────────┬──────────┬──────────┐
│ コマンド        │  重大  │  重要  │  情報  │
├────────────────┼──────────┼──────────┼──────────┤
│ lint           │        0 │        6 │       92 │
│ links          │        0 │        0 │        0 │
│ terms          │        0 │      194 │       10 │
│ viewpoints     │        0 │        3 │        0 │
│ contradictions │        8 │       10 │        0 │
│ gaps           │        0 │        1 │        0 │
├────────────────┼──────────┼──────────┼──────────┤
│ 合計           │        8 │      214 │      102 │
└────────────────┴──────────┴──────────┴──────────┘

 Viewpoint カバレッジ: 3/6（50%）
 グロッサリーカバレッジ: 94%

⏱️  実行時間: 0.4 秒

 推奨事項:
  • 最初に 8 個の重大問題を修正してください
  • ⚡ 数値パラメータの矛盾を解決してください
  • Viewpoint カバレッジを増やしてください（現在 50%）

╔══════════════════════════════════════╗
║      総合スコア: 85/100（B）        ║
╚══════════════════════════════════════╝

CLI モード

# 標準モード（非インタラクティブ出力）
./doc_validate.rb lint

# インタラクティブモード（各問題でプロンプト）
./doc_validate.rb lint --interactive

# バッチモード CI/CD 向け（出力なし、終了コード付き）
./doc_validate.rb lint --batch
# 終了コード: 0=成功、1=警告、2=重大

インタラクティブモード

有効化: --interactive または -i

問題が検出された場合:

キー	アクション	説明
f	fix	自動修正を適用（利用可能な場合）
s	skip	スキップ、今は修正しない
i	ignore	.docignore に追加
e	edit	$EDITOR でファイルを開く
x	explain	問題についてさらに詳しく説明

利用可能な自動修正

問題タイプ	fix アクション
broken_link	同様のファイルのファジー検索またはリンク削除
synonym	正規用語への置換
empty_section	空のセクションを削除（確認付き）

エッジケース

状況	動作
fix が利用不可	「(fix unavailable)」を表示
Ctrl+C	session.json に進捗を保存

設定

プロジェクトルートの .docvalidate.yml ファイル:

version: 1

# グロッサリー
glossary:
  file: "02_GLOSSARY.md"
  forbidden_synonyms:
    - ["ウォレット", "wallet", "財布"]
    - ["トランザクション", "tx", "送金"]

# 検査の範囲
scope:
  strict:
    - "*.md"
    - "architecture/**/*.md"
  relaxed:
    - "research/**/*.md"
    trigger: on_change
  ignore:
    - "claudedocs/**"

# orphan/dead-end の除外
link_exceptions:
  not_orphans:
    - "README.md"
    - "CHANGELOG.md"
    - "**/GLOSSARY.md"

# ネーミング規則
formatting:
  root_naming: "^[0-9]{2}_[A-Z_]+\\.md$"

データモデル

.docvalidate/.docignore — 無視される問題

フォーマット: JSON Lines

{"id": "LINT-001", "file": "research/old.md", "reason": "アーカイブ済み", "created": "2025-01-30"}

.docvalidate/history.json — メトリクス履歴

{
  "runs": [{
    "timestamp": "2025-01-30T10:30:00Z",
    "metrics": {"critical": 2, "warning": 5, "info": 8}
  }]
}

エラーハンドリング

AI のフォールバックチェーン

opus（利用不可） → sonnet → haiku → native（AI なし）

オフラインモード

--offline または ネットワーク接続がない場合:

• ✅ /doc:lint — 完全に機能
• ✅ /doc:links — 完全に機能
• ⚠️ /doc:terms — forbidden_synonyms のみ
• ❌ /doc:contradictions — 利用不可
• ❌ /doc:gaps — 利用不可

問題の優先度

優先度	カテゴリ
重大	contradictions、gaps、missing_threat_model
重要	duplicates、terms、missing_state_diagrams
情報	broken_links、formatting、orphans

現在のバージョン（v1.1.0）の制限

機能	ステータス	備考
インタラクティブモード	✅	f/s/i/e/x が動作
バッチモード + 終了コード	✅	CI/CD 向け
自動修正	✅	broken_link、synonym、empty_section
Mermaid グラフ	❌ ロードマップ	リンクグラフの可視化
セッション復旧	❌ ロードマップ	Ctrl+C 後の再開
ユニットテスト	❌ ロードマップ	カバレッジ 0%

関連ドキュメント

• Issue #7 — 主要仕様
• Issue #12 — 改善計画