docs-guard

文档守护

你正在审查即将发布的生成或修改后的文档。完成第一轮文档编写后，请应用以下规则进行守护检查。核心原则：文档是一组关于代码库的声明，而每项声明都可以核查。你的工作就是核查这些声明。

这些规则之所以存在，是因为 AI Agent 根据 API「通常」的样子来写文档，而不是依据眼前的代码。已发表的研究表明，一半针对编程问题的 AI 回答包含错误信息，而模型对低频 API 生成正确调用的概率仅约三分之一——但无论正确与否，文字听起来都很权威。读者无法分辨经过验证的文档和幻觉文档。你可以，因为你有源代码。

如何使用此技能

守护检查模式（推荐）：生成或编辑文档或文档字符串后，根据源代码核验每项声明，并在交付前运行自检。

实时模式（明确指定）：用户在编写文档前调用此技能时，先核验再撰写——阅读实际实现，然后记录其实际行为。在交付前运行自检。

审查模式（用户要求你审查、审计或事实核查文档时）：根据 references/review-checklist.md 逐项检查目标文档，并提供附带文件名:行号证据的发现报告。除非用户要求，否则不要在审查模式下重写文档。

先适配项目

1. 阅读项目的 Agent 指引（CLAUDE.md、AGENTS.md）和任何文档风格指南。发生冲突时，以项目约定为准。
2. 找出必须同步更新的文档范围：README、参考文档、文档字符串、变更日志、示例、配置样例。一处更改通常也需要更新其他相关文档（规则 6）。
3. 了解文档中的版本策略：项目支持哪些版本，功能在哪些地方标注了版本。

规则

准确性——必须修正

1. 每个引用的符号都必须存在。 文档中提及的每个函数、方法、类、钩子、CLI 命令、标志、端点、配置键、环境变量和文件路径，都必须根据实际源代码、CLI 帮助输出、路由表或架构进行核验——要通过阅读核验，而不是凭记忆。核验流程见 references/verification.md。无法核验的引用不得发布。

2. 每段代码示例都必须可运行。 导入路径有效，API 存在且签名（名称、参数顺序、默认值、返回结构）与文档一致；示例在作者的机器之外也能运行——不能包含硬编码的本地路径、真实凭据或隐含的先前状态。示例规则见 references/code-samples.md。

3. 记录代码的实际行为，而非预期行为。 描述行为前先阅读实现。如果代码与注释或规范不一致，以代码为准——并向用户指出这一不一致，不要默默地选择一方。

4. 不得包含无法核验的声明。 性能数据、兼容性矩阵、规模限制以及「可用于生产」之类的断言，必须有仓库内的依据（基准测试脚本、CI 矩阵、变更日志条目），否则就删去。「快速」是营销说法；「O(n log n)，在 bench/sort.md 中经过基准测试」才是文档。

版本管理与偏差

5. 明确标注版本。 如果项目追踪版本，功能、标志和行为应注明其引入版本。前置条件必须指定固定版本或版本范围，不能写「最新」。已弃用的项目应注明弃用状态及替代项。

6. 代码更改需要同步更新文档。 编辑文档中有说明的代码行为时——例如重命名、更改签名、新默认值、移除标志——要在同一次更改中更新所有提及该行为的文档。完成前，使用 grep 搜索文档中的旧符号。

内容——应当修正

7. 不要凑字数，不要灌水。 删除以下内容：复述函数签名的文档字符串（例如，在 get_user_by_id 上方写“根据 ID 获取用户”）、重复标题内容的章节、技术文案中的营销形容词（“强大”“无缝”“极快”），以及冗长的引言（“在本节中，我们将探讨……”）。文档字符串只有在补充签名无法表达的约定时才有价值：单位、范围、错误条件、副作用、线程或顺序保证。

8. 不要转述上游文档。 应链接到外部文档，而不是复述其内容——上游一旦变更，转述的文档就会过时。只记录你的项目与外部内容之间的关系（使用了哪些子集、配置有哪些不同）。

9. 示例也要涵盖失败路径。 只展示成功路径的教程，只记录了一半 API。展示错误是什么样的，以及调用方应如何处理——使用代码实际抛出的错误类型（根据规则 1 核实）。

结构——值得注意

10. 导航内容必须准确。 标题应能概括对应章节，目录应与实际标题一致，内部链接和锚点应可正常跳转，已发布的文档中不应包含 TODO 占位内容或“即将推出”章节——未撰写的章节应直接删除，而不是承诺之后补上。

交付前自检

1. 列出文档中提到的每个符号、标志、端点、配置键和路径。是否在本次工作中逐一对照源码核实，而不是凭记忆判断？
2. 每段代码示例都能在干净的机器上运行吗？是否检查了每个导入项和签名？
3. 是否有任何数字、兼容性声明或最高级形容词找不到可在仓库中核实的来源？
4. 如果此次更改涉及代码，是否已搜索所有文档位置，检查旧名称是否仍然存在？
5. 是否有只复述签名的文档字符串？是否有重复标题内容的章节？
6. 所有内部链接和锚点都能正常跳转吗？

如果任何一项的答案是否定的，请先修正，再展示给用户。

报告格式（审查模式）

**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>

先列出规则 1–4 中的问题（错误声明），再列出内容偏差，最后列出内容方面的问题。如果文档没有问题，请用一行说明——准确性也值得肯定。

严重性指南

• 必须修正： 规则 1–4——错误文档比没有文档更糟，因为读者会据此采取行动
• 应当修正： 规则 5–9——内容偏差会累积成债务，噪音也会掩盖重点
• 值得注意： 规则 10——导航和润色

参考资料

• references/verification.md——机械核查流程：提取声明、核实符号、签名、CLI 标志、端点、配置键和链接
• references/code-samples.md——如何编写可交付的示例：可运行性、真实数据、密钥安全和错误处理路径
• references/docstrings.md——文档字符串、PHPDoc 和 JSDoc 专属规则：何时需要、必须包含什么、如何检测转述
• references/review-checklist.md——审查模式的结构化检查流程
• references/sources.md——研究资料和风格指南 URL；仅在引用资料时阅读

此技能不负责的内容

• 审查代码本身——这是 clean-code-guard 的职责。此技能审查文档对代码的描述。
• 从零制定文档策略或信息架构——此技能负责把关准确性和内容质量，不负责决定范围。
• 强制执行行文风格指南——语气由项目决定；真实性由此技能把关。