Breaking a Large Task into Codex-Sized Steps

"Codex-sized" isn't a fixed unit — it depends on the model you're running, its context window, and how much of that window a given task actually needs to hold at once. But the underlying skill, breaking a big task into steps a single session can complete reliably, is the same regardless of which model answers.

Why bigger isn't always harder, but longer usually is

A large but simple task — apply the same small change across many files — can be a single session's work even though it touches a lot of surface area, because each individual decision is small and repetitive. A shorter but genuinely complex task — redesign one tricky piece of logic with several interacting edge cases — can be much harder to complete reliably in one pass, because the difficulty is in the reasoning, not the volume. Sizing a step by "how much typing" rather than "how much genuine judgment it requires" is a common way to misjudge what actually fits in one session.

The natural seams to cut along

Real tasks usually have natural boundaries worth respecting rather than cutting through: a step that leaves the codebase in a broken, half-migrated state is a worse stopping point than one that leaves it working, even if the working state isn't the final one. Structuring steps so each one ends with tests passing — even if the feature isn't complete — means a session that goes sideways can be discarded without losing the last genuinely working state, rather than leaving you to untangle a half-finished change from a good one.

Watching context accumulate as the real sizing signal

For a model that publishes a long-context repricing threshold, a step's real size isn't "how many files" but "how much accumulated input by the time it's done" — file contents, prior turns, tool output, all counted together. A step that felt reasonably scoped on paper can still cross that threshold if it involves reading through a lot of surrounding code to understand context before making a small change. Checking a step's expected size against the context-window planner before starting, especially for anything touching an unfamiliar part of a large codebase, catches this before it becomes a mid-task surprise.

Handing off state between steps

When one step's output becomes the next step's starting point, what actually carries over matters more than it seems. A fresh session with no memory of the prior step needs the relevant context re-established — either by starting inside the same long-running session, or by explicitly summarizing what changed and why before starting the next step in a new one. Losing that context between steps is a common source of a later step undoing or duplicating what an earlier step already did.

Definition of done, restated per step

The site's own guidance on giving Codex a clear definition of done applies at the level of an individual step, not just the whole task — a step without its own concrete success criterion is exactly where scope tends to creep, since there's nothing to check the step's actual output against. "Refactor the auth module" as a single step invites drift; "extract the token validation logic into its own function, with the existing tests still passing" is a step you can actually verify.

When a step is too small to be worth it

There's a real cost on the other side too — splitting a task into steps so granular that each one needs its own round of context-gathering, review and re-establishing state adds overhead without adding safety. If a step's own setup cost — explaining what it needs to know — is comparable to the size of the step itself, it's probably cut too fine, and a session with more room to work independently within a still-well-defined boundary is usually the better call.

Sequencing dependent steps correctly

Where later steps genuinely depend on earlier ones — a shared interface needs to exist before code that implements it, a migration needs to run before code that assumes the new schema — get the order right explicitly rather than letting Codex infer it from a flat list of tasks. An implicit dependency that isn't stated is exactly the kind of thing that produces a plausible-looking but broken result when steps get reordered or parallelized without that constraint in view.

Writing the step list down before starting the first one

It's tempting to plan the first step in detail and figure out the rest as you go, especially on a task that feels straightforward at the outset. A written step list, even a rough one, sketched before any code changes begin, is worth the up-front time specifically because it surfaces dependency ordering and scope questions while they're cheap to answer — before a session has already committed to an approach that a later, unplanned step turns out to conflict with. It doesn't need to be a formal document; a short list in your own notes or in the first message of the session is enough to serve the purpose.

Steps that produce their own verification

The strongest kind of step is one that leaves behind a concrete way to check it worked — a passing test, a script that validates the new state, a diff that's small enough to read in full. A step whose completion can only be judged by re-reading a lot of code and trusting your own impression that it looks right is a weaker step, not because the work itself is necessarily worse, but because there's less to check it against later if something built on top of it later turns out to be wrong.

Revisiting the plan mid-task

A step list made before starting is a plan, not a contract — if the second step reveals that the third step's assumption was wrong, revising the remaining steps before continuing is the right move, not a failure of the original planning. Treating an early plan as fixed once real work has started, even after it's clearly been overtaken by what you've actually learned, is a worse habit than the plan being imperfect in the first place.