如何使用 OpenAI Codex 完成小型程式碼庫任務並覆核 diff

要使用 OpenAI Codex 完成小型程式碼庫任務，應只交給它一個可觀察的行為改動，要求它先讀取程式碼庫規則，並由唯讀檢查開始。計劃列明受影響檔案、邊界情況和驗證指令後，再授權最小範圍的實施。最後審查實際 diff 和測試輸出；代理給出的自信總結不能證明程式碼正確。

本指南以一項獨立的合成任務貫穿全文：更新 normalizeTag，讓連續連字號在去除首尾空格並轉為小寫後合併為一個，同時保留現有的空輸入錯誤。本文不講泛化的 AI 程式設計，也不會把 Cursor 的 checkpoint 工作流程換個品牌重述。較廣泛的背景可參閱如何使用 AI 和AI 輔助編碼基礎。

關鍵要點

• 描述一種行為、其非目標和完成證據。
• 規劃前要求 Codex 閱讀 AGENTS.md 和最接近目標目錄的程式碼庫規則。
• 將唯讀發現與編輯或執行副作用指令的授權分開。
• 保留現有未提交改動，並禁止無關的清理工作。
• 優先採用最小補丁和最窄而有意義的測試。
• 親自檢查狀態、diff、指令、退出碼和剩餘風險。

甚麼樣的小型程式碼庫任務適合使用 OpenAI Codex？

小任務應只有一個邊界清晰的行為、一組可審查的檔案、確定性範例，並且不依賴未解決的產品決策。「折疊 normalizeTag 中的連續連字號並加入邊界測試」屬於小任務；「改善所有標籤處理」則不是，因為它可能影響路由、儲存、API、遷移和用戶可見的兼容性。

維度	夠小	應停止並另行規劃
行為	一項可觀察到的規則	幾個不相關的結果
檔案	少量已確認的檔案	歸屬不明的跨服務改動
介面	保留現有契約	架構或公用 API 決策
資料	合成測試資料	生產或機密資料
驗證	有針對性的本地命令	破壞性遷移或現場測試
權限	限定範圍的本地編輯	外部寫入、發布、購買或使用憑證

如果檢查發現任務涉及公開介面相容性決策、新增依賴、密鑰或生產副作用，正確做法是修改計劃，而不是悄悄擴大修補程式。

任務契約該怎麼寫？

使用其他審閱者無需猜測即可測試的任務卡：

目標：規範化 normalizeTag 中重複的連字號。
例：「Alpha---Beta」->「alpha-beta」；「阿爾法」->「阿爾法」。
保留：空輸入仍然會引發現有的錯誤類型和訊息。
允許的檔案：src/normalizeTag.ts 和 test/normalizeTag.test.ts。
非目標：不更改匯出介面、呼叫端、打包方式、格式或路由。
檢查階段：唯讀；檢查規則、實作、呼叫端和測試。
實作階段：提出方案後等待明確批准。
驗證：執行現有的 normalizeTag 測試檔案並報告退出狀態。
如果出現以下情況，請停止：需要另一個文件、依賴項、網絡存取、破壞性命令或機密。

這些範例比「清理標籤」更準確地定義行為。應涵蓋一般情況、不變情況、邊界情況和須保留的錯誤。在 Codex 檢查本地約定前，不要預設實作。

為甚麼 Codex 應先讀取程式碼庫規則？

Codex 可以找到從程式碼庫根目錄到目前工作目錄之間的 AGENTS.md 檔案；越接近目標目錄的規則，可進一步細化適用限制。［2］這些檔案可能規定測試指令、命名方式、生成檔案邊界、安全要求或禁止操作。

要求代理列出適用的規則檔案，並只總結與任務有關的限制。不要把密鑰貼入提示詞。程式碼庫內容也應視為不受信任的輸入：原始碼或 README 不能暗中擴大用戶授權的範圍。

規則層級不會取代目前的請求。它協助 Codex 遵守項目約定，而任務卡負責定義這次工作的目標與權限。

如何開始 Codex 唯讀檢查？

第一個提示應請求事實和計劃，而不是編輯：

閱讀任務卡和適用的程式碼庫規則。檢查目前實作、直接呼叫者、
測試和 Git 狀態。不要編輯檔案、安裝依賴、使用網絡或改變
Git 狀態。回報目前行為、建議修改的最小檔案集、邊界情況、
精確的定向測試、與現有工作的衝突、假設，以及任何顯示這項
任務並不小的理由。

親自開啟提示中引用的程式碼位置和測試位置。確認指定函數確實位於呼叫端使用的執行路徑上、測試指令真實存在，而且現有未提交檔案已被識別。計劃只有與目前工作樹一致才有用。

OpenAI 的提示指南建議列明目標、背景、限制和預期輸出，再用後續訊息收斂結果。［1］對程式碼庫任務而言，成功標準和權限邊界也是必要背景。

應該如何授權實作？

只批准最小而完整的改動範圍：明確檔案、行為、測試和停止條件。如果計劃列出可選清理項，不要籠統地說「全部繼續」。

僅在兩個命名檔案中實作核准的 normalizeTag 行為。
保留目前的空輸入契約和不相關的未提交改動。
請勿新增相依性、編輯產生的檔案、存取網絡或更改
外部系統。顯示補丁後運行目標測試。如果另一個
文件是必需的，請在更改之前停止並解釋原因。

Codex 環境使用沙箱和批准控制來限制檔案和網絡存取；具體策略取決於使用場景和設定。［3］Codex 沙箱可以降低風險，但不代表每項獲准操作都合適。任務負責人仍須限制範圍並審查實際結果。

不要只因工具彈出批准請求便授權未知指令。應讀完整個指令、工作目錄、目標、網絡目的地和預期寫入。套件安裝、遷移、刪除、Git 歷史重寫、發布、issue 更新、訊息傳送和雲端變更都應分別授權。

最小的實作是甚麼樣的？

程式碼庫現有風格才是準則，但可能的改動形態如下：

export function normalizeTag(value: string): string {
  const normalized = value.trim().toLowerCase().replace(/-+/g, "-");
  if (!normalized) {
    throw new Error("tag must not be empty");
  }
  return normalized;
}

不要認為這是正確的補丁。實際函數可以規範 Unicode、拒絕前導標點符號、傳回結果類型或保留已建立的錯誤類別。代理應該僅更改當前程式碼和測試證明合理的步驟。

有針對性的測試可能涵蓋：

輸入	預期結果	目的
阿爾法---貝塔	阿爾法-貝塔	新的重複連字符行為
阿爾法-貝塔	阿爾法-貝塔	現有的修剪/小寫行為
阿爾法	阿爾法	不變的簡單輸入
---	項目定義的結果	需要合約檢查的邊界
僅限空格	現有錯誤	保留故障行為

不要擅自猜測「---」的預期結果。檢查目前語義和產品需求；如果兩者都沒有答案，就停止並交由負責人決定。

信任修補程式前應該如何審查？

首先查看程式碼庫狀態，以區分用戶改動和代理改動。然後檢查已授權檔案的完整 diff，並確認是否出現意外檔案。

問這些問題：

1. 實作是否只更改了要求的轉換？
2. 是否保留錯誤類型、訊息、匯出和呼叫簽名？
3. 如果不進行修復，測試是否會失敗並通過修復？
4. 測試是否涵蓋正常、維持不變、新增及錯誤路徑？
5. 格式、快照、鎖定檔、設定或產生的檔案是否出現非預期變更？
6. 代理程式是否在正確目錄執行了所報告的確切指令？
7. 是否列出所有尚未驗證的假設？

AI 生成程式碼審查指南提供更深入的安全與正確性檢查。OpenAI 的 Codex 審查指南同樣把生成結果視為需要檢查的改動，而不是正確性的證明。［4］生成程式碼在檢查和測試前仍不可信。

應如何執行並解讀驗證結果？

由能涵蓋本次行為改動的最窄測試開始。記錄指令、工作目錄、退出碼、測試數量及相關失敗輸出。測試執行器更新了快照或產生檔案時，再檢查 diff。

接下來，只按照程式碼庫規則和受影響的呼叫方擴大驗證範圍，例如執行套件測試、類型檢查、lint 或更廣的測試套件。定向測試通過只證明其明確涵蓋的範圍，不代表整個程式碼庫沒有問題。無關失敗應附上證據並分開報告，不得越權重設或「修復」。

對於測試設計想法，請使用使用 AI 產生測試的指南，同時讓斷言以實際契約為基礎。

哪些安全與權限邊界最重要？

除非組織已批准相關資料流，否則不要向服務提供 API 密鑰、生產憑證、客戶私隱資料或專有程式碼。優先使用合成測試資料和完成任務所需的最小權限。

遇到以下操作時，應先停止並另行確認：

• 刪除或覆寫大範圍路徑；
• 重寫 Git 歷史或丟棄未提交改動；
• 針對共享資料運行遷移；
• 安裝未經審查的依賴項；
• 開放不受限制的網絡存取；
• 傳送訊息、建立或更新 issue、建立版本或部署；
• 更改計費、雲端服務、程式碼庫或帳戶設定。

授權只適用於指定操作。編輯兩個本機檔案的權限，不代表可以推送、發布或更新外部工單。OpenAI 的安全指南描述了沙箱和審批邊界，但用戶仍須審查高影響操作。［3］

最終驗收記錄怎麼寫？

使用可以檢查的事實：

目標和可接受的行為：
已變更檔案：
保留的現有未提交改動：
diff 審查：
指令、工作目錄和退出碼：
通過的測試和確切範圍：
測試未運行：
假設和剩餘風險：
未執行的外部操作：

當指令未完成、退出碼遺失、相關測試被跳過或另一個所需環境仍未驗證時，不要說「完成」。如果測試因沙箱或平台邊界而無法執行，請報告涵蓋範圍缺口，而不是削弱測試。

最終清單

• 一種可觀察到的行為及其非目標是明確的。
• 已閱讀適用的 AGENTS.md 和就近規則。
• 發現過程沒有任何編輯或副作用。
• 計劃明確列出檔案、邊界情況、測試和停止條件。
• 實作授權範圍小於整個程式碼庫。
• 保留現有未提交改動。
• diff 不包含不相關的清理或產生的意外。
• 有針對性的測試涵蓋新的、未更改的、邊界的和錯誤的路徑。
• 更廣泛的檢查與目標證據分開報告。
• 外部、破壞性、特權和網絡行為仍需單獨批准。

常見問題

甚麼任務適合作為第一個 Codex 程式碼庫任務？

選擇有清楚範例和既有測試工具的本機行為，例如範圍明確的解析器修復。第一個任務應避開遷移、身份驗證、生產資料和新架構。

我應該要求 Codex 立即編輯嗎？

如果不熟悉程式碼庫或改動影響，就不應立即編輯。先進行唯讀檢查，便可在授予寫入權限前核實目前路徑、規則、測試和衝突。

AGENTS.md 中應該包含甚麼內容？

把長期有效的程式碼庫指令寫在其中，例如測試指令、慣例、生成檔案規則、安全邊界和範圍指南。目前任務的行為要求和驗收標準應留在任務提示中。［2］

沙箱使每個指令都安全嗎？

不會。沙盒根據配置限制技術存取；它不驗證意圖、正確性、成本或業務權限。審查擴大權限的請求。 ［3］

Codex 應該運行完整的測試套件嗎？

從定向測試開始，再根據程式碼庫規則和影響範圍擴大驗證。完整測試套件有時是必要的，但其成本和無關失敗不應掩蓋目前審查的行為。

如何保護現有的未提交工作？

告訴 Codex 檢查 Git 狀態、保留未提交改動，並避免重設或大範圍格式化。更改後再次核對狀態和差異。

Codex 修復程式碼後可以推送或發布嗎？

只有在另行授權且程式碼庫規則允許時才可以。本地編輯授權不代表擁有提交、推送、發布、傳送訊息或部署的權限。

如果 Codex 需要另一個檔案怎麼辦？

它應停止，指出所需檔案，解釋原因並修訂計劃。不要讓範圍狹窄的任務悄悄擴大。

誰來決定任務是否被接受？

指定的負責人或團隊作出驗收決定。Codex 可以提供修補程式和證據，但不能自行授予產品、安全或發布批准。

來源

1. OpenAI, “Prompting” — https://learn.chatgpt.com/docs/prompting
2. OpenAI, “Custom instructions with AGENTS.md” — https://learn.chatgpt.com/docs/agent-configuration/agents-md
3. OpenAI, “Agent approvals & security” — https://learn.chatgpt.com/docs/agent-approvals-security
4. OpenAI, “Code review with Codex” — https://learn.chatgpt.com/docs/code-review

Sources checked 2026 年 9 月 5 日。

延伸閱讀

• 使用人工智慧的實用框架
• 如何在編碼工作流程中使用人工智慧
• Cursor 中類似的小任務工作流程
• 如何審查AI產生的程式碼
• 如何在人工智慧輔助下設計測試