用 AI Agent 解决文档长期“掉队”的问题

在 Flashduty 工程实践中，发现文档长期“掉队”：功能已经上线、用户已经在用，但文档却没有同步更新。这种“文档漂移”不会立刻引发事故，却会不断消耗用户信任。尤其在引入 AI 客服之后，这个问题被进一步放大——文档质量，直接决定 AI 的回答质量。

问题的根因也很现实：没有专职写文档的人员，工程师既要做产品、又要开发，但没有人对“文档完整性”负责。写文档成本高、收益滞后，自然被排在低优先级。因此，依赖“大家自觉更新文档”是行不通的，我们必须用系统来解决。

为此，构建了一个 AI Agent（基于 Claude Code skill）。核心做法是通过一个 YAML 映射，把文档页面和对应源码关联起来，让系统知道“该去哪里找依据”，从而自动检测文档与代码之间的不一致。

详细参考：20 个 PR, 9000 行变更: 我们为什么不再手写文档

整个系统有两种模式：
Diff 模式：基于近期代码变更（git diff），识别新增功能、字段变化、规则调整等，再和现有文档比对，适合日常增量检测。
Audit 模式：从前端代码出发，全面盘点所有用户可见功能（页面、表单、开关等），逐一检查文档覆盖和准确性，适合做全量审计。

之所以选择从前端入手，是因为前端定义了用户真正能看到的产品边界，可以天然过滤掉后端的大量内部逻辑和噪音。

系统会输出结构化的“发现列表”，然后自动生成完整文档（中英双语），并提交 PR。工程师只需要做审核和润色。整个流程变成：AI 负责发现问题和写文档，人类负责把关质量。

实际跑下来，很快发现自己的文档远没有想象中完善：一次扫描就找出了数十个关键缺口，累计生成了 9000 多行内容。随后我们把这个能力产品化，变成定时任务，甚至接入 CI，在问题刚产生时就能被发现。

实践结论很简单：不要试图让工程师变得更“自觉”，而是用系统保证文档始终正确。