Codex 改完代码，文档还要自己补？从 Git Diff 生成 CHANGELOG 和发布说明

lrt369805210

346人浏览 · 2026-08-04 09:04:40

lrt369805210 · 2026-08-04 09:04:40 发布

摘要：代码已经通过验收，CHANGELOG、README、技术文档和发布说明却还没开始写？本文给出一套可以直接复用的 Codex 文档工作流：先从 Git 变更、测试和 Issue 中提取证据，再识别用户可见变化，分别生成三类文档草稿，最后检查每一条描述是否有依据。文末附完整提示词、验收清单和自动化思路。

关键词：Codex、CHANGELOG、技术文档、发布说明、Git diff、文档自动化、AI 编程

代码改完以后，文档通常是最容易被拖到最后的一件事。

功能能跑，测试也通过了，大家准备合并或者发布时才发现：

README 里的参数还是旧的；
CHANGELOG 只写了一句“优化若干问题”；
发布说明讲了功能，却没说谁会受到影响；
接口已经变化，示例代码还停留在上一个版本；
有些内容只是计划，已经被提前写成“正式支持”。

这个阶段当然可以让 Codex 帮忙，但一句“根据代码更新文档”还不够。它可能把内部重构写成面向用户的新功能，也可能根据类名和注释补出代码里并不存在的能力。

核心原则：先让 Codex 找证据，再让它写文档。

本文整理了一套从代码变更到发布材料的完整流程。你可以只用其中一个环节，也可以把它直接交给 Codex，生成一份等待人工确认的文档草稿。

CHANGELOG、技术文档和发布说明，不是一回事

不少项目会把三类内容混在一起，最后写出来谁都不好用。

文档	主要读者	需要回答的问题	不应该塞进去的内容
CHANGELOG	已经在使用项目的人	这个版本增加、修改和修复了什么	实现过程、提交记录复读、内部类名
技术文档	使用者和开发者	功能现在怎么使用，参数、示例和限制是什么	没有公开的路线图、无法验证的承诺
发布说明	准备升级或关注版本的人	这个版本有什么价值，谁会受影响，是否需要操作	每个文件的修改细节、无关重构

同一个改动，在三种文档里的写法也不同。

假设某次修改让配置项从必填变成可选：

CHANGELOG 记录“配置项现在可以省略，并使用默认值”；
技术文档要更新字段说明、默认值和完整示例；
发布说明需要告诉读者：哪些用户会受益，升级后是否需要修改现有配置。

如果只让 Codex 生成“一份更新说明”，这三种用途很容易被揉成一段没有重点的文字。

先看完整工作流

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

整套流程可以拆成五步：

锁定本次需要说明的变更范围；
从代码、测试和上下文中提取可证实事实；
找到真正受影响的文档位置；
分别生成 CHANGELOG、技术文档和发布说明；
检查每条描述的证据、示例和发布边界。

OpenAI 的官方文档工作流也采用了类似顺序：从分支、提交、Issue、PR 或具体文件开始，先搜索已有文档，再做尽量小而准确的更新，并运行适合仓库的文档检查。Keep documentation up-to-date

下面把每一步展开。

第一步：先锁定变更范围，不要直接让 Codex 写

文档最容易出错的地方，是一开始就没有说清楚“要描述哪一批改动”。

同一个工作区里可能同时存在：

本次功能修改；
之前留下的未提交内容；
自动格式化产生的变化；
生成文件和依赖锁文件；
尚未准备公开的实验代码。

所以第一轮只做只读检查。可以让 Codex 查看：

git status --short
git diff --stat
git diff
git log --oneline <基线提交>..<目标提交>

具体使用工作区 diff、一个提交、两个版本标签还是某个 PR，要根据你的发布范围决定。不要把上面的占位符原样执行。

可以直接使用这段提示词：

请先不要修改任何文件，也不要生成正式文档。

本次要整理的变更范围是：<工作区 diff / 提交范围 / PR / 版本标签>。

请只读检查：
1. Git 状态、变更统计和完整 diff；
2. 与这些改动直接相关的测试；
3. 已提供的 Issue、PR、需求或发布背景；
4. 当前仓库已有的 README、docs、CHANGELOG 和发布模板。

先输出：
- 本次变更包含哪些独立事项；
- 哪些属于用户可见变化；
- 哪些只是内部实现或重构；
- 哪些信息仍然无法确认；
- 哪些内容可能不适合出现在公开文档里。

<font color="#B45309"><b>这一轮只报告，不要修改文件。</b></font>

这一步的目标不是写出漂亮文案，而是把边界框住。

第二步：建立“事实清单”，区分代码变化和产品结论

看懂 diff，并不代表已经知道应该怎么对外描述。

例如，代码里新增了一个重试函数，只能证明“实现里出现了重试逻辑”，不能直接写成“所有网络问题都不会影响任务”。测试覆盖了两个场景，也不能推出所有异常都已经解决。

我更建议让 Codex 先整理一张事实表：

事实	证据位置	面向谁	可信状态
新增一个配置项	配置类型、解析逻辑和测试	使用者	已证实
默认行为发生变化	默认值代码和回归测试	已有用户	已证实
性能得到提升	只有实现调整，没有基准数据	使用者	无法证实
下个版本继续扩展	只存在于讨论记录	外部读者	不应公开

提示词可以这样写：

请根据已经确认的变更范围，整理“可用于文档的事实清单”。

每一项必须包含：
- 事实描述；
- 证据文件、测试或公开上下文；
- 影响对象；
- 是否属于用户可见变化；
- 状态：已证实 / 部分证实 / 无法证实 / 不应公开。

不要把变量名、类名或实现方式直接升级为产品承诺。
没有测试、代码或公开资料支持的结论，请明确标为无法证实。

做完这一步，后面的文档基本不会偏得太远。

第三步：先找受影响的文档，不要顺手重写全部 README

确认事实之后，下一步不是立即改文件，而是先搜索项目里哪些地方提到了相关功能。

可以重点检查：

README 中的安装、配置和快速开始；
docs/ 中的功能说明、API 文档和排障页面；
示例项目和代码片段；
CHANGELOG 或版本记录；
迁移指南、发布模板和运维手册；
配置键、命令名、接口路径和旧术语的引用位置。

搜索时不要只用功能名称。配置项、命令、错误提示、接口字段和旧名称也可能出现在不同页面里。

请根据事实清单，搜索当前仓库中可能受影响的文档。

需要同时搜索：
- 功能名称和旧名称；
- 配置键、命令、接口字段；
- 示例代码和错误提示；
- README、docs、CHANGELOG、迁移指南与发布模板。

输出一份文档影响清单：
1. 必须更新的文件和具体章节；
2. 建议更新但需要人工确认的内容；
3. 搜索过但无需修改的位置及原因；
4. 可能已经过期、但不属于本次范围的内容。

暂时不要进行大范围重写。

官方建议里有一点很实用：只更新“最小有用范围”。 如果补一段说明、改一个示例就能解决问题，没有必要让 Codex 重写整页，更不要顺手改变原有术语、目录结构和交叉链接。

第四步：三类文档分开生成

范围和证据确认后，再开始写草稿。

1. 生成 CHANGELOG

CHANGELOG 适合简短、可扫描、面向变化本身。可以按项目已有格式分类；如果仓库没有约定，不必为了整齐强行添加空栏目。

请根据已确认的事实清单，为 <版本号或发布日期> 起草 CHANGELOG 条目。

要求：
- 保持当前 CHANGELOG 的格式、语气和分类方式；
- 只记录对使用者、维护者或兼容性有实际影响的变化；
- 区分 Added、Changed、Fixed、Deprecated、Removed、Security；
- 没有内容的分类不要输出；
- 不要复读提交信息，不要写内部类名和无关重构；
- 破坏性变化、弃用和迁移要求必须单独标明；
- 每条内容都必须能追溯到事实清单。

先输出草稿和证据对应关系，暂时不要写入文件。

一条合格的 CHANGELOG 不需要把过程讲完，但应该让已有用户知道“这会不会影响我”。

2. 更新技术文档

技术文档的重点不是宣传，而是让读者能够正确使用。

除了功能描述，还要关注：

使用前提和适用版本；
参数、默认值和返回结果；
正常示例与关键失败场景；
兼容性、权限和安全限制；
从旧行为迁移到新行为的方法。

请根据事实清单和文档影响清单，起草最小必要的技术文档更新。

要求：
- 保留现有章节结构、术语、frontmatter 和交叉链接；
- 只修改与本次行为变化直接相关的段落和示例；
- 示例中的命令、参数和返回值必须能从代码或测试确认；
- 如果默认值、错误行为或兼容性发生变化，必须明确说明；
- 不写未公开路线图、内部讨论和无法证实的能力；
- 不为了“写得更完整”而扩大到无关章节。

修改后列出：每个文档文件改了什么、依据是什么、还缺什么验证。

3. 生成发布说明

发布说明要比 CHANGELOG 更好读，但仍然不能变成营销承诺。

建议至少包含：

这次版本解决了什么问题；
哪些人会受到影响；
是否需要修改配置、重新部署或迁移数据；
已知限制和暂未覆盖的场景；
到哪里查看完整文档和 CHANGELOG。

请基于已确认的事实，为 <版本或发布渠道> 起草发布说明。

读者是：<普通用户 / 开发者 / 项目维护者>。

请包含：
1. 一段不超过 100 字的版本摘要；
2. 主要新增、变化和修复；
3. 对已有用户的影响；
4. 升级、配置或迁移操作；
5. 已知限制和未验证内容；
6. 相关技术文档与 CHANGELOG 链接位置。

要求：
- 使用读者能理解的语言，不复读代码实现；
- 不使用“全面提升”“彻底解决”等无法证明的表述；
- 不把计划中的能力写成已经发布；
- 草稿中的每项结论都要标注对应证据。

同一份事实清单，最终要得到三种不同颗粒度的文本。 这比让 Codex 把同一段话复制到三个文件里更有用。

第五步：再做一次“反向验收”

代码要验收，文档同样要验收。

我会重点检查下面几项：

检查项	要确认什么
事实准确	每个功能、参数、默认值和限制是否有代码、测试或公开资料支持
范围正确	有没有把内部重构包装成新能力，或遗漏用户可见变化
示例可用	命令、配置和代码片段是否能够运行，是否使用真实路径和字段
前后一致	README、技术文档、CHANGELOG 和发布说明是否使用同一术语
发布边界	是否混入未公开计划、客户信息、内部链接或敏感配置
文档质量	格式、链接、frontmatter 和文档构建是否通过

可以让 Codex 做一次只读复核：

请对当前文档改动进行只读验收，不要继续润色或扩大修改范围。

逐条检查：
- 每个用户可见结论是否能从代码、测试或公开资料中证实；
- CHANGELOG、技术文档和发布说明是否存在表述冲突；
- 示例命令、配置键、接口字段和链接是否正确；
- 是否混入内部实现、未公开计划、客户信息或敏感内容；
- 是否保留了原有文档结构、术语和 frontmatter；
- 仓库已有的格式、链接和文档构建检查是否通过。

输出：
1. 已通过的检查和证据；
2. 无法执行的检查及原因；
3. 无法证实或需要人工确认的表述；
4. 建议发布 / 修正后发布 / 暂不发布。

发现问题先报告，不要直接改写。

这里最值得看的不是“文档检查通过”这句话，而是 Codex 实际运行了什么命令，以及每条对外描述能不能找到依据。

不想分五次问？直接复制这份完整提示词

下面这段适合代码已经完成验收、准备整理发布材料时使用：

请根据当前项目中已经完成并通过验收的代码变更，起草本次发布需要的文档材料。

本次变更范围：<工作区 diff / 提交范围 / PR / 版本标签>
目标版本：<版本号或发布日期>
发布读者：<普通用户 / 开发者 / 项目维护者>

重要限制：
- 先只读分析，不要立即修改文件；
- 不要暂存、提交、推送或发布；
- 不要覆盖用户已有的无关修改；
- 不要把内部重构写成用户功能；
- 不要写未公开路线图、客户信息、密钥或内部链接；
- 无法从代码、测试或公开资料证实的内容必须标记，不要自行补全。

请按顺序完成：

1. 检查 Git 状态、变更统计和完整 diff，锁定本次范围；
2. 读取相关测试、Issue、PR、需求说明和已有文档；
3. 建立事实清单，区分用户可见变化、内部实现、无法证实和不应公开内容；
4. 搜索 README、docs、示例、CHANGELOG、迁移指南和发布模板，生成文档影响清单；
5. 起草 CHANGELOG，只记录有实际影响的新增、变化、修复、弃用、移除和安全事项；
6. 起草最小必要的技术文档更新，保留原有结构、术语、frontmatter 和交叉链接；
7. 起草发布说明，说明版本价值、影响对象、升级操作和已知限制；
8. 为所有用户可见结论建立证据对应关系；
9. 运行仓库已有的文档格式、链接、示例或构建检查；
10. 输出文档验收报告。

验收报告必须包含：
- 建议修改的文件；
- 每个文件的修改原因；
- CHANGELOG、技术文档和发布说明草稿；
- 用户可见结论及其证据；
- 已执行的检查和结果；
- 未执行或无法完成的检查；
- 需要人工确认的内容；
- 最终建议：可以写入 / 确认后写入 / 暂不写入。

先把分析、草稿和证据发给我审核，得到确认后再修改文件。

这段提示词故意把“分析”和“写入文件”拆开。发布材料涉及对外承诺，先看草稿，通常比让 Codex 写完再回退更省事。

四个很常见的文档自动化误区

1. 直接把 Git 提交记录当 CHANGELOG

“refactor service”“fix typo”“update deps”对开发过程有意义，对使用者未必有意义。CHANGELOG 应该按用户影响重新组织，而不是把提交标题换一种说法。

2. 只看代码，不看测试和已有文档

代码告诉你实现发生了什么，测试能补充边界，已有文档则决定术语和结构。三者缺一，很容易写出事实没错、但放错位置的内容。

3. 为了完整，重写整份 README

改动越大，越难审查，也越容易破坏原来的链接、示例和写作习惯。多数版本只需要补充一个段落、改一个示例或增加一条迁移说明。

4. 把“看起来合理”当成“已经证实”

尤其是性能、安全、兼容性和稳定性描述，没有基准测试、回归测试或明确证据时，宁愿保守一点，也不要让 Codex 根据实现意图给出确定结论。

流程稳定以后，可以再考虑自动化

第一次做时，建议保留人工确认。等到文档位置、分类方式和验收规则都比较稳定，再把流程接入脚本或 CI。

OpenAI 的非交互模式文档把“生成发布说明或摘要”列为 codex exec 的适用场景之一，它可以把输出交给其他命令继续处理。Codex 非交互模式

一个最简思路是：让流水线收集已经确定的提交范围，再让 Codex 输出 Markdown 草稿。比如：

codex exec "根据指定提交范围生成发布说明草稿。只输出 Markdown；无法证实的内容标记为待确认。"

但不要一开始就让它自动发布。 更合适的落点是：

自动生成草稿；
保存为待审查文件或构建产物；
人工检查证据、敏感信息和发布边界；
确认后再进入正式发布流程。

如果每次都要重复同样的提示词和检查步骤，可以把这套流程做成 Codex Skill；如果只是希望项目长期提醒“用户行为变化后必须同步文档”，则可以把简短规则写进 AGENTS.md。

例如：

## Documentation

- When user-facing behavior changes, check README, docs, examples, and CHANGELOG.
- Public docs must only include information that is public and verifiable from this repository.
- Preserve existing terminology, links, and frontmatter.
- Run the repository's documentation checks before final handoff.

如果你还不清楚 AGENTS.md 怎么写，可以先看我们之前整理的这篇：

AGENTS.md 到底怎么写？给 Codex 一份真正有用的项目说明书

Codex 任务还没结束，但人要离开电脑怎么办？

前面的流程解决了“代码改完以后，怎样把变更整理成可信的文档和发布材料”。但在实际使用 Codex 时，还有一个很现实的问题：任务没有结束，人却不一定能一直坐在电脑前。

运行测试、执行构建、检查文档、等待命令返回……任何一步都可能拉长任务时间。中途如果需要看一眼进度、补充一句要求，或者处理权限确认，又得重新回到电脑前。

这也是我们开源 Linco Bridge 的出发点。

Codex、Claude Code、Hermes 等本地 Agent 仍然运行在个人电脑上，代码和开发环境也继续留在本机；Linco Bridge 负责把会话进度、流式输出、工具调用和权限请求延伸到手机端。它不是把项目搬到云端，而是让你离开电脑以后，仍然可以在手机上继续跟进本地 Agent。

如果你想进一步了解 Linco Bridge，可以从下面这几篇开始：