我們使用 Codex 改變維護 OpenAI Agents SDK 程式碼庫的方式。透過存放在程式碼庫內的技能、AGENTS.md 和 GitHub Actions，我們將驗證、版本發布準備、範例整合測試和 PR 審查等例行工程工作，轉化為可重複執行的工作流程。即使設定相當簡單，也幫助我們提高了這些活躍程式碼庫的開發吞吐量。2025 年 12 月 1 日至 2026 年 2 月 28 日期間，兩個程式碼庫共合併了 457 個 PR，高於前三個月（2025 年 9 月 1 日至 2025 年 11 月 30 日）的 316 個（Python：182 -> 226，TypeScript：134 -> 231）。
先簡單介紹背景：這套 SDK 提供 Python 和 TypeScript 版本。它提供建構智慧體式應用程式所需的核心元件，也讓開發者能以精簡的方式，在 Realtime API 上建構支援多個智慧體、工具和人為介入控制的語音智慧體。它的使用規模相當可觀：截至 2026 年 3 月 6 日，在近期各自的 30 天統計期間內，Python 套件在 PyPI 上約有 1,470 萬次下載，TypeScript 套件在 npm 上則約有 150 萬次下載。
設定很簡單：
- 在
AGENTS.md中定義程式碼庫政策 - 在
.agents/skills/中存放程式碼庫專用技能 - 視需要在這些技能中加入指令碼和參考資料
- 需要在 CI 中執行相同工作流程時，使用 Codex GitHub Action
這套設定為 Codex 提供穩定的上下文，讓它了解程式碼庫的運作方式，進而提高例行工程工作的速度與準確性。
如果你維護公開的開源專案，請參閱 Codex for OSS。符合資格的維護者可以申請包含 Codex 的 ChatGPT Pro、 API 點數，以及有條件提供的 Codex Security 存取權。
將工作流程存放在程式碼庫中
在這些程式碼庫中，我們使用技能來記錄各自專用的工作流程。技能是一小套操作知識，包含一份 SKILL.md 資訊清單，以及選用的 scripts/、references/ 和 assets/。Codex 自訂文件說明了這種做法為何有效：技能很適合可重複執行的工作流程，因為它能提供更豐富的指示、指令碼和參考資料，又不會一開始就讓智慧體的上下文過於龐大。
這符合技能採用的漸進式揭露模式：
- 先查看
name和description等中繼資料 - 只有在選用技能時，才載入
SKILL.md - 只有在需要時，才閱讀參考資料或執行指令碼
兩個 SDK 程式碼庫都將這些工作流程與程式碼存放在一起：
Python 程式碼庫提供了較簡單的基礎範例：
code-change-verification會在程式碼或建置行為變更時，執行必要的格式化、程式碼檢查、型別檢查和整套測試。docs-sync會對照程式碼庫檢查文件，找出缺漏、錯誤或過時的內容。examples-auto-run會以自動模式執行範例，並提供記錄和重新執行的輔助工具。final-release-review會比較上一個發布版本的標籤與目前的候選版本，檢查是否已準備好發布。implementation-strategy會在修改執行階段或 API 之前，決定相容性界線和實作方式。openai-knowledge會透過官方文件 MCP 工作流程，取得最新的 OpenAI API 和平台文件。pr-draft-summary會在交接時準備分支名稱建議、PR 標題和說明草稿。test-coverage-improver會執行覆蓋率檢查，找出最大的缺口，並提出最有助益的測試建議。
JavaScript 程式碼庫大致遵循相同模式，並針對其 npm monorepo 和發布流程，加入幾項程式碼庫專用技能：
changeset-validation會檢查 changeset 和版本升級層級是否確實符合套件差異。integration-tests會將套件發布至本機 Verdaccio 套件登錄庫，並驗證套件在各個支援的執行環境中的安裝與執行行為。pnpm-upgrade會同步更新 pnpm 工具鏈和 CI 中固定使用的版本。
比起具體的技能清單，更重要的是這套模式：每項技能都有範圍明確的契約、清楚的觸發條件，以及具體的輸出。
有些最實用的技能並非強制關卡。docs-sync 和 test-coverage-improver 都是先提供報告的工作流程：它們會檢查目前的差異或覆蓋率產出資料，排定重要事項的優先順序，並在修改前要求核准。在 Python 程式碼庫中，docs-sync 也以原始碼中的文件字串和註解作為產生參考文件的權威來源，而不是手動修補產生的內容。JavaScript 專用的 pnpm-upgrade 技能則是另一個範圍明確的維護工作流程範例：它會一併更新本機 pnpm 版本、packageManager 和工作流程中固定使用的版本，而不是採用大範圍的搜尋與取代。
將工作流程列為必要步驟
當程式碼庫要求在適當時機使用技能，技能就能發揮更大的作用。這正是 AGENTS.md 的用途。
AGENTS.md 指南將這類檔案描述為隨程式碼庫一同保存的程式碼庫層級指示，並在智慧體開始工作前就生效。指南也建議保持內容精簡。在 Agents SDK 程式碼庫中，我們用這些檔案記錄 Codex 每次都應遵循的規則，並將最有價值的規則放在靠近開頭的位置。
實務上，兩個程式碼庫都用簡短的「如果／那麼」規則，規定何時必須使用技能。修改執行階段或 API 之前，先呼叫 $implementation-strategy，決定相容性界線和實作方式。如果變更影響 SDK 程式碼、測試、範例或建置行為，就呼叫 $code-change-verification。如果 JavaScript 套件變更影響發布中繼資料，就呼叫 $changeset-validation。如果工作涉及 OpenAI API 或平台整合，就呼叫 $openai-knowledge。工作完成並準備好交接時，則呼叫 $pr-draft-summary。
這個結構也符合 agents.md 的建議：將專案概覽、建置與測試指令、程式碼風格、測試指引、安全性考量，以及其他程式碼庫專用規則集中在同一處。Agents SDK 程式碼庫遵循這種架構，但會將日常工作中最重要的操作觸發條件放在開頭。精簡版本如下：
# AGENTS.md
## Project overview
- Core SDK code lives under `src/agents/` or `packages/*/src/`.
- Tests live under `tests/` or `packages/*/test/`.
- Sample apps and integration surfaces live under `examples/`.
## Mandatory skill usage
- Use `$implementation-strategy` before editing runtime or API changes that may affect compatibility boundaries.
- Run `$code-change-verification` when runtime code, tests, examples, or build/test behavior changes.
- Use `$openai-knowledge` for OpenAI API or platform work.
- Use `$pr-draft-summary` when substantial code work is ready for review.
## Build and test commands
- Python: `make format`, `make lint`, `make typecheck`, `make tests`
- TypeScript: `pnpm i`, `pnpm build`, `pnpm -r build-check`, `pnpm lint`, `pnpm test`
## Compatibility rules
- Preserve positional compatibility for public constructors and dataclass fields.實際檔案會在這個基礎上加入程式碼庫專用的細節，例如 JavaScript 程式碼庫中的 $changeset-validation，以及兩份檔案中更詳細的執行階段、文件和發布指引。若要查看完整範例，請參閱 openai-agents-python 中的 AGENTS.md 和 openai-agents-js 中的 AGENTS.md。
AGENTS.md 不只用來設定技能觸發條件。Python 程式碼庫也在其中記錄了一項公開 API 相容性規則：保留匯出的建構函式參數與 dataclass 欄位的位置語意；新增選用參數或欄位時，盡可能加在末尾；若無法避免重新排序，則加入相容性測試。這也是一種值得採用的模式：將對發布至關重要的相容性規則，與技能觸發條件存放在同一處。
驗證規則
$code-change-verification 就是一個清楚的例子。
在這兩個程式碼庫中，規則並不是「一律執行冗長的整套驗證」，而是「當執行階段程式碼、測試、範例，或建置／測試行為變更時，執行驗證，且必須通過後才能將工作標示為完成」。
設定觸發條件，讓僅修改文件的工作不必負擔繁重流程；強制要求則確保 SDK 程式碼變更都會經過程式碼庫的標準驗證步驟。
實際的整套驗證步驟都定義在技能本身。
在 Python 程式碼庫中，技能要求執行：
make format
make lint
make typecheck
make tests在 JavaScript 程式碼庫中，技能要求嚴格依照以下順序執行：
pnpm i
pnpm build
pnpm -r build-check
pnpm -r -F "@openai/*" dist:check
pnpm lint
pnpm test技能明訂程式碼庫對「已驗證」的定義，而 AGENTS.md 讓這個定義成為必須遵守的要求。
Changeset 驗證
JavaScript 程式碼庫對套件變更還有一個必要步驟：以 Changesets 為基礎的 $changeset-validation。
當 packages/ 下的任何內容變更，或 .changeset/ 有變更時，模型不能只執行測試。它還必須建立或更新適當的 changeset、驗證版本升級層級，並確認 changeset 確實符合差異內容。
這項技能不只是檢查檔案是否存在。它要求 Codex 評估 git diff，並將驗證規則放在共用提示詞中，讓本機執行與 GitHub Actions 使用相同的邏輯。它也明訂程式碼庫專用政策，例如：
- 分支中已有 changeset 時，使用現有的 changeset，不要另建一份
- 摘要保持單行，採用 Conventional Commit 風格，以便同時用作提交標題
- 在 1.0 之前，一般功能開發應避免升級主要版本；明確標示為僅供預覽的新增功能，若未改變現有行為，則視為修補版本變更
- 根據套件的實際變更，驗證所需的版本升級層級
如此一來，Codex 必須先驗證自己建立的發布中繼資料，才能宣告工作完成。
使用最新文件
當工作涉及 OpenAI API 或平台整合時，兩個程式碼庫也都要求使用 $openai-knowledge。
這項技能只在官方 OpenAI 文件 MCP 外加上一層簡單封裝。它不讓模型憑記憶作答，而是指示 Codex 使用 OpenAI 開發者文件 MCP 伺服器，查閱 Responses API、工具、串流、Realtime 和 MCP 等介面與功能的最新文件。
如果本機 Codex 環境尚未設定 MCP 伺服器，技能會引導維護者參閱文件 MCP 快速入門和官方 MCP 伺服器端點。
準備 PR 交接資料
完成實質工作後，兩個程式碼庫都會使用 $pr-draft-summary。
這項技能只會在任務實際上已完成或可供審查，且變更涉及實質的程式碼、測試、範例、影響行為的文件或建置／測試組態時觸發。接著，它會自動收集分支名稱、工作樹狀態、變更的檔案、差異統計和近期提交，並產生：
- 建議的分支名稱
- PR 標題
- PR 說明草稿
輸出格式刻意採用嚴格規範。典型的結果如下：
# Pull Request Draft
## Branch name suggestion
git checkout -b fix/tracing-lazy-init-fork-safety
## Title
fix: #2489 lazily initialize tracing globals to avoid import-time fork hazards
## Description
This pull request fixes import-time tracing side effects that could break fork-based process models by moving tracing bootstrap to lazy, first-use initialization.
It updates tracing setup so initialization happens once on first access while preserving the existing public tracing APIs.
It also adds regression tests for import-time behavior, one-time bootstrap, and custom provider handling.
This pull request resolves #2489.當你信任模型能驗證並總結自己的工作後，請它產生 PR 草稿就成了順理成章的最後一步。這能讓交接資料保持一致，也能減少程式碼編寫完成後的重複撰寫工作。
撰寫更好的描述
技能的 SKILL.md 前置中繼資料中的 description 欄位，是路由契約的一部分。
這是結構上的要求，與文風無關。智慧體技能規格將 name 和 description 列為 SKILL.md 前置中繼資料的必要欄位，其漸進式揭露模型也規定，啟動時會載入所有技能的這些欄位。完整的 SKILL.md 本文，以及任何 scripts/、references/ 或 assets/，則要等到技能實際啟用時才會載入。
Codex 技能文件和自訂文件也從 Codex 的角度說明了相同的行為：Codex 先透過各項技能的中繼資料探索可用技能，選定技能後才載入 SKILL.md，並且只在需要時讀取參考資料或執行指令碼。OpenAI API 技能 Cookbook對託管 Shell 環境的說明同樣明確：OpenAI 會先讀取各項技能的 name、description 和路徑，模型再根據這些資訊，決定何時讀取完整的 SKILL.md。其中的 SKILL.md 前置中繼資料一節更直接指出：name 和 description 對技能探索與路由很重要。
因此，在 Agents SDK 程式碼庫中，Codex 尚未讀取技能的其餘內容前，description 就是決定路由的主要依據之一。
以下是 code-change-verification 的具體範例。
過於含糊：
description: Run the mandatory verification stack in the OpenAI Agents JS monorepo.更好的版本（實際使用的描述）：
description: Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents JS monorepo.較短的版本已經告訴 Codex 這項技能的用途，但仍未說明技能何時適用、哪些變更應觸發技能，以及這些檢查是否可省略。更具體的版本則將這三點都交代清楚。
pr-draft-summary 也採用相同的模式。
過於含糊：
description: Create a PR title and draft description for a pull request.更好的版本（實際使用的描述）：
description: Create a PR title and draft description after substantive code changes are finished. Trigger when wrapping up a moderate-or-larger change (runtime code, tests, build config, docs with behavior impact) and you need the PR-ready summary block with change summary plus PR draft text.同樣地，實際使用的描述就是路由中繼資料。它會告訴 Codex：
- 這是在任務收尾時使用的技能
- 它適用於實質變更，而非每一輪對話
- 輸出是可直接用於 PR 的內容區塊，而非單純的文字摘要
這些程式碼庫帶來的一個實務心得是：值得花時間寫好 description。如果路由表現不可靠，先修正中繼資料，再考慮增加程式碼。
將固定操作交給指令碼
接下來的問題是，哪些工作應交給模型，哪些應交由指令碼處理。
一種可靠的分工方式是：
- 解讀、比較和報告仍由模型負責
- 將結果確定、需要重複執行的 Shell 工作寫入
scripts/
這與公開指引一致。Codex 自訂文件說明，技能能為可重複執行的工作流程提供更豐富的指示、指令碼和參考資料，而不會在一開始就讓上下文過度膨脹。這適合以模型為主的工作方式：讓 Codex 處理工作中需要依上下文判斷的部分，只有在需要時才引入指令碼，處理結果確定的部分。OpenAI API 技能 Cookbook也建議將技能指令碼設計成小型 CLI：從指令列執行、產生結果確定的 stdout 輸出、失敗時明確顯示用法或錯誤訊息，並在需要時將輸出寫入已知的檔案路徑。
在 Agents SDK 程式碼庫中，我們盡量將模型用在確實能發揮其智慧的地方，例如：
- 閱讀原始碼，推斷預期行為
- 將記錄與預期行為進行比較
- 判斷版本差異中是否存在實際的相容性風險
- 提供維護者能據以採取行動的說明
指令碼則負責這些工作所需的固定操作，例如：
- 依固定順序執行程式碼庫要求的驗證指令
- 啟動範例執行、收集各個範例的記錄，並為失敗的範例寫入重跑檔案
- 在審查版本是否已準備好發布之前，擷取上一個版本的標籤
- 提供
start、stop、status、logs、tail、collect和rerun等輔助指令，方便反覆執行同一套工作流程
如果模型每次都得重新摸索同一套 Shell 操作步驟，通常就表示這些步驟應該寫成指令碼。如果任務需要依據上下文判斷、權衡取捨或提供說明，這部分就應繼續交由模型處理。
將整合測試自動化
在這兩個程式碼庫中，自動化整合測試是最實用的工作流程領域之一。這裡有兩個相關層次：一是在兩個程式碼庫中自動驗證庫內範例；二是在 JavaScript 程式碼庫中，另外驗證已發布的套件按使用者實際採用的方式安裝後，是否仍能正常運作。
採用這套做法之前，範例驗證有一部分需要手動進行。雖然可以執行範例，但最後往往還是得靠人工查看記錄，或檢視輸出來判斷結果看起來是否正確。只有一個範例時，這樣做還應付得來；面對持續成長的 SDK 程式碼庫，就難以擴展。
第一層是 examples-auto-run，但我們先建立了執行器，之後才有這項技能。要讓範例驗證能夠自動化，我們首先必須在兩個程式碼庫中建立基礎支援，讓範例能以非互動方式執行。這表示範例指令碼必須能以自動模式執行，包括通常需要互動提示或核准的範例。
這些基礎工作包括：
- 自動回應常見的互動提示
- 在執行器支援的情況下，自動核准 HITL、MCP、
apply_patch和 Shell 動作 - 將仍不適合自動化的範例保留在自動略過清單中，例如需要額外執行環境設定的即時功能範例或 Next.js 應用程式範例
- 為每次範例執行寫入結構化記錄
- 產生重跑檔案，以便只重試失敗的範例，不必全部重新執行
基礎建置完成後，我們將它整理成一項技能，讓工作流程能重複使用且容易呼叫。在 Python 程式碼庫中，examples-auto-run 封裝了 uv run examples/run_examples.py --auto-mode --write-rerun --main-log ... --logs-dir ...。在 JavaScript 程式碼庫中，它則封裝了建置檢查，接著以自動模式執行 pnpm examples:start-all，並支援為各個範例記錄輸出與重新執行。
為了提升驗證品質，執行器負責執行範例，並將各個範例的 stdout 和 stderr 保存在各自的記錄中。接著，技能會讓 Codex 逐一查看這些記錄，並與原始碼比對：
- 閱讀範例原始碼與註解
- 推斷預期流程
- 開啟對應的記錄
- 將預期行為與實際的 stdout 和 stderr 比較
- 對每個成功執行的範例都進行上述檢查，而非只抽查一個
相較於嘗試在指令碼中用固定斷言判定正確性，這種做法更準確，也更靈活。表示成功的結束代碼固然有用，但對於會呼叫真實 API、使用工具或產生結構化輸出的範例來說，光靠它還不夠。先記錄實際輸出，再仔細對照原始碼檢查，就能依各個範例真正的設計意圖進行驗證。
JavaScript 程式碼庫還有第二層：獨立的 integration-tests 技能。這套工作流程不只直接在原始碼所在位置執行範例，還會將套件發布到本機 Verdaccio 套件登錄庫，並在多種環境中測試安裝與執行，包括 Node.js、Bun、Deno、Cloudflare Workers 和 Vite React 應用程式。它能找出另一類問題：關注的不是「範例能否在程式碼庫中執行？」，而是「套件經過發布、安裝及執行環境整合後，行為是否仍然正確？」
綜合來看，這些工作流程說明了結合技能、指令碼和模型判斷的價值。指令碼讓執行過程可重複、保留驗證證據，並涵蓋那些手動檢查十分繁瑣的安裝方式。Codex 再運用這些證據，進行更仔細的比對，超越指令碼中簡單的通過／失敗檢查。
加入發布檢查
發布準備也是這種模式能派上用場的領域。
這兩個程式碼庫的版本發布審查流程，都是先找出前一個版本的標籤，與最新的 main 比較差異，再請 Codex 檢查差異中是否有以下問題：
- 公開 API 與使用者可見的 SDK 行為中的向後相容性問題
- 回歸問題，包括預期行為的細微變化
- 需要提供遷移說明或更新版本說明的變更，卻缺少相關內容
技能會根據這些發現，綜合判斷是否已準備好發布版本。
openai/openai-agents-python#2480 就是一個具體例子：版本發布審查的整體結果仍為通過，但也指出已停止支援 Python 3.9，以及後續需要補上的版本說明：
Release readiness review (excerpt)
Release call:
🟢 GREEN LIGHT TO SHIP. Minor-version bump includes expected breaking change
(Python 3.9 drop) with no concrete regressions found.
Scope summary:
- 38 files changed (+1450/-789); key areas touched: `src/agents/tool.py`,
`src/agents/extensions/`, `src/agents/realtime/`, `tests/`,
`pyproject.toml`, `uv.lock`.
Python 3.9 support removed
- Risk: 🟡 MODERATE. Users pinned to Python 3.9 will be unable to install the
0.9.0 release.
- Evidence: `pyproject.toml` now sets `requires-python = ">=3.10"` and drops
the Python 3.9 classifier; CI skip logic for 3.9 was removed.
- Action: Ensure release notes clearly call out the Python 3.9 drop and that
packaging metadata remains `>=3.10`.這項技能也定義了如何決定是否放行。審查以「可安全發布」為起點，只有在差異中找到具體證據，顯示確實存在問題時，才會判定為阻擋發布。每次判定阻擋發布，都必須附上明確的解除阻擋檢查清單。這讓審查結果更容易運用：通過表示差異中未發現會阻擋發布的問題；阻擋則表示確實存在問題，而且有明確的下一步。
這比籠統地要求「請審查這次發布」更有用。它要求模型針對具體差異進行推理，並從實際操作的角度說明結果。如果可以安全發布，就明確說明；如果不行，就指出確切的證據，以及具體需要完成的後續工作。
在 CI 中執行工作流程
當一項技能在本機使用時能發揮效用，就能透過 Codex GitHub Action，輕鬆在 CI 中自動執行相同的工作流程。先讓本機工作流程穩定下來，效果最好，因為手動使用的過程正是修正指示、改善指令碼，以及找出實際邊界情況的機會。
對公開程式碼庫而言，觸發機制的設計與技能本身同樣重要。GitHub Action 安全性檢查清單建議：限制能啟動工作流程的人員、優先採用可信任的事件或明確核准、清理來自 PR、提交、議題或留言的提示詞輸入、透過 drop-sudo 或非特權使用者保護 OPENAI_API_KEY，並將執行 Codex 安排為作業的最後一步。
如果工作流程具有寫入能力，又接收不受信任的公開輸入，風險通常出在技能周邊的觸發機制設計、輸入處理方式與執行時權限。
在 PR 審查中使用 Codex
技能是提升這些程式碼庫生產力的一環，Codex GitHub PR 自動審查則是另一環。
自從 Codex GitHub PR 自動審查推出以來，Codex 在這些程式碼庫的大多數程式碼變更審查中，都提供了實質幫助。我們已將它納入日常審查流程，而非只在特殊情況下使用。
對於單純的程式錯誤、回歸問題與缺漏測試，現在依靠 Codex 完成必要審查，在實務上已足夠安全。它能反覆依照相同模式檢查正確性，並維持一致的表現，消除了小型修正與日常改進的一大瓶頸。
同儕審查依然重要，只是重點轉向了另一類變更。
當核心問題不是「這段程式碼是否正確？」，而是「幾個可行方案中該選哪一個，又該如何發布？」，人工審查仍不可或缺。這類情況包括：
- API 或架構變更有多種合理設計，需要維護者明確做出選擇
- 行為變更會影響對產品的預期、向後相容性承諾或推出政策
- 命名、遷移與版本發布溝通的決策，難點在於選擇對使用者與貢獻者最清楚易懂的做法
- 需要維護者或團隊之間達成共識的變更，例如界定工作範圍、安排執行順序，或決定哪些內容現在發布、哪些留待之後
在上述所有情況中，Codex 仍能提供有用的協助，但由人來決策並直接討論，依然大有幫助。
AGENTS.md 也能記錄這樣的分工：程式碼庫可以告訴 Codex，正確性審查應著重哪些事項，讓 Codex 一致地套用這些指引。
這也大幅提升了工作吞吐量。處理低風險變更時，重複性的審查與驗證工作不再每次都需要等待審查者排出有限的時間；維護者則能專注於需要掌握更多背景、也最仰賴其判斷的審查。這樣的轉變，讓我們能更快處理積壓的程式錯誤與小型功能改進。
結語
在 OpenAI Agents SDK 程式碼庫中，將技能納入日常工作設定，最能發揮其效用。
AGENTS.md 告訴 Codex 哪些工作流程必須執行；description 說明何時該採用這些流程；scripts/ 負責有確定規則可循的部分，模型則處理需要依據上下文判斷的部分。當工作流程在本機已穩定可靠，就能透過 Codex GitHub Action，將相同流程帶入 CI。
這讓這些程式碼庫的日常工程工作更明確、更可靠。驗證、版本發布審查與 PR 交接如今都遵循一致且可重複執行的流程，也讓我們更容易加快小型改進的發布速度。