How do I use Claude Dynamic Workflows to migrate a codebase?

Five steps. (1) Update to Claude Code latest (npm i -g @anthropic-ai/claude-code) and ensure you have Opus 4.8 access — Pro, Max, Team, or Enterprise plan, or direct API. (2) Run a scoped pilot on a small subdirectory first to validate Claude's plan and check token cost. (3) Write a clear migration spec: source language/framework, target language/framework, success criteria (tests pass, lint clean, behavior preserved). (4) Invoke Claude Code in your repo root and describe the migration. Dynamic Workflows triggers automatically when Claude judges the task large enough — it writes a JS orchestration script that spawns up to 1,000 subagents (16 concurrent), with adversarial verifier agents reviewing output. (5) Monitor in the Claude Code UI, review the integrated result, run your test suite, and merge. Anthropic's reference demo migrated 750,000 lines of Zig to Rust in 11 days with 99.8% test pass rate.

How much does a codebase migration with Dynamic Workflows cost?

Materially more than a normal Claude Code session — Anthropic explicitly warns to pilot scoped tasks first. Rough order-of-magnitude estimate: a full 750K-line migration using Opus 4.8 standard mode burns hundreds to low thousands of dollars in tokens (the public demo cost was characterized as well into four figures). Fast Mode is ~3x cheaper, which helps. Real cost control tactics: (a) pilot a 5K-line subdirectory first and measure; (b) cache prompts aggressively — Claude Code prompt caching applies; (c) consider direct API billing rather than Claude Code subscription credit pool (the June 15, 2026 billing change means Pro $20 / Max 5x $100 / Max 20x $200 credit pools, which Dynamic Workflows will exhaust quickly); (d) run during off-hours if you're using burst capacity.

What kinds of migrations work best with Dynamic Workflows?

Anything large, parallelizable, and well-defined. Best fits: (1) Language ports — Zig to Rust, Python 2 to 3, JavaScript to TypeScript. (2) Framework upgrades — Vue 2 to Vue 3, Angular major versions, Rails minor upgrades, React class components to hooks. (3) Library swaps — Moment.js to date-fns, axios to fetch, jQuery removal. (4) Security audit sweeps — find and patch every instance of a vulnerable pattern. (5) Test framework migrations — Jest to Vitest, Mocha to Jest. Worst fits: ambiguous business-logic refactors with no clear success criteria, migrations requiring deep human design choices on every file, or anything where you cannot write a clear acceptance test.

How do I verify Claude's migration result before merging?

Four layers. (1) Built-in verification — Dynamic Workflows runs adversarial verifier agents that review each subagent's output before integration; Claude reports overall confidence and flags uncertain regions. (2) Your test suite — run the full suite against the migrated code; the Anthropic Zig-to-Rust demo achieved 99.8% pass rate, target similar. (3) Manual code review — Dynamic Workflows produces a final summary with a list of all touched files and decisions made; review the high-risk files (auth, payment, security-sensitive paths) by hand. (4) Staged rollout — merge behind a feature flag, run in shadow mode against production traffic, compare outputs, then promote. Don't merge an entire codebase migration in one PR; split by directory or by risk tier.

Quick Answer

How to Migrate a Codebase With Claude Dynamic Workflows (2026)

Published: May 31, 2026

How to Migrate a Codebase With Claude Dynamic Workflows

Anthropic’s Dynamic Workflows (shipped May 28, 2026 with Claude Opus 4.8) make codebase-scale migrations practical for the first time — the reference demo did a 750,000-line Zig → Rust port in 11 days with 99.8% test pass rate. Here’s the operating manual.

Last verified: May 31, 2026.

TL;DR — the 5-step process

Update Claude Code, verify Opus 4.8 access.
Pilot on a small scoped subdirectory — measure cost and result quality.
Write a clear migration spec — source, target, success criteria, tests.
Run the full migration with Dynamic Workflows from the repo root.
Verify, stage, and merge — verifier agents + your test suite + manual review of high-risk files + staged rollout behind a flag.

Prerequisites

Item	Detail
Claude Code	Latest version: `npm i -g @anthropic-ai/claude-code`
Opus 4.8 access	Paid Claude plan (Pro, Max, Team, Enterprise) OR direct API
Direct API key (recommended)	`export ANTHROPIC_API_KEY=sk-ant-...`
Repo	Clean git working tree on a feature branch
Tests	Comprehensive test suite that runs against the source codebase
Time	Pilot: hours. Real migration: days to a couple of weeks
Budget	Pilot: $20–100. Full migration: hundreds to low thousands

Billing note: the June 15, 2026 Claude Code billing change introduces a separate credit pool ($20 / $100 / $200 by tier, metered at full API rates, no rollover). Dynamic Workflows will exhaust these credit pools quickly. Use direct API billing for serious migrations.

Step 1 — Update Claude Code, verify Opus 4.8 access

# Install / update
npm i -g @anthropic-ai/claude-code

# Verify version (should be the latest May 28, 2026+ build)
claude --version

# Set your API key (direct API billing recommended for migrations)
export ANTHROPIC_API_KEY=sk-ant-...

# Verify Opus 4.8 is available
claude --model claude-opus-4-8-20260528 "hi"

If the version is older than the May 28, 2026 release, update before continuing — Dynamic Workflows only ship with the new runtime.

Step 2 — Pilot a scoped subdirectory

Pick a small representative subdirectory (5K–20K lines). Migrate just that. Measure:

Result quality — does the migrated code compile, test, and behave correctly?
Token cost — Anthropic surfaces this in Claude Code. Note input + output + cache hits.
Time — how long did Dynamic Workflows take to converge?
Verifier agent flags — what did the adversarial verifier flag for human review?

cd your-repo/some-pilot-subdirectory
claude

In the Claude Code session:

Migrate this subdirectory from {source} to {target}.
Tests are in ../tests/{pilot}. Keep behavior identical.
Run tests after migration and report failures.

Extrapolate the pilot’s cost and quality to the full repo before committing the budget.

Step 3 — Write a clear migration spec

Bad spec: “Port this code to TypeScript.”

Good spec template:

# Migration Spec

## Source
- Language/framework: Python 3.11 + FastAPI 0.110
- Repository: ~120K lines

## Target
- Language/framework: TypeScript 5.4 + Hono 4.0 on Bun 1.1
- Conventions: camelCase, ES2022, strict TS

## Success criteria
- All existing tests pass (currently 1,847 tests, 96.4% coverage)
- Linting passes (eslint + prettier configured in target)
- No external API contract changes
- Performance within 20% of source

## Out of scope
- Database schema changes
- Public API contract changes
- Replacing pydantic models with anything other than zod

## Special cases (high-risk files)
- auth/oauth.py — manual review required
- payments/stripe.py — manual review + extra test runs
- crypto/keys.py — do not migrate, wrap with TS bindings

Hand the spec to Claude Code as the first message of the migration session.

Step 4 — Run the migration

From the repo root:

cd your-repo
claude

In the session, hand Claude the spec and the trigger:

Read MIGRATION-SPEC.md.
Run a full repository migration following the spec.
Use Dynamic Workflows to parallelize.
For each file, write the target file, run the relevant tests, and verify behavior.
Report progress every hour with a status summary.
Stop and ask before touching files in the "Special cases" section.

Claude Opus 4.8 will judge the task large enough and trigger Dynamic Workflows automatically. It will:

Generate a JavaScript orchestration script for the migration.
Spawn up to 1,000 subagents (16 concurrent) — each handling a file or small file group.
Run adversarial verifier agents that review subagent output before integration.
Manage intermediate state in the JS runtime, keeping your Claude session context clean.
Surface a final aggregated result with confidence flags per directory.

Monitor in real time — Claude Code shows live subagent activity, token spend, and confidence breakdown. If you see the cost climbing faster than the pilot extrapolation predicted, pause and recalibrate.

Step 5 — Verify, stage, merge

Four verification layers:

Layer 1 — Built-in verifier agents

Dynamic Workflows already ran adversarial verifiers. Read Claude’s final report:

Per-file confidence — flagged regions get extra scrutiny.
Decisions log — every non-trivial choice Claude made.
Test results — Claude ran tests as it went; review failures.

Layer 2 — Your test suite

Run the full suite against the migrated code:

# In the migrated target
npm test  # or pytest, cargo test, etc.

Target: ≥99% pass rate on the first run (Anthropic’s Zig → Rust demo hit 99.8%). Anything lower needs investigation before merge.

Layer 3 — Manual code review of high-risk files

Even with verifier agents, review by hand:

Authentication and authorization paths
Payment, billing, and financial logic
Cryptographic code
Anything with a security-sensitive blast radius
Any file Claude flagged with low confidence

Layer 4 — Staged rollout

Do not merge the entire migration in one PR. Instead:

Merge behind a feature flag — both implementations live in main.
Shadow mode — route a small % of production traffic to the new implementation, compare outputs, keep the source implementation authoritative.
Gradually promote — increase the percentage, monitor metrics.
Retire the source — only after the target has run authoritatively in production for a representative time window.

Cost-control tactics

Dynamic Workflows burn tokens. Tactics that materially reduce cost:

Use Fast Mode for non-critical subdirectories — ~3x cheaper than standard Opus 4.8.
Prompt caching — Claude Code caches reused context; cache hit rates of 30–60% are realistic on long migrations and roughly double effective budget.
Direct API billing — avoid the credit-pool ceiling after the June 15, 2026 change.
Off-peak runs — some discount programs vary by time.
Split by tier — run the easy 80% with Fast Mode; reserve standard mode for the risky 20%.
Pilot ruthlessly — never extrapolate from a 1K-line pilot to a 1M-line migration; pilot at least 5K–20K lines.

Common pitfalls

Migration spec too vague. Claude can’t infer your conventions — write them down.
No source-of-truth test suite. If you can’t prove behavior, you can’t verify the migration. Build the test suite first.
Merging everything at once. Always stage. Always feature-flag.
Ignoring verifier flags. They exist for a reason — review every low-confidence region.
Letting Dynamic Workflows touch security-critical files unsupervised. Always carve those out as “ask before touching” in the spec.
Underestimating cost. Pilot and extrapolate.

When NOT to use Dynamic Workflows

Ambiguous business-logic refactors with no clear success criteria — write the spec first; if you can’t, the work isn’t ready.
Single-file or small refactors — normal Claude Code handles these better and cheaper.
Migrations requiring product judgment on every file (e.g., “make this UI more modern”) — Dynamic Workflows are a mechanical scale tool, not a design tool.
No test suite — without verification you can’t trust the result.

Verdict

Dynamic Workflows turn “we should migrate this someday” projects into “we should do this next month” projects. The platform is genuinely new — the reference 750K-line Zig → Rust migration in 11 days at 99.8% test pass would have taken a team months in 2024. The keys to success are unchanged from any large code change: clear spec, comprehensive tests, staged rollout, manual review of high-risk paths. Pilot first, measure cost, then commit.

Sources: Anthropic Dynamic Workflows launch (May 28, 2026), Marktechpost Dynamic Workflows technical analysis, Anthropic Claude Code documentation, Zeniteq dynamic workflows writeup, Reworked.co coverage, Towards AI agent-building piece, Anthropic API pricing docs (verified May 31, 2026).