程序员小枫同学

Appearance

用 Codex 开发一个完整功能 ​

嘿，我是小枫。今天聊一个我踩坑最多的话题：怎么用 Codex 正儿八经地开发一个功能，而不是让它帮你写一堆最后得重来的代码。

我刚开始用 Codex 的时候特别天真，丢一句「帮我加个导出功能」就指望它给我全搞定。结果呢，它确实写出来了——就是产品逻辑全是我替我做主了，权限也不对，空状态压根没考虑，改到最后我恨不得自己重写一遍。后来我慢慢琢磨出一套流程，照着走能少踩很多坑，分享给你。

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

别学我最早那样，扔一句「增加导出功能」就完事。需求越模糊，Codex 脑补的空间就越大，而它脑补出来的东西，十有八九跟你想的不一样。

我现在习惯把需求写成具体的验收条件，像这样：

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

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

说白了就是提前想好这六个维度：成功路径、空状态、错误状态、权限、数据上限、兼容性。你写得越清楚，Codex 跑偏的概率就越低。

第二步：让 Codex 找现有模式 ​

需求理清了，别急着让它写代码。先让它做一次「只读调研」——看看项目里已有的实现是怎么做的。

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

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

这一步我吃过亏。有次为了一个小导出功能，Codex 给我引入了一个全新的 CSV 库和一套自己的状态管理，结果后面维护的时候同事问我：「小枫你这儿怎么又多了一套东西？」从那以后我每次都先让它找现有模式——项目里已有的方案，能复用就复用，别为了一个小功能引入新体系。

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

调研完了，先别动手，让 Codex 出计划。

好的切法长这样——每个切片都能独立跑起来验证：

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

我以前经常犯的错是「先写所有后端，再写所有前端，最后一起测」——这种切法最大的问题是，问题全攒到最后才暴露，那时候已经改不动了。

提示词你可以这样写：

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

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

计划你看过了，确认没问题，这时候才开始写代码。记住，一次只搞一个切片：

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

小批次推进的好处特别实在——数据结构设错了、接口理解偏了、产品逻辑有问题，你第一时间就能发现，而不是写了三个切片之后才回头改。

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

功能代码写完了，千万别忘了数据这块。涉及数据库或者公共接口的时候，我习惯让 Codex 回答这几个问题：

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

我的血泪教训：迁移脚本和功能代码千万别绑在一起一次性上线。分开来，先保证迁移能安全跑通，再上功能代码，出问题也好回滚。

第六步：补齐异常路径 ​

这时候功能应该能跑通 happy path 了，但真正让人头疼的都是异常情况。让 Codex 拿着验收条件做一次反向检查：

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

注意最后一句话很重要——让 Codex 「只报告真实相关项」。不然它会给你每个函数都套上 try-catch，代码臃肿得不行。

第七步：完成端到端验证 ​

一个功能至少要过这五关：

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

验证完了输出一份对照报告，一目了然：

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

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

功能确认没问题之后，做一次局部整理就够了：删调试代码、统一命名、合并重复逻辑、补齐注释。这时候千万别手痒去升级依赖或者重构无关模块——我有次上线前顺手升级了一个工具库，结果兼容性问题搞到半夜，血的教训。

常见失败模式 ​

聊几个我亲身踩过的坑，希望你不用再踩一遍。

Codex 自己决定产品逻辑 ​

Codex 在没有明确指令的时候，会自动脑补产品决策。有一次我让它做导出，它自己决定「用户肯定想要 PDF」，给我整了一套 PDF 生成 pipeline，其实产品只要 CSV。我的习惯是：让它把未决策的项列出来，产品判断的事情一律由人来拍板。

只验证 happy path ​

刚开始用 Codex 的时候，我经常只测正常流程，结果上线后用户一点空列表导出就崩了。后来我养成的习惯是把权限、空结果、重复提交、失败恢复直接写进验收条件里，而不是最后补一句「考虑边界情况」——相信我，最后补的那句永远不会被认真对待。

一次改太多文件 ​

有次我一个功能改了 20 个文件，出问题之后根本不知道是哪个改动引起的。现在严格按垂直切片走，每个切片完就看 diff 和测试，哪里崩了一目了然。

生成了第二套架构 ​

Codex 有时候会「创新」——在已有项目里另起一套完全不同的实现方式。避免这个的办法是：实现前先让它搜索相邻功能，明确要求复用现有组件、错误类型和数据访问模式。

完成门槛 ​

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

下一步 ​

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