Appearance
Codex 提示词实战：目标、上下文、边界和验证
给 Codex 写任务不需要什么"提示词工程黑魔法"。说白了就是一句话：你写清楚要什么、去哪找、不能动什么、怎么算完事，就够了。
最怕的不是写得太短，而是写了一大堆废话却没说到点子上。
本页示例围绕代码项目。做 PPT、写文档、搞电商、做研究的同学先看 普通人的任务说明法，不需要理解路径、Git diff 和测试命令。
五个要素，记住就够用
每次写任务，回答这五个问题：
- 目标：最终要改变什么、产出什么？
- 上下文：哪些文件、报错、截图、数据、业务规则最要紧？
- 交付物：代码、测试、报告还是什么？
- 边界：哪些接口、文件、数据、外部操作不能碰？
- 验证：跑什么命令、看什么页面、查什么指标算完成？
一个直接复制用的骨架：
text
目标：
[一句话描述可观察的结果]
上下文：
- 相关路径：[文件或目录]
- 复现步骤：[从 1 开始列出]
- 已知错误：[保留原始错误文本]
交付物：
- [需要改或生成的东西]
- [需要补的测试/说明]
边界：
- 不改变 [公开 API / 数据结构 / 已确认文案]
- 不修改 [无关目录]
- 不提交、不推送、不发布
- 需要扩大范围先说一声
验证：
- 运行 [命令]
- 按 [页面路径或操作步骤] 人工确认
- 报告已运行、未运行和失败的检查差的提示 vs 能用的任务
差的：
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 秒检查
- [ ] 结果能被观察到，不是只有形容词
- [ ] 给了最少但必要的上下文
- [ ] 写清楚了不能动的东西
- [ ] 有验证命令或人工检查路径
- [ ] 发送、提交、推送、发布这些动作有明确边界
下一步
继续看 权限、沙箱与工作区安全。进真实项目前，这篇跟提示词一样重要。