Claude Code Subagents - Specialized AI Assistants

Subagents are specialized AI assistants that Claude Code can delegate tasks to. Each subagent has a specific purpose, uses its own context window, and can be configured with specific tools.

What Are Subagents?

Subagents enable delegated task execution by:

Creating isolated AI assistants with separate context windows
Providing customized system prompts for specialized expertise
Enforcing tool access control to limit capabilities
Preventing context pollution from complex tasks
Enabling parallel execution of multiple tasks

Subagents Architecture Overview

Subagents Architecture

The main Claude Code agent delegates tasks to specialized subagents (Architect, Engineer, Reviewer, Tester) which return aggregated results for the completed project.

Key Benefits

Benefit	Description
Context preservation	Separate context prevents pollution
Specialized expertise	Fine-tuned for specific domains
Reusability	Use across different projects
Flexible permissions	Different tool access levels
Scalability	Multiple agents work simultaneously

File Locations

Priority	Type	Location	Scope
1	CLI-defined	`--agents` flag	Session only
2	Project	`.claude/agents/`	Current project
3	User	`~/.claude/agents/`	All projects
4	Plugin	Plugin `agents/`	Via plugins

Configuration

File Format

      
        ---
name: your-sub-agent-name
description: When this subagent should be invoked
tools: tool1, tool2, tool3
model: sonnet
---

Your subagent's system prompt goes here.

Configuration Fields

Field	Required	Description
`name`	Yes	Unique identifier (lowercase, hyphens)
`description`	Yes	When to invoke this agent
`tools`	No	Comma-separated tool list
`disallowedTools`	No	Tools the agent must not use
`model`	No	`sonnet`, `opus`, `haiku`, or `inherit`
`permissionMode`	No	Permission mode for operations
`maxTurns`	No	Maximum agentic turns
`skills`	No	Skills to preload
`mcpServers`	No	MCP servers to make available
`memory`	No	Memory scope (`user`, `project`, `local`)
`background`	No	Run as background task
`effort`	No	Reasoning effort level
`isolation`	No	Git worktree isolation

Built-in Subagents

Claude Code comes with several built-in subagents:

Agent	Purpose
Explore	Codebase exploration and understanding
Plan	Planning and architecture
Code Reviewer	Code quality and security review
Test Engineer	Test generation and execution
Documentation	Documentation creation

Creating Custom Subagents

Code Reviewer Agent

      
    
      
        ---
name: code-reviewer
description: Expert code reviewer. Use proactively after code changes.
tools: Read, Grep, Glob
model: sonnet
---

You are a senior code reviewer with 15 years of experience.

## Focus Areas

1. **Security**
   - SQL injection
   - XSS vulnerabilities
   - Authentication issues
   - Data validation

2. **Quality**
   - Code complexity
   - Naming conventions
   - Error handling
   - Test coverage

3. **Performance**
   - Algorithm efficiency
   - Memory usage
   - Database queries

## Output Format

Provide structured feedback:
- Critical issues (must fix)
- Suggestions (should fix)
- Observations (nice to have)

      
      
        

Test Engineer Agent

      
    
      
        ---
name: test-engineer
description: Generate and run tests. Use when creating tests.
tools: Read, Write, Bash(npm test)
model: sonnet
---

You are a test engineer specializing in comprehensive test coverage.

## Test Types

1. **Unit Tests**
   - Test individual functions
   - Mock external dependencies
   - Cover edge cases

2. **Integration Tests**
   - Test component interactions
   - Use real dependencies where appropriate
   - Test API endpoints

3. **E2E Tests**
   - Test critical user flows
   - Use realistic test data
   - Verify complete workflows

## Process

1. Analyze code structure
2. Identify test cases
3. Generate tests
4. Run tests
5. Fix failures

      
      
        

Documentation Agent

      
    
      
        ---
name: doc-writer
description: Create comprehensive documentation. Use when documenting code.
tools: Read, Write
model: sonnet
---

You are a technical writer specializing in developer documentation.

## Documentation Types

1. **API Documentation**
   - Endpoints
   - Parameters
   - Responses
   - Examples

2. **Code Documentation**
   - Function descriptions
   - Parameter types
   - Return values
   - Usage examples

3. **Architecture Docs**
   - System overview
   - Component relationships
   - Data flow
   - Deployment

      
      
        

Tool Configuration Options

Option 1: Inherit All Tools

      
        ---
name: full-access-agent
description: Agent with all available tools
---

Option 2: Specify Individual Tools

      
        ---
name: limited-agent
description: Agent with specific tools only
tools: Read, Grep, Glob, Bash
---

Option 3: Conditional Tool Access

      
        ---
name: conditional-agent
description: Agent with filtered tool access
tools: Read, Bash(npm:*), Bash(test:*)
---

Using Subagents

Via CLI

      
        claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer",
    "prompt": "You are a senior code reviewer...",
    "tools": ["Read", "Grep", "Glob"],
    "model": "sonnet"
  }
}'

Via `/agents` Command

/agents

Opens an interactive menu to create, view, edit, and manage subagents.

Background Subagents

Run subagents as background tasks:

      
        ---
name: background-analysis
description: Analyze codebase in background
background: true
---

Perform comprehensive codebase analysis...

Worktree Isolation

Give subagents their own git worktree:

      
        ---
name: isolated-work
description: Work in isolated environment
isolation: worktree
---

Make changes in isolation...

Best Practices

Clear descriptions: Include when to use the agent
Limit tools: Only grant necessary tools
Focused purpose: One agent, one job
Test thoroughly: Verify agent behavior
Document well: Clear system prompts

Enjoyed this post? Never miss out on future posts by following us

Claude Code Subagents - Specialized AI Assistants