Building Multi-Step Agent Workflows

Most non-trivial work — migrating a codebase, shipping a feature with tests, auditing a security surface — is too big to one-shot. The reliable path is to break the work into smaller pieces, run them with the right amount of parallelism, and verify the result before declaring victory. This guide covers the core patterns for multi-step agent workflows in Claude Code: decomposition, fan-out/fan-in, verification passes, when to reach for an orchestrator subagent, and the pitfalls that quietly wreck long runs.

Decomposition: split before you build

Decomposition is the act of turning one vague request ("modernize the auth layer") into an ordered list of concrete, independently checkable steps. A good decomposition has steps that are small enough to verify, but large enough to carry real meaning on their own.

A practical heuristic: each step should produce an artifact you could review in isolation — a diff, a file, a test result, a written finding. If a step's output is "I thought about it," it isn't a step.

A typical decomposition prompt looks like:

Before writing any code, produce a numbered plan to add rate limiting
to our API. For each step, list: the files touched, what changes, and
how I can verify that step in isolation. Stop after the plan — wait
for my approval.

Once the plan exists, each numbered item becomes a unit of execution you can run, check, and roll back independently.

Fan-out / fan-in: parallel work, single merge

Some steps are independent of each other — they don't share state and can run at the same time. Fan-out means dispatching those independent steps in parallel; fan-in means collecting their results and merging them into a single coherent outcome.

In Claude Code, fan-out happens when you launch multiple subagents (via the Task tool) in one turn. Each subagent runs in its own isolated context window, does its slice of work, and returns a summary. The main agent then performs the fan-in: reading each summary and reconciling them.

Fan-out shines for read-heavy, embarrassingly-parallel research:

Spawn three parallel subagents:
  1. Map every place we read process.env and list undocumented vars.
  2. Find all SQL queries built with string concatenation.
  3. List API routes that lack input validation.
Each returns a bulleted list with file:line references.
Then merge all three into one prioritized findings table.

The key property: subagents share no memory with each other. That isolation is what makes parallelism safe, but it also means fan-in is real work — the orchestrating agent must actively combine outputs, dedupe overlaps, and resolve conflicts. Don't assume three independent reports stitch themselves together.

A minimal subagent definition:

---
name: security-scanner
description: Read-only scanner for common web vulnerabilities. Use proactively before merges.
model: sonnet
color: red
---
 
You are a security reviewer. Inspect only the files you are given.
Report findings as `severity | file:line | issue | fix`. Never edit code.

Verification passes: trust nothing unchecked

A verification pass is a step whose only job is to confirm earlier steps actually worked. This is the single highest-leverage habit in multi-step workflows, because agents are optimistic — they will report success on code that doesn't compile.

Make verification an explicit step, not an afterthought:

• Mechanical checks — run the build, the linter, the test suite. These are objective and cheap.
• Adversarial review — a separate subagent re-reads the diff with a critical eye, knowing nothing about the implementer's intent.

Using a fresh subagent for review matters: the agent that wrote the code is primed to believe it is correct. A reviewer with a clean context window and no stake in the implementation catches issues the author rationalized away.

Run `npm run build && npm run lint && npm test`. Paste the raw output.
If anything fails, stop and report — do not attempt fixes yet.

For higher-stakes changes, chain a second opinion:

Launch a code-review subagent. Give it only the diff and the original
requirements. Ask: does this fully meet the requirements, and what could
break? Return a verdict plus a list of concerns.

Orchestrator agent vs. sequential steps

Not every workflow needs an orchestrator. Choose based on shape:

Stick with sequential steps when

• Steps are dependent — step 3 needs step 2's output.
• The task fits comfortably in one context window.
• You want to inspect and approve each step as it happens.

This is the default and usually the right call. Linear work in a single context keeps everything visible and easy to course-correct.

Use an orchestrator subagent when

• You have repeated fan-out/fan-in cycles (research many modules, then synthesize).
• The total work would blow past the context window if done in one thread.
• You want a reusable, named pattern your team invokes the same way each time.

An orchestrator is itself a subagent (.claude/agents/workflow-orchestrator.md) whose system prompt encodes the process: how to plan, when to fan out, how to merge, and what verification to run. You can also wrap a fixed sequence as a slash command in .claude/commands/ (e.g. .claude/commands/ship-feature.md) so the whole workflow runs from a single invocation. Reach for an orchestrator when the coordination logic itself is worth saving — not just for one big task.

Pitfalls to watch for

Context loss

Subagents return only a summary, and the main thread can compact or drop detail over a long run. Critical specifics — exact filenames, version numbers, an edge case the user mentioned once — evaporate between steps. Defend against it by writing durable state to a file (a PLAN.md or a scratch notes file) that every step re-reads, rather than relying on the conversation to remember.

Over-decomposition

The opposite failure: splitting work so finely that coordination overhead dwarfs the actual task. Twelve subagents each editing one line will spend more tokens negotiating handoffs than a single agent would spend doing the whole thing — and the fan-in becomes a tangle of near-identical reports.

A good rule: decompose until each step is independently verifiable, then stop. If two steps always run together and share state, they are one step. Parallelism is a tool for genuinely independent work, not a goal in itself.

Putting it together

The throughline is simple: plan in plain text, run independent work in parallel and dependent work in sequence, verify every step with mechanical checks plus a fresh-eyes review, and persist anything you can't afford to lose to a file. Start sequential, add an orchestrator only when the coordination pattern repeats, and resist the urge to slice the work finer than you can check.