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.

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