怎样写一个合格的 Codex 任务

怎样写一个合格的 Codex 任务

这一篇是 Codex 使用方法的核心。

很多人用 Codex 效果不稳定，不是因为 Codex 不会写代码，而是因为任务描述太模糊：

帮我优化一下
帮我修一下
帮我看看
帮我改好

这些话都不够。

合格的 Codex 任务应该让 Codex 清楚知道：

我要什么
在哪里改
不能改什么
怎么验收
失败了怎么办
最后怎么汇报

前置教程：Git 提交前检查
如果你还没学会如何让 Codex 做任务验收和提交前检查，先完成前置教程，再回到本篇。

依据来源：OpenAI Codex 官方手册中关于任务上下文、提示词、验证、审批、安全和 diff 审查的说明。

本篇目标

跟着本篇做完后，你应该能做到：

1. 写出一个 Codex 能执行的任务。
2. 明确任务目标。
3. 提供必要上下文。
4. 限制修改范围。
5. 写清验收标准。
6. 让 Codex 先提问再动手。
7. 避免一次任务过大。
8. 让 Codex 最后按固定格式汇报。

合格任务的 7 个组成部分

一个合格任务，建议包含 7 块：

1. 任务目标
2. 背景上下文
3. 修改范围
4. 禁止事项
5. 验收标准
6. 不确定时怎么处理
7. 汇报格式

不是每次都要写得很长，但这 7 个意识要有。

第 1 块：任务目标

任务目标要具体。

不好的写法：

帮我优化首页。

好的写法：

请把首页顶部按钮文案从“开始”改成“从 0 开始学习”。

不好的写法：

帮我修一下登录。

好的写法：

登录页点击“登录”后，如果手机号为空，请在输入框下方显示“请输入手机号”，不要弹窗。

判断标准：

一个陌生人看完任务目标，应该能知道最后页面或代码要变成什么样。

第 2 块：背景上下文

Codex 会读项目，但你仍然要提供任务背景。

示例：

这是一个 Astro 静态教程站。
当前页面是首页。
我只想调整首页 CTA 文案，不想改布局。

或者：

这是一个 Spring Boot 接口。
当前 Bug 出现在用户登录接口。
错误现象是手机号为空时返回 500，期望返回 400 和中文错误信息。

背景不是越多越好，而是要让 Codex 少猜。

第 3 块：修改范围

范围越清楚，越不容易失控。

示例：

修改范围：
1. 优先只修改 src/pages/index.astro。
2. 如果必须修改样式文件，请先说明原因。
3. 不要修改路由、配置、依赖和构建脚本。

或者：

修改范围：
1. 只处理登录接口参数校验。
2. 不要重构用户服务。
3. 不要修改数据库结构。
4. 不要改注册逻辑。

范围不是为了限制 Codex 发挥，而是为了让任务可控。

第 4 块：禁止事项

明确告诉 Codex 不要做什么。

常见禁止事项：

不要安装新依赖。
不要提交 Git。
不要删除文件。
不要修改无关页面。
不要重构整个项目。
不要改数据库结构。
不要把 API Key 写进文件。
不要扩大修复范围。

如果你不写禁止事项，Codex 可能会为了“做得更完整”顺手做很多事。

第 5 块：验收标准

验收标准是任务是否完成的判断依据。

示例：

验收标准：
1. 首页按钮文案显示为“从 0 开始学习”。
2. 只修改必要文件。
3. 页面没有明显布局错乱。
4. Codex 需要检查 Git diff 并说明变化。

Bug 修复示例：

验收标准：
1. 手机号为空时返回 400。
2. 返回信息包含“请输入手机号”。
3. 正常手机号登录流程不受影响。
4. 如果项目有相关测试，请运行或说明为什么没有运行。

不要只说“修好”。要说什么叫修好。

第 6 块：不确定时怎么处理

这是很多人忽略的关键。

你要告诉 Codex：不确定时先问。

示例：

如果你不确定入口文件在哪里，请先只读分析并告诉我，不要猜。

如果你发现需要修改超过 2 个文件，请先停下来说明原因，等我确认。

如果错误原因不明确，请先列出可能原因和你需要查看的文件，不要直接改。

这能显著减少乱改。

第 7 块：汇报格式

最后要求 Codex 按固定格式汇报。

示例：

完成后请按下面格式汇报：

## 修改摘要
- 改了什么：
- 修改文件：

## 验收结果
- 检查了什么：
- 结果是什么：

## 风险提示
- 是否有未确认事项：
- 是否建议进入提交前检查：

固定格式能让你更容易验收。

通用任务模板

下面是一份可以直接复制的通用模板：

请完成下面这个 Codex 任务。

## 任务目标
请把【这里写具体目标】。

## 背景上下文
- 当前项目是：【项目类型】
- 当前问题/需求是：【现象或需求】
- 期望结果是：【完成后应该看到什么】

## 修改范围
1. 优先修改：【文件或目录】
2. 如果必须修改其他文件，请先说明原因。
3. 不要修改和任务无关的代码。

## 禁止事项
1. 不要提交 Git。
2. 不要安装新依赖。
3. 不要删除文件。
4. 不要把 API Key、token、账号信息写进文件。
5. 不要扩大任务范围。

## 验收标准
1. 任务目标已经实现。
2. 修改范围符合上面的限制。
3. 请检查 Git 状态和 diff。
4. 请根据项目情况做最小必要验收。
5. 如果没有运行检查，请说明原因。

## 不确定时
如果你不确定原因、入口文件或修改范围，请先提问或列出判断依据，不要猜。

## 汇报格式
完成后请按下面格式回复：

### 修改摘要
- 改了什么：
- 修改了哪些文件：

### 验收结果
- 做了哪些检查：
- 哪些通过：
- 哪些失败：
- 哪些没有检查，原因是什么：

### 风险提示
- 是否有超出范围的改动：
- 是否需要我人工确认：
- 是否建议进入提交前检查：

小任务模板

适合文案、样式、小页面调整：

请完成一个小范围修改任务。

任务目标：
【写清楚要改成什么】

范围限制：
1. 优先只修改 1 个文件。
2. 如果必须修改多个文件，请先说明原因。
3. 不要安装依赖。
4. 不要提交 Git。

验收标准：
1. 改动符合任务目标。
2. 没有无关文件变化。
3. 请检查 Git diff 并用中文解释。
4. 如有最小必要检查，请运行；如果没运行，请说明原因。

完成后请总结：
- 修改文件
- 修改内容
- 验收结果
- 是否可以进入提交前检查

Bug 任务模板

适合修问题：

我遇到了一个 Bug。

## 现象
【实际发生了什么】

## 期望
【应该发生什么】

## 复现步骤
1. 【第一步】
2. 【第二步】
3. 【看到什么错误】

## 错误信息
【粘贴完整报错；没有就写“暂无”】

## 要求
1. 请先阅读相关代码定位原因。
2. 定位原因后先解释，不要立刻修改。
3. 确认最小修复方案后再修改。
4. 不要扩大修复范围。
5. 不要顺手重构无关代码。

## 验收标准
1. Bug 现象消失。
2. 原有正常流程不受影响。
3. 修改范围尽量小。
4. 请运行或说明最小必要检查。

## 汇报格式
- Bug 原因：
- 修改文件：
- 修改内容：
- 验收结果：
- 是否还有风险：

大任务怎么拆

如果你的任务像这样：

帮我做一个完整登录注册系统。

不要直接丢给 Codex。

先让 Codex 拆任务：

我想做登录注册系统。请先不要写代码。

请帮我拆成 5 到 8 个小任务，每个任务都要满足：
1. 目标明确。
2. 修改范围可控。
3. 有验收标准。
4. 可以单独提交。

请按推荐顺序输出，并告诉我第一个任务应该做什么。

大任务必须先拆，再一个个做。

什么时候必须先问 Codex 不要动手

遇到这些情况，先让 Codex 分析，不要立刻修改：

• 报错原因不清楚。
• 涉及支付、权限、登录、安全。
• 涉及数据库结构。
• 涉及大量文件。
• 你不确定项目技术栈。
• 你不确定应该改哪个模块。
• 你只是想让 Codex 给方案。

提示词：

请先只读分析，不要修改文件。
请告诉我可能原因、需要查看的文件、建议修改方案和风险点。
等我确认后再动手。

验收结果

做到这里，如果满足下面 7 条，就说明本篇完成：

1. 你知道不能只说“帮我改一下”。
2. 你知道任务要写目标、背景、范围、禁止事项。
3. 你知道要把验收标准写进任务。
4. 你知道不确定时要让 Codex 先问或先分析。
5. 你会用固定汇报格式。
6. 你会把大任务拆成小任务。
7. 你能复制模板并替换变量。

本篇你真正学会了什么

你学会的是：

Codex 不是靠魔法变准的，是靠任务描述变清楚的。

把任务写清楚，才是让 vibe coding 更专业和更高效的第一步。

下一篇学什么

下一篇看：修 Bug 任务模板。

那一篇会把 Bug 场景单独展开，做成可以直接复制使用的模板库。