02 · 一次任務是怎麼完成的

Codex 不是“發一句話然後等程式碼”的黑盒。一次可靠任務更像一條工程管線：定義目標、收集上下文、制定計劃、執行修改、執行驗證、交付審查。

如果你只說“做一個小遊戲”，它需要猜框架、位置、邊界、驗收方式。如果你把目標、範圍、禁止事項和驗證方式寫清楚，Codex 才能穩定推進。

任務管線

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

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 至少要包含三類邊界。

mindmap
  root((任務邊界))
    檔案邊界
      只改哪些目錄
      哪些檔案不能碰
    行為邊界
      不新增依賴
      不做無關重構
      不改公共 API
    驗證邊界
      跑哪些命令
      什麼算透過
      哪些無法驗證要說明

檔案邊界控制改動範圍。行為邊界控制實現方式。驗證邊界控制交付標準。

缺檔案邊界，Codex 可能擴大修改面。缺行為邊界，它可能順手引入新依賴。缺驗證邊界，它可能只給“已完成”的文字結論。

計劃階段不是形式

很多人跳過計劃，直接讓 Codex 寫程式碼。短任務可以這樣做，但稍微複雜一點就容易失控。

一個合格計劃應該說明：

• 要讀哪些檔案，為什麼相關。
• 準備改哪些檔案。
• 不會改哪些檔案。
• 預期風險點是什麼。
• 改完用什麼方式驗證。

計劃不是為了讓回答更長，而是給你一個提前攔截的機會。你可以在它動手前發現範圍太大、方向不對、驗證不夠。

執行階段要保護工作樹

Codex 執行任務時必須尊重當前工作樹。

執行前應確認：

• 目標檔案是否已經有別人改動。
• 當前 dirty files 中哪些和本任務有關。
• 是否存在未提交生成物、日誌、構建產物。
• 是否允許修改共享指令碼、配置或索引檔案。

如果有多個 agent 同時工作，任務邊界要更窄。最穩的方式是每批只處理少量檔案，驗證後再進入下一批。

驗證階段要和目標對應

驗證不是機械跑一個命令。它必須覆蓋任務目標。

例子：

• 文件 MDX 改動：至少跑 MDX 型別生成或 types:check。
• 樣式改動：需要桌面和移動端截圖或視覺檢查。
• 邏輯改動：需要相關單元測試、整合測試或可復現步驟。
• 配置改動：需要啟動、lint、schema 或 dry-run。

如果驗證命令失敗，Codex 不能直接“忽略”。它應該說明失敗原因、是否由本次改動引入、還缺什麼環境或許可權。

交付階段要給證據

完成彙報至少包含：

• 改了哪些檔案。
• 每個檔案解決了什麼問題。
• 跑了哪些驗證。
• 哪些沒有驗證，為什麼。
• 還剩哪些風險或後續候選。

這讓你能快速判斷任務是否真的完成，而不是隻看到一段樂觀描述。

可直接複用的任務模板

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

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

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

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

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

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

Codex 的任務質量，來自目標、邊界、上下文和反饋閉環。把這四件事寫清楚，它就更像工程協作者，而不是隨機程式碼生成器。