Originally published at heycc.cn. This is a mirrored copy — the canonical version is kept up to date at the source.
Claude Code Subagents and Workflows: A Hands-On Guide to Delegation and Parallel Fan-Out
The single hardest resource to manage in an agentic coding session is not the model's intelligence — it is the context window. Run the test suite once and a few hundred lines of pytest output land in your conversation. Grep a large codebase and you get file paths you will never look at again. Fetch a doc page and a wall of markdown sits between you and your next decision. None of it is wrong; all of it crowds out the reasoning you actually care about.
Subagents and dynamic workflows are Claude Code's two answers to that problem. A subagent does a side task in its own context window and returns only the summary. A dynamic workflow takes the same idea and scales it to tens or hundreds of agents coordinated by a script. What each one is, when to reach for it, how to define your own subagent in YAML, and how to fan work out at scale all follow below, drawn from the official docs as of the date noted at the end. If you are wiring external tools into the same setup, the companion MCP server setup guide covers the connection layer that subagents can then borrow.
What a subagent actually is
A subagent is a specialized assistant that runs in its own context window with a custom system prompt, specific tool access, and independent permissions. When Claude hits a task that matches a subagent's description, it can delegate to that subagent, which works independently and reports back only its result. The verbose intermediate output — the logs, the search hits, the file dumps — stays in the subagent's context and never touches your main conversation.
Claude Code ships three built-in subagents that it delegates to automatically when appropriate:
- Explore — a fast, read-only agent for searching and analyzing codebases. It runs on Haiku for low latency, and Write and Edit are denied. Claude uses it for file discovery and code search without making changes. When it invokes Explore, it specifies a thoroughness level: quick, medium, or very thorough.
- Plan — a read-only research agent used during plan mode to gather context before presenting a plan. It inherits the main conversation's model.
- General-purpose — a capable agent for complex, multi-step tasks that need both exploration and modification. It inherits the main model and has access to all tools.
One important detail: Explore and Plan deliberately skip your CLAUDE.md files and the parent session's git status to stay fast and cheap. Every other built-in and custom subagent loads both. If a rule must reach an Explore run — "ignore the vendor/ directory," say — restate it in the prompt you give Claude when you delegate.
Subagent vs. inline: when to delegate
The official guidance is narrative, but the decision comes down to a handful of signals. Stay in the main conversation when the work is tightly coupled to what you are already doing; hand it to a subagent when it is self-contained and noisy. The table below turns that judgment into signals you can read off mid-session.
"Absorbs the noise" is not just a turn of phrase — it shows up as a real number in the /workflows token total mentioned below. A few actual runs from this site's own operations, read directly off the token usage the harness reports per agent: an Explore-type agent tracing every script in a mid-size repo that reads a specific pair of data files (grep across ~10 files, read the relevant lines in each, summarize) used 46,638 tokens and 15 tool calls in 53 seconds. Four separate research agents doing web-search-and-verify tasks (5 topics each, WebSearch plus WebFetch to confirm each claim against a primary source) used between 48,000 and 60,000 tokens and 16-46 tool calls apiece. In every case, only a compact summary — a few hundred words — came back to the main conversation; the tens of thousands of tokens spent reading, searching, and cross-checking never touched the primary context window at all. That's the mechanism "absorbs the noise" is describing.
The signals that say "delegate this"
| Signal | Stay inline (main loop) | Delegate to a subagent | Why |
|---|---|---|---|
| Output volume | Output is short and you'll reference it | Output is verbose (logs, search hits, doc dumps) you won't reuse | The subagent absorbs the noise and returns only the summary |
| Context sharing | Planning, editing, and testing share heavy context | The task is self-contained and returns a clean result | A subagent starts fresh and can't see your conversation history |
| Tool / permission scope | You need your full toolset | You want to restrict tools or permissions (e.g. read-only) | Scoping tools is the point — a reviewer that can't write can't break things |
| Iteration | The task needs frequent back-and-forth | The task runs once and reports back | Subagents are awkward to steer turn by turn |
| Latency | A quick, targeted change | You can afford a cold start | Subagents start fresh and may need time to gather context |
| Parallelizable parts | The work is one linear thread | Several independent investigations can run at once | Independent subagents run simultaneously, then Claude synthesizes |
The last row is worth dwelling on. For independent investigations you can spawn multiple subagents to work simultaneously — researching the authentication, database, and API modules in parallel, for example — and Claude then synthesizes the findings. This works best when the research paths do not depend on each other. If they do, you are back to a single thread and a subagent buys you nothing.
A related tip: for a quick question about something already in your conversation, neither a subagent nor a workflow is right. The docs point you at /btw instead — it sees your full context, has no tool access, and the answer is discarded rather than added to history.
Defining your own subagent
When you keep spawning the same kind of worker with the same instructions, define a custom subagent. A subagent is a Markdown file with YAML frontmatter: the frontmatter is configuration, and the body becomes the system prompt. Only name and description are required.
---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer ensuring high standards of code quality and security.
When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately
Provide feedback organized by priority: critical issues, warnings, suggestions.
Include specific examples of how to fix each issue.
Beyond the two required fields, the optional ones do the heavy lifting:
-
tools— an allowlist of tools the subagent may use. Omit it and the subagent inherits everything the main conversation has. -
disallowedTools— a denylist removed from the inherited or specified set. If both are set,disallowedToolsis applied first. -
model—sonnet,opus,haiku,fable, a full model ID such asclaude-opus-4-8, orinherit. The default isinherit. Routing a noisy task to Haiku is a cheap, fast win. -
permissionMode—default,acceptEdits,auto,dontAsk,bypassPermissions, orplan. -
isolation— set toworktreeto run the subagent in a temporary git worktree, giving it an isolated copy of the repo so parallel sessions never edit the same files. The worktree is automatically cleaned up if the subagent makes no changes. -
memory—user,project, orlocal, giving the subagent a persistent directory that survives across conversations so it can accumulate patterns and recurring issues.
The frontmatter also accepts skills, mcpServers, and hooks, among others, but the six above are the ones you reach for first.
Where subagents live, and who wins
Scope is determined entirely by file location, and when two subagents share a name the higher-priority location wins. The precedence, highest to lowest:
| Priority | Location | Scope |
|---|---|---|
| 1 (highest) | Managed settings | Organization-wide |
| 2 |
--agents CLI flag |
Current session only |
| 3 | .claude/agents/ |
Current project |
| 4 | ~/.claude/agents/ |
All your projects |
| 5 (lowest) | A plugin's agents/ directory |
Where the plugin is enabled |
Project subagents in .claude/agents/ are the sweet spot for team work: check them into version control so everyone gets — and can improve — the same reviewer, debugger, or migration helper.
The recommended way to create and manage all of this is the /agents command. It opens a tabbed interface: a Running tab listing live and recently finished subagents, and a Library tab where you view, create (with guided setup or Claude generation), edit, and delete subagents. Changes made through this interface take effect immediately without restarting. (If you edit a subagent file on disk directly, you do need to restart the session to load it.)
Invoking a subagent on purpose
Automatic delegation is the default, but you have three ways to force the issue, escalating in strength:
- Natural language — just name the subagent in your prompt ("use the test-runner subagent to fix failing tests"). Claude decides whether to delegate.
-
@-mention — type
@, pick the subagent from the typeahead, and that specific subagent is guaranteed to run for that one task. Your full message still goes to Claude, which writes the task prompt; the @-mention only controls which subagent runs. -
Session-wide — pass
claude --agent <name>(or set theagentsetting). The whole session adopts that subagent's system prompt, tool restrictions, and model. The subagent's prompt replaces the default Claude Code system prompt entirely.
When you build your own, four practices from the docs separate a useful subagent from a flaky one: design each to excel at one focused task; write a detailed description, since Claude uses it to decide when to delegate; limit tool access to only what the job needs; and check project subagents into version control to share them with your team.
Four ways to parallelize, and who coordinates
Subagents are one of four ways Claude Code parallelizes work. They differ by who holds the plan:
| Approach | What it is | Who coordinates | Status |
|---|---|---|---|
| Subagents | Delegated workers inside one session that return a summary | Claude, turn by turn | Generally available |
| Agent view | Background sessions you dispatch and monitor from one screen (claude agents) |
You — check back later | Research preview |
| Agent teams | Coordinated sessions with a shared task list and inter-agent messaging | A lead agent | Experimental, disabled by default |
| Dynamic workflows | A script that runs many subagents and cross-checks their results | The script | Generally available |
Worktrees underpin the file-isolation story for all of these: each session gets a separate git checkout so parallel work never collides, and a subagent opts in with isolation: worktree.
Dynamic workflows: fan-out at scale
A dynamic workflow is the heavy artillery. It is a script — JavaScript, written by Claude for the task you describe — that a runtime executes in the background while your session stays responsive. Where subagents and skills keep the plan in Claude's context window turn by turn, a workflow moves the loop, the branching, and the intermediate results into code. Claude's context then holds only the final answer.
The scale is the headline: a single workflow run fans work out across tens to hundreds of parallel subagents in a single session, checking results before they reach you. Moving the plan into code also lets a workflow apply a repeatable quality pattern — having independent agents adversarially review each other's findings before reporting, or drafting a plan from several angles and weighing them — so you get a more trustworthy result than a single pass.
You trigger one by including the keyword ultracode in your prompt, or just asking in plain language to "use a workflow." The bundled /deep-research command is the quickest way to see it work: it fans web searches across several angles, cross-checks the sources, and returns a cited report.
Watch a run with the /workflows command, which lists running and completed runs and opens a progress view showing each phase with its agent count, token total, and elapsed time. You can drill into any phase to see what each agent found.
One caution worth stating plainly: a workflow spawns many agents, so a single run can use meaningfully more tokens than working the same task through conversation. Running many subagents or sessions at once multiplies token usage. The docs' advice is sound — gauge spend by running a workflow on a small slice first (one directory, a narrow question) before turning it loose on the whole repo.
Choosing among the three tiers
Put the three tiers together and the decision tree is short. Stay in the main conversation for coupled, iterative, latency-sensitive work. Delegate to a subagent — built-in or custom — when a side task is verbose, self-contained, or needs tool restrictions, and especially when several independent investigations can run at once. Reach for a dynamic workflow only when the job outgrows a handful of subagents or genuinely benefits from agents cross-checking each other: a codebase-wide audit, a large migration, or research that needs sources weighed against one another.
If you are choosing tools before you build any of this, the broader landscape is covered in Claude Code vs. Cursor in 2026.
How the four sources map to the claims
Each block above traces to one of the four sources listed below (all read 2026-06-28). The built-in subagents and their models, the YAML frontmatter fields, the scope-precedence table, and the /agents interface come from the Claude Code subagents reference. The four parallelization approaches — subagents, agent view, agent teams, dynamic workflows — come from the "Run agents in parallel" page. The dynamic-workflows mechanics, the /workflows view, and the "tens to hundreds of parallel subagents" scale come from the workflows docs, with the May 28, 2026 general-availability date confirmed by the Anthropic announcement. Field names and defaults are the kind of detail that moves between releases, so the live pages win over this article if they disagree.
Top comments (0)