jpskill.com
✍️ ライティング コミュニティ

documentation-audit

コードベースとドキュメントの整合性を確認し、リリース前後の乖離を検出・検証するSkill。

📜 元の英語説明(参考)

This skill should be used when verifying documentation claims against codebase reality. Triggers on "audit docs", "verify documentation", "check docs", "docs accurate", "documentation drift", "before release", "after refactor", "docs don't match". Uses two-pass extraction with pattern expansion for comprehensive detection.

🇯🇵 日本人クリエイター向け解説

一言でいうと

コードベースとドキュメントの整合性を確認し、リリース前後の乖離を検出・検証するSkill。

※ jpskill.com 編集部が日本のビジネス現場向けに補足した解説です。Skill本体の挙動とは独立した参考情報です。

⬇ このSkillをダウンロード(.skill) 元のソースを見る ↗

⚠️ ダウンロード・利用は自己責任でお願いします。当サイトは内容・動作・安全性について責任を負いません。

🎯 このSkillでできること

下記の説明文を読むと、このSkillがあなたに何をしてくれるかが分かります。Claudeにこの分野の依頼をすると、自動で発動します。

📦 インストール方法 (3ステップ)

  1. 1. 上の「ダウンロード」ボタンを押して .skill ファイルを取得
  2. 2. ファイル名の拡張子を .skill から .zip に変えて展開(macは自動展開可)
  3. 3. 展開してできたフォルダを、ホームフォルダの .claude/skills/ に置く
    • · macOS / Linux: ~/.claude/skills/
    • · Windows: %USERPROFILE%\.claude\skills\

Claude Code を再起動すれば完了。「このSkillを使って…」と話しかけなくても、関連する依頼で自動的に呼び出されます。

詳しい使い方ガイドを見る →
最終更新
2026-05-17
取得日時
2026-05-17
同梱ファイル
1

📖 Skill本文(日本語訳)

※ 原文(英語/中国語)を Gemini で日本語化したものです。Claude 自身は原文を読みます。誤訳がある場合は原文をご確認ください。

ドキュメンテーション監査

ドキュメンテーション内の記述を、実際のコードベースと二段階のアプローチで体系的に検証します。

概要

核心原則: リコール率が低いことは偽陽性よりも悪いことです。見落とされた記述は目に見えないままになります。

二段階プロセス:

  1. パス1: ドキュメントから直接記述を抽出し、検証します。
  2. パス2A: 誤った記述からパターンを拡張し、同様の問題を見つけます。
  3. パス2B: コードベースのインベントリとドキュメント化された項目を比較します（ギャップ検出）。

クイックスタート

  1. 対象ドキュメントを特定します（ユーザー向けのみ、plans/、audits/ はスキップ）。
  2. レポートヘッダー用に現在の git コミットをメモします。
  3. 並列エージェント（ドキュメントごとに1つ）を使用してパス1の抽出を実行します。
  4. 誤った記述のパターンを分析します。
  5. パス2の拡張検索を実行します。
  6. docs/audits/AUDIT_REPORT_YYYY-MM-DD.md を生成します。

記述の種類

種類 例 検証
file_ref scripts/foo.py ファイルは存在しますか？
config_default "デフォルトは 'AI Radio'" スキーマ/コードを確認します。
env_var STATION_NAME .env.example + コード内にありますか？
cli_command --normalize フラグ スクリプトはそれをサポートしていますか？
behavior "2分ごとに実行される" タイマー/コードを確認します。

検証の信頼性:

  • ティア1（自動）: file_ref、config_default、env_var、cli_command
  • ティア2（半自動）: symbol_ref、version_req
  • ティア3（人間によるレビュー）: behavior、constraint

パス2 パターン拡張

パス1の後、誤った記述を分析し、同様のパターンを検索します。

Dead script found: diagnose_track_selection.py
  → Search: all script references → Found 8 more dead scripts

Wrong interval: "every 10 seconds"
  → Search: "every \d+ (seconds?|minutes?)" → Found 3 more

Wrong service name: ai-radio-break-gen.service
  → Search: service/timer names → Found naming inconsistencies

常に確認すべき一般的なパターン:

  • デッドスクリプト: scripts/*.py 参照
  • タイマー間隔: every \d+ (seconds?|minutes?)
  • サービス名: ai-radio-*.service、*.timer
  • 設定変数: RADIO_* 環境変数
  • CLIフラグ: bash ブロック内の --flag パターン

出力形式

docs/audits/AUDIT_REPORT_YYYY-MM-DD.md を生成します。

# Documentation Audit Report
Generated: YYYY-MM-DD | Commit: abc123

## Executive Summary
| Metric | Count |
|--------|-------|
| Documents scanned | 12 |
| Claims verified | ~180 |
| Verified TRUE | ~145 (81%) |
| **Verified FALSE** | **31 (17%)** |

## False Claims Requiring Fixes
### CONFIGURATION.md
| Line | Claim | Reality | Fix |
|------|-------|---------|-----|
| 135 | `claude-sonnet-4-5` | Actual: `claude-3-5-sonnet-latest` | Update |

## Pattern Summary
| Pattern | Count | Root Cause |
|---------|-------|------------|
| Dead scripts | 9 | Scripts deleted, docs not updated |

## Human Review Queue
- [ ] Line 436: behavior claim needs verification

詳細な参照

実行チェックリストとアンチパターンについては、checklist.md を参照してください。 記述抽出パターンについては、extraction-patterns.md を参照してください。

📜 原文 SKILL.md(Claudeが読む英語/中国語)を展開

<!-- ABOUTME: Documentation audit skill for verifying claims against codebase --> <!-- ABOUTME: Uses two-pass extraction with pattern expansion for comprehensive detection -->

Documentation Audit

Systematically verify claims in documentation against the actual codebase using a two-pass approach.

Overview

Core principle: Low recall is worse than false positives—missed claims stay invisible.

Two-pass process:

  1. Pass 1: Extract and verify claims directly from docs
  2. Pass 2A: Expand patterns from false claims to find similar issues
  3. Pass 2B: Compare codebase inventory vs documented items (gap detection)

Quick Start

  1. Identify target docs (user-facing only, skip plans/, audits/)
  2. Note current git commit for report header
  3. Run Pass 1 extraction using parallel agents (one per doc)
  4. Analyze false claims for patterns
  5. Run Pass 2 expansion searches
  6. Generate docs/audits/AUDIT_REPORT_YYYY-MM-DD.md

Claim Types

Type Example Verification
file_ref scripts/foo.py File exists?
config_default "defaults to 'AI Radio'" Check schema/code
env_var STATION_NAME In .env.example + code?
cli_command --normalize flag Script supports it?
behavior "runs every 2 minutes" Check timers/code

Verification confidence:

  • Tier 1 (auto): file_ref, config_default, env_var, cli_command
  • Tier 2 (semi-auto): symbol_ref, version_req
  • Tier 3 (human review): behavior, constraint

Pass 2 Pattern Expansion

After Pass 1, analyze false claims and search for similar patterns:

Dead script found: diagnose_track_selection.py
  → Search: all script references → Found 8 more dead scripts

Wrong interval: "every 10 seconds"
  → Search: "every \d+ (seconds?|minutes?)" → Found 3 more

Wrong service name: ai-radio-break-gen.service
  → Search: service/timer names → Found naming inconsistencies

Common patterns to always check:

  • Dead scripts: scripts/*.py references
  • Timer intervals: every \d+ (seconds?|minutes?)
  • Service names: ai-radio-*.service, *.timer
  • Config vars: RADIO_* environment variables
  • CLI flags: --flag patterns in bash blocks

Output Format

Generate docs/audits/AUDIT_REPORT_YYYY-MM-DD.md:

# Documentation Audit Report
Generated: YYYY-MM-DD | Commit: abc123

## Executive Summary
| Metric | Count |
|--------|-------|
| Documents scanned | 12 |
| Claims verified | ~180 |
| Verified TRUE | ~145 (81%) |
| **Verified FALSE** | **31 (17%)** |

## False Claims Requiring Fixes
### CONFIGURATION.md
| Line | Claim | Reality | Fix |
|------|-------|---------|-----|
| 135 | `claude-sonnet-4-5` | Actual: `claude-3-5-sonnet-latest` | Update |

## Pattern Summary
| Pattern | Count | Root Cause |
|---------|-------|------------|
| Dead scripts | 9 | Scripts deleted, docs not updated |

## Human Review Queue
- [ ] Line 436: behavior claim needs verification

Detailed References

For execution checklist and anti-patterns: checklist.md For claim extraction patterns: extraction-patterns.md