qa-docs-coverage

QA ドキュメントカバレッジ

ドキュメントを品質システムとして監査する際に、このスキルを使用してください。必要なドキュメントを洗い出し、現状のドキュメントを対応づけ、ギャップに優先順位を付け、重要なドキュメントが劣化しないようチェックを追加します。修正するドキュメントの執筆や再構成には、docs-codebase のほうが適しています。

クイックリファレンス

タスク	使用するもの
発見と監査の手順	references/discovery-patterns.md、references/audit-workflows.md
優先順位付けと指標	references/priority-framework.md、references/documentation-quality-metrics.md
AI 向け指示、llms.txt、新鮮さのチェック	references/ai-instruction-coverage.md、references/freshness-tracking.md
ランブックとコントラクトの検証	references/runbook-testing.md、references/api-docs-validation.md
CI/CD ゲート	references/cicd-integration.md
スクリプトとテンプレート	scripts/check_local_links.py、scripts/check_external_links.py、scripts/docs_freshness_report.py、assets/coverage-report-template.md、assets/documentation-backlog-template.md

ナビゲーション

• ドキュメント自体の執筆や再構成には、docs-codebase を使用してください。
• PRD、実装仕様、プロジェクトのメモリレイヤーには、docs-ai-prd を使用してください。
• ドキュメントを副次的な懸念事項とする、純粋なコードリスクのレビューには、software-code-review を使用してください。
• ミューテーションスコアのゲートを含むテストスイートの品質には、qa-testing-strategy を使用してください。

デフォルト

• ドキュメントの不足を判断する前に、コンポーネントを洗い出してください。
• ドキュメントの数ではなく、リスクと運用への影響に基づいて優先順位を付けてください。
• 重要な外部コントラクトとランブックはブロック対象とし、それ以外はバックログに入れてください。
• AI が生成したドキュメントは、リンク、コマンド、記載内容を確認するまではドラフトとして扱ってください。
• エージェント向けドキュメントでは、該当するサイトパスに維持管理された llms.txt があると、エージェントが正規ページを見つけやすくなるか確認してください。フォーマット では、/docs/llms.txt のようなパスを限定したファイルも使用できます。
• テストランブックには、正規の開始、対象を絞った実行、クリーンアップ／リセット、デプロイゲートの各コマンドを明記する必要があります。
• トピックごとに正規のドキュメントを1つ、重要な領域ごとにオーナーを1人にしてください。

ワークフロー

1. サービス、コントラクト、ランブック、指示ファイル、重要なワークフローを洗い出します。
2. 現在のドキュメントを監査モデルに対応づけ、実際のギャップ、重複、古くなった領域を特定します。アーカイブは一覧から除外してください。
3. ギャップの深刻度と修正順序に基づいて優先順位を付けます。
4. スクリプトや CI ツールで、リンク、ランブック、コントラクト、新鮮さを示すシグナルを検証します。証拠には inventory、static、executed、operator-validated のラベルを付けてください。Markdown、リンク、コマンド構文だけでは、ランブックが記載された最終状態に到達することの証明にはなりません。
5. 実行したランブックについて、前提条件、環境、正確なコマンド、観測された出力、クリーンアップ結果、および意図的にテスト対象外とした破壊的操作や特権操作を記録します。
6. オーナー、ステータス、次のゲートを含むカバレッジマップ、ランブック検証、または AI ドキュメントの整理レポートを作成します。

主要な判断

監査モデル

優先度は次の3段階です。

• P1：外部との契約および障害時の動作
• P2：内部統合および運用ドキュメント
• P3：開発者向けリファレンスおよび利便性に関するドキュメント

デフォルトポリシー — これはこのスキルにおける正式な鮮度しきい値のセットです。freshness-tracking.md、scripts/docs_freshness_report.py、および CI の例でも同じしきい値を使用しています。

• P1：30日、ブロッキング。docs_freshness_report.py --fail-on P1（スクリプトのデフォルト）を実行し、古くなった P1 ドキュメントがある場合にのみ CI が失敗するようにします。
• P2：60日、警告。
• P3：90日、警告。
• 変更のたびに失敗させるのではなく、ブロッキング対象外の負債はバックログで管理します。

網羅性と有用性

網羅率はスクリーニングの目安であり、最終判断ではありません。スポットチェックの方法と、AI が生成したテストの網羅率にも同じ落とし穴があることについては、api-docs-validation.mdを参照してください。

ドキュメント化の優先順位付け

コンポーネントの種類（P1/P2/P3）は優先順位の最低ラインであり、順位付けのすべてではありません。同じ段階内では、実際の利用状況が作業の順序を決めます。あるトピックに関するサポートチケットや Slack の質問の頻度は、コンポーネントの種類よりも優先される場合があります（週に2件のチケットがある P3 の設定オプションは、誰からも問い合わせがないドキュメント未整備の P2 サービスより優先されます）。チケットがまだなくても、オンボーディングの障壁は先行指標です。「ドキュメントが不明瞭」と記載されたインシデントの事後検証があれば、元の段階に関係なく、そのドキュメントを P1 に再設定します。また、兆候がないからといって優先度が低いとは限りません。コンポーネントの必要性にまだ誰も気づいていない可能性があるため、ロードマップと照合してください。

ドキュメント化しない場合

ドキュメントには保守コストがかかるため、反射的に推奨しないでください。名前、型シグネチャ、コンテキストから自明なコードにはインラインドキュメントを追加しません（不足ではなく「適切にドキュメント化されていない」と判断します）。内部の呼び出し元が1つだけで、独立した障害モードがないコンポーネントには、専用ページを作成しません。わかりにくいインターフェースをドキュメントで補うのではなく、インターフェース自体を改善してください。非推奨のコンポーネントや、まもなく削除されるコンポーネントのドキュメント化は推奨しません。代わりに、削除または明示的な非推奨通知を推奨してください。

鮮度とオーナーシップ

重要なドキュメントには、再検証に必要な十分なメタデータを含めます。オーナー、最終確認日、レビュー頻度、関連するコードパスやシステムなどです。複数のリポジトリをまたぐハブでは、鮮度の基準をカレンダー上のスケジュールだけでなく、リポジトリの同期イベントに合わせます。

経過期間以外のドキュメント劣化の兆候

last_verified が新しくても、ドキュメントの内容が誤っていることがあります。劣化の兆候（識別子の消失、気づかれにくいコードの乖離、矛盾する例、チケットとの不一致）と、劣化の兆候が新しいバッジより優先される理由については、freshness-tracking.mdを参照してください。

ドキュメントを維持するオーナーシップモデル

frontmatter にオーナーを記載することは必要ですが、それだけでは不十分です。オーナーシップモデルがフィードバックループを生み出すかどうかを判断してください。author-owns-until-handoff（執筆者がチームを異動すると機能しなくなります）、docs-on-call rotation（担当者が交代しても継続します）、CODEOWNERS-enforced（コミット時に乖離を検出します）、team-charter-embedded（担当者の交代後も最も継続しやすい）があります。強制する仕組みのない記名オーナーは最も弱いモデルです。オーナーがいることを確認するだけでなく、不備として指摘してください。

Runbook と AI 向け指示

Runbook は、新しい担当者が実行して明確な完了状態に到達できる場合にのみ適切です。

テスト用 Runbook（古くなっている場合は P1）には、正規の開発サーバーまたは環境のブートストラップコマンド、正規の対象を絞ったテストまたはバッチコマンド、正規のクリーンアップまたはリセットコマンド、正規のデプロイゲート再実行コマンド、トレース、ログ、失敗時の状況を記録した成果物の保存場所を明記する必要があります。「最初にテストスイート全体を実行する」という古い案内が、時間を大幅に浪費させたり、環境の衝突を引き起こしたり、本来のデプロイゲートの流れを迂回させたりする場合は、P1 として扱ってください。

指示ファイルの監査では、現在有効なエージェント／ランタイムのファイルが実際に使用中のツールと一致していること（Claude Code と Codex の詳細については ai-instruction-coverage.md を参照）、重複する指示レイヤーが意図的なものであること、外部の主張に出典と確認日が記載されていること、AI が生成した編集内容が現在のコードとワークフローの実態に即していることを確認します。

アンチパターン

• 影響度で優先順位を付けず、一度にすべてを文書化する。
• 実行やリンクのチェックをせずに、AI が生成したドキュメントをマージする。
• 担当者が決まっておらず、再確認されることのないドキュメントを放置する。
• ドキュメントフォルダーが大きいというだけで、健全だと思い込む。
• 実際の内容をサンプルで抜き取り確認せずに、docstring やエンドポイントのカバレッジ率を報告する。
• 一目瞭然のコードについてドキュメントを推奨したり、わかりにくいインターフェースの修正の代わりにドキュメントを推奨したりする。
• ランナーの構成が変わった後も、正規の Runbook に古いテストコマンドやバッチ名を残す。
• あるツールの指示ファイルのパターンを、すべてのツールに共通するものとして扱う。
• サポートチケットの件数、オンボーディング時の摩擦、インシデントの事後検証から、どのギャップが実際に問題を引き起こしているかがすでに明らかなのに、コンポーネントの種類だけでギャップの優先順位を付ける。

学びのループ

過去の判断や落とし穴が関係する場合は、learnings.consolidated.md があれば参照してください。learnings.md は、必要な履歴を確認する場合、または利用できる代替ファイルとしてのみ使用してください。それ以外の場合は、どちらも参照しないでください。

適用した後、覚えておく価値のあるパターン、再発を防ぐべきミス、または意外だった分野の事実に遭遇した場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って、日付入りの箇条書きを 1 つ learnings.md に追記してください。SKILL.md 自体は変更しないでください。