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 a message a human wrote. That is the whole loop, and teams that follow it get dramatically more predictable results than teams that type a paragraph and hope.

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, then write the message yourself. A commit message is the record of intent, and intent is the one thing the agent does not have.

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. More turns will not help.

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 require a human-written commit message on everything. Then look at your revert rate. That is the number that tells you whether the workflow is working, and it is the one we ask teams to track before and after training.

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