名称: qa-docs-coverage 描述: “文档作为QA：审计文档覆盖率和新鲜度，验证运行手册，并为API、服务、事件和操作工作流维护文档质量门。包括AI辅助审计、可观察性模式和自动化覆盖跟踪。”

QA文档覆盖率（2026年1月） - 发现、新鲜度和运行手册质量

现代最佳实践（2026年1月）

文档作为QA：将文档视为生产工件，具有所有者、审查节奏和CI质量门（链接/样式/合同/新鲜度）
合同优先：在CI中验证OpenAPI/AsyncAPI/JSON模式；使用覆盖工具（Swagger Coverage / OpenAPI Coverage）检测缺口
运行手册可测试性：每个运行手册必须在预发布环境中可执行；通过合成测试和事件演练进行验证
自动化 + 可观察性：通过CI仪表板跟踪覆盖率百分比、新鲜度和漂移；通过PR清单防止回归

此技能提供操作工作流，用于审计现有代码库、识别文档缺口，并系统生成缺失文档。它通过提供发现和分析层来补充文档代码库。

核心原则：模板存在于文档代码库中。此技能告诉您要记录什么以及如何找到未记录组件。

核心参考：Diataxis（文档结构）、OpenAPI（REST）、AsyncAPI（事件）。

何时使用

审计现有仓库以查找缺失/过时的文档
向CI/CD添加文档质量门（lint/链接检查/合同/新鲜度）
验证运行手册以准备事件（减少MTTR）

何时避免

在没有组件清单的情况下从头编写新文档（先使用发现）
发布未经人工审查和命令/链接验证的AI生成文档

快速开始

使用渐进式披露：仅加载所需的参考文件。

发现组件：references/discovery-patterns.md
衡量覆盖率 + 缺口：references/audit-workflows.md（阶段1-2）和assets/coverage-report-template.md
优先处理工作：references/priority-framework.md
创建可操作的待办事项：assets/documentation-backlog-template.md和文档代码库中的模板
防止回归：references/cicd-integration.md和references/freshness-tracking.md

可选（推荐脚本；从被审计仓库运行）：

本地链接检查：python3 frameworks/shared-skills/skills/qa-docs-coverage/scripts/check_local_links.py docs/
新鲜度报告：python3 frameworks/shared-skills/skills/qa-docs-coverage/scripts/docs_freshness_report.py --docs-root docs/

大型代码库审计（10万-100万行代码）

对于大型代码库，核心原则是：LLM不需要整个代码库 - 它们需要当前任务的正确上下文。

阶段0：上下文提取

在开始审计之前，使用工具提取代码库上下文：

工具	命令/URL	用例
gitingest	将“github.com”替换为“gitingest.com”	快速完整仓库转储
repo2txt	https://github.com/kirill-markin/repo2txt	选择性文件提取
tree	`tree -L 3 --dirsfirst -I 'node_modules	.git

分层审计策略

对于单体仓库和大型项目，分层审计：

1. 根级别（第1周）
   ├── AGENTS.md / CLAUDE.md 存在？
   ├── README.md 质量
   ├── ARCHITECTURE.md 存在？
   └── docs/ 目录结构

2. 模块级别（第2-3周）
   ├── 每个主要目录有 AGENTS.md？
   ├── API 文档完整？
   └── 服务边界记录？

3. 组件级别（第4周+）
   ├── 单个组件 READMEs
   ├── 代码注释质量
   └── 测试文档

跨平台文档审计

检查多工具兼容性：

[ ] AGENTS.md 存在（跨平台标准）
[ ] CLAUDE.md 存在或符号链接到 AGENTS.md
[ ] GEMINI.md 符号链接（如果使用 Gemini）
[ ] 文件大小小于 300 行（使用 @references 表示深度）
[ ] 每个主要模块的子目录文档

大型代码库覆盖率检查清单

大型代码库审计检查清单

上下文提取：
[ ] 生成代码库转储（gitingest/repo2txt）
[ ] 创建目录结构概述
[ ] 识别主要模块/服务

根文档：
[ ] AGENTS.md / CLAUDE.md 存在且 <300 行
[ ] README.md 包含快速开始
[ ] ARCHITECTURE.md 包含系统概述
[ ] 配置跨平台符号链接

模块文档：
[ ] 每个主要目录有 AGENTS.md
[ ] API 端点记录
[ ] 数据库模式记录
[ ] 事件/消息合同记录

维护：
[ ] 文档所有权分配
[ ] 新鲜度跟踪启用
[ ] CI/CD 检查配置

来源：Anthropic Claude 代码最佳实践、OpenAI AGENTS.md 指南

核心QA（默认）

“文档作为QA”的含义

将文档视为生产质量工件：它们减少MTTR、支持安全变更，并定义预期行为。
可靠性和调试人体工学所需文档类型：
- “如何在本地/CI运行”和“如何测试”
- 操作运行手册（警报、常见故障、回滚）
- 服务合同（OpenAPI/AsyncAPI）和模式示例
- 已知问题和限制（附带解决方法）

覆盖率模型（基于风险）

按影响优先级记录文档：
- P1：外部消费合同和故障行为（OpenAPI/AsyncAPI、身份验证、错误代码、SLOs）。
- P2：内部集成和操作工作流（事件、作业、数据库模式、运行手册）。
- P3：开发者参考（配置、实用程序）。

新鲜度检查（防止文档过时）

为关键文档定义所有者、审查节奏和“最后验证”字段。
CI经济性：
- 仅阻止PR缺少/无效的P1文档。
- 警告P2/P3缺口；通过待办事项跟踪。
运行链接检查和linting作为快速预合并步骤。

运行手册可测试性

如果新工程师可以遵循运行手册并达到可测量的最终状态，则“可测试”。
包括：先决条件、精确命令、预期输出、回滚标准、和升级路径。

要做 / 避免

要做：

保持文档接近代码（同一仓库）并与变更一起版本化。
使用合同和示例作为集成的真相来源。

避免：

大型“仅文档”项目没有所有者和CI门。
编写无法在沙盒/预发布环境中执行的运行手册。

快速参考

审计任务	工具/模式	输出	参考
发现APIs	`*/Controller.cs`, `/routes//*.ts`	组件清单	discovery-patterns.md
计算覆盖率	Swagger Coverage, 手动差异	覆盖率报告	coverage-report-template.md
优先处理缺口	外部 → P1, 内部 → P2, 配置 → P3	文档待办事项	priority-framework.md
生成文档	AI辅助 + 文档代码库模板	文档文件	audit-workflows.md 阶段3
验证合同	Spectral, AsyncAPI CLI, OpenAPI diff	Lint报告	cicd-integration.md
跟踪新鲜度	Git blame, 最后修改元数据	陈旧度报告	freshness-tracking.md
自动化检查	GitHub Actions, GitLab CI, PR模板	持续覆盖	cicd-integration.md

决策树：文档审计工作流

用户需求：[审计类型]
    ├─ 开始新审计？
    │   ├─ 公开APIs？ → 优先级1：外部面向（OpenAPI、webhooks、错误代码）
    │   ├─ 内部服务/事件？ → 优先级2：内部集成（端点、模式、作业）
    │   └─ 配置/实用程序？ → 优先级3：开发者参考（选项、助手、常量）
    │
    ├─ 找到未记录组件？
    │   ├─ API/控制器？ → 扫描端点 → 使用 api-docs-template → 优先级1
    │   ├─ 服务/处理程序？ → 列出职责 → 记录合同 → 优先级2
    │   ├─ 数据库/实体？ → 生成ER图 → 记录实体 → 优先级2
    │   ├─ 事件/消息？ → 映射生产者/消费者 → 模式 + 示例 → 优先级2
    │   └─ 配置/实用程序？ → 提取选项 → 默认值 + 描述 → 优先级3
    │
    ├─ 大型代码库有多个缺口？
    │   └─ 使用基于阶段的方法：
    │       1. 发现扫描 → 覆盖率分析
    │       2. 按影响优先级（P1 → P2 → P3）
    │       3. 增量生成文档（关键优先）
    │       4. 设置维护（PR模板、季度审计）
    │
    └─ 维护现有文档？
        └─ 检查：
            ├─ 过时文档（代码已变，文档未变） → 更新或归档
            ├─ 孤立文档（引用不存在代码） → 删除
            └─ 缺失覆盖率 → 添加到待办事项 → 优先处理

导航：发现与分析

组件发现

资源：references/discovery-patterns.md

语言特定模式，用于发现可记录组件：

.NET/C# 代码库（控制器、服务、DbContexts、Kafka 处理程序）
Node.js/TypeScript 代码库（路由、服务、模型、中间件）
Python 代码库（视图、模型、任务、配置）
Go、Java/Spring、React/前端模式
发现命令（ripgrep、grep、find）
交叉引用发现（Kafka主题、外部APIs、webhooks）

优先级框架

资源：references/priority-framework.md

优先处理文档工作的框架：

优先级1：外部面向（公开APIs、webhooks、身份验证） - 必须记录
优先级2：内部集成（服务、事件、数据库） - 应该记录
优先级3：开发者参考（配置、实用程序） - 好有
优先化决策树
文档债务评分（公式 + 解释）
合规考虑（ISO 27001、GDPR、HIPAA）

审计工作流

资源：references/audit-workflows.md

执行审计的系统工作流：

阶段1：发现扫描（识别所有组件）
阶段2：覆盖率分析（与现有文档比较）
阶段3：生成文档（使用模板）
阶段4：维护覆盖率（PR模板、CI/CD检查）
审计类型（完整、增量、目标）
审计检查清单（审计前、期间、后）
工具和自动化

CI/CD集成

资源：references/cicd-integration.md

自动化文档检查和执行：

PR模板文档检查清单
CI/CD覆盖率门（GitHub Actions、GitLab CI、Jenkins）
预提交钩子（Git、Husky）
文档linter（markdownlint、Vale、链接检查器）
API合同验证（Spectral、AsyncAPI CLI）
覆盖工具（Swagger Coverage、OpenAPI Coverage）
自动化覆盖率报告
最佳实践和反模式

新鲜度跟踪

资源：references/freshness-tracking.md

跟踪文档陈旧度和代码漂移：

新鲜度元数据标准（last_verified、所有者、review_cadence）
基于Git的新鲜度分析脚本
按优先级陈旧度阈值（P1: 30天、P2: 60天、P3: 90天）
CI/CD新鲜度门（GitHub Actions、GitLab CI）
可观察性仪表板和指标
自动化文档提醒机器人

导航：模板

覆盖率报告模板

模板：assets/coverage-report-template.md

结构化覆盖率报告包含：

执行摘要（覆盖率百分比、关键发现、建议）
按类别覆盖率（API、服务、数据、事件、基础设施）
缺口分析（P1、P2、P3带影响/努力）
过时文档跟踪
文档债务评分
行动计划（冲刺 + 持续）

文档待办事项模板

模板：assets/documentation-backlog-template.md

待办事项跟踪包含：

状态摘要（进行中、待办 P1/P2/P3、受阻、完成）
按优先级任务组织
模板参考（快速链接）
努力估计（低 < 2小时、中 2-8小时、高 > 8小时）
审查节奏（每周、双周、每月、季度）

输出工件

运行审计后，产生这些工件：

覆盖率报告 - .codex/docs/audit/coverage-report.md
- 整体覆盖率百分比
- 按类别详细发现
- 带优先级缺口分析
- 建议和下个审计日期
文档待办事项 - .codex/docs/audit/documentation-backlog.md
- 进行中项目带所有者
- 待办项目按优先级（P1、P2、P3）
- 受阻项目带解决路径
- 完成项目带日期
生成文档 - .codex/docs/（按类别组织）
- API参考（公开/私有）
- 事件目录（Kafka/消息传递）
- 数据库模式（ER图）
- 后台作业（运行手册）

与基础技能集成

此技能与以下技能紧密合作：

文档代码库 - 提供模板：

api-docs-template.md - REST API文档
adr-template.md - 架构决策
readme-template.md - 项目概述
changelog-template.md - 发布历史

工作流：

使用qa-docs-coverage发现缺口
使用文档代码库模板填充缺口
使用qa-docs-coverage CI/CD集成维护覆盖率

要避免的反模式

一次性记录所有内容 - 按影响优先级，增量记录
合并未经审查的文档草稿 - 草稿必须由所有者验证并在实践中可运行
忽略过时文档 - 过时文档比没有文档更糟
文档没有所有者 - 为每个文档区域分配所有者
跳过审计 - 不要假设您知道记录了什么
阻止所有PR - 仅阻止P1缺口，对P2/P3警告

可选：AI / 自动化

要做：

使用AI从代码和工单起草文档，然后需要人工审查和链接/命令验证。
使用AI建议“新鲜度差异”和缺失文档部分；通过运行运行手册步骤进行验证。

避免：

发布未验证的草稿，包括不正确命令、不安全建议或虚构端点。

成功标准

立即（审计后）：

覆盖率报告清晰显示带优先级的缺口
文档待办事项可操作且已分配
关键缺口（P1）已识别带所有者

短期（1-2个冲刺）：

所有P1缺口已记录
外部面向组件文档覆盖率 > 80%
文档待办事项积极管理

长期（持续）：

季度审计显示覆盖率改善（上升趋势）
PR文档检查清单合规性 > 90%
Slack中“如何做”问题减少
新工程师入职时间减少

使用说明

对于Claude：审计代码库时：

从发现开始 - 使用references/discovery-patterns.md找到组件
计算覆盖率 - 比较发现组件与现有文档
优先处理缺口 - 使用references/priority-framework.md分配P1/P2/P3
遵循工作流 - 使用references/audit-workflows.md进行系统方法
使用模板 - 参考文档代码库的文档结构
设置自动化 - 使用references/cicd-integration.md进行持续维护

记住：目标不是100%覆盖率，而是为目标受众提供有用覆盖率。记录开发者、操作员和集成商实际需要的内容。

文档质量审计覆盖技能 qa-docs-coverage