用途:docs-guard 用于在生成或修改文档后、发布前做一次守卫式审核。其核心原则是:文档是对代码库的一组声明,而每条声明都可被核查。它针对 AI 常凭记忆而非眼前代码写文档的问题,帮助区分已核实与幻觉文档。
主要能力:规则覆盖准确性、版本与漂移、实质内容、结构四类。准确性要求每个被引用的符号、函数、类、钩子、CLI 命令、标志、端点、配置键、环境变量和文件路径都须对照实际源码、CLI 帮助、路由表或 schema 核实;代码示例必须能运行,导入可解析、签名一致;文档须描述代码实际行为而非预期行为;性能数字、兼容性矩阵、规模限制等不可核实的声明必须删除。版本规则要求明确标注引入版本、固定或限定前置条件、说明弃用项及替代方案;代码变更须同步更新所有提及该行为的文档面。实质规则反对空话、复述签名或标题、营销形容词,要求示例覆盖失败路径、不转述上游文档。结构规则要求标题与内容一致、目录与锚点可解析、无 TODO 占位。
使用方式:三种模式。守卫模式(推荐)在文档生成或编辑后核对每条声明并做自检;实时模式在写文档前先读实现再写;审核模式按 review-checklist.md 逐项检查并输出带 file:line 证据的发现报告,除非被要求否则不重写。使用前先读项目 agent 说明(CLAUDE.md、AGENTS.md)和文档风格指南,项目约定优先;识别须同步更新的文档面;注意版本策略。交付前自检符号、示例可运行性、无来源数字、旧名称 grep、冗余 docstring、链接锚点。审核报告按规则编号列出违规,先报规则 1–4 的虚假声明,再报漂移与噪音,最后结构。
适用场景:审核发布前的 README、API 参考、docstring、变更日志、教程与文档站点。限制:不审核代码本身(属 clean-code-guard);不从头生成文档策略或信息架构;不强制文风。参考资料包括 verification.md、code-samples.md、docstrings.md、review-checklist.md、sources.md。