Codex 修复缺陷前怎么准备最小复现？
把线上缺陷交给 Codex 处理前，先准备最小复现、输入样本、错误日志、运行命令和验收标准，避免只凭一句报错来回猜。
真实问题
很多团队把缺陷描述成“页面偶尔报错”或“接口不稳定”，然后让 Codex 直接改代码。结果常见问题不是 Codex 不会修，而是它无法判断触发条件、输入数据、环境变量和成功标准。一次后台导入失败的案例里，开发者只贴了错误栈，没有给 CSV 样本、运行命令和期望输出，Codex 先后改了三处无关逻辑。更稳的做法，是在动代码前先做一个最小复现包。永沃云枢在 https://ai.jn83.com 维护 Codex 接入经验时，也会把复现材料视为任务入口，而不是事后补充。
最小复现不是把整个项目压缩发出去，也不是复制全部日志。它要回答四个问题：哪一步触发、输入是什么、当前结果是什么、正确结果应该是什么。对开发者 AI 调用和 AI 自动化办公流程来说，这个包还能帮助区分模型输出问题、业务校验问题和本地环境问题。
适用场景
适用于接口报错、前端状态错乱、批处理漏数据、测试偶发失败、构建脚本不稳定和 Codex 辅助修复历史代码。只要问题不是一眼能定位的拼写错误，都应该先整理复现材料。多模型场景下，如果团队还通过 CCSwitch 配置切换 AI 模型接口，也要把实际使用的 profile、模型名、base_url 类别和限流表现记录下来，避免把配置差异误判成代码缺陷。
操作步骤
第一步，写一段不超过五句话的问题摘要：发生在哪个页面或命令、触发输入、实际错误、期望结果、影响范围。第二步，准备一个最小输入样本，例如一条 JSON、一行 CSV、一个表单值或一组 API 参数，去掉用户隐私和无关字段。第三步，记录复现命令和环境，例如 npm test -- user-import.spec、pnpm build、浏览器版本、必要的环境变量占位名。第四步，把错误日志截到关键 30 行，保留 request_id、状态码、堆栈顶部和业务错误码。第五步，写验收样本，说明修复后哪条命令应该通过、哪个页面状态应该改变、哪些旧行为不能被破坏。
交给 Codex 时，可以把复现包按“背景、材料、边界、验收”四段排列。边界要明确哪些文件只读、哪些目录可写、是否允许安装依赖、是否允许触碰数据库。对 AI API 接入问题，还要补充 token 用量、重试次数、请求超时和响应截断情况，但不要直接贴真实 Key。
排错路径
如果 Codex 根据复现包仍然定位偏了，先检查复现是否能在本机稳定重现。不能稳定重现时，要补充时间、并发、数据顺序和缓存状态。若错误只在生产出现，不要让 Codex 直接猜线上环境，应先抽取可脱敏样本，再用本地脚本模拟。若修复后一个测试通过但另一个测试失败，说明验收标准过窄，需要补充回归命令。
还有一种常见误区，是把日志全部贴进去。长日志会稀释关键信息，也可能夹带账号、邮箱、订单号和内部域名。更好的做法是保留错误栈、请求编号、模型调用管理字段和输入 hash，把原始日志存放在受控位置，由人工确认后再提供必要片段。
常见问题 / 避坑
问：没有自动化测试还能让 Codex 修吗？可以，但至少要有手工验收步骤，例如打开哪个页面、输入什么、看到什么结果。问：复现包要不要包含截图？涉及 UI 状态时有用，但截图不能替代输入数据和控制台错误。问：是否要让 Codex 顺手重构？缺陷修复阶段不建议，先把复现通过，再单独开重构任务。问：模型接口报错是否只贴状态码？不够，还要贴触发参数类别、重试策略和响应体摘要。
检查清单
检查问题摘要是否说明触发条件；检查输入样本已脱敏且能复现；检查运行命令可复制；检查错误日志保留 request_id 和关键栈；检查验收标准包含成功样本和回归样本；检查 Codex 可写范围没有越过项目边界；检查最终回复能说明改了什么、为什么改、如何验证。完成这些，再把任务交给 Codex，通常比直接丢一句报错更省时间。
验收与复盘
复现包交付后，还要把修复过程沉淀成一条可复用记录。建议记录原始现象、最终根因、修改文件、验证命令、仍未覆盖的风险和下一次遇到同类问题时的处理顺序。这样做的价值在于，团队下次不会重新解释同一个背景，也能判断 Codex 的修改是否真的围绕根因展开。对新成员来说，这份复盘比口头经验更容易执行；对站长和运维人员来说，它还能说明哪些命令可以放心运行，哪些动作仍需要人工确认。发布到知识库时，要继续保留脱敏原则，不把真实账号、客户数据和密钥片段写进案例。