Dynamic Workflows, Sub-agents, or Agent Teams: Which to Use

For sequential reasoning where each step relies on the previous discovery, stick to dynamic workflows. When you need to process large, independent datasets in parallel, sub-agents are the industry standard for 90% of your production needs.

Only escalate to agent teams when your workers require lateral communication to solve entangled problems. Most tasks don't require this level of overhead. While dynamic workflows provide the simplest failure model, agent teams introduce a "war room" environment where specialized peers coordinate via shared state, which drives up your token cost and setup time.

What are dynamic workflows, sub-agents, and agent teams?

These three patterns define how you structure agent communication and parallelism:

• Dynamic workflows (single agent): A single execution flow where Claude Code assesses the task and adapts its plan mid-stream without spawning external workers.
• Sub-agents (parent-child hierarchy): A parent agent delegates tasks to isolated child workers using the Task tool. Communication is strictly vertical.
• Agent teams (peer-to-peer network): Specialized agents coordinate laterally via a shared task store and direct messaging.

Dynamic workflows: when should a script orchestrate for you?

In a dynamic workflow, you let a single Claude Code agent manage its own execution plan. It reorders steps or backtracks based on real-time tool outputs. There is no fixed script; the sequence is determined by the agent's internal reasoning.

Use cases:

• Codebase audits: Scanning directory structures to identify high-risk modules before investigating.
• Production debugging: Investigating bugs where the path depends entirely on what previous tool calls reveal.
• Open-ended research: Scenarios where you cannot predict the depth of investigation upfront.

This pattern offers the simplest failure model. You have one context window and one execution flow, making traces straightforward. The limitation is speed: because there is no parallelism, processing large datasets is much slower than multi-agent setups.

Sub-agents: when to spawn workers turn by turn?

Treat sub-agents like freelancers: you give them a brief, they work in isolation, and they hand back a scoped result. The parent agent acts as a project manager, using the Task tool to spawn temporary workers for discrete chunks of work. Each sub-agent operates in a fresh context window, returning only a summary to the parent. This keeps the parent's context window clean and prevents "context ballooning."

Sub-agents have been stable since July 2025. You define them using YAML frontmatter in Markdown files located in .claude/agents/.

name: codebase-scout
description: Explore and map codebase architecture
memory: .claude/memory/codebase-scout
tools:
  - Read
  - Grep
  - Glob
 
Update your agent memory as you discover codepaths and architectural patterns.
Write concise notes about what you found and where.

Agent teams: when do peers coordinate via a shared task list?

Agent teams follow the "war room" model. This is a heavy-duty architecture where persistent, specialized agents communicate laterally. This pattern is experimental (released February 2026) and requires the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS feature flag.

Implementation details for the war room:

• Environment: Teammates spawn in separate tmux panes or iTerm2 splits.
• Shared state: Coordination relies on a structured store—typically JSON, a database, or git-based task locking—where workers track task states (pending, in_progress, completed).
• Peer messaging: Teammates send messages directly to each other without routing through a lead agent.

The "ceiling" for this pattern was demonstrated when 16 parallel Opus instances built a Rust-based C compiler across 2,000 sessions, consuming 2 billion tokens at a cost of roughly $20,000. Use this only for entangled, cross-layer features where a change in the backend API must immediately inform the frontend worker.

Compared: token cost, scale, and repeatability

In a sub-agent setup, your orchestrator's context grows as summaries return. If 10 sub-agents each produce 2,000 tokens of output, your orchestrator's context reaches 20,000+ tokens rapidly. For complex projects, this can balloon to 50,000 tokens per call. Agent teams avoid this specific accumulation but burn tokens faster by running multiple full-session plans in parallel.

Decision framework: which pattern for your task?

1. Is the task parallelizable? If work is sequential or requires full historical reasoning at every step, use a dynamic workflow.
2. Do parallel workers need to talk to each other laterally? If workers can finish jobs independently without knowing what others found, use sub-agents.
3. Identify "relay fatigue": If you are manually passing information between isolated sub-agent sessions (the "telephone game"), you have hit the coordination wall. This is your signal to escalate to agent teams.

Apply the 90/10 rule: start with sub-agents by default. They are cheaper and easier to audit.

Should you combine patterns?

Complex architectures often use a hybrid approach. You use a high-level orchestrator (sub-agent pattern) to handle high-level project planning and sequential decisions. This orchestrator then delegates an entire "execution phase" to a specialized agent team for parallel, entangled implementation. This keeps your top-level context manageable while allowing lateral coordination where it is needed most.

FAQ

What is a Claude Code agent team? A team is a group of specialized agents coordinating laterally via shared task lists and peer messaging. They run in separate terminal panes (tmux/iTerm2) and are designed for entangled tasks where workers must adjust their approach based on peer discoveries.

What is the difference between a sub-agent and an agent team? Sub-agents are "freelancers" that report vertically to a parent and work in isolation. Agent teams are a "war room" where peers collaborate laterally. Sub-agents are stable (July 2025), while agent teams are experimental (February 2026) and require feature flags.

Which pattern uses fewer tokens? Sub-agents are more efficient because they only return summaries to the parent context. Agent teams consume roughly 7x more tokens than standard sessions because each teammate maintains a full, independent context and parallel plan-mode execution.

Can you combine agent teams and sub-agents? Yes. You can use an orchestrator (sub-agent pattern) to manage the project lifecycle and delegate specific, complex execution phases to an agent team. This hybrid model balances high-level control with lateral execution efficiency.

When should I not use agent teams? Avoid them for sequential tasks, simple parallel batch jobs, or one-off tasks. The coordination overhead and 7x token premium are only justified when tasks are so "entangled" that workers cannot proceed without real-time peer communication.

How does shared state work? Shared state uses a structured data store—often a JSON file or git-based locking—that all agents can access. Workers read their assigned tasks and relevant prior outputs from the store and write their results back to update the team's progress.

References

• Sub-agent vs Agent Team in Claude Code: Pick the Right Pattern in 60 Seconds — Medium
• Claude Subagents vs Agent Teams: What's the Difference? — YouTube
• Claude Code Agent Teams vs Sub-Agents: Which Pattern Should You Use? — MindStudio
• Claude Code Dynamic Workflows vs Agent Teams vs Sub-Agents: Which Should You Use? — MindStudio
• Akshay Pachaar on Sub-agents vs Agent Teams — X
• Akshay Pachaar on Agent Orchestration Patterns — X
• Orchestrate Subagents at Scale with Dynamic Workflows — Claude Code Docs