A Codex workflow that survives contact with a real repo

The Codex workflow in five steps

Shape the task. Ask for a plan. Approve a small diff. Verify with a command. Commit with an accurate, reviewed message. That is the whole loop, as a proposed workflow to test on your own tasks.

Each step exists because of a specific thing that goes wrong without it.

Step by step

• Shape. Name the file or the module if you know it, and state how you will know it worked. "The webhook retries forever on a 410. It should stop after the first 410 and mark the subscription dead. Add a test for both cases."
• Plan. For anything beyond a one-file change, ask for the plan before the code. You will catch the wrong approach in ten seconds instead of after three hundred lines. This is the highest-return habit in the whole workflow.
• Small diff. One concern per run. If the agent starts renaming things you did not ask about, stop it and re-scope rather than reviewing the mess.
• Verify. The agent runs the test. You run it too, once, yourself. Not because it lies, but because it sometimes runs a narrower command than you think, for example a single file rather than pnpm test.
• Commit. Read the diff and check that the message accurately describes the intent and behavior. An agent can draft it, but the responsible author must verify it.

Where teams lose time

Long sessions. A conversation that has been running for two hours has a context window full of stale test output. Symptoms are the agent forgetting a constraint you set early or re-reading files it already read. Start a new session per task and lose nothing that matters.

Approving without reading. The tempting rhythm is approve, approve, approve, then discover at commit time that four files changed. Once a team drifts into that, agent code enters the repository unreviewed and shows up later as an incident nobody can explain.

Fighting a stuck agent. Three failed attempts at the same approach means it is missing a constraint. Read the error yourself, tell it the thing it does not know, and restart. Continue only when the new evidence supports a different next step.

What this workflow does not solve

It will not make a badly specified ticket produce good code, and it will not protect a repository whose tests do not actually test anything. The verify step is load bearing. If your suite passes with the feature deleted, the whole loop is decorative.

Adopt it this week

Write the five steps on a card and pin it in the team channel. For one week, require the plan step on any change touching more than two files, and review the accuracy of each commit message. Then look at your revert rate. Also inspect defect severity, review effort and task mix; revert rate alone does not establish whether the workflow improved.

If you want help putting this into practice, talk to us.