Orientation

Working with Codex

Think of Codex as a capable project teammate with tools, not as an oracle. It can inspect context, make changes, run checks, and explain what it found—but you still define the destination and decide what evidence is enough.

Codex

Best at

Repository exploration, code changes, tests, debugging, refactoring, documentation, browser checks, and multi-step work where the environment can provide evidence.

You

Still own

Intent, authorization, risk tolerance, product decisions, sensitive data, final review, and whether the outcome is actually good for the people who use it.

Give it a destination, not a maze

Current OpenAI guidance favors prompts that describe the expected outcome, success criteria, important constraints, allowed side effects, evidence rules, and final answer shape. It generally recommends leaving the exact route open unless the route itself is a requirement.

Good default: “Make X work in the existing system. Success means A, B, and C. Preserve D. Check it with E. Tell me what changed and what could not be verified.”

That gives Codex room to inspect the real code and select an efficient path while still making “done” concrete.

A healthy Codex turn

01Orient. It identifies the repository, relevant instructions, current state, and likely owners before editing.

02Explain the first move. You get a short preamble when tools or a long task are involved.

03Work in bounded increments. It preserves existing behavior and makes the smallest complete change.

04Check the claim. It runs relevant tests, lint/type/build checks, and real runtime checks when the change needs them.

05Hand off honestly. It reports files, behavior, checks, failures, assumptions, and remaining risk.

Let it continue when…

The goal is clear, the next steps are reversible, and the missing information can be learned by inspecting the workspace or running a safe check.

Ask before acting when…

A choice would change the product direction, expose sensitive data, incur meaningful external cost, affect production, or make recovery difficult.

Important Codex surfaces

Surface	Use it for	Remember
Repository guidance	Stable project conventions, commands, architecture maps, and safety boundaries.	Keep it short; use nested files and linked docs for specialized detail.
Skills	Reusable task workflows with a clear trigger and optional scripts or references.	Descriptions steer discovery. Read the full skill only when it applies.
Tools	Grounding in files, tests, browsers, APIs, images, or other real surfaces.	Tool output is evidence, not permission. Side effects still need scope.
Subagents	Parallel independent research or review when the task benefits from it.	Give each one a narrow question, minimum context, and a clear return format.