What Dynamic Workflows Actually Do

Anthropic shipped dynamic workflows in Claude Code on May 28, 2026, and the headline stat is striking: up to 1,000 parallel subagents per run, capable of work that would have filled a quarter-long engineering roadmap. But the real story is more specific — and more useful — than the number suggests.

A dynamic workflow is a JavaScript orchestration script that Claude writes at runtime based on your prompt. The script fans work out across parallel subagents, each tackling a bounded slice of the task. Results are verified by independent reviewer agents before being folded into the final output. Your main session stays responsive throughout; the heavy lifting happens in the background, with progress checkpointed so that an interrupted run picks up where it left off.

For large-scale migrations specifically — framework swaps, API deprecations, language ports — this is a qualitative shift. The problem with running a single agent across a 100,000-line codebase isn’t intelligence; it’s context window and coordination. Dynamic workflows break the problem into parallel units that fit comfortably in each agent’s context, then stitch the results together under the orchestrator’s supervision.

This guide covers how to actually use the feature for a substantial migration: what to set up, how to structure the prompt, what to watch during the run, and what the Bun Zig-to-Rust rewrite reveals about the tradeoffs you’ll face.

Prerequisites: What You’ll Need

Before you type a prompt, verify you have the following in place:

• Claude Code v2.1.154 or later. Run claude --version to check. Update with npm install -g @anthropic-ai/claude-code@latest if needed.
• An eligible plan. Dynamic workflows are available on Max, Team, and Enterprise plans (Enterprise requires admin enablement via Claude Code settings), and on the Anthropic API, Amazon Bedrock, Google Cloud Vertex AI, and Microsoft Foundry. If you’re on a Team plan in an org, confirm your admin hasn’t disabled the feature.
• Auto mode enabled. Dynamic workflows perform best when Claude can decide how to handle subtask allocation. Set effort level to auto in the effort menu before starting.
• A version-controlled codebase with a working test suite. This is not optional. Dynamic workflows modify many files in parallel. Without a baseline test suite and a clean git state, you have no ground truth to validate against after the run.
• A rough count of the files in scope. Know your migration surface area before you prompt. The workflow orchestration is proportional to scope — prompting to migrate an entire monorepo without narrowing scope will be expensive and slow. If the migration targets a specific service or module, say so explicitly.

One honest warning: dynamic workflows consume substantially more tokens than a standard Claude Code session. Anthropic’s own documentation flags this. On a 50,000-line migration, expect to burn through a meaningful fraction of a monthly Max or Team token budget. Run a dry-run scoped to a single module first to calibrate costs before committing to the full codebase.

Phase 1 — Plan and Scope the Migration

The quality of the orchestration script Claude generates is almost entirely determined by the quality of your initial prompt. Vague prompts produce sprawling, hard-to-validate runs. Specific prompts produce auditable, incremental ones.

Write a Migration Brief, Not a Single Line

Before invoking the workflow, write a short brief in your CLAUDE.md or inline in the prompt. A useful brief covers four things:

1. What you’re migrating from and to — exact frameworks, libraries, or languages, with version numbers.
2. The scope — which directories, modules, or files are in scope, and which are explicitly out of scope.
3. Invariants you need preserved — test suite must pass, public API signatures must not change, no new runtime dependencies without review.
4. Phase boundaries, if any — if you want to migrate read paths first, then write paths, say so. The orchestrator will reflect this in how it sequences subagents.

An example brief for a React 18 to React 19 migration might look like:

Migrate the /src/components directory from React 18 to React 19.
Scope: all .tsx files under /src/components. Exclude /src/legacy.
Invariants: all Vitest tests must pass after migration; no changes
to exported prop interfaces; deprecate old lifecycle methods using
React 19 equivalents, not by deletion.
Phase 1: migrate leaf components with no sub-imports.
Phase 2: migrate container components.
Phase 3: migrate root layout components.

This level of detail gives the orchestration script real structure. Without it, Claude will make reasonable but opinionated choices about phasing that may not match your architecture.

Commit a Clean State to Git

Before the workflow touches anything, do a clean commit. You want a deterministic rollback point, and you want git diff to tell you exactly what the workflow changed.

Phase 2 — Launch the Workflow

You have two ways to invoke a workflow:

1. Explicit invocation: Include the word “workflow” in your prompt — e.g., “Create a workflow to migrate /src/components from React 18 to React 19 following the attached brief.” Claude will generate the orchestration script and show it to you before running.
2. Ultracode mode: Turn on ultracode from the effort menu. This sets effort to xhigh and lets Claude decide autonomously when a workflow is appropriate for your task. If the task is large enough, it will spawn the workflow without an explicit trigger.

The first time a workflow triggers in a session, Claude Code shows you the orchestration plan and asks for confirmation. Read it. The plan describes the number of subagents, their roles (writer, reviewer, fix-loop), and the phase structure. If the plan doesn’t match your brief, clarify before confirming — restarting a workflow mid-run is wasteful.

What You’ll See During the Run

Once confirmed, the workflow executes in the background. You’ll see a live progress indicator in the CLI or IDE extension. Individual subagents surface findings incrementally — you don’t have to wait for the full run to see early results.

For a migration, the typical workflow structure is:

• Phase A (writer agents): Each agent takes a bounded file set and writes the migrated version. At this stage, the code may not compile — Phase A is about behavioral equivalence at the file level, not build-level correctness.
• Phase B (reviewer agents): Independent agents check each writer’s output against the original, flagging semantic drift, missing edge cases, and introduced patterns that violate your invariants.
• Phase C (fix-loop agents): Compilation errors, test failures, and reviewer flags are addressed crate-by-crate or module-by-module until the build and test suite pass.

This three-phase shape is what Jarred Sumner used for the Bun rewrite, and it’s reflected in Anthropic’s official documentation as the recommended pattern for large migrations.

Phase 3 — Monitor, Verify, and Merge

The workflow’s self-verification loop doesn’t mean you’re off the hook. Here’s what to watch and check before you merge anything.

Run the Full Test Suite Independently

When the workflow reports completion, run your test suite yourself in a clean environment. The workflow’s internal test runner operates in the background sandbox; your CI pipeline may catch platform-specific failures it missed. This is especially important for migrations involving native modules, system calls, or platform-specific behavior.

Review the Unsafe or Unchecked Code the Workflow Introduced

The Bun rewrite is instructive here. After 960,000 lines of Zig were ported to Rust in six days and 6,755 commits, the resulting codebase contained 13,044 unsafe Rust blocks, compared to 73 in comparable hand-written Rust. The migration passed 99.8% of the test suite — an impressive result — but the safety debt is significant and will require systematic review before the code can be considered production-quality by Rust idiom standards. The Bun team instructed the workflow to add SAFETY comments on every unsafe block, which at least makes the debt visible and auditable.

Whatever your target language or framework, the same principle applies: dynamic workflows optimize for behavioral equivalence and test pass rate, not for idiomatic style or safety posture. Use your code review process to catch what the agents de-prioritized.

Use Git Diff as Your Primary Audit Tool

Because you committed a clean state before the run, git diff gives you a complete picture of every file the workflow touched. For large migrations, use a focused diff review: spot-check 10–15% of changed files against the original, focusing on the most complex ones (high cyclomatic complexity, heavy use of the migrated API, most test coverage).

Stage the Merge

Don’t merge the full migration output in a single PR. Instead, merge by phase or by module. This makes review tractable, keeps the blame history clean, and lets you catch integration failures at module boundaries before they compound.

What the Bun Rewrite Teaches

The Bun Zig-to-Rust migration is the most extensively documented public use of dynamic workflows at scale to date, and it contains more useful signal than most early-access case studies.

Jarred Sumner initiated the rewrite after Zig’s language team implemented a strict no-AI-contributions policy in early 2026 — Anthropic had acquired Bun in December 2025 and the team relied on Claude models for refactoring and optimization work. The language switch was forced by governance, not engineering preference. That’s an unusual origin story, but the execution of the rewrite itself is what’s instructive.

The migration ran across approximately 960,000 lines of code and completed in six days. The test suite reached 99.8% pass rate on Linux x64. The binary shrank by 3 to 8 MB. Post-migration, the Bun team ran an overnight optimization workflow that identified unnecessary data copies and opened individual PRs for each, which is a clean example of how follow-up workflows can automate the cleanup work that typically follows a large rewrite.

The honest caveat: the rewrite is not yet in production. The 13,044 unsafe blocks represent real work before the code meets Rust’s safety standards. “Six days to a passing test suite” is genuinely impressive, but “six days to production-ready Rust” is a different claim. The two are not the same.

For your own migration, calibrate expectations accordingly. Dynamic workflows will get you to a passing test suite faster than any other method. They will not replace the code review, integration testing, and safety audit that follow.

Limitations to Account For

Three constraints matter most for planning purposes:

Token cost scales with scope. Each subagent burns tokens on the model it runs against. At 1,000 agents, the token consumption of a single workflow can exceed what most teams budget for a day of normal Claude Code usage. Scope your first workflow conservatively, measure actual usage, and extrapolate before committing the full codebase.

Workflows are not magic context windows. The orchestrator coordinates subagents but each subagent still operates within a bounded context. For migrations involving deeply coupled modules where behavior depends on cross-file state, the agent handling file A doesn’t inherently know the full internals of file B. Your migration brief needs to surface these coupling points explicitly — or the workflow will handle them with plausible-but-wrong assumptions.

The feature is in research preview. Anthropic flagged this explicitly at launch. The API surface may change. Workflow scripts that work today may require updates when the feature graduates from preview. Don’t build production automation on top of the current orchestration script format without planning for migration.

None of these constraints makes the feature less valuable. They make it important to start small, measure carefully, and treat the first run as a calibration exercise.

Further Reading

• Orchestrate subagents at scale with dynamic workflows — Claude Code Docs — The official reference, covering the WORKFLOW.js format, ultracode mode, and admin settings for Enterprise.
• Claude Opus 4.8: Dynamic Workflows, 1,000 Parallel Agents — Our coverage of yesterday’s release, including the effort controls and fast-mode pricing changes shipped alongside workflows.
• Bun’s Zig-to-Rust Rewrite: Engineering Realities of Language Backend Migration — A detailed technical post-mortem on the unsafe block debt, Rust lifetime mapping challenges, and what the rewrite reveals about AI-assisted large-scale porting.