Content Consistency Validator(コンテンツ一貫性バリデーター)
概要
複数のドキュメントソース(ウェブサイト、GitHubリポジトリ、ローカルドキュメント)間で、トーン、用語、フォーマット、構造の一貫性をチェックします。重大度で分類された不一致と、ファイルパスや行番号を含む実行可能な修正提案を備えた読み取り専用レポートを生成します。
使用例
- リリース前監査: 新バージョンのタグ付け前にバリデーターを実行し、README、ドキュメントサイト、変更履歴間のバージョン不一致(例:ウェブサイトではv2.1.0と表示されているが、GitHubのREADMEではv2.0.0のまま)を検出します。
- ブランド変更後チェック: 製品名の変更や用語の更新(例:「plugin」を「extension」に変更)後、すべてのドキュメント、ランディングページ、コントリビューティングガイドで新しい用語が一貫して使用されていることを検証します。
- オンボーディングレビュー: 新しいコントリビューターがドキュメントの混乱を報告した場合、一貫性チェックを実行して、矛盾する機能の主張、古い連絡先情報、ドキュメントソース間の欠落セクションを表面化します。
前提条件
- 少なくとも2つのコンテンツソース(ウェブサイト、GitHubリポジトリ、またはローカルドキュメントディレクトリ)へのアクセス
- リモートURL(デプロイ済みサイト、GitHub rawコンテンツ)用に構成されたWebFetchパーミッション
- 認識可能なパス(
docs/、claudes-docs/、internal/)に保存されたローカルドキュメント
手順
- ソースを発見 — ビルドディレクトリ(
dist/、build/、public/、out/、_site/)、GitHubのREADME/CONTRIBUTINGファイル、ローカルドキュメントフォルダをスキャンします。find . -maxdepth 3 -name "README*" -o -name "CONTRIBUTING*" | head -20 ls -d docs/ claudes-docs/ internal/ 2>/dev/null - 各ソースから構造化データを抽出:バージョン番号、機能の主張、製品名、タグライン、連絡先情報、URL、技術要件。
grep -rn 'v[0-9]\+\.[0-9]\+' docs/ README.md grep -rn -i 'features\|capabilities' docs/ README.md - 抽出を確認 — ソースごとに少なくとも3つのデータポイントがあることを確認します。ソースが空を返した場合は、続行する前にエラーハンドリングの表を確認します。
- 比較マトリックスを構築 — 各ソースを他のすべてのソースとペアにして比較します(ウェブサイト vs GitHub、ウェブサイト vs ローカルドキュメント、GitHub vs ローカルドキュメント)。
diff <(grep -i 'version' README.md) <(grep -i 'version' docs/overview.md) - 不一致を重大度で分類:
- Critical: 矛盾するバージョン番号、相反する機能リスト、不一致の連絡先情報、壊れた相互参照
- Warning: 一貫性のない用語(例:「plugin」と「extension」)、1つのソースでの情報欠落、古い日付
- Informational: スタイルの違い、プラットフォーム固有の表現、異なる詳細レベル
- 信頼度優先順位を適用: ウェブサイト(最も信頼できる) > GitHub(開発者向け) > ローカルドキュメント(内部用)。
- レポートをMarkdownとして生成: エグゼクティブサマリー、ペアごとの比較表、用語一貫性マトリックス、ファイルパスと行番号付きの優先順位付けされたアクションアイテムを含みます。
consistency-reports/YYYY-MM-DD-HH-MM-SS.mdに 保存します。
レポート形式
# 一貫性レポート — YYYY-MM-DD
## エグゼクティブサマリー
| 重大度 | 件数 |
|----------|-------|
| Critical | 2 |
| Warning | 5 |
| Info | 3 |
## ウェブサイト vs GitHub
| フィールド | ウェブサイト | GitHub | 重大度 |
|-------------|---------------|---------------|----------|
| バージョン | v2.1.0 | v2.0.0 | Critical |
| 機能X | 記載あり | 欠落 | Warning |
## アクションアイテム
1. **Critical** — `README.md:14` のバージョンを v2.0.0 → v2.1.0 に更新
2. **Warning** — 「機能X」を `README.md` の機能リストに追加
エラーハンドリング
| エラー | 原因 | 解決策 |
|---|---|---|
| ウェブサイトのコンテンツにアクセス不可 | URLが4xx/5xxを返す、またはビルドディレクトリが存在しない | サイトがデプロイされているか確認するかローカルビルドを実行。WebFetchパーミッションを確認 |
| GitHub APIレート制限 | 短時間に大量のフェッチを実行 | リセットウィンドウ後に一時停止して再試行。認証済みリクエストを使用 |
| ドキュメントディレクトリが存在しない | 期待されるパスが存在しない | 作業ディレクトリを確認。ドキュメントパスを明示的に指定 |
| コンテンツ抽出が空 | クライアントサイドレンダリングがフェッチで表示されない | ライブURLの代わりにローカルビルド出力ディレクトリを使用 |
| diffコマンドの失敗 | ファイルパスに特殊文字が含まれている | diffやgrepに渡すすべてのファイルパスを引用符で囲む |
リソース
- コンテンツソース発見ロジック:
${CLAUDE_SKILL_DIR}/references/how-it-works.md - 信頼度優先順位と検証タイミング:
${CLAUDE_SKILL_DIR}/references/best-practices.md - ユースケースウォークスルー:
${CLAUDE_SKILL_DIR}/references/example-use-cases.md