Claude Code's Agent Features (Using Sub-agents)
Claude Code goes beyond a mere "dialogue CLI," with a Sub-agent feature that runs multiple agents in parallel itself. It can speed up large tasks.
What Is a Sub-agent
A mechanism where the main Claude Code session (orchestrator) calls child agents handling specific tasks. Parallel execution shortens time; context separation raises accuracy.
Typical Use
1. Parallel Research
> I want to write this project's API documentation. > Investigate each endpoint in parallel. → Claude Code spins up 5 Sub-agents, each handling a different endpoint, aggregating results.
2. Refactor Division
> Make all TypeScript files strict-mode compliant. > Process in parallel by module with Sub-agents.
3. Parallelizing Test Generation
> Add tests to each file in src/utils/*. > 1 Sub-agent per file.
Sub-agent Definition (Project-Specific)
In the .claude/agents/ directory, you can define specialist Sub-agents.
# .claude/agents/code-reviewer.md --- name: code-reviewer description: A specialist agent that reviews code changes --- You are a senior code reviewer. Focus on: - Security (auth, input validation, secrets) - Performance (N+1, memory leaks) - Correctness (error handling, edge cases) Output format: - Issues found (severity) - Specific line references - Suggested fixes
# .claude/agents/test-writer.md --- name: test-writer description: A specialist agent that writes tests --- You are a test engineer. Use Vitest. Write: - Happy path tests - Edge cases - Error scenarios - 1 file per source file
How to Call
Call Explicitly
> @code-reviewer review this directory's recent changes > @test-writer write tests for src/utils/parseDate.ts
Called Automatically
If the main Claude Code judges "this is test-writer's job," it auto-delegates.
Where to Use It
| Scene | Sub-agent effect |
|---|---|
| Same-kind change to many files | 3-5x faster via parallel |
| Different expertise needed | Separate reviewer / implementer / test-writer |
| Context tends to get dirty | Independent context per role |
| Multiple independent tasks | Time saved by concurrency |
Uses to Avoid
- A one-line task: Sub-agent overhead is larger
- Strong dependency: if B uses A's result, sequential is fine
- Multiple Sub-agents editing the same file: a hotbed of conflicts
Pricing and Performance
- Pricing: Sub-agents also call the Claude API so cost adds up. Parallel saves time but increases tokens
- Pro plan: mind the monthly limit
- Max plan: heavy use possible at USD 100-200/mo
Control Flow
Parallel Execution
> The following in parallel: > - Add missing tests under tests/ > - Update docs/ to the latest > - Update CHANGELOG.md
Approval Points
> Each Sub-agent's output, commit after waiting for my OK.
Logs and Debugging
- Sub-agent execution logs saved in
.claude/logs/ - Trace "what did it do then?" later
- Re-runnable on failure
Team Operation
- Commit Sub-agent definitions to Git
- Everyone using the same Sub-agent = uniform output quality
- Maintain periodically (update old Sub-agents)
Application Examples
- Auto-generate API docs: parallel-research each endpoint
- Multilingualization: parallel-translate each language file
- Security audit: check from multiple angles simultaneously
- Performance analysis: parallel-investigate multiple bottleneck candidates
Foundations Chapter Wrap-Up
Now the 2 foundations chapters of "Develop" (LLM dev basics + AI coding tools) are in place. Next, proceed to the practice chapters "Prompt Design" and "App Development."
