Codex 橙皮书 | AI 原生开放教材

第四篇：标准工作流

从需求到交付的完整链路

很多人刚开始用 Codex，会直接一句话丢给它：

帮我做一个网站。帮我改这个功能。帮我优化这个项目。

这样不是不行，但很容易出现一个问题： AI 改得很快，但你不知道它到底改了什么，也不知道能不能放心交付。

所以真正稳定的方式，不是让 Codex 一口气乱改，而是按照一套固定工作流来推进。

你可以把它理解成：

需求不是直接变成交付物，中间必须经过“理解、计划、修改、验证、检查、验收”这几步。

标准六步法

步骤	名称	简单来说	目的
1	需求拆解	先让 Codex 知道要做的项目是什么	避免不了解结构就乱改
2	制定计划	先列出要做什么，确认后再动手	避免一步改太多、方向跑偏
3	小步实现	一次只改一小块	降低出错概率，方便回滚
4	测试	改完后运行检查并手动验证	确认代码没有明显报错
5	代码审查	看 diff，检查改得对不对、有没有风险	防止 AI 改到不该改的地方
6	提交与复盘	提交代码并沉淀经验	AI 负责执行，人负责拍板

第一步：需求拆解

在让 Codex 修改项目之前，第一件事不是写代码，而是先拆需求。

很多人用 Codex 容易翻车，不是因为 Codex 不会写代码，而是因为一开始需求没说清楚。

比如你只说：

帮我优化首页。

Codex 可能会理解成：

改 UI
改文案
改布局
改组件结构
改路由
甚至顺手删掉一些它觉得“没用”的代码

所以在正式动手前，应该先把需求拆成几个关键问题。

背景是什么

先说明这个任务为什么要做。

问题	示例
现在项目处于什么阶段	这是一个已经上线的官网页面
当前遇到什么情况	首页转化率低，用户不知道产品卖点
为什么现在要改	准备发布新版，需要优化首屏表达
这个需求属于什么类型	UI 优化 / Bug 修复 / 新功能 / 重构

要解决什么问题

需求要尽量具体，不要只写“优化”“美化”“改好一点”。

模糊说法	更清楚的说法
优化首页	优化首页首屏标题、副标题和 CTA 按钮
页面不好看	调整卡片间距、字体层级和按钮样式
登录有问题	修复点击登录按钮后没有跳转的问题
做一个后台	新增用户列表页，包含搜索、筛选和分页

好的需求应该能回答：

这次到底要解决哪一个具体问题？

示例：

text

这次主要解决三个问题：
1. 首屏标题表达不清楚
2. CTA 按钮不明显
3. 移动端首屏内容太拥挤

哪些文件可能相关

如果你知道大概文件位置，最好提前告诉 Codex。

这样可以减少它全项目乱找、乱改的概率。

场景	可能相关文件
改首页	app/page.tsx、pages/index.tsx、components/Hero.tsx
改样式	globals.css、tailwind.config.js、相关组件文件
改登录	login/page.tsx、auth.ts、middleware.ts
改接口	api 目录、server 目录、lib 目录
改文案	页面组件、配置文件、i18n 文件

哪些功能不能动

这一点非常重要。

Codex 很容易为了完成当前任务，顺手改掉其他地方。

所以要提前告诉它：

不能动的内容	说明
登录逻辑	只改 UI，不改认证流程
接口地址	不要改 API 请求路径
数据结构	不要改数据库字段
路由结构	不要改已有页面路径
已有组件	除非必要，不要大规模重构
依赖版本	不要随便升级或新增依赖

这一步的核心是给 Codex 画边界。

什么结果算完成

不要只说“做完就行”，要告诉 Codex 什么叫完成。

需求类型	完成标准
UI 优化	页面视觉明显改善，移动端不乱
Bug 修复	原来的报错消失，相关功能可正常使用
新功能	用户能完整走通操作流程
性能优化	构建正常，页面加载没有明显变慢
文案优化	标题、副标题、按钮文案更清楚

示例：

text

完成标准：
1. 首页首屏能清楚表达产品用途
2. CTA 按钮更明显
3. 移动端显示正常
4. 不影响其他页面
5. 项目可以正常运行和构建

需要哪些测试

改完之后不能只看 Codex 说“完成了”，还要提前说明需要怎么验证。

测试类型	适用场景
页面预览	UI 修改、页面布局调整
控制台检查	前端页面、交互功能
构建测试	Next.js、React、Vue 项目
单元测试	有测试文件的项目
手动流程测试	登录、支付、表单、上传等流程
移动端测试	响应式页面、小红书首图、移动网页

有哪些风险

需求拆解时，还要提前让 Codex 判断风险。

这样它不会一边改一边乱试。

风险	说明
影响范围过大	小需求被改成大重构
样式污染	改了全局 CSS，影响其他页面
依赖风险	新增不必要依赖，项目变复杂
逻辑风险	为了修一个问题，改坏其他流程
数据风险	改接口、字段、数据库相关内容
兼容风险	桌面端正常，移动端出问题

需求拆解提示词模板

实际使用 Codex 时，可以直接复制这段：

text

请先帮我做需求拆解，不要立刻修改代码。

需求：
【这里写你的需求】

请按下面结构分析：

1. 背景是什么
- 当前项目大概是什么
- 为什么要做这个需求
- 这个需求属于新功能、Bug 修复、UI 优化，还是重构

2. 要解决什么问题
- 当前具体问题是什么
- 本次要解决到什么程度
- 哪些内容不是本次范围

3. 哪些文件可能相关
- 请根据项目结构判断可能涉及哪些文件
- 先列出来，不要直接修改

4. 哪些功能不能动
- 不要改哪些逻辑
- 不要动哪些接口
- 不要影响哪些页面或组件

5. 什么结果算完成
- 功能完成标准
- 页面完成标准
- 代码完成标准

6. 需要哪些测试
- 需要运行什么命令
- 需要手动检查哪些页面
- 需要重点验证哪些流程

7. 有哪些风险
- 可能影响哪些功能
- 是否有样式污染风险
- 是否有重构过度风险
- 是否有新增依赖风险

最后，请给我一个简短的执行建议：
- 建议先做哪一步
- 是否需要我确认后再修改

第二步：让 Codex 制定计划

需求拆解完成后，不要马上让 Codex 写代码。

这一步要让 Codex 先制定计划。

你可以把它理解成：

先让 AI 说清楚它准备怎么做，再决定要不要让它动手。

很多项目翻车，不是因为 Codex 不会改，而是因为它一上来就开始改。

等你发现方向不对时，它可能已经改了很多文件，回头检查和回滚都很麻烦。

所以第二步的核心是：

先计划，后执行。先确认，后修改。

先不要写代码

这一点要写在提示词最前面。

因为 Codex 的默认倾向是：看到需求后直接开始解决问题。

但在真实项目里，直接改代码风险很高。

直接写代码的问题	可能后果
没理解项目结构	改错文件
没确认需求边界	做了不该做的功能
没判断影响范围	误伤旧功能
没列测试方式	改完不知道怎么验收
一次改太多	出错后不好回滚

示例提示词：

text

先不要写代码，也不要修改任何文件。
请先根据当前需求和项目结构，制定一个修改计划。
等我确认后，再开始执行。

开启计划模式

可以参考前文 Codex App 基础使用里的「计划模式」小节。实际使用时，也可以直接在 Codex CLI 或 App 输入 /plan，先让 Codex 输出计划，再决定是否执行。

第三步：小步实现

计划确认后，才进入真正的代码修改阶段。

但这里有一个非常重要的原则：

不要让 Codex 一次性把所有东西都改完。

很多人用 Codex 翻车，就是因为一上来就让它“全部实现”。

结果它可能会同时改页面、改组件、改样式、改接口、改配置，最后项目虽然看起来变了，但你很难判断到底哪里出了问题。

所以更稳定的方式是：

一次只改一个功能点。改完一小步，就检查一小步。

一次只改一个功能点

小步实现的核心是控制修改范围。

比如你要优化首页，不要一次性说：

text

请帮我优化整个首页。

更推荐拆成这样：

步骤	修改内容
第一步	只优化首屏标题和副标题
第二步	只调整 CTA 按钮
第三步	只优化移动端布局
第四步	只补充产品卖点卡片
第五步	只处理最终样式细节

这样每一步都很清楚，出问题也容易定位。

不要让 Codex 顺手重构无关代码

Codex 有时候会觉得某些代码“不够优雅”，然后顺手帮你重构。

但真实项目里，顺手重构是很危险的。

Codex 的顺手操作	可能带来的问题
重命名组件	导致引用路径出错
拆分文件	增加维护成本
改全局样式	影响其他页面
优化旧逻辑	破坏原本可用功能
升级依赖	引发兼容问题
删除它认为无用的代码	实际可能是业务逻辑

所以在小步实现时，要明确限制：

text

本次只实现当前功能点。
不要顺手重构无关代码。
不要修改命名、目录结构、依赖版本和全局配置。
如果你发现代码可以优化，请先记录为建议，不要直接修改。

这句话很重要。

Codex 可以提建议，但不能私自扩大改动范围。

不要接受大面积无解释修改

如果 Codex 一次性改了很多文件，而且没有解释清楚原因，就要暂停。

尤其是看到这些情况时，要提高警惕：

情况	处理方式
改动文件数量突然很多	要求解释每个文件为什么改
删除了大量代码	要求说明删除原因
新增了不认识的依赖	要求说明必要性
修改了配置文件	要求说明影响范围
改了和需求无关的页面	要求回退无关修改
代码风格大变	要求保持原项目风格

遇到不确定先停下来问

小步实现不是让 Codex 什么都问，而是遇到关键不确定时必须停下来。

比如：

不确定情况	为什么要停
不确定该改哪个文件	防止改错位置
不确定业务规则	防止逻辑做错
不确定是否能删旧代码	防止误删功能
不确定是否新增依赖	防止项目复杂化
不确定接口含义	防止影响数据
不确定测试失败原因	防止越修越乱

可以提前给 Codex 加这条规则：

text

如果你遇到以下情况，请先停下来问我，不要自行决定：

1. 不确定该改哪个文件
2. 不确定是否要删除旧代码
3. 不确定是否要新增依赖
4. 不确定业务逻辑应该怎么处理
5. 不确定测试失败原因
6. 发现需要超出原计划的修改

小步实现提示词模板

实际使用时，可以直接复制下面这段：

text

请开始小步实现。

当前只执行第【1】步：
【这里写本次只做的一个功能点】

要求：
1. 一次只改这个功能点
2. 只修改和当前功能直接相关的文件
3. 不要顺手重构无关代码
4. 不要修改目录结构
5. 不要新增不必要依赖
6. 不要删除已有功能
7. 不要改计划外的文件

修改完成后请停止，并输出：

1. 本次修改了哪些文件
2. 每个文件改了什么
3. 为什么这些修改是必要的
4. 有没有改到计划外内容
5. 有没有潜在风险
6. 下一步建议做什么

注意：
如果遇到不确定的地方，请先停下来问我，不要自行决定。

第四步：测试

Codex 完成小步修改后，不能马上进入下一步，必须先测试。

很多人用 Codex 最大的问题是：

AI 说完成了，但项目其实没跑通。页面看起来正常，但某些功能已经坏了。当前功能修好了，旧功能却被影响了。

所以测试的核心是：不是相信 Codex 说「完成」，而是用结果证明它真的完成。

下面这张表覆盖了一次完整测试要做的事，按从快到慢的顺序执行即可：

测试类型	作用	常见命令	重点
单元测试	检查函数、组件、模块是否正常	`npm test` / `pnpm test` / `yarn test`	失败先说明原因，不要直接改代码
类型检查	TypeScript 项目提前发现类型错误	`npm run typecheck` / `tsc --noEmit`	没有该命令就明确说明
lint	检查代码规范问题（未使用变量、import 顺序、Hook 用法等）	`npm run lint`	区分本次新增问题和项目原有问题
构建	本地能打开不代表能上线，构建才说明能打包	`npm run build` / `pnpm build`	失败先总结报错和影响范围
手动测试	UI、表单、登录、支付、上传必须手动点一遍	——	按用户操作路径逐步验证
浏览器测试	终端看不出来的页面/控制台/接口问题	——	看页面显示、Console 报错、Network、移动端
回归测试	不只测新功能，还要测旧功能有没有被改坏	——	列出本次修改可能影响的旧页面和组件

两个提醒：很多老项目本身就有 lint 或类型问题，不要让 Codex 把历史问题都顺手重构；回归测试是最容易被小白忽略的一步——改了首页按钮，也可能影响复用同一组件的其他页面。

手动测试时，可以让 Codex 把验证步骤列成「操作—预期结果」表格，例如：

步骤	操作	预期结果
1	打开首页	页面正常加载
2	点击 CTA 按钮	跳转到注册页
3	缩小到手机宽度	页面不变形
4	打开控制台	没有明显红色报错

测试阶段提示词模板

实际使用时，可以直接复制这段：

text

请对本次修改进行测试，不要继续新增功能。

请按下面顺序执行或说明：

1. 单元测试
- 项目是否有单元测试
- 如果有，请运行测试命令
- 如果失败，请说明失败原因

2. 类型检查
- 项目是否有 typecheck 命令
- 如果有，请运行
- 如果没有，请说明

3. lint
- 运行 lint 检查
- 区分本次新增问题和项目原有问题

4. 构建
- 运行 build 命令
- 如果失败，请说明报错原因和影响范围

5. 手动测试
- 列出需要手动测试的页面
- 列出用户操作步骤
- 列出每一步预期结果

6. 浏览器测试
- 检查页面显示
- 检查控制台报错
- 检查移动端布局
- 检查关键按钮和交互

7. 回归测试
- 检查本次修改是否影响旧功能
- 列出可能受影响的页面、组件和流程

最后请输出测试总结：
- 哪些测试通过了
- 哪些测试失败了
- 失败原因是什么
- 是否可以进入下一步
- 是否需要先修复问题

第五步：代码审查

测试通过后，不代表这次修改就可以直接交付。

还需要做代码审查。

代码审查可以理解成：

不只是看代码能不能跑，还要看代码改得对不对、稳不稳、有没有风险。

Codex 写代码很快，但它也可能出现这些问题：

常见问题	说明
功能能跑，但逻辑不对	表面正常，真实业务流程有问题
改动太大	为了一个小需求，改了很多无关代码
误删旧逻辑	删除了看似没用、实际有用的代码
忽略边界条件	正常输入能用，异常输入就崩
安全问题	暴露密钥、权限判断错误、输入未校验
风格不统一	新代码和原项目写法不一致
可维护性差	临时写死、硬编码、后续不好改

所以代码审查不是可选项，而是 Codex 工作流里的关键一步。

两轮审查：Codex 自审 + 人工审查

第一轮先让 Codex 自查刚才的修改（目的不是完全相信它，而是让它先暴露明显问题），最好让它输出成表格：

检查项	结果	说明
是否改到计划外文件	否	只修改了首页相关组件
是否新增依赖	否	没有修改 package.json
是否删除旧逻辑	否	原有按钮跳转逻辑保留
是否存在风险	有	移动端按钮间距还需人工确认

第二轮人工审查。最终交付的人是你，不是 Codex。不要求每行都看懂，但要重点看 diff 的这几处：

审查重点	要看什么
文件范围	是否只改了该改的文件
修改 / 删除内容	是否符合计划、有没有删掉旧功能
命名和结构	是否和原项目风格一致
业务逻辑	是否符合真实需求（能跑 ≠ 逻辑对）
测试结果	是否真的跑过测试

涉及登录、支付、权限、数据库、鉴权等重要代码，建议再用第二个模型做交叉审查——一个模型写，另一个模型专门挑错（只改文案、轻微样式一般不必）。但第二个模型的建议同样不能全盘接受，它帮你发现问题，不替你做最终决定。

重点盯四类高风险问题

下面四类是 Codex 最容易出问题、也最该重点审的地方：

类别	常见问题	审查要点
边界条件	正常输入能用、异常输入就崩	空数据、接口失败、未登录、权限不足、移动端尺寸、重复点击
安全问题	涉及用户/接口/权限/支付/上传/数据库时	是否暴露密钥 token、权限判断是否缺失、输入是否校验、是否泄露敏感信息、接口是否有鉴权
是否误删	看似没用、实际有用的代码被删	重点看 diff 的删除内容；旧组件、注释、兼容代码、fallback、配置项都可能仍被依赖
业务逻辑	代码能跑但逻辑错（跳错页、价格算错、越权）	正常路径、异常路径、权限判断、是否覆盖了旧业务规则

看到大段删除但 Codex 没解释清楚，就不要直接接受。

代码审查提示词模板

实际使用时，可以直接复制这一段：

text

请对本次修改做代码审查，不要继续写代码。

请按下面结构审查：

1. Codex 自审
- 本次是否只改了计划内文件
- 是否有无关重构
- 是否有新增依赖
- 是否有硬编码
- 是否有误删旧逻辑

2. 修改范围审查
- 修改了哪些文件
- 每个文件为什么要改
- 是否存在计划外修改
- 是否有大面积无解释修改

3. 边界条件审查
- 空数据如何处理
- 接口失败如何处理
- 用户未登录如何处理
- 权限不足如何处理
- 重复点击如何处理
- 移动端是否可能异常

4. 安全问题审查
- 是否暴露密钥、token、账号密码
- 是否影响权限判断
- 是否缺少输入校验
- 是否可能泄露敏感信息
- 是否修改了接口鉴权逻辑

5. 删除内容审查
- 删除了哪些代码
- 删除原因是什么
- 是否确认没有其他地方依赖
- 是否可能影响旧功能

6. 业务逻辑审查
- 是否符合需求
- 正常流程是否正确
- 异常流程是否正确
- 是否影响旧业务规则
- 是否有不确定的业务假设

7. 审查结论
请最后给出结论：
- 可以继续
- 需要小修
- 需要回退部分修改
- 需要重新制定计划

注意：
只审查，不要继续修改代码。
如果发现问题，请先说明问题和建议，等我确认后再改。

第六步：提交与复盘

代码测试通过、审查完成后，最后一步不是简单地说“完成了”。

真正完整的 Codex 工作流，还需要做两件事：

第一，把这次修改正式提交。第二，把这次经验沉淀下来。

很多人用 Codex 只做到“代码能跑”，但没有提交说明、没有 PR 描述、没有记录问题、没有更新文档。

这样短期看没问题，长期就会出现一个麻烦：

每次都像第一次做。每次都要重新解释。每次都重复踩坑。

所以第六步的核心是：

交付不是结束，复盘才是下一次效率提升的开始。

生成 commit

当这次修改已经通过测试和审查后，就可以让 Codex 帮你生成 commit。

commit 不是随便写一句“update”就行，而是要说明这次到底改了什么。

好的 commit 应该能回答：

问题	说明
改了什么	本次提交的主要内容
为什么改	对应什么需求或问题
影响哪里	涉及哪些模块、页面或功能
是否通过测试	是否构建、lint、测试通过

常见 commit message 格式：

text

feat: add user profile page
fix: resolve login redirect issue
style: improve homepage responsive layout
refactor: simplify product card component
docs: update setup guide

如果是中文项目，也可以写成：

text

feat: 新增用户资料页
fix: 修复登录后跳转异常
style: 优化首页移动端布局
docs: 更新项目使用说明

写 PR

如果项目使用 GitHub、GitLab 或团队协作流程，提交后通常还要写 PR。

PR 的作用不是“走形式”，而是让别人快速知道：

PR 要说明什么	作用
这次做了什么	方便 reviewer 快速理解
为什么要做	说明需求背景
改了哪些地方	降低审查成本
怎么测试	证明不是随便改
有什么风险	提前暴露不确定点
需要重点看哪里	引导 reviewer 审查重点

一个好的 PR 描述可以这样写：

text

## 本次修改

- 优化首页首屏标题、副标题和 CTA 按钮
- 调整移动端首屏布局
- 保留原有跳转逻辑，没有修改接口和路由

## 测试结果

- npm run lint 通过
- npm run build 通过
- 手动检查首页桌面端和移动端显示正常
- 点击 CTA 按钮跳转正常

## 风险说明

- 本次涉及首页样式调整，需要重点确认移动端显示
- 没有新增依赖
- 没有修改登录、接口、数据库逻辑

记录问题

复盘时，要把这次过程中遇到的问题记录下来。

这一步非常重要。

因为 Codex 工作流里，真正有价值的不是“这次做完了”，而是：

下次遇到类似问题，可以少走弯路。

需要记录的问题包括：

问题类型	示例
需求问题	一开始需求描述不够清楚
计划问题	Codex 计划里漏掉了移动端
修改问题	Codex 顺手改了无关组件
测试问题	项目没有 typecheck 命令
审查问题	发现它误删了 fallback 逻辑
沟通问题	提示词没有明确“不要新增依赖”

记录格式可以很简单：

text

本次问题记录：

1. 问题：Codex 一开始想修改全局样式
   原因：需求里没有明确限制“只改首页”
   解决：补充提示词，要求只修改首页相关文件

2. 问题：移动端测试遗漏
   原因：计划阶段没有列移动端验收标准
   解决：以后在测试清单里固定加入移动端检查

3. 问题：PR 描述不够清楚
   原因：没有提前记录测试结果
   解决：每次测试后直接生成测试总结

总结 Prompt

如果这次使用的提示词效果不错，就应该把它沉淀下来。

这一步的目的很简单：

好用的 Prompt，不要每次重新写。

比如这次你发现下面这句话很有用：

text

不要顺手重构无关代码。
如果发现需要超出计划的修改，请先停下来问我。

那就应该记录下来，以后作为固定规则使用。

可以整理成表格：

有效 Prompt	适用场景	为什么有效
先不要写代码，先制定计划	所有复杂需求	防止 Codex 直接乱改
一次只改一个功能点	多步骤任务	降低出错和回滚成本
不要顺手重构无关代码	老项目维护	防止改动范围扩大
修改完成后总结 diff	每次修改后	方便人工审查
不确定先停下来问	业务逻辑不清楚时	防止 AI 自作主张

更新 AGENTS.md

如果某些规则以后每次都要遵守，就不要只写在聊天里，最好更新到项目级 AGENTS.md。

AGENTS.md 可以理解成：

写给 Codex 的项目规则说明书。

它可以告诉 Codex：

内容	作用
项目怎么运行	让 Codex 知道启动、测试、构建命令
代码风格是什么	避免生成不符合项目风格的代码
哪些目录不能动	防止误改核心文件
修改前要怎么做	固定“先计划后执行”
测试要求是什么	改完必须跑哪些检查
提交要求是什么	commit 和 PR 怎么写

示例内容：

text

# AGENTS.md

## 工作规则

- 修改前必须先阅读项目结构。
- 修改前必须先制定计划，不要直接写代码。
- 一次只实现一个功能点。
- 不要顺手重构无关代码。
- 不要新增不必要依赖。
- 不确定业务逻辑时，先提问，不要自行决定。

## 测试要求

每次修改后至少检查：

- npm run lint
- npm run build
- 相关页面手动测试
- 浏览器控制台是否有报错
- 移动端布局是否正常

## 提交要求

提交前需要说明：

- 修改了哪些文件
- 每个文件改了什么
- 测试是否通过
- 是否有风险或未完成事项

更新项目文档

除了 AGENTS.md，如果这次修改影响了项目使用方式，也要更新项目文档。

比如：

修改内容	需要更新的文档
新增功能	README、功能说明
新增环境变量	.env.example、部署文档
新增命令	README、开发指南
修改接口	API 文档
修改部署流程	部署说明
修改配置	配置说明
新增组件	组件使用说明

文档更新不是为了好看，而是为了避免以后忘记。

常见文档包括：

文件	作用
README.md	项目介绍、启动方式、常用命令
.env.example	环境变量示例
docs/	详细项目文档
CHANGELOG.md	版本更新记录
AGENTS.md	Codex 工作规则
CONTRIBUTING.md	团队协作规范

提交与复盘提示词模板

实际使用时，可以直接复制下面这段：

text

请进入提交与复盘阶段，不要继续新增功能。

请按下面结构输出：

1. Commit 建议
- 生成一个合适的 commit message
- 使用 conventional commit 格式
- 不要夸大本次修改范围

2. PR 描述
请生成 PR 内容，包括：
- 本次修改
- 修改原因
- 涉及文件
- 测试结果
- 风险说明
- reviewer 需要重点看的地方

3. 问题记录
请复盘本次过程：
- 遇到了哪些问题
- 原因是什么
- 如何解决
- 下次如何避免

4. Prompt 总结
请总结：
- 哪些 Prompt 有效
- 为什么有效
- 适合什么场景复用
- 是否建议加入 AGENTS.md

5. AGENTS.md 更新建议
请输出适合加入 AGENTS.md 的长期规则：
- 修改前规则
- 修改中规则
- 测试规则
- 提交规则

6. 项目文档更新建议
请判断是否需要更新：
- README.md
- .env.example
- docs/
- CHANGELOG.md
- 其他项目文档

最后请给出交付结论：
- 是否可以提交
- 是否可以发 PR
- 是否还有未完成事项
- 是否有需要人工确认的风险

Codex 任务模板库

前面讲的是 Codex 的标准工作流。

这一节直接放一些常用模板，方便以后复制使用。

这些模板的作用是：

不用每次重新想 Prompt，直接按场景复制，然后填入自己的需求。

读项目模板

这个模板适合在刚打开一个新项目时使用。

尤其是你第一次让 Codex 接触某个项目，不要一上来就让它改代码。

更稳的方式是：先让它读项目，输出一份项目理解报告。

这样你可以先判断：

检查点	作用
Codex 是否看懂项目	防止一上来改错文件
技术栈是否判断正确	确认它知道项目用的是什么框架
启动方式是否清楚	后面测试和运行更顺
核心模块是否找对	后续修改不会乱找方向
风险是否提前暴露	避免误改核心逻辑

读项目模板（可直接复制）

text

请先不要修改任何代码。

请阅读当前项目，并输出一份项目理解报告，包括：

1. 技术栈
- 项目使用了哪些主要技术
- 前端/后端/数据库/构建工具分别是什么
- 是否使用 TypeScript、Tailwind、框架或组件库

2. 目录结构
- 主要目录分别负责什么
- 页面、组件、工具函数、接口、配置文件分别在哪里
- 哪些目录是核心目录，哪些目录不建议随便改

3. 启动方式
- 项目如何安装依赖
- 项目如何本地启动
- 是否需要环境变量
- 如果 README 里有说明，请优先参考 README

4. 测试命令
- 项目是否有 test 命令
- 是否有 lint 命令
- 是否有 typecheck 命令
- 是否有 build 命令
- 如果没有相关命令，请明确说明

5. 核心模块
- 项目的核心功能模块有哪些
- 每个模块大概负责什么
- 如果后续要修改功能，应该优先查看哪些文件

6. 后续修改风险
- 哪些文件或目录改动风险较高
- 哪些逻辑不能随便改
- 是否存在全局样式、全局配置、鉴权、接口、数据库等高风险区域
- 后续修改时需要特别注意什么

请只输出项目理解报告，不要修改代码。
输出完成后等待我确认。

修 Bug 模板

我遇到一个 bug：

【现象】
【复现步骤】
【期望结果】
【实际结果】
【相关文件/页面】

请先定位原因，不要直接修改。

先给出：

可能原因
需要查看的文件
修复方案
风险点等我确认后再改代码。

加功能模板

我想新增一个功能：

【功能描述】
【入口位置】
【交互流程】
【视觉要求】
【数据来源】
【验收标准】

请先阅读相关代码，给出实现计划。

不要改无关文件。

实现后请运行测试并总结 diff。

前端页面模板

请根据下面要求实现一个页面：

【页面用途】
【目标用户】
【视觉风格】
【模块结构】
【中文文案】
【响应式要求】
【不要出现的问题】

请先给出组件拆分方案，再开始实现。

代码审查模板

请审查当前分支相对 main 的 diff。

重点检查：

潜在 bug
边界条件
安全风险
类型问题
性能问题
是否有无关修改
测试是否充分请不要直接修改代码，先输出 review 报告。

重构模板

请重构以下模块：

【模块路径】

目标是：

提高可读性
减少重复代码
保持现有行为不变
不改变公共 API
不引入新依赖请先写重构计划，并说明如何验证行为一致。

写测试模板

请为以下功能补充测试：

【功能描述】
【相关文件】
【边界情况】

要求：

不改业务逻辑
覆盖正常路径
覆盖异常路径
覆盖边界条件
运行测试并报告结果。

写文档模板

请根据当前项目生成文档：

项目简介
安装方式
启动方式
环境变量说明
常用命令
目录结构
开发注意事项
常见问题请不要编造不存在的命令，必须基于项目文件判断。

第四篇：标准工作流 ​

从需求到交付的完整链路 ​

标准六步法 ​

第一步：需求拆解 ​

背景是什么 ​

要解决什么问题 ​

哪些文件可能相关 ​

哪些功能不能动 ​

什么结果算完成 ​

需要哪些测试 ​

有哪些风险 ​

需求拆解提示词模板 ​

第二步：让 Codex 制定计划 ​

先不要写代码 ​

开启计划模式 ​

第三步：小步实现 ​

一次只改一个功能点 ​

不要让 Codex 顺手重构无关代码 ​

不要接受大面积无解释修改 ​

遇到不确定先停下来问 ​

小步实现提示词模板 ​

第四步：测试 ​

测试阶段提示词模板 ​

第五步：代码审查 ​

两轮审查：Codex 自审 + 人工审查 ​

重点盯四类高风险问题 ​

代码审查提示词模板 ​

第六步：提交与复盘 ​

生成 commit ​

写 PR ​

记录问题 ​

总结 Prompt ​

更新 AGENTS.md ​

更新项目文档 ​

提交与复盘提示词模板 ​

Codex 任务模板库 ​

读项目模板 ​

读项目模板（可直接复制） ​

修 Bug 模板 ​

加功能模板 ​

前端页面模板 ​

代码审查模板 ​

重构模板 ​

写测试模板 ​

写文档模板 ​

第四篇：标准工作流

从需求到交付的完整链路

标准六步法

第一步：需求拆解

背景是什么

要解决什么问题

哪些文件可能相关

哪些功能不能动

什么结果算完成

需要哪些测试

有哪些风险

需求拆解提示词模板

第二步：让 Codex 制定计划

先不要写代码

开启计划模式

第三步：小步实现

一次只改一个功能点

不要让 Codex 顺手重构无关代码

不要接受大面积无解释修改

遇到不确定先停下来问

小步实现提示词模板

第四步：测试

测试阶段提示词模板

第五步：代码审查

两轮审查：Codex 自审 + 人工审查

重点盯四类高风险问题

代码审查提示词模板

第六步：提交与复盘

生成 commit

写 PR

记录问题

总结 Prompt

更新 AGENTS.md

更新项目文档

提交与复盘提示词模板

Codex 任务模板库

读项目模板

读项目模板（可直接复制）

修 Bug 模板

加功能模板

前端页面模板

代码审查模板

重构模板

写测试模板

写文档模板