---
title: "写好 Codex 提示词"
description: "Prompt 描述你希望 Codex 做什么，好的提示词会写清目标、上下文、边界和验证方式。"
verifiedAt: "2026-05-07"
---

你通过 prompts 和 Codex 交互。Prompt 描述你希望它做什么，Codex 随后进入循环：调用模型、读取文件、编辑文件、运行命令和调用工具，直到任务完成或被取消。

> [!IMPORTANT]
> 好的 Codex prompt 不只是“请帮我做”。它要写清目标、上下文、范围、禁止事项、验证方式和交付格式。

<Cards>
  <Card title="Prompting" href="https://developers.openai.com/codex/prompting">
    官方 Codex prompting 基础。
  </Card>
  <Card title="From theory to practice" href="/docs/codex/understanding/from-theory-to-practice">
    把模糊需求改写成可执行任务。
  </Card>
  <Card title="How a task completes" href="/docs/codex/understanding/how-a-task-completes">
    理解 Codex 从 prompt 到验证的循环。
  </Card>
</Cards>

## 两个简单例子

解释代码：

```text
请解释 transform module 是如何工作的，以及其他模块如何使用它。
```

新增功能：

```text
请添加一个新的命令行选项 `--json`，用于输出 JSON。
```

这两个 prompt 能跑，但真实项目里还不够。要稳定交付，需要补上下文、范围和验证。

## 好 prompt 的结构

```mermaid
flowchart LR
    Goal["目标"] --> Context["上下文"]
    Context --> Scope["范围"]
    Scope --> Boundaries["禁止事项"]
    Boundaries --> Verify["验证"]
    Verify --> Deliver["交付"]
```

建议包含：

- 目标：用户层面的结果是什么。
- 上下文：相关文件、错误日志、截图、链接、业务规则。
- 范围：只允许动哪些文件或目录。
- 禁止事项：不新增依赖、不改数据库、不动无关文件等。
- 验证：跑什么测试、lint、build、截图或人工检查。
- 交付：最后汇报改动文件、验证结果、未验证项和风险。

## Outcome-first 写法

GPT-5.5 的官方提示词指导强调 outcome-first：先定义结果、成功标准、约束和可用上下文，让模型选择具体路径。对 Codex 来说，这比写一长串“先做 A、再做 B、再做 C”更稳，除非每一步都是业务硬约束。

可以用这个模板：

```text
目标：
修复用户在移动端打开设置页时按钮错位的问题。

上下文：
- 复现路径：打开 /settings，宽度 390px，点击 Profile tab。
- 相关文件优先看 src/app/settings 和 src/components/tabs。

范围：
- 只改布局和样式相关文件。
- 不改接口、不改数据结构、不新增依赖。

验证：
- 跑现有 lint/build。
- 用浏览器检查 390px、768px、1440px 三个宽度。
- 最后说明改动文件、验证结果和残余风险。
```

这个 prompt 没规定 Codex 必须先读哪个文件、后改哪个组件，但把目标和验收写清楚了。Codex 可以按实际代码结构选择路径。

## 停止条件和缺证据行为

长任务尤其要写 stopping conditions。否则 Codex 可能一直扩大搜索范围或改到无关文件。

建议直接写：

- 如果没有复现到问题，先停下并报告已检查路径，不要猜改。
- 如果需要新增依赖，先说明原因和替代方案。
- 如果测试失败且与本次改动无关，记录失败命令和证据，不要顺手大改。
- 如果超过约定范围，先输出计划，等确认后再继续。

缺证据时也要明确：

```text
如果官方文档、源码和现象不一致，以本仓库当前源码和可复现行为为准；无法确认时标注为推断，不要写成确定结论。
```

## 复杂任务先拆

Codex 处理复杂工作时，拆成更小、更聚焦的步骤更稳。小任务更容易测试，也更容易 review。

如果不知道怎么拆，先让 Codex 只做计划：

```text
请先不要改文件。基于当前问题提出最小实现计划，列出需要读取的文件、可能风险和验证方式。
```

确认计划后，再让它执行第一步。

## Prompt 里应该少写什么

很多旧 prompt 会堆满绝对规则，例如 ALWAYS、NEVER、must、only。官方提示词指导建议把这些词留给真正的不变量，例如安全边界、必填字段、绝对禁止的动作。

判断类任务更适合写 decision rules：

| 不推荐 | 推荐 |
| --- | --- |
| “永远不要联网。” | “只有当本地资料不足或需要最新事实时联网，并引用来源。” |
| “必须先读所有文件。” | “先读入口文件和调用链，发现范围不足再扩展。” |
| “一定要完整重构。” | “优先最小改动；只有现有结构无法满足目标时再提出重构计划。” |

对 Codex 来说，过多绝对规则会让它在冲突指令里浪费推理，甚至错过更简单的验证路径。

## Thread 和上下文

Thread 是一个单独 session：包含你的 prompt，以及随后产生的模型输出和 tool calls。

一个 thread 可以包含多个 prompts。比如第一个 prompt 实现功能，后续 prompt 添加测试。

可以同时运行多个 threads，但避免让两个 threads 修改同一批文件。并发任务要用 worktree 或明确文件边界。

提交 prompt 时，包含 Codex 可以使用的 context，例如相关文件和图片引用。IDE extension 会自动包含 open files 和 selected text range。

长任务会受 context window 限制。Codex 可能自动 compact：总结相关信息，丢弃不太相关的细节。关键约束、文件路径和验证方式应写在清楚位置，不要只藏在很早的对话里。

## 常见坑

- 任务太宽：让 Codex “优化项目”。
- 没写验证：最后只能凭感觉判断。
- 没写禁止事项：分析任务变成修改任务。
- 没给复现路径：Codex 只能猜 bug。
- 多个 threads 同时改同一批文件。
- 把敏感 token、cookie、私钥贴进 prompt。

## 验收清单

- Codex 知道目标和允许范围。
- Codex 知道不能做什么。
- Codex 知道先读哪些文件或证据。
- Codex 知道完成后怎么验证。
- 最终输出能说明 diff、验证结果、未验证项和剩余风险。
- 长任务写明停止条件和缺证据处理方式。
- 输出长度、格式、表格或 JSON 要求写成可检查标准。

## 官方资料

- [Prompting](https://developers.openai.com/codex/prompting)
- [Workflows](https://developers.openai.com/codex/workflows)
- [Agent approvals and security](https://developers.openai.com/codex/agent-approvals-security)
- [GPT-5.5 Prompt guidance](https://developers.openai.com/api/docs/guides/prompt-guidance)

## 接下来去哪

<Cards>
  <Card title="选择模型" href="/docs/codex/official/04-model-pricing/14-model-selection" description="提示词写好之后再考虑换更强模型" />
  <Card title="理解价格和用量" href="/docs/codex/official/04-model-pricing/15-pricing-usage" description="提示词大小直接影响 token 与 credits 消耗" />
  <Card title="实践建议" href="/docs/codex/official/04-model-pricing/63-best-practices" description="把好提示词沉淀成 AGENTS.md 与 skill" />
  <Card title="基础配置" href="/docs/codex/official/02-config-security/06-basic-config" description="config.toml 是长期偏好的家" />
  <Card title="批准与安全模式" href="/docs/codex/official/02-config-security/07-approval-security" description="提示词搭配 approval 才能落地受控自动化" />
</Cards>
