How to use Codex to build a feature step by step: plan, build in slices, ship

What does a step-by-step Codex run look like from the outside?

Five moves, repeated: plan, edit the plan, build one slice, inspect and commit, then either continue or replan. Each prompt carries the four parts OpenAI's Codex best practices recommend for any non-trivial task: the goal, the context that matters, the constraints, and "Done when: What should be true before the task is complete, such as tests passing, behavior changing, or a bug no longer reproducing?" The loop below adds one rule of its own: the member, not Codex, decides when a slice is finished.

The worked example runs in the B2B invoicing repository from the AGENTS.md guide, whose AGENTS.md already names the test commands, the stop-and-ask paths (packages/db/, packages/ui/, new dependencies) and the definition of done. The feature is small and typical: finance users want to download the invoices they are looking at as a CSV file, with the same filters and sort as the screen. The run is a composite written up from a sample repository, not a transcript, so treat the specific failures as illustrations of the kind Codex runs produce rather than as a measurement of how often they happen.

How do you start the run so a bad slice is cheap to undo?

Start on a clean branch and a clean permission boundary. In the ChatGPT desktop app, select Codex, open a new chat in the project, choose Worktree under the composer and base it on main. The worktrees documentation describes a worktree as a second checkout that lets Codex run chats in parallel without disturbing your local one. From the CLI, create a branch with git switch -c feat/invoice-csv-export and run codex in the repository.

Leave permissions on Ask for approval. The permissions page describes it, as of October 2026, as the mode where Codex can read and edit files in the current workspace and run routine local commands, and asks before using the internet or going beyond the workspace boundary. The best practices page names the alternative as a common mistake: "Giving Codex full permission to your computer before you understand the workflow."

What is the exact prompt for the plan?

Toggle Plan mode with /plan (or Shift+Tab) and send:

/plan Add CSV export to the invoices list.

Goal: a finance user on /invoices can download the invoices they are looking
at, with the same filters and sort, as a CSV file.
Context: spec in docs/specs/invoice-csv-export.md. The list endpoint is
apps/api/src/routes/invoices.ts. The page is apps/web/app/invoices/page.tsx.
Constraints: follow AGENTS.md. No changes to packages/db or packages/ui.
No new dependencies. Amounts stay integer cents until the CSV writer formats them.
Done when: a test proves the export returns the same invoices as the list
endpoint for the same filters, and the button downloads a file in the browser.

Plan this as vertical slices. Each slice must work on its own, name the files
it touches, and name the command that proves it works. Do not write code yet.

"Vertical" is the word doing the most work. A horizontal plan builds all the backend, then all the frontend, and nothing is testable end to end until the last step. A vertical slice cuts through every layer for one behaviour, so each slice ends in something you can run.

What should you change in the plan Codex proposes?

Read the plan against four questions: does every slice name its files, does every slice name a check, does any slice touch a stop-and-ask path, and is there anything in it nobody asked for. A first plan for this feature came back with four slices, and two of them failed those questions.

Codex's proposed slice	Problem	Edit
1. Add a CSV library and a shared toCsv helper in packages/ui	New dependency and a shared package, both on the stop list	Write a 20-line CSV writer in apps/api/src/lib/csv.ts
2. Export endpoint reusing the list query	Fine, but no check named	Add: test comparing export rows to GET /invoices for the same filters
3. Export button on the invoices page	Fine	Keep, add a manual check: filter to Overdue, export, open the file
4. Refactor filter parsing into a shared module	Not part of the feature	Cut, log as a separate task

The edited plan has three slices. Send it back as the agreed plan so it sits in the chat as the reference for every later prompt:

Revised plan, use this one:
Slice 1, API: GET /invoices/export.csv takes the same query params as GET /invoices
  and returns text/csv. Files: apps/api/src/routes/invoices.ts,
  apps/api/src/lib/csv.ts, apps/api/test/invoices-export.test.ts.
  Check: pnpm test --filter api
Slice 2, web: an Export CSV button on /invoices that calls the endpoint with the
  current filters. Files: apps/web/app/invoices/page.tsx,
  apps/web/app/invoices/ExportButton.tsx and its test. Check: pnpm test
  --filter web, then filter to Overdue in the browser, export, open the file.
Slice 3, limits: zero matches returns a header row only; more than 10,000 rows
  returns 413 with a message the button shows. Check: two new API tests.
Confirm you will follow this plan, then wait.

The fourth slice in the original plan is the one to notice. Nothing was wrong with it except that nobody asked for it, and a refactor bundled into a feature is the change most likely to break something the feature's tests never look at. For more on where to cut a spec into slices, how to turn a PRD into agent tasks covers the dependency order in detail.

What is the prompt for each slice, and what do you inspect after it?

Every slice prompt has the same shape: which slice, the fence, the check, the report, and an explicit stop.

Implement slice 1 only. Stay inside the three files the plan names. If you need
another file, stop and tell me which and why before editing it.
Run pnpm test --filter api and pnpm typecheck.
In your final message, paste both outputs and list each changed file with one
line on why. Do not start slice 2.

When Codex reports back, open the diff pane and check four things before reading any explanation. The changed files match the plan, and no file outside it appears. The new test asserts the behaviour, not just that the endpoint answers; a test that only checks for status 200 proves nothing about the filters. The pasted output is real command output with a pass count, not a sentence saying tests pass. And amounts are converted from cents in exactly one place, the CSV writer.

On the first pass of slice 1, the test only checked the status code. The code review documentation describes the fastest fix: leave an inline comment on the line in the diff pane, then "send a follow-up message that makes your intent explicit, for example, 'Address the inline comments and keep the scope minimal.'" The comment here read: "Assert that the CSV rows match GET /invoices?status=overdue for the seeded data, row for row." The second pass added that assertion and passed.

Then commit. The Codex CLI page puts it as a habit: "Create Git checkpoints before and after a task so you can revert changes." In the app, commit from the built-in Git controls; in the CLI, ask Codex to commit with a message or run git commit yourself. A commit after each passing slice means a failed later slice costs one slice, not the feature.

Slice 2 runs the same way with its own files and its browser check. You do the browser check, not Codex: filter to Overdue, click Export CSV, open the file, and compare three rows to the screen.

When do you stop and replan instead of asking Codex to try again?

After a slice fails its check twice, or the moment Codex asks to edit a file outside the slice. Asking for a third attempt at the same slice rarely fixes the cause, because the cause is usually an assumption in the plan, and each retry builds on it.

Slice 3 hit that rule. The 413 test seeded 10,001 invoices one insert at a time and timed out. Codex's second attempt raised the test timeout, which made the run slower and still failed in CI, and also changed a test configuration file the plan never mentioned. That is two signals at once: a repeated failure and a step outside the fence. The response is to revert slice 3 in the review pane back to the slice 2 commit, then send:

Stop. Slice 3 failed its check twice and the last attempt edited a file outside
the plan. I have reverted it. Do not write code yet.
1. In five lines or fewer: what did you assume that turned out to be false?
2. Propose a revised plan for slice 3 only, with files and the check.

Codex's answer named the false assumption: that the row limit had to be tested with real rows. The revised slice counted matching invoices with one query before building the file, and tested the limit by stubbing the count, which ran in well under a second. If the false assumption is something about the repository that will bite again, such as "seeding more than a few hundred rows in tests is too slow here", add it to AGENTS.md now. OpenAI's own advice is the trigger: "When Codex makes the same mistake twice, ask it for a retrospective and update AGENTS.md."

How does the run end?

With a review before anyone else sees it. Run /review and choose Review against a base branch; the slash command reference documents it as starting code review mode against uncommitted changes or a base branch, and Codex reports findings without changing your working tree. Fix what it finds as one more small prompt with the same file fence as the slices (an unfenced fix prompt is exactly where scope slips in), rerun the checks, then open the pull request from the app's built-in Git controls, or as a draft from the terminal with gh pr create --draft.

The honest limitation of the loop is speed on easy work. Three slices with a plan and a replan is more ceremony than a one-file change needs, and running it on everything will make it feel slow. Use it when a change crosses layers or touches money, permissions or shared code; for a copy fix, ask for the change and read the diff. The guide to reviewing Codex pull requests takes this feature's pull request through review, including the out-of-scope change the slice fences were built to prevent, and a Codex skill can produce the evidence block at the end of every slice so you stop typing it.

See the Building with Codex bootcamp for the session plan and the next cohort dates.