Claude Code Dynamic Workflows Explained

claude-code-dynamic-workflows-explained.md

Claude Code Dynamic Workflows, Explained

A practical guide to what dynamic workflows are, how a Claude Code agent uses them, and where they actually help. Written for teammates who already use Claude Code but haven't dug into this feature yet.

Status: research preview, Claude Code v2.1.154+. On Pro you turn it on in /config ("Dynamic workflows"). Available on all paid plans plus Anthropic API, Bedrock, Vertex AI, and Foundry.

How to read the source labels. This guide mixes three kinds of claims, and they're tagged inline so you can weigh them:

• [DOCS] - stated in Anthropic's official documentation. Take as authoritative.
• [OBSERVED] - discovered by having a Claude Code agent inspect its own tooling (the Workflow tool's built-in description and the shipped deep-research workflow). The official docs deliberately don't publish the scripting API, so these details came from the agent examining what it actually has access to. High confidence, but not officially documented - could change between versions.
• [SPECULATION] - our reasoned guesses about intent and possible uses. Clearly our opinion, not Anthropic's word.

---

The one-sentence version

A dynamic workflow is a small script that sends a whole fleet of AI sub-agents off to do work in the background, keeps all their messy intermediate output out of the main conversation, and hands back only the finished result.

The problem it solves

When you ask Claude Code to do something big - "audit every endpoint for missing auth," "research this thoroughly," "migrate these 400 files" - it normally works through it in the conversation, one step at a time. It can delegate to a few helper agents, but every helper's output comes back into the main chat. That has two costs:

1. The context fills up. Read 40 files and all 40 land in the conversation, crowding out everything else.
2. It doesn't really parallelize. Coordinating more than a handful of helpers turn-by-turn gets unwieldy fast.

Dynamic workflows fix both by moving the plan out of the conversation and into a script that a separate runtime executes. The sub-agents' chatter stays in the script's own memory; only the final answer comes back. That's what lets one run coordinate dozens - even hundreds - of agents without drowning the main session.

How it's different from the things you already know

Think of it as a third option alongside two you've probably used:

• Sub-agents - Claude spawns a helper, gets the answer back into the chat. Great for one or two delegated tasks. The plan lives in Claude's head.
• Skills - reusable instructions Claude follows. Also keep the plan in Claude's head.
• Workflows - the plan is code. A runtime holds the loop, the branching, and all the partial results. Claude only sees the final return.

The practical line: if the job is small enough for Claude to hold the whole plan in its head, use sub-agents or a skill. If it needs more agents than one conversation can juggle, or you want to save the orchestration and re-run it later, use a workflow.

There's a bonus that's easy to miss: because a workflow is code, it can bake in a quality pattern, not just "more agents." [OBSERVED] The built-in research workflow, for example, has three independent agents try to disprove every claim before it's allowed into the final report. That kind of adversarial cross-check is hard to do reliably by hand and trivial to encode in a script. [DOCS] Anthropic explicitly calls this out as a core reason to use workflows - "a more trustworthy result than a single pass."

How a Claude Code agent actually invokes one

You don't write JavaScript. Here's the real flow:

To trigger one for a task: just include the word "workflow" in your prompt - e.g. "Run a workflow to audit every API route under src/ for missing auth checks." Claude writes the script for you, shows you the planned phases, and asks for approval before anything runs. (Prefer /effort ultracode and Claude will decide on its own when a task is big enough to warrant a workflow.)

What happens under the hood:

1. Claude writes a script (you can view it before approving - it shows the phases it plans to run).
2. You approve. The run starts in the background - your session stays free to keep working.
3. You watch progress with /workflows (arrow keys to drill into any phase and see what each agent found), or glance at the one-line summary in the task panel.
4. When it finishes, the final result lands back in your conversation - just the distilled answer, not the hundreds of intermediate steps.

For workflows that already exist (the built-in one, or any your team has saved), Claude invokes them by name. [OBSERVED] It reads the workflow's description to understand what input it needs - and here's the nice part: if the input is too vague, the workflow's own description can instruct Claude to ask you a couple of clarifying questions first, then weave your answers into the run. The built-in research workflow does exactly this - its description literally says to ask 2-3 clarifying questions if the question is underspecified, otherwise just go. (This means the author of a workflow controls how smart it is about asking you for the right inputs.)

So from your seat: you describe the goal in plain language, Claude figures out whether it needs more detail and asks if so, the work happens in the background, and you get a clean result.

The one built-in: /deep-research

Claude Code ships with a single bundled workflow, /deep-research, and it's the best way to see the feature in action:

/deep-research What changed in the Node.js permission model between v20 and v22?

[OBSERVED] What it does behind the scenes (we know these specifics because the agent inspected the actual shipped workflow):

1. Breaks your question into ~5 different search angles.
2. Runs a web search for each angle in parallel.
3. Fetches the best ~15 sources, de-duplicates them, and pulls out concrete checkable claims (each with a supporting quote).
4. Sends each claim to 3 independent "skeptic" agents whose job is to refute it - a claim survives only if fewer than 2 of the 3 manage to refute it.
5. Synthesizes a cited report from what's left, with the failed claims filtered out (and listed separately, for transparency).

You get one trustworthy, sourced report instead of a wall of search results - and your main conversation never sees the ~75 verification steps that produced it.

Saving and sharing workflows

Once a workflow does what you wanted, you can keep it. In /workflows, select the run and press s. You choose where it goes:

• Personal (~/.claude/workflows/) - available in all your projects, just for you.
• Team (.claude/workflows/ in the repo) - commit it, and everyone who clones the repo gets it as a /command.

A saved workflow shows up exactly like a built-in command in autocomplete. This is the real team payoff: encode "the review we run on every branch" or "our standard incident research" once, commit it, and the whole team runs the identical orchestration with one command. The process becomes a versioned, shared artifact instead of tribal knowledge.

Where it actually helps (use-cases)

Strong fits:

• Codebase-wide audits - "check every route for missing auth," "find every place we log PII." Lots of files, each agent reads-and-reports, near-zero conflict. This is the sweet spot.
• Deep research with cross-checking - the built-in case. Many sources, verified against each other.
• Large mechanical migrations - rename a pattern across hundreds of files, add a header to every module. Each file's change is independent; fan out, then reconcile.
• Hard decisions worth several angles - draft a plan or design three different ways, weigh them against each other, pick the best. More trustworthy than one-and-done.
• Long, heavy single tasks - even with one agent: "go read these 40 files and summarize the auth flow." The reading happens off to the side; you get back a summary, not 40 files in your context. (Scale isn't the only reason to reach for it - keeping a big grind out of the main conversation is reason enough.)

Poor fits - don't force these:

• Tightly coupled work where everything depends on everything else (e.g. backend + shared types + frontend for one feature). The dependency chain is the bottleneck; parallel agents just create a painful merge later. Parallelize the genuinely independent parts, keep the coupled core sequential.
• Anything needing your input mid-run. A workflow can't stop to ask you a question partway through (only a permission prompt can pause it). If you need sign-off between stages, run each stage as its own workflow.
• Small tasks where a single agent or a quick delegation is simpler. A workflow spawns many agents and costs more tokens - don't bring the crane to hang a picture.

How Anthropic intends it to be used [DOCS]

From their documentation, the framing is consistent:

• 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 re-run.
• The headline value isn't just "more agents" - it's the ability to apply a repeatable quality pattern: independent agents adversarially reviewing each other's findings, or multiple independent attempts weighed against each other, producing a more trustworthy result than a single pass.
• Their own examples: a codebase-wide bug sweep, a 500-file migration, a research question that needs sources cross-checked, and a hard plan worth drafting from several independent angles before committing.
• Be aware of cost: a workflow run uses meaningfully more tokens than doing the same task in conversation, and it counts toward your usage limits. Check which model you're on before a big run; for stages that don't need the strongest model, Claude can route them to a cheaper one.

Where this could go - our speculation [SPECULATION]

Everything in this section is our own reasoning about possibilities, not something Anthropic has stated. The feature is new and in preview, so treat these as "worth trying," not "supported recipes." The underlying capability that makes all of these plausible is simple: fan a job out to many independent agents, keep their work off to the side, get back a synthesis - and increasingly, those agents can use any tool or integration Claude Code can reach.

For engineers:

• Pre-merge review gauntlet - one workflow that runs several independent reviewers over a diff (security lens, performance lens, test-coverage lens, "does this match the ticket" lens), each blind to the others, then merges their findings. Save it to the repo as /review and the whole team runs the same bar on every PR.
• Dependency or license sweep - fan out across every package/module, have each agent report what it pulls in, flag anything risky, synthesize a single report.
• Test-gap hunting - one agent per module asking "what's the nastiest untested edge case here?", then a second pass that tries to actually write a failing test for each. Hundreds of files, one command.
• Incident triage - a saved workflow that, given an error signature, fans out across logs, recent commits, related services, and known-issue trackers in parallel, then assembles a ranked list of likely causes. Turn the 2am scramble into one command.
• Documentation drift detection - agents compare each doc page against the code it describes and report mismatches.
• "Explain this codebase to me" - fan out readers across subsystems, each summarizing one area, synthesized into an onboarding map - without any of the raw file content clogging your session.

For non-engineers (anyone using Claude Code or a Claude surface that exposes this - and especially as these tools connect to more of your everyday apps):

• Competitive / market scans - the deep-research pattern isn't just for technical questions. "Compare these five vendors across price, support, and reviews," with every claim cross-checked before it reaches you. Useful for ops, procurement, marketing, sales.
• Document review at volume - fan out across a folder of contracts, policies, or applications, each agent extracting the same set of fields or flagging the same risks, collated into one spreadsheet-like summary.
• Content audits - check every page of a website or knowledge base against a style guide, a brand checklist, or for outdated facts.
• Literature / source reviews - researchers, students, analysts: gather many sources on a question and get back only the claims that survived adversarial cross-checking, with citations.
• Due diligence and background synthesis - pull together what's publicly knowable about a company, a partner, or a topic from many angles at once, verified rather than first-hit.
• Personal "many small lookups" jobs - planning a trip, comparing options, reconciling a pile of notes: anything that's really N independent little research tasks plus a summary is a natural fit, and keeps the grind out of your main chat.

The honest caveat on all of the above: workflows cost more tokens than a normal chat, they can't pause to ask you mid-run, and the feature is a preview. The ones most likely to pay off are the repeatable jobs - the review, the scan, the audit you do over and over - because you save the workflow once and the whole team gets a one-command tool. [SPECULATION ends]

The mental model to walk away with

You describe a goal. If it's the kind of job that needs a small army of agents - or one you'll want to repeat - Claude writes a script, asks for your OK, and runs the army in the background. The army's chatter stays out of your way; you get back the finished work. Save the good ones and they become one-command tools your whole team can run.

Quick reference

Thing	How
Turn it on	/config -> "Dynamic workflows"
Run one for a task	Put the word "workflow" in your prompt
Let Claude decide when	/effort ultracode
Run the built-in	/deep-research <question>
Watch progress	/workflows
Save a good run	/workflows -> select -> s
Share with team	Save to .claude/workflows/ and commit
Turn it off	/config, or disableWorkflows in settings

Resources and links

Official Anthropic documentation [DOCS]:

• Dynamic workflows - the primary doc this guide is built on (when to use, running /deep-research, having Claude write one, saving/sharing, limits, turning it off).
• Sub-agents - the worker primitive that workflows orchestrate.
• Run agents in parallel - compares sub-agents, the agent view, agent teams, and workflows.
• Skills - the "instructions Claude follows" alternative.
• Permission modes - governs the launch-approval prompt.
• Manage costs - how multi-agent runs count toward usage limits.
• Settings reference - including disableWorkflows.

A note on the [OBSERVED] details: the specifics about how the built-in deep-research workflow is structured, and how a Claude Code agent reads a workflow's input requirements, are not in the public docs - the scripting API is intentionally undocumented in this preview. Those came from having a Claude Code agent (running v2.1.154) inspect its own tooling. If you're reading this on a later version, double-check anything tagged [OBSERVED], as internals can shift between releases.