产品一直在变，文档很容易慢半拍。

靠人记住每次改动，再去几份材料里逐页找位置，漏掉一处就会留下旧说法。让 AI 重写全文也不够：它不知道哪些行为真的变了，哪些只是代码结构变了；如果旧文档本身就错了，重写还可能把错话说得更顺。

我在维护产品知识时，把更新拆成了三段：先按明确范围读代码变更，把其中隐含的产品行为写成带证据的业务规则；再拿核实过的规则更新内部产品知识；需要对外说明时，再从审阅过的材料中筛选和改写。这三段首尾相接，但不是一个命令自动跑完。中间每一步都需要检查上一环节的结论。

先框定这次要看的代码范围

“把整个代码库的业务逻辑都提取出来”听起来省事，实际很难证明有没有漏。代码库可能有多个产品线和分支，提交里还混着发布、依赖更新、重构和测试。范围不先定，最后既说不清结论从哪来，也说不清哪些内容没看。

先画清这轮检查的边界，再开始读代码差异。

开始前先写下四件事：这次看哪些代码库和分支、从哪个基线看到哪个终点、哪些提交类型先排除、最终要回答什么产品问题。然后按这个口径比较真实差异。提交标题只能当线索，不能代替 diff；标题写着“优化”的改动可能改变用户行为，标题写着“修复”的改动也可能只是内部整理。

初筛后，把候选变更分成“确认涉及产品行为”“看起来有关、需要读代码”“纯工程变动”几类。逐项检查后再归并到产品主题，并留下覆盖范围和排除理由。这样，报告说的是“这段范围内核过的变化”，不会把“这轮没看到”扩大成“产品从来没有”。

从代码差异里写出业务规则

代码讲的是程序怎么走，产品文档要讲用户会遇到什么。中间得翻译一次。只写“增加了校验”仍是实现摘要；读者真正要知道的是：谁在什么条件下会遇到它，系统接着做什么，结果有什么变化。

业务规则要能从用户结果一路追回实现证据。

我会把一条候选规则拆成几个问题：触发条件是什么、系统执行了什么判断或动作、用户能看到什么结果、失败或边界情况下又会怎样。再把每一项逐一对回变更代码。可以用一个固定句式整理：“当【条件】成立时，系统会【行为】，因此用户可以／不能【结果】；遇到【边界情况】时会【例外】。”方括号是写作提示，不能留在最终结论里。

证据也要分层。代码直接写明、调用链能完整支持的，标为已核实；需要结合多个模块才能推出的，标为推断；缺少关键调用方或运行条件的，留作待确认。提交标题、注释和模型的解释都能提供线索，却不能单独证明产品规则。最后形成的不是一段“这次改了什么”的摘要，而是可回到代码复核、也能拿去对照产品说明的行为描述。

把规则写回内部产品知识

业务变化报告适合回答“这一轮改了什么”，但它是按时间组织的。长期维护还需要把稳定事实写回按产品概念组织的知识页，让后来查资料的人能找到规则，而不必从几轮变更报告里拼起来。

把经过核实的变化放回长期知识，而不是只留在本轮报告里。

写回前先找现有页面，不要看到新改动就新建一页。把新规则和旧说法逐条比：如果一致，补上代码来源和核验范围；如果有差异，回到实现查清是旧文档过时、规则只适用于特定条件，还是代码本身还有未确认的路径。修订时保留“原来怎么写、为什么改、依据是什么”，再更新目录或交叉链接，避免正文已变、检索入口仍指向旧内容。

变更报告和产品知识承担不同职责：前者保留时间线和本轮覆盖范围，后者沉淀目前可以复用的规则。把两者链接起来，既能追问“这条规则怎么来的”，也能知道“它现在应该去哪一页找”。代码说明的是当前实现，不自动证明所有运行环境都已升级；部署状态需要另外核实。

对外文档要再过一道筛选

内部资料解决的是“团队要知道什么”，外部文档解决的是“读者需要知道什么”。两者不能直接复制。内部页面可能记录证据位置、版本差异和仍待核实的推断；外部读者通常只需要适用条件、正确用法和可预期结果。

对外版本要经过受众筛选和人工复核。

因此，对外整理要从已经核实的内部材料出发，先明确读者和使用场景，再决定保留哪些规则、删去哪些内部背景。每条面向外部的说明都要能回到已审阅的来源；如果内部结论还标着“推断”或“待确认”，不能在公开稿里悄悄改成确定语气。涉及版本范围或部署条件的内容，也要明确它描述的是哪一层状态。

生成器可以负责重复的格式转换和内容筛选，但规则是否适合公开、措辞是否会让读者误解，仍需人工复核。复核时至少从头走一遍：内容是否都能追到内部依据、读者是否能据此正确行动、是否混入未确认说法或不必要的内部信息。文件生成成功，只说明转换完成，不代表它已经通过审阅或发布。

扫描有范围，自动化也有成本

定期扫一个明确的变更区间，比声称一次提取完所有业务逻辑更可信。每轮结束时留下基线、覆盖范围、已核实的规则、推断和待确认项；下一轮从上次的终点接着查，并回看尚未闭环的问题。这样既能渐进补齐，也不会把有限扫描包装成“全量提取”。

留下尚未确认的边界，才能避免把有限扫描说成全量结论。

自动化可以从重复、边界清楚的动作开始：整理候选变更、生成证据清单、检查链接和格式。判断一段实现是否改变产品语义、多个文档应该如何协调、什么内容可以公开，仍需要人把关。代码变更密集、同一规则被多处复用时，记录这些关系更划算；变化少、只有一份短文档时，定点核对可能更轻。

这套方法的目标不是把流程做得越长越好，而是让每次更新都说得清三件事：我检查了什么，结论依据在哪里，哪些边界还没确认。新行为因此能进到正确的知识位置，旧说法有机会被发现和修正，对外版本也有明确的审核依据。

下一篇接着聊另一个问题：多个 Agent 同时改同一份资料，怎么避免彼此覆盖，又怎么把两边的有效改动合回来，关注一下能及时获取更新通知。