Featured Agents Task Tool Subagents Architecture

Claude Code Agents: Complete Guide to Specialized Subagents

Master all Claude Code agent types. From Explore to security-auditor, learn when and how to use each specialized agent for maximum efficiency.

January 10, 2026 • 20 min read • By ClaudeWorld

Claude Code’s agent system is one of its most powerful features. Through the Task tool, you can spawn specialized subagents that work in parallel, each optimized for specific tasks. This guide covers every agent type, when to use them, and how to combine them effectively.

Understanding Claude Code Agents

What is an Agent?

According to the official documentation, an agent in Claude Code is a specialized subprocess that:

  • Runs autonomously with its own context
  • Has access to specific tools and capabilities
  • Can work in parallel with other agents
  • Returns results to the main conversation

The Task Tool

The Task tool is how you spawn agents:

Task({
  subagent_type: "Explore",           // Required: Agent type
  model: "haiku",                      // Optional: haiku, sonnet, opus
  prompt: "Your task description",     // Required: What to do
  run_in_background: false             // Optional: Async execution
})

Agent Type Overview

Agent TypePurposeDefault ModelBest For
ExploreFast codebase navigationHaiku 4.5File search, patterns
general-purposeComplex multi-step tasksSonnet 4.5Implementation, analysis
code-reviewerCode quality analysisSonnet 4.5PR reviews, patterns
security-auditorVulnerability detectionSonnet 4.5Auth, payment code
test-runnerTest executionHaiku 4.5Running, analyzing tests
debuggerRoot cause analysisSonnet 4.5Bug investigation
refactor-assistantCode improvementSonnet 4.5Cleanup, restructuring
doc-writerDocumentationHaiku/SonnetREADME, API docs

The Explore Agent

Overview

The Explore agent (introduced in v2.1.0) is Claude Code’s fastest agent for codebase navigation. Powered by Haiku 4.5, it combines multiple search tools into a single efficient operation.

Syntax

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: `
    Explore [target] (thoroughness: [level]).
    [Specific goals]
  `
})

Thoroughness Levels

LevelTimeUse Case
quick10-30sFind specific file or function
medium30-60sMap module structure and patterns
very thorough60-120sComplete flow analysis

Examples

Quick search:

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Explore authentication (thoroughness: quick). Find the login handler."
})

Medium exploration:

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: `
    Explore payment module (thoroughness: medium).
    Find all Stripe integration points and webhook handlers.
  `
})

Thorough analysis:

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: `
    Explore user authentication (thoroughness: very thorough).
    Map complete auth flow from login to session management.
    Include JWT handling, refresh tokens, and logout.
  `
})

Why Explore is Faster

Old approach (5 manual steps):

Agent 1: Glob find *auth*.ts       → 15s
Agent 2: Grep search "JWT"         → 15s
Agent 3: Read auth/index.ts        → 10s
Agent 4: Grep find middleware      → 15s
Agent 5: Read test files           → 10s
Total: 65 seconds

New approach (1 Explore agent):

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Explore auth (thoroughness: medium). Map JWT, middleware, tests."
})
// Total: 30-45 seconds

The general-purpose Agent

Overview

The general-purpose agent handles complex, multi-step tasks that require deeper reasoning. Uses Sonnet 4.5 by default for balanced performance.

Syntax

Task({
  subagent_type: "general-purpose",
  model: "sonnet",  // or "opus" for critical tasks
  prompt: "Your complex task description"
})

Examples

Implementation:

Task({
  subagent_type: "general-purpose",
  model: "sonnet",
  prompt: `
    Implement user profile editing feature.
    - Add API endpoint for profile updates
    - Create form component with validation
    - Include image upload support
    - Follow existing patterns in src/api/
  `
})

Analysis:

Task({
  subagent_type: "general-purpose",
  model: "sonnet",
  prompt: `
    Analyze the current state management architecture.
    - Identify patterns and anti-patterns
    - Assess scalability
    - Recommend improvements
  `
})

Refactoring:

Task({
  subagent_type: "general-purpose",
  model: "sonnet",
  prompt: `
    Refactor the order processing module.
    - Extract shared logic to utilities
    - Improve error handling
    - Maintain backward compatibility
  `
})

The code-reviewer Agent

Overview

The code-reviewer agent specializes in code quality analysis, pattern detection, and best practice enforcement.

Syntax

Task({
  subagent_type: "code-reviewer",
  model: "sonnet",
  prompt: "Review [target] for [aspects]"
})

Examples

PR Review:

Task({
  subagent_type: "code-reviewer",
  model: "sonnet",
  prompt: `
    Review changes in the authentication module.
    Check for:
    - Code quality and patterns
    - Error handling
    - Test coverage
    - Documentation

    Provide findings with severity levels.
  `
})

Pattern Check:

Task({
  subagent_type: "code-reviewer",
  model: "sonnet",
  prompt: `
    Review src/components/ for React best practices.
    Check:
    - Proper hook usage
    - Component structure
    - Prop validation
    - Performance optimizations
  `
})

The security-auditor Agent

Overview

The security-auditor agent is specialized for vulnerability detection and security best practices. Essential for authentication, payment, and data handling code.

Syntax

Task({
  subagent_type: "security-auditor",
  model: "sonnet",  // or "opus" for critical code
  prompt: "Audit [target] for security vulnerabilities"
})

Examples

Authentication Audit:

Task({
  subagent_type: "security-auditor",
  model: "sonnet",
  prompt: `
    Audit the authentication module.
    Check for OWASP Top 10:
    - Injection vulnerabilities
    - Broken authentication
    - Sensitive data exposure
    - Broken access control

    Report findings with severity.
  `
})

Payment Security:

Task({
  subagent_type: "security-auditor",
  model: "opus",  // Critical code deserves best model
  prompt: `
    Comprehensive security audit of payment processing.
    Check:
    - PCI DSS compliance
    - Data encryption
    - Token handling
    - Webhook security
    - Error message safety
  `
})

When to Use security-auditor

ScenarioPriority
Auth/login changesHigh
Payment codeCritical
User data handlingHigh
API endpointsMedium
File uploadsHigh
External integrationsMedium

The test-runner Agent

Overview

The test-runner agent handles test execution, coverage analysis, and test result interpretation.

Syntax

Task({
  subagent_type: "test-runner",
  model: "haiku",
  prompt: "Run tests for [target] and analyze results"
})

Examples

Run Tests:

Task({
  subagent_type: "test-runner",
  model: "haiku",
  prompt: `
    Run all tests related to user authentication.
    Report:
    - Pass/fail status
    - Coverage percentage
    - Failed test details
  `
})

Coverage Analysis:

Task({
  subagent_type: "test-runner",
  model: "haiku",
  prompt: `
    Analyze test coverage for the checkout module.
    Identify:
    - Uncovered code paths
    - Edge cases missing tests
    - Integration test gaps
  `
})

The debugger Agent

Overview

The debugger agent specializes in root cause analysis and systematic bug investigation.

Syntax

Task({
  subagent_type: "debugger",
  model: "sonnet",
  prompt: "Investigate [error/issue] and find root cause"
})

Examples

Error Investigation:

Task({
  subagent_type: "debugger",
  model: "sonnet",
  prompt: `
    Investigate: TypeError: Cannot read 'id' of undefined
    at CheckoutForm.handleSubmit (checkout.tsx:45)

    Context: Error occurs when submitting with empty cart.

    Find root cause and suggest fix.
  `
})

Performance Issue:

Task({
  subagent_type: "debugger",
  model: "sonnet",
  prompt: `
    Debug slow dashboard load (8s, should be <2s).
    Investigate:
    - Data fetching patterns
    - Render cycles
    - Database queries
    - Network waterfall
  `
})

The refactor-assistant Agent

Overview

The refactor-assistant agent helps with code restructuring, cleanup, and improvement without changing functionality.

Syntax

Task({
  subagent_type: "refactor-assistant",
  model: "sonnet",
  prompt: "Refactor [target] to improve [aspect]"
})

Examples

Code Cleanup:

Task({
  subagent_type: "refactor-assistant",
  model: "sonnet",
  prompt: `
    Refactor utils/helpers.ts:
    - Split into focused modules
    - Remove dead code
    - Improve naming
    - Add TypeScript types
  `
})

Pattern Extraction:

Task({
  subagent_type: "refactor-assistant",
  model: "sonnet",
  prompt: `
    Extract common patterns from API handlers.
    Create:
    - Shared error handling middleware
    - Response helpers
    - Validation utilities
  `
})

The doc-writer Agent

Overview

The doc-writer agent specializes in creating and updating documentation.

Syntax

Task({
  subagent_type: "doc-writer",
  model: "sonnet",  // or "haiku" for simple docs
  prompt: "Document [target]"
})

Examples

API Documentation:

Task({
  subagent_type: "doc-writer",
  model: "sonnet",
  prompt: `
    Document the user API endpoints.
    Include:
    - Endpoint descriptions
    - Request/response formats
    - Authentication requirements
    - Error codes
    - Examples
  `
})

README Update:

Task({
  subagent_type: "doc-writer",
  model: "haiku",
  prompt: `
    Update README.md with:
    - New authentication flow
    - Environment variables
    - Setup instructions
  `
})

Parallel Agent Patterns

Pattern 1: Analysis Swarm

Launch multiple Explore agents for comprehensive analysis:

// 5 parallel Explore agents
Task({ subagent_type: "Explore", model: "haiku",
  prompt: "Map auth file structure (thoroughness: quick)" })
Task({ subagent_type: "Explore", model: "haiku",
  prompt: "Find JWT patterns (thoroughness: quick)" })
Task({ subagent_type: "Explore", model: "haiku",
  prompt: "Analyze middleware (thoroughness: medium)" })
Task({ subagent_type: "Explore", model: "haiku",
  prompt: "Check auth tests (thoroughness: quick)" })
Task({ subagent_type: "Explore", model: "haiku",
  prompt: "Review recent changes (thoroughness: quick)" })

Pattern 2: Implementation with Review

Build and verify simultaneously:

// Phase 1: Implementation
Task({
  subagent_type: "general-purpose",
  model: "sonnet",
  prompt: "Implement user profile feature"
})

// Phase 2: Parallel review (after Phase 1)
Task({ subagent_type: "code-reviewer", model: "sonnet",
  prompt: "Review code quality" })
Task({ subagent_type: "security-auditor", model: "sonnet",
  prompt: "Security review" })
Task({ subagent_type: "test-runner", model: "haiku",
  prompt: "Run and analyze tests" })

Pattern 3: Multi-File Refactoring

Divide work across parallel agents:

// Each agent handles one file
Task({ subagent_type: "general-purpose", model: "sonnet",
  prompt: "Refactor payment/checkout.ts to new pattern" })
Task({ subagent_type: "general-purpose", model: "sonnet",
  prompt: "Refactor payment/subscription.ts to new pattern" })
Task({ subagent_type: "general-purpose", model: "sonnet",
  prompt: "Refactor payment/refund.ts to new pattern" })
Task({ subagent_type: "general-purpose", model: "sonnet",
  prompt: "Update payment/types.ts for new pattern" })
Task({ subagent_type: "test-runner", model: "haiku",
  prompt: "Update payment tests for new pattern" })

Pattern 4: Bug Investigation

Parallel hypothesis testing:

// Investigate multiple theories simultaneously
Task({ subagent_type: "Explore", model: "haiku",
  prompt: "Search for session handling changes (thoroughness: quick)" })
Task({ subagent_type: "Explore", model: "haiku",
  prompt: "Check for race conditions (thoroughness: medium)" })
Task({ subagent_type: "Explore", model: "haiku",
  prompt: "Review error logs (thoroughness: quick)" })
Task({ subagent_type: "Explore", model: "haiku",
  prompt: "Find timeout configurations (thoroughness: quick)" })
Task({ subagent_type: "debugger", model: "sonnet",
  prompt: "Analyze most likely root cause from exploration" })

Model Selection Guide

Task TypeModelCostSpeed
Quick searchHaiku 4.5$⚡⚡⚡
Pattern matchingHaiku 4.5$⚡⚡⚡
Test runningHaiku 4.5$⚡⚡⚡
Simple docsHaiku 4.5$⚡⚡⚡
Code reviewSonnet 4.5$$⚡⚡
ImplementationSonnet 4.5$$⚡⚡
DebuggingSonnet 4.5$$⚡⚡
Security auditSonnet/Opus$$-$$$⚡-⚡⚡
ArchitectureOpus 4.5$$$⚡

Cost/Speed Trade-offs:

  • Haiku 4.5: 2x faster, 1/3 cost vs Sonnet
  • Sonnet 4.5: Best coding performance
  • Opus 4.5: Highest intelligence, default Thinking Mode

Background Agents

For long-running tasks, use run_in_background:

Task({
  subagent_type: "security-auditor",
  model: "opus",
  prompt: "Comprehensive security audit of entire codebase",
  run_in_background: true
})

Check on background tasks:

TaskOutput({ task_id: "...", block: false })

Best Practices

1. Choose the Right Agent

File search → Explore (haiku)
Implementation → general-purpose (sonnet)
Code quality → code-reviewer (sonnet)
Security → security-auditor (sonnet/opus)
Testing → test-runner (haiku)
Bugs → debugger (sonnet)
Cleanup → refactor-assistant (sonnet)
Docs → doc-writer (haiku/sonnet)

2. Keep Prompts Focused

Too broad:

"Analyze everything about the codebase"

Focused:

"Explore authentication module (thoroughness: medium). Find JWT handling and session management."

3. Provide Context

Task({
  subagent_type: "general-purpose",
  model: "sonnet",
  prompt: `
    Context: Migrating from REST to GraphQL.
    Pattern: Use new ApiClient from src/lib/api.ts

    Task: Refactor user service to use GraphQL.
  `
})

4. Use Parallel When Possible

Independent tasks should run simultaneously:

// These are independent - run in parallel
Task({ ..., prompt: "Analyze file A" })
Task({ ..., prompt: "Analyze file B" })
Task({ ..., prompt: "Analyze file C" })

5. Chain Dependent Tasks

Sequential tasks should be phased:

Phase 1: Explore (gather context)
Phase 2: Implement (with context from Phase 1)
Phase 3: Review (verify Phase 2)

Getting Started

Today:

  1. Try one Explore agent with thoroughness: medium
  2. Use code-reviewer on recent changes
  3. Run test-runner after your next implementation

This week:

  1. Implement Analysis Swarm pattern
  2. Use security-auditor for sensitive code
  3. Try parallel implementation with review

This month:

  1. Develop agent combinations for your workflow
  2. Optimize model selection for cost/performance
  3. Create templates for common patterns

Claude Code agents transform how you work—from sequential prompting to parallel orchestration. Master them to unlock 5-10x efficiency gains.

Sources: Claude Code Documentation, Claude Code GitHub, CHANGELOG