Sub Agents in Claude Code: The Functionality That Changes Your Development Workflow
Reading time: 6 minutes
If you use Claude Code regularly, you probably already know its basic workflow: plan, code, test. It works well. But there’s a functionality that Anthropic quietly launched and few developers are taking advantage of: Sub Agents.
The result? A workflow where each task has a dedicated specialist, with their own context and specific tools.
The Problem That Sub Agents Solve
When we develop, we constantly switch between different “mental modes”:
- Architecture Mode: Designing code structure
- Testing Mode: Looking for edge cases and coverage gaps
- Debugging Mode: Tracing the root cause of a bug
- Documentation Mode: Updating READMEs and comments
- Refactoring Mode: Improving existing code without breaking functionality
The problem arises when you ask Claude Code to do something specific and it decides to do something different:
- You ask it to fix a test → it refactors the entire test suite
- You ask it to find a bug → it implements a new feature
- You ask for suggestions → it starts coding changes
This happens because Claude Code, by default, has access to all tools and operates in a single context. Sub Agents solve exactly this.
What Are Sub Agents?
Sub Agents are specialized AI assistants within Claude Code. Each one has:
| Characteristic | Description |
|---|---|
| Own System Prompt | Specific instructions for their role |
| Restricted Tools | Only access to what they need |
| Isolated Context | Doesn’t mix with other tasks |
| Explicit Invocation | You decide when to use it |
Think of them as a team of specialists you can call upon based on the task.
Setting Up Your First Sub Agents
Step 1: Update Claude Code
First, make sure you have the latest version:
claude update
Step 2: Access the Agents Menu
Within Claude Code, run:
/agents
You’ll see options to create, edit, and manage your agents.
Step 3: Create an Agent
Select “Create new agent” and then “Generate with Claude” (recommended).
Claude will ask you to describe what you want the agent to do. For example:
Expert in test coverage analysis. Only analyzes and suggests,
never modifies code. Identifies gaps in testing and uncovered edge cases.
Step 4: Configure the Tools
This is the key part. Restrict tools based on the role:
| Agent Type | Recommended Tools |
|---|---|
| Architect | Read, List, Glob (read-only) |
| Test Analyst | Read, List, Glob (read-only) |
| Implementer | Read, Write, Edit, Bash |
| Debugger | Read, Bash, Edit (limited) |
| Documenter | Read, Write (only .md and comments) |
An architecture agent should not be able to edit code. Only analyze and recommend.
Step 5: Choose the Scope
You have two options:
- Project Agents: Saved in
.claude/agents/of the project. Versioned with git. - Global Agents: Available across all your projects.
For teams, Project Agents are ideal because everyone shares the same specialists.
Practical Case: Developing a Feature with Sub Agents
Let’s see a real workflow. Suppose you need to implement JWT authentication in an API.
Agent 1: Architect (Read-Only)
Name: architect
Prompt: Expert in software architecture. Analyzes project structure,
suggests patterns and evaluates technical decisions. NEVER implements code,
only provides detailed recommendations.
Tools: Read, List, Glob
Invocation:
@architect I need to implement JWT authentication.
How should I structure the modules?
Expected result: An analysis of your current structure and recommendations on where to place middleware, services, and utilities. Without touching any files.
Agent 2: Implementer
Name: implementer
Prompt: Developer focused on implementation. Follows exact specifications
without adding unsolicited functionality. Writes clean and well-documented code.
Tools: Read, Write, Edit, Bash
Invocation:
@implementer Implement the JWT authentication middleware
according to the architect's recommendations in /src/middleware/auth.ts
Expected result: Precise implementation of what was requested, without surprise refactors.
Agent 3: Test Analyst
Name: test-analyst
Prompt: Testing specialist. Analyzes existing coverage, identifies
uncovered edge cases and suggests necessary tests. DOES NOT write tests,
only provides detailed specifications.
Tools: Read, List, Glob
Invocation:
@test-analyst Analyze the auth middleware we just created.
What test cases do we need?
Expected result: Detailed list of test cases: valid token, expired token, malformed token, missing header, etc.
Agent 4: Test Writer
Name: test-writer
Prompt: Writes tests based on provided specifications.
Follows project conventions. One test at a time when requested.
Tools: Read, Write, Edit
Invocation:
@test-writer Implement the tests for the expired token case
according to the analysis above
Expected result: Only the requested test, not the entire suite.
Recommended Agent Configurations
Here’s a set of agents that works well for most projects:
┌─────────────────┬──────────────────────────────────────┬─────────────────┐
│ Agent │ Purpose │ Tools │
├─────────────────┼──────────────────────────────────────┼─────────────────┤
│ architect │ Analysis and structure design │ Read, List │
│ implementer │ Feature coding │ Read, Write, │
│ │ │ Edit, Bash │
│ test-analyst │ Coverage analysis and gaps │ Read, List │
│ test-writer │ Writing specific tests │ Read, Write │
│ debugger │ Bug investigation │ Read, Bash │
│ refactor │ Improvements to existing code │ Read, Write, │
│ │ │ Edit │
│ docs │ Documentation and comments │ Read, Write │
│ reviewer │ Code review and suggestions │ Read, List │
└─────────────────┴──────────────────────────────────────┴─────────────────┘
Tips for Leveraging Sub Agents
1. Start with 3-4 Agents
You don’t need to create 10 agents on day one. Start with the essentials: architect, implementer, and test-analyst.
2. Tool Restriction is Key
The magic is in limiting what each agent can do. An architect who can edit code will eventually do it.
3. Use Project Agents for Teams
Save them in .claude/agents/ and push them to the repository. The entire team works with the same specialists.
4. Delegate Explicitly
Instead of expecting Claude Code to choose the right agent, invoke them directly with @agent-name.
5. Iterate on Prompts
If an agent doesn’t behave as expected, adjust its system prompt. Be specific about what it should and shouldn’t do.
How Delegation Works
Claude Code can automatically delegate tasks to sub agents when it detects that another specialist would be more appropriate. But you can also be explicit:
# Explicit delegation
@architect review the structure of the payments module
# Claude Code decides
I need to analyze the payments architecture
# (Claude may automatically invoke the architect)
ConclusionSub Agents transform Claude Code from a generalist assistant to a team of specialists. The main benefit is not code speed—it’s control over workflow and elimination of unwanted context switching.
If you’ve been using Claude Code for a while and feel like it sometimes “goes off on tangents”, Sub Agents are the solution you’ve been looking for.
Have you tried Sub Agents yet? Share your setup in the comments. What agents have you created for your workflow?
For more information, consult the official Claude Code documentation.