Appearance
Codex 提示词实战：目标、上下文、边界和验证
Codex 不需要“咒语”，但复杂任务需要一份像工程工单一样清楚的说明。最稳定的写法是告诉它要交付什么、去哪里找事实、什么不能动、怎样证明完成，而不是预先替它编造几十个执行步骤。
本页示例围绕代码项目。普通办公、PPT、电商、研究和内容任务请先看 普通人的任务说明法，不需要理解路径、Git diff 或测试命令。
五要素任务说明
记住五个问题即可：
- 目标：最终要改变什么行为或产出什么文件？
- 上下文：哪些路径、错误、截图、数据或业务规则最重要？
- 交付物：代码、测试、报告、PPT 还是可运行页面？
- 边界：哪些接口、文件、数据和外部动作不能碰？
- 验证：用什么命令、页面路径或检查表判断完成？
一个可直接复用的骨架：
text
目标：
[一句话描述可观察结果]
上下文：
- 相关路径：[文件或目录]
- 复现步骤：[从 1 开始列出]
- 已知错误：[保持原始错误文本]
交付物：
- [需要修改或生成的内容]
- [需要补充的测试/说明]
边界：
- 不改变 [公开 API / 数据结构 / 已批准文案]
- 不修改 [无关目录]
- 不提交、不推送、不发布
- 需要扩大范围时先说明
验证：
- 运行 [命令]
- 按 [页面路径或业务步骤] 人工确认
- 报告已运行、未运行及失败的检查差提示和好任务的区别
差提示：
text
帮我优化登录。它没有说明是性能、交互、安全还是代码结构，也没有完成标准。
可执行版本：
text
修复登录页连续点击“登录”会发送多个请求的问题。
复现：打开 /login，填写有效账号，快速双击登录按钮，Network 中出现两个 POST /api/login。
要求：请求发送后禁用按钮并显示原有 loading 状态；请求结束后恢复。保持 API 和页面文案不变，补一个回归测试。先复现，再修改，最后运行登录组件测试和前端构建。只改登录相关文件。后者并不更“高级”，只是让结果可观察。
先调查还是直接改
以下情况先要求只读调查：
- 陌生仓库；
- 根因还不确定；
- 涉及数据库、权限、计费或部署；
- 用户说的路径可能和真实路由不一致；
- 工作树有并行修改；
- 修改可能跨多个仓库。
调查模板：
text
先不要修改。沿真实调用链定位 [现象] 的原因。
请给出入口、关键分支、数据变化、日志/错误证据和最小修复点。
把已确认事实、推断和未验证项分开写。当问题位置和验收标准已经非常明确时，可以直接让它修改，但仍保留范围和验证要求。
四类高频任务模板
修 Bug
text
Bug：[原始现象或错误文本]
复现步骤：
1. ...
2. ...
先实际复现并保存失败证据，再定位根因。只修根因，不通过吞异常、跳过校验或删除测试绕过。补回归测试，运行最小相关测试和构建。报告修改文件、验证结果和剩余风险。开发功能
text
实现 [用户可见能力]。
验收：
- 当 [条件] 时，用户看到 [结果]
- 当 [异常条件] 时，系统 [处理方式]
- 保持 [兼容性要求]
先阅读现有相邻实现并列出复用点。完成代码、测试和必要文档。不要增加新依赖，除非现有能力确实不足并先说明理由。做代码审查
text
审查当前分支相对 main 的变化。
重点找会导致错误、安全问题、数据损坏、兼容性回归或缺失测试的内容。
每条发现必须包含文件、位置、触发条件和影响；不要把纯风格偏好当问题。
只报告，不修改。更新文档
text
更新 [页面] 以解决 [读者任务]。
使用项目中的真实命令、字段和路径；版本敏感事实使用当前官方来源。
保留现有 URL。完成后运行文档构建、链接检查和敏感信息扫描，并说明未验证项。给上下文，但不要倾倒上下文
有效上下文通常包括：
- 原始错误文本和完整复现条件；
- 最相关的入口文件、配置和调用方；
- 业务规则以及不能改变的兼容性；
- 一份正确结果示例；
- 截图中需要关注的区域；
- 验证命令和测试账号的安全替代方案。
无效做法是一次粘贴几万行日志、整个数据库导出或大量无关文档。先让 Codex 在授权范围内搜索，再补它找不到的私有上下文。发送日志前删除 Token、Cookie、账号、手机号和用户数据。
用后续消息纠偏
第一轮结果偏了，不必重写整段任务。指出具体差异：
text
根因判断正确，但修改范围过大。保留 src/auth/session.ts 的修复，撤回对公共响应结构的改动，并用现有错误类型完成处理。Codex 正在执行时：
- Steer：把新信息加入当前执行，用于立即改方向；
- Queue：等当前执行结束后再处理，用于下一步任务。
CLI 中通常可用 Enter 发送即时纠偏，用 Tab 排队后续消息；界面快捷键可能随版本变化，以当前帮助为准。
要求证据，不要求表演过程
不必让 Codex 输出冗长的“内心思考”。更有价值的是要求可核验产物：
- 读取过的关键文件；
- 复现失败的命令和输出摘要；
- Git diff；
- 测试、构建和页面检查结果；
- 未验证项及原因；
- 关键判断对应的官方来源。
常见跑偏原因
目标是形容词
“更专业”“更高级”“更安全”无法验收。把它们变成具体行为、页面差异或检查指标。
把猜测写成事实
“问题一定在缓存”会把调查锁死。改成“我怀疑缓存，请沿调用链验证，也检查其他可能原因”。
边界互相冲突
既要求“不改接口”，又要求新增一个必须返回的字段。先决定哪条优先，并说明兼容策略。
一次混入多个目标
修 Bug、重构目录、升级依赖、改 UI 和写博客应拆成不同任务。每个任务只有一个主要完成标准。
提交任务前的 20 秒检查
- [ ] 结果能被观察，而不是只有形容词。
- [ ] 提供了最小必要上下文。
- [ ] 写清了不能动的内容。
- [ ] 有验证命令或人工检查路径。
- [ ] 对外发送、提交、推送、发布等动作有明确边界。
下一步
继续学习 权限、沙箱与工作区安全。进入真实项目前，这一章和提示词同样重要。