让 Codex 按代码事实同步产品文档

这项工作的产物包括一份变化与文档的对应表、一组范围克制的文档差异，以及完整的检查结果。验收时，每条新增说法都能指向公开代码、测试或已经发布的资料，每个改动页面也能说明为什么受影响。内部讨论、未发布路线和客户信息不会进入公开文本。

先确认什么已经变了

把目标分支、提交或变更文件交给 Codex，并提供现有文档目录、发布说明和相关公开资料。先让它只读代码与测试，列出用户能够观察到的变化。参数名称、默认值、错误行为、配置键、命令输出和兼容范围都值得核对。实现细节若不影响使用方式，可以留在代码注释或开发说明中。

随后为每项变化标记证据。代码显示实现已经存在，测试说明预期行为，公开发布说明确认可对外使用。来源不清就停。三者有冲突时先停止写作，记录冲突并请负责人判断。拉取请求描述和工单能解释背景，不能单独证明当前代码已经具备某项能力。

文档先别动。先做一份影响表，把变化、受影响读者、旧说法、建议新说法和证据并排放好。若同一变化只影响管理员，就不要顺手修改普通用户的快速开始。若一个新默认值会改变旧项目，则需要同时检查升级说明和回退方式。这张表会把写作范围压到有证据的地方。

先查读者。搜索功能名、配置键、命令、旧术语和相关示例，再沿着交叉链接检查入口页、教程、参考页与迁移说明。可见结果是一份候选页面清单，每项注明需要更新、需要复核或保持不动。这样能发现旧示例，也能阻止一次局部变化演变成整套文档重写。

阅读每个候选页面的 frontmatter、标题层级、术语和相邻链接。让 Codex 保留现有信息架构，只修改用户完成任务所需的最小范围。新增参数时，除了参考表，还要检查快速开始和复制示例是否需要同步。错误行为改变时，应更新故障排查与预期输出。

仓库里的 AGENTS.md 可以保存长期规则，例如用户可见行为发生变化时检查哪些目录、公开文档允许引用什么、需要运行哪些命令。规则要写成团队能够持续执行的动作，避免塞入本次任务才成立的临时细节。

版本化文档还要先确定修改哪一份。当前版本、长期支持版本和即将发布版本可能保留不同语法。Codex 应从导航配置或生成脚本查清来源文件，再更新对应版本。直接复制同一段到所有版本，容易把新能力写进仍不支持它的旧页面。

改一页，查一圈。相邻入口、站内搜索和旧链接都可能把读者带到这项功能，局部修改完成后要从这些路径重新进入目标页。

先更新最接近代码事实的参考页，再处理教程和入口页。这样后续页面可以引用稳定定义。每写完一处，让 Codex 回查原证据，确认名称、大小写、默认行为和适用版本没有被润色走样。无法证明的营销式判断直接删除，待发布能力应明确保持未发布状态。

示例也会过期。示例代码要在仓库允许的环境中运行。复制命令、相对路径、导入方式和输出都需要检查。不能运行时，至少用类型检查、语法检查或现有测试验证，并在交付中说明缺少哪项环境。链接则检查目标存在、锚点有效、旧地址是否需要兼容。

最后查看整份文档差异。确认没有意外改动无关页面，没有泄露密钥、内部网址、客户名称与私有路线。可见结果是一份按页面归组的变更摘要，每条都带来源与验证方式。发布后从真实导航与站内搜索重新进入目标页，复查链接、示例和版本标签。

运行仓库已有的格式、链接、代码示例和站点构建检查，保存命令与结果。机器检查还不够。还要人工通读入口顺序和术语一致性。页面已经发布后，从真实导航进入一次，避免文件存在但读者找不到。

高频文档同步可以写成可复用 Skill 或受控自动任务，让 Codex 定期读取近期变更并准备草稿。自动化的输出仍应停在可审阅差异，公开发布范围、来源边界和最终合并由明确的仓库流程决定。

代码可能包含尚未启用的开关，测试也可能覆盖实验路径。只有仓库证据时，文档应描述能确认的行为，不替发布团队宣布可用范围。生成文档、版本化页面和多语言副本还可能有专门来源文件，直接改产物会在下次生成时丢失。