我做过很多次多文件、多步骤的改动从前期的任务拆解到最后的提交、审查试下来这套流程是目前最顺手的。之前几篇讲了Codex CLI的环境配置和基础玩法这篇直接进入实战拿一次真实的全栈功能开发来复盘整个链路重点讲清楚如何把模糊的想法变成Codex能执行的任务、如何让多文件的改动不出乱子以及在Codex给出错误代码时怎么定位和修复。对准备把Codex CLI当日常生产力的朋友来说这篇文章应该能帮你把能用提升到好用。1. 任务的起点把模糊想法转成Codex能执行的指令1.1 先自己想清楚再让Codex动手很多人在用Codex CLI的时候有个误解觉得AI编程助手厉害在你说个大概它就能给你写出来。试过几次就会发现想法越模糊返工次数越多。Codex不是读心术它是你的结对编程搭档需要你把需求描述到它不用追问的状态。我习惯在开工前花十分钟写一份任务说明这份说明不是给Codex看的是给自己看的。等你想明白了把它塞给Codex的时候自然就能得到好结果。任务说明包含四个部分背景当前代码的状态哪个模块需要改动为什么需要改动。目标改动完成后用户能做什么系统会有什么样的新行为。约束不许动哪些文件、必须遵循的代码风格、已有的设计模式。验收标准什么样的结果算做完最好能写出跑什么命令看什么输出。比如想给已有的博客加一个标签云功能背景是博客项目已经有文章列表和标签字段但标签只存在数据库里没有页面展示目标是首页侧边栏出现标签云点击标签可以查看该标签下的文章列表约束是不能改动现有的文章发布流程不许引入额外的数据库表验收标准是首页出现标签云、标签数量正确、点击标签后列表正确。这段描述Codex直接就能开工。而如果只说给我加个标签云它大概率会先问你一堆问题或者问都不问直接按照自己的想法来结果和你的预期相去甚远。1.2 一个大需求拆成多个任务的价值从任务说明再往前一步是要主动拆任务。把一个大需求拆成多个小任务是Codex CLI正确使用方式里最容易被忽视的一点。为什么不一次性把需求全部丢给Codex两个原因。第一一次改动太多代码出现bug时你很难定位是哪个部分出了问题。第二Codex的上下文窗口是有限的任务太大会让它忘掉前面说过的重要细节。拆分方式是按照端到端可交付的原则第一个任务数据库层确认字段、查询方法跑通测试。第二个任务后端API提供标签列表和标签筛选文章的接口。第三个任务前端组件渲染标签云和标签筛选页。第四个任务联调和样式。每个任务之间是有依赖关系的一个完成并验证了再进行下一个。好处很明显每一个环节都在验证错误被控制在最小范围。拆分后的任务描述每个任务仍然包含背景、目标、约束、验收标准四部分。第一个任务和第二个任务之间会自动形成衔接——第二个任务描述里的背景写的就是第一个任务完成后的状态。还有个小技巧在任务描述的最后加一段你完成这个任务后请告诉我你改动过哪些文件以及我需要手动确认哪些步骤。这句话会让Codex在收尾时主动汇报对后续人工检查特别有用。2. Codex CLI的会话策略追问、嵌套与人工确认2.1 追问式的任务开启方式把任务说明交给Codex之后不要直接让它开工。**先让它复述一遍它对任务的理解给出它的实施计划然后再动手。**这一步能省下大量返工时间。有一次我让Codex实现一个用户角色判断逻辑觉得自己已经描述得很清楚了。它复述说需要给每个用户增加角色字段并在此字段的基础上进行权限判断。我一看这和我的预期完全不同——我不想改数据库结构只想让现有的API在访问时根据一个固定的配置判断角色。如果我直接让它开工它会去改数据库、写迁移脚本浪费一整轮。而我让它先复述两分钟就发现了问题马上补充说明用户角色不需要存数据库在API内部根据请求头中的部门ID推导。具体的做法是每条任务描述都附加这样一段话在我告诉你开始之前请先复述你对这个任务的理解并给出一个分步实施计划。不要写任何代码。等你确认计划无误后再开始。第一次这么用的时候Codex会反问一些细节这时候跟它对话、澄清问题比你直接给它答案效果更好。因为它在追问中暴露了它对需求理解的盲区你来补上它后续的执行准确率会高出一大截。2.2 中间休息与临时会话一个任务跑完验证通过接着做下一个任务。这里有一个很多人忽略的点一个任务完成之后是接着在这个会话里继续下一个任务还是开一个新会话我的经验是每完成一个任务就开一个新的会话。原因有两个。第一历史对话越长Codex上下文越接近上限它响应速度变慢并且可能出现遗忘早期指令的情况。开了新会话给它一个最干净的起点它在执行新任务时不会背着旧包袱。第二对话历史里难免有错误的代码、错误的猜测这些内容对后续任务是有干扰的。开新会话相当于清空垃圾只把当前需要的上下文带进去。但注意开新会话不等于不带上下文。**你需要在新的会话里把上一个任务的完成状态重新描述一遍。**比如第二个任务开始前新会话里要告诉它上一个任务已完成数据库有tags表和articles_tags关联表已有getTags()接口返回所有标签数组格式是JSON数组。现在继续做第二个任务……这个过程看起来繁琐实际效率会明显提升。这就像你让一个同事干活也会把上一轮结果跟他对齐一遍而不是指望他记得上一次会议的所有结论。2.3 人工确认是环节不是负担在Codex改完代码后有一个环节不能省让它在动手前和改完后都给你一个说明然后你抽查一下它的实际改动。Codex的标准行为模式是改文件 输出总结。但我要求它多一步先告诉我它打算动哪些文件、每个文件大概怎么改等我说继续再动手。这个对话框是天然的安全闸门。实际操作中Codex经常会提出一些你没想到的改动方案。比如我让它做一个删除全部completed状态的todo项功能它在计划里说了一句确认删除前是否需要二次确认提示我本来没想过这个问题但看到它提出来才想到用户误触删光所有已完成项的惨状赶紧加上确认提示。人机分工最合理的状态是Codex负责执行、分析和提出备选方案人负责拍板决策。把人工确认看成保护机制而不是额外负担整个流程会顺畅很多。3. 跑测试与手动验证Codex不会替你做的最后一公里3.1 自动测试脚本的编写Codex写完代码你让它自己跑测试它可能会给你一条测试通过的结论。但要注意如果没有测试脚本它所谓跑测试可能只是编译通过或自己写了几个断言就完事了。这时候你需要在任务描述里明确要求给现有项目增加或更新测试用例并且运行所有相关测试保证全部通过。如果你在任务描述里已经写好了验收标准这一节就会水到渠成。比如把测试命令写到package.json的scripts里运行npm test能看到通过结果。Codex会自动创建测试文件和脚本。测试的粒度也很重要。单测测逻辑集成测链路。Codex通常擅长写单元测试但集成测试建议你自己写一遍主流程因为集成测试往往暴露的是需求理解偏差而不是代码bug。让Codex写集成测试容易和它的理解保持一致但会偏离你的真实需求。有一次我让它实现一个忘记密码流程单测全绿但我手动过一遍流程时发现点击邮件里的重置链接后页面直接跳到了登录页没有任何提示。原因是API返回了成功状态但前端没有处理这个响应。这种问题单测是测不出来的必须手动验证。3.2 手动验证清单手动验证不需要把整个功能从头点到尾按核心链路过一遍即可新建、编辑、删除走一遍主流程。异常输入试一遍看是否报错报错信息是否合理。刷新页面确认状态不会丢失或错乱。换个浏览器或设备试试确认不是环境特有问题。把这些手动验证的清单也写进任务说明里Codex会在改动完代码后自己先过一遍然后把结果汇报给你。你要做的是再独立抽查一遍重点看它没测过的边界场景。Codex自己验证时往往会报喜不报忧容易忽略它认为不相关的页面或者它在验证过程中发现的bug顺手就修了但没告诉你。我的习惯是让它把改动记录列出来然后我挑几个文件直接打开源码看diff有疑问当场问这个文件你为什么改了这行机器可以自动化代码生成和静态检查但**功能是否符合预期这个判断永远需要人来做最后确认。**4. 多文件改动时的Codex策略与易错点排查4.1 一个任务改动多文件时如何避免代码风格漂移Codex在改一个跨多个文件的功能时很容易出现风格不统一的问题。比如你原有的API都是返回JSON对象Codex可能在某些地方返回了字符串你原有的函数命名都是动词开头的动宾结构Codex可能会冒出几个名词短语。这个问题在任务描述阶段就能预防把项目规范文件明确指出来。比如请阅读根目录下的CODING_STYLE.md并严格遵照其中所有约定。如果你还没有这个文件建议先花半小时整理一份把命名规范、错误处理方式、注释风格、组件组织方式写清楚。这半小时的投资能让后续每一次Codex任务的风格一致性大幅提升。还有一种风格漂移出现在导入路径上Codex经常搞不清楚用相对路径还是绝对路径。这个不用问直接在看diff时肉眼扫一遍发现就用命令修正顺便加一句后续任务描述这个项目统一使用/前缀导入不要使用相对路径。4.2 多文件改动的diff审查重点Codex完成多文件改动后怎么做diff审查别每行都看你没那个精力。按优先级只盯三处第一处是被删除的行。AI很喜欢重写它可能把原有的一段稳定代码重构成自己的版本但重构后某些边界行为发生了变化。删除代码比新增代码更容易引入隐患。第二处是被改动的函数签名。跨文件调用时签名一变所有调用点都要跟着变Codex通常能搞定但偶尔会漏掉某一处调用没改。第三处是新增的依赖。如果Codex在任务中新增了第三方包你要问清楚为什么加、能否用已有依赖替代。随意引入依赖会让项目变臃肿也会埋下安全隐患。我自己在做完一次多文件改动后发现Codex改了一个公共工具函数入参从对象改成了字符串。它更新了所有调用点但漏了一个隐藏在页面生命周期里的调用。那个页面每次打开都报错但控制台报错信息不明显排查花了我一个多小时。从那以后凡是涉及公共函数签名变动的改动我都会在人工验证清单里加一项全局搜索这个函数的调用点人工一个个确认。4.3 当Codex给出错误代码时的排查链路Codex不是每次都对。当你发现它给的代码有问题时先别急着推翻重来按下面的链路排查第一步确认错误现象。把报错信息和触发步骤原样贴回给它要求它解释出错原因。它的解释如果是猜测性的那大概率没找到根因如果它能说到具体某一行做了错误假设那方向可能对了。第二步回看它的假设。很多错误源于对现有代码结构的错误假设。你可以让它先阅读相关文件并描述现有结构再对照它实际写的代码看假设哪里出了问题。第三步最小化复现。让Codex写一个最小复现脚本或者你自己手动构造一个场景。把问题缩小到一个可独立运行的范围再问Codex怎么修。有一次遇到一个奇怪的问题Codex实现的分页接口在前端传page参数时它返回正常不传时返回的数据丢失了total字段。我把现象贴回去它先说可能是前端没有处理undefined但我前端确实有处理。后来让它读后端接口代码它才发现自己在分页参数缺省时走了另一条分支那条分支没有封装total。这次排查走的就是问题描述→假设验证→读代码找根因的链路而不是第一轮就让它重写这个接口。除非代码整体架构有问题否则不建议每次都让Codex推倒重写。推倒重写带来的新代码同样可能有新错误而且容易丧失原有代码中你不知道但依赖的行为。改成找出那一个错误的点改动尽可能小Codex的错误率会低很多。5. Git工作流与Codex的配合提交、回滚、临时修改5.1 提交信息的规范建议我做Codex项目时把Git工作流和AI任务绑定形成一套固定节奏一个任务完成人工验证通过立刻commit一次。提交信息我通常手写不用Codex生成的。原因很简单Codex给的提交信息要么太长像文档要么太短没有信息量。手写一条简洁的fix(api): 修正分页时total字段丢失问题只需要几秒钟却能让后续的git log清晰得多。Commit之前还要让Codex跑一次lint和test确保提交进去的代码是健康的。如果Codex改动过程中意外破坏了别的测试这个commit要拦住先修复再提交。5.2 引入CI之前和之后的差异团队小的时候CI可有可无。但有Codex参与开发之后CI的存在感会明显提升。因为Codex改代码时容易在你看不到的角落里破坏一些规则。用GitHub Actions跑一个简单的CI包含lint、test、build三个环节每次push都会有自动检查。这样被破坏的规则在合并前就会被揪出来而不是到上线时才爆雷。有一次项目升级了依赖库主版本Codex执行某个任务时使用了旧版API。单测全过但build直接挂掉报错指向一个函数签名变更。CI帮我拦住这个改动省了在集成环境里半夜排查的麻烦。强烈建议在项目目录里放一个AGENTS.md文件写明Codex相关的约定哪些操作必须经过人工确认、提交前必须跑CI、禁止直接push到main分支、所有改动必须通过PR进入。5.3 让Codex帮你完成Git操作Codex不仅能写代码也能执行Git操作。除了权限敏感的操作比如force push日常的创建分支、stash、cherry-pick、revert交给它没毛病。我是这样用的想让Codex做一次修改前先让它创建一个分支比如fix/tag-cloud-styles。这样原始分支是干净的随时可以切换回去对比。做完改动、验证通过之后让它在分支上commit并push然后在远端发起PR。整个流程不用离开终端效率很高。一个特别实用的组合如果Codex改坏了而你还没来得及commit直接让它执行git checkout .等于把改动的文件全部重置到HEAD状态。这个操作不可逆但Codex不会像人一样犹豫指令清晰就能执行得干净。5.4 回滚也是需要演示的场景Codex偶尔会出现一个任务改了五六个文件、但只有两三个文件真正需要的情况。这时候全部commit有点脏。我不建议直接开新会话把不需要的改动删掉因为可能会误删有用的部分。正确姿势是让Codex列出它改动过的文件清单然后你来决定保留哪些告诉它只保留xxx的改动剩下的revert。代码回滚对Codex来说就是一次普通的文件修改操作很容易完成比人手动处理更利落。还有个细节回滚后需要把之前人工验证过的功能再冒烟测试一遍确认回滚操作本身没有引入新问题。这条经验来自一次实际事故——有个同事让Codex回滚某个功能时把另一个功能的配置项也回滚了结果一直在出诡异问题排查了很久才定位到是回滚覆盖面过大。6. 深入一点的技巧让Codex处理数据库迁移和跨服务变更6.1 数据库迁移让Codex生成迁移脚本而非自动执行涉及到数据库结构变更的任务我不让Codex直接执行迁移只让它生成迁移脚本和对应的升级/回滚SQL。原因有两个迁移是不可逆操作即使有回滚脚本一旦执行出错成本很高而且迁移往往需要在特定的时间窗口进行不是代码改动完成就能立即执行的。让Codex做这块工作时任务描述里我会写清楚不要自动执行数据库迁移。请生成migration文件并提供对应的rollback脚本。在测试环境中运行迁移前必须先人工审阅生成SQL。这里还能用上Codex一个很擅长的能力分析现有数据库结构指出可能存在的数据一致性问题。比如加字段时如果没有默认值已有的行会不会出错删表时是否还有外键引用。这些分析在迁移脚本里直接让它写注释后续维护的人看代码会更省心。6.2 跨服务变更Codex怎么配合多仓或多模块如果你的项目不止一个代码仓库一个功能可能需要同时改前后端、改另一个服务的接口。这种情况用Codex也是可行的但要注意任务的边界感。我在这种场景下的做法是一次会话只负责一个仓库的改动不跨仓库。改完仓库A验证通过再开新会话去改仓库B。但同步两个仓库之间的接口契约是在改之前就要定下来的。我会把接口契约文档接口路径、参数、返回结构写清楚塞给两个仓库各自的Codex任务描述。Codex在改完一个仓库后会自动检查当前仓库的测试是否通过。但它不会主动去另一个仓库做接口联调。这时候需要一个人工步骤把仓库A的接口模拟服务启动起来让仓库B的代码在本地连过去实际跑通一下。有一次跨服务改动前后端都完成了单元测试全过联调时发现接口返回的字段命名一个用驼峰一个用下划线两边各写各的没有对齐。文本契约虽然写了但写文案的时候两边都理解不同的命名规则最后还是联调时才发现。跨服务联调这个步骤不能跳过AI也一样。6.3 老项目的重构Codex适合当重构参谋最后说一下Codex在老项目重构中的用法。老项目往往有大量历史包袱直接让Codex重构整个模块风险很大。更稳的方式是让Codex先分析后小步重构。比如你有一个后台管理模块代码又长又乱你想提取公共方法。可以这样描述任务不要改动任何功能逻辑。请阅读以下三个文件找出可以抽取的公共方法输出一份重构建议不实际改动代码。等我确认建议后再动手。这样的描述会让Codex先输出建议你再决定哪些改动值得做。它往往能发现一些你没有察觉的重复代码和潜在问题但你仍然保有裁量权。小步重构时每次改动控制在一个方法提取或一个文件重命名的粒度。改完立即测试通过后再进行下一个。这种节奏看起来很慢但累计下来效果很好而且每次代码变更都是可控、可回滚的。7. 让Codex与团队其他成员协作的几个注意事项7.1 AGENTS.md如何减少协作摩擦前面提到的AGENTS.md对个人开发者来说是个备忘对团队协作来说就是代码协定的主心骨。市面上大型开源项目里这类文件越来越多作用是把AI协作的边界制度化。以我维护的一个项目为例AGENTS.md写了几件事禁止自动生成并执行数据库迁移只准生成脚本。禁止删除被测试覆盖的公共函数必须修改时需同步更新测试。新增依赖前必须人工确认。所有对外接口变更需同步修改API文档。代码改动遵循现有命名风格不引入新的风格。Codex每次执行任务前会自动读一遍这个文件相当于在动手之前就被约束了一轮。这个文件写的不是一个一个的命令而是原则。原则表述清楚Codex推断出的实施方式会比给一条条死命令更符合团队习惯。7.2 Codex出现问题时怎么向它描述上下文团队同事问到为什么这个功能在Codex改完之后出问题了不要把原始报错直接丢给Codex也不要说改成你能想到的最佳方案。这两者效果都不好。场景化的描述应该是这样的在main分支的最新提交上访问/admin/users页面点击编辑按钮后页面空白控制台报错TypeError: Cannot read properties of undefined (reading name)。之前这个页面是可以正常工作的。请先阅读这个页面的组件文件和对应的数据层代码找出错误原因不要修改任何内容只输出分析结果。这种描述有具体触发路径、有报错信息、有限定范围Codex的分析准确率会高很多。反观帮我修一个bug页面打不开这类描述Codex只能猜猜不准就会来回试错。7.3 什么时候不该用CodexBig有个问题什么时候不该让Codex做我的判断依据很简单——当这个改动的后果难以用git diff来撤销时就需要极其谨慎。比如删除线上的数据库记录、修改生产环境的配置、执行不可逆的安全策略变更。这类操作更合适的角色是让Codex先生成操作文案和检查清单由人工审阅后手动执行而不是让它全自动跑完。此外涉及敏感凭据的操作我从不交给Codex。就算你的终端环境里没有被托管的密钥Codex生成的脚本也可能会打印日志、写入错误文件稍有不慎就把凭据带出去了。安全边界要用制度的确定性来约束而不是指望模型每次都眼光独到。8. 从我真实项目里提炼的几条硬核经验8.1 让Codex先读文件再说话的价值好几次遇到Codex对项目结构一无所知却直接开写的情况。这多半因为我没有在任务描述里加一句先阅读项目的README和关键源代码再开始工作。加上这句话之后Codex的回答质量会有肉眼可见的提升。有一次让它改一个老模块的路由配置它没读文件就开写把路由路径从/user改成了/users导致所有旧链接全部404。后来我养成习惯所有涉及文件改动的任务都强制它先阅读相关文件输出它理解的上下文再开始改动。8.2 一句话锁死不要顺手改别的AI有个毛病看到哪里不符合它习惯就顺手改了。一次让它修一个登录页按钮的样式问题它顺手把按钮文案从登录改成了Sign in。我需要它只做指定的事。所以任务描述里通常加一句除非必要不要改动与本任务无关的任何代码。所有改动必须和本任务直接相关。这句话看似简单实际效果很好。它会把Codex的自由发挥裁剪到最低让你审查diff时不需要在一堆无关改动里筛选。8.3 用最后一次改动定位回归问题项目迭代久了偶尔会遇到这个功能昨天还能用今天就不行了的回归问题。Codex一天之内改了十几个文件怎么定位我的做法是让Codex做一次二元搜索式的排查先看最近的git log和git diff列出所有改动过的文件然后逐个文件判断它和出问题的功能是否有依赖关系。对于可能相关的文件继续往下看具体的改动代码直到找到可疑的那处。这个方法对Codex来说是自然擅长的因为它能一次性读取大量文件并快速分析。最终它会给你一个判断这个回归更可能是由xxx文件中的xxx改动引起的因为该文件为这个功能提供了xxx数据。然后你只需要回看一下那次改动的代码确认或否认它的判断。整个定位过程从一小时压缩到十分钟。一些零碎但重要的收尾建议最后分享几个我在多轮实战里沉淀的习惯每一条都是从具体事故里捡回来的。测试要看失败的情形而不是通过的情形——Codex写测试时天然倾向覆盖能跑通的路径容易漏掉异常分支。我在验收时习惯自己加几个破坏性场景来验证边界。历史上上次人类改动过的文件往往是本次bug最可能的藏身处Codex却不擅长记住这一点。所以你可以在任务描述里加一句优先排查最近10次commit中改动过的文件它会更快锁定目标。Codex有很强的类比迁移能力但也有很强的惯性漂移倾向。它解决问题的方式常常和你原本的实现思路不一样这未必是坏事但你需要确保它遵守了项目既有的技术栈约束而不是把一个纯前端方案改成了需要引入后端的方案。希望这篇实战记录能帮你在自己的项目里更稳妥地把Codex CLI用起来。如果你也有独特的配合方式欢迎随时拿出来讨论这套工作流没有标准答案只有越用越顺手的区别。