Claude Code Subagents: Specialized AI Workers for Complex Tasks

A subagent is a child Claude session that the main agent can launch via the Agent tool. The child gets a fresh context window, a defined tool set, a system prompt, and a single task. When it finishes, it returns a summary to the parent. The conversation between them is invisible to you — only the final report shows up in your transcript.

This is not just a delegation pattern. Subagents solve two real problems: context pollution (long searches blow up the parent’s history) and specialization (different tasks want different system prompts and tool allowlists).

Built-in Subagents

Out of the box you get several:

• general-purpose — Multi-step research and execution. The default when no specialized agent fits.
• Explore — Read-only fast search. Designed for “find me the file that defines X” or “where is Y referenced.” Will not edit. Optimized for breadth, not depth.
• Plan — Software architect. Produces an implementation plan, identifies critical files, and considers tradeoffs. Will not write code.
• statusline-setup — Configures the Claude Code status line.
• claude-code-guide — Answers questions about Claude Code itself, the SDK, and the Claude API.

When the Parent Should Delegate

The rule of thumb: delegate when the work is independent, expensive in tokens, and only the conclusion matters. Bad delegation: “Edit this one file” — round trip overhead beats the work. Good delegation: “Audit the codebase for unused dependencies” — pages of output collapse into a one-line answer.

Other signals:

• The task spans many files and you do not need to see the search trail.
• You want a second opinion that is not anchored on the parent’s analysis.
• You want parallelism — fire three subagents at once for independent investigations.

Custom Subagents

Define your own in .claude/agents/<name>.md (project) or ~/.claude/agents/<name>.md (user):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

---
name: db-migration-reviewer
description: Reviews SQL migrations for safety on large tables. Use when migration files change.
tools: Read, Grep, Glob, Bash
model: opus
---

You are a database migration safety reviewer. For any migration:

1. Identify the operation (ADD COLUMN, DROP, ALTER, INDEX...).
2. Estimate the row count of affected tables (use `\dt+` or schema files).
3. Flag locking behavior, NULL constraints on populated tables,
   non-concurrent indexes, foreign-key cascades.
4. Output a verdict: SAFE / RISKY / UNSAFE with one line per concern.

Do not modify files. Read-only review.

Now the parent can invoke it via the Agent tool with subagent_type: "db-migration-reviewer". You can also describe trigger conditions so the parent knows when to delegate without you asking.

Briefing a Subagent

Subagents start cold. They have not seen your conversation. The prompt you pass them is the entire context they get. The Claude Code docs are blunt about this: terse command-style prompts produce shallow work. Treat the prompt like an email to a smart colleague who just walked into the room — explain the goal, what you have already ruled out, and what form of answer you want.

Bad:  "Find the bug"
Good: "Login fails intermittently in staging. I've ruled out the
       JWT validator (tested in isolation) and the DB pool (logs
       show no exhaustion). Suspect the session middleware. Look
       at src/middleware/session.ts and adjacent code, find the
       race or state bug, and report under 200 words."

Foreground vs Background

Subagents run in the foreground by default — the parent waits for the result. For genuinely parallel work, the parent can launch them in the background and continue with other tasks; a notification fires on completion. Use background mode only when you have real independent work to do, not as a habit.

Patterns That Work

• Explore for navigation, Plan for design, general for execution. Three tools, three jobs.
• One subagent per investigation thread. Fan out, gather summaries, synthesize in the parent.
• Custom agent per recurring review. A security-reviewer, accessibility-reviewer, or performance-reviewer that you invoke before merging is cheap to write and pays back forever.
• Trust but verify. A subagent’s summary describes what it intended. If it claims to have written a file, check the diff before believing the report.

Subagents are the difference between a single agent that gets confused on big tasks and a fleet of small agents that each do one thing well. Once you have your first custom one, you will write five more inside a week.