摘要代码已经通过验收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 查看gitstatus--shortgitdiff--statgitdiffgitlog--oneline基线提交..目标提交具体使用工作区 diff、一个提交、两个版本标签还是某个 PR要根据你的发布范围决定。不要把上面的占位符原样执行。可以直接使用这段提示词请先不要修改任何文件也不要生成正式文档。 本次要整理的变更范围是工作区 diff / 提交范围 / PR / 版本标签。 请只读检查 1. Git 状态、变更统计和完整 diff 2. 与这些改动直接相关的测试 3. 已提供的 Issue、PR、需求或发布背景 4. 当前仓库已有的 README、docs、CHANGELOG 和发布模板。 先输出 - 本次变更包含哪些独立事项 - 哪些属于用户可见变化 - 哪些只是内部实现或重构 - 哪些信息仍然无法确认 - 哪些内容可能不适合出现在公开文档里。 font color#B45309b这一轮只报告不要修改文件。/b/font这一步的目标不是写出漂亮文案而是把边界框住。第二步建立“事实清单”区分代码变化和产品结论看懂 diff并不代表已经知道应该怎么对外描述。例如代码里新增了一个重试函数只能证明“实现里出现了重试逻辑”不能直接写成“所有网络问题都不会影响任务”。测试覆盖了两个场景也不能推出所有异常都已经解决。我更建议让 Codex 先整理一张事实表事实证据位置面向谁可信状态新增一个配置项配置类型、解析逻辑和测试使用者已证实默认行为发生变化默认值代码和回归测试已有用户已证实性能得到提升只有实现调整没有基准数据使用者无法证实下个版本继续扩展只存在于讨论记录外部读者不应公开提示词可以这样写请根据已经确认的变更范围整理“可用于文档的事实清单”。 每一项必须包含 - 事实描述 - 证据文件、测试或公开上下文 - 影响对象 - 是否属于用户可见变化 - 状态已证实 / 部分证实 / 无法证实 / 不应公开。 不要把变量名、类名或实现方式直接升级为产品承诺。 没有测试、代码或公开资料支持的结论请明确标为无法证实。做完这一步后面的文档基本不会偏得太远。第三步先找受影响的文档不要顺手重写全部 README确认事实之后下一步不是立即改文件而是先搜索项目里哪些地方提到了相关功能。可以重点检查README 中的安装、配置和快速开始docs/中的功能说明、API 文档和排障页面示例项目和代码片段CHANGELOG 或版本记录迁移指南、发布模板和运维手册配置键、命令名、接口路径和旧术语的引用位置。搜索时不要只用功能名称。配置项、命令、错误提示、接口字段和旧名称也可能出现在不同页面里。请根据事实清单搜索当前仓库中可能受影响的文档。 需要同时搜索 - 功能名称和旧名称 - 配置键、命令、接口字段 - 示例代码和错误提示 - README、docs、CHANGELOG、迁移指南与发布模板。 输出一份文档影响清单 1. 必须更新的文件和具体章节 2. 建议更新但需要人工确认的内容 3. 搜索过但无需修改的位置及原因 4. 可能已经过期、但不属于本次范围的内容。 暂时不要进行大范围重写。官方建议里有一点很实用只更新“最小有用范围”。如果补一段说明、改一个示例就能解决问题没有必要让 Codex 重写整页更不要顺手改变原有术语、目录结构和交叉链接。第四步三类文档分开生成范围和证据确认后再开始写草稿。1. 生成 CHANGELOGCHANGELOG 适合简短、可扫描、面向变化本身。可以按项目已有格式分类如果仓库没有约定不必为了整齐强行添加空栏目。请根据已确认的事实清单为 版本号或发布日期 起草 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 草稿。比如codexexec根据指定提交范围生成发布说明草稿。只输出 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 repositorys documentation checks before final handoff.如果你还不清楚AGENTS.md怎么写可以先看我们之前整理的这篇AGENTS.md 到底怎么写给 Codex 一份真正有用的项目说明书Codex 任务还没结束但人要离开电脑怎么办前面的流程解决了“代码改完以后怎样把变更整理成可信的文档和发布材料”。但在实际使用 Codex 时还有一个很现实的问题任务没有结束人却不一定能一直坐在电脑前。运行测试、执行构建、检查文档、等待命令返回……任何一步都可能拉长任务时间。中途如果需要看一眼进度、补充一句要求或者处理权限确认又得重新回到电脑前。这也是我们开源Linco Bridge的出发点。Codex、Claude Code、Hermes 等本地 Agent 仍然运行在个人电脑上代码和开发环境也继续留在本机Linco Bridge 负责把会话进度、流式输出、工具调用和权限请求延伸到手机端。它不是把项目搬到云端而是让你离开电脑以后仍然可以在手机上继续跟进本地 Agent。如果你想进一步了解 Linco Bridge可以从下面这几篇开始Linco Bridge 开源在手机端续接 Codex、Claude Code、Hermes 等本地 AI Agent —— 从项目定位、整体架构和安全边界开始了解手机端续接 Codex 实战从安装 linco-connect 到跑通第一个跨端会话 —— 实际跑通电脑与手机之间的第一个会话cc-connect 已经很强了我们为什么还要做 Linco Bridge —— 对比两种开源方案的产品路线和连接方式离开电脑后怎么继续跟进 Codex 任务国内用户的 5 种远程方案 —— 比较官方 Remote、远程桌面、SSH、国内 IM 和 Linco Bridge项目地址GitHublincotalk/linco-bridge如果你也会让 Codex 或其他本地 Agent 执行耗时任务欢迎试用 Linco Bridge、提交 Issue或者点一个 Star。也欢迎在评论区聊聊离开电脑以后你最希望在手机上继续处理哪类任务Codex 实战系列第一次让 Codex 接手陌生项目我不会先让它写代码7 步完成项目接管AGENTS.md 到底怎么写给 Codex 一份真正有用的项目说明书Codex 改完代码怎么判断能不能提交一套可直接复制的验收流程Codex 改完代码文档还要自己补从 Git Diff 生成 CHANGELOG 和发布说明参考资料OpenAIKeep documentation up-to-dateOpenAICodex non-interactive mode