用 Codex 开发一个完整功能

开发功能时，Codex 最容易犯的错误不是不会写代码，而是在需求空白处自行做产品决定。先把用户行为、异常路径和兼容边界写成验收条件，再让它研究现有实现模式，能显著减少返工。

第一步：把需求改写成行为

不要只写“增加导出功能”。改成：

目标：用户可以在订单列表导出当前筛选结果为 CSV。

验收：
1. 导出内容使用当前筛选和排序；
2. 空结果时按钮可点击，但下载只包含表头；
3. CSV 使用 UTF-8，Excel 打开中文不乱码；
4. 普通用户只能导出自己有权查看的订单；
5. 单次最多导出 10,000 条，超限显示已有错误提示样式；
6. 不改变现有列表 API 的响应结构。

补齐：成功路径、空状态、错误状态、权限、数据上限、兼容性和可观察结果。

第二步：让 Codex 找现有模式

先只读调查，不实现。寻找项目中最接近的下载、列表筛选、权限校验和错误提示实现。

输出：
- 可复用的组件、服务和工具函数；
- 建议修改文件；
- 数据从 UI 到存储/下载的路径；
- 需要新增的测试层级；
- 仍需产品确认的问题。

优先复用项目已有方式。为了一个小功能引入新的状态库、HTTP 客户端或 UI 体系，通常会制造更多维护成本。

第三步：按垂直切片制定计划

好的切片能独立验证，例如：

1. 后端按权限和筛选生成正确 CSV；
2. 前端发起下载并处理空结果、超限和失败；
3. 端到端验证真实用户路径；
4. 更新使用说明和发布记录。

差的切法是“先写所有后端，再写所有前端，最后一起测”，因为问题会积到最后。

提示：

给出 3 到 5 个可独立验证的垂直切片。每个切片写清修改文件、完成条件、测试和回退点。不要开始实现，先让我审查计划。

第四步：实现第一个最小切片

确认计划后：

只实现切片 1。
遵循现有架构和命名，不提前实现后续切片。
先补最接近业务规则的测试，再实现代码。
完成后运行最小验证，展示 diff 摘要和未解决问题。

小批次的好处是你能及时发现数据结构、接口和产品理解是否错误。

第五步：处理数据和兼容性

涉及数据库或公共接口时，要求 Codex回答：

• 旧数据怎样读取；
• 新字段是否可空、默认值是什么；
• 新旧客户端能否同时工作；
• 迁移能否重复执行；
• 失败怎样回滚；
• 是否需要先读后写、双写或分阶段启用；
• 日志和监控如何确认新功能健康。

不要让迁移脚本和功能代码在没有验证的情况下同时一次性上线。

第六步：补齐异常路径

让 Codex按验收条件做一次反向检查：

逐条对照验收条件，列出对应实现和测试。再补查：空输入、重复提交、权限拒绝、超时、部分失败、文本溢出、并发和重试。只报告真实相关项，不要机械添加无关防御代码。

第七步：完成端到端验证

一个功能至少要经过：

1. 单元或模块测试；
2. 类型检查、lint 或编译；
3. 后端/前端集成；
4. 用户路径人工验证；
5. Git diff 和独立代码审查。

示例报告：

验收 1：通过。筛选条件由前端传入，后端复用 OrderFilter；集成测试覆盖。
验收 2：通过。空结果下载仅含表头；fixture 验证。
验收 3：通过。使用 UTF-8 BOM；在 Excel 中人工打开确认。
验收 4：通过。查询复用现有 tenant scope；拒绝路径测试通过。
验收 5：通过。10001 条返回 422 和现有错误码。
验收 6：通过。列表 API 未修改。

第八步：清理实现而不是扩大范围

功能正确后再做一次局部整理：删除调试代码、补命名、合并重复逻辑、更新注释。不要在交付前临时升级依赖或重构无关模块。

常见失败模式

Codex 自己决定产品逻辑

让它把所有未决策项列出来，产品判断由人确认。

只验证 happy path

把权限、空结果、重复提交和失败恢复写进验收条件，而不是最后补一句“考虑边界情况”。

一次改太多文件

按垂直切片逐步执行，每个切片都看 diff 和测试。

生成了第二套架构

在实现前要求搜索相邻功能，明确复用现有组件、错误类型和数据访问模式。

完成门槛

• [ ] 每条验收条件都能对应实现和验证。
• [ ] 未决策问题在编码前得到确认。
• [ ] 修改按可验证切片完成。
• [ ] 兼容性、权限和异常路径有明确处理。
• [ ] 文档和发布说明与真实行为一致。

下一步

继续学习 用 Codex 补测试与建立验证门槛。