---
title: "11 · 从理解到实战场景"
description: "把模糊需求改写成 Codex 能执行、能验证、能交付的工程任务。"
verifiedAt: "2026-05-06"
---

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

理解模型、上下文、沙箱和审批之后，真正影响质量的是任务定义。用户给的经常不是工程任务，而是一句模糊话。

> [!TIP]
> 好的 Codex 任务不是“让它试试看”，而是把目标、证据、范围、边界和验证写到它无法误解。

<Cards>
  <Card title="任务如何完成" href="/docs/codex/understanding/how-a-task-completes">
    先理解 Codex 从读取上下文到交付 diff 的完整链路。
  </Card>
  <Card title="上下文工程" href="/docs/codex/understanding/context-engineering">
    模糊需求要先转成足够窄的上下文包。
  </Card>
  <Card title="沙箱和审批" href="/docs/codex/understanding/sandbox-approval">
    执行前确认权限，不让分析任务变成失控修改。
  </Card>
</Cards>

## 核心动作

```mermaid
flowchart LR
    Fuzzy["模糊需求"] --> Triage["分诊"]
    Triage --> Evidence["收证据"]
    Evidence --> Scope["拆范围"]
    Scope --> Brief["写任务说明"]
    Brief --> Execute["执行"]
    Execute --> Verify["验证交付"]
```

模糊需求不要直接交给 Codex 修改代码。正确顺序是：

1. 分诊：这句话可能是什么意思。
2. 收证据：先看现场，不猜。
3. 拆任务：把大问题拆成可验证的小任务。
4. 写任务说明：明确目标、范围、边界、验证。
5. 再执行：让 Codex 开始改。

前四步通常不改代码。这个成本看起来慢，但比改错方向后回滚便宜。

## 案例一：网站做快一点

“网站做快一点”不是一个可执行任务。它可能指：

- 首屏慢。
- 图片太大。
- API 慢。
- 路由切换卡。
- 第三方脚本拖慢。
- SEO 抓取慢。

先让 Codex 分诊，而不是直接优化：

```text
请分诊“网站做快一点”这个需求，不要改文件。
列出可能含义、需要查看的证据、推荐先验证哪一项。
```

等证据指向首屏 LCP，再写成正式任务：

- 目标：首屏 LCP 从当前基线降到明确阈值。
- 范围：只改 Hero 组件和首屏图片。
- 边界：不新增依赖，不改路由，不动全局配置。
- 验证：Lighthouse、截图对比、核心页面手动检查。

这才是 Codex 能执行的任务。

## 案例二：这个 bug 你看下

“你看下”最大的问题是没有复现路径。没有复现路径，Codex 只能猜。

先补齐信息：

- 哪个页面。
- 哪个按钮或操作。
- 控制台报错全文。
- 最近改过什么。
- 能稳定复现还是偶发。
- 期望行为和实际行为分别是什么。

拿到信息后，再让 Codex 给假设排序。比如“点击保存没反应”可能是 API 返回结构变了、状态初始值缺失、异步竞态，或者按钮被 disabled。不要让它直接改第一个猜测。

## 案例三：读懂一个新代码库

“读懂项目”也不是一个可执行任务。更好的目标是“建立项目地图”。

可以让 Codex 只读这些内容：

- README、CONTRIBUTING、AGENTS.md 或 CLAUDE.md。
- package.json、pyproject.toml、Cargo.toml 等项目清单。
- 主要源码目录。
- 路由和入口文件。
- 测试目录。

输出要求应该是：

- 项目一句话用途。
- 技术栈。
- 主要目录职责。
- 启动、测试、构建命令。
- 最重要的文件和原因。
- 新人下一步该读什么。
- 不确定的地方明确标出。

这类任务的关键是“不改文件”。读懂项目阶段不要让 Codex 顺手优化。

## 一份好任务说明

给 Codex 的任务说明至少包含五项：

- 目标：用户层面的结果是什么。
- 范围：只允许动哪些目录或文件。
- 边界：明确不做什么。
- 验证：用什么命令或人工步骤验收。
- 交付：最后要汇报什么。

如果你说不清验证方式，说明任务还没准备好执行。

## 常用模板

修 bug：

```text
任务：修复 {现象}
目标：{用户可见问题消失}
范围：只改 {文件/目录}
边界：不新增依赖，不改数据库，不改无关文件
验证：运行 {测试命令}，并手动检查 {步骤}
请先给计划，确认后再改。
```

补测试：

```text
任务：给 {组件/函数} 补测试
覆盖：正常路径、空值、错误状态、边界输入
边界：不改生产逻辑，除非发现真实 bug 并先说明
验证：运行对应测试文件
```

代码审查：

```text
请审查当前 diff，不要改文件。
优先看 bug、回归风险、安全问题、缺失测试。
按严重程度排序，并给出文件位置和建议验证方式。
```

## 判断任务是否写对

看四点：

- Codex 是否知道先读什么。
- Codex 是否知道不能动什么。
- Codex 是否知道完成后怎么验证。
- 任务是否能拆成一次可 review 的改动。

如果 Codex 开始问大量澄清问题，说明任务还不够具体。如果 Codex 上来就改很多无关文件，通常是范围和边界没写清楚。

## 新手常见坑

- 把模糊愿望当成工程任务。
- 让 Codex 在没有证据时直接修。
- 没写“不改文件”，结果分析任务变成修改任务。
- 没有验收标准，最后只能凭感觉判断好坏。
- 一次塞太多目标，导致 diff 无法 review。

这一篇的核心不是模板，而是工程顺序：先把需求变成可验证任务，再让 Codex 执行。

## 下一步

把这里的任务说明方式带回官方场景页：Web、原生应用、数据清洗、PR review、Slack 派发、Computer Use QA 都是同一套逻辑。入口不同，底层标准一样：目标清楚、上下文足够、边界明确、验证可复现。
