---
title: "02 · 一次任务是怎么完成的"
description: "把 Codex 的一次任务理解成从目标、上下文、计划、执行到验证交付的工程管线。"
canonical: "https://xiangyugongzuoliu.com/openai-codex-prompt-to-task"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

Codex 不是“发一句话然后等代码”的黑盒。一次可靠任务更像一条工程管线：定义目标、收集上下文、制定计划、执行修改、运行验证、交付审查。

如果你只说“做一个小游戏”，它需要猜框架、位置、边界、验收方式。如果你把目标、范围、禁止事项和验证方式写清楚，Codex 才能稳定推进。

> [!TIP]
> Codex 最容易失败的地方，通常不是写代码本身，而是任务太宽、上下文不足、验证标准缺失。先把任务管线控住，再谈生成质量。

<Cards>
  <Card title="上下文工程" href="/docs/codex/understanding/context-engineering">
    继续学习 Codex 如何读取任务、项目、代码、规则和反馈。
  </Card>
  <Card title="CLI / App / IDE / Cloud" href="/docs/codex/understanding/cli-app-ide-cloud">
    根据任务形态选择合适入口。
  </Card>
  <Card title="安全与审批" href="/docs/codex/understanding/sandbox-approval">
    让任务在正确权限边界内执行。
  </Card>
</Cards>

## 任务管线

一次 Codex 任务可以拆成七步：

```mermaid
flowchart TB
    A["1. 接收任务<br/>理解用户目标"]
    B["2. 澄清边界<br/>确认范围和禁止事项"]
    C["3. 收集上下文<br/>读取文件、规则、报错"]
    D["4. 制定计划<br/>列出修改点和验证方式"]
    E["5. 执行修改<br/>改文件或调用工具"]
    F["6. 运行验证<br/>测试、类型检查、构建"]
    G{"验证通过?"}
    H["7. 交付审查<br/>说明 diff、证据、风险"]

    A --> B --> C --> D --> E --> F --> G
    G -->|通过| H
    G -->|失败| C
```

每一步都有对应风险：

- 接收任务：目标过宽，导致改动失控。
- 澄清边界：你和 Codex 对“完成”的理解不同。
- 收集上下文：读错文件或漏掉项目规则。
- 制定计划：计划跨度太大，不可审查。
- 执行修改：顺手重构或碰到无关文件。
- 运行验证：验证命令和目标不匹配。
- 交付审查：只报喜，不说明未验证和残余风险。

真正的质量控制，不是等 Codex 改完后再看，而是在每个节点提前设置约束。

## 为什么任务要先变小

新手最适合从小任务开始，因为小任务可以审查。

适合起步的任务：

- 一句话能说清目标。
- 改动范围不超过 1-3 个文件。
- 30 分钟内能验收。
- 有明确测试、截图、类型检查或人工验收标准。

不适合直接交给 Codex 的任务：

- “优化整个项目”。
- “重构所有页面”。
- “升级核心架构”。
- “把全站风格弄高级一点”。

大任务不是不能做，而是要拆成一组小任务，每个小任务都能独立验证。

## 三个必须写清楚的边界

任务 prompt 至少要包含三类边界。

```mermaid
mindmap
  root((任务边界))
    文件边界
      只改哪些目录
      哪些文件不能碰
    行为边界
      不新增依赖
      不做无关重构
      不改公共 API
    验证边界
      跑哪些命令
      什么算通过
      哪些无法验证要说明
```

文件边界控制改动范围。行为边界控制实现方式。验证边界控制交付标准。

缺文件边界，Codex 可能扩大修改面。缺行为边界，它可能顺手引入新依赖。缺验证边界，它可能只给“已完成”的文字结论。

## 计划阶段不是形式

很多人跳过计划，直接让 Codex 写代码。短任务可以这样做，但稍微复杂一点就容易失控。

一个合格计划应该说明：

- 要读哪些文件，为什么相关。
- 准备改哪些文件。
- 不会改哪些文件。
- 预期风险点是什么。
- 改完用什么方式验证。

计划不是为了让回答更长，而是给你一个提前拦截的机会。你可以在它动手前发现范围太大、方向不对、验证不够。

## 执行阶段要保护工作树

Codex 执行任务时必须尊重当前工作树。

执行前应确认：

- 目标文件是否已经有别人改动。
- 当前 dirty files 中哪些和本任务有关。
- 是否存在未提交生成物、日志、构建产物。
- 是否允许修改共享脚本、配置或索引文件。

如果有多个 agent 同时工作，任务边界要更窄。最稳的方式是每批只处理少量文件，验证后再进入下一批。

## 验证阶段要和目标对应

验证不是机械跑一个命令。它必须覆盖任务目标。

例子：

- 文档 MDX 改动：至少跑 MDX 类型生成或 `types:check`。
- 样式改动：需要桌面和移动端截图或视觉检查。
- 逻辑改动：需要相关单元测试、集成测试或可复现步骤。
- 配置改动：需要启动、lint、schema 或 dry-run。

如果验证命令失败，Codex 不能直接“忽略”。它应该说明失败原因、是否由本次改动引入、还缺什么环境或权限。

## 交付阶段要给证据

完成汇报至少包含：

- 改了哪些文件。
- 每个文件解决了什么问题。
- 跑了哪些验证。
- 哪些没有验证，为什么。
- 还剩哪些风险或后续候选。

这让你能快速判断任务是否真的完成，而不是只看到一段乐观描述。

## 可直接复用的任务模板

```text
目标：
{具体要完成什么}

范围：
只改 {文件或目录}。
不要碰 {排除范围}。

执行顺序：
先只读分析并列计划；确认后再修改。

约束：
不新增依赖，不做无关重构，不覆盖现有未提交改动。

验证：
改完运行 {命令}。
如果失败，说明失败原因、是否与本次改动相关、替代验证是什么。

交付：
列出修改文件、验证结果、未验证项和残余风险。
```

Codex 的任务质量，来自目标、边界、上下文和反馈闭环。把这四件事写清楚，它就更像工程协作者，而不是随机代码生成器。
