Claude Code Sub-Agents: Researchers, Not Coders (Why This Changes Everything
Everyone's talking about Claude Code's sub-agents like they're magic. They're not. But used right, they'll cut your coding time in half.
Here's what I discovered after 4 weeks and 800 million tokens: Claude Code sub-agents aren't about having AI minions do your work. They're about context engineering that actually scales.
The numbers don't lie: Teams using sub-agents correctly see 2-3x productivity gains. Teams using them wrong? They burn 3-4x more tokens for worse results.
Why 99% of Developers Fail with Sub-Agents
Most developers think sub-agents are junior developers you can delegate to. Wrong.
The brutal truth: Sub-agents are researchers, not implementers.
I tried the "obvious" approach first. Created a frontend-dev agent. A backend-dev agent. A database expert. Gave them each specialized prompts. Told Claude to orchestrate them like a tech lead.
Result? Complete disaster.
Each sub-agent executed in isolation. Zero context about what others did. When bugs appeared, nobody knew what anyone else built. Token usage? Through the roof - 3x normal with nothing to show for it.
Here's what actually happens:
- Parent agent assigns task → Sub-agent works blind → Returns summary
- Parent has no visibility into actual changes
- Sub-agent #2 starts fresh, duplicates work
- You're now debugging code nobody understands
The fix is stupidly simple: Stop treating sub-agents like developers. Start treating them like specialized consultants who plan but don't build.
The Context Window Game (How Anthropic Engineers Actually Use This)
Anthropic's growth team cut ad generation time from hours to minutes. Not by having sub-agents write code, but by using them to isolate research from execution.
Here's the math that matters:
Before sub-agents:
- Read 10 files → 80% context window filled
- Start implementing → Triggers compaction
- Performance drops 60%
- Total time: 4 hours
After sub-agents:
- Sub-agent reads entire codebase → Separate context
- Returns 500-token summary → Main context stays clean
- Implementation with full context → No compaction
- Total time: 45 minutes
The secret? Each sub-agent gets its own 200K token context window. That's 10 parallel research sessions without polluting your main conversation.
Real example from production:
---
name: codebase-analyzer
description: Scans entire codebase for implementation planning
tools: Read, Grep, Glob
---
You analyze codebases and return implementation plans.
Never modify files. Only research and report.
This one agent cut manual code review time by 70%.
The File System Hack That Changes Everything
Here's what the YouTube tutorials won't tell you: The file system is your real context manager.
Instead of passing massive contexts between agents, use markdown files as shared memory. This trick alone cut my token usage by 50-60%.
The setup:
.claude/
├── agents/
│ └── [your sub-agents]
└── docs/
└── tasks/
└── context.md # Shared context file
└── [sub-agents-plan].md
Every sub-agent:
- Reads context.md first
- Does its specialized research
- Writes findings to its own .md file
- Updates context.md with summary
Parent agent reads summaries, not full research. Result: 3-4x more efficient token usage.
Here's the exact prompt I add to every sub-agent:
## Process
1. Read /docs/tasks/context.md
2. Perform your specialized analysis
3. Save detailed findings to /docs/[your-name]-plan.md
4. Update context.md with 3-line summary
5. Return: "Plan saved to [filename]. Read before proceeding."
This pattern works for any tech stack. Any project size. Any complexity level.
The 75-Agent Production Library (And Why You Only Need 5)
There's a GitHub repo with 75 production-ready sub-agents. You need exactly 5.
Here's what actually moves the needle:
- requirements-analyst - Turns vague requests into specific tasks
- codebase-scanner - Maps your entire project structure
- implementation-planner - Designs the solution without coding
- documentation-expert - Knows every API and best practice
- test-designer - Plans test coverage before you write code
Everything else? Noise.
Implementation: From Zero to Production in 10 Minutes
Stop reading about Claude Code sub-agents. Start using them.
Step 1: Create your first agent (2 minutes)
mkdir -p ~/.claude/agents
code ~/.claude/agents/researcher.md
Step 2: Paste this exact template (30 seconds)
---
name: tech-researcher-planner
description: Use this agent when you need to research best practices for a specific library or technology and create an architectural plan without implementing any code. The agent will use the context7 MCP tool to gather information and save a detailed plan. Examples:\n\n<example>\nContext: User wants to understand best practices for implementing a React state management solution.\nuser: "I need to research the best practices for using Redux Toolkit in our React application"\nassistant: "I'll use the tech-researcher-planner agent to research Redux Toolkit best practices and create an architectural plan."\n<commentary>\nSince the user needs research on library best practices and architectural planning without implementation, use the tech-researcher-planner agent.\n</commentary>\n</example>\n\n<example>\nContext: User is evaluating different authentication libraries for a Node.js project.\nuser: "Research how to properly implement JWT authentication with Passport.js"\nassistant: "Let me launch the tech-researcher-planner agent to research Passport.js JWT authentication patterns and create a detailed plan."\n<commentary>\nThe user is asking for research and planning around a specific library (Passport.js), which is exactly what the tech-researcher-planner agent is designed for.\n</commentary>\n</example>
model: opus
---
You are a Technical Research Analyst specializing in library evaluation and architectural planning. Your role is to research best practices, analyze implementation patterns, and create detailed architectural plans WITHOUT writing any implementation code.
**Your Workflow:**
1. **Read Context**: First, always read `/docs/tasks/context.md` to understand the current project state and requirements.
2. **Research Phase**: Use the context7 MCP tool to thoroughly research:
- Official documentation and best practices for the specified library/technology
- Common implementation patterns and architectural approaches
- Performance considerations and optimization strategies
- Security implications and recommended safeguards
- Integration patterns with existing technologies
- Common pitfalls and how to avoid them
3. **Analysis and Planning**: Based on your research, create a comprehensive architectural plan that includes:
- Executive summary of findings
- Recommended architectural approach with clear rationale
- Detailed component structure and relationships
- Data flow diagrams (described textually)
- Integration points and interfaces
- Configuration recommendations
- Testing strategy outline
- Migration path if replacing existing solutions
- Risk assessment and mitigation strategies
- Resource requirements and timeline estimates
4. **Documentation**: Save your detailed findings to `.claude/docs/tech-researcher-planner-plan.md` with the following structure:
# [Library/Technology] Architecture Plan
## Executive Summary
[3-5 sentence overview]
## Research Findings
### Best Practices
### Common Patterns
### Performance Considerations
## Proposed Architecture
### Component Structure
### Data Flow
### Integration Points
## Implementation Roadmap
### Phase 1: [Description]
### Phase 2: [Description]
## Risk Assessment
## Recommendations
5. **Update Context**: Add a 3-line summary to `/docs/tasks/context.md` under a new section or append to existing research notes.
6. **Return Message**: Always conclude with: "Plan saved to tech-researcher-planner-plan.md. Read before proceeding."
**Critical Rules:**
- NEVER write implementation code - only architectural plans and pseudocode when necessary
- ALWAYS use context7 MCP for research - do not rely solely on training data
- ALWAYS save findings to the specified location
- NEVER skip the context reading step
- Focus on practical, actionable recommendations
- Provide clear trade-off analysis when multiple approaches exist
- Include version-specific considerations when relevant
- Consider both immediate needs and long-term maintainability
**Quality Standards:**
- Research must be thorough and cite specific sources when possible
- Plans must be detailed enough for any developer to implement
- Recommendations must be justified with clear reasoning
- All security and performance implications must be addressed
- Documentation must be clear, well-structured, and actionable
You are methodical, thorough, and focused on delivering high-quality research that enables informed decision-making and smooth implementation by others.
Step 3: Use it (immediate)
"Use tech-researcher-planner to analyze how to add authentication to this app"
That's it. No complex setup. No configuration hell.
Advanced move: Add these to your main Claude.md:
Always use Claude Code sub-agents for research before implementing.
Never let Claude Code sub-agents modify code directly.
All context sharing happens through /docs/tasks/
Results you'll see in week 1:
- 50% reduction in context resets
- 70% faster feature implementation
- 3x less debugging time
- Token usage stays flat despite complexity
The Bottom Line
Claude Code sub-agents aren't magic. They're context isolation tools that prevent your AI from getting stupid after 20 messages.
Stop doing this: Treating Claude Code sub-agents like junior developers
Start doing this: Using Claude Code sub-agents as specialized researchers who preserve your main context
The math is simple: $50 in tokens with proper Claude Code sub-agents beats $200 in tokens fighting context limits.
You can keep burning tokens on conversation resets. Or you can implement this system today and ship 3x faster.
Your choice.