AI 写了整套系统文档,为什么还是漏掉了关键业务?

遗留系统理解

AI 很快写出一套完整的老系统文档，却漏掉了夜间任务后的人工修正。我们从这次匿名化理解任务出发，说明红创如何用系统地图、真实业务旅程、验证问题和多源证据，把合理推断变成可以复核的系统知识。

场景来自红创参与的一次老系统理解任务，系统名称和业务数据已匿名化。

一个运行多年的系统准备增加接口，原始文档已经过期，主要开发人员也已离开。Agent 扫描代码后很快生成了模块说明、数据流和业务规则，内容完整得像一份正式设计文档。

现场人员核对时发现，它遗漏了一个夜间任务后的人工修正步骤。代码只记录系统动作，人工操作只存在于值班习惯中，两者共同决定第二天的数据结果。

01文档写得像真的，不代表理解是真的

AI 很擅长根据代码形成解释，但解释仍然可能是最合理的猜测。老系统的真实行为还分散在数据库、配置、日志、调度平台、操作界面和人员经验中。

我们的判断是：理解系统不是生成更多说明，而是让每个关键判断都能被证据验证。

最容易误判的地方，是解释在逻辑上完全说得通。代码里有修正字段，Agent 就可能推断系统自动修正；现实中也许是值班人员发现异常后手工改写。文字没有语病，业务含义却已经变了。

所以，我们会先问这份说明能够支持什么行动。如果团队看完仍然不知道某条记录为什么变化、异常时该如何恢复，文档再完整，也没有解决维护中最关键的问题。

02别急着解释，先把系统地图画出来

红创先让 Agent 建立系统地图，识别入口、模块、数据库、定时任务、外部接口和人工操作点。每个节点记录来源、负责人和未知问题。

地图完成后，再围绕一条真实业务旅程追踪状态变化。Agent 可以提出“这段逻辑可能用于月末补偿”，但在日志、历史数据或专家确认出现之前，它只能被标记为待验证假设。

工作台中的规则记录，应把推断和证据放在一起。例如，夜间任务后的人工修正，先记录代码入口与运行差异，再列出缺少的操作证据和待确认角色。任务不会因为生成了一段解释就自动结束。

地图也不需要一开始覆盖所有模块。先沿一条真实旅程找到入口、数据去向、失败处理和人工接手点，相关未知逐步收敛后，再扩展到周边业务。

03AI 是否读懂，用三个问题验证

第一，能否根据输入预测系统输出，而不是只复述代码。第二，能否解释一个历史异常为什么发生，以及系统如何恢复。第三，能否在不破坏既有行为的前提下，完成一项小修改并通过回归验证。

这三个问题把“理解”从文档质量变成可测试能力。只要预测、解释或修改失败，就说明上下文仍有缺口。

验证时，要先固定输入和预期，再让 Agent 解释。否则，模型看到现有结果后很容易给出自洽理由，却没有证明它能够提前判断系统行为。正常样例之外，还应加入团队确实遇到过的异常。

小修改也要在隔离环境进行。测试结果与解释不一致时，先检查理解缺了什么，不能为了让验证通过而悄悄修改预期。

04别让专家审全文，只让他确认关键假设

业务专家不需要逐页阅读 AI 生成的长文档。红创工作台会列出高风险、低置信度和相互冲突的判断，请专家集中确认。例如某字段是否允许人工覆盖，某任务失败后是否必须补跑。

确认结果会回写规则表、上下文包和测试用例，而不是只留在会议纪要中。

对于暂时无人能够确认的规则，我们不会让 Agent 自行补全答案，而是明确记录风险、影响范围和临时保护措施，让后续修改绕开尚未证实的关键区域。

对一个尚未确认的人工修正规则，可以把触发条件、可能影响的数据和待补证据列在同一张卡上。专家只需回答关键分歧，确认结果再进入回归样例。这样，业务确认不是一次口头背书，而是下一次修改可以检查的依据。

提问还需要避免暗示答案。与其问“这里是不是自动补偿”，不如请对方说明异常出现后实际做过哪些操作、在哪个系统完成、留下什么记录。开放地核对行为，更容易发现 AI 解释之外的事实。

确认人与规则维护人也要明确。一次访谈结束，不代表知识永久有效；操作习惯改变时，应有人负责把变化反馈到规则和测试中。

05重要规则，至少要有两类证据

我们把代码与数据、运行行为、专家判断组成证据三角。重要规则至少获得两类证据支持，并记录最后验证时间。系统发生变化时，可以定位哪些理解需要重新确认。

最终形成的不是一份静态说明书，而是一组与代码版本关联的系统知识。后续任务如果推翻某项判断，工作台会同步更新规则、测试和证据状态，避免新的维护人员继续使用过期结论。

两类证据也不意味着简单投票。两份文档可能来自同一份旧说明，不能算独立支持；代码与日志相互矛盾时，要继续寻找原因，而不是挑选看起来更可信的一份。

我们保留争议和未知，是为了让后续修改知道哪里需要谨慎。能说明哪些已经确认、哪些尚未证明，比宣称“系统已经全部读懂”更接近可靠的工程交付。

我们的落点：

AI 可以加快老系统发现，但不能把推断自动变成事实。红创用系统地图、真实业务旅程、三个验证问题和证据三角，让“读懂系统”成为可以检查、更新和复用的工程资产。