审查生成或变更的文档准确性：在 README/API…

在代理生成或修改文档后、代码变更影响文档后或发布文档前，用源码逐条核验文档中的符号、代码示例、版本、声明与结构，拦截文档与代码漂移和不可验证内容。

适用场景

解决思路

1. 把文档视为一组关于代码库的可检验主张，逐条核对每个主张。
2. Guard-pass 模式：在文档或 docstring 生成/编辑后，对照源码核验每个主张，并在交付前运行自检。
3. Live 模式：用户要求在写文档前调用本技能时，先读实际实现，再按实现写文档；交付前运行自检。
4. Review 模式：用户要求审查、审计或事实核查文档时，按 references/review-checklist.md 走查目标文档，产出带 file:line 证据的 findings report；除非被要求，否则不要重写文档。
5. 先读项目的 agent instructions（CLAUDE.md、AGENTS.md）和任何文档风格指南；冲突时项目约定优先。
6. 识别必须同步变动的文档面：README、reference docs、docstrings、changelog、examples、config samples；改动一个通常意味着要改其他相关文档（规则 6）。
7. 记录项目的版本政策：支持哪些版本，以及功能在哪里做版本标记。
8. 准确性问题（必须修）规则 1：文档提到的每个 function、method、class、hook、CLI command、flag、endpoint、config key、env var 和 file path 都必须存在；通过阅读实际源码、CLI help output、route table 或 schema 核验，不能凭记忆。
9. 按 references/verification.md 中的验证流程执行引用核验；无法验证的引用不得发布。
10. 规则 2：每个代码示例都必须能运行；核验 imports 可解析、API 存在且签名与文档一致（names、argument order、defaults、return shape），示例能在作者机器之外运行。
11. 代码示例不得包含硬编码本地路径、真实凭据或隐式的先前状态；示例规则见 references/code-samples.md。
12. 规则 3：描述前先读实现，记录代码的实际行为，而不是 intended behavior。
13. 当代码与注释/规格不一致时，以代码为事实，并向用户标记该不一致，不要静默选边。
14. 规则 4：不得有不可验证声明；性能数字、兼容性矩阵、规模限制和“production-ready”断言必须能由仓库内来源支持（benchmark script、CI matrix、changelog entry），否则删除。
15. 将“Fast”这类营销词改为有依据的文档，例如“O(n log n), benchmarked in bench/sort.md”。
16. 版本与漂移规则 5：当项目跟踪版本时，功能、flag 和行为要说明引入版本。
17. 前置条件要固定版本或范围，绝不要写“latest”。
18. 已弃用项要标明弃用，并给出替代项。
19. 规则 6：当编辑行为已被文档化的代码（重命名、签名变更、新默认值、移除 flag）时，在同一次变更中更新所有提及它的文档面。
20. 完成前 grep 文档中的旧 symbol。
21. 实质内容规则 7：删除填充和 slop：只复述签名的 docstring（如 get_user_by_id 上方的“Gets the user by ID”）、复述标题的章节、技术 prose 中的营销形容词（“powerful”、“seamless”、“blazingly fast”）以及开头填充（“In this section, we will explore…”）。
22. docstring 应通过补充签名无法表达的契约来证明其存在：units、ranges、error conditions、side effects、threading/ordering guarantees。
23. 规则 8：不要转述上游文档；改为链接到外部文档，因为转述的上游文档会在上游变化时漂移。
24. 只记录项目与外部事物的关系（使用哪个子集、有什么不同配置）。
25. 规则 9：示例也要覆盖失败路径；只展示 happy path 的教程只记录了一半 API。
26. 展示错误长什么样以及调用方应如何处理，并使用代码实际抛出的错误类型（按规则 1 核验）。
27. 结构规则 10：导航要说真话；标题要描述其章节，目录要匹配实际标题，内部链接和 anchors 要能解析。
28. 已发布文档中不得有 TODO stubs 或“coming soon”章节；未写的章节要删除，不要承诺。
29. 交付前自检 1：列出文档提到的每个 symbol、flag、endpoint、config key 和 path；确认每个都在本次会话中对照源码核验过，而不是凭记忆。
30. 自检 2：确认每个代码示例都能在干净机器上运行，并检查每个 import 和签名。
31. 自检 3：检查是否有任何数字、兼容性声明或最高级表述没有仓库可验证来源。
32. 自检 4：如果本次变更触及代码，grep 所有文档面中的旧名称。
33. 自检 5：检查是否有 docstring 只复述签名，或章节只复述标题。
34. 自检 6：检查所有内部链接和 anchors 是否解析。
35. 如果任一自检答案不对，先修复再展示给用户。
36. Review 模式报告格式：使用 **Rule N violation** in `docs/path.md:<line or section>` 格式，并列出 Claim、Reality（带 file:line）、Fix。
37. 报告时先列规则 1–4 的发现（错误声明），再列漂移，再列实质问题；如果文档干净，用一句话说明。
38. 按严重性分级：规则 1–4 为 Must fix（错误文档比没有文档更糟，读者会据此行动）；规则 5–9 为 Should fix（漂移债务和噪声会埋没信号）；规则 10 为 Worth noting（导航和打磨）。
39. 需要时查阅 references/verification.md（提取主张、验证 symbols、signatures、CLI flags、endpoints、config keys、links 的机械流程）、references/code-samples.md（可发布示例：可运行性、真实数据、secrets hygiene、错误路径）、references/docstrings.md（docstring/PHPDoc/JSDoc 规则）、references/review-checklist.md（review 模式结构化走查）、references/sources.md（研究与风格指南 URL；仅在引用来源时读）。
40. 不要审查代码本身；本技能只审查文档对代码的声明（代码审查归 clean-code-guard）。
41. 不要从零生成文档策略或信息架构；本技能只守护准确性和实质，不做范围决策。
42. 不要强制 prose 风格指南；语气属于项目，真相属于本技能。

适用边界 · 注意事项

• 不用于生产代码审查；应使用 clean-code-guard。
• 不用于测试审查；应使用 test-guard。
• 不用于营销文案、博客文章、非技术写作的散文风格编辑、文档站点主题美化，也不用于从零生成文档策略或信息架构（本技能只守护准确性与实质，不审查代码本身或决定范围）。