如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題
Jul 20, 2026 Codex

自訂 Codex 程式碼審查規則

提供更具體的規則,讓 Codex 在審查程式碼時更容易發現問題,也更能遵循團隊慣例。

作者: Hari Srikanth

自訂 Codex 程式碼審查規則

用 Codex 審查程式碼時,有些意見會一再出現。可能是要維持舊版 API 契約、避免把客戶資料寫入日誌,或是提醒作者,改名會讓另一個服務無法正常運作。這些檢查很重要,但如果只有少數審查者知道背後的原因,就很容易漏掉。

現在,Codex 程式碼審查可以依據 AGENTS.md 中的程式碼庫自訂規則找出這些問題,並指出審查意見所依據的指引。如果你已經用 AGENTS.md 指引程式開發任務,同一個檔案也能用來指引審查。當貢獻者或程式開發智慧體著手修改程式碼庫中不熟悉的部分、還不了解過去的設計考量時,這些規則尤其有幫助。本文會說明程式碼庫規則在審查中扮演的角色、如何撰寫有效的規則,以及我們在測試中學到的經驗。

交付更多程式碼

程式開發智慧體能處理規模更大的變更,也能持續執行耗時較長的任務,幫助團隊把更多構想化為程式碼。自第四季以來,OpenAI 每週的 PR 數量已超過原來的兩倍,我們也在許多客戶的團隊中看到類似趨勢。產出更多程式碼有其好處:團隊能推出新功能,解決更多問題。但這也意味著有更多 pull requests 在等待熟悉審查重點的人處理,程式碼審查很快就可能成為瓶頸。

三個季度以來,每週的 PR 數量呈上升趨勢

多項變更同時送審時,審查就更困難。從差異內容來看,一項變更可能完全合理,卻會讓舊版用戶端無法正常運作,或越過作者不知道的界線。必須有人記得這些背景,並在作者還來得及調整時提醒對方。

審查瓶頸

送審的 pull requests 越多,審查者在提供意見前,就越沒有時間釐清每項變更的目的並蒐集相關背景。一旦作者轉去處理其他工作,即使只是小幅修改,也可能花上更長時間。及早提供意見,能讓團隊充分受益於更快的開發速度,也能避免工作卡在等人審查的環節。

有些問題光看差異內容也很難發現。重新命名回應欄位,看似只是例行整理,卻可能讓仍依賴既有契約的用戶端無法正常運作。經驗豐富的審查者或許記得為什麼必須保留這個欄位,新加入的貢獻者或第一次修改這項服務的智慧體很可能不知道。

用規則傳達審查指引

團隊成員通常要靠經驗逐漸熟悉這些背景,要怎麼讓程式開發智慧體也掌握這些資訊?新的程式碼庫規則介面讓你能在 AGENTS.md 中寫下簡短、適用範圍明確的審查指引。Codex 程式碼審查可以套用與變更相關的規則,並在指出問題時引用規則。把說明放在適用的程式碼附近,就不必在每個 pull request 裡重複解釋。

隨著程式開發模型越來越能依照指示行事,即使審查耗時很長,一條簡短、範圍明確的指示也能讓模型專注於團隊真正關心的問題。Codex 自己的程式碼庫就將程式碼審查規則寫在 AGENTS.md 中,涵蓋模型可見的上下文、破壞相容性的變更等議題。

來看一個實際例子:

Codex App Server 會發出名為 rawResponseItem/completed 的內部通知。這項通知雖然標示為實驗性功能,Codex 雲端卻已經在使用。程式碼庫的破壞相容性變更審查規則明確指出,rawResponseItem/* 是外部系統用來整合的介面,即使仍處於實驗階段,審查者也應確保介面得以保留。

App Server 通訊協定定義了傳輸時使用的既有通知名稱。假設有人在整理程式碼時改了這一行:

-RawResponseItemCompleted => "rawResponseItem/completed"
+RawResponseItemCompleted => "rawResponseItem/done"

這項變更可以通過編譯,但監聽既有通知的用戶端將收不到通知。程式碼庫中對應的規則很簡短,節錄如下:

## Code Review Rules

### Breaking changes

Search for breaking changes in external integration surfaces:

- raw response item events (`rawResponseItem/*`), even while experimental

針對上述差異,程式碼審查可能會提出這樣的意見:

請保留既有的 rawResponseItem/completed 通知。 Codex 雲端元件會透過這個名稱監聽通知。即使事件仍處於實驗階段,改名也會讓這些元件收不到事件。請依照 AGENTS.md 的說明,保留既有名稱,或新增一個回溯相容的事件。

Codex 團隊特別加入這條規則,以保護 Codex 雲端中使用這項通知的元件。適用於整個程式碼庫的規則應放在根目錄,僅適用於特定服務的規則則放在該服務的目錄。審查時,Codex 可以根據有變動的檔案套用指引,並指出作者應參考哪條規則。審查無關的變更時,也就不需要 App Server 的背景資訊。

團隊可以搭配既有工具使用規則。對於能以明確條件判定結果的檢查,測試和靜態分析工具很有效;程式碼庫規則則適合記錄較難用程式表達的判斷準則。相容性要求和資料使用界線都是很好的起點。有了相關指引,作者不必先了解過去每一次事故或每個目錄的慣例,才能動手修改。

撰寫能長期發揮作用的規則

我們用一套評估案例測試程式碼審查運用程式碼庫指引的成效,其中既有已知違規案例,也有看似相近但符合規則的反例。在主要評估案例中,有規則指引的各個版本找出了 98% 應依自訂規則指出的問題,基準對照組則找出了 58.3%。

找出違規只是審查工作的一部分。我們也想知道,當審查需要同時兼顧多條規則,或 pull request 本身就包含許多變更時,結果會如何。我們測試了違規後果嚴重的案例,也測試了無須干預的變更,並從以下四個問題整理結果:

評估項目

涵蓋率

當差異內容繁多,又需要兼顧多條規則時,Codex 能否找出預期應辨識的違規問題?

避免誤報

對於沒有問題的變更和符合條件的例外,Codex 能否避免提出不必要的審查意見?

既有能力的保留程度

程式碼審查是否仍能找出程式碼庫規則未涵蓋的一般錯誤?

意見是否可據以行動

每則審查意見是否都指出了相關指引、問題位置和優先順序?

我們也試過幾種常見的指引寫法,包括簡短的條列清單,以及由特定團隊負責維護的章節。

在內部程式碼庫使用規則時,我們也觀察到相同的情況。Codex 能找到並引用預設審查可能忽略的個別目錄指引,但指示過於籠統,很容易產生多餘的審查意見。如果規則數量少、範圍明確,並且寫清楚哪些做法是安全的,Codex 就能專注於最有幫助的問題,避免把規則套用到附近的每一項變更。

先寫下容易忽略、違反後果卻很嚴重的必要條件。 把審查者一再解釋的檢查事項寫成規則,例如相容性要求或資料使用界線。如果拿掉某條規則也不影響審查結果,就不必加入。

只讓規則適用於它所規範的程式碼。 適用於整個程式碼庫的指引應放在根目錄,特定服務的指引則寫在子目錄的 AGENTS.md 中。縮小適用範圍,可以避免無關指示分散注意力,也能清楚看出規則由誰負責。

寫清楚必須維持的條件和安全做法。 rawResponseItem/* 規則點出了相容性風險。「保留既有名稱,或新增一個回溯相容的事件」則讓作者知道還有哪些可行的做法。

讓規則經得起時間考驗,並適時更新。 寫清楚必須達成的結果,避免以日後可能更名的函式來定義規則。規則更新時也應加以審查;如果某項指引反覆產生多餘的意見,就縮小它的適用範圍,或將它移除。

格式和其他機械式檢查交由 CI 處理。程式碼庫規則應用來回答審查者原本得一再提出的問題。

開始使用

如果你的程式碼庫已啟用 Codex 程式碼審查,請在適用的 AGENTS.md 檔案中加入兩三條規則,再建立一個具代表性的 pull request。如果你是第一次使用程式碼審查,可以參閱程式碼審查快速入門指南,了解如何為 GitHub 程式碼庫啟用這項功能。你也可以直接用 @codex review 要求審查。

先從審查者一再給出的說明著手,或挑一個這個程式碼庫特有、漏掉就會造成嚴重後果的錯誤。試著送審三種變更:一個應該觸發規則的案例、一個符合規則的安全反例,以及一個與規則無關的變更。確認第一個案例能得到有用的審查意見,另外兩個不會產生多餘意見,再根據觀察結果調整指引。

Codex 程式碼審查可作為額外的審查者。測試、分支保護和必要核准等機制會繼續強制執行相關要求。

如果你花在審查變更上的時間比撰寫程式碼還多,可以先挑一項團隊反覆提醒的檢查事項。把它寫進 AGENTS.md,然後在下一個 pull request 試用 Codex 程式碼審查。