重点掌握四要素：

• 目标：修什么bug/加什么功能
• 范围：允许修改哪些模块
• 约束：不能改接口、不能动数据库、要保留现有样式
• 验证：跑那些测试、预期结果是什么

1.简介

前两个阶段解决：

• 第1阶段解决“Codex是什么，有哪些入口，怎么拿上下文”。
• 第2阶段解决“如何在本地用CLI/IDE读代码、改代码、跑命令、解释报错、做review”。

第3阶段解决：如何把需求说清楚，让Codex能稳定执行。

官方Best practices中给出的默认提示结构很实用，可以归纳为四件事：

要素	含义
Goal	你要改什么、修什么、做什么
Context	哪些文件、错误、文档、例子和背景重要
Constraints	必须遵守哪些架构、接口、样式、安全和范围限制
Done when	什么情况才算完成，例如测试通过、bug不再复现、行为符合预期

对应到中文工程任务，就是：

目标+上下文+范围+约束+验证+输出要求

也就是：好prompt不是“帮我做一下”，而是“把任务边界和完成标准交代清楚”。

2.Codex执行任务的基本方式

Codex Prompting文档说明：你发送prompt后，Codex会进入一个循环：

理解任务->读取文件->调用工具->修改文件->运行命令->汇报结果

这个过程会持续到任务完成，或者你取消它。

所以给Codex写需求时，不能只想着“让模型回答”，而要想着：

• 他应该先读哪些文件
• 他可以改哪些文件
• 他不应该改哪些东西
• 他应该运行哪些命令？
• 他怎么证明任务完成？
• 他最后该如何汇报？

这就是“可执行任务”的核心

3.一个稳定的需求模板

推荐给Codex提需求，优先使用模板：

任务：<一句话说明要做什么>

目标：
- <修复什么bug/增加什么功能/改善什么行为>

上下文：
- 相关文件：<文件路径>
- 相关错误：<报错、日志、截图、复现步骤>
- 可参考实现：<已有模块、相似功能、文档链接>

范围：
- 允许修改：<目录或文件>
- 不要修改：<目录或文件>

约束：
- <不能改接口/不能改数据库schema/不引入新依赖/保留现有样式>
- <遵守已有代码风格>
- <保持向后兼容>

验证：
- 运行：<测试、`lint`、`typecheck`、`build`命令>
- 预期：<测试通过/bug不再复现/UI行为符合描述>

输出：
- 总结改了哪些文件
- 说明运行了哪些验证
- 如果有未验证风险，明确列出来

最小版本：

- 当前错误行为
- 期望行为
- 允许修改文件
- 不允许修改内容
- 要运行的测试`。
- 最后总结修改和验证结果。

4.目标：说清楚要达成什么结果

目标要描述“期望行为”，不能只描述“我觉得哪里有问题”。

不好的写法：

登陆这里有bug，帮我修一下。

更好的写法：

修复登录在密码错误时仍然跳转到首页的问题。
期望行为：密码错误时停留在登录页，显示后端返回的错误信息，不写入`token`。

目标最好包含：

• 当前错误行为
• 期望正确行为
• 影响场景
• 用户可观察结果

适合bug的目标格式：

Bug：<当前错误行为>
期望：<正确行为>
影响：<哪些用户/页面/接口受影响>

适合功能的目标格式：

功能：<新增能力>
用户行为：<用户如何触发>
系统行为：<系统应如何响应>
完成后：<用户看到什么/数据发生什么变化>

5.上下文：给Codex正确的入库

Codex Workflows文档强调，IDE会自动带上打开文件和选区；CLI中通常需要显示@文件路径，或用/mention添加文件。

上下文不是越多越好，而是越相关越好。

推荐给上下文：

• 相关文件路径
• 复现步骤
• 排错日志
• stack trace
• 相关功能实现等等

不要只说：

这个页面有问题

更好的写法：

问题出现在`src/pages/settings/ProfileForm.tsx`。
提交表单后请求成功，但页面仍显示旧昵称。
请参考`src/pages/settings/PasswordForm.tsx`的保存反馈逻辑。

如果不确定相关文件，可以这样说：

我不确定相关文件在哪里。请先只读代码，定位这个行为涉及的入口、状态管理和API调用。先不要改文件。

6.范围：告诉Codex可以动哪里

范围用于控制修改半径。

如果不给范围，Codex可能会选择一个技术上可行但影响过大的方案。

推荐写法：

范围：

• 允许修改src/pages/settings和src/api/user.ts
• 可以补充相关测试
• 不要修改数据库schema
• 不要改公共API返回结构
• 不要重构无关组件

常见范围类型：

类型	示例
文件范围	只改src/auth/*和对应测试
模块范围	只改订单模块，不动支付模块
行为范围	只修复错误提示，不改变提交流程
技术范围	不引入新依赖，不迁移状态管理
数据范围	不修改数据库schema，不改历史数据

范围越清楚，Codex越容易交付小而可review的diff。

7.约束：提前说清楚不能破坏什么

约束是为了避免“功能做了，但破坏了别的东西”。

常见约束：

• 不能改变APIshape
• 不能修改数据库schema
• 不能引入新依赖
• 不能改变现有UI样式

示例：

约束：
- 不改变`GET /api/users`的返回结构
- 不新增运行时依赖
- 保留现有页面布局和样式
- 优先复用`src/lib/request.ts`
- 只做最小修复，不做额外重构

8.验证：告诉Codex怎么证明完成

Codex在能验证自己工作的情况下，产出更可靠。

验证可以包括：

• 复现步骤
• 单元测试
• 集成测试
• lint
• typecheck
• build
• 手动UI检查
• /review

提示词：

验证：
- 先运行`npm test -- ProfileForm.test.ts`，确认当前失败
- 修复后重新运行同一测试
- 再运行`npm run typecheck`
- 预期：测试通过，保存昵称后页面展示新昵称

9.输出要求：让结果方便review

让Codex最后输出这些内容：

最后请输出：
1. 修改了哪些文件
2. 每个文件为什么改
3. 运行了哪些命令
4. 验证结果是什么
5. 还有哪些风险或未验证点

对于code review场景，可以要求：

请以`code review`格式输出：
- 严重问题优先
- 每个问题包含文件路径和具体风险
- 不要把总结放在问题前面
- 如果没有发现问题，明确说明剩余测试缺口

10.复杂任务：先计划，再执行

Best practices建议：复杂、模糊、难描述的任务，先让Codex计划，不要直接写代码。

适合先计划的任务：

• 多模块重构
• 架构调整
• 性能优化
• 跨端一致性修改
• 数据模型迁移

推荐提示词：

这是一个复杂任务。请先不要修改文件。
先阅读相关代码，输出：
1. 影响范围
2. 可能方案
3. 推荐方案及理由
4. 需要修改的文件
5. 验证计划
6. 风险点

等我确认后再开始实现。

如果说不清需求，也可以让Codex反问：

我只有一个模糊想法。请先像工程负责人一样追问我关键问题，把需求澄清成可执行任务。暂时不要写代码。

11.常见任务模板

11.1修bug

任务：修复设置页保存后状态没有持久化的问题。

目标：
- 当前：点击保存后显示“已保存”，刷新页面后设置恢复旧值。
- 期望：保存成功后刷新页面仍保留新值。

上下文：
- 页面：src/pages/settings/SettingsPage.tsx
- API：src/api/settings.ts
- 可参考：src/pages/profile/ProfilePage.tsx 的保存逻辑

范围：
- 允许修改`settings`页面、`settings API`封装和相关测试
- 不要修改后端接口`shape`

约束：
- 保持现有UI不变
- 不引入新依赖
- 优先做最小修复

验证：
- 先尝试复现问题
- 修复后运行`settings`相关测试
- 如果没有现成测试，请补一个最小回归测试

输出：
- 总结改动文件、验证命令和剩余风险

11.2加功能

任务：给用户列表增加按状态筛选。

目标：
- 在用户列表页增加 `status`筛选项
- 支持active、disabled、all
- 筛选条件同步到 `URL query`

上下文：
- 页面：src/pages/users/UserList.tsx
- 现有搜索逻辑：src/hooks/useUserSearch.ts
- API：src/api/users.ts

范围：
- 可以修改用户列表页面、相关`hook`、相关测试
- 不要修改其他列表页

约束：
- 不改变现有接口返回结构
- 不引入新状态管理库
- 保持现有表格样式
- `URL query`命名使用 `status`

验证：
- 运行用户列表相关测试
- 运行`typecheck`
- 预期：切换筛选时列表刷新，刷新浏览器后筛选条件仍保留

输出：
- 列出修改文件和测试结果

11.3解释并修复报错

任务：解释并修复 `npm test`报错。

上下文：
- 命令：`npm test -- UserList.test.ts`
- 报错：
  <粘贴错误输出>

要求：
- 先解释根因
- 再定位相关文件
- 最后做最小修复

范围：
- 只改与这个测试失败直接相关的文件
- 不要更新`snapshot`，除非能说明行为变化是正确的

验证：
- 修复后重新运行同一测试
- 如果涉及类型，运行 `npm run typecheck`

输出：
- 说明根因、改动和验证结果

11.4写测试

任务：为订单金额计算函数补测试。

目标：
- 覆盖正常折扣
- 覆盖无折扣
- 覆盖优惠金额超过总价
- 覆盖空订单项

上下文：
- 函数：`src/domain/order/calculateTotal.ts`
- 现有测试风格：`src/domain/order/*.test.ts`

范围：
- 只新增或修改订单金额相关测试
- 不修改业务实现，除非发现明确bug 并先说明

验证：
- 运行订单`domain`相关测试

输出：
- 总结新增了哪些测试场景

11.5UI调整

任务：调整登录页错误提示样式。

目标：
- 错误提示从页面顶部移动到密码输入框下方
- 文案保持后端返回内容

上下文：
- 页面：src/pages/login/LoginPage.tsx
- 现有表单组件：src/components/FormField.tsx

范围：
- 允许修改登录页和必要的表单展示组件
- 不要改认证逻辑

约束：
- 保留现有整体布局
- 不改变登录API调用
- 不新增UI库
- 移动端不能遮挡按钮

验证：
- 运行登录页相关测试
- 如果项目有 `Storybook` 或截图测试，运行相关检查
- 手动检查错误密码场景

输出：
- 列出改动和验证结果

11.6.Code review

任务：`review`当前未提交改动。

重点：
- 行为回归
- 安全风险
- 错误处理
- 缺失测试
- 类型边界

范围：
- 只`review`当前`diff`，不评价无关旧代码

输出：
- `findings` 优先，按严重程度排序
- 每个 `finding` 包含文件路径、具体风险和建议
- 如果没有发现问题，说明剩余测试缺口

12.和AGENTS.md的关系

不要把每次都重复的规则塞进prompt。

适合放进AGENTS.md：

• 项目结构
• 常用命令
• 测试命令
• lint/typecheck 命令
• 代码风格
• review标准
• 禁止事项
• “完成”的定义

适合放进单次prompt

• 本次任务目标
• 本次相关文件
• 本次特殊约束
• 本次验证方式
• 本次优先级

心智模型：

`AGENTS.md`= 长期规则  
`Prompt`= 本次任务

如果你发现自己每次都在说：

不要引入新依赖  
修改后跑`typecheck`  
最后总结验证结果

就应该考虑把这些规则写进AGENTS.md。

13. 总结

目标决定方向  
上下文决定入口  
范围决定修改半径  
约束决定不能破坏什么  
验证决定是否真的完成  
输出要求决定是否容易`review`

一句话总结：

正确提需求的核心，是把Codex当成工程队友：给清楚任务、边界和完成标准，让它能读代码、改代码、跑验证，并把结果交付成你能review的形式。