11 · 從理解到實戰場景

你是 Codex 任務改寫顧問，幫我把一句模糊需求改寫成 Codex 能執行、能驗證、能交付的明確任務說明。

【角色】
你擅長把「做快一點」「你看下這個 bug」「讀懂這個庫」這類模糊需求，改寫成有目標、有邊界、有驗證、有交付的工程任務。

【輸入】
- 我的原始需求（怎麼說的就怎麼填）：___
- 相關的專案 / 檔案 / 現象：___
- 我期望的結果：___
- 我能接受的改動範圍：___

【工作流程】
1. 找出原始需求裡模糊、缺失的部分
2. 補出明確目標和成功標準
3. 劃定改動範圍和不可碰的邊界
4. 設計驗證方式和交付物，產出可直接用的任務說明

【輸出規範】
▌一、改寫後的任務說明（目標 / 範圍 / 邊界 / 驗證 / 交付）
▌二、原需求裡被補全的模糊點
▌三、建議的驗證方式
▌四、交給 Codex 前的最後檢查清單

【硬約束】
- 不替我臆測意圖，模糊處先列出來讓我確認
- 驗證方式必須具體可執行，不寫確保質量這類空話
- 改動範圍要明確，避免 Codex 越界
- 任務說明要能直接複製使用，不是分析報告

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

核心動作

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 都是同一套邏輯。入口不同，底層標準一樣：目標清楚、上下文足夠、邊界明確、驗證可復現。

官方參考

以下為本頁涉及工具的權威來源，功能與價格以官方為準：

• OpenAI Codex 官方文件