APREX · EST. 2026
You have one Claude instance. It's supposed to understand your code, check security, write tests, update documentation, and review pull requests — all at once. That's not a smart AI colleague. That's one overworked person with too many hats and not enough coffee.
Claude Code subagents are the answer to that problem.
What exactly is a subagent?
A subagent is not a separate program or a distinct subscription tier. It's a Claude instance with a specific role, defined in a simple Markdown file with YAML frontmatter. The files live in the .claude/agents/ folder in your project, and Claude Code loads them automatically.
According to Anthropic's official documentation (docs.anthropic.com), each subagent has its own context window. That means your code reviewer doesn't need to know anything about the design exploration you did yesterday — less noise, more precise analysis.
> HIGHLIGHT
> Context separation isn't just a technical detail. It's the reason a dedicated security agent actually finds vulnerabilities that a general assistant misses — it's not lost in the forest of unrelated information.
The built-in subagents
Claude Code ships with three built-in subagents you can use without any configuration:
| Subagent | Model | Access | Use case |
|---|---|---|---|
| Explore | Claude Haiku | Read-only | Fast codebase search and navigation |
| Plan | Claude (full) | Read + analysis | Research and planning |
| General-purpose | Claude (full) | Full tool access | Complex multi-step tasks |
Explore uses Haiku for speed — the right model for fast lookups. Plan is your research agent. General-purpose is the wildcard with full tool access.
How to define your own subagent
A custom subagent is no more complex than this:
`markdown
name: security-checker
description: Analyzes code for security vulnerabilities
tools: [read, search]
model: claude-opus-4
You are a security auditor. You look for SQL injection,
unauthenticated endpoints, and hardcoded secrets.
Report findings with severity and line numbers.
`
Your documentation agent only needs Read and Edit on Markdown files. Your deploy agent needs shell access, but absolutely not access to secrets. Permission control at this level isn't paranoia — it's common sense.
According to Nimbalyst (nimbalyst.com), best practice is to keep subagents "boring and specific": code-reviewer, test-runner, frontend-qa, docs-maintainer, security-checker, migration-planner. Not vague "senior engineer" personas that do everything and nothing.
> PULLQUOTE
> "Boring and specific subagents beat creative and vague ones every time. An agent that knows exactly what to do, does it better."
Agent Teams: The next level
Subagents follow a parent-child hierarchy: one main session calls on its specialists. Agent Teams are something else entirely.
Launched in research preview in February 2026 (version 2.1.32, Opus 4.6+), Agent Teams let multiple independent Claude instances work in parallel and send messages to each other via a mailbox system. Peer-to-peer, not hierarchy.
> KEYFIGURE
> - 9,000+ Claude Code plugins available as of February 2026
> - 7x more tokens used in subagent-heavy workflows vs. single-thread session
> - V2.1.32 — the version that introduced Agent Teams (2026-02-05)
Practical example: one agent writes frontend code, another writes backend tests, a third checks the API contract — all simultaneously, with messages going back and forth. According to Sitepoint (sitepoint.com), this is still experimental and stability is not guaranteed.
Claude Code Review: Proof in practice
The most concrete evidence that the multi-agent approach actually works came on March 9, 2026: Anthropic rolled out Claude Code Review, a multi-agent PR analysis system with five dedicated agents:
- Correctness Agent — logical errors and bugs
- Security Agent — vulnerabilities and exposed secrets
- Performance Agent — bottlenecks and inefficient code
- Style & Consistency Agent — code style and conventions
- Test Coverage Agent — missing tests and edge cases
The result, according to Lushbinary (lushbinary.com): Anthropic's internal code review coverage jumped from 16 percent to 54 percent. That's not a marginal improvement. That's a transformation.
Hooks: Automation with a safety valve
Hooks are event-driven automation that runs around agent actions. Five types:
- PreToolUse — runs before a tool is used (can block the action)
- PostToolUse — runs after a tool has been used
- Notification — alerts on important events
- UserPromptSubmit — runs when you submit a prompt
- Stop — runs when an agent finishes
A PreToolUse hook can block a force-push to main. A PostToolUse hook can auto-format files after editing. According to Anthropic's hooks documentation (code.claude.com), this is the safety valve that prevents agents from making irreversible mistakes.
> FACT BOX: How Skills activate automatically
> Skills are reusable instruction packages stored as SKILL.md files with YAML frontmatter. Claude Code reads the context and activates the right skill automatically — without you needing to ask explicitly. With more than 9,000 plugins available in the Claude Code ecosystem, there's a good chance someone has already built what you need.
Agent View and terminal survival
Agent View is the control center for your background sessions. The claude agents command shows all active and pending agents. Most importantly: sessions survive if you close the terminal. Your agents keep working while you take lunch.
Pitfalls to avoid
Subagents are not free — cognitively or economically. CloudZero, the first cost platform with Anthropic Usage and Cost Admin API integration, warns that subagent-heavy workflows can use up to seven times as many tokens as a standard session (cloudzero.com). Agent Teams are even more expensive, since each inter-agent message is a full round trip.
The pitfalls are well-known:
BOTTOM LINE
Claude Code subagents aren't magic — they're disciplined division of labor. A specific agent with limited context and precise permissions does its job better than one general assistant with too much responsibility. The proof is there: 16 to 54 percent code review coverage at Anthropic itself. Start with the built-in agents, keep them boring and specific, and stay alert to token costs. Agent Teams are promising — but still experimental.
Verified against 5 open primary sources and 5 independent analyses.