Claude Code Subagents: Parallelize Development with Custom AI Agents

You ask Claude Code to refactor a large codebase. An hour later, your main conversation is buried under thousands of lines of search results, logs, and file contents — most of which you'll never look at again. Context fills up. Performance degrades. Claude starts forgetting things.

That's the single-agent problem. And Claude Code's subagent system is the answer.

Subagents let Claude delegate focused tasks to isolated AI instances, each running in their own context window. The results come back as clean summaries. Your main conversation stays lean. And when tasks are independent, they can run in parallel — turning a 2-hour sequential grind into a 20-minute parallel sprint.

This guide covers everything: how Claude Code subagents work, the built-in agents you already have, how to write your own, and how to structure parallel workflows that actually ship faster.

What Are Claude Code Subagents (And How They Differ from Multi-Agent APIs)

Before we go further, let's nail the distinction. If you've read about Claude's orchestrator-subagent pattern via the API, that's a different layer. API multi-agent systems require you to write orchestration code — you manage spawning, context passing, and result aggregation yourself.

Claude Code subagents are built into the CLI. You define them as Markdown files with YAML frontmatter. Claude decides when to delegate to them automatically, based on the description you write. No orchestration code needed.

Here's what makes subagents powerful:

• Isolated context windows — Each subagent works in its own context. Heavy exploration, log tailing, or codebase-wide searches stay out of your main conversation.
• Tool restrictions — You can lock a subagent to read-only tools, preventing it from making changes when that's not what you want.
• Model routing — Route specific tasks to Claude Haiku for speed and cost savings, reserving Opus or Sonnet for complex reasoning.
• Reusable configs — Define a subagent once. Use it across all your projects forever.
• Persistent memory — Subagents can remember patterns they learn across sessions.

One important constraint: subagents cannot spawn other subagents. This prevents infinite nesting. If you need agents that communicate across separate sessions, look at Claude Code's Agent Teams feature instead.

The Built-In Subagents You Already Have

Claude Code ships with built-in subagents that activate automatically. You've probably seen them in action without realizing it.

Explore (Haiku — Read-Only)

The Explore agent handles codebase search and analysis. When Claude needs to understand a large project before writing code, it delegates that exploration to Explore rather than flooding your main context with file contents.

It uses Haiku — fast and cheap — and has access only to read-only tools. You can invoke it directly:

Use Explore to find all API endpoints in this codebase (very thorough)

Three thoroughness levels are supported: quick for targeted lookups, medium for balanced searches, and very thorough for comprehensive analysis.

Plan (Read-Only — Inherits Main Model)

When you're in plan mode (/plan) and Claude needs to understand your codebase before presenting an approach, it delegates that research to the Plan subagent. Same read-only restriction, but uses your current model.

General-Purpose (All Tools — Inherits Main Model)

For complex, multi-step tasks that require both reading and writing — general-purpose is the fallback. It gets all tools and handles anything that doesn't fit a specialized subagent.

To see every subagent available in your current environment:

bashclaude agents

How to Create Custom Subagents

Custom subagents are Markdown files with YAML frontmatter. Two locations matter:

The YAML Frontmatter Fields

Here's a complete custom subagent definition:

markdown---
name: api-reviewer
description: >
  Reviews API route handlers for security issues, missing validation,
  and inconsistent error handling. Use proactively after any changes
  to /api or /routes directories.
model: claude-sonnet-4-6
tools:
  - Read
  - Grep
  - Glob
  - Bash
permissionMode: acceptEdits
color: purple
memory: project
---

You are a senior API security reviewer. When analyzing route handlers:

1. Check for missing input validation on all request parameters
2. Verify authentication middleware is applied on protected routes
3. Look for SQL injection vectors or unsafe query construction
4. Flag any endpoints that return more data than the caller needs
5. Check error responses don't leak stack traces or internal paths

For each issue found, show: the file path, the problematic code, and a corrected version.

• name — The identifier used when invoking via /agents or CLI flags
• description — Critical. Claude reads this to decide when to delegate. Write it like a precise trigger condition, not a marketing tagline.
• model — claude-haiku-4-5, claude-sonnet-4-6, or claude-opus-4-6. Defaults to the main conversation's model.
• tools — Allowlist of tools. Omit to inherit all tools from the parent conversation.
• disallowedTools — Explicit blocklist, useful when you want "everything except write tools."
• permissionMode — acceptEdits (auto-approve edits), bypassPermissions (skip all prompts), or default (inherit from parent).
• memory — project saves memory to .claude/agent-memory/, user saves to ~/.claude/agent-memory/, none disables memory.
• color — Visual identifier in the Claude Code UI.
• maxTurns — Cap the number of turns the subagent can take.

The /agents Command

The fastest way to create subagents without writing YAML by hand:

/agents

This opens a tabbed UI. Switch to Library → Create new agent → Generate with Claude. Describe what you want in plain English, Claude generates the frontmatter and system prompt, then you select tools, model, and memory scope.

CLI-Defined Subagents (Ephemeral)

For one-off automation or testing without saving to disk:

bashclaude --agents '{
  "migration-tester": {
    "description": "Runs database migration tests and reports failures.",
    "prompt": "You are a database migration specialist. Run the migration test suite, analyze any failures, and report which migrations broke and why.",
    "tools": ["Bash", "Read"],
    "model": "sonnet"
  }
}'

These exist only for the current session — perfect for CI pipeline agent injections.

Running Parallel Subagent Workflows

Here's where the real velocity gains live. When you have independent tasks — tasks with no dependencies on each other — subagents can tackle them simultaneously.

How to Trigger Parallel Execution

The key is being explicit in your prompt. Claude won't automatically parallelize unless you tell it to:

Use 3 parallel subagents to simultaneously:
1. Analyze the authentication module for security vulnerabilities
2. Profile the database query layer for N+1 issues
3. Review the API rate limiting implementation for edge cases

Each agent should work independently and report its findings separately.

Compare that to the vague version: "Review our security." — Claude will tackle that sequentially, one area at a time.

Practical Parallel Workflow Patterns

Use 4 parallel agents to review the following independently:
- Agent 1: src/api/ — authentication and authorization
- Agent 2: src/db/ — query safety and indexing
- Agent 3: src/lib/ — utility functions and error handling
- Agent 4: src/components/ — React component performance patterns

Each agent should use the Explore subagent for discovery, then compile a findings list.

Advanced teams run 3-4 parallel Claude Code sessions on separate Git branches, each implementing the same feature with a different approach. You compare the implementations and cherry-pick the best. The mental model: instead of one engineer exploring one approach, you get a small team exploring in parallel.

bash# Terminal 1: Branch A — functional approach
git checkout -b feature/auth-functional
claude "Implement OAuth2 flow using functional composition patterns"

# Terminal 2: Branch B — class-based approach  
git checkout -b feature/auth-class
claude "Implement OAuth2 flow using a class-based service pattern"

For large research tasks — competitive analysis, codebase audits, documentation generation:

Split this task across 5 parallel subagents:
- Agent 1: Analyze all TypeScript types and interfaces — list any inconsistencies
- Agent 2: Map all API endpoints and their expected inputs/outputs
- Agent 3: Document all environment variables and their usage
- Agent 4: Identify all third-party dependencies and their versions
- Agent 5: Find all TODO/FIXME comments and categorize by severity

After all agents complete, synthesize a single technical debt report.

What to Watch Out For

Parallel subagents aren't free — there are real constraints:

• Subagents can't create nested subagents. If your subagent hits a task it wants to delegate further, it can't. Design subagents to be terminal executors, not orchestrators.
• Parallel writes cause conflicts. Never have multiple agents writing to the same files simultaneously. Separate their file access clearly.
• Rate limits compound. Heavy parallel use will hit Anthropic's API rate limits faster. Monitor your usage on the Claude platform dashboard.
• Context accumulation. Each subagent returns a summary, but those summaries still consume your main context. With 10 parallel agents all returning 500-word reports, your main conversation fills up fast.

Real-World Subagent Library: 5 You Should Build Today

1. Test Coverage Analyzer

markdown---
name: test-coverage
description: >
  Analyzes test coverage gaps. Use when asked to improve test coverage or
  before any major refactor.
model: claude-haiku-4-5
tools: [Read, Grep, Glob, Bash]
---
Analyze the test suite. For each source file, identify what's tested and what isn't. 
Prioritize gaps by risk: untested error paths > untested happy paths > untested edge cases.
Output a prioritized list of what to test next.

2. Dependency Auditor

markdown---
name: dep-auditor
description: >
  Audits package.json dependencies for outdated versions, security advisories,
  and unused packages. Use before releases or quarterly.
model: claude-sonnet-4-6
tools: [Read, Bash, Glob]
---
Run npm audit, check for outdated packages, and identify any packages imported in
package.json but not used in source files. Report: (1) critical vulnerabilities,
(2) major version updates available, (3) unused dependencies to remove.

3. Documentation Generator

markdown---
name: doc-writer
description: >
  Generates JSDoc/TSDoc documentation for undocumented functions and components.
  Use when asked to document a module or when documentation coverage is low.
model: claude-sonnet-4-6
tools: [Read, Glob, Grep, Edit]
permissionMode: acceptEdits
---
Find all exported functions, classes, and React components that lack documentation.
Add concise JSDoc/TSDoc comments: description, @param, @returns, and one @example.
Match the style of existing documented functions in the same file.

4. Migration Safety Checker

markdown---
name: migration-checker
description: >
  Checks database migrations for safety issues before they run in production.
  Use proactively whenever a new migration file is created.
model: claude-sonnet-4-6
tools: [Read, Glob, Bash]
---
Analyze each migration file for: destructive operations without backups, missing indexes
on large tables, operations that lock tables for too long, and missing down migrations.
Flag anything that could cause downtime or data loss.

5. PR Summarizer

markdown---
name: pr-summarizer
description: >
  Generates pull request descriptions from git diff. Use when asked to write a PR
  description or summarize recent changes.
model: claude-haiku-4-5
tools: [Bash, Read]
---
Run git diff main...HEAD and git log main...HEAD. From the diff, produce a PR description
with: a one-line summary, bullet-pointed changes grouped by area, testing notes, and
any breaking changes. Keep it under 400 words.

Team Workflows: Sharing Subagents via Git

The most underused feature of the project-scoped subagents (.claude/agents/) is that they live in your repo. Check them in, and every developer on your team gets them automatically.

repo/
  .claude/
    agents/
      api-reviewer.md
      test-coverage.md
      dep-auditor.md
      doc-writer.md
    CLAUDE.md

This is the equivalent of a shared .eslintrc or prettier.config.js — team-wide AI behavior, version-controlled and reviewable. New developers onboard with your team's specialized AI toolkit already configured.

For organization-wide standards, administrators can deploy subagents through Claude Code's managed settings, which takes highest priority over project and user definitions.

Key Takeaways

• Claude Code subagents run in isolated context windows — they handle noisy tasks without polluting your main conversation
• Built-in subagents (Explore, Plan, General-purpose) activate automatically; use /agents to see what's available
• Custom subagents are Markdown files in .claude/agents/ (project) or ~/.claude/agents/ (personal)
• Be explicit about parallelism — tell Claude to use N parallel subagents or it will work sequentially
• Route tasks to Haiku for cost efficiency; reserve Sonnet/Opus for complex reasoning
• Check .claude/agents/ into Git to share specialized AI workflows across your team
• Subagents cannot spawn subagents — design them as terminal executors, not orchestrators

Next Steps

Claude Code's subagent system is one of the topics covered in the Claude Certified Architect (CCA-F) exam — specifically around agentic architectures, context management, and multi-agent coordination patterns.

If you're studying for the CCA certification, our Claude Certified Architect exam guide covers the full exam structure. And if you want to test your knowledge on agentic systems specifically, our CCA practice test bank includes questions on subagent design, context management, and orchestration trade-offs.

The developers passing the CCA exam in 2026 are the ones who understand not just how to prompt Claude, but how to architect systems around it — and subagents are a core part of that architecture.