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
Runbook 与契约验证	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。

默认原则

• 在判断文档缺失之前，先发现各个组件。
• 根据风险和运维影响排列优先级，而不是根据文档数量。
• 对关键外部契约和 Runbook 设置阻断门禁；其余内容纳入待办。
• 将 AI 生成的文档视为草稿，直到链接、命令和声明均经过检查。
• 对于面向 Agent 的文档，检查相关站点路径下维护中的 llms.txt 是否有助于 Agent 找到规范页面；格式也允许使用路径范围文件，例如 /docs/llms.txt。
• 测试 Runbook 必须声明规范的起始、定向运行、清理/重置和部署门禁命令。
• 每个主题保留一份规范文档，每个关键领域指定一位负责人。

工作流

1. 发现服务、契约、Runbook、指令文件和关键工作流。
2. 将现有文档映射到审查模型，识别实际缺口、重复内容和过时部分；从清单中排除归档内容。
3. 按严重程度和修复顺序排列缺口。
4. 使用脚本或 CI 工具验证链接、Runbook、契约和时效性信号。将证据标记为 inventory、static、executed 或 operator-validated；Markdown、链接和命令语法并不能证明 Runbook 能达到其声明的最终状态。
5. 对已执行的 Runbook，记录前置条件、环境、确切命令、观察到的输出、清理结果，以及有意不测试的任何破坏性操作或特权步骤。
6. 生成覆盖度映射、Runbook 验证报告或 AI 文档清理报告，并注明负责人、状态和后续门禁。

核心决策

审计模型

使用三个优先级：

• P1：外部契约和故障行为
• P2：内部集成和运维文档
• P3：开发者参考文档和便捷文档

默认策略 — 这是此技能采用的规范性新鲜度阈值；freshness-tracking.md、scripts/docs_freshness_report.py 和 CI 示例中的阈值都与之保持一致：

• P1：30 天，阻塞。运行 docs_freshness_report.py --fail-on P1（脚本的默认设置），使 CI 仅在 P1 文档过时时失败。
• P2：60 天，警告。
• P3：90 天，警告。
• 将非阻塞欠账记入待办列表，而不是让每次变更都失败。

覆盖率与实用性

覆盖率百分比是一项筛查指标，而非结论 — 有关抽查方法以及 AI 生成测试覆盖率中同样存在的陷阱，请参阅 api-docs-validation.md。

如何确定文档编写优先级

组件类型（P1/P2/P3）设定的是底线，而不是完整的排序依据。在同一优先级内，应根据实际使用信号安排工作顺序：某个主题的支持工单或 Slack 问题频率，可能比组件类型更重要（每周收到两张工单的 P3 配置选项，优先级高于无人询问、缺少文档的 P2 服务）；即使尚无工单，入门流程中的阻碍也是领先指标；如果事件复盘报告指出“文档不清晰”，无论原先属于哪个级别，都应将该文档重新定为 P1；没有信号不代表优先级低 — 应对照路线图核查，因为这可能意味着还没人发现自己需要该组件。

何时不应编写文档

文档需要维护成本；不要不加判断地建议编写文档。对于仅凭名称、类型签名和上下文就能清楚理解的代码，跳过内联文档（标记为“无需文档”，而非缺口）。对于只有一个内部调用方且没有独立故障模式的组件，不要单独为其编写页面。与其绕着令人困惑的接口编写说明，不如优先修复接口。不要建议为已弃用或即将移除的组件编写文档；应改为建议移除组件或明确标注弃用。

新鲜度与所有权

关键文档应包含足够的元数据，以便重新核验：所有者、上次核验日期、审核周期、相关代码路径或系统。对于多仓库枢纽，新鲜度应根据仓库同步事件来更新，而不应只依赖日历计划。

除文档年限外的文档腐化信号

即使 last_verified 时间较近，文档仍可能有误 — 有关腐化信号（标识符消失、代码悄然变更、示例与实际情况矛盾、工单内容冲突）及其为何应优先于新鲜度标记，请参阅 freshness-tracking.md。

有助于维持文档的所有权模式

在 frontmatter 中列出所有者是必要条件，但并非充分条件。应判断所有权模式能否形成反馈闭环：作者持有直到交接（作者转组后便会失效）、文档值班轮换（可应对人员更替）、由 CODEOWNERS 强制执行（在提交时发现偏差）、纳入团队章程（最能经受人员更替）。仅指定姓名、没有任何强制机制的所有权模式最弱 — 应将其标记为缺口，而不能只勾选“已指定所有者”。

运行手册和 AI 指令

只有新成员能够照着执行并明确知道何时完成的运行手册才合格。

测试运行手册（过时则为 P1）必须声明：规范的开发服务器或环境引导命令、规范的定向测试或批量测试命令、规范的清理或重置命令、规范的部署门禁重放命令，以及跟踪记录、日志或故障上下文的存放位置。如果过时的“先运行整个测试套件”指引会实质性地浪费时间、导致环境冲突，或绕过预期的部署门禁流程，则应将其视为 P1。

指令文件审查应核实：当前启用的 Agent/运行时文件确实与所用工具相符（Claude Code 和 Codex 的具体信息请参阅 ai-instruction-coverage.md）；重复的指令层是有意设置的；外部声明均有来源和核验日期；AI 生成的编辑内容仍符合当前代码和工作流的实际情况。

反模式

• 不按影响程度排序，一次性记录所有内容。
• 未执行文档或检查链接，就合并 AI 生成的文档。
• 保留无人负责、从未重新核验的文档。
• 认为文档文件夹越大就越完善。
• 未抽查样例内容，就报告文档字符串或端点覆盖率。
• 为一眼就能看懂的代码撰写文档，或用文档代替修复令人困惑的接口。
• 运行器拓扑发生变化后，规范运行手册中仍保留过时的测试命令或批次名称。
• 将某一种工具的指令文件模式视为通用模式。
• 仅按组件类型给问题排序，即使支持工单数量、入职摩擦或事故复盘已经表明哪个问题实际影响最大。

经验循环

如果先前的决策或陷阱与当前任务相关，且 learnings.consolidated.md 存在，请先查阅；仅在需要历史记录或该文件不可用时，才使用 learnings.md。否则，两者都跳过。

应用经验后，如果遇到了值得记住的模式、值得防止的错误，或令人意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 在 learnings.md 中追加一条带日期的项目符号。不要修改 SKILL.md 本身。