Claude Code Agent Workflows: Orchestrating Multi-Step Tasks with Claude Code and Codex

A single-prompt Claude Code session is great for a scoped change: fix this bug, write this test, refactor this function. It falls apart the moment the task spans a dozen files, touches a database migration, needs its own test strategy, and has to pass review before anyone trusts it in production. That's the gap between "using Claude Code" and "running Claude Code as an agent" — and it's a gap in workflow architecture, not model capability.

Running Claude Code as an agent means giving it a multi-step task with a defined scope, letting it plan before it executes, checking its plan before it touches code, and routing its output through explicit review and validation gates before anything ships. It is not autocomplete with a longer leash, and it is not unsupervised automation — the entire value of the pattern comes from the structure you put around the model, not from removing yourself from the loop. This article walks through that structure on a real feature, shows you where to put the human checkpoints, and covers when Codex is the better tool for a given step in the loop.

What "agent" means here, concretely

If you've already got a CLAUDE.md dialed in and a few slash commands wired up, you've been using Claude Code mainly for focused, single-request tasks: you ask, it reads context, it produces a diff, you review it. Treat that as the baseline. Running it as an agent changes the shape of the interaction in three ways:

1. The unit of work is a task, not a prompt. You hand it something like "add soft-delete support to the orders table and propagate it through the API and admin UI," not "write a migration."
2. In this workflow, you require a plan — an intermediate artifact — before any code gets written. You review that plan the way you'd review a design doc, not a diff.
3. The loop has named stages with different failure modes, and you decide, per stage, how much autonomy to grant and where to stand in the loop.

The common failure pattern with ungoverned agentic usage is letting the model skip straight from "task description" to "code changes across fifteen files" with no plan checkpoint in between. By the time you're reviewing, you're reviewing an essay, not a paragraph, and your ability to catch a wrong architectural assumption early is gone. The fix isn't less automation — it's inserting a planning stage with a hard stop.

The loop: planning → execution → review → validation → release-readiness

Treat every multi-step task as passing through five stages. Each stage has an owner (you or the agent), an artifact, and an exit condition. The way I suggest layering this: keep CLAUDE.md as the standing repo context you already maintain, and use slash commands you define yourself as repeatable entry points for each stage; this loop is the sequencing structure on top.

Stage 1 — Planning

Owner: agent drafts, you approve. Artifact: a written plan, not code. Exit condition: you've read the plan and either approved it or sent it back with corrections.

Resist the urge to let the agent start writing code in the same turn it produces a plan. Split them. A planning prompt should force the model to commit to scope, file list, and sequencing before anything executes:

You are planning a multi-step change to this repo. Do not write or
modify any code in this turn.

Task: Add soft-delete support to the `orders` table, surfaced through
the API and reflected in the admin UI's order list.

Produce a plan with:
1. Summary of the approach and why (1 paragraph)
2. Database changes (migration shape, backward-compat concerns)
3. Backend changes, file by file
4. Frontend/API-consumer changes, file by file
5. Tests you will add or modify, and what each one proves
6. Risks or ambiguous decisions that need my sign-off before you proceed
7. Rollback plan if this needs to be reverted post-deploy

Reference CLAUDE.md for our conventions. If something in CLAUDE.md
conflicts with this task, flag it instead of guessing.

This is the single highest-leverage artifact in the whole loop. A plan is cheap to reject and cheap to redirect; a thousand-line diff across fifteen files is not. If you have a slash command setup already, wrap this as /plan and keep the task description as its argument — that keeps the entry point consistent with how your team already invokes Claude Code for day-to-day work.

Read the plan like a design doc. Specifically check:

• Does the file list match your mental model of what should change? If it's touching things you didn't expect, that's a signal either you under-scoped the task or the agent misunderstood it.
• Is the migration backward-compatible, or does it assume a deploy order that your actual release process can't guarantee?
• Did it surface ambiguous decisions instead of silently picking one? A plan that resolves every ambiguity on its own without flagging it is a plan you should read twice.

Stage 2 — Execution

Owner: agent executes, against the approved plan only. Artifact: a diff, scoped to what the plan described. Exit condition: execution matches plan scope, or it stops and asks.

Once you approve a plan, the execution prompt should bind the agent to it explicitly, rather than re-describing the task from scratch:

Execute the plan above exactly as approved. If you discover during
implementation that the plan is wrong or incomplete, stop and explain
the discrepancy — do not silently expand scope or make a different
architectural choice.

Work file by file in the order listed. After each file, note what
changed and why in one line.

The instruction to stop on discrepancy is doing real work here. A plan that isn't binding gives you no check against scope creep — if the agent hits a wrinkle the plan didn't anticipate, there's nothing forcing that moment to surface rather than get folded silently into the change. The stop-on-deviation instruction makes any improvised fix visible to you, rather than buried in the diff where it's easy to miss during review. Binding execution to the plan and explicitly requiring a stop-and-ask on deviation is the oversight mechanism, not a formality.

If you have subagents configured for specialized roles — a test-writing subagent, a migration-focused subagent — this is the stage where they earn their keep, since execution against an already-approved plan is a much safer place to delegate than open-ended task interpretation.

Stage 3 — Review

Owner: you, assisted by the agent. Artifact: inline comments or a review summary. Exit condition: every file in the diff has been read by a human, not skimmed.

This is the stage people are most tempted to compress, and it's the one you shouldn't. Using Claude Code to assist review — "summarize what changed and flag anything that deviates from our error-handling conventions in CLAUDE.md" — is reasonable and genuinely useful. Using it as a substitute for your own read of the diff defeats the purpose of having a human gate at all. A useful review-assist prompt:

Summarize this diff against the approved plan. For each file, note:
- Whether the change matches what the plan specified
- Any deviation, however small, and why it might have happened
- Anything that touches error handling, auth, or data integrity,
  called out explicitly regardless of how minor it looks

Treat the model's review summary as a first pass that tells you where to look harder, not as a verdict.

Stage 4 — Validation

Owner: automated, agent-assisted, human-verified. Artifact: test results, lint/type-check output, manual verification notes. Exit condition: the specific tests the plan promised actually exist and actually pass — not just "tests pass."

Validation has a subtle trap: an agent under pressure to show green can write tests that pass trivially rather than tests that would catch a real regression. Go back to stage 1's plan and check that the tests listed there are the tests that exist now, and that they assert something meaningful about the soft-delete behavior — not just that the endpoint returns 200. A copy-paste validation checklist:

• Every test named in the approved plan exists in the diff
• Tests fail if you revert the implementation (spot-check one or two by temporarily reverting)
• Type checks and lint pass clean, not suppressed with inline ignores introduced by the agent
• Migration has been run against a copy of production-shaped data, not just an empty dev database
• Backward-compatibility claims from the plan are actually exercised by a test, not just asserted in prose

Stage 5 — Release-readiness

Owner: you. Artifact: a go/no-go decision and a rollback note. Exit condition: you can answer "what do we do if this is wrong in production" before merging.

This stage is deliberately outside the agent's authority. You can write a prompt asking the agent to draft a rollback plan in stage 1 and a changelog entry at wrap-up, then review them yourself — the decision to ship belongs to a human who understands the actual production environment, deploy order, and blast radius. If the task touches a database migration, "release-readiness" should explicitly include confirming migration order against your deploy pipeline, since an agent that only sees the repo has no visibility into your actual infrastructure sequencing.

Where Codex fits

Claude Code and Codex both operate as coding agents against a repo, and in practice the choice between them is less "which is better" and more "which fits this step of the loop and this environment." A few situational heuristics that hold up across the loop above:

• Sandboxed, disposable execution environments. If a step in your workflow benefits from running in an isolated, ephemeral environment — trying a risky refactor, running a long test matrix, exploring an approach you might throw away — that's a good candidate to hand to whichever tool you've set up with the tighter sandboxing in your CI/cloud environment, rather than running it against your primary working tree.
• Parallel exploration of an ambiguous plan. When stage 1 surfaces a genuinely ambiguous architectural choice, running the same task through both tools and diffing their plans is a cheap way to pressure-test your own assumptions before you commit a human reviewer's time to one direction.
• Where your existing tooling already lives. If your CI pipeline, PR automation, or review bots are already integrated with one tool's API and workflow model, that integration surface is often the deciding factor over any difference in output quality for a given task.
• Consistency of context. Claude Code pulling from a CLAUDE.md you've already tuned for your repo's conventions has an advantage that's purely about your investment in that file, not an inherent property of the model — the same investment applied to whatever context mechanism Codex uses would narrow the gap.

The practical pattern for most teams running both: pick one as the default driver for the planning → execution → review loop described above, and treat the other as a tool you reach for on specific steps — sandboxed exploration, a second opinion on an ambiguous plan, or a task that's already wired into infrastructure the other tool owns. Don't run both end-to-end on the same task as a default habit; it doubles review burden without a clear corresponding gain for most changes.

Wiring this into what you already have

If CLAUDE.md is your repo's standing context and slash commands are your repeatable entry points, this loop is the orchestration layer that sequences them into a task. Concretely:

• Create a /plan <task> command that wraps the Stage 1 prompt and tells the agent to write the plan to a file or PR description for review.
• Create a /execute command that takes the approved plan as context and runs Stage 2, bound to "stop on deviation."
• Create a /review-summary command that runs the Stage 3 assist prompt against the current diff.
• Create a /validate command that runs your test suite, lint, and type checks, then tells the agent to cross-check results against the plan's testing section.

If you've already set up subagents for specialized work — a dedicated test-writer, a migration-reviewer — slot them into Stage 2 and Stage 4 specifically, since those are the stages where a narrowly scoped agent operating against an already-approved plan is safer than a general-purpose agent interpreting an open-ended task. Keep Stage 1 and Stage 5 as your own territory, assisted but not delegated: planning sets the scope everything else inherits, and release-readiness is where production reality lives outside what the repo can tell the agent.

The failure mode to watch for

The agentic workflows that go wrong in practice don't usually fail because the model wrote bad code — they fail because a stage got skipped under time pressure. Someone approves a plan without reading it closely, or merges a diff because "tests pass" without checking what the tests actually assert, or treats a model's review summary as the review. The five-stage loop above isn't bureaucracy for its own sake; each gate exists because a specific, observed failure mode lives at that boundary. Running Claude Code as an agent on a real codebase is valuable precisely because you keep all five gates — the moment you start collapsing them to move faster, you've traded a structured workflow for exactly the single-prompt autocomplete usage this whole approach was meant to replace.

Frequently asked questions

Does running Claude Code "as an agent" mean it works without supervision?

No. Every stage in the loop above has a human owner or a human exit condition. The term describes a workflow structure — plan, execute, review, validate, release — not a reduction in oversight.

How is this different from just using a longer, more detailed single prompt?

A single prompt, however detailed, collapses planning and execution into one turn with one output to review. The agent loop separates them into distinct artifacts — a plan you approve before code exists, then a diff you review against that plan — which is what makes large multi-step tasks reviewable at all.

Should I let subagents handle an entire stage without checking in?

For execution and validation against an already-approved plan, that's reasonable, since the scope is already bounded. For planning and release-readiness, keep yourself in the loop directly — those are the stages where an unreviewed mistake is expensive to catch later.

Do I need Codex if I'm already happy with Claude Code?

Not necessarily. The two tools overlap heavily as coding agents, and the deciding factors in practice are usually sandboxing needs, existing CI integration, and how much context investment you've already put into one tool's setup — not a fundamental capability gap that forces you to run both.

What's the single highest-leverage change if I'm currently skipping straight to code?

Insert a mandatory planning stage with a hard stop before any code is written, and read the plan as carefully as you'd read a design doc. That one gate catches more problems than any amount of post-hoc code review on a diff that's already sprawled across a dozen files.