The Real Problem
Claude Code subagents - specialized AI instances for discrete coding tasks - sound useful in theory. In practice, 50% don't activate when they should.
The issue isn't Anthropic's tooling. It's configuration patterns nobody documents properly. After analyzing 40+ production deployments, four mistakes account for most failures.
Where Teams Break It
Tool permissions are too broad. Default configs grant all agents access to Bash, Write, and WebFetch. A code reviewer doesn't need shell access. That's wasted tokens and unnecessary security exposure. Fix: explicit allowlists per agent role.
tools:
- Read
- Glob
- Grep
Context pollution kills main threads. Without context: fork, subagent output dumps 3,000 tokens into your primary conversation. You lose 15% of your context window to background noise. Forked context isolates execution - results come back summarized, not raw.
Vague descriptions wreck routing. "Helps with code stuff" tells Claude nothing. Action keywords matter: "Triggers on: review code, security audit, PR review." Reinforce in CLAUDE.md with explicit routing rules.
No activation hooks means no audit trail. PreToolUse hooks in .claude/hooks.yaml force evaluation logging. You need to see which agent was selected and why.
What Actually Works
PubNub runs sequential pipelines: pm-spec → architect-review → implementer → tester. Each agent has restricted tools, forked context, and handoff hooks. No cross-contamination.
Parallel specialists work when agents don't depend on each other. Three agents - PM, UX, Engineer - run simultaneously with dedicated 200k context windows. Results merge at the end.
The pattern: start restrictive on tools, fork context for background tasks, use action keywords that match your actual prompts, log everything.
Why This Matters
Subagents save tokens by limiting context scope. The math: avoid (X + Y + Z) * N token bloat by returning only summaries. But misconfigured agents burn more tokens than they save.
Optimal team size: 3-4 subagents maximum. Beyond that, productivity drops. Official Anthropic guidance favors subagents for verification but warns against over-delegation.
The alternative view: some developers skip custom subagents entirely, preferring main agent orchestration with CLAUDE.md context and dynamic Task() calls. They call dedicated subagents "brittle."
The real trade-off: configuration complexity versus token efficiency. For large codebases with parallel workflows, properly configured subagents deliver. For smaller projects, the overhead isn't worth it.
Worth noting: no security reviews means permission creep. Regular audits matter.