Skip to main content

Subagents

Subagents are specialized AI agents that handle specific tasks within a larger workflow. This guide explains what they are, how to use them effectively, and where the technology is heading.

What Are Subagents?​

Subagents are modular, specialized agents designed for specific tasks. Instead of one monolithic agent trying to do everything, subagents divide work into focused roles.

┌─────────────────────────────────────────┐
│              Main Agent                 │
│  (orchestrates and delegates)           │
└────────┬──────────┬──────────┬──────────┘
         │          │          │
         ▼          ▼          ▼
    ┌────────┐ ┌────────┐ ┌────────┐
    │Explore │ │  Plan  │ │ Verify │
    │Agent   │ │ Agent  │ │ Agent  │
    └────────┘ └────────┘ └────────┘

Why Use Subagents?​

Specialization​

Each subagent focuses on one thing and does it well:

  • Constrained scope - Fewer distractions, fewer mistakes
  • Optimized instructions - Tuned for the specific task
  • Appropriate tools - Only the tools needed for that task

Isolated Context​

Subagents run in their own context windows:

  • No pollution - Research doesn't clutter your main conversation
  • Fresh starts - Each task begins without accumulated confusion
  • Parallel work - Multiple subagents can work simultaneously

Reliability​

Smaller, focused agents are more reliable:

  • Easier to debug - When something fails, you know where
  • Predictable behavior - Constrained agents are more consistent
  • Faster iteration - Fix one subagent without affecting others

Using Subagents Intentionally​

You can explicitly ask your coding agent to use subagents for specific tasks. This is a powerful technique for managing context and parallelizing work.

Preserving Main Context​

Use subagents for work that shouldn't pollute your main conversation:

  • "Use a subagent to explore the codebase for authentication patterns"
  • "Spawn a subagent to research how the API handles rate limiting"
  • "Have a subagent analyze the test coverage while we continue"

The research happens in isolated context, and you get a summary back without all the intermediate exploration cluttering your conversation.

Specifying Models​

With some coding agents (like Claude Code), you can specify which model a subagent should use:

  • "Use a Haiku subagent to scan all files for TODOs" - Cheaper/faster for simple tasks
  • "Spawn an Opus subagent for this complex refactoring" - More capable for hard problems

This lets you optimize for cost and latency while keeping powerful models available for complex work.

Parallel Exploration​

When you're unsure about an approach, spawn parallel subagents:

  • "Have two subagents explore different solutions to this problem"
  • "Spawn subagents to investigate the frontend and backend simultaneously"

Example Prompts​

"Use a subagent to search for all usages of this deprecated function"

"Spawn a parallel agent to run the tests while we continue implementing"

"Have a Haiku subagent summarize the authentication module—I just need an overview"

"Use subagents to check the frontend, backend, and database layers in parallel"

When to Use Subagents​

Complex Multi-Phase Work​

Break large tasks into phases, each handled by a subagent:

1. Explore agent → Understand current implementation
2. Plan agent → Design the approach
3. Main agent → Implement changes
4. Verify agent → Run tests
5. Cleanup agent → Remove dead code

Parallel Investigations​

When you need to investigate multiple areas:

  • Check logs in different environments simultaneously
  • Search for patterns across different parts of the codebase
  • Verify changes across multiple services

Context-Heavy Research​

When research would consume too much of your main context:

  • Reading through large codebases
  • Analyzing many similar files
  • Gathering information from multiple sources

Verification Before Shipping​

Never ship without verification:

  • Run tests automatically
  • Check for type errors
  • Validate against requirements
  • Catch issues before they reach production

The Future: Agent Swarms​

Coding agents are evolving from single assistants to coordinated teams. Here's where the technology is heading.

Agent Teams (Claude Code)​

Claude Code is developing "agent teams" functionality that transforms subagents into full multi-agent orchestration:

  • Team lead - Plans, delegates, and coordinates
  • Specialist agents - Work in parallel on different concerns
  • Shared task board - Agents can see and update shared work
  • Direct communication - Agents can message each other

Why This Matters​

  • Parallel execution - Multiple files and features developed simultaneously
  • Specialized focus - Each agent masters its domain
  • Scalable complexity - Tackle larger projects than one agent can handle
  • Human-like collaboration - More like working with a team than a single assistant

Current State​

As of early 2026, agent teams are an emerging capability. Check your coding agent's documentation for the latest features:

Subagent Best Practices​

Keep Them Focused​

Each subagent should have one clear purpose:

  • Good: "Run E2E tests and report failures"
  • Bad: "Test the app, fix any bugs, update docs, and deploy"

Constrain Their Tools​

Give subagents only the tools they need:

Subagent TypeRecommended Tools
ExploreRead, Search, Glob (no Edit, Write)
PlanRead, Search (no Edit, Write)
VerifyRead, Run commands (no Edit)
ImplementAll tools

Define Clear Outputs​

Specify what the subagent should return:

  • Test results summary
  • Pass/fail status
  • List of findings with locations
  • Recommendations for next steps

Handle Failures Gracefully​

Subagents should report failures clearly:

  • What failed
  • Why it failed (if determinable)
  • What to do next

Learn More​