11 · 從理解到實戰場景

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

核心動作

flowchart LR
    Fuzzy["模糊需求"] --> Triage["分診"]
    Triage --> Evidence["收證據"]
    Evidence --> Scope["拆範圍"]
    Scope --> Brief["寫任務說明"]
    Brief --> Execute["執行"]
    Execute --> Verify["驗證交付"]

模糊需求不要直接交給 Codex 修改程式碼。正確順序是：

1. 分診：這句話可能是什麼意思。
2. 收證據：先看現場，不猜。
3. 拆任務：把大問題拆成可驗證的小任務。
4. 寫任務說明：明確目標、範圍、邊界、驗證。
5. 再執行：讓 Codex 開始改。

前四步通常不改程式碼。這個成本看起來慢，但比改錯方向後回復便宜。

案例一：網站做快一點

“網站做快一點”不是一個可執行任務。它可能指：

• 首屏慢。
• 圖片太大。
• API 慢。
• 路由切換卡。
• 第三方指令碼拖慢。
• SEO 抓取慢。

先讓 Codex 分診，而不是直接最佳化：

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

等證據指向首屏 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：

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

補測試：

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

程式碼審查：

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

判斷任務是否寫對

看四點：

• Codex 是否知道先讀什麼。
• Codex 是否知道不能動什麼。
• Codex 是否知道完成後怎麼驗證。
• 任務是否能拆成一次可 review 的改動。

如果 Codex 開始問大量澄清問題，說明任務還不夠具體。如果 Codex 上來就改很多無關檔案，通常是範圍和邊界沒寫清楚。

新手常見坑

• 把模糊願望當成工程任務。
• 讓 Codex 在沒有證據時直接修。
• 沒寫“不改檔案”，結果分析任務變成修改任務。
• 沒有驗收標準，最後只能憑感覺判斷好壞。
• 一次塞太多目標，導致 diff 無法 review。

這一篇的核心不是模板，而是工程順序：先把需求變成可驗證任務，再讓 Codex 執行。

下一步

把這裡的任務說明方式帶回官方場景頁：Web、原生應用、資料清洗、PR review、Slack 派發、Computer Use QA 都是同一套邏輯。入口不同，底層標準一樣：目標清楚、上下文足夠、邊界明確、驗證可復現。