Codex 提示词与上下文

Codex 不要求特殊“咒语”。稳定结果来自四件事：说明结果、提供会改变判断的上下文、划清边界、定义如何验证。提示词的作用不是替代工程设计，而是让任务的成功条件可检查。

一个够用的任务结构

目标：用户点击“保存”后，即使请求超时也能看到明确反馈。

上下文：React 页面在 src/pages/Profile.tsx；请求封装在 src/api/profile.ts；
现有通知组件在 src/components/Toast.tsx。

边界：不改变后端接口，不新增依赖，不重写表单状态管理。

验收：
- 成功、4xx、5xx 和超时都有对应状态；
- 连续点击不会产生重复请求；
- 补充相关测试并运行 lint、test、build；
- 报告未能验证的行为。

这四段不是强制格式。小任务可以一句话说清，大任务再补范围、风险和交付格式。不要为了“完整”堆入不会影响决策的背景。

先描述结果，再描述过程

优先写：

修复 375px 宽度下导航栏出现横向滚动的问题。保留现有菜单行为，补充回归测试，并用浏览器验证 375px 和 1440px。

谨慎写：

把第 42 行改成 flex-wrap，再加两个媒体查询……

除非实现方式本身是硬性约束，否则先说明用户可观察的结果。Codex 阅读代码后可能发现真正的问题是最小宽度、绝对定位或长文本，而不是你预想的 flex-wrap。

给足“决策上下文”

指定入口，不要倾倒整个仓库

在 IDE 扩展中，打开文件会自动成为重要上下文；在 CLI 中可以明确写路径，或用 @ 路径补全、/mention 附加文件。

阅读 @src/routes.ts @src/auth/session.ts 和 @tests/auth.spec.ts。
解释登录回调如何保存会话，再指出刷新后丢失状态的最可能位置。
先不要修改文件。

提供复现步骤和真实错误

复现：
1. pnpm dev
2. 以普通用户登录
3. 打开 /settings/billing
4. 刷新页面

实际：页面回到 loading，控制台出现下方错误。
期望：刷新后继续显示当前套餐。

错误日志：<粘贴经过脱敏的完整堆栈>

“修复登录 Bug”需要大量猜测；可重复的步骤能让 Codex先建立失败基线，再判断修复是否有效。

明确权威来源

当 README、代码和 Issue 可能冲突时，告诉它以谁为准：

以 tests/contract/ 下的契约测试为当前行为基线。README 可能过时；若发现冲突，请列出但不要顺手修改文档。

边界只写真正重要的事

有价值的边界通常属于以下几类：

类型	示例
修改范围	只修改支付回调及其测试
兼容性	不改变公开 JSON 字段和错误码
依赖	不新增生产依赖
数据安全	不执行写数据库或生产环境命令
人工审批	迁移文件先给方案，确认后再生成
交付质量	必须运行指定测试并报告退出结果

边界太多、互相冲突时，模型只会把注意力花在满足文字表面。可以要求它在动手前指出冲突或缺失条件。

把“完成”改成可验证证据

不要只写“确保能用”。根据任务选择证据：

• 纯函数：单元测试覆盖正常值、边界值和错误值；
• API：契约测试、状态码、响应结构和兼容性；
• UI：目标视口截图、交互状态、键盘访问和控制台错误；
• 性能：同一数据集、同一运行环境下的前后指标；
• 数据库：迁移可逆性、锁表风险、备份和演练结果；
• 文档：链接有效、示例可运行、版本与前置条件明确。

推荐在提示词结尾固定加入：

完成后请报告：
1. 修改了什么，以及为什么；
2. 实际运行了哪些命令及其结果；
3. 哪些行为没有验证；
4. 剩余风险和建议的人工检查。

按任务类型套用模板

理解代码

先不要改代码。追踪一次 POST /orders 请求从路由到数据库的完整路径。
列出涉及文件、每层职责、数据校验位置、事务边界和两个最容易误改的点。
结论必须引用仓库中的文件或测试；不确定时明确标注。

修复 Bug

根据以下步骤复现问题：<步骤>。
实际结果：<现象>。期望结果：<行为>。

先运行最小复现并定位根因，再提出最小修复。不要用吞异常或删除校验来绕过问题。
补充一个修复前失败、修复后通过的回归测试，并运行相关测试套件。

实现功能

实现：<用户可观察行为>。
入口：<文件、路由或组件>。
沿用：<现有组件、服务或模式>。
不得改变：<兼容性与范围边界>。
验收：<测试、构建、视口或接口证据>。

先阅读相关代码并列出计划；若需要新增依赖或改公开 API，先停下来说明理由。

重构

重构 <模块>，目标是 <降低重复/明确边界/改善可测试性>。
保持外部行为、公开 API 和序列化格式不变。

先确认现有测试基线，再分小步修改。每一步运行最相关的测试；
不要把格式化、依赖升级或无关命名调整混入本次 diff。

代码审查

审查当前分支相对 main 的改动。
优先找会导致错误结果、数据损坏、安全问题或兼容性回归的具体问题。
每条发现要给出文件与行号、触发条件、影响和可执行修复建议。
不要把纯风格偏好列为缺陷；没有发现时明确说明测试盲区和剩余风险。

大任务如何拆分

一个有效的拆分顺序是：

1. 调查：读代码、复现、确认约束，不编辑；
2. 设计：列方案、接口变化、风险和验证计划；
3. 实现：每次只改变一个可观察行为；
4. 验证：运行针对性检查，再跑更广的回归；
5. 审查：查看 diff，删掉越界改动，报告残余风险。

当任务持续较久，可以要求 Codex维护简短的 TODO；当中途发现方向错误，直接发送新消息纠偏。不要等它完成一个错误假设上的大改动才反馈。

AGENTS.md、配置与当前提示词怎么分工

内容	放置位置
本次 Issue 的目标与验收	当前提示词
仓库长期命令、目录约定、测试要求	AGENTS.md
某子目录独有规则	更靠近该目录的 AGENTS.md
沙箱、审批、模型、MCP 等运行设置	.codex/config.toml 或用户配置
跨项目复用的一套专业流程	Skill 或 Plugin

不要把临时产品需求写成全局规则，也不要用配置文件承载本应由测试保护的业务行为。

常见低质量提示词

写法	问题	改法
“优化这个项目”	成功标准不明确	指定一个指标或用户行为
“修复所有 Bug”	范围无限，无法验收	给复现步骤和优先级
“不要犯错”	不可操作	指定测试、审查和停止条件
粘贴整仓日志	噪声淹没关键信号	提供相关堆栈和复现环境
只要求“写代码”	容易跳过验证	要求基线、测试与风险摘要
强制先说“好的”	不提升工程质量	让它复述约束和未知项

资料与实践来源

官方资料

• OpenAI Prompting
• Prompting Codex：工作流示例
• Configuration Reference

工程实践

• Simon Willison：How I use LLMs to help me write code
• Addy Osmani：My LLM coding workflow going into 2026

本文将社区作者反复强调的“小步、可复现、可验证、保留人工判断”整理成模板；具体 Codex 功能仍以官方文档为准。

最后校对：2026 年 7 月 22 日