Back to Details

docs-guard

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Docs Guard

Docs Guard

You are reviewing generated or changed documentation before it ships. Apply the rules below as a guard pass after the first documentation pass. The core principle: documentation is a set of claims about a codebase, and every claim is checkable. Your job is to check them.
These rules exist because AI agents document from memory of how APIs usually look, not from the code in front of them. Published research: half of AI answers to programming questions contain incorrect information, and models produce valid invocations for infrequent APIs barely a third of the time — yet the prose sounds authoritative either way. Readers cannot tell verified docs from hallucinated docs. You can, because you have the source.
你需要在文档发布前审核生成或修改的文档。在首次文档编写完成后，按照以下规则进行审核校验。核心原则：文档是关于代码库的一系列声明，每一项声明都必须可验证。你的工作就是对这些声明进行验证。
制定这些规则的原因是，AI Agent是基于对API通常形式的记忆来编写文档，而非依据眼前的代码。已发表研究表明：AI对编程问题的回答中有一半包含错误信息，模型对不常用API生成有效调用的概率仅约三分之一——但无论结果如何，其表述听起来都很权威。读者无法区分经过验证的文档和虚构的文档，但你可以，因为你拥有源代码。

How to use this skill

如何使用该技能

Guard-pass mode (recommended): after documentation or docstrings have been generated or edited, verify every claim against the source and run the self-check before delivery.
Live mode (explicit): when the user invokes this skill before writing docs, verify before you write — read the actual implementation, then document what it does. Run the self-check before delivery.
Review mode (the user asks you to review, audit, or fact-check docs): walk references/review-checklist.md against the target docs and produce a findings report with file:line evidence. Do not rewrite in review mode unless asked.
校验模式（推荐）：在文档或docstrings生成或编辑完成后，对照源代码验证每一项声明，并在交付前进行自我检查。
实时模式（显式）：当用户在编写文档前调用该技能时，先验证再编写——阅读实际实现代码，然后根据其功能编写文档。交付前进行自我检查。
审核模式（用户要求审核、审计或核实文档）：对照references/review-checklist.md检查目标文档，并生成带有文件:行号证据的检查报告。除非被要求，否则审核模式下请勿重写文档。

Adapt to the project first

先适配项目

  1. Read the project's agent instructions (CLAUDE.md, AGENTS.md) and any docs style guide. Project conventions win on conflict.
  2. Identify the docs surfaces that must move together: README, reference docs, docstrings, changelog, examples, config samples. A change to one usually owes a change to others (Rule 8).
  3. Note the documented version policy: which versions does the project support, and where are features version-tagged?
  1. 阅读项目的Agent说明文档（CLAUDE.md、AGENTS.md）以及任何文档风格指南。若存在冲突，以项目约定为准。
  2. 确定必须同步更新的文档载体：README、参考文档、docstrings、变更日志、示例、配置样本。对其中一项的变更通常需要同步更新其他相关载体（规则8）。
  3. 记录项目的版本策略：项目支持哪些版本，功能在何处进行版本标记？

The Rules

规则

Accuracy — must fix

准确性——必须修正

  1. Every referenced symbol must exist. Every function, method, class, hook, CLI command, flag, endpoint, config key, env var, and file path mentioned in the docs gets verified against the actual source, CLI help output, route table, or schema — by reading it, not recalling it. The verification procedure is in references/verification.md. An unverifiable reference does not ship.
  2. Every code sample must work. Imports resolve, APIs exist with the documented signatures (names, argument order, defaults, return shape), and the sample runs outside the author's machine — no hardcoded local paths, no real credentials, no implicit prior state. Sample rules: references/code-samples.md.
  3. Document the code's actual behavior, not its intended behavior. Read the implementation before describing it. Where code and comments/specs disagree, the code is the truth — and flag the disagreement to the user instead of silently picking a side.
  4. No unverifiable claims. Performance numbers, compatibility matrices, scale limits, and "production-ready" assertions require a source in the repository (benchmark script, CI matrix, changelog entry) or they come out. "Fast" is marketing; "O(n log n), benchmarked in bench/sort.md" is documentation.
  1. 所有引用的符号必须存在。文档中提及的每一个函数、方法、类、Hook、CLI命令、标志、端点、配置键、环境变量和文件路径，都必须对照实际源代码、CLI帮助输出、路由表或模式进行验证——通过阅读代码验证，而非凭记忆。验证流程详见references/verification.md。无法验证的引用不得发布。
  2. 所有代码示例必须可运行。导入路径有效，API存在且与文档描述的签名（名称、参数顺序、默认值、返回结构）一致，示例可在作者机器之外的环境运行——不得包含硬编码的本地路径、真实凭证或隐式的前置状态。代码示例规则详见references/code-samples.md。
  3. 记录代码的实际行为，而非预期行为。在描述代码功能前先阅读实现代码。当代码与注释/规范不一致时，代码即为事实——需向用户标记这种不一致，而非擅自选择某一方。
  4. 不得包含无法验证的声明。性能数据、兼容性矩阵、规模限制和“生产就绪”等断言必须有代码库内的来源（基准测试脚本、CI矩阵、变更日志条目），否则需删除。“快速”属于营销话术；“时间复杂度O(n log n)，基准测试详见bench/sort.md”才是合格的文档内容。

Versioning and drift

版本控制与偏差

  1. Versions are explicit. Features, flags, and behaviors state the version that introduced them when the project tracks versions. Prerequisites are pinned or ranged, never "latest". Deprecated items say so, with the replacement.
  2. A code change owes a docs change. When editing code whose behavior is documented — rename, signature change, new default, removed flag — update every doc surface that mentions it in the same change. Grep the docs for the old symbol before finishing.
  1. 版本必须明确。当项目跟踪版本时，功能、标志和行为需注明引入它们的版本。依赖项需固定版本或指定版本范围，不得使用“latest”。已废弃的内容需明确标注，并说明替代方案。
  2. 代码变更需同步更新文档。当修改的代码行为已被文档描述时——重命名、签名变更、默认值修改、标志移除——需在同一变更中更新所有提及该内容的文档载体。完成前需在文档中搜索旧符号。

Substance — should fix

内容质量——应当修正

  1. No filler, no slop. Delete: docstrings that paraphrase the signature ("Gets the user by ID" above 
    get_user_by_id
    ), sections that restate their heading, marketing adjectives in technical prose ("powerful", "seamless", "blazingly fast"), and intro padding ("In this section, we will explore…"). A docstring earns its place by adding contracts the signature cannot express: units, ranges, error conditions, side effects, threading/ordering guarantees.
  2. Don't paraphrase upstream docs. Link to external documentation instead of restating it — paraphrased upstream docs drift the moment upstream changes. Document only your project's relationship to the external thing (which subset you use, what you configure differently).
  3. Examples cover the failure path too. A tutorial that only shows the happy path documents half the API. Show what the error looks like and what the caller should do — using the error types the code actually raises (verify per Rule 1).
  1. 无冗余内容。删除以下内容：重复签名信息的docstrings（如
    get_user_by_id
    上方的“通过ID获取用户”）、重复标题的章节、技术文档中的营销形容词（“强大的”“无缝的”“极快的”），以及介绍性冗余内容（“在本节中，我们将探讨……”）。docstrings的价值在于补充签名无法表达的约定：单位、范围、错误情况、副作用、线程/顺序保证。
  2. 不得转述上游文档。应链接到外部文档而非转述——转述的上游文档会在上游内容变更时出现偏差。仅需记录你的项目与外部内容的关联（使用的子集、配置差异）。
  3. 示例需覆盖异常路径。仅展示正常流程的教程只描述了API的一半功能。需展示错误的表现形式以及调用者应采取的措施——使用代码实际抛出的错误类型（需按照规则1验证）。

Structure — worth noting

结构——值得注意

  1. Navigation tells the truth. Headings describe their sections, the table of contents matches the actual headings, internal links and anchors resolve, and there are no TODO stubs or "coming soon" sections in published docs — unwritten sections are removed, not promised.
  1. 导航需准确。标题需描述对应章节内容，目录与实际标题一致，内部链接和锚点可正常跳转，已发布文档中不得包含TODO占位符或“即将推出”的章节——未编写的章节需删除，而非承诺。

Self-check before delivery

交付前自我检查

  1. List every symbol, flag, endpoint, config key, and path your docs mention. Did you verify each one against the source in this session — not from memory?
  2. Would every code sample run on a clean machine? Did you check each import and signature?
  3. Any number, compatibility claim, or superlative without a repo-verifiable source?
  4. If this change touched code: did you grep all docs surfaces for the old names?
  5. Any docstring that just restates the signature? Any section that restates its heading?
  6. Do all internal links and anchors resolve?
If any answer is wrong, fix it before showing the user.
  1. 列出文档中提及的所有符号、标志、端点、配置键和路径。你是否在本次会话中对照源代码验证了每一项——而非凭记忆？
  2. 所有代码示例是否可在干净的机器上运行？你是否检查了每一个导入和签名？
  3. 是否存在无代码库可验证来源的数字、兼容性声明或最高级表述？
  4. 若本次变更涉及代码：你是否在所有文档载体中搜索了旧名称？
  5. 是否存在仅重复签名信息的docstrings？是否存在重复标题的章节？
  6. 所有内部链接和锚点是否均可正常跳转？
若任何问题的答案是否定的，需在展示给用户前修正。

Reporting format (review mode)

审核模式报告格式

**Rule N violation** in `docs/path.md:<line or section>`
- Claim: <what the docs say>
- Reality: <what the code/CLI/schema actually has, with file:line>
- Fix: <one sentence>
Lead with Rule 1–4 findings (false claims), then drift, then substance. If a doc is clean, say so in one line — accuracy deserves credit.
**规则N违反** 位于 `docs/path.md:<行号或章节>`
- 声明：<文档中的内容>
- 实际情况：<代码/CLI/模式的实际内容，包含文件:行号>
- 修正方案：<一句话描述>
优先展示规则1-4的问题（错误声明），然后是偏差问题，最后是内容质量问题。若文档无问题，用一句话说明——准确性值得肯定。

Severity guide

严重程度指南

  • Must fix: Rules 1–4 — false documentation is worse than no documentation; readers act on it
  • Should fix: Rules 5–9 — drift debt and noise that buries the signal
  • Worth noting: Rule 10 — navigation and polish
  • 必须修正：规则1-4——错误的文档比没有文档更糟；读者会依据错误内容行事
  • 应当修正：规则5-9——偏差债务和冗余内容会掩盖有效信息
  • 值得注意：规则10——导航和完善性问题

References

参考资料

  • references/verification.md — the mechanical procedure: extracting claims, verifying symbols, signatures, CLI flags, endpoints, config keys, links
  • references/code-samples.md — what makes a sample shippable: runnability, realistic data, secrets hygiene, error paths
  • references/docstrings.md — docstring/PHPDoc/JSDoc-specific rules: when one is justified, what it must contain, paraphrase detection
  • references/review-checklist.md — structured walk-through for review mode
  • references/sources.md — research and style-guide URLs; read only when citing a source
  • references/verification.md —— 机械验证流程：提取声明、验证符号、签名、CLI标志、端点、配置键、链接
  • references/code-samples.md —— 可发布代码示例的标准：可运行性、真实数据、凭证安全、异常路径
  • references/docstrings.md —— docstring/PHPDoc/JSDoc专属规则：何时需要编写、必须包含的内容、重复表述检测
  • references/review-checklist.md —— 审核模式下的结构化检查清单
  • references/sources.md —— 研究资料和风格指南链接；仅在引用来源时阅读

What this skill does not do

该技能不负责的工作

  • Review the code itself — clean-code-guard's jurisdiction. This skill reviews what the docs claim about the code.
  • Generate documentation strategy or information architecture from scratch — it guards accuracy and substance, not scope decisions.
  • Enforce a prose style guide — tone belongs to the project; truth belongs to this skill.
  • 审核代码本身——这是clean-code-guard的职责范围。本技能仅审核文档对代码的声明是否准确。
  • 从零开始生成文档策略或信息架构——它仅负责保障准确性和内容质量，不涉及范围决策。
  • 强制执行文风指南——语气由项目决定；真实性由本技能保障。