Introduction

When people think of Claude Code CLI, most still see it as just “an AI assistant that writes code.” But the Subagent feature we’re discussing today takes this tool to a whole new level.

Imagine you’re running a restaurant. When it’s small, the owner does everything - cooking, serving, and cashiering. But as the restaurant grows, you need to hire staff. Professional chefs handle the cooking, waiters serve the food, and cashiers manage payments. Everyone does what they’re best at, and the restaurant runs efficiently.

Claude Code’s subagent system works the same way. The main Agent is like the boss, coordinating everything; sub-Agents are like employees, each with their specialty. Some review code quality, others hunt for security vulnerabilities, some optimize performance, and others focus on test coverage. This approach not only boosts efficiency but also ensures each task gets professional treatment.

Four Key Advantages of Subagents

1. Context Preservation

Think of it like having dinner at home versus attending a company meeting - two completely separate scenarios. You can chat casually at home, but you won’t bring household chores into the company meeting. Subagents work the same way. Each has its own isolated “workspace,” handling tasks without interference from the main conversation’s context and without polluting the main dialogue.

For example, when you ask a subagent to check code for security vulnerabilities, it doesn’t need to know what you previously chatted about with the main Agent. It just focuses on the code at hand. This maintains focus while avoiding information overload.

2. Specialized Expertise

Just like going to the hospital - eye doctors handle eyes, orthopedists handle fractures, each doctor excels in their field. Subagents work similarly. You can configure specialized prompts and workflows for different task types.

A code quality review subagent might focus on SOLID principles, naming conventions, and code cleanliness, while a security subagent emphasizes injection risks, authentication, and data encryption. Each to their own specialty.

3. Reusability

This one’s even simpler. When you’ve worked hard to train an excellent code reviewer, you want it to work across all projects, not retrain it every time you switch projects.

Claude Code subagents, once created, can be reused across different projects and even shared with team members. This keeps the entire team’s workflow consistent and helps new members onboard faster.

4. Flexible Permissions

Like company permission management. Receptionists don’t need access to financial systems, and sales don’t need access to R&D codebases. Different roles have different permission scopes.

In Claude Code, you can set different tool access permissions for each subagent. Some might only need to read code, others might need to run tests, and some might need to modify files. Configure flexibly based on task requirements - safe and efficient.

Subagent Configuration Methods

Claude Code offers two ways to configure subagents, like categorizing employees into “full-time staff” and “contractors.”

Project Subagents

These are your “full-time employees,” dedicated to a specific project. Configuration files go in the project root’s .claude/agents/ folder. These subagents only work for the current project and have the highest priority.

For example, an e-commerce project might need a subagent specifically for payment security checks, while a data analysis project might need one for query performance optimization. These are project-specific needs, perfect for project subagents.

User Subagents

These are your “general consultants,” usable across all projects. Configuration files go in the user directory’s ~/.claude/agents/ folder. These subagents handle general tasks like code style checking and basic test coverage.

Note that when project and user subagents share the same name, the project subagent takes priority. Just like full-time employees definitely understand the project better than contractors.

The Relationship Between Main Agent and Subagents

Here’s an important concept: the main Agent and subAgents are isolated, like different departments with their own offices.

Imagine this scenario: you (the user) assign the boss (main Agent) a bunch of tasks. The boss looks and says, “Oh, this task needs code quality checking, so I’ll call the quality inspector (code-reviewer subagent); that task needs testing, so I’ll call the test engineer (test-runner subagent).”

Each subagent, after receiving its assignment, goes back to its own “office” (independent environment) to work, then reports results back to the boss. The boss compiles all results and finally reports to you.

What’s the benefit?

  1. No Context Confusion: The quality inspector doesn’t need to know what the test engineer is doing; each focuses on their own task
  2. Resource Savings: If the main Agent’s context is already large, you can offload some tasks to subagents, indirectly lightening the main Agent’s burden
  3. Parallel Tasks: Multiple subagents can work simultaneously, like multiple employees handling different tasks at once - much more efficient

Subagent Configuration Format

Each subagent is a Markdown file with a simple format, like filling out an employee information form:

---
name: code-reviewer
description: Review code for quality and maintainability
tools: Read, Grep, Bash
model: sonnet
color: red
---

You are an experienced code reviewer, excellent at finding code issues.
When reviewing, please focus on:
- Clean code principles
- SOLID principles
- DRY principle
- Naming conventions

Key fields:

  • name: The subagent’s name, like an employee ID
  • description: The subagent’s job description, telling the main Agent when to call this subagent
  • tools: List of tools the subagent can use; if omitted, all tools are available
  • model: The model the subagent uses; choose based on task difficulty
  • color: Display background color, purely for aesthetics and differentiation

The content below is the subagent’s “work manual,” detailing its role, skills, workflow, and considerations. The more detailed, the more professional the subagent’s performance.

Hands-On: Creating Your First Subagent

Enough theory - let’s get practical. Suppose we want to create a code reviewer.

Step 1: Create Configuration File

Create .claude/agents/code-reviewer.md in the project root:

---
name: code-reviewer
description: Review code for quality and maintainability
model: sonnet
color: red
---

You are a senior code reviewer with 10 years of development experience.
When reviewing code, be thorough like a teacher grading homework, but maintain a friendly attitude.

Focus on these aspects:
1. Is the code clear and understandable (naming, comments, structure)
2. Does it follow design principles (SOLID, DRY)
3. Are there obvious bugs or risks
4. Are there performance issues
5. Is the code style consistent

When giving suggestions, explain why changes should be made, don't just say "this is bad."

Step 2: Restart Claude Code

After creating the configuration file, restart Claude Code CLI to recognize the new subagent.

Step 3: Use the Subagent

Now you have two ways to use this subagent:

Implicit Invocation (let AI decide):

Please review my recent code changes

The AI sees the word “review,” checks the code-reviewer’s description, and knows to use this subagent.

Explicit Invocation (specify directly):

Use the code-reviewer subagent to review my latest changes

This explicitly tells the AI which subagent to use, no guessing needed.

Advanced Play: Multi-Subagent Collaboration

Once you have one subagent, you can have a second and third. Let’s create a few more:

  • security-auditor.md: Security auditor, specialized in finding security vulnerabilities
  • performance-engineer.md: Performance engineer, specialized in optimization
  • test-automator.md: Test specialist, specialized in checking test coverage

Serial Invocation: One After Another

Like assembly line work, do this then that:

First use code-reviewer to check code quality,
then use security-auditor to check security issues,
finally use performance-engineer to analyze performance

The AI calls these three subagents in sequence, each completing before the next starts.

Parallel Invocation: Work Simultaneously

If tasks are independent, let multiple subagents work at once:

Use security-auditor and performance-engineer simultaneously to check this code,
then summarize the results for me

This is like having multiple employees work simultaneously - obviously more efficient.

Ultimate Play: Building Workflows with Custom Commands

If you frequently need to execute a fixed set of checks, typing long commands every time is obviously too cumbersome. This is where Custom Commands come in handy.

For example, let’s create a “full review” command that calls four subagents at once:

In .claude/commands/full-review.md, write:

---
description: Comprehensive code review
argument-hint: [content to review]
model: sonnet
---

Execute multiple subagents to comprehensively review $ARGUMENTS, require parallel execution:

1. Code quality check - invoke code-reviewer subagent
2. Security audit - invoke security-auditor subagent
3. Performance analysis - invoke performance-engineer subagent
4. Test coverage assessment - invoke test-automator subagent

Finally, organize all feedback into a unified report, prioritized as:
- Critical issues (must fix)
- Recommendations (should fix)
- Suggestions (consider fixing)
- Positive feedback (what's done well)

After restarting Claude Code, just use one command:

/full-review @index.py

Four subagents start working simultaneously, and after each completes their task, the main Agent compiles the results into a complete review report. How’s that for efficiency?

Practical Tips and Considerations

Don’t Write Prompts from Scratch

Many people panic when they hear “write prompts,” but there’s no need to worry. GitHub has tons of ready-made subagent configurations - search “claude code subagent” and you’ll find plenty. Take them, modify slightly, and adjust to fit your project needs.

Just like cooking doesn’t require inventing recipes - follow existing ones, adjust to your taste, and you can still make delicious food.

Set Tool Permissions Wisely

Not all subagents need access to all tools. For example, a pure static analysis subagent might only need Read and Grep, not Write and Bash.

Like company permission management - give what should be given, don’t give what shouldn’t. It’s safer and avoids mistakes.

Use Colors for Differentiation

While the color field seems purely decorative, when using multiple subagents simultaneously, different colors let you instantly see which subagent is speaking. Red for reviewer, yellow for security, green for performance engineer, blue for tester - crystal clear at a glance.

Balance Project-Level and User-Level

General subagents (like basic code review, simple test checking) can go at the user level, usable across all projects. Project-specific subagents (like framework-specific checks, business rule validation) go at the project level.

This reuses general capabilities while meeting project-specific needs.

Summary

Claude Code’s subagent mechanism essentially transforms “one person doing everything” into “team division of labor.” Each subagent has its own specialty and work environment, neither interfering with nor hindering each other’s collaboration.

Properly using subagents enables you to:

  • Get more professional handling for each task
  • Avoid context pollution, maintain task focus
  • Improve work efficiency, support parallel processing
  • Establish reusable workflows, reduce repetitive labor

In simple terms, it upgrades the AI assistant from an “all-rounder” to a “professional team.” As the “project manager,” you just assign tasks, and leave the rest to professional “employees.”

This isn’t just technical progress - it’s a work methodology revolution. From now on, your Claude Code isn’t a lone warrior but a skilled elite team.

Think about it - next time you write code, you’ll have a code reviewer, security expert, performance engineer, and test engineer standing beside you. Doesn’t that lineup feel reassuring?

Final Thoughts

This article actually comes from my own experiences using Claude Code subagents. When I first started, I thought configuring subagents was quite troublesome, until one day a project needed a security audit with four or five check items. Running them manually one by one took half a day. After configuring a few subagents, one command did everything - it felt like suddenly having several assistants.

AI tools evolve incredibly fast. Two years ago we debated whether AI could write code; now we’re discussing how to make AI teams collaborate. If you’re also following AI programming tool developments or want to exchange practical experiences, welcome to follow my blog “Dream Beast Programming.” I’ll continue sharing AI tool usage tips and lessons learned, along with thoughts on this field.

After all, this field changes so fast - exploring alone always has limitations. Exchanging ideas together helps us all avoid detours.