Codex 改完代码怎么写变更说明？
Codex 完成代码修改后，应按文件清单、行为变化、验证命令、未覆盖风险和回滚备注整理交接，方便 PR review。
适用场景：代码改了，但 Review 不知道从哪看
这篇适合用 Codex 接入日常开发、站点维护、脚本修复和 AI 自动化办公工具改造的个人或小团队。常见问题是 Codex 说“已完成”，但 PR 里有十几个文件，Review 人不知道哪些是核心变更，哪些是格式化，哪些测试跑过，哪些风险没有覆盖。永沃云枢在 https://ai.jn83.com 整理 Codex 实操时，会把变更说明当成交付物的一部分，而不是任务结束后的客套话。
这和“让 AI 写代码”不是一回事。真正可用的 Codex 接入流程，需要把 AI 模型接口、工具调用、本地命令、人工判断和最终验收串起来。变更说明写得清楚，后续上线、回滚和排查都会轻很多。
操作步骤：先列事实，再写结论
第一步，列文件清单。不要只写“优化了接口”，要说明改了哪些文件、每个文件承担什么角色。比如 API 路由负责参数校验，前端组件负责错误提示，测试文件覆盖成功和失败路径。文件多时可以按模块分组。
第二步，写行为变化。Review 人最关心用户或系统会看到什么不同。比如“AI API 接入失败时从通用错误改为显示 request_id”，“CCSwitch 配置读取增加 profile 名称校验”，“开发者 AI 调用 JSON 校验失败时进入人工复核队列”。行为变化要能被验证，不要写成抽象的“提升稳定性”。
第三步，贴验证命令和结果。命令要完整，例如 npm test -- api-json、pnpm lint、rg "禁用文案" seo，并说明通过、失败或未运行。没有运行的测试也要写原因，不要假装覆盖了。
第四步，写风险和回滚。风险不是自我否定，而是告诉接手人哪里需要重点看。比如没有真实数据库、没有外部供应商 Key、只做了本地静态检查、移动端未截图。回滚备注可以写配置开关、可删除文件或恢复旧路由的方式。
常见问题/避坑：不要让总结替代证据
第一个坑是只写“修复若干问题”，没有文件和验证命令。第二个坑是把未验证的内容写成已验证。第三个坑是忽略用户已有改动，Codex 在脏工作区里改代码时，尤其要区分自己改的文件和原来就存在的改动。第四个坑是把风险藏起来，导致 Review 人按低风险合并。
还有一个常见问题是变更说明和 PR 标题不一致。标题说修 UI，正文却改了权限、支付或数据库字段，这会让 Review 失焦。涉及 admin 设置、注册开关、邮件、支付、搜索提交等高风险区域时，应在说明里单独标出，并给出没有触碰或只读检查的证据。
检查清单：交接前自己先读一遍
检查项包括：目标和范围是否一句话说清；文件清单是否完整；行为变化是否可验证；测试命令是否包含结果；未验证项是否明确；是否写出风险；是否说明回滚；是否区分用户已有改动；是否包含截图、日志或关键输出；是否避免夸大“已经上线”“保证稳定”等无法验证说法。
如果是 SEO 内容、AI API 接入或模型调用管理相关变更，还要检查 URL、canonical、JSON-LD、sitemap、robots、SQL 和乱码。Codex 可以帮助执行本地验证，但最终合并前，Review 人仍应抽看关键文件，确认没有越权改动。
一个可直接复用的变更说明结构
可以按“做了什么、改了哪里、怎么验证、还有什么风险”四段写。第一段写用户可见变化；第二段列文件或模块；第三段列命令和结果；第四段写未覆盖项和回滚建议。这个结构足够短，也能覆盖大多数真实 PR。
例如：“本次为 AI API JSON 抽取增加 Schema 校验，失败时进入人工复核。涉及 api/extract、schema/contract 和 tests/json-contract。已运行单元测试和 30 条固定样本，2 条需要业务确认。未连接生产数据库，回滚可关闭 validate_json_output 开关。”这样的说明比“已优化 AI 输出稳定性”有用得多。
补充一个小习惯：在最终说明里写出“没有做什么”。例如没有运行远程部署、没有连接数据库、没有调用后台管理接口、没有修改注册和支付配置。这个边界能让接手人快速判断风险，也能避免把本地内容生成误认为已经上线。
FAQ：这些能不能让 Codex 自动生成？
可以让 Codex 根据 git diff、测试输出和任务日志生成初稿，再由人补充业务风险。尤其是涉及 https://ai.jn83.com 的首页、注册、支付、AI 生图入口、CCSwitch 配置和开发者 AI 调用时，人工补充边界更重要。自动化能减少整理时间，但不能替代对影响范围的判断。