Claude Code dynamic workflows are a research-preview Opus 4.8 capability that can split a complex coding task into parallel subagents and then bring the results back into one reviewable workflow. As of 29 May 2026, this is the most interesting Claude Opus 4.8 feature for developers because it changes Claude Code from a single long-running assistant into a coordinator that can explore several parts of a repository at once.
If you are new to Claude Code, start with my Claude Code in VS Code setup guide first. If you only want the release overview, read Claude Opus 4.8 explained. If your main concern is API migration and model IDs, use the Opus 4.8 API migration guide. This page is the hands-on tutorial for using dynamic workflows without turning your repository into a mystery box.
Quick answer
Use dynamic workflows when a coding task has several independent investigation paths. Good examples include a framework migration, a security audit, a flaky-test investigation, a multi-package dependency upgrade, or a repo-wide performance review. Avoid them for tiny edits, single-file fixes, or tasks where a single narrow prompt is easier to review.
| Use case | Dynamic workflow fit | Why |
|---|---|---|
| Large refactor | Strong | Different subagents can inspect routing, data access, UI, tests, and docs separately. |
| One-line bug fix | Weak | The overhead is larger than the task. |
| Dependency upgrade | Strong | One subagent can inspect package changes while another checks tests and another reviews docs. |
| Security review | Strong | Parallel review helps cover auth, data handling, API boundaries, and logging. |
| Unclear product idea | Medium | It can explore options, but you need to lock scope before implementation. |
How dynamic workflows work conceptually
Think of dynamic workflows as a planning layer on top of Claude Code. Instead of one assistant reading the repo in a single path, Claude can break the job into subproblems. Each subagent investigates a bounded part of the task, reports findings, and the parent workflow combines those findings into a plan or implementation.
This matters because large software work often fails at the discovery stage. A single agent may inspect the obvious files and miss a helper module, test fixture, generated type, or routing rule. Parallel subagents can cover more ground, especially when the task naturally divides by directory, layer, or concern.
The risk is that parallel work can produce parallel confusion. Dynamic workflows are powerful only when you give them boundaries. Name what is in scope, name what is out of scope, and require a final summary that tells you what changed, what was tested, and what still needs human review.
Before you run one
Do not start with "fix everything". That prompt is dramatic, but it creates vague behaviour and broad diffs. Start with a specific goal, a reason, and a review standard. Claude Code should know whether it is allowed to edit files, whether it should only inspect first, and which checks count as success.
- Make sure the repository is in a clean or intentionally understood state.
- Write down the target branch, task, and directories in scope.
- Decide whether the first run is read-only investigation or implementation.
- List the tests, build commands, or manual checks you expect.
- Decide how you will reject or split a diff if the change gets too large.
Prompt pattern for dynamic workflows
The best prompt has five parts: role, goal, scope, workflow, and review output. You are not only telling Claude what to do. You are telling it how to decompose the task and how to bring the results back to you.
You are working in this repository as a careful coding agent.
Goal:
Audit the authentication flow for bugs that could affect login, token refresh,
or logout behaviour.
Scope:
- Inspect src/auth, src/api, src/router, and the related tests.
- Do not edit files in the first pass.
- Do not change formatting or unrelated components.
Workflow:
- Split the investigation into subagents by concern: routing, API calls,
token storage, and tests.
- Each subagent should report concrete files, suspected risks, and evidence.
- After the investigation, combine the findings into a ranked action plan.
Review output:
- Give me a summary table.
- List exact files to change if we proceed.
- Recommend the smallest safe implementation plan.
- Do not make changes until I approve the plan.This kind of prompt gives Claude Code permission to use dynamic exploration while still keeping you in control. The first pass produces evidence, not a surprise implementation. Once you trust the plan, you can ask for the smallest implementation slice.
Tutorial: repo audit workflow
Start with an audit because it is the safest way to learn the pattern. You get value even if you do not accept any code changes, and you can judge whether the subagent reports are useful.
- Open the repository in VS Code and start Claude Code from the integrated terminal.
- Paste the audit prompt with clear scope and a "do not edit files" instruction.
- Wait for the subagent findings and read the file references before trusting the summary.
- Ask Claude to turn the top two issues into a minimal implementation plan.
- Approve one change at a time rather than asking for the whole audit to be fixed at once.
- Run tests yourself or require Claude to run the exact test commands and paste the result summary.
The key retention trick inside your own workflow is to treat each result as a next step, not a finish line. If the audit finds routing and token-storage issues, ask Claude to implement one and link the other to a follow-up task. That keeps the diff small and the review real.
Tutorial: migration workflow
Dynamic workflows are especially useful for migrations because migrations touch many parts of a project. A dependency upgrade may involve package files, imports, generated code, tests, CI scripts, and documentation. One agent can do it, but parallel inspection is often faster and safer.
Goal:
Plan a migration from the old client package to the new client package.
Scope:
- Search the repository for imports and direct API usage.
- Inspect tests that cover those files.
- Identify compatibility risks.
- Do not edit files until the plan is approved.
Subagent split:
- Usage search and inventory.
- Type and interface compatibility.
- Test coverage review.
- Documentation and examples review.
Final output:
- Migration checklist.
- Files grouped by risk.
- Recommended order of changes.
- Tests to run after each step.Once the plan is ready, ask Claude Code to implement the lowest-risk slice first. For example, change one module and its tests before moving to the rest of the repository. A dynamic workflow is good at discovering the map; it should not force you to accept a huge diff.
Reviewing subagent output
Subagent output should be treated like an internal research memo. It may be useful, but it still needs review. Look for file references, evidence, and consistency between subagents. If one subagent says a function is unused and another says tests depend on it, pause and resolve the conflict before implementation.
- Check evidence: Good findings name files, functions, commands, or tests.
- Check overlap: Two subagents may inspect the same area and disagree.
- Check scope drift: Reject findings that require unrelated refactors.
- Check test reality: A confident plan without test commands is not enough.
- Check final diff size: The larger the change, the more staged the rollout should be.
A team workflow that keeps people in control
Dynamic workflows work best when the team treats Claude Code as a contributor to the engineering process, not as a secret replacement for it. Give one person ownership of the prompt, one person ownership of the review, and one person ownership of the release decision if the change is risky. That may sound formal, but it prevents a common problem: everybody is impressed by the agent output and nobody is clearly accountable for accepting the diff.
For small teams, the lightweight version is enough. The person who starts the workflow writes the task boundary and asks for a read-only plan first. A second person reviews the plan or the final diff if the task touches production behaviour. The final merge still follows your normal code review rules. That pattern keeps the speed benefit while preserving the discipline that makes software maintainable.
Where tool calling fits
Dynamic workflows become much stronger when the model can call tools and read results. A subagent that only guesses from static files is less useful than one that can search, run a focused test, inspect output, and adjust. If you are designing your own AI app, read my tool calling patterns guide before copying the idea into production.
The important principle is the same: tools need boundaries. Claude should know which commands are safe, which files are in scope, and which outputs are evidence. Good tool design makes agents reliable. Loose tool design makes them noisy.
Cost and speed considerations
Dynamic workflows can spend more tokens because several subagents may inspect overlapping context. That is not automatically bad if the workflow saves developer time, but it needs measurement. Track cost per successful task, not only total tokens. A workflow that costs more but saves two hours of review may still be a bargain. A workflow that produces a giant diff nobody trusts is expensive even if the token bill looks modest.
Use caching and model routing for repeated context. Do not send the same large repository explanation over and over if it can be cached. Use cheaper models for low-risk classification and reserve Opus 4.8 for the planning, review, and hard-code reasoning steps.
Common mistakes
- Starting too broad: "Improve this app" creates vague subagents and vague diffs.
- Skipping the read-only pass: Implementation before investigation makes review harder.
- Trusting a summary without evidence: Require file-level findings.
- Accepting one huge diff: Split work into reviewable slices.
- Forgetting existing tests: Dynamic workflows should strengthen verification, not bypass it.
How this connects to the Opus 4.8 API migration
Dynamic workflows are mostly a Claude Code surface, but the same habits apply when you migrate API apps to Opus 4.8. You still need scoped prompts, careful evaluation, cost measurement, and a rollback path. If your next job is to update application code from Opus 4.7 to Opus 4.8, continue with the API migration guide.
FAQs
What are Claude Code dynamic workflows? Dynamic workflows are a research-preview capability for Claude Code and supported Claude API or cloud surfaces where Claude can split complex work into parallel subagents, explore parts of a task separately, and bring the results back into one reviewable plan.
When should I use dynamic workflows? Use them for large repo audits, migrations, multi-module refactors, dependency upgrades, test expansion, and bug investigations that have independent branches of work.
Do dynamic workflows replace code review? No. They can speed up exploration and implementation, but the final code, tests, and release decision still need human review.
Where should I read next? Read the Opus 4.8 explainer for release context or the migration guide for API changes.
Related guides on this site
Keep the next click inside the same workflow so you can move from idea to implementation without context switching.
- Start with the Opus 4.8 explainer if you want pricing, model ID, and feature context.
- Continue with the migration guide if you are updating API code.
- Set up Claude Code in VS Code before trying advanced workflows.
- Learn tool calling patterns for safer agent design.
- Compare frontier model trade-offs before you standardise your coding stack.
- Return to the AI hub for the full AI development library.