The short version
  • "Claude Code workflow" means two things: the way you run one session day to day, and a feature called dynamic workflows that runs many agents from a script.
  • The one-session loop is plan, build, verify. The step people skip is giving Claude a check it can run that comes back pass or fail.
  • Fan-out pays for work that is wide, independent and mechanical enough to describe once. It costs tokens, memory and your attention.
  • A good pipeline shape is review, then verify each finding. A second agent tries to disprove what the first one claimed.
  • Our scars: a ten-agent run that filled a laptop's disk, a message to a running agent that started a second copy of it, and nine research agents that hit a usage limit together.
  • Feature names here change often. Everything named in this guide was checked against the documentation in November 2026.

"Claude Code workflow" means two different things. One is a working method: how to plan, prompt and check. The other is a product feature that runs dozens of agents from a script. The second goes badly without the first.

This guide covers both in that order. Feature facts come from Anthropic's documentation as fetched in November 2026; the failure stories are ours. If the vocabulary is new, AI agents explained is the place to start.

Two things called a Claude Code workflow

The method is how one person and one session get work done: what you ask for first, when you let Claude edit, how you know it worked.

The feature is what the documentation calls dynamic workflows: "a JavaScript script that orchestrates many subagents at once. Claude writes the script for the task you describe, and a runtime executes it in the background while your session stays responsive." It runs through the Workflow tool, hence the search for "Claude Code workflow tool."

They connect. A dynamic workflow is the same loop written as code and run by many workers. Loose single-session habits get multiplied.

The one-session loop: plan, build, verify

Most work never needs more than this.

planplan mode:read andpropose, noeditsbuildin the mainconversationverifya check thatreturns passor failverify theworldthe live page,with a cache-buster/clearbefore thenext tasknot passing: back to build
The one-session loop. Most work never needs more than this.

1. Plan before editing. For any change you want to review before it touches disk, use plan mode. Claude reads and proposes but makes no edits until you approve.

claude --permission-mode plan

Mid-session, press Shift+Tab until the status bar shows plan mode. Skip it for a one-line fix.

2. Build in the main conversation. Keep planning, implementation and testing together when they share context or need back-and-forth with you.

3. Verify with something that returns pass or fail. This is the step that changes results most. Anthropic's best practices page explains why: "Claude stops when the work looks done. If it has nothing to run that tells it whether the work actually is done, 'looks done' is all it has to go on." The check can be a test file, a build's exit code, a linter, or a browser screenshot beside the mockup.

The page lists ways to apply the check, from loosest to strictest:

  • In the prompt: "run the auth tests after, and keep going until they pass."
  • As a goal: /goal with a condition that is checked after every turn.
  • As a Stop hook: a script that sends Claude back to work until it passes. We cover the mechanics in Claude Code hooks.
  • By a reviewer that did not write the code: /code-review reviews the diff in a fresh subagent.

Then ask for evidence: the command and its output, or the screenshot. "All tests pass" on its own tells you very little.

4. Verify the world, not just the diff. This part is ours. Our global instruction file has a section headed "Verify before you assert," and its first line is: "Claims about live systems must come from the live system, not from inference, cached knowledge, or a memory file." In practice that means fetching the deployed page with a cache-buster after a deploy, because, as the same file says, "Green CI is not proof the change is live."

5. Keep the context clean. Run /clear between unrelated tasks so the next one does not carry the last one's history. On a long task, /compact with a focus, such as /compact keep the API changes and the test commands.

That is the whole method. We go deeper on the habits in how to use Claude Code effectively.

What Claude Code ships for multi-agent work

The names matter, because they are easy to confuse and several are new. As of November 2026 the documentation's parallel agents page lists five approaches:

Approach What it is Status in the docs Our use
Subagents Workers inside one session that return a summary Standard Daily
Agent view One screen for background sessions, opened with claude agents Research preview Documentation only
Agent teams A lead session supervising peer sessions with a shared task list Experimental, off by default Documentation only
Dynamic workflows A script that runs many subagents and can cross-check their results Available on paid plans Yes
Projects One ongoing conversation that starts parallel cloud sessions called threads Public beta on some plans Documentation only

Around those sit supporting pieces:

  • Worktrees. claude --worktree feature-auth (or -w) starts a session in its own git checkout so parallel sessions cannot collide. We run this blog's work from a separate worktree for exactly that reason.
  • /batch. A bundled skill that splits one large mechanical change into 5 to 30 units, each in its own worktree.
  • Cloud sessions. claude --cloud "task" starts a session in the cloud from the current repository.
  • Scheduling. /loop re-runs a prompt on an interval while a session is open. Cloud scheduled tasks, which the docs say were formerly called routines, run without your machine and are created with /schedule. Desktop scheduled tasks run on your machine.

"Documentation only" means we have not run that feature in production. Plan and limit details are Anthropic's to state, and they change.

When fan-out pays

The docs give the test in one sentence: reach for a workflow "when a task needs more agents than one conversation can coordinate, or when you want the orchestration codified as a script you can read and rerun." Their examples are a codebase-wide bug sweep, a 500-file migration, and research where sources need cross-checking.

Our own test is in the delegation section of the instruction file every session reads:

Delegate only for large, genuinely independent, parallelizable work: a wide multi-file investigation, several unrelated tracks.

and, just as firmly:

Do not delegate what you could finish yourself in a handful of tool calls, and do not use a subagent to verify or double-check your own work — verification belongs in the main loop.

Put together, fan-out is worth it when all four of these are true:

  1. The work is wide. Many files, many sources, many items of the same kind.
  2. The pieces are independent. No piece needs another's result, and no two edit the same file.
  3. You can describe one piece completely. Each agent starts with only its prompt. If the brief needs a conversation to explain, the job is not ready.
  4. A summary is enough. You are giving up the detail in exchange for the breadth.

When any of those fails, a single session or one well-briefed subagent is faster and cheaper.

A worked pipeline: review, then verify each finding

The most useful shape we know is two stages. Stage one finds candidate problems. Stage two tries to knock each one down. A reviewer asked to find problems always finds something; an independent agent asked to disprove a claim has no stake in it. The documentation calls this having "independent agents adversarially review each other's findings before they're reported."

changed filesevery file on the branchfindingcandidate from stage onefindingcandidate from stage onefindingcandidate from stage onereportonly findings that surviveStage two: an independent agent tries to disprove each finding before it is reported.
Review, then verify each finding. The reviewer has a stake in finding something; the verifier does not.

Run it without writing anything. Ask in plain words:

use a workflow to review every file changed on this branch for correctness
bugs, then have a separate agent try to disprove each finding, and report
only the findings that survive

Including the keyword ultracode in a prompt has the same effect as asking for a workflow. Claude writes the script and shows you the planned phases. Depending on your permission mode you get options to run it, view the raw script, or cancel. Read the script the first few times.

What the script looks like. A saved workflow is a meta block followed by plain JavaScript with top-level await. The documented building blocks are agent(), which starts one subagent, pipeline(), which runs one per item in a list, and parallel(), which runs a set at once. This is the shape of the review pipeline written against that API. It is an illustration, not a script we are publishing as tested; let Claude generate yours for your repository.

export const meta = {
  name: 'review-then-verify',
  description: 'Review changed files, then try to disprove each finding',
}

const changed = await agent('List every file changed on this branch against main.', {
  schema: {
    type: 'object',
    required: ['files'],
    properties: { files: { type: 'array', items: { type: 'string' } } },
  },
})

const reviews = await pipeline(changed.files, file =>
  agent(`Review ${file} for correctness bugs only. Skip style.`, {
    label: `review ${file}`,
    schema: {
      type: 'object',
      required: ['findings'],
      properties: { findings: { type: 'array', items: { type: 'string' } } },
    },
  }),
)

const findings = reviews.filter(Boolean).flatMap(r => r.findings)

const verdicts = await pipeline(findings, claim =>
  agent(`A reviewer claims: "${claim}". Try to disprove it. Read the code and run the relevant test. Say whether it holds and quote your evidence.`, {
    label: 'verify finding',
  }),
)

return verdicts.filter(Boolean)

Three details in that script come straight from the docs. Passing a schema makes an agent return JSON in that shape instead of prose. An agent() call resolves to null if it is stopped or hits an unrecoverable error, and pipeline() keeps those nulls, which is why the results are filtered. And the script itself has no file or shell access: agents do the reading and running, and the script only coordinates.

Watch and manage the run. /workflows opens the progress view. In it, p pauses or resumes, x stops the selected agent or the whole run, r restarts a running agent, and s saves the script as a command, either to .claude/workflows/ in the project or ~/.claude/workflows/ for yourself. A saved workflow then runs as /<name>.

Know the limits. As of November 2026 the runtime allows up to 16 concurrent agents by default (fewer on machines with fewer CPUs), 1,000 agents per run, and no user input mid-run. That last one shapes design: if you want sign-off between stages, the docs say to run each stage as its own workflow.

Cost and failure modes

The documentation is direct about cost: "a single run can use meaningfully more tokens than working through the same task in conversation," and runs count toward your plan's usage and rate limits. Claude Code shows a Large workflow warning when a run schedules more than 25 agents or its projected total passes 1.5 million tokens. The warning is advisory.

The cheapest safeguard is in the docs too: run the workflow on a small slice first. One directory, not the repository. Then read the per-agent token usage in /workflows before you scale up.

The rest of this section is what the documentation could not have told us in advance.

A fan-out can fill your disk. A ten-agent workflow doing image-heavy work, alongside video encoding and a headless browser, pushed an 18 GB laptop into swap. On that machine swap shares storage with everything else. Free disk went from 7.9 GB to zero, and the shell stopped running until the workflow was stopped. Token limits are not the only budget. Before a wide run we check free disk and swap use, cap concurrency when headroom is under about 10 GB, and delete intermediate files as each stage lands.

You cannot easily reach a running agent. In October we sent a message to a workflow agent while it was running, to give it a credit limit we had forgotten. The tool reported that it was resuming the agent, and a second copy started from the same transcript. The new copy received the message. The one doing the work never saw it. We have not retested this on the current version, and the docs now describe a guard against relaunching a run while its old agents are still alive, so the behaviour may differ today. The rule we kept is version-proof: put limits in the brief and in the files the agent reads before launch, and steer a running agent through those files, not through messages.

Stopping is not always clean. In our runs, stopping a workflow left some agents' child processes, such as a browser, still running, and we cleaned them up by hand.

Worktree isolation needs a git repository. A workflow we launched with worktree isolation from a directory outside the repository failed with an error saying so. Start from inside the repo, or split parallel fixers by file ownership.

Usage limits arrive for everyone at once. Nine research agents ran in parallel for about ninety minutes, hit the limit together, and one partial notes file was all that had reached disk. Recovering their reading from the transcripts cost about a tenth of the original run. Today's docs describe workflow runs pausing at a subscription usage limit and continuing after the reset, under several conditions. We still tell every long-running agent to write notes to disk before its first web call.

Scheduling, cloud runs, and asking first

Some workflows should run without you. The documented options, compared in the scheduling docs:

  • /loop 5m check the deploy re-runs a prompt while the session is open. Recurring loops expire after seven days.
  • Cloud scheduled tasks run on Anthropic's infrastructure from a fresh clone, on a schedule, an API call or a GitHub event. The docs mark them as a research preview. Minimum interval: one hour.
  • GitHub Actions for scheduling that lives with the repository.

Our own scheduled agents are of the last kind: a set of GitHub Actions workflows in our site's repository that call the Claude API, described in building a daily SEO audit agent. We have not run cloud scheduled tasks in production, so treat that bullet as documentation only.

Two cautions from our notes.

A cloud session is not your laptop. When we checked in October, claude --cloud needed a git repository to start from, and the cloud session did not receive our user-level instruction file, memory, locally added MCP servers or local credentials. It did get the repository's own CLAUDE.md and .claude/ folder. To move work up, we write a handoff file into the repo, commit it, and start the cloud session with "Continue from HANDOFF.md." Cloud suits long, self-contained work in one repository.

A job that starts itself needs a yes. When a ticket called for a nightly job on a Mac, Claude Code's auto mode blocked the install command as unauthorised persistence. We agree with the block. The rule now: build and test the job, then ask for the install with the exact command and how to remove it, then check the first scheduled run. A successful manual run does not prove the schedule works.

Workflow vs skill, and a cheatsheet

The docs compare the options by one question: who holds the plan?

Skill Subagent Dynamic workflow
What it is Instructions Claude follows A worker Claude starts A script the runtime executes
Who decides the next step Claude, following the prompt Claude, turn by turn The script
Where intermediate results live The conversation The conversation Script variables
Scale One conversation A few tasks per turn Dozens to hundreds of agents

If the job is "do this procedure properly," write a skill. If it is "do this to four hundred files and cross-check the results," ask for a workflow. We sort the mechanisms in Claude Code skills vs subagents vs hooks.

Cheatsheet, as of November 2026:

You want to Use
Plan before any edit Shift+Tab to plan mode, or claude --permission-mode plan
Drop history between tasks /clear
Shrink a long session, keeping what matters /compact keep <what to keep>
Keep Claude going until a condition holds /goal <condition>
Get a review from fresh eyes /code-review
Run a session in its own checkout claude -w <name>
Start a background session claude --bg "<task>"
See all background sessions claude agents
See what is running in this session /tasks
Split one big mechanical change /batch <instruction>
Run a task as a workflow "use a workflow to…" or the keyword ultracode
Research across many sources /deep-research <question>
Watch, pause, stop or save a run /workflows, then p, x, s
Poll something while you work /loop 5m <prompt>
Schedule a cloud run /schedule <description>

A Claude Code workflow, in either sense, is a loop with a check in it. Get the single-session version right first. Then widen it only when the work is wide, and budget for tokens, memory and the cleanup.

If you would like that loop built around your own systems, with the checks and the limits designed in, that is what our AI integration service does. Tell us about the job you want to hand to an agent.

Common questions

What is a good Claude Code workflow?

For one session: plan before editing, build in small steps, and verify with something that returns pass or fail. Give Claude the command that runs your tests or build, ask for the output as evidence, and clear the conversation between unrelated tasks. That loop covers most work. Multi-agent features such as subagents and dynamic workflows are for jobs that are too wide for one conversation, not a replacement for the loop.

What is the Claude Code workflow tool?

It is the mechanism behind dynamic workflows. As of November 2026, Claude Code can write a JavaScript script that orchestrates many subagents, and a runtime executes that script in the background while your session stays usable. The script holds the loop, the branching and the intermediate results, so only the final answer comes back into the conversation. You watch and manage runs with the /workflows command. The documentation says it is available on all paid plans and through the API.

Can you show a Claude Code workflow example?

The bundled one is /deep-research followed by a question: it fans out web searches, cross-checks the sources, and returns a cited report. For your own, describe the job and ask for a workflow, for example: use a workflow to review every file changed in this PR for correctness issues, then merge the per-file findings into one ranked summary. Claude writes the script, shows you the planned phases, and runs it once you approve.

What are the best Claude Code workflow tips?

Run a wide job on a small slice first to see the cost. Put limits such as credit ceilings in the brief before launch, because a running agent is hard to reach. Have agents write notes to disk as they go. Check free disk space and memory before a large fan-out on a laptop. Give each parallel session its own git worktree. And keep verification in the script: a second agent that tries to disprove each finding is worth more than a longer first pass.

What is the Claude Code workflow feature called?

The documentation calls it dynamic workflows. It sits beside four other documented ways to run work in parallel: subagents, agent view for background sessions, agent teams, and projects. The related setting that makes Claude plan a workflow for every substantial task is called ultracode, turned on with /effort ultracode. Names in this area have changed more than once, so check the current docs before relying on a term from an older article.

Claude Code workflow vs skill: what is the difference?

A skill is a set of instructions Claude follows inside the conversation, deciding each next step itself. A workflow is a script the runtime executes, and the script decides what runs next. Skills suit procedures that need judgement and full context. Workflows suit jobs with dozens to hundreds of agents where you want the orchestration fixed and repeatable. A saved workflow becomes a slash command, which is why the two can look alike from the prompt.

Is there a Claude Code workflow cheatsheet?

The short form: Shift+Tab to reach plan mode; /clear between unrelated tasks; /compact with a focus on long ones; claude -w and a name for a session in its own worktree; claude agents for the background-session view; /tasks for what is running in this session; /workflows to watch, pause, stop or save a workflow run; /loop with an interval and a prompt for polling; /schedule for cloud scheduled tasks. The full table is in the article.