qa-docs-coverage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

QA Docs Coverage (Jan 2026) - Discovery, Freshness, and Runbook Quality

QA文档覆盖率（2026年1月）- 发现、时效性与运行手册质量

Modern Best Practices (January 2026)

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

Docs as QA: Treat docs as production artifacts with owners, review cadence, and CI quality gates (links/style/contracts/freshness)
Contract-first: Validate OpenAPI/AsyncAPI/JSON Schema in CI; use coverage tools (Swagger Coverage / OpenAPI Coverage) to detect gaps
Runbook testability: Every runbook must be executable in staging; validate with synthetic tests and incident exercises
Automation + observability: Track coverage %, freshness, and drift via CI dashboards; prevent regressions via PR checklists

This skill provides operational workflows for auditing existing codebases, identifying documentation gaps, and systematically generating missing documentation. It complements docs-codebase by providing the discovery and analysis layer.

Key Principle: Templates exist in docs-codebase. This skill tells you what to document and how to find undocumented components.

Core references: Diataxis (doc structure), OpenAPI (REST), AsyncAPI (events).

文档即QA：将文档视为生产级制品，配备负责人、审核周期以及CI质量关卡（链接/格式/契约/时效性）
契约优先：在CI中验证OpenAPI/AsyncAPI/JSON Schema；使用覆盖率工具（Swagger Coverage / OpenAPI Coverage）检测缺口
运行手册可测试性：每个运行手册必须能在预发布环境执行；通过合成测试和故障演练验证
自动化+可观测性：通过CI仪表盘追踪覆盖率百分比、时效性和偏差；通过PR检查清单防止退化

本技能提供审计现有代码库、识别文档缺口、系统性生成缺失文档的运维工作流。它通过提供发现与分析层，与docs-codebase形成互补。

核心原则：模板存于docs-codebase中。本技能告诉你需要记录什么以及如何找到未记录的组件。

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

When to use

适用场景

Auditing an existing repo for missing/outdated documentation
Adding documentation quality gates (lint/link checks/contracts/freshness) to CI/CD
Validating runbooks for incident readiness (MTTR reduction)

审计现有仓库中缺失/过时的文档
为CI/CD添加文档质量关卡（语法检查/链接检查/契约/时效性）
验证运行手册的故障就绪性（缩短平均修复时间MTTR）

When to avoid

不适用场景

Writing new documentation from scratch without a component inventory (use discovery first)
Publishing AI-generated docs without human review and command/link verification

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

Quick start

快速开始

Use progressive disclosure: load only the reference file you need.

Discover components: references/discovery-patterns.md
Measure coverage + gaps: references/audit-workflows.md (Phase 1-2) and assets/coverage-report-template.md
Prioritize work: references/priority-framework.md
Create an actionable backlog: assets/documentation-backlog-template.md and templates in docs-codebase
Prevent regression: references/cicd-integration.md and references/freshness-tracking.md

Optional (recommended scripts; run from the repo being audited):

Local link check:

python3 frameworks/shared-skills/skills/qa-docs-coverage/scripts/check_local_links.py docs/

Freshness report:

python3 frameworks/shared-skills/skills/qa-docs-coverage/scripts/docs_freshness_report.py --docs-root docs/

采用渐进式披露：仅加载你需要的参考文件。

发现组件：references/discovery-patterns.md
测量覆盖率与缺口：references/audit-workflows.md（第1-2阶段）和assets/coverage-report-template.md
工作优先级排序：references/priority-framework.md
创建可执行的待办事项：assets/documentation-backlog-template.md以及docs-codebase中的模板
防止退化：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/

Large Codebase Audit (100K-1M LOC)

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

For large codebases, the key principle is: LLMs don't need the entire codebase - they need the right context for the current task.

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

Phase 0: Context Extraction

第0阶段：上下文提取

Before starting an audit, extract codebase context using tools:

Tool	Command/URL	Use Case
gitingest	Replace "github.com" with "gitingest.com"	Quick full-repo dump
repo2txt	https://github.com/kirill-markin/repo2txt	Selective file extraction
tree	`tree -L 3 --dirsfirst -I 'node_modules	.git

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

工具	命令/URL	使用场景
gitingest	将"github.com"替换为"gitingest.com"	快速全仓库导出
repo2txt	https://github.com/kirill-markin/repo2txt	选择性文件提取
tree	`tree -L 3 --dirsfirst -I 'node_modules	.git

Hierarchical Audit Strategy

分层审计策略

For monorepos and large projects, audit hierarchically:

text

1. Root Level (Week 1)
   ├── AGENTS.md / CLAUDE.md exists?
   ├── README.md quality
   ├── ARCHITECTURE.md exists?
   └── docs/ directory structure

2. Module Level (Week 2-3)
   ├── Each major directory has AGENTS.md?
   ├── API documentation complete?
   └── Service boundaries documented?

3. Component Level (Week 4+)
   ├── Individual component READMEs
   ├── Code comments quality
   └── Test documentation

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

text

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

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

3. 组件层级（第4周及以后）
   ├── 单个组件的README
   ├── 代码注释质量
   └── 测试文档

Cross-Platform Documentation Audit

跨平台文档审计

Check for multi-tool compatibility:

text

[ ] AGENTS.md exists (cross-platform standard)
[ ] CLAUDE.md exists or symlinked to AGENTS.md
[ ] GEMINI.md symlinked (if using Gemini)
[ ] File size under 300 lines (use @references for depth)
[ ] Subdirectory docs for each major module

检查多工具兼容性：

text

[ ] 存在AGENTS.md（跨平台标准）
[ ] 存在CLAUDE.md或已链接到AGENTS.md
[ ] 已链接GEMINI.md（如果使用Gemini）
[ ] 文件行数少于300行（使用@references获取详细内容）
[ ] 每个主要模块都有子目录文档

Large Codebase Coverage Checklist

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

text

LARGE CODEBASE AUDIT CHECKLIST

Context Extraction:
[ ] Generated codebase dump (gitingest/repo2txt)
[ ] Created directory structure overview
[ ] Identified major modules/services

Root Documentation:
[ ] AGENTS.md / CLAUDE.md present and <300 lines
[ ] README.md with quick start
[ ] ARCHITECTURE.md with system overview
[ ] Symlinks configured for cross-platform

Module Documentation:
[ ] Each major directory has AGENTS.md
[ ] API endpoints documented
[ ] Database schemas documented
[ ] Event/message contracts documented

Maintenance:
[ ] Documentation ownership assigned
[ ] Freshness tracking enabled
[ ] CI/CD checks configured

Sources: Anthropic Claude Code Best Practices, OpenAI AGENTS.md Guide

text

大型代码库审计检查清单

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

根目录文档：
[ ] 存在AGENTS.md / CLAUDE.md且行数<300
[ ] README.md包含快速开始指南
[ ] ARCHITECTURE.md包含系统概览
[ ] 已配置跨平台链接

模块文档：
[ ] 每个主要目录都有AGENTS.md
[ ] API端点已记录
[ ] 数据库 schema已记录
[ ] 事件/消息契约已记录

维护：
[ ] 已分配文档负责人
[ ] 已启用时效性追踪
[ ] 已配置CI/CD检查

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

Core QA (Default)

核心QA（默认）

What "Docs as QA" Means

“文档即QA”的含义

Treat docs as production quality artifacts: they reduce MTTR, enable safe changes, and define expected behavior.
REQUIRED doc types for reliability and debugging ergonomics:
- "How to run locally/CI" and "how to test"
- Operational runbooks (alerts, common failures, rollback)
- Service contracts (OpenAPI/AsyncAPI) and schema examples
- Known issues and limitations (with workarounds)

将文档视为生产质量制品：它们能缩短MTTR、支持安全变更并定义预期行为。
为了可靠性和调试便利性，必须具备的文档类型：
- “本地/CI运行方式”和“测试方式”
- 运维运行手册（告警、常见故障、回滚）
- 服务契约（OpenAPI/AsyncAPI）和schema示例
- 已知问题与限制（含解决方法）

Coverage Model (Risk-Based)

覆盖率模型（基于风险）

Prioritize docs by impact:
- P1: externally consumed contracts and failure behavior (OpenAPI/AsyncAPI, auth, error codes, SLOs).
- P2: internal integration and operational workflows (events, jobs, DB schema, runbooks).
- P3: developer reference (configs, utilities).

按影响优先级排序文档：
- P1：外部消费契约和故障行为（OpenAPI/AsyncAPI、认证、错误码、服务水平目标SLO）。
- P2：内部集成和运维工作流（事件、任务、数据库schema、运行手册）。
- P3：开发者参考（配置、工具）。

Freshness Checks (Prevent Stale Docs)

时效性检查（防止文档过时）

Define owners, review cadence, and a "last verified" field for critical docs.
CI economics:
- Block PRs only for missing/invalid P1 docs.
- Warn for P2/P3 gaps; track via backlog.
Run link checks and linting as fast pre-merge steps.

为关键文档定义负责人、审核周期和“最后验证”字段。
CI策略：
- 仅针对缺失/无效的P1文档阻止PR。
- 对P2/P3缺口发出警告；通过待办事项追踪。
将链接检查和语法检查作为快速预合并步骤。

Runbook Testability

运行手册可测试性

A runbook is "testable" if a new engineer can follow it and reach a measurable end state.
Include: prerequisites, exact commands, expected outputs, rollback criteria, and escalation paths.

如果新工程师能按照运行手册操作并达到可衡量的最终状态，那么该运行手册就是“可测试的”。
包含：前置条件、精确命令、预期输出、回滚标准和升级路径。

Do / Avoid

应做/不应做

Do:

Keep docs close to code (same repo) and version them with changes.
Use contracts and examples as the source of truth for integrations.

Avoid:

Large "doc-only" projects with no owners and no CI gates.
Writing runbooks that cannot be executed in a sandbox/staging environment.

应做：

将文档放在代码附近（同一仓库），并随变更版本化。
将契约和示例作为集成的事实来源。

不应做：

没有负责人和CI关卡的大型“纯文档”项目。
编写无法在沙箱/预发布环境执行的运行手册。

Quick Reference

快速参考

Audit Task	Tool/Pattern	Output	Reference
Discover APIs	`*/Controller.cs` , `/routes//*.ts`	Component inventory	discovery-patterns.md
Calculate Coverage	Swagger Coverage, manual diff	Coverage report	coverage-report-template.md
Prioritize Gaps	External → P1, Internal → P2, Config → P3	Documentation backlog	priority-framework.md
Generate Docs	AI-assisted + docs-codebase templates	Documentation files	audit-workflows.md Phase 3
Validate Contracts	Spectral, AsyncAPI CLI, OpenAPI diff	Lint report	cicd-integration.md
Track Freshness	Git blame, last-modified metadata	Staleness report	freshness-tracking.md
Automate Checks	GitHub Actions, GitLab CI, PR templates	Continuous coverage	cicd-integration.md

审计任务	工具/模式	输出	参考
发现API	`*/Controller.cs` , `/routes//*.ts`	组件清单	discovery-patterns.md
计算覆盖率	Swagger Coverage、手动对比	覆盖率报告	coverage-report-template.md
缺口优先级排序	外部→P1，内部→P2，配置→P3	文档待办事项	priority-framework.md
生成文档	AI辅助 + docs-codebase模板	文档文件	audit-workflows.md 第3阶段
验证契约	Spectral、AsyncAPI CLI、OpenAPI diff	语法检查报告	cicd-integration.md
追踪时效性	Git blame、最后修改元数据	过时报告	freshness-tracking.md
自动化检查	GitHub Actions、GitLab CI、PR模板	持续覆盖率	cicd-integration.md

Decision Tree: Documentation Audit Workflow

决策树：文档审计工作流

text

User needs: [Audit Type]
    ├─ Starting fresh audit?
    │   ├─ Public-facing APIs? → Priority 1: External-Facing (OpenAPI, webhooks, error codes)
    │   ├─ Internal services/events? → Priority 2: Internal Integration (endpoints, schemas, jobs)
    │   └─ Configuration/utilities? → Priority 3: Developer Reference (options, helpers, constants)
    │
    ├─ Found undocumented component?
    │   ├─ API/Controller? → Scan endpoints → Use api-docs-template → Priority 1
    │   ├─ Service/Handler? → List responsibilities → Document contracts → Priority 2
    │   ├─ Database/Entity? → Generate ER diagram → Document entities → Priority 2
    │   ├─ Event/Message? → Map producer/consumer → Schema + examples → Priority 2
    │   └─ Config/Utility? → Extract options → Defaults + descriptions → Priority 3
    │
    ├─ Large codebase with many gaps?
    │   └─ Use phase-based approach:
    │       1. Discovery Scan → Coverage Analysis
    │       2. Prioritize by impact (P1 → P2 → P3)
    │       3. Generate docs incrementally (critical first)
    │       4. Set up maintenance (PR templates, quarterly audits)
    │
    └─ Maintaining existing docs?
        └─ Check for:
            ├─ Outdated docs (code changed, docs didn't) → Update or archive
            ├─ Orphaned docs (references non-existent code) → Remove
            └─ Missing coverage → Add to backlog → Prioritize

text

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

Navigation: Discovery & Analysis

导航：发现与分析

Component Discovery

组件发现

Resource: references/discovery-patterns.md

Language-specific patterns for discovering documentable components:

.NET/C# codebase (Controllers, Services, DbContexts, Kafka handlers)
Node.js/TypeScript codebase (Routes, Services, Models, Middleware)
Python codebase (Views, Models, Tasks, Config)
Go, Java/Spring, React/Frontend patterns
Discovery commands (ripgrep, grep, find)
Cross-reference discovery (Kafka topics, external APIs, webhooks)

资源：references/discovery-patterns.md

用于发现可文档化组件的语言特定模式：

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

Priority Framework

优先级框架

Resource: references/priority-framework.md

Framework for prioritizing documentation efforts:

Priority 1: External-Facing (public APIs, webhooks, auth) - Must document
Priority 2: Internal Integration (services, events, database) - Should document
Priority 3: Developer Reference (config, utilities) - Nice to have
Prioritization decision tree
Documentation debt scoring (formula + interpretation)
Compliance considerations (ISO 27001, GDPR, HIPAA)

资源：references/priority-framework.md

用于优先级排序文档工作的框架：

优先级1：外部面向（公共API、webhook、认证）- 必须记录
优先级2：内部集成（服务、事件、数据库）- 应该记录
优先级3：开发者参考（配置、工具）- 可选记录
优先级决策树
文档债务评分（公式+解释）
合规考虑（ISO 27001、GDPR、HIPAA）

Audit Workflows

审计工作流

Resource: references/audit-workflows.md

Systematic workflows for conducting audits:

Phase 1: Discovery Scan (identify all components)
Phase 2: Coverage Analysis (compare against existing docs)
Phase 3: Generate Documentation (use templates)
Phase 4: Maintain Coverage (PR templates, CI/CD checks)
Audit types (full, incremental, targeted)
Audit checklist (pre-audit, during, post-audit)
Tools and automation

资源：references/audit-workflows.md

用于执行审计的系统化工作流：

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

CI/CD Integration

CI/CD集成

Resource: references/cicd-integration.md

Automated documentation checks and enforcement:

PR template documentation checklists
CI/CD coverage gates (GitHub Actions, GitLab CI, Jenkins)
Pre-commit hooks (Git, Husky)
Documentation linters (markdownlint, Vale, link checkers)
API contract validation (Spectral, AsyncAPI CLI)
Coverage tools (Swagger Coverage, OpenAPI Coverage)
Automated coverage reports
Best practices and anti-patterns

资源：references/cicd-integration.md

自动化文档检查与强制执行：

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

Freshness Tracking

时效性追踪

Resource: references/freshness-tracking.md

Track documentation staleness and drift from code:

Freshness metadata standards (last_verified, owner, review_cadence)
Git-based freshness analysis scripts
Staleness thresholds by priority (P1: 30 days, P2: 60 days, P3: 90 days)
CI/CD freshness gates (GitHub Actions, GitLab CI)
Observability dashboards and metrics
Automated doc reminder bots

资源：references/freshness-tracking.md

追踪文档过时情况与代码偏差：

时效性元数据标准（last_verified、负责人、审核周期）
基于Git的时效性分析脚本
按优先级划分的过时阈值（P1：30天，P2：60天，P3：90天）
CI/CD时效性关卡（GitHub Actions、GitLab CI）
可观测性仪表盘与指标
自动化文档提醒机器人

Navigation: Templates

导航：模板

Coverage Report Template

覆盖率报告模板

Template: assets/coverage-report-template.md

Structured coverage report with:

Executive summary (coverage %, key findings, recommendations)
Coverage by category (API, Service, Data, Events, Infrastructure)
Gap analysis (P1, P2, P3 with impact/effort)
Outdated documentation tracking
Documentation debt score
Action plan (sprints + ongoing)

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

结构化覆盖率报告包含：

执行摘要（覆盖率百分比、关键发现、建议）
按类别划分的覆盖率（API、服务、数据、事件、基础设施）
缺口分析（P1、P2、P3含影响/工作量）
过时文档追踪
文档债务评分
行动计划（迭代+持续）

Documentation Backlog Template

文档待办事项模板

Template: assets/documentation-backlog-template.md

Backlog tracking with:

Status summary (In Progress, To Do P1/P2/P3, Blocked, Completed)
Task organization by priority
Templates reference (quick links)
Effort estimates (Low < 2h, Medium 2-8h, High > 8h)
Review cadence (weekly, bi-weekly, monthly, quarterly)

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

待办事项追踪包含：

状态摘要（进行中、待办P1/P2/P3、阻塞、已完成）
按优先级组织的任务
模板参考（快速链接）
工作量估算（低<2小时，中2-8小时，高>8小时）
审核周期（每周、每两周、每月、每季度）

Output Artifacts

输出制品

After running an audit, produce these artifacts:

Coverage Report -
```
.codex/docs/audit/coverage-report.md
```
- Overall coverage percentage
- Detailed findings by category
- Gap analysis with priorities
- Recommendations and next audit date
Documentation Backlog -
```
.codex/docs/audit/documentation-backlog.md
```
- In Progress items with owners
- To Do items by priority (P1, P2, P3)
- Blocked items with resolution path
- Completed items with dates
Generated Documentation -
```
.codex/docs/
```
(organized by category)
- API reference (public/private)
- Event catalog (Kafka/messaging)
- Database schema (ER diagrams)
- Background jobs (runbooks)

审计完成后，生成以下制品：

覆盖率报告 -
```
.codex/docs/audit/coverage-report.md
```
- 整体覆盖率百分比
- 按类别划分的详细发现
- 含优先级的缺口分析
- 建议与下次审计日期
文档待办事项 -
```
.codex/docs/audit/documentation-backlog.md
```
- 已分配负责人的进行中项
- 按优先级划分的待办项（P1、P2、P3）
- 含解决路径的阻塞项
- 带日期的已完成项
生成的文档 -
```
.codex/docs/
```
（按类别组织）
- API参考（公共/私有）
- 事件目录（Kafka/消息）
- 数据库schema（ER图）
- 后台任务（运行手册）

Integration with Foundation Skills

与基础技能的集成

This skill works closely with:

docs-codebase - Provides templates for:

api-docs-template.md - REST API documentation
adr-template.md - Architecture decisions
readme-template.md - Project overviews
changelog-template.md - Release history

Workflow:

Use qa-docs-coverage to discover gaps
Use docs-codebase templates to fill gaps
Use qa-docs-coverage CI/CD integration to maintain coverage

本技能与以下技能紧密配合：

docs-codebase - 提供文档编写模板：

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

工作流：

使用qa-docs-coverage发现缺口
使用docs-codebase模板填补缺口
使用qa-docs-coverage的CI/CD集成维护覆盖率

Anti-Patterns to Avoid

应避免的反模式

Documenting everything at once - Prioritize by impact, document incrementally
Merging doc drafts without review - Drafts must be validated by owners and runnable in practice
Ignoring outdated docs - Outdated docs are worse than no docs
Documentation without ownership - Assign owners for each doc area
Skipping the audit - Don't assume you know what's documented
Blocking all PRs - Only block for P1 gaps, warn for P2/P3

一次性记录所有内容 - 按影响优先级排序，增量记录
合并未经审核的文档草稿 - 草稿必须经负责人验证并可实际执行
忽略过时文档 - 过时文档比没有文档更糟
无负责人的文档 - 为每个文档区域分配负责人
跳过审计 - 不要假设你知道已记录的内容
阻止所有PR - 仅针对P1缺口阻止PR，对P2/P3缺口发出警告

Optional: AI / Automation

可选：AI/自动化

Do:

Use AI to draft docs from code and tickets, then require human review and link/command verification.
Use AI to propose "freshness diffs" and missing doc sections; validate by running the runbook steps.

Avoid:

Publishing unverified drafts that include incorrect commands, unsafe advice, or hallucinated endpoints.

应做：

使用AI从代码和工单中生成文档草稿，然后要求人工审核和链接/命令验证。
使用AI提出“时效性差异”和缺失的文档章节；通过运行运行手册步骤进行验证。

不应做：

发布包含错误命令、不安全建议或虚构端点的未验证草稿。

Success Criteria

成功标准

Immediate (After Audit):

Coverage report clearly shows gaps with priorities
Documentation backlog is actionable and assigned
Critical gaps (P1) identified with owners

Short-term (1-2 Sprints):

All P1 gaps documented
Documentation coverage > 80% for external-facing components
Documentation backlog actively managed

Long-term (Ongoing):

Quarterly audits show improving coverage (upward trend)
PR documentation checklist compliance > 90%
"How do I" questions in Slack decrease
Onboarding time for new engineers decreases

即时（审计后）：

覆盖率报告清晰显示含优先级的缺口
文档待办事项可执行且已分配
已识别含负责人的关键缺口（P1）

短期（1-2个迭代）：

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

长期（持续）：

季度审计显示覆盖率持续提升（上升趋势）
PR文档检查清单合规率>90%
Slack中“如何操作”类问题减少
新工程师入职时间缩短

Related Skills

Usage Notes

使用说明

For Claude: When auditing a codebase:

Start with discovery - Use references/discovery-patterns.md to find components
Calculate coverage - Compare discovered components vs existing docs
Prioritize gaps - Use references/priority-framework.md to assign P1/P2/P3
Follow workflows - Use references/audit-workflows.md for systematic approach
Use templates - Reference docs-codebase for documentation structure
Set up automation - Use references/cicd-integration.md for ongoing maintenance

Remember: The goal is not 100% coverage, but useful coverage for the target audience. Document what developers, operators, and integrators actually need.

针对Claude：审计代码库时：

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

记住：目标不是100%覆盖率，而是针对目标受众的有用覆盖率。记录开发者、运维人员和集成人员实际需要的内容。

qa-docs-coverage

Original

Translation

QA Docs Coverage (Jan 2026) - Discovery, Freshness, and Runbook Quality

QA文档覆盖率（2026年1月）- 发现、时效性与运行手册质量

Modern Best Practices (January 2026)

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

When to use

适用场景

When to avoid

不适用场景

Quick start

快速开始

Large Codebase Audit (100K-1M LOC)

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

Phase 0: Context Extraction

第0阶段：上下文提取

Hierarchical Audit Strategy

分层审计策略

Cross-Platform Documentation Audit

跨平台文档审计

Large Codebase Coverage Checklist

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

Core QA (Default)

核心QA（默认）

What "Docs as QA" Means

“文档即QA”的含义

Coverage Model (Risk-Based)

覆盖率模型（基于风险）

Freshness Checks (Prevent Stale Docs)

时效性检查（防止文档过时）

Runbook Testability

运行手册可测试性

Do / Avoid

应做/不应做

Quick Reference

快速参考

Decision Tree: Documentation Audit Workflow

决策树：文档审计工作流

Navigation: Discovery & Analysis

导航：发现与分析

Component Discovery

组件发现

Priority Framework

优先级框架

Audit Workflows

审计工作流

CI/CD Integration

CI/CD集成

Freshness Tracking

时效性追踪

Navigation: Templates

导航：模板

Coverage Report Template

覆盖率报告模板

Documentation Backlog Template

文档待办事项模板

Output Artifacts

输出制品

Integration with Foundation Skills

与基础技能的集成

Anti-Patterns to Avoid

应避免的反模式

Optional: AI / Automation

可选：AI/自动化

Success Criteria

成功标准

Related Skills

相关技能

Usage Notes

使用说明