openai-codex-rust-patterns

OpenAI Codex Rust ベストプラクティス

openai/codex の codex-rs/（Codex CLI コーディングエージェントを提供する、119 個のクレートと 2,008 個のファイルからなる Rust ワークスペース）から抽出した内容です。11 カテゴリにわたる 63 個のルールを収録しています。それぞれのルールには、パターンが記述されている codex-rs 内の正確なファイルを引用しているため、主要な貢献者（Michael Bolin、jif-oai、Ahmed Ibrahim、Eric Traut、Pavel Krymets）が実際にリリースしている方法に沿って Rust を書けます。引用は、コミット 8a94430（2026-05-25）の main を基に更新されています。

適用するタイミング

次のようなときは、これらのガイドラインを参照してください。

• tokio タスクを起動する、キャンセルトークンを所有する、または長時間実行されるバックグラウンドワーカーを管理する非同期 Rust コードを書く、あるいはレビューするとき。
• ライブラリやサービスで、エラー列挙型、Result のフロー、再試行ループ、またはレイヤー境界を設計するとき。
• サブプロセスを起動する、サンドボックス化を徹底する、または LLM が生成したコードを安全に実行する CLI ツールを構築するとき。
• 約 5 個を超えるクレートを含む Cargo ワークスペースを設計し、何を分離するか、共有依存関係をどう管理するかを決めるとき。
• 既存のテストがインラインの mod tests { ... } ブロックで書かれている Rust コードベースにテストを追加し、規模の拡大が負担になってきたとき。
• serde を使って JSON-RPC または独自のワイヤープロトコルを実装するとき。特に、クライアントを壊さずに進化させる必要がある場合。
• API キーなどのシークレットをメモリに読み込むとき、またはコアダンプ、デバッガーのアタッチ、LD_PRELOAD に対して、認証情報を扱うバイナリを強化するとき。
• DNS リバインディングに耐える必要があるネットワークの送信先許可リストを徹底するとき、または信頼できないプラグインや拡張機能を読み込むとき。
• PII に関するプライバシー制約があるサービスに、OpenTelemetry のトレース、ログ、またはメトリクスを組み込むとき。
• LLM の出力をストリーミングし、連続した貼り付け入力に対応し、または raw モードのターミナル状態を管理する Ratatui ベースの TUI を構築するとき。
• .unwrap()、.lock().unwrap()、anyhow::Result<()>、または #[cfg(feature = "test")] を使おうとしているときはいつでも。このスキルでは、codex が代わりに何をしているかを説明します。

優先度別ルールカテゴリ

優先度	カテゴリ	影響度	接頭辞
1	防御的コーディングとパニックの抑制	CRITICAL	defensive-
2	エラー処理と Result の規律	CRITICAL	errors-
3	非同期処理、並行性、キャンセル	HIGH	async-
4	サンドボックス化とプロセスの隔離	HIGH	sandbox-
5	シークレットとプロセスの強化	HIGH	secrets-
6	型設計と不変条件	HIGH	types-
7	テストアーキテクチャ	MEDIUM-HIGH	testing-
8	プロトコルと Serde の設計	MEDIUM-HIGH	proto-
9	ワークスペースとクレートの構成	MEDIUM	workspace-
10	可観測性とトレーシング	MEDIUM	otel-
11	TUI（Ratatui）のレンダリング	MEDIUM	tui-

クイックリファレンス

1. 防御的コーディングとパニックの規律（CRITICAL）

• defensive-deny-unwrap-workspace-wide — ワークスペース全体で unwrap と expect を禁止し、必要な場合は局所的に許可します。
• defensive-debug-assert-with-early-return — 到達不能な分岐では、セーフなフォールバックとともに debug_assert(false) を使用します。
• defensive-recover-poisoned-lock — 毒されたロックを unwrap せず、into_inner で復旧します。
• defensive-banned-interpreter-prefixes — 汎用インタープリター向けの許可リストルールを学習しないようにします。
• defensive-head-tail-output-buffer — ヘッドとテールを保持するリングバッファーで、サブプロセスの出力を制限します。
• defensive-io-drain-timeout-grandchildren — I/O ドレインタスクに、子プロセスとは別のタイムアウトを設定します。
• defensive-refuse-to-run-unsandboxed — サンドボックスで要求されたポリシーを適用できない場合は、実行を拒否します。
• defensive-canonicalize-approval-cache-key — 承認キーをハッシュ化する前に、シェルラッパーを正規化します。
• defensive-fault-isolate-plugin-load — プラグインの読み込み失敗を分離し、モデルに渡す前にマニフェストテキストをサニタイズします。

2. エラー処理と Result の規律（CRITICAL）

• errors-exhaustive-retryable-match — すべてのバリアントに対する網羅的な match で、再試行可能なエラーを分類します。
• errors-transient-permanent-type-split — 一時的な結果と永続的な結果を、2 つの enum バリアントとして表現します。
• errors-boundary-error-translator — 単一の関数で、レイヤー境界におけるエラーを変換します。
• errors-carry-retry-delay-in-variant — サーバーが要求した再試行待ち時間を、エラーバリアント内に保持します。
• errors-struct-display-payload — 表示に必要なエラー状態は、事前にフォーマットした文字列ではなく構造体に格納します。
• errors-tool-call-respond-vs-fatal — ツールエラーを、モデルへの応答用と致命的エラー用のバリアントに分けます。
• errors-io-error-with-context-struct — anyhow ではなく、コンテキストフィールドを持つ構造体で io::Error をラップします。

3. 非同期処理、並行処理、キャンセル（HIGH）

• async-abort-on-drop-handle — JoinHandle を AbortOnDropHandle として保持し、Drop 時にキャンセルします。
• async-graceful-then-forceful-cancel — まず協調的にキャンセルし、猶予期間の期限後に abort します。
• async-biased-select-for-cancellation — キャンセルが常に競合時に優先されるよう、biased select を使用します。
• async-bounded-vs-unbounded-channel-split — 送信チャネルには上限を設け、イベントチャネルは無制限のままにします。
• async-child-cancellation-tokens — 起動したサブタスクには、親のトークンのクローンではなく子トークンを渡します。
• async-shared-boxfuture-joinhandle — バックグラウンドの JoinHandle を Shared でラップし、複数の待機側から join できるようにします。

4. サンドボックス化とプロセス分離（HIGH）

• sandbox-shared-policy-data-model — サンドボックスポリシーはプラットフォームごとのコードではなく、共有データとして保持します。
• sandbox-staged-restrictions-re-exec — 同じバイナリを再実行することで、互換性のない制限を段階的に適用します。
• sandbox-resolve-before-allow-dns-rebinding — ホスト名を解決し、プライベート IP を拒否して DNS リバインディングを防ぎます。
• sandbox-dev-null-first-missing-mount — 最初に見つからないパスに /dev/null をマウントし、mkdir による脱出を防ぎます。
• sandbox-three-layer-network-isolation — 環境変数、seccomp、名前空間を重ねてネットワークを分離します。
• sandbox-env-clear-pre-exec — spawn のたびに、pre_exec で環境変数を消去し、子プロセスを制限します。
• sandbox-argv0-multiplex-binary — argv[0] とシンボリックリンクを使ってヘルパーバイナリを多重化します。

5. シークレットとプロセスの強化（HIGH）

• secrets-read-into-locked-buffer — シークレットをゼロ化可能なスタックバッファーに読み込み、mlock でロックします。stdin() 経由では読み込まないでください。
• secrets-ctor-pre-main-hardening — main() の実行前にシークレットを扱うプロセスを強化し、安全側に倒して失敗させます。
• secrets-manual-debug-elide — Debug を導出するのではなく、認証情報を省略する手動の Debug 実装を記述します。

6. 型設計と不変条件（HIGH）

• types-thread-local-raii-serde — スレッドローカルの RAII ガードを使ってデシリアライザーのコンテキストを渡します。
• types-try-from-newtype-validation — newtype で serde try_from を使用し、解析のたびに検証を実行します。
• types-non-exhaustive-public-enums — すべての公開 wire レベルの列挙型に、最初から non_exhaustive を指定します。
• types-unknown-variant-forward-compat — 認識できない値を Unknown バリアントで保持します。

7. テストアーキテクチャ（MEDIUM-HIGH）

• testing-path-attribute-sibling-tests — インラインの mod tests ではなく、#[path] でテストを兄弟ファイルとして追加します。
• testing-wiremock-sse-fakes — wiremock と小さな SSE イベントコンストラクターでネットワークをフェイクします。
• testing-atomic-bool-test-opt-in — cargo feature ではなく AtomicBool でテスト専用の動作を制御します。
• testing-insta-snapshot-tui-rendering — insta でターミナルのレンダリングをスナップショット化し、安定した UI 差分を取得します。
• testing-paused-runtime-advance — start_paused と advance を使い、タイミングに依存するテストを決定的に実行します。

8. プロトコルと Serde の設計（中〜高）

• proto-internally-tagged-rpc-dispatch — マクロを使った内部タグ付き列挙型で、JSON-RPC をディスパッチします。
• proto-double-option-tri-state — Option<Option> を使って、未指定、null、設定済みを区別します。
• proto-rename-alias-wire-migration — rename と alias を組み合わせ、クライアントに影響を与えずにワイヤー上の名前を移行します。
• proto-experimental-runtime-gate — 実験的なフィールドは、機能フラグではなく、実行時の存在に基づいて有効化します。
• proto-sse-idle-timeout-terminator — SSE ストリームをアイドルタイムアウトと必須の終端子を持つものとして扱います。
• proto-internal-vs-wire-error-split — 内部エラーの列挙型とワイヤーエラーの列挙型を分離します。
• proto-removed-feature-tombstone — 削除した機能フラグを、解析可能な何もしない tombstone として残します。

9. ワークスペースとクレートの構成（中）

• workspace-layered-transport-api-core — HTTP レイヤーを transport、api、core のクレートとして積み重ねます。
• workspace-lint-config-package — workspace.lints と clippy.toml にポリシーを記述します。
• workspace-utils-microcrate-fanout — 共通ユーティリティを utils/ 配下の単一目的のマイクロクレートに配置します。
• workspace-test-support-as-member-crates — 共通のテストヘルパーをワークスペースメンバーのクレートとして登録します。
• workspace-ban-per-crate-features — クレートごとの機能は避け、代わりに target-cfg または個別のクレートを使います。

10. 可観測性とトレーシング（中）

• otel-log-only-vs-trace-safe-targets — PII をログ専用のターゲットに振り分け、トレースのカーディナリティを安全な範囲に保ちます。
• otel-field-empty-then-record — スパンフィールドを field::Empty として宣言し、値が判明してから記録します。
• otel-layered-subscribers-env-filter — boxed fmt レイヤーを使って、レイヤーごとの EnvFilter インスタンスを構築します。
• otel-w3c-traceparent-propagation — 環境変数、JSON-RPC、HTTP ヘッダーを介して W3C traceparent を伝播させます。
• otel-instrument-at-trace-level — #[instrument] のデフォルトを trace レベルにし、info はネットワーク呼び出し用に限定します。

11. TUI（Ratatui）のレンダリング（中）

• tui-two-gear-hysteresis-chunking — 固定のスロットリングを、ヒステリシスで切り替えるスムーズモードと追い付きモードに置き換えます。
• tui-schedule-frame-coalescer — FrameRequester アクターとレートリミッターを介して再描画をまとめます。
• tui-drop-guard-panic-hook-chain — Drop ガードと連鎖するパニックフックを使って、ターミナルの状態を復元します。
• tui-paste-burst-state-machine — 文字のタイミングを追跡するステートマシンを使って、ブラケットなしの貼り付けバーストを検出します。
• tui-event-broker-pause-resume — サブプロセスへ処理を引き渡す前にイベントストリームを破棄して、一時停止します。

使用方法

codex-rs/ から引用した詳しい解説やコード例については、個別のリファレンスファイルをお読みください。

• セクションの定義 — カテゴリー構成、影響度、プレフィックス
• AGENTS.md — すべてのルールをまとめた、自動生成のナビゲーションドキュメント

各ルールファイルには、次の内容が含まれています。

• フロントマターに一致する命令形のタイトル
• WHY を説明する 2～4 文の解説
• 素朴なアプローチを示す誤った例
• ファイルパスを記載した、codex-rs の正しい例

リファレンスファイル

ファイル	説明
AGENTS.md	すべてのルールをまとめた、自動生成の目次ドキュメント
README.md	スキルリポジトリのドキュメント — 貢献方法、構成、コマンド
references/_sections.md	カテゴリーの定義と順序
gotchas.md	これらのルールを適用する際に判明した失敗しやすいポイント
metadata.json	バージョン、分野、codex-rs への参照