Agent Skills: OpenAI Codex Rust Best Practices

OpenAI Codex Rust Best Practices

Distilled from openai/codex codex-rs/ — a 119-crate, 2,008-file Rust workspace that ships the Codex CLI coding agent. Contains 63 rules across 11 categories, each citing the exact file in codex-rs where the pattern lives, so you can write Rust the way its top contributors (Michael Bolin, jif-oai, Ahmed Ibrahim, Eric Traut, Pavel Krymets) actually ship it. Citations were refreshed against main at commit 8a94430 (2026-05-25).

When to Apply

Reference these guidelines when:

• Writing or reviewing async Rust code that spawns tokio tasks, owns cancellation tokens, or manages long-lived background workers.
• Designing error enums, Result flows, retry loops, or layer boundaries in a library or service.
• Building a CLI tool that spawns subprocesses, enforces sandboxing, or runs LLM-generated code safely.
• Architecting a Cargo workspace with more than ~5 crates, deciding what to split out, and how to manage shared dependencies.
• Adding tests to a Rust codebase where existing tests are inline mod tests { ... } blocks and scaling is becoming painful.
• Implementing a JSON-RPC or custom wire protocol with serde — especially one that must evolve without breaking clients.
• Reading API keys or other secrets into memory, or hardening a binary that handles credentials against core dumps, debugger attach, and LD_PRELOAD.
• Enforcing a network egress allowlist that must survive DNS rebinding, or loading untrusted plugins/extensions.
• Wiring OpenTelemetry traces, logs, or metrics into a service that has privacy constraints around PII.
• Building a Ratatui-based TUI that streams LLM output, handles paste bursts, or manages raw-mode terminal state.
• Any time you find yourself reaching for .unwrap(), .lock().unwrap(), anyhow::Result<()>, or #[cfg(feature = "test")] — this skill explains what codex does instead.

Rule Categories by Priority

| Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Defensive Coding & Panic Discipline | CRITICAL | defensive- | | 2 | Error Handling & Result Discipline | CRITICAL | errors- | | 3 | Async, Concurrency & Cancellation | HIGH | async- | | 4 | Sandboxing & Process Isolation | HIGH | sandbox- | | 5 | Secrets & Process Hardening | HIGH | secrets- | | 6 | Type Design & Invariants | HIGH | types- | | 7 | Testing Architecture | MEDIUM-HIGH | testing- | | 8 | Protocol & Serde Design | MEDIUM-HIGH | proto- | | 9 | Workspace & Crate Organization | MEDIUM | workspace- | | 10 | Observability & Tracing | MEDIUM | otel- | | 11 | TUI (Ratatui) Rendering | MEDIUM | tui- |

Quick Reference

1. Defensive Coding & Panic Discipline (CRITICAL)

• defensive-deny-unwrap-workspace-wide — Deny unwrap and expect at the workspace level, opt in locally.
• defensive-debug-assert-with-early-return — Use debug_assert(false) with a safe fallback on unreachable branches.
• defensive-recover-poisoned-lock — Recover a poisoned lock with into_inner instead of unwrapping it.
• defensive-banned-interpreter-prefixes — Avoid learning allowlist rules for general-purpose interpreters.
• defensive-head-tail-output-buffer — Cap subprocess output with a head-and-tail ring buffer.
• defensive-io-drain-timeout-grandchildren — Time out the I/O drain task separately from the child process.
• defensive-refuse-to-run-unsandboxed — Refuse to run when the sandbox cannot enforce the requested policy.
• defensive-canonicalize-approval-cache-key — Canonicalize shell wrappers before hashing approval keys.
• defensive-fault-isolate-plugin-load — Isolate plugin load failures and sanitize manifest text before the model sees it.

2. Error Handling & Result Discipline (CRITICAL)

• errors-exhaustive-retryable-match — Classify retryable errors with an exhaustive match on every variant.
• errors-transient-permanent-type-split — Encode transient vs permanent outcomes as two enum variants.
• errors-boundary-error-translator — Translate errors at the layer boundary in a single function.
• errors-carry-retry-delay-in-variant — Carry the server-requested retry delay inside the error variant.
• errors-struct-display-payload — Put display-relevant error state in a struct, not a preformatted string.
• errors-tool-call-respond-vs-fatal — Split tool errors into respond-to-model and fatal variants.
• errors-io-error-with-context-struct — Wrap io::Error in a struct with a context field instead of anyhow.

3. Async, Concurrency & Cancellation (HIGH)

• async-abort-on-drop-handle — Store JoinHandles as AbortOnDropHandle so Drop cancels them.
• async-graceful-then-forceful-cancel — Cancel cooperatively first, then abort after a grace deadline.
• async-biased-select-for-cancellation — Use biased select to make cancellation always win race ties.
• async-bounded-vs-unbounded-channel-split — Bound the submission channel but leave the event channel unbounded.
• async-child-cancellation-tokens — Give spawned sub-tasks child tokens, not clones of the parent.
• async-shared-boxfuture-joinhandle — Wrap a background JoinHandle in Shared<BoxFuture> for multi-waiter joins.

4. Sandboxing & Process Isolation (HIGH)

• sandbox-shared-policy-data-model — Keep sandbox policy as shared data, not per-platform code.
• sandbox-staged-restrictions-re-exec — Stage incompatible restrictions by re-executing the same binary.
• sandbox-resolve-before-allow-dns-rebinding — Resolve hostnames and reject private IPs to defeat DNS rebinding.
• sandbox-dev-null-first-missing-mount — Mount /dev/null over the first missing path to block mkdir escapes.
• sandbox-three-layer-network-isolation — Stack env vars, seccomp, and namespaces for network isolation.
• sandbox-env-clear-pre-exec — Clear the env and tether children via pre_exec before every spawn.
• sandbox-argv0-multiplex-binary — Multiplex helper binaries via argv[0] and symlinks.

5. Secrets & Process Hardening (HIGH)

• secrets-read-into-locked-buffer — Read a secret into a zeroized stack buffer, then mlock it — never through stdin().
• secrets-ctor-pre-main-hardening — Harden a secret-handling process before main() runs, and fail closed.
• secrets-manual-debug-elide — Write a manual Debug impl that elides credentials instead of deriving it.

6. Type Design & Invariants (HIGH)

• types-thread-local-raii-serde — Pass deserializer context via a thread-local RAII guard.
• types-try-from-newtype-validation — Use serde try_from on a newtype to run validation on every parse.
• types-non-exhaustive-public-enums — Mark every public wire-level enum non_exhaustive from the start.
• types-unknown-variant-forward-compat — Preserve unrecognized values in an Unknown variant.

7. Testing Architecture (MEDIUM-HIGH)

• testing-path-attribute-sibling-tests — Attach tests as sibling files via #[path] instead of inline mod tests.
• testing-wiremock-sse-fakes — Fake the network with wiremock and small SSE event constructors.
• testing-atomic-bool-test-opt-in — Gate test-only behavior with an AtomicBool, not a cargo feature.
• testing-insta-snapshot-tui-rendering — Snapshot terminal rendering with insta for stable UI diffs.
• testing-paused-runtime-advance — Use start_paused and advance to make timing-dependent tests deterministic.

8. Protocol & Serde Design (MEDIUM-HIGH)

• proto-internally-tagged-rpc-dispatch — Dispatch JSON-RPC by an internally tagged enum with a macro.
• proto-double-option-tri-state — Use Option<Option<T>> to distinguish absent, null, and set.
• proto-rename-alias-wire-migration — Pair rename and alias to migrate wire names without breaking clients.
• proto-experimental-runtime-gate — Gate experimental fields by runtime presence, not capability flags.
• proto-sse-idle-timeout-terminator — Treat SSE streams as idle-timeout with required terminator.
• proto-internal-vs-wire-error-split — Split internal error enums from wire error enums.
• proto-removed-feature-tombstone — Keep removed feature flags as parseable no-op tombstones.

9. Workspace & Crate Organization (MEDIUM)

• workspace-layered-transport-api-core — Stack HTTP layers as transport, api, and core crates.
• workspace-lint-config-package — Encode policy in workspace.lints and clippy.toml.
• workspace-utils-microcrate-fanout — Place shared utilities in single-purpose microcrates under utils/.
• workspace-test-support-as-member-crates — Register shared test helpers as workspace member crates.
• workspace-ban-per-crate-features — Avoid per-crate features; use target-cfg or separate crates instead.

10. Observability & Tracing (MEDIUM)

• otel-log-only-vs-trace-safe-targets — Route PII to log-only targets and keep traces cardinality-safe.
• otel-field-empty-then-record — Declare span fields as field::Empty, then record them when known.
• otel-layered-subscribers-env-filter — Build per-layer EnvFilter instances with boxed fmt layers.
• otel-w3c-traceparent-propagation — Propagate W3C traceparent via env vars, JSON-RPC, and HTTP headers.
• otel-instrument-at-trace-level — Default #[instrument] to trace level, reserve info for network calls.

11. TUI (Ratatui) Rendering (MEDIUM)

• tui-two-gear-hysteresis-chunking — Replace fixed throttles with hysteresis-gated smooth and catch-up modes.
• tui-schedule-frame-coalescer — Coalesce redraws through a FrameRequester actor and rate limiter.
• tui-drop-guard-panic-hook-chain — Restore terminal state via a Drop guard and a chained panic hook.
• tui-paste-burst-state-machine — Detect unbracketed paste bursts via a character timing state machine.
• tui-event-broker-pause-resume — Pause the event stream by dropping it before a subprocess handoff.

How to Use

Read individual reference files for detailed explanations and code examples cited from codex-rs/:

• Section definitions — Category structure, impact levels, and prefixes
• AGENTS.md — Auto-generated navigation document compiling every rule

Each rule file contains:

• Imperative title matching its frontmatter
• 2–4 sentence explanation of the WHY
• Incorrect example showing the naive approach
• Correct example from codex-rs with the file path cited

Reference Files

| File | Description | |------|-------------| | AGENTS.md | Auto-built TOC document compiling every rule | | README.md | Skill repository docs — contribution, structure, commands | | references/_sections.md | Category definitions and ordering | | gotchas.md | Failure points discovered while applying these rules | | metadata.json | Version, discipline, references to codex-rs |