docs-guard

Docs Guard

你正在文档交付前对其进行审查（包括新生成的或修改过的文档）。在完成首轮文档撰写后，请将以下规则作为“把关审查”（Guard Pass）来执行。核心原则：文档本质上是针对代码库提出的一系列断言，而每一个断言都是可验证的。 你的工作就是去逐一验证它们。

之所以需要这些规则，是因为 AI Agent 在写文档时，往往是凭记忆调取 API“通常”长什么样，而不是根据眼前的实际代码来写。已发表的科研数据表明：AI 回答编程问题时，有一半都包含错误信息；而对于低频 API，模型生成正确调用的概率甚至不足三分之一——但无论对错，它输出的语气听起来都极其权威。读者根本无法区分哪些是经过验证的文档，哪些是 AI 幻觉生成的文档。但你可以，因为你拥有源码。

如何使用此 Skill

把关模式（Guard-pass mode）（推荐）：在生成或编辑完文档/docstring 后，在交付前对照源码核对每一处断言，并完成自我检查。

实时模式（Live mode）（显式）：当用户在写文档前显式调用此 Skill 时，先验证再撰写——读取实际的代码实现，然后据实记录其行为。交付前同样运行自我检查。

审查模式（Review mode）（用户明确要求你审查、审计或核查文档时）：对照目标文档梳理 references/review-checklist.md，并生成带有 文件:行号 依据的发现报告。除非用户明确要求，否则在审查模式下不要直接改写文档。

优先适配项目规范

1. 先读取项目的 Agent 指令（CLAUDE.md、AGENTS.md）以及项目自带的文档风格指南。如有冲突，以项目本身的约定为准。
2. 识别必须协同变更的文档联动面：README、参考文档、docstring、变更日志、示例代码、配置样例。修改其中一处，通常意味着其他相关地方也需要跟着改（参见规则 6）。
3. 注意文档中声明的版本策略：项目支持哪些版本？功能特性在何处标注了版本标签？

审查规则

准确性 — 必须修复

1. 引用的每一个符号都必须真实存在。 文档中提及的每一个函数、方法、类、Hook、CLI 命令、参数 Flag、Endpoint、配置 Key、环境变量和文件路径，都必须对照实际源码、CLI help 输出、路由表或 Schema 进行核对——要通过“读取”去查，而不是靠“记忆”去想。机械核对流程参见 references/verification.md。无法验证的引用一律不得交付。

2. 每一个代码示例都必须能够运行。 Import 必须能正确解析，API 必须存在且签名（名称、参数顺序、默认值、返回结构）与文档描述完全一致，代码示例必须能在作者机器之外的环境中独立运行——不得包含硬编码的本地路径、真实的敏感凭据（Secrets），或隐式的预置状态。示例规范参见 references/code-samples.md。

3. 记录代码的实际行为，而非预期行为。 在描述代码逻辑前，先去读代码的具体实现。当代码逻辑与注释/规范不一致时，以代码为准——并将此不一致反馈给用户，而不是私自替用户做决定。

4. 拒绝无法验证的夸大断言。 性能数据、兼容性矩阵、规模极限以及“生产环境就绪（production-ready）”等断言，必须在代码库中有明确的来源依据（基准测试脚本、CI 矩阵、changelog 记录），否则一律删除。“速度极快”是营销套话；“O(n log n)，基准测试见 bench/sort.md”才是合格的技术文档。

版本控制与漂移

5. 版本信息必须明确。 在追踪版本的项目中，新增的功能、Flag 及行为变动必须标明引入该特性的具体版本。依赖前置条件必须锁定版本或标注版本区间，严禁使用“latest”。弃用（Deprecated）项必须明确说明，并提供替代方案。

6. 代码一改，文档必改。 当修改了已被文档记载的代码行为时（重命名、修改函数签名、新增默认值、删除参数 Flag），必须在同一次提交中同步更新所有提及该符号的文档面。在结束工作前，记得对所有文档执行 Grep 搜索，确保旧符号已被清掉。

内容干货 — 应当修复

7. 拒绝水文与无意义废话。 必须删掉：简单转述签名的 docstring（例如在 get_user_by_id 上方写“根据 ID 获取用户”）、单纯重复标题内容的章节、技术文案中的营销形容词（如“功能强大”、“无缝衔接”、“极致飞快”），以及开篇的客套垫话（如“在本章中，我们将深入探讨……”）。一个 docstring 只有补充了函数签名无法表达的契约约束才有价值：如单位、取值范围、异常条件、副作用、线程/执行顺序保证等。

8. 不要转述上游文档。 遇到上游组件，直接附上外部文档链接，不要复述其内容——上游一旦更新，你转述的内容就会立刻过时漂移。只记录你的项目与该外部组件的关系（使用了哪个子集、进行了哪些自定义配置）。

9. 代码示例也要覆盖失败路径。 只展示 Happy Path（成功路径）的教程只相当于写了一半的文档。必须展示报错时的样子以及调用方该如何处理——并且要使用代码中实际抛出的异常类型（按规则 1 进行核对）。

结构规范 — 值得关注

10. 导航结构必须保真。 标题必须准确概括该章节内容，目录（TOC）必须与实际标题保持一致，内部链接与 Anchor 锚点必须能正常跳转。已发布的文档中绝对不能出现 TODO 占位符或“即将推出（coming soon）”等挂空挡的章节——未写完的章节直接删掉，不要开空头支票。

交付前自查清单

1. 罗列出文档中提到的所有符号、Flag、Endpoint、配置 Key 和路径。你是否在本次会话中对照源码逐一核对过了（而不是靠记忆）？
2. 每一个代码示例是否都能在一台全新的干净机器上跑通？你核对过每一个 Import 和函数签名了吗？
3. 是否存在任何没有代码库来源可查的数据、兼容性断言或极品形容词？
4. 如果本次变更改动了代码：你是否在所有文档中 Grep 搜索了旧名称？
5. 是否存在仅仅重复函数签名的 docstring？是否存在仅仅重复标题内容的章节？
6. 所有的内部链接和 Anchor 锚点都能正常跳转吗？

如果上述任何一项自查没通过，请在呈现给用户之前先将其修复。

报告格式（审查模式）

**违反 Rule N** 见 `docs/path.md:<行号或章节>`
- 文档断言：<文档中是怎么说的>
- 实际情况：<代码/CLI/Schema 中实际是什么，带 文件:行号 依据>
- 修复建议：<一句话修复方案>

优先输出 Rule 1–4 的发现（虚假断言/错误信息），其次是文档漂移问题，最后是干货度问题。如果文档很干净无误，用一句话明确说明即可——准确无误值得肯定。

严重程度指南

• 必须修复： Rules 1–4 — 错误的文档比没有文档危害更大，读者会信以为真并据此操作
• 应当修复： Rules 5–9 — 漂移债务与掩盖有效信息的噪点废话
• 值得关注： Rule 10 — 导航跳转与细节润色

参考资料

• references/verification.md — 机械核对流程：提取断言、验证符号、函数签名、CLI 参数 Flag、Endpoint、配置 Key、链接
• references/code-samples.md — 合格示例的可交付标准：可运行性、真实数据、敏感信息卫生、错误处理路径
• references/docstrings.md — 针对 docstring/PHPDoc/JSDoc 的专项规则：何时有必要写、必须包含什么、同义反复检测
• references/review-checklist.md — 审查模式下的结构化逐项检查清单
• references/sources.md — 论文研究及风格指南 URL 链接；仅在引用来源时查阅

本 Skill 不涉及的范围

• 不审查代码本身 — 这是 clean-code-guard 的职责。本 Skill 只审查文档对代码所作出的断言。
• 不从零生成文档战略或信息架构 — 本 Skill 守卫的是准确性与干货度，而非文档范围设定。
• 不强求特定的文风指南 — 语调由项目本身决定，而事实真伪由本 Skill 守卫。