Using Subagents

Create specialized AI assistants for focused, complex tasks using Claude Code's subagent system. This guide shows you how to create and use subagents effectively for real development work.

Official Documentation: See Claude Code Sub-agents for comprehensive technical details.

How Subagents Work

Subagents are separate AI assistants with their own context windows, specialized for specific tasks. They're ideal for:

• Focused expertise - Security reviews, performance analysis, testing
• Context isolation - Complex tasks that don't pollute your main conversation
• Parallel work - Multiple independent analyses simultaneously
• Specialized tools - Custom tool access for specific domains

Creating Subagents

Use the /agents command to create subagents with specific capabilities:

Basic Subagent Creation

# Create a security-focused subagent
/agents create security-expert "Security specialist for code audits and vulnerability analysis"

# Create a performance analyst
/agents create performance-analyzer "Performance expert for optimization and bottleneck analysis"

# Create a testing specialist  
/agents create test-engineer "Testing expert for comprehensive test strategy and implementation"

Subagents with Specific Tools

# Database specialist with relevant tools
/agents create database-expert "Database optimization and schema design specialist" --tools Read,Write,Bash,Grep

# DevOps engineer with infrastructure tools
/agents create devops-engineer "Container orchestration and deployment specialist" --tools Bash,Read,Write,Glob

Using Subagents

Once created, you can invoke subagents either automatically or explicitly:

Explicit Invocation

Direct a specific subagent to handle a task:

# Use security expert for code review
"Use the security-expert subagent to review this authentication system for common vulnerabilities and provide specific recommendations with code examples."

# Use performance analyzer for bottleneck investigation
"Use the performance-analyzer subagent to profile this API endpoint and identify optimization opportunities."

Automatic Routing

Claude Code can automatically route tasks to appropriate subagents:

# Claude automatically uses security-expert if available
"Review this payment processing code for security vulnerabilities"

# Claude automatically uses performance-analyzer if available
"This database query is slow, help me optimize it"

Practical Subagent Patterns

Domain Specialists

Create experts for specific technical domains:

# Frontend specialist
/agents create frontend-expert "React/TypeScript specialist for component optimization and user experience"

# Backend architect  
/agents create backend-architect "API design and microservices architecture specialist"

# Database expert
/agents create database-specialist "SQL optimization and database design expert"

Usage example:

"Use the frontend-expert subagent to refactor these React components for better performance and maintainability."

Analysis Teams

Create multiple specialists for comprehensive analysis:

# Security analyst
/agents create security-analyst "Security vulnerability assessment and penetration testing"

# Performance auditor
/agents create performance-auditor "Application performance profiling and optimization"

# UX reviewer
/agents create ux-reviewer "User experience analysis and improvement recommendations"

Usage example:

"I need a comprehensive review of our checkout system. Use the security-analyst to check for vulnerabilities, the performance-auditor to identify bottlenecks, and the ux-reviewer to find user experience issues."

Sequential Workflow

Chain subagents for complex, multi-stage work:

# Create workflow specialists
/agents create system-analyst "Legacy system analysis and documentation specialist"
/agents create solution-architect "Modern architecture design based on analysis"
/agents create implementation-engineer "Code implementation following architectural specifications"

Usage example:

# Stage 1: Analysis
"Use the system-analyst subagent to analyze this legacy payment system and document all dependencies, security issues, and performance bottlenecks."

# Stage 2: Design (after analysis complete)
"Use the solution-architect subagent to design a modern payment architecture that addresses the identified issues while maintaining backward compatibility."

# Stage 3: Implementation (after design complete)
"Use the implementation-engineer subagent to implement the payment service refactoring following the architecture design."

Managing Subagents

List Available Subagents

# View all created subagents
/agents list

Remove Subagents

# Remove a specific subagent
/agents remove security-expert

# Remove all subagents
/agents clear

Real-World Examples

API Security Review

Create specialized subagents for comprehensive security analysis:

# Create security team
/agents create auth-specialist "Authentication and JWT security expert"
/agents create data-protection "Data validation and protection specialist"  
/agents create access-control "Authorization and permission system expert"

Then use them:

"I need a security review of our user API. Use the auth-specialist to review JWT implementation, the data-protection subagent to examine input validation, and the access-control subagent to analyze our permission system."

Database Migration

Sequential workflow for complex database changes:

# Create migration team
/agents create migration-analyst "Database schema analysis and migration planning"
/agents create migration-architect "Migration strategy and rollback procedure design"  
/agents create migration-engineer "Migration script implementation and testing"

Workflow:

# Phase 1
"Use the migration-analyst to analyze our current PostgreSQL schema for performance bottlenecks and dependencies."

# Phase 2 (after analysis)
"Use the migration-architect to design a zero-downtime migration strategy based on the analysis."

# Phase 3 (after design)
"Use the migration-engineer to implement production-ready migration scripts with rollback support."

Performance Optimization

Parallel analysis for system optimization:

# Create performance team
/agents create frontend-optimizer "Frontend performance and bundle optimization specialist"
/agents create backend-profiler "API and database performance analysis expert"
/agents create infrastructure-monitor "Server and deployment optimization specialist"

Usage:

"Our application is slow. Use the frontend-optimizer to analyze client-side performance, the backend-profiler to examine API bottlenecks, and the infrastructure-monitor to review server resource usage."

Best Practices

Effective Subagent Design

Specific Expertise:

# Good: Focused domain
/agents create react-performance "React component rendering optimization specialist"

# Avoid: Too broad
/agents create general-helper "Generic coding assistant"

Clear Responsibilities:

# Good: Specific role
/agents create api-security "REST API security vulnerability analysis and remediation"

# Avoid: Vague purpose  
/agents create code-reviewer "Looks at code and suggests improvements"

Coordination Strategies

Independent Tasks: Use multiple subagents for parallel analysis

"Use security-expert for vulnerability assessment and performance-analyzer for optimization review simultaneously."

Dependent Tasks: Use sequential handoff with clear context

"Use the analyst subagent first to document the system, then use the architect subagent to design improvements based on that analysis."

Complex Coordination: Break into phases with explicit handoffs

# Phase 1 complete message
"Analysis phase complete. Key findings: Database bottleneck in user queries, missing indexes on user_id and order_date. Ready for architecture design phase."

Common Mistakes to Avoid

• Over-specialization: Don't create subagents for simple, one-off tasks
• Context confusion: Each subagent has its own context - provide necessary background
• Tool mismatches: Ensure subagents have appropriate tools for their tasks
• Poor handoffs: Provide clear summaries when chaining subagents

Quick Reference

Creation Commands

/agents create <name> "<description>"                    # Basic subagent
/agents create <name> "<description>" --tools Tool1,Tool2  # With specific tools
/agents list                                             # Show all subagents
/agents remove <name>                                    # Remove subagent
/agents clear                                           # Remove all subagents

Usage Patterns

Pattern	Command	Use Case
Explicit	Use the <name> subagent to...	Direct task assignment
Automatic	Natural language request	Let Claude route to appropriate subagent
Parallel	Multiple explicit requests	Independent simultaneous work
Sequential	Chain explicit requests	Dependent workflow stages

Subagent Types

Type	Example	Best For
Specialist	security-expert, performance-analyzer	Domain expertise
Workflow	analyst, architect, engineer	Multi-stage processes
Parallel	frontend, backend, database	Independent analysis

Next Steps

Learn about Output Styles to configure how subagents present their findings, and explore Context Management for managing information flow between subagents.