---
title: "11 · 從理解到實戰場景"
description: "把模糊需求改寫成 Codex 能執行、能驗證、能交付的工程任務。"
verifiedAt: "2026-05-06"
---

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

理解模型、上下文、沙箱和審批之後，真正影響質量的是任務定義。使用者給的經常不是工程任務，而是一句模糊話。

> [!TIP]
> 好的 Codex 任務不是“讓它試試看”，而是把目標、證據、範圍、邊界和驗證寫到它無法誤解。

<Cards>
  <Card title="任務如何完成" href="/zh-Hant/docs/codex/understanding/how-a-task-completes">
    先理解 Codex 從讀取上下文到交付 diff 的完整鏈路。
  </Card>
  <Card title="上下文工程" href="/zh-Hant/docs/codex/understanding/context-engineering">
    模糊需求要先轉成足夠窄的上下文包。
  </Card>
  <Card title="沙箱和審批" href="/zh-Hant/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 都是同一套邏輯。入口不同，底層標準一樣：目標清楚、上下文足夠、邊界明確、驗證可復現。
