私たちは Codex を使って、OpenAI Agents SDK リポジトリのメンテナンス方法を変えています。リポジトリ内のスキル、AGENTS.md、GitHub Actions を組み合わせることで、検証、リリース準備、サンプルの結合テスト、PR レビューといった繰り返し発生する開発作業を、繰り返し実行できるワークフローにまとめています。かなりシンプルな構成でも、活発に開発が進むこれらのリポジトリで、開発スループットの向上につながっています。2025 年 12 月 1 日から 2026 年 2 月 28 日までに両リポジトリでマージされた PR は 457 件で、その前の 3 か月間にあたる 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は、コードやビルドの動作が変わったときに、必須のフォーマット、Lint、型チェック、テストを一通り実行します。docs-syncは、ドキュメントをコードベースと照合し、不足、誤り、古くなった記述を見つけます。examples-auto-runは、ログと再実行用のヘルパーを備えた自動モードでサンプルを実行します。final-release-reviewは、前回のリリースタグと現在のリリース候補を比較し、リリースの準備が整っているかを確認します。implementation-strategyは、ランタイムや API の変更に着手する前に、互換性を維持する範囲と実装方針を決めます。openai-knowledgeは、公式の Docs MCP ワークフローを通じて、OpenAI API とプラットフォームの最新ドキュメントを取得します。pr-draft-summaryは、作業の引き継ぎ時に、ブランチ名の候補、PR タイトル、説明文の下書きを用意します。test-coverage-improverは、カバレッジを測定して特に不足している箇所を見つけ、効果の高いテストを提案します。
JavaScript リポジトリも基本的には同じ構成ですが、npm モノレポとリリースプロセスに合わせて、リポジトリ固有のスキルをいくつか追加しています。
changeset-validationは、チェンジセットとバージョンの引き上げレベルが、パッケージの実際の差分に合っているかを確認します。integration-testsは、ローカルの Verdaccio レジストリにパッケージを公開し、サポート対象のランタイムでインストールから実行までの動作を検証します。pnpm-upgradeは、pnpm ツールチェーンと CI で固定しているバージョンを、整合性を保ちながら更新します。
個々のスキルの顔ぶれよりも重要なのは、その構成パターンです。各スキルには、範囲を絞った役割と要件、明確な実行条件、具体的な出力があります。
特に役立つスキルの中には、必須の合格条件を課さないものもあります。docs-sync と test-coverage-improver は、まず報告を行うワークフローです。現在の差分やカバレッジの成果物を調べ、重要な事項に優先順位を付け、編集に入る前に承認を求めます。Python リポジトリでは、docs-sync は生成済みの出力を手作業で修正せず、ソースコード内の docstring とコメントを、生成するリファレンスドキュメントの正本として扱います。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 testsJavaScript リポジトリでは、スキルが次の順序を厳密に指定しています。
pnpm i
pnpm build
pnpm -r build-check
pnpm -r -F "@openai/*" dist:check
pnpm lint
pnpm testスキルは、そのリポジトリにおける「検証済み」の定義を明文化し、AGENTS.md はその定義の遵守を義務付けます。
チェンジセットの検証
JavaScript リポジトリでは、パッケージを変更する際にもう一つ必須の手順があります。Changesets を中心に構成された $changeset-validation です。
packages/ 配下に変更があった場合や、.changeset/ が変わった場合、モデルはテストを実行するだけでは不十分です。適切なチェンジセットを作成または更新し、バージョンの引き上げレベルを検証したうえで、チェンジセットが実際の差分に合っているかを確認する必要があります。
このスキルは、ファイルの存在を確認するだけではありません。Codex に git diff の評価を求め、ローカル実行と GitHub Actions で同じロジックを使えるよう、検証ルールを共通のプロンプトにまとめています。また、次のようなリポジトリ固有のポリシーも定義しています。
- ブランチにチェンジセットがすでに存在する場合は、別のものを作成せず、既存のものを使用
- コミットタイトルとしても使えるよう、概要は Conventional Commit 形式の 1 行に集約
- 1.0 より前は、通常の機能開発でのメジャーバージョンの引き上げを避け、プレビュー専用と明示された追加機能は、既存の動作を変えない場合にパッチ変更として扱う
- パッケージの実際の変更内容と照らし合わせて、必要なバージョンの引き上げレベルを検証
これにより、Codex は作業の完了を報告する前に、自ら作成したリリースのメタデータを検証する責任を負います。
最新ドキュメントの活用
両リポジトリでは、OpenAI API やプラットフォームとの連携に関わる作業で、$openai-knowledge の使用も必須にしています。
このスキルは、公式の OpenAI Docs MCP に最小限の手順を加えたものです。モデルが記憶に頼って回答するのではなく、OpenAI Developer Documentation MCP サーバーを使って、Responses API、ツール、ストリーミング、Realtime、MCP などの最新ドキュメントを調べるよう Codex に指示します。
ローカルの Codex 環境で MCP サーバーがまだ設定されていない場合、このスキルはメンテナーに Docs 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 フィールドは、スキル選択のルールの一部です。
これは文体ではなく、構造に関わる話です。Agent Skills 仕様では、name と description を SKILL.md のフロントマターの必須フィールドとしています。また、段階的に情報を開示するモデルに従い、起動時にはすべてのスキルについてこれらのフィールドを読み込むと定めています。SKILL.md の本文全体や scripts/、references/、assets/ が読み込まれるのは、その後、スキルが実際に起動されたときだけです。
Codex のスキルのドキュメントとカスタマイズのドキュメントでは、同じ動作を Codex の側から説明しています。Codex はまず各スキルのメタデータを使ってスキルを見つけ、選択したときに初めて SKILL.md を読み込みます。参照資料の読み込みやスクリプトの実行は、必要なときにのみ行います。OpenAI API でのスキルの活用を紹介する Cookbookでも、ホスト型シェル側の動作が同じように明確に説明されています。OpenAI は最初に各スキルの name、description、パスを読み取り、モデルはその情報を使って SKILL.md 全体を読むタイミングを判断します。同じ Cookbook のSKILL.md のフロントマターのセクションでは、この点をより直接的に述べています。name と description は、スキルの発見と選択に重要です。
このため Agents SDK のリポジトリでは、Codex がスキルの残りの部分を読む前に、description がスキル選択の主な判断材料の 1 つになります。
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 に伝わります。しかし、どのような場面で適用するのか、どのような変更で起動すべきなのか、チェックが任意なのかは伝わりません。より具体的な説明では、この 3 点すべてをモデルに伝えています。
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 にそのまま使える形式で出力すること
これらのリポジトリから得られる実践的な教訓の 1 つは、description の記述に時間をかけることです。スキルの選択が安定しないと感じたら、コードを増やす前にメタデータを修正しましょう。
定型処理のスクリプト化
次に考えるのは、何をモデルに任せ、何をスクリプトに移すべきかです。
次のように分担すると、安定して機能します。
- 解釈、比較、報告はモデルに任せる
- 決まった手順で繰り返すシェル作業は
scripts/にまとめる
これは公開されているガイダンスとも一致しています。Codex のカスタマイズのドキュメントでは、スキルは、最初からコンテキストを膨らませることなく、繰り返し使うワークフローのための詳しい指示、スクリプト、参照資料を Codex に提供する方法だと説明しています。これはモデルを中心とした構成に適しています。文脈に依存する作業は Codex に任せ、決まった手順で処理する部分には、必要なときだけスクリプトを使います。OpenAI API でのスキルの活用を紹介する Cookbookでも、スキルのスクリプトを小さな CLI として設計することを推奨しています。コマンドラインから実行でき、同じ入力に対して同じ標準出力を返し、失敗時には使用方法やエラーメッセージを明確に表示し、必要に応じて所定のファイルパスに結果を書き出すスクリプトです。
Agents SDK のリポジトリでは、モデルの知的な判断が実際に役立つ場面でモデルを使うようにしています。たとえば、次のような作業です。
- ソースコードを読んで意図された動作を推測する
- ログと意図された動作を比較する
- リリースの差分に互換性を損なう実際のリスクがあるかを判断する
- メンテナーが具体的な対応を取れるように説明する
その周辺の定型処理はスクリプトが担当します。たとえば、次のような作業です。
- リポジトリで必須の検証コマンドを決まった順序で実行する
- サンプルの実行を開始し、サンプルごとのログを収集して、失敗したものの再実行用ファイルを作成する
- リリース可否のレビュー前に、前回のリリースタグを取得する
- 同じワークフローを簡単に繰り返し実行できるよう、
start、stop、status、logs、tail、collect、rerunなどの補助コマンドを用意する
モデルが毎回同じシェルの手順を考え直しているなら、多くの場合、その手順をスクリプトにすべきだというサインです。文脈やトレードオフを踏まえた判断、説明が必要な部分は、モデルに任せるべきです。
統合テストの自動化
両リポジトリで特に役立っているワークフローの 1 つが、統合テストの自動化です。ここには関連する 2 つの層があります。両リポジトリでリポジトリ内のサンプルを自動検証する層と、JavaScript リポジトリで、公開したパッケージをユーザーと同じ方法でインストールしても正しく動作するかを別途検証する層です。
この仕組みを導入する前は、サンプルの検証に手作業が残っていました。サンプル自体は実行できても、最後の確認はログを目視したり、出力を見て正しそうかを判断したりすることに頼りがちでした。サンプルが 1 つなら対応できますが、拡大し続ける SDK リポジトリ全体では、この方法はうまく機能しません。
最初の層は examples-auto-run ですが、スキルを作ったのはランナーを作った後です。サンプル検証を自動化するには、まず両リポジトリでサンプルを非対話形式で実行できる基盤を整える必要がありました。通常は入力や承認が必要なサンプルも含め、サンプルスクリプトを自動モードで実行できるようにしたのです。
その基盤には、次の機能を含めました。
- よくある対話型プロンプトへの自動回答
- ランナーが対応している場合に、HITL、MCP、
apply_patch、シェルのアクションを自動承認 - 追加の実行環境のセットアップが必要なリアルタイム処理や 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 を実行します。
検証の質を高めるため、ランナーはサンプルを実行し、その標準出力と標準エラー出力をサンプルごとのログに保存する役割を担います。その後、スキルは Codex にログを 1 つずつ確認させ、次の手順でソースコードと比較させます。
- サンプルのソースコードとコメントを読む
- 意図された処理の流れを推測する
- 対応するログを開く
- 意図された動作と実際の標準出力および標準エラー出力を比較する
- 1 つのサンプルだけでなく、正常終了したすべてのサンプルでこの確認を行う
これは、正しさの判定をスクリプト内の固定的なアサーションとして記述するよりも正確で柔軟です。成功を示す終了コードは有用ですが、実際の API と通信したり、ツールを使ったり、構造化出力を生成したりするサンプルでは、それだけでは十分ではありません。まず実際の出力を記録し、その後ソースコードと慎重に照らし合わせることで、各サンプルを本来の意図に沿って検証できます。
JavaScript リポジトリには、さらに 2 つ目の層として、独立した 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 の引き継ぎが、繰り返し実行できる同じプロセスに沿って進むようになり、小さな改善をより速く届けやすくなっています。