The Agent Loop & the Four-Element Prompt

Before you tune a single prompt, fix the right mental model of what happens after you press Enter. Codex is not answering a question in one shot — it is running a loop, the same loop a careful engineer runs by hand:

1. Gather context — it reads relevant files and searches your repository to understand what's actually there.
2. Propose changes or commands — based on your prompt, it suggests edits to apply or commands to run.
3. Pause for approval — depending on your active approval mode, it stops and asks before editing files or running commands.
4. Iterate — you respond, it adjusts, and the cycle repeats conversationally until the work is done.

The official description is exactly this: Codex "can read your repository, make edits, and run commands as you iterate together." Two design choices make the loop trustworthy. First, Codex always surfaces a transcript of its actions, so you can see every file it read, every command it ran, and every change it made. Second — and this is the Codex-specific detail people get wrong — there is no /undo command. Rollback is done with your normal git workflow: the transcript shows you what changed, and git (diff, restore, checkout, reset) is how you take it back.

This is why the loop, not the model alone, is what makes Codex an agent. A chat model predicts text; the loop is what turns that text into reading, editing, running, and checking — with you in the approval seat.

Here's the leverage point. The loop is fixed — gather, propose, approve, iterate — but how well each pass goes is almost entirely decided by the brief you hand Codex at the start. A vague prompt sends the agent off to gather the wrong context, propose the wrong change, and burn an approval cycle (and tokens) on work you'll throw away. A precise prompt aims the very first pass at the target.

Think of Codex as a sharp new teammate who has never seen your codebase. They will read code fast and write it well — but only if you tell them what to change, where to look, what rules to respect, and how you'll both know it's done. Leave any of those implicit and they'll guess. That's not a Codex quirk; it's the nature of delegating a task to anyone capable but unbriefed.

The good news: OpenAI distilled "a good brief" into a four-element template that you can reach for on every non-trivial task. The rest of this lesson is that template, the one lever that beats all others, and the handful of mistakes that quietly wreck otherwise good prompts.

OpenAI's best-practices guidance frames every good Codex prompt around four questions. Answer them and the agent has everything it needs to aim its first pass at the goal.

A worked example pulls them together:

Goal: Add a 5-requests-per-minute rate limit to the POST /login route.
Context: Auth lives in @src/routes/auth.ts; existing middleware in @src/middleware/.
         The integration test is @test/auth.test.ts.
Constraints: Reuse the existing rateLimit middleware pattern — don't add a new
             dependency. Don't change the response shape on success.
Done-when: A new test proves the 6th request in a minute returns 429, the full
           suite passes, and `npm run lint` is clean.

Notice what the Context line is doing: the @ prefix opens Codex's fuzzy file search over the workspace root, and pressing Tab or Enter drops the highlighted path into your message. You're not pasting whole files — you're handing the agent precise pointers and letting it read them. That keeps your prompt short and your context window clean.

Of all the prompting advice OpenAI publishes, one tip outranks the rest: "Codex produces higher-quality outputs when it can verify its work." Give the agent a way to check itself and it closes its own loop — running the check, reading the failure, fixing, and re-running — instead of stopping the moment the code merely looks right.

Concretely, fold verification into your brief:

• Steps to reproduce an issue, so Codex can confirm the bug exists before and after.
• A way to validate a feature — the exact command or test that proves it works.
• Lint and pre-commit checks to run, so the change meets your standards, not just compiles.

This is why the Done-when element is so powerful: a good Done-when is usually a runnable check. "The new test passes and npm run lint is clean" doesn't just describe success — it hands Codex the verifier it needs to drive the loop to completion. Withhold a verifier and you become the verification step, eyeballing diffs the agent could have checked itself.

The failure mode to recognize: an agent with no way to verify will confidently declare victory on code that doesn't run. The fix is almost never a smarter model — it's showing the agent how to test, then letting it.

The second-biggest lever is scope. OpenAI's guidance is blunt: break big work into small, focused steps, because "smaller tasks are easier for Codex to test and for you to review." A tight task gives the agent a verifier it can actually run and gives you a diff you can actually read. A sprawling one — "refactor the whole auth system" — gives both of you a mess where errors compound and nobody can tell what broke.

But sometimes you don't yet know how to slice the work — the code is unfamiliar or the change touches many files. The move then is to ask Codex to propose a plan first rather than guessing. You can switch to plan mode with /plan (and optionally send a prompt with it), letting the agent map the work into ordered steps before it touches anything. You review the plan, correct the slicing, and then let it execute — turning one risky leap into a sequence of small, reviewable, verifiable steps.

The deeper mechanics of plan mode and the /goal completion criterion get their own lesson next. For now, hold the judgment call: small clear change → just brief it well and go; large or uncertain change → get a plan, then break it down.

As you write four-element prompts, you'll notice some lines repeat every session: "use our middleware pattern", "run npm run lint before finishing", "don't add dependencies." Those are durable rules about your project, and retyping them into every prompt is both tedious and easy to forget. Their home is AGENTS.md — an open Markdown standard that acts as "a README for agents," read automatically at the start of a session.

The guiding principle is the line worth memorizing: "A short, accurate AGENTS.md is more useful than a long file full of vague rules." Put the things that are always true — build/test/lint commands, code style, architecture constraints, do-not rules, and how to verify work — into a tight AGENTS.md (scaffold one with /init). Keep the per-task specifics — this goal, these files, this finish line — in the prompt.

The division of labor is clean:

Get this split right and your prompts stay short, your standards stay consistent, and Codex stops re-learning your project on every run.

Most disappointing Codex sessions trace back to a handful of avoidable briefing errors. OpenAI publishes them as common mistakes; here are the three that matter most for this lesson, each with its fix.

• Overloading prompts with durable rules instead of moving them into AGENTS.md or a skill. Fix: prompt holds the task; AGENTS.md holds how the project works.
• Not showing the agent how to run builds and tests. This is the quiet killer — without a verifier, Codex can't close its loop and you inherit the checking. Fix: include the exact build/test/lint commands (in the prompt or AGENTS.md).
• Skipping planning on multi-step tasks. Leaping straight into a sprawling change invites compounding errors and an unreviewable diff. Fix: ask for a plan (/plan), then break the work into small steps.

Two more from the same list are worth keeping on your radar even though they belong to later lessons: granting full permissions before you understand the workflow (keep approvals and sandbox tight early, loosen only once you trust the task) and using one thread per project instead of one per coherent unit of work (session hygiene). You'll go deep on both later — but knowing they're mistakes now will save you from forming the habits.

Put positively: a good brief is a sharp Goal, precise Context, real Constraints, a runnable Done-when, durable rules pushed into AGENTS.md, and a plan when the work is big. That's the whole craft.