Claude Code Subagents Tutorial: Delegate, Parallelize, and Ship 3x Faster

What Are Claude Code Subagents?

A subagent is a separate Claude instance that runs in its own context window. You give it a task, it does the work -- reading files, searching code, running commands -- and returns a summary. The verbose intermediate output never enters your main conversation. According to Anthropic's documentation, subagents help you preserve context, enforce tool constraints, and specialize behavior with focused system prompts.

Think of subagents as specialized coworkers. You would not ask your security reviewer to also handle deployment. Each subagent gets a specific role, specific tools, and a specific model -- then delivers results without cluttering your workspace.

3 Built-in Subagents You Already Have

Claude Code ships with three built-in subagent types that it dispatches automatically. Understanding these helps you decide when to create custom ones. According to the Claude Code documentation (April 2026), each built-in subagent inherits the parent conversation's permissions with additional tool restrictions.

Create Your First Custom Subagent (Step-by-Step)

Custom subagents are Markdown files with YAML frontmatter. You can create them with the interactive /agents command or by writing the file directly. Here is the manual approach -- it is faster once you know the format.

Step 1: Choose Your Scope

Step 2: Write the Subagent File

Create .claude/agents/code-reviewer.md in your project root:

---
name: code-reviewer
description: Reviews code for quality, security, and best practices. Use after completing a feature or before creating a PR.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. When invoked:

1. Read the changed files
2. Check for security issues (injection, auth gaps, data exposure)
3. Check for code quality (naming, structure, duplication)
4. Check for performance issues (N+1 queries, unnecessary re-renders)
5. Return a structured report with severity levels

Step 3: Test It

Restart your Claude Code session (subagents are loaded at session start), then ask Claude to use it:

You can also use the /agents command to see all loaded subagents and verify yours appears in the Library tab.

Every Frontmatter Field Explained

The YAML frontmatter controls everything about your subagent's behavior. Only name and description are required. Here is the complete field reference as of Claude Code v2.1 (April 2026).

Model Routing: Match the Right Model to Each Subagent

Model selection is the single biggest cost lever for subagents. Anthropic offers three model tiers as of April 2026. Routing a file-search subagent to Haiku instead of Opus saves 60x per invocation with zero quality loss for that task type. Here is how to think about model assignment.

The model resolution order matters: the CLAUDE_CODE_SUBAGENT_MODEL environment variable overrides everything, then the per-invocation model parameter, then the frontmatter model field, and finally the main conversation's model as fallback.

Run Subagents in Parallel: The Speed Multiplier

Claude Code can dispatch up to 7 subagents simultaneously. Each runs in its own context window with no shared state. The key requirement: tasks must be genuinely independent. If one subagent needs the output of another, run them sequentially instead.

When to Parallelize

Prompt Pattern for Parallel Dispatch

Be explicit about what you want parallelized. Claude dispatches subagents in parallel when you describe independent tasks in a single message:

I need 4 things done in parallel:

1. Use the code-reviewer agent to review src/auth/
2. Use the test-writer agent to generate tests for src/api/users.ts
3. Search the codebase for any hardcoded API keys or secrets
4. Check all TODO comments and list them by priority

These are independent -- run them simultaneously.

Worktree Isolation: Safe Parallel Writes

What happens when multiple subagents need to write code simultaneously? Without isolation, they would conflict on the same files. The isolation: worktree frontmatter field solves this by giving each subagent its own git worktree -- a separate working copy of your repository.

---
name: feature-builder
description: Implements features in an isolated worktree
tools: Read, Write, Edit, Bash, Grep, Glob
model: sonnet
isolation: worktree
---

Implement the requested feature in this isolated worktree.
Run tests before reporting results. If tests pass,
report the worktree path and branch name so changes
can be merged.

• ●Auto-cleanup. If the subagent makes no changes, the worktree is automatically removed.
• ●Branch returned. If changes are made, the worktree path and branch name are returned so you can review and merge.
• ●No conflicts. Each subagent works on its own copy. Three feature-builders can run simultaneously without stepping on each other.

Tool Permissions: Principle of Least Privilege

Every subagent should have access to only the tools it needs. According to security best practices, restricting tools reduces the blast radius if a subagent misinterprets a task. Claude Code provides two mechanisms: an allowlist (tools) and a denylist (disallowedTools).

If both fields are set, disallowedTools is applied first, then tools is resolved against the remaining pool. A tool listed in both is removed. For most subagents, pick one mechanism -- the allowlist for strict restriction, the denylist for minor adjustments.

7 Production-Ready Subagent Templates

Copy these into your .claude/agents/ or ~/.claude/agents/ directory. Each template has been tested in production workflows and includes the recommended model and tool configuration.

---
name: security-reviewer
description: Reviews code for security vulnerabilities. Use before merging PRs or after implementing auth/payment features.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a security-focused code reviewer. Analyze for:
- SQL injection, XSS, and command injection risks
- Authentication and authorization gaps
- Sensitive data in logs, errors, or responses
- Hardcoded secrets or API keys
- OWASP Top 10 vulnerabilities

Return findings grouped by severity: Critical, High, Medium, Low.

---
name: codebase-explorer
description: Fast codebase exploration and file discovery. Use when researching unfamiliar code areas.
tools: Read, Grep, Glob
model: haiku
---

You are a fast codebase researcher. When given a question:
1. Search for relevant files and patterns
2. Read key files to understand structure
3. Return a concise summary (under 300 words)
Include file paths and line numbers for all references.

---
name: test-writer
description: Generates comprehensive tests for source files. Use after implementing new features.
tools: Read, Write, Edit, Bash, Grep, Glob
model: sonnet
isolation: worktree
---

You are a test engineer. For the given source file:
1. Read the implementation and identify all code paths
2. Write tests covering happy path, edge cases, and error handling
3. Follow existing test patterns in the project
4. Run the tests to verify they pass
Use the project's existing test framework and conventions.

---
name: dependency-auditor
description: Audits project dependencies for security, licensing, and size issues.
tools: Read, Bash, Grep, Glob
model: haiku
---

Audit the project's dependencies:
1. Check for known vulnerabilities (npm audit / pip audit)
2. Flag unused dependencies
3. Identify oversized packages that could be replaced
4. Check license compatibility
Return a table of findings sorted by severity.

---
name: doc-generator
description: Generates documentation for modules, APIs, or functions.
tools: Read, Write, Edit, Grep, Glob
model: sonnet
isolation: worktree
---

Generate documentation for the specified code:
1. Read the source and understand the public API
2. Write clear, concise documentation with examples
3. Include parameter types, return values, and edge cases
4. Follow the project's existing documentation style
Save docs alongside the source files.

---
name: log-analyzer
description: Analyzes log files for errors, patterns, and anomalies. Use when debugging production issues.
tools: Read, Bash, Grep
model: haiku
---

Analyze the provided log file or output:
1. Identify all errors and warnings
2. Group by error type and frequency
3. Find patterns (time clustering, user correlation)
4. Suggest root cause for the top 3 issues
Return findings in a structured report under 500 words.

---
name: architecture-reviewer
description: Reviews architectural decisions, module boundaries, and system design. Use before major refactors.
tools: Read, Grep, Glob
model: opus
---

You are a principal engineer reviewing architecture. Analyze:
1. Module boundaries and coupling between components
2. Data flow and state management patterns
3. Scalability bottlenecks
4. Consistency of patterns across the codebase
Focus on structural issues, not style. Report trade-offs,
not just problems. Suggest concrete alternatives.

Scope MCP Servers to Specific Subagents

MCP (Model Context Protocol) servers let Claude Code connect to external tools like Playwright, Slack, or databases. The mcpServers frontmatter field lets you scope these connections to individual subagents. Inline servers connect when the subagent starts and disconnect when it finishes.

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  - github
---

Use Playwright tools to navigate pages, take screenshots,
and verify UI behavior. Report pass/fail for each test
case with screenshots of failures.

• ●Inline definitions (like the Playwright config above) are scoped to this subagent only. The MCP server does not run in other subagents or the main conversation.
• ●String references (like "github" above) reuse an already-configured MCP server from your session. No additional server instance is created.

Persistent Memory: Let Subagents Learn Across Sessions

By default, subagents start fresh every time. The memory frontmatter field gives a subagent a persistent memory directory where it can accumulate insights across conversations. This is useful for code reviewers that learn your project's patterns or explorers that build a codebase index over time.

5 Common Subagent Mistakes (and How to Fix Them)

After building dozens of subagent configurations, these are the patterns that trip people up most often. Each mistake wastes tokens or produces poor results.

Subagents vs. Agent Teams: Which to Use

Claude Code offers two delegation mechanisms: subagents (within a single session) and agent teams (across separate sessions). Choosing the right one depends on your task structure and coordination needs.

Rule of thumb: if the task takes under 5 minutes and needs no cross-worker communication, use a subagent. If workers need to coordinate or the task requires sustained parallel effort, use agent teams.

Frequently Asked Questions

Related Guides