Claude Code Workflows: Patterns That Work

A Claude Code workflow is either a built-in feature or a habit. The feature, dynamic workflows, is a script that runs many subagents in the background and gives you one answer. The habit is a loop you repeat: give Claude a check to run, review in a fresh context, run sessions in parallel, schedule what recurs. This page covers both. We checked Anthropic's docs on 31 October 2026.

Quick facts

Part 1: dynamic workflows

What they are

Anthropic's docs define a dynamic workflow as a JavaScript script that orchestrates many subagents at once. You describe the task. Claude writes the script. A runtime executes it in the background while your session stays responsive.

The difference from a normal session is who holds the plan. With subagents, skills and agent teams, Claude is the orchestrator: it decides turn by turn what to do next, and every result goes into a context window. With a workflow, the script holds the loop, the branching and the intermediate results, so Claude's context holds only the final answer.

A workflow also makes quality patterns practical. It can have independent agents adversarially review each other's findings before reporting, or draft a plan from several angles and weigh them. That is more trustworthy than a single pass, because no one agent marks its own homework.

Run one now

The quickest way to see it is the bundled workflow:

/deep-research What changed between MCP spec versions this year, and which clients support the newest one?

Per the docs, it fans out web searches across several angles, fetches and cross-checks the sources, votes on each claim and returns a cited report with claims that did not survive cross-checking filtered out. It runs only when you invoke it.

Ask Claude to write one

You do not write the script. You say what you want. The docs give these shapes:

Audit many files for the same issue

use a workflow to audit every route handler under src/routes/ for missing authentication checks, and adversarially verify each finding before reporting it

Keep fixing until a check passes

use a workflow to run npx tsc --noEmit and keep fixing the reported errors until the type check passes or two rounds in a row make no progress

Migrate many files in parallel

use a workflow to migrate every component under src/components/ from JavaScript to TypeScript, working on each file in its own isolated copy

Two more shapes the docs name: review every changed file and write one summary (a reviewer per file, then one agent ranks and deduplicates), and research a topic across many sources.

Before it runs you can approve the plan. After it runs you can save it, so it becomes a command in / autocomplete, and you can pass input to a saved workflow. A saved script can ship in a plugin. The docs also describe an ultracode keyword for a single prompt, and /effort ultracode, which makes Claude plan a workflow for every substantive task in the session. That is a heavy setting, so know the cost first.

Limits and behaviour

From the docs:

• No mid-run user input. A run pauses only for agent permission prompts and usage-limit waits. For sign-off between stages, run each stage as its own workflow.
• The script cannot touch the filesystem or shell itself. Agents read, write and run commands; the script coordinates them.
• No module loading. A script that contains import() fails before it starts.
• Up to 16 concurrent agents by default, fewer on a machine with fewer CPUs.
• Up to 4,096 items in one parallel() or pipeline() call, and 1,000 agents total per run.
• Runs are resumable in the same session after a pause or a usage limit.

Cost

The docs are plain: a workflow spawns many agents, so one run can use meaningfully more tokens than the same task in conversation, and it counts toward your plan's usage and rate limits.

How to keep it sane:

1. Try a slice first: one directory instead of the repo, a narrow question instead of a broad one.
2. Watch /workflows, which shows each agent's token usage, and stop the run there if it balloons. Completed work is usually kept.
3. Check /model before a big run. Ask Claude to use a smaller model for stages that do not need the strongest one.
4. Heed the Large workflow warning, which appears past 25 agents or 1.5 million projected tokens. It is advisory and does not stop the run.
5. Set a size guideline if you want a different threshold.

You can turn workflows off if you do not want them.

Part 2: the everyday workflows

Most useful "workflows" are not scripts. They are loops. Anthropic's best practices page is built around a small set of them.

Loop 1: tell Claude what it cannot see

Claude reads your code well. What it cannot find is what was never in the repo: a decision from a meeting, a deploy process in one person's head, the environment variable your tests need. The docs say to write down only what Claude can't find by reading the repo, or what it would waste time rediscovering each session. Keep CLAUDE.md short. See our CLAUDE.md starter template.

Loop 2: plan before you build

Brainstorm first, ask for a plan, review it, then let Claude implement. Plan mode (/plan, or Shift+Tab) keeps Claude read-only while it works out the approach. Our plan-before-coding prompt is a ready version.

Loop 3: give Claude a check to run

This is the single highest-value habit in the docs. Claude stops when the work looks done. If it has nothing to run that says whether the work is done, you are the test suite.

The page lists four levels, from loose to strict:

Whichever you choose, ask for evidence: the command it ran and its output, or a screenshot. "All tests pass" on its own tells you little. After Claude says it is done, /verify builds and runs the app and looks at the result, which catches what tests and typechecks miss.

For front-end work, pair the loop with a browser: Playwright MCP or Chrome DevTools MCP. Our browser QA recipe shows the shape.

Loop 4: review in a fresh context

The code's author is a poor reviewer of it. A subagent reviewer, or /code-review, starts without your conversation and so is not swayed by the reasoning that produced the code. See our code review subagent.

Loop 5: enforce what cannot have exceptions

Instructions can be forgotten. Rules that must always hold belong in hooks and permissions: a hook that runs formatting or blocks a command, permission rules, and the sandbox. The docs contrast deterministic and non-deterministic instructions. A line in CLAUDE.md is a request; a hook is a rule.

Loop 6: parallel sessions

When you have separate pieces of work, give each its own checkout so edits do not collide:

claude -w feature-auth

--worktree starts a session in a new git worktree under .claude/worktrees/. A worktree is a fresh checkout, so gitignored files such as .env are missing. List the small ones you need in a .worktreeinclude file at the project root. It copies rather than links, so do not put node_modules in it. The docs mention a setting for symlinking large directories instead.

Loop 7: run from a script

claude -p runs once and exits, which is how Claude Code lands in CI jobs, git hooks and shell loops. The docs' own example:

for file in $(cat files.txt); do
  claude --bare -p "Migrate $file to the new logger API and commit. Reply OK or FAIL." \
    --allowedTools "Read,Edit,Bash(git add *),Bash(git commit *)" \
    --permission-mode dontAsk \
    --max-turns 20
done

--bare skips hooks, skills, plugins, MCP servers and CLAUDE.md so the run behaves the same everywhere. --permission-mode dontAsk refuses anything not pre-approved. --max-turns caps a runaway. Try it on three files before the rest. Add --max-budget-usd for a spend cap.

Loop 8: start runs on a schedule or an event

Claude can run a long task by itself; something has to start it. Inside a session, /loop repeats a prompt on an interval:

/loop 15m check CI on this branch, and if it is red pull the failing job's log, fix it and push

For anything that should happen while your laptop is closed, /schedule sets up a cloud scheduled task. The docs warn: before you leave a cloud scheduled task running, protect main with a GitHub branch rule the task cannot bypass, and watch the first few runs.

The unattended checklist

The best practices page gives five questions to answer before you leave a task running:

1. Does it know what done looks like? A goal condition, a spec file or a failing test to turn green.
2. Can it check its own work? Tests, a Stop hook or a review step.
3. What is it allowed to touch? Permission rules, dontAsk, the sandbox, a worktree, the one branch it may push to.
4. What stops it? --max-turns, --max-budget-usd or a spend limit.
5. Where does the result go, and who signs off? A PR or summary, then a person approves the merge or deploy.

The docs say what stays with you: starting it, deciding what done means this time, and approving the merge at the end.

Pick the right tool

Real prompts to copy

Before you change anything, write a plan for the new rate limiter in a
numbered list. Wait for my approval.

Implement it. After each step, run npm test and paste the output. Do
not say done until the whole suite passes.

Now review the diff as a stranger would. Run /code-review and list
anything it flags.

use a workflow to find every place we call the old client and migrate
it, one isolated copy per file, and verify each result with the tests

Limits and cautions

• Workflows spend tokens fast. Start small and read the cost section above.
• No mid-run input in a workflow. Split staged work into separate runs.
• Unattended runs need guardrails. Turn caps, budget caps, narrow permissions and a human at the merge.
• Hooks are code. A Stop hook that runs your script runs on your machine.
• Cloud schedules change shared branches. Protect main.
• Feature availability varies by plan and platform, and the docs note requirements such as Claude Code v2.1.269 for the concurrency setting.
• Vendor lock. These patterns are Claude Code features. Ideas carry over to other agents, but the commands do not.

Our take

We read the docs and did not run a workflow for this page, so we have no timing or cost numbers of our own.

The two meanings of "workflow" are worth keeping apart. The everyday loops give most of the benefit and cost nothing: a check Claude can run, a fresh-context review, a plan before the code. If you do only those, you are ahead of most people.

Dynamic workflows are a different tool for a different size of problem. They suit work you could describe as "do this to every X", and the cost warning is real. We would run one on a slice, read the saved script, and only then scale up.

The most underrated idea in the docs is the evidence rule. Ask for the command and its output every time. It costs one sentence in a prompt, and it is the difference between "it says it worked" and "I saw it work".

Frequently asked questions

What is a Claude Code workflow? A dynamic workflow is a script that orchestrates many subagents; loosely, any repeatable loop.

When should I use a dynamic workflow? For tasks that need more agents than one conversation can coordinate.

How many agents can a workflow run? 16 at once by default and 1,000 per run.

Do workflows cost more? Yes. Start with a small slice.

How do I make Claude check its own work? Give it a pass or fail check, and ask for evidence.

*Product names are used descriptively. We are not affiliated with Anthropic.*