Subagent-Driven Development

A Claude Code development skill for leveraging subagents (Task tool) to parallelize research, implementation, and testing across multiple autonomous agents for faster, more thorough software development.

When to Use

Choose Subagent-Driven Development when:

• Working on complex tasks that benefit from parallel research and implementation
• Needing to explore a codebase thoroughly before making changes
• Running multiple independent operations concurrently (tests, builds, searches)
• Performing comprehensive code analysis across many files simultaneously

Consider alternatives when:

• Simple, focused changes — handle directly without subagent overhead
• Sequential tasks with dependencies — run in order in the main context
• Reading a few specific files — use Read/Grep tools directly

Quick Start

Copy
## Using Subagents Effectively

### Research Phase
Launch an Explore subagent to understand the codebase:
- Find all files matching a pattern
- Search for function definitions and usages
- Map out the architecture and dependencies

### Implementation Phase
Use the main context for writing code after research is complete.
Do NOT delegate code writing to subagents unless doing isolated,
independent implementations that don't need shared context.

### Testing Phase
Launch subagents to run tests in parallel:
- Unit tests in one agent
- Integration tests in another
- Lint/typecheck in a third

Copy
// Conceptual model of subagent orchestration
interface SubagentTask {
  type: 'Explore' | 'general-purpose' | 'Plan';
  description: string;
  prompt: string;
  dependencies?: string[];
  runInBackground?: boolean;
}

class SubagentOrchestrator {
  planResearchPhase(task: string): SubagentTask[] {
    return [
      {
        type: 'Explore',
        description: 'Find relevant files',
        prompt: `Search the codebase for files related to: ${task}.
                 Look for components, services, types, and tests.
                 Report file paths, key exports, and dependencies.`
      },
      {
        type: 'Explore',
        description: 'Analyze existing patterns',
        prompt: `Examine the existing code patterns for: ${task}.
                 Focus on naming conventions, file structure,
                 error handling patterns, and testing approaches.`
      }
    ];
  }

  planValidationPhase(): SubagentTask[] {
    return [
      {
        type: 'general-purpose',
        description: 'Run tests',
        prompt: 'Run the test suite and report results.',
        runInBackground: true
      },
      {
        type: 'general-purpose',
        description: 'Run type check',
        prompt: 'Run TypeScript type checking and report errors.',
        runInBackground: true
      }
    ];
  }
}

Core Concepts

When to Use Each Agent Type

Agent Type	Best For	Context Access	Typical Duration
Explore	File search, code analysis	Read-only, thorough	Quick to medium
general-purpose	Complex multi-step tasks	Full tool access	Medium to long
Plan	Architecture design	Research + planning	Medium

Parallel vs Sequential Execution

Copy
## Parallel (Independent Tasks)
Launch multiple agents simultaneously when tasks don't depend on each other:
- Agent 1: Search for all API routes
- Agent 2: Search for all database models
- Agent 3: Search for all test files
→ All three run concurrently, results combined after

## Sequential (Dependent Tasks)
Run agents in order when results inform next steps:
1. Agent 1: Find the authentication module → returns file paths
2. Agent 2: Analyze the auth module found by Agent 1 → returns patterns
3. Main context: Implement changes based on Agent 2's analysis

## Background (Non-blocking)
Run agents in background when you don't need results immediately:
- Background agent: Run full test suite (takes 5 minutes)
- Meanwhile: Continue implementing next feature
- Check test results when the background agent completes

Effective Prompting for Subagents

Copy
## Good Subagent Prompt
"Search the codebase for all files that handle user authentication.
Look in: src/auth/, src/middleware/, src/services/
Search for: JWT, session, login, authenticate, authorize
Report: file paths, key function names, and how they connect.
Be thorough - check multiple directories and naming conventions."

## Bad Subagent Prompt
"Find auth stuff."
→ Too vague, agent won't know what to search for or where

## Good Background Task Prompt
"Run `npm test` in the project root and report:
1. Total tests passed/failed
2. Any failing test names and error messages
3. Code coverage summary if available"

## Bad Background Task Prompt
"Run tests."
→ Missing directory context, unclear what to report

Configuration

Option	Description	Default
max_concurrent_agents	Maximum parallel subagents	3
default_agent_type	Default agent type for tasks	"Explore"
background_enabled	Allow background agent execution	true
timeout_per_agent	Maximum agent execution time	120s
share_context	Share conversation context with agents	true
model	Model for subagents: haiku, sonnet, opus	"sonnet"
isolation	Run in worktree for file safety	false
auto_resume	Resume interrupted agents	true

Best Practices

1. Use Explore agents for codebase research before making changes — Explore agents are optimized for searching, reading, and analyzing code without modifying anything, and they handle multiple search rounds automatically
2. Launch independent research agents in parallel to maximize throughput — if you need to understand three different parts of the codebase, launch three Explore agents simultaneously rather than searching sequentially
3. Write detailed, specific prompts for subagents that include what to search for, where to look, and what to report — vague prompts waste agent turns on unfocused exploration
4. Use background agents for long-running operations like test suites, builds, and deployments so you can continue working while waiting for results
5. Keep implementation in the main context rather than delegating to subagents because the main context has the full conversation history, user preferences, and accumulated understanding that subagents lack

Common Issues

Subagent results not matching expectations: The agent may not understand the codebase context that the main conversation has accumulated. Include relevant context in the subagent prompt — mention specific file paths, conventions, and what you have already discovered.

Too many concurrent agents overwhelming the system: Running many agents simultaneously can hit rate limits or slow down responses. Limit to 2-3 concurrent agents, use background execution for non-urgent tasks, and batch related searches into single agents rather than creating one per query.

Agent performing redundant work: Multiple agents searching for similar things waste resources. Before launching agents, check if you already have the information from earlier in the conversation, and coordinate agent scopes so they cover different areas without overlap.