标准工作流：从需求到交付的完整链路
从零开始掌握 OpenAI Codex——AI 编程工程 Agent。14 章覆盖认识 Codex、四种入口安装、核心功能（自动化/插件/Skill/MCP/Git/记忆）、标准工作流、实战案例和第三方模型接入。
一句话结论
标准工作流 = 需求理解 → 读项目 → 出计划 → 改代码 → 跑测试 → 看 diff → 写 PR；任务必须拆小，每一步都要可验证。
第四篇：标准工作流
从需求到交付的完整链路
很多人刚开始用 Codex，会直接一句话丢给它：
帮我做一个网站。 帮我改这个功能。 帮我优化这个项目。
这样不是不行，但很容易出现一个问题： AI 改得很快，但你不知道它到底改了什么，也不知道能不能放心交付。
所以真正稳定的方式，不是让 Codex 一口气乱改，而是按照一套固定工作流来推进。
你可以把它理解成：
需求不是直接变成交付物，中间必须经过“理解、计划、修改、验证、检查、验收”这几步。
标准六步法
| 步骤 | 名称 | 简单来说 | 目的 |
|---|---|---|---|
| 1 | 需求拆解 | 先让 Codex 知道要做的项目是什么 | 避免不了解结构就乱改 |
| 2 | 制定计划 | 先列出要做什么，确认后再动手 | 避免一步改太多、方向跑偏 |
| 3 | 小步实现 | 一次只改一小块 | 降低出错概率，方便回滚 |
| 4 | 测试 | 改完后运行检查并手动验证 | 确认代码没有明显报错 |
| 5 | 代码审查 | 看 diff，检查改得对不对、有没有风险 | 防止 AI 改到不该改的地方 |
| 6 | 提交与复盘 | 提交代码并沉淀经验 | AI 负责执行，人负责拍板 |
第一步：需求拆解
在让 Codex 修改项目之前，第一件事不是写代码，而是先拆需求。
很多人用 Codex 容易翻车，不是因为 Codex 不会写代码，而是因为一开始需求没说清楚。
比如你只说：
帮我优化首页。
Codex 可能会理解成：
- 改 UI
- 改文案
- 改布局
- 改组件结构
- 改路由
- 甚至顺手删掉一些它觉得“没用”的代码
所以在正式动手前，应该先把需求拆成几个关键问题。
背景是什么
先说明这个任务为什么要做。
| 问题 | 示例 |
|---|---|
| 现在项目处于什么阶段 | 这是一个已经上线的官网页面 |
| 当前遇到什么情况 | 首页转化率低，用户不知道产品卖点 |
| 为什么现在要改 | 准备发布新版，需要优化首屏表达 |
| 这个需求属于什么类型 | UI 优化 / Bug 修复 / 新功能 / 重构 |
要解决什么问题
需求要尽量具体，不要只写“优化”“美化”“改好一点”。
| 模糊说法 | 更清楚的说法 |
|---|---|
| 优化首页 | 优化首页首屏标题、副标题和 CTA 按钮 |
| 页面不好看 | 调整卡片间距、字体层级和按钮样式 |
| 登录有问题 | 修复点击登录按钮后没有跳转的问题 |
| 做一个后台 | 新增用户列表页，包含搜索、筛选和分页 |
好的需求应该能回答：
这次到底要解决哪一个具体问题？
示例：
[code]
这次主要解决三个问题：
1. 首屏标题表达不清楚
2. CTA 按钮不明显
3. 移动端首屏内容太拥挤
[/code]
哪些文件可能相关
如果你知道大概文件位置，最好提前告诉 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 修复 | 原来的报错消失，相关功能可正常使用 |
| 新功能 | 用户能完整走通操作流程 |
| 性能优化 | 构建正常，页面加载没有明显变慢 |
| 文案优化 | 标题、副标题、按钮文案更清楚 |
示例：
[code]
完成标准：
1. 首页首屏能清楚表达产品用途
2. CTA 按钮更明显
3. 移动端显示正常
4. 不影响其他页面
5. 项目可以正常运行和构建
[/code]
需要哪些测试
改完之后不能只看 Codex 说“完成了”，还要提前说明需要怎么验证。
| 测试类型 | 适用场景 |
|---|---|
| 页面预览 | UI 修改、页面布局调整 |
| 控制台检查 | 前端页面、交互功能 |
| 构建测试 | Next.js、React、Vue 项目 |
| 单元测试 | 有测试文件的项目 |
| 手动流程测试 | 登录、支付、表单、上传等流程 |
| 移动端测试 | 响应式页面、小红书首图、移动网页 |
有哪些风险
需求拆解时，还要提前让 Codex 判断风险。
这样它不会一边改一边乱试。
| 风险 | 说明 |
|---|---|
| 影响范围过大 | 小需求被改成大重构 |
| 样式污染 | 改了全局 CSS，影响其他页面 |
| 依赖风险 | 新增不必要依赖，项目变复杂 |
| 逻辑风险 | 为了修一个问题，改坏其他流程 |
| 数据风险 | 改接口、字段、数据库相关内容 |
| 兼容风险 | 桌面端正常，移动端出问题 |
需求拆解提示词模板
实际使用 Codex 时，可以直接复制这段：
[code]
请先帮我做需求拆解，不要立刻修改代码。
需求：
【这里写你的需求】
请按下面结构分析：
1. 背景是什么
- 当前项目大概是什么
- 为什么要做这个需求
- 这个需求属于新功能、Bug 修复、UI 优化，还是重构
2. 要解决什么问题
- 当前具体问题是什么
- 本次要解决到什么程度
- 哪些内容不是本次范围
3. 哪些文件可能相关
- 请根据项目结构判断可能涉及哪些文件
- 先列出来，不要直接修改
4. 哪些功能不能动
- 不要改哪些逻辑
- 不要动哪些接口
- 不要影响哪些页面或组件
5. 什么结果算完成
- 功能完成标准
- 页面完成标准
- 代码完成标准
6. 需要哪些测试
- 需要运行什么命令
- 需要手动检查哪些页面
- 需要重点验证哪些流程
7. 有哪些风险
- 可能影响哪些功能
- 是否有样式污染风险
- 是否有重构过度风险
- 是否有新增依赖风险
最后，请给我一个简短的执行建议：
- 建议先做哪一步
- 是否需要我确认后再修改
[/code]
第二步：让 Codex 制定计划
需求拆解完成后，不要马上让 Codex 写代码。
这一步要让 Codex 先制定计划。
你可以把它理解成：
先让 AI 说清楚它准备怎么做，再决定要不要让它动手。
很多项目翻车，不是因为 Codex 不会改，而是因为它一上来就开始改。
等你发现方向不对时，它可能已经改了很多文件，回头检查和回滚都很麻烦。
所以第二步的核心是：
先计划，后执行。 先确认，后修改。
先不要写代码
这一点要写在提示词最前面。
因为 Codex 的默认倾向是：看到需求后直接开始解决问题。
但在真实项目里，直接改代码风险很高。
| 直接写代码的问题 | 可能后果 |
|---|---|
| 没理解项目结构 | 改错文件 |
| 没确认需求边界 | 做了不该做的功能 |
| 没判断影响范围 | 误伤旧功能 |
| 没列测试方式 | 改完不知道怎么验收 |
| 一次改太多 | 出错后不好回滚 |
示例提示词：
[code]
先不要写代码，也不要修改任何文件。
请先根据当前需求和项目结构，制定一个修改计划。
等我确认后，再开始执行。
[/code]
开启计划模式
可以参考前文 Codex App 基础使用里的「计划模式」小节。实际使用时，也可以直接在 Codex CLI 或 App 输入 /plan，先让 Codex 输出计划，再决定是否执行。
第三步：小步实现
计划确认后，才进入真正的代码修改阶段。
但这里有一个非常重要的原则：
不要让 Codex 一次性把所有东西都改完。
很多人用 Codex 翻车，就是因为一上来就让它“全部实现”。
结果它可能会同时改页面、改组件、改样式、改接口、改配置，最后项目虽然看起来变了，但你很难判断到底哪里出了问题。
所以更稳定的方式是：
一次只改一个功能点。 改完一小步，就检查一小步。
一次只改一个功能点
小步实现的核心是控制修改范围。
比如你要优化首页，不要一次性说：
[code]
请帮我优化整个首页。
[/code]
更推荐拆成这样：
| 步骤 | 修改内容 |
|---|---|
| 第一步 | 只优化首屏标题和副标题 |
| 第二步 | 只调整 CTA 按钮 |
| 第三步 | 只优化移动端布局 |
| 第四步 | 只补充产品卖点卡片 |
| 第五步 | 只处理最终样式细节 |
这样每一步都很清楚，出问题也容易定位。
不要让 Codex 顺手重构无关代码
Codex 有时候会觉得某些代码“不够优雅”，然后顺手帮你重构。
但真实项目里，顺手重构是很危险的。
| Codex 的顺手操作 | 可能带来的问题 |
|---|---|
| 重命名组件 | 导致引用路径出错 |
| 拆分文件 | 增加维护成本 |
| 改全局样式 | 影响其他页面 |
| 优化旧逻辑 | 破坏原本可用功能 |
| 升级依赖 | 引发兼容问题 |
| 删除它认为无用的代码 | 实际可能是业务逻辑 |
所以在小步实现时，要明确限制：
[code]
本次只实现当前功能点。
不要顺手重构无关代码。
不要修改命名、目录结构、依赖版本和全局配置。
如果你发现代码可以优化，请先记录为建议，不要直接修改。
[/code]
这句话很重要。
Codex 可以提建议，但不能私自扩大改动范围。
不要接受大面积无解释修改
如果 Codex 一次性改了很多文件，而且没有解释清楚原因，就要暂停。
尤其是看到这些情况时，要提高警惕：
| 情况 | 处理方式 |
|---|---|
| 改动文件数量突然很多 | 要求解释每个文件为什么改 |
| 删除了大量代码 | 要求说明删除原因 |
| 新增了不认识的依赖 | 要求说明必要性 |
| 修改了配置文件 | 要求说明影响范围 |
| 改了和需求无关的页面 | 要求回退无关修改 |
| 代码风格大变 | 要求保持原项目风格 |
遇到不确定先停下来问
小步实现不是让 Codex 什么都问，而是遇到关键不确定时必须停下来。
比如：
| 不确定情况 | 为什么要停 |
|---|---|
| 不确定该改哪个文件 | 防止改错位置 |
| 不确定业务规则 | 防止逻辑做错 |
| 不确定是否能删旧代码 | 防止误删功能 |
| 不确定是否新增依赖 | 防止项目复杂化 |
| 不确定接口含义 | 防止影响数据 |
| 不确定测试失败原因 | 防止越修越乱 |
可以提前给 Codex 加这条规则：
[code]
如果你遇到以下情况，请先停下来问我，不要自行决定：
1. 不确定该改哪个文件
2. 不确定是否要删除旧代码
3. 不确定是否要新增依赖
4. 不确定业务逻辑应该怎么处理
5. 不确定测试失败原因
6. 发现需要超出原计划的修改
[/code]
小步实现提示词模板
实际使用时，可以直接复制下面这段：
[code]
请开始小步实现。
当前只执行第【1】步：
【这里写本次只做的一个功能点】
要求：
1. 一次只改这个功能点
2. 只修改和当前功能直接相关的文件
3. 不要顺手重构无关代码
4. 不要修改目录结构
5. 不要新增不必要依赖
6. 不要删除已有功能
7. 不要改计划外的文件
修改完成后请停止，并输出：
1. 本次修改了哪些文件
2. 每个文件改了什么
3. 为什么这些修改是必要的
4. 有没有改到计划外内容
5. 有没有潜在风险
6. 下一步建议做什么
注意：
如果遇到不确定的地方，请先停下来问我，不要自行决定。
[/code]
第四步：测试
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 | 打开控制台 | 没有明显红色报错 |
测试阶段提示词模板
实际使用时，可以直接复制这段：
[code]
请对本次修改进行测试，不要继续新增功能。
请按下面顺序执行或说明：
1. 单元测试
- 项目是否有单元测试
- 如果有，请运行测试命令
- 如果失败，请说明失败原因
2. 类型检查
- 项目是否有 typecheck 命令
- 如果有，请运行
- 如果没有，请说明
3. lint
- 运行 lint 检查
- 区分本次新增问题和项目原有问题
4. 构建
- 运行 build 命令
- 如果失败，请说明报错原因和影响范围
5. 手动测试
- 列出需要手动测试的页面
- 列出用户操作步骤
- 列出每一步预期结果
6. 浏览器测试
- 检查页面显示
- 检查控制台报错
- 检查移动端布局
- 检查关键按钮和交互
7. 回归测试
- 检查本次修改是否影响旧功能
- 列出可能受影响的页面、组件和流程
最后请输出测试总结：
- 哪些测试通过了
- 哪些测试失败了
- 失败原因是什么
- 是否可以进入下一步
- 是否需要先修复问题
[/code]
第五步：代码审查
测试通过后，不代表这次修改就可以直接交付。
还需要做代码审查。
代码审查可以理解成：
不只是看代码能不能跑，还要看代码改得对不对、稳不稳、有没有风险。
Codex 写代码很快，但它也可能出现这些问题：
| 常见问题 | 说明 |
|---|---|
| 功能能跑，但逻辑不对 | 表面正常，真实业务流程有问题 |
| 改动太大 | 为了一个小需求，改了很多无关代码 |
| 误删旧逻辑 | 删除了看似没用、实际有用的代码 |
| 忽略边界条件 | 正常输入能用，异常输入就崩 |
| 安全问题 | 暴露密钥、权限判断错误、输入未校验 |
| 风格不统一 | 新代码和原项目写法不一致 |
| 可维护性差 | 临时写死、硬编码、后续不好改 |
所以代码审查不是可选项，而是 Codex 工作流里的关键一步。
两轮审查：Codex 自审 + 人工审查
第一轮先让 Codex 自查刚才的修改（目的不是完全相信它，而是让它先暴露明显问题），最好让它输出成表格：
| 检查项 | 结果 | 说明 |
|---|---|---|
| 是否改到计划外文件 | 否 | 只修改了首页相关组件 |
| 是否新增依赖 | 否 | 没有修改 package.json |
| 是否删除旧逻辑 | 否 | 原有按钮跳转逻辑保留 |
| 是否存在风险 | 有 | 移动端按钮间距还需人工确认 |
第二轮人工审查。最终交付的人是你，不是 Codex。不要求每行都看懂，但要重点看 diff 的这几处：
| 审查重点 | 要看什么 |
|---|---|
| 文件范围 | 是否只改了该改的文件 |
| 修改 / 删除内容 | 是否符合计划、有没有删掉旧功能 |
| 命名和结构 | 是否和原项目风格一致 |
| 业务逻辑 | 是否符合真实需求（能跑 ≠ 逻辑对） |
| 测试结果 | 是否真的跑过测试 |
涉及登录、支付、权限、数据库、鉴权等重要代码，建议再用第二个模型做交叉审查——一个模型写，另一个模型专门挑错（只改文案、轻微样式一般不必）。但第二个模型的建议同样不能全盘接受，它帮你发现问题，不替你做最终决定。
重点盯四类高风险问题
下面四类是 Codex 最容易出问题、也最该重点审的地方：
| 类别 | 常见问题 | 审查要点 |
|---|---|---|
| 边界条件 | 正常输入能用、异常输入就崩 | 空数据、接口失败、未登录、权限不足、移动端尺寸、重复点击 |
| 安全问题 | 涉及用户/接口/权限/支付/上传/数据库时 | 是否暴露密钥 token、权限判断是否缺失、输入是否校验、是否泄露敏感信息、接口是否有鉴权 |
| 是否误删 | 看似没用、实际有用的代码被删 | 重点看 diff 的删除内容；旧组件、注释、兼容代码、fallback、配置项都可能仍被依赖 |
| 业务逻辑 | 代码能跑但逻辑错（跳错页、价格算错、越权） | 正常路径、异常路径、权限判断、是否覆盖了旧业务规则 |
看到大段删除但 Codex 没解释清楚，就不要直接接受。
代码审查提示词模板
实际使用时，可以直接复制这一段：
[code]
请对本次修改做代码审查，不要继续写代码。
请按下面结构审查：
1. Codex 自审
- 本次是否只改了计划内文件
- 是否有无关重构
- 是否有新增依赖
- 是否有硬编码
- 是否有误删旧逻辑
2. 修改范围审查
- 修改了哪些文件
- 每个文件为什么要改
- 是否存在计划外修改
- 是否有大面积无解释修改
3. 边界条件审查
- 空数据如何处理
- 接口失败如何处理
- 用户未登录如何处理
- 权限不足如何处理
- 重复点击如何处理
- 移动端是否可能异常
4. 安全问题审查
- 是否暴露密钥、token、账号密码
- 是否影响权限判断
- 是否缺少输入校验
- 是否可能泄露敏感信息
- 是否修改了接口鉴权逻辑
5. 删除内容审查
- 删除了哪些代码
- 删除原因是什么
- 是否确认没有其他地方依赖
- 是否可能影响旧功能
6. 业务逻辑审查
- 是否符合需求
- 正常流程是否正确
- 异常流程是否正确
- 是否影响旧业务规则
- 是否有不确定的业务假设
7. 审查结论
请最后给出结论：
- 可以继续
- 需要小修
- 需要回退部分修改
- 需要重新制定计划
注意：
只审查，不要继续修改代码。
如果发现问题，请先说明问题和建议，等我确认后再改。
[/code]
第六步：提交与复盘
代码测试通过、审查完成后，最后一步不是简单地说“完成了”。
真正完整的 Codex 工作流，还需要做两件事：
第一，把这次修改正式提交。 第二，把这次经验沉淀下来。
很多人用 Codex 只做到“代码能跑”，但没有提交说明、没有 PR 描述、没有记录问题、没有更新文档。
这样短期看没问题，长期就会出现一个麻烦：
每次都像第一次做。 每次都要重新解释。 每次都重复踩坑。
所以第六步的核心是：
交付不是结束，复盘才是下一次效率提升的开始。
生成 commit
当这次修改已经通过测试和审查后，就可以让 Codex 帮你生成 commit。
commit 不是随便写一句“update”就行，而是要说明这次到底改了什么。
好的 commit 应该能回答：
| 问题 | 说明 |
|---|---|
| 改了什么 | 本次提交的主要内容 |
| 为什么改 | 对应什么需求或问题 |
| 影响哪里 | 涉及哪些模块、页面或功能 |
| 是否通过测试 | 是否构建、lint、测试通过 |
常见 commit message 格式：
[code]
feat: add user profile page
fix: resolve login redirect issue
style: improve homepage responsive layout
refactor: simplify product card component
docs: update setup guide
[/code]
如果是中文项目，也可以写成：
[code]
feat: 新增用户资料页
fix: 修复登录后跳转异常
style: 优化首页移动端布局
docs: 更新项目使用说明
[/code]
写 PR
如果项目使用 GitHub、GitLab 或团队协作流程，提交后通常还要写 PR。
PR 的作用不是“走形式”，而是让别人快速知道：
| PR 要说明什么 | 作用 |
|---|---|
| 这次做了什么 | 方便 reviewer 快速理解 |
| 为什么要做 | 说明需求背景 |
| 改了哪些地方 | 降低审查成本 |
| 怎么测试 | 证明不是随便改 |
| 有什么风险 | 提前暴露不确定点 |
| 需要重点看哪里 | 引导 reviewer 审查重点 |
一个好的 PR 描述可以这样写：
[code]
## 本次修改
- 优化首页首屏标题、副标题和 CTA 按钮
- 调整移动端首屏布局
- 保留原有跳转逻辑，没有修改接口和路由
## 测试结果
- npm run lint 通过
- npm run build 通过
- 手动检查首页桌面端和移动端显示正常
- 点击 CTA 按钮跳转正常
## 风险说明
- 本次涉及首页样式调整，需要重点确认移动端显示
- 没有新增依赖
- 没有修改登录、接口、数据库逻辑
[/code]
记录问题
复盘时，要把这次过程中遇到的问题记录下来。
这一步非常重要。
因为 Codex 工作流里，真正有价值的不是“这次做完了”，而是：
下次遇到类似问题，可以少走弯路。
需要记录的问题包括：
| 问题类型 | 示例 |
|---|---|
| 需求问题 | 一开始需求描述不够清楚 |
| 计划问题 | Codex 计划里漏掉了移动端 |
| 修改问题 | Codex 顺手改了无关组件 |
| 测试问题 | 项目没有 typecheck 命令 |
| 审查问题 | 发现它误删了 fallback 逻辑 |
| 沟通问题 | 提示词没有明确“不要新增依赖” |
记录格式可以很简单：
[code]
本次问题记录：
1. 问题：Codex 一开始想修改全局样式
原因：需求里没有明确限制“只改首页”
解决：补充提示词，要求只修改首页相关文件
2. 问题：移动端测试遗漏
原因：计划阶段没有列移动端验收标准
解决：以后在测试清单里固定加入移动端检查
3. 问题：PR 描述不够清楚
原因：没有提前记录测试结果
解决：每次测试后直接生成测试总结
[/code]
总结 Prompt
如果这次使用的提示词效果不错，就应该把它沉淀下来。
这一步的目的很简单：
好用的 Prompt，不要每次重新写。
比如这次你发现下面这句话很有用：
[code]
不要顺手重构无关代码。
如果发现需要超出计划的修改，请先停下来问我。
[/code]
那就应该记录下来，以后作为固定规则使用。
可以整理成表格：
| 有效 Prompt | 适用场景 | 为什么有效 |
|---|---|---|
| 先不要写代码，先制定计划 | 所有复杂需求 | 防止 Codex 直接乱改 |
| 一次只改一个功能点 | 多步骤任务 | 降低出错和回滚成本 |
| 不要顺手重构无关代码 | 老项目维护 | 防止改动范围扩大 |
| 修改完成后总结 diff | 每次修改后 | 方便人工审查 |
| 不确定先停下来问 | 业务逻辑不清楚时 | 防止 AI 自作主张 |
更新 AGENTS.md
如果某些规则以后每次都要遵守，就不要只写在聊天里，最好更新到项目级 AGENTS.md。
AGENTS.md 可以理解成：
写给 Codex 的项目规则说明书。
它可以告诉 Codex：
| 内容 | 作用 |
|---|---|
| 项目怎么运行 | 让 Codex 知道启动、测试、构建命令 |
| 代码风格是什么 | 避免生成不符合项目风格的代码 |
| 哪些目录不能动 | 防止误改核心文件 |
| 修改前要怎么做 | 固定“先计划后执行” |
| 测试要求是什么 | 改完必须跑哪些检查 |
| 提交要求是什么 | commit 和 PR 怎么写 |
示例内容：
[code]
# AGENTS.md
## 工作规则
- 修改前必须先阅读项目结构。
- 修改前必须先制定计划，不要直接写代码。
- 一次只实现一个功能点。
- 不要顺手重构无关代码。
- 不要新增不必要依赖。
- 不确定业务逻辑时，先提问，不要自行决定。
## 测试要求
每次修改后至少检查：
- npm run lint
- npm run build
- 相关页面手动测试
- 浏览器控制台是否有报错
- 移动端布局是否正常
## 提交要求
提交前需要说明：
- 修改了哪些文件
- 每个文件改了什么
- 测试是否通过
- 是否有风险或未完成事项
[/code]
更新项目文档
除了 AGENTS.md，如果这次修改影响了项目使用方式，也要更新项目文档。
比如：
| 修改内容 | 需要更新的文档 |
|---|---|
| 新增功能 | README、功能说明 |
| 新增环境变量 | .env.example、部署文档 |
| 新增命令 | README、开发指南 |
| 修改接口 | API 文档 |
| 修改部署流程 | 部署说明 |
| 修改配置 | 配置说明 |
| 新增组件 | 组件使用说明 |
文档更新不是为了好看，而是为了避免以后忘记。
常见文档包括：
| 文件 | 作用 |
|---|---|
| README.md | 项目介绍、启动方式、常用命令 |
| .env.example | 环境变量示例 |
| docs/ | 详细项目文档 |
| CHANGELOG.md | 版本更新记录 |
| AGENTS.md | Codex 工作规则 |
| CONTRIBUTING.md | 团队协作规范 |
提交与复盘提示词模板
实际使用时，可以直接复制下面这段：
[code]
请进入提交与复盘阶段，不要继续新增功能。
请按下面结构输出：
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
- 是否还有未完成事项
- 是否有需要人工确认的风险
[/code]