Best Practices & Common Pitfalls

Most frustration with Codex traces back to one mismatch: people prompt it like a search box and then act surprised when an agent runs off and does something they didn't fully specify. Fix the frame first.

Codex is an autonomous teammate you delegate to — it reads the repo, plans, edits across files, runs commands, runs tests, and proposes a PR. That means the skills that make you productive are the skills of a good delegator: state the goal precisely, give the right context, set the constraints, define what "done" means, and let the agent verify itself. Everything in this lesson is a corollary of that one idea.

The good news is that the whole playbook is short and it's a checklist, not a theory. There are roughly six habits and six mistakes, and they mirror each other. Internalize the habits and the mistakes mostly stop happening on their own.

For anything beyond a trivial one-liner, lead with the four elements. OpenAI's best-practices guidance frames every good prompt as answering four questions:

• Goal — what are you trying to change or build?
• Context — which files, folders, docs, examples, or error messages matter?
• Constraints — what standards, architecture, or safety rules should Codex follow?
• Done-when — what should be true before the task is considered complete?

The Done-when element is the one people skip, and it's the one that pays the most. It does double duty: it tells Codex when to stop, and — if you phrase it as something runnable — it becomes the agent's own success check.

Goal:       Add rate limiting to the POST /login endpoint.
Context:    Auth lives in src/auth/; tests in tests/auth/.
            See src/middleware/throttle.ts for the existing pattern.
Constraints: Reuse the throttle middleware — don't add a new dependency.
            Keep the public API of loginHandler unchanged.
Done-when:  npm test passes, including a new test that a 6th login
            attempt within 60s returns HTTP 429.

Notice the prompt names specific files rather than making Codex hunt, points at an existing pattern to imitate, and ends with a check that is literally runnable. That last line is what lets Codex close its own loop instead of handing you something that merely looks finished.

When you genuinely don't know how to decompose the work, don't guess — ask Codex to propose a plan first (use /plan, or ask it to interview you). Reviewing a plan is cheaper than reviewing a wrong diff.

If you remember one habit from this lesson, make it this one. OpenAI's own guidance is blunt: "Codex produces higher-quality outputs when it can verify its work." Give it the means to check itself and quality jumps; withhold it and you become the verification step — slower, and easy to skip.

Concretely, hand Codex three kinds of feedback so it can close the loop:

• Steps to reproduce a bug, so it can confirm the bug exists before fixing and is gone after.
• A way to validate the feature — a test to write or run, an endpoint to hit, an output to compare.
• Lint and pre-commit checks to run, so style and obvious errors are caught by the machine, not by you in review.

This pairs directly with breaking big work into small steps. As the docs put it, "smaller tasks are easier for Codex to test and for you to review." A focused step has a tight verifier and a small diff; a sprawling one has neither, and a single bad assumption early on poisons everything after it.

The two habits reinforce each other: small steps make verification cheap, and a working verifier makes it safe to take many small steps quickly.

A thread is Codex's working memory. The best-practices rule is: one thread per coherent unit of work — not one thread per project. A single endless thread accumulates stale context, half-finished tangents, and contradictory instructions; Codex starts getting distracted by things you stopped caring about three tasks ago.

Start a fresh, focused thread when you switch to a genuinely different task. Within a long piece of work, three tools keep the context clean:

Note the distinction newcomers from other tools trip on: there is no /undo in Codex. Rollback is your normal git workflow — Codex surfaces a transcript of every action it took, so you git status, git diff, and revert as you would any other change. And /approvals is gone; the command is /permissions (covered next).

If you find yourself pasting the same instructions into prompt after prompt — "use pnpm not npm," "run the linter before you say you're done," "never touch the generated/ folder" — that's a signal those rules belong somewhere durable, not in your working memory and definitely not in every prompt.

Where durable knowledge lives:

• AGENTS.md — the cross-tool Markdown standard ("a README for agents"). Put repository layout, build/test/lint commands, engineering conventions, and do-not rules here. Codex loads it automatically and merges files from the Git root down to your cwd, so the closest file wins. Scaffold one with /init.
• Skills — when you keep reusing the same multi-step prompt or correcting the same workflow, package it as a skill. "Skills define the method." Start with 2–3 concrete use cases; keep them local while iterating.
• The prompt — only the task-specific details: this goal, these files, this done-when.

The guiding maxim from the docs: "A short, accurate AGENTS.md is more useful than a long file full of vague rules." Resist the urge to write an essay. Vague rules ("write clean code") cost tokens and change nothing; specific, verifiable ones ("all new endpoints need a test in tests/api/") earn their place. Codex caps the injected project docs at 32 KiB (project_doc_max_bytes) by default, so brevity isn't just style — it's a budget.

Codex has two independent controls, and conflating them is a classic mistake. Sandbox = WHERE Codex can act (the OS-enforced read/write/network boundary). Approvals = WHEN Codex must stop and ask you. They're related but not interchangeable, and you set them separately.

Approval policy (--ask-for-approval/-a) is the orthogonal axis: untrusted (auto-run only known-safe reads), on-request (works in the sandbox, asks to go beyond it — the recommended interactive default), or never (no prompts, stays in the sandbox).

The best practice is defense by default: start tight and loosen deliberately, per repo, once you understand the workflow — never the reverse. When you need a little more room, prefer the narrow tool over the nuclear one:

# Grant one extra writable dir instead of dropping the sandbox
codex --add-dir ../shared-lib "..."

# Switch posture mid-session
/permissions

Reach for --add-dir or a tighter network allowlist before you ever reach for --dangerously-bypass-approvals-and-sandbox (alias --yolo), which disables both controls and belongs only inside a hardened container or VM.

Codex runs the same agent locally (CLI/IDE) and in the cloud (isolated containers in OpenAI's infrastructure that check out your repo, run setup scripts, and execute in the background — even in parallel). They're not competitors; they're for different moments.

The rule of thumb: default to local when you want to steer and see every step; delegate to cloud when the task is large, well-specified, and you'd rather kick it off and come back to a PR. Cloud tasks finish as a PR you review, and you can pull a cloud diff down locally with codex apply TASK_ID to test it on your machine.

A related lever: once a manual workflow is reliable, you can wrap it in an automation to run on a schedule — "skills define the method, automations define the schedule." But note the ordering — automations come after the workflow works by hand, never before.

OpenAI's best-practices page ships an explicit list of mistakes to avoid. Print it, pin it, return to it. Every one is the inverse of a habit above:

Three of these (durable rules, planning, threads-per-task) are about not overloading context. Two (verifier, automations) are about not skipping verification. One (permissions) is about not over-trusting too early. If you keep those three principles in mind — protect context, always verify, earn trust gradually — you'll avoid the whole list without memorizing it.