概览
使用 Codex 对比源代码变更、公开文档、发行说明和 PR 上下文，然后在发布前起草有针对性的文档更新并附上验证步骤。
适合场景
- 适用于需要跟踪频繁变化行为的开发者文档、README、运行手册、示例和迁移说明。
- 为技术产品维护文档的团队。
根据源代码变更更新文档
根据以下来源更新 [product/feature] 文档： - [this repo/source linked repo] 中已更改的源文件 - 提及新行为的现有文档页面 - 我在下方提供的任何相关 issue、PR、发行说明或公开参考资料 然后： - 识别哪些内容是面向用户的 - 只更新需要变更的文档 - 不要将未发布的路线图、私有客户细节和仅限内部的上下文写入公开文档 - 保留现有文档结构、术语和交叉链接 - 运行适合此次变更的文档检查 在最终定稿前，总结变更内容、你验证了什么，以及任何无法从可信来源证明的说法。 [在此处链接发行说明或其他参考资料]
简介
当文档与源代码变更同步更新，而不是几周后才补上时，最容易保持最新。Codex 可以检查变更过的代码、测试、发行说明、关联 issue 以及 pull request 上下文，然后起草与现有结构一致、范围清晰的文档更新。
将此工作流用于开发者文档、README 更新、变更日志草稿、迁移说明、运行手册，或任何其他需要跟踪频繁变化行为的内容。
使用方法
- 从你需要记录的变更开始。
分享分支、pull request、commit、issue 或文件。如果文档是公开的，请明确说明未发布的路线图、私有客户细节和仅限内部的上下文应保持排除在外。
- 让 Codex 梳理受影响的文档。
在起草前，让它在现有文档中搜索功能名称、配置键、命令、示例和相关术语。
- 更新最小但有用的文档范围。
Codex 应保留当前页面结构、术语、交叉链接和 frontmatter。当精确的说明、示例或章节更新已经足够时，它应避免大范围重写。
- 验证变更。
让 Codex 运行适合该仓库的格式化和文档检查，然后总结每一条面向用户的说法背后的证据。
提供给 Codex 的内容
| 来源 | 为什么有帮助 | | ------------------------------------ | ---------------------------------------------------------------------------- | | 变更的代码和测试 | 让 Codex 能分析实际行为，从而起草有针对性的文档更新。 | | 公开发行说明或产品文档 | 帮助 Codex 匹配公开术语、可用性和功能状态。 | | Pull request 或 issue 上下文 | 解释为什么会发生这项变更，以及哪些面向用户的行为最重要。 | | 本地文档检查 | 在文档发布前，为 Codex 提供明确的完成标准。 |
添加更多上下文（例如公开发行说明）可以让 Codex 避免包含私有上下文或尚未公开的更新。
让工作流可重复使用
对于仓库级约定，可将文档要求添加到 AGENTS.md。例如：
## Documentation - When user-facing behavior changes, check whether docs, examples, or changelogs need updates. - Public docs must only include public information or behavior visible in this repo. - Preserve existing terminology and frontmatter. - Run the docs formatting and build checks before final handoff.
如果流程包含更多步骤，可以将其做成一个 技能，以便未来的 Codex 线程复用相同的来源检查、起草和验证循环。更多关于这种模式的细节，请参见 将工作流保存为技能。
你也可以把这个工作流变成一个 线程自动化：例如让 Codex 按计划运行它，并让它从 GitHub 获取所有最近的 PR，以便自动保持文档为最新状态，比如每周一次：