常用工作流模板：理解代码、重构、补测试和性能优化
TL;DR
Codex 适合多步工程任务，但多步不代表任由它自由发挥。团队应该把高频任务沉淀成工作流模板，让 Codex 知道先读什么、什么时候不改文件、什么时候给计划、什么时候执行、跑哪些验证、最后汇报什么。理解代码、重构、补测试、性能优化这四类任务，覆盖了大多数日常工程场景。
模板的价值不是把 prompt 写得花，而是固定停靠点。理解代码阶段不改文件；重构阶段保持行为不变；补测试阶段先识别风险；性能优化阶段先测量再修改。每类任务的成功标准不同，如果都用一句“帮我处理一下”，结果会不可控。
本文中的模板是工程实践建议。它们可以放进团队文档、issue 模板、AGENTS.md 示例或 Codex Cloud 任务单里。实际使用时要替换路径、命令和约束，不要把模板当万能文本。
读者定位
本文面向已经把 Codex 用到真实仓库里的开发者和技术负责人。你可能正在从个人试用走向团队复用，希望不同成员给 Codex 派任务时有共同语言。你也可能在 review Codex 产物时发现：有人让它“理解代码”却改了文件，有人让它“重构”却改变行为，有人让它“补测试”却只覆盖 happy path，有人让它“优化性能”却没有数据。
工作流模板能降低这些差异。它不能替代工程判断，但能让常见任务有默认轨道。
问题：同一个目标，流程不同，结果差异很大
“补测试”可以有很多做法。差的做法是直接让 Codex 写几个会通过的测试；好的做法是先读现有测试风格，列出风险路径，补边界和回归测试，必要时先让失败测试暴露 bug，再决定是否修生产代码。
“重构”也一样。差的做法是让 Codex 自行整理模块；好的做法是先确认公共接口和测试护栏，给出小步计划，保持行为不变，运行相关检查，最后说明行为保持依据。
“性能优化”更依赖流程。没有基准的优化只是猜。Codex 可以发现明显低效代码，但没有复现命令、profile、日志或前后数据时，人类很难判断结果是否真实。
工程工作天然分阶段：定位、假设、计划、修改、验证、总结。模板的作用，就是把这些阶段写进任务，防止 Codex 在错误阶段做正确动作。
心智模型：四类任务对应四种停靠点
理解代码的停靠点是“地图”。产物应该是关键文件、调用链、数据流、风险点、不确定问题。默认不改文件。
重构的停靠点是“行为不变证据”。产物应该是小 diff、测试结果、公共接口说明、未改变行为的理由。默认不做顺手清理。
补测试的停靠点是“风险覆盖”。产物应该是新增场景、为什么覆盖这些场景、是否暴露 bug、相关测试结果。默认先不改生产代码，除非任务明确允许。
性能优化的停靠点是“数据”。产物应该有优化前后指标、复现命令、修改原因、剩余瓶颈。默认不凭直觉大改架构。
四类任务都可能读代码、改文件、跑命令，但节奏完全不同。模板把节奏固定下来。
模板一：理解代码
适用场景：新人接手模块、准备改高风险代码、排查问题前建立事实、review 大 diff 前理解影响。
Goal:
解释 <module/path> 的职责、入口、数据流、关键依赖和主要风险。
Context:
从 <entry files> 开始。必要时追踪调用方、测试和配置。
Constraints:
不要修改文件。不要运行会写文件或访问外部系统的命令。
Steps:
1. 先列出你准备阅读的文件和原因。
2. 阅读后总结核心流程。
3. 列出关键函数、调用链和数据结构。
4. 标注不确定点和建议下一步。
Done-when:
输出面向接手开发者的说明，包含关键文件、调用链、风险、测试覆盖和待确认问题。
真实用法：
Goal:
解释 src/auth 的登录与 session 刷新流程。
Context:
从 src/auth/index.ts、src/auth/session.ts、tests/auth/session.test.ts 开始。
Constraints:
不要修改文件，不要运行测试，只读分析。
Done-when:
输出登录入口、token 生成与校验、cookie 更新、登出路径、现有测试覆盖和风险点。
注意：理解任务最容易滑成修改任务。必须写“不要修改文件”。如果 Codex 发现 bug，让它列出建议，不要直接修。
模板二：行为保持型重构
适用场景：降低复杂度、拆函数、消除重复、改命名、迁移内部实现但保持外部行为。
Goal:
在不改变外部行为的前提下，降低 <module/path> 的复杂度或重复。
Context:
从 <module files> 和相关测试开始。先确认公共接口和现有测试。
Constraints:
不改公开 API。
不引入新依赖。
不跨目录做顺手清理。
遇到行为变化需求先停下说明。
Steps:
1. 先给出重构计划和预计改动文件。
2. 等确认后执行最小可 review diff。
3. 运行相关测试和类型检查。
4. 若测试失败，先判断是重构引入还是既有问题。
Done-when:
汇报改动范围、行为保持依据、验证命令、失败项和剩余风险。
真实用法：
Goal:
重构 src/orders/exporter.ts，减少重复的 CSV 字段拼接逻辑，保持导出结果完全一致。
Context:
相关测试在 tests/orders/exporter.test.ts。CSV 字段顺序不能变化。
Constraints:
不改公开函数签名，不改字段顺序，不引入依赖，不碰订单查询逻辑。
Done-when:
先给计划，确认后执行。执行后运行 pnpm test -- tests/orders/exporter.test.ts，
并说明哪些测试证明行为保持。
注意：没有测试护栏的重构要先补测试或降级为计划任务。不要让 Codex 在无证据情况下大范围重构共享模块。
模板三：补测试
适用场景：修 bug 前补回归测试、提高边界覆盖、为重构建立护栏、补权限或错误路径测试。
Goal:
为 <feature/module> 补充缺失测试，重点覆盖 <risk list>。
Context:
从现有测试 <test files> 和实现 <source files> 开始，沿用项目测试风格。
Constraints:
优先只改测试文件。
如果测试暴露生产代码 bug，先停下汇报，不要直接修，除非本任务明确允许。
不要重写测试框架或引入新测试依赖。
Steps:
1. 列出现有覆盖和缺口。
2. 设计测试场景。
3. 补最小测试。
4. 运行相关测试。
Done-when:
汇报新增场景、覆盖风险、测试命令结果和未覆盖风险。
真实用法：
Goal:
为用户资料更新补测试，覆盖空昵称、重复邮箱、无权限修改和并发版本冲突。
Context:
从 tests/users/profile.test.ts 和 src/users/profile.ts 开始。
Constraints:
先只改测试。若发现实现不满足预期，停下说明失败测试和建议修复点。
Done-when:
运行 pnpm test -- tests/users/profile.test.ts。
汇报每个新增测试对应的风险。
注意：有效测试不只是覆盖成功路径。让 Codex 先列风险，再写测试，通常比直接要求“补测试”更好。
模板四：性能优化
适用场景：慢查询、页面首屏慢、批处理耗时、内存占用异常、重复网络请求。
Goal:
降低 <operation> 的耗时或资源占用，并保留可复查证据。
Context:
提供复现步骤、日志、profile、慢查询、基准命令或性能指标。
Constraints:
先建立基准，不要凭直觉大改架构。
不改变用户可见行为。
不引入缓存一致性风险。
涉及数据库索引、队列、缓存、权限时先给计划。
Steps:
1. 确认当前复现方式和指标。
2. 找热点并提出最小修改方案。
3. 修改后复测。
4. 对比优化前后数据。
Done-when:
输出优化前后数据、修改文件、验证命令、剩余瓶颈和回滚建议。
真实用法：
Goal:
降低订单列表接口 P95 延迟，目标是减少重复 customer 查询。
Context:
慢日志显示 GET /orders P95 为 1800ms。入口在 services/api/orders.ts。
测试在 tests/api/orders.test.ts。可以使用本地 seed 数据。
Constraints:
先不要改数据库 schema。不要引入缓存。先定位重复查询来源并给计划。
Done-when:
给出当前瓶颈证据、最小修改方案、需要运行的测试和手动性能验证步骤。
注意：性能任务如果没有数据，应该先转成 Ask 或 Plan。直接 Execute 很容易得到漂亮但不可信的 diff。
真实工作流案例：从理解到重构再补测试
假设团队要整理一个旧的导出模块。不要一次性发：
帮我重构导出模块并补测试。
更稳的三步是：
第一步，理解：
先不要修改文件。解释 src/export 的入口、CSV 字段生成、权限检查和测试覆盖。
输出风险点和建议的重构边界。
第二步，计划：
基于刚才的分析，给出行为保持型重构计划。
计划要列出预计改动文件、不会改变的公共接口、需要补的测试和验证命令。
不要修改文件。
第三步，执行：
按确认计划执行。只改 exporter.ts 和 exporter.test.ts。
不改变 CSV 字段顺序，不引入依赖。
运行 pnpm test -- tests/exporter.test.ts。
最后汇报 diff、行为保持依据和剩余风险。
这个流程的成本比一句话高，但每一步都有可检查产物。出问题时也容易回滚到上一阶段。
操作清单：模板落地
- 把四类模板放进团队文档，不要让每个人临场发明。
- 在
AGENTS.md中链接或简述常用任务模式。 - 每个模板都写“默认是否允许改文件”。
- 每个模板都写验证命令和最终汇报要求。
- 高风险任务先用理解或计划模板，不直接执行。
- 补测试和性能优化都要先列风险或基准。
- 重构模板必须写行为保持和公共接口边界。
- 模板只是默认轨道，实际任务要填真实路径、命令和约束。
权衡与风险
模板会牺牲一点灵活性。小修小补不需要完整流程。团队可以规定：低风险文档修改直接 Execute；代码修改至少写 Goal 和 Done-when；高风险模块必须先 Plan。
模板也可能变成形式主义。如果每个任务都复制一大段模板但不填路径、命令和风险，效果不如短而具体的任务。模板的价值在具体化，不在长度。
另一个风险是把模板当成质量保证。模板能引导 Codex，但不能替代测试、review 和领域判断。性能数据、权限边界、账单规则、数据迁移仍要由负责人确认。
常见误区
误区一：理解代码任务允许顺手修。理解阶段要产出地图，不产出 diff。
误区二：重构任务没有行为保持证据。没有测试或快照时，先补护栏或缩小范围。
误区三：补测试只补能过的用例。应该覆盖边界、错误、权限、空数据、并发和历史回归。
误区四：性能优化没有基准。没有前后数据，优化结果无法判断。
误区五：模板不写停靠点。真正有用的是“先列文件”“先给计划”“发现 bug 先停下”“跑命令后汇报”这些停靠点。
团队落地：模板库的建设和迭代
工作流模板如果只存在于某个人的笔记里，很难形成团队能力。更好的做法是维护一个小型模板库，放在仓库文档或工程手册中，和 AGENTS.md 互相引用。模板库不需要很多，开始只保留四类：理解代码、行为保持型重构、补测试、性能优化。等团队真实使用后，再增加 CI 修复、PR review 处理、文档更新、依赖升级等模板。
模板库的第一条原则是少而精。每个模板都要有适用场景、默认授权、输入字段、停靠点、完成标准和失败处理。不要收集十几种看似华丽的 prompt。模板越多，开发者越不会选；模板越抽象，Codex 越不会按预期执行。
第二条原则是保留版本。模板会随着团队经验变化。比如一开始补测试模板允许 Codex 直接修生产代码，后来发现容易混杂 diff，就改成“测试暴露 bug 时先停下”。这些变化应进入版本历史或文档说明，让团队知道规则为什么改变。模板不是口号，而是从失败中提炼出的操作规程。
第三条原则是绑定验证。每个模板都要说明至少一种验证方式。理解代码模板的验证是人工核对关键文件和调用链；重构模板的验证是行为保持测试；补测试模板的验证是新测试覆盖风险；性能模板的验证是前后数据。没有验证方式的模板，只是更长的请求。
第四条原则是限定默认权限。模板开头应写清“默认不修改文件”或“允许在确认后修改”。理解模板默认只读，计划模板默认不执行，重构模板默认先计划，补测试模板默认优先只改测试，性能模板默认先测量。默认权限写清后，开发者就不需要每次重复解释。
第五条原则是把模板接入真实工具。Issue 模板可以提供下拉项选择“理解代码、补测试、修 bug、性能优化”；PR review bot 可以把评论转成四要素任务；Cloud 任务表单可以要求填写 Done-when；AGENTS.md 可以简述模板选择规则。模板只有进入入口，才会被稳定使用。
第六条原则是统计效果。团队可以记录每类模板的成功率、平均返工次数、常见失败原因、测试未运行比例。数据不需要复杂，哪怕只在复盘文档里记录，也能看出哪些模板需要调整。例如性能模板常失败，可能是缺少基准数据；重构模板常失败，可能是测试护栏不足。
第七条原则是保留人工判断。模板不能决定架构取舍，不能判断业务口径，不能替代 code owner。模板只是让 Codex 按正确顺序做事。遇到跨团队接口、生产数据、用户权限、合规要求时，模板应引导 Codex 停下，而不是假装可以自动完成。
最后，模板库要鼓励删减。某个模板长时间没人用，删掉。某个模板和另一个模板差异很小，合并。某条规则已经进入 AGENTS.md，从模板里删掉。好的模板库像工具箱，常用工具顺手可取，不常用工具不占位置。
反例分析：模板滥用也会制造失败
模板能提高一致性，但滥用模板会制造另一类问题。团队如果只会复制模板，不会根据任务调整，Codex 仍然会失败，只是失败文本更长。
第一种反例是模板字段空泛。Goal 写“提升质量”，Context 写“相关代码”，Constraints 写“遵守规范”，Done-when 写“完成即可”。这看起来用了模板，实际信息量接近零。模板不是表格样式，而是迫使你填入具体路径、风险、命令和验收。
第二种反例是所有任务都套同一个模板。理解代码、重构、补测试、性能优化需要不同停靠点。用重构模板处理性能问题，会缺基准；用补测试模板处理代码理解，会诱导修改文件。模板选择本身就是工程判断。
第三种反例是模板过重。修一个错别字也要求完整分析、计划、执行、复盘，开发者会很快放弃模板。模板库应支持轻量版本。低风险任务可以用短 brief，高风险任务再用完整模板。
第四种反例是模板没有和权限绑定。理解模板写了“不修改文件”，但实际运行在宽松写权限下；执行模板需要写文件，却运行在只读环境中。Prompt 和沙箱不匹配时，要么风险过大，要么任务卡住。模板应提示推荐权限。
第五种反例是模板忽略失败路径。比如补测试模板没写“测试暴露生产 bug 时停下”，Codex 可能直接修生产代码，导致任务范围扩大。每个模板都应写清遇到越界、失败、缺环境时怎样处理。
第六种反例是模板不更新。项目测试命令改了，模板还写旧命令；团队开始使用 Cloud，模板没写环境要求；新建高风险模块，模板没增加停靠点。模板库要跟项目实践同步，否则会成为过期规则来源。
第七种反例是模板和 AGENTS.md 冲突。模板允许引入依赖，项目规则禁止；模板要求全量测试，项目规则要求先跑局部测试。冲突会让 Codex 自行取舍。模板应引用项目规则，并只补本类任务的特殊流程。
第八种反例是模板缺少人工 review。有人以为用了模板就可以自动合并。模板只让 Codex 过程更清楚，不能替代 owner 判断。涉及接口、权限、账单、迁移、性能口径的任务，仍要人工确认。
解决模板滥用的方法是定期看产物，而不是看模板是否填写完整。挑几次 Codex 任务，问：模板是否让任务更清楚？是否减少返工？是否让验证更可信？如果没有，就修改或删除模板。模板的标准不是漂亮，而是减少实际失败。
模板选择清单
在派任务前，先判断任务类型。这个判断比模板文字本身更重要。
如果你想让 Codex 解释代码、找入口、梳理调用链、评估风险，用理解代码模板。这个模板默认只读，产物是地图。不要在同一个任务里要求它顺手修复。
如果你想降低复杂度、拆分函数、消除重复、调整内部结构，用行为保持型重构模板。这个模板必须写公共接口和测试护栏。没有测试时，先补测试或只做计划。
如果你想增加测试覆盖，用补测试模板。这个模板要先列风险，再写用例。若测试暴露生产 bug，默认停下说明。否则补测试任务会变成隐藏修复任务。
如果你想降低耗时、减少查询、优化内存或渲染，用性能优化模板。这个模板必须先有指标或要求 Codex 建立指标。没有数据时，不进入执行。
如果任务同时包含多类目标，优先拆分。例如“重构并补测试”可以先理解，再补测试护栏，再重构。“优化性能并修 bug”可以先确认 bug 是否导致性能问题，再决定路径。模板组合要有顺序，不要堆在一个 prompt 里。
如果任务属于安全、权限、账单、迁移、部署这类高风险领域，先套理解或计划模板，不要直接套执行模板。高风险任务的第一产物通常应该是事实和计划，而不是 diff。
如果任务低风险，例如文档链接、错别字、单个注释，可以不用完整模板。写清 Goal、文件范围和 Done-when 即可。模板不是为了增加仪式，而是为了控制风险。
模板选择做对后，Codex 的行为会更稳定。它会知道自己当前是在画地图、搭护栏、改实现，还是拿数据证明优化。工程任务的质量往往不取决于模型多会写，而取决于它被放在了正确流程里。
延伸阅读
GitHub 原文：06-common-workflow-templates.md