Introduction to the concept of Claude Code Subagent

Introduction

When using Claude Code to handle complex tasks, you may have encountered such a dilemma: the context of the main conversation is getting longer and longer, the AI begins to "forget" previous important information, and the quality of the response gradually decreases.

Subagent was born to solve this problem.

If Skills is the "work manual" for Claude, then Subagent is the "full-time employee" you hire - they have their own independent work station (context), focus on a specific type of work, and report the results to you after completion.

Understanding Subagent

Imagine you are the CEO of a company. When the company is small, you handle everything yourself. But as your business expands, you start hiring full-time employees: accountants for finance, HR for recruiting, and engineers for development. Each employee works at his or her own station and reports to you after completing the task.

Subagent plays exactly this role in Claude Code.

From a technical perspective, Subagents are specialized AI assistants that have the following characteristics:

Why do we need an independent context?

This is the core design concept of Subagent and deserves a deep understanding.

In a normal conversation, all information is piled into the same context. When you have Claude search the code base, analyze the files, and then make modifications, all of this intermediate processing takes up context space. As the conversation progresses and the context becomes more crowded, Claude may begin to "forget" earlier important information.

Subagent changes that:

主对话（专注于高层目标）
│
├── 用户：帮我优化这个模块的性能
│
├── Claude：我来分析一下...
│   │
│   └── [调用 Explore Subagent]
│       │ 在独立上下文中：
│       ├── 搜索相关文件
│       ├── 分析代码结构
│       ├── 识别性能瓶颈
│       └── 返回：发现 3 个优化点...
│
└── Claude：根据分析，我发现 3 个优化点...

Subagent's analysis process does not pollute the main conversation. The main dialogue received only refined results, maintaining clarity and focus.

Built-in Subagent type

Claude Code provides three powerful built-in Subagents, covering the most common usage scenarios:

Explore Subagent

Targeting: Fast, read-only exploration of the code base.

Features:

• Use Haiku model (fast, low latency)
• Strictly read-only - files cannot be created, modified or deleted
• Available tools: Glob, Grep, Read, Bash (read-only operations)

When to use: When you ask exploratory questions such as "Where is this function implemented?" and "How are errors handled?" Claude will automatically call Explore Subagent.

Detail Level:

Plan Subagent

Positioning: Study the code base and prepare an implementation plan.

Features:

• Use Sonnet model (stronger inference capabilities)
• Only exploration tools: Read, Glob, Grep, Bash
• Automatically called in planning mode

When to use: When you enter planning mode and need Claude to conduct research before proposing a plan, Plan Subagent will automatically collect information and then give plan suggestions based on the research results.

General-purpose Subagent

Positioning: Handle complex multi-step tasks.

Features:

• Use Sonnet model
• Access to all tools (including reading and writing)
• Suitable for complex tasks that require exploration and modification

When to use: When the task involves multiple steps, requires searching before modifying, or the initial search may fail and multiple strategies need to be tried.

My understanding and practice

If you carefully observe the three official built-in Subagents, you will find one thing in common: They are all research and planning tasks. Explore is responsible for exploring the code base, Plan is responsible for making plans, and even General-purpose is mainly used for research and analysis. None of them are specifically designed for writing code.

This confirms my understanding of Subagent: The core value of Subagent is not "clean context", but to allow the main agent to focus on doing things.

Division of labor mode

My usage method is very simple: Subagent is responsible for "information collection" work such as research, planning, and review, and the main agent is responsible for actual execution.

Subagent（调研员）          主 Agent（执行者）
     │                           │
     ├── 探索代码库结构            │
     ├── 分析依赖关系              │
     ├── 制定实施计划              │
     └── 返回精炼的上下文 ──────────→ 基于上下文执行任务
                                  │
                                  ├── 编写代码
                                  ├── 修改文件
                                  └── 运行测试

Why not let Subagent write code?

Some people like to have the main agent schedule multiple subagents to write code. I think this is unreliable. The reason is simple: Context is severely missing.

The Subagent's context is independent. It does not know what was discussed, what decisions were made, and what constraints were imposed in the main conversation. Asking it to write code is like asking a new employee to complete a task without any background information - the code produced is likely not to match your expectations.

On the contrary, it is much more reasonable to position Subagent as a "researcher":

• The research task itself does not require much context
• Information is returned instead of code, which can be used by the main agent based on the full context
• Even if the survey results are biased, the main agent can correct them

My daily usage

1. Before starting a new task: Let the Explore agent quickly understand the structure of the relevant code
2. Complex task planning: Let the Plan agent analyze the requirements and formulate implementation steps
3. Code Review: Let the Review agent check code quality and security issues
4. Actual Coding: The main agent writes code based on the collected context

Here is the list of agents I currently use:

The advantage of this is that the main agent's context window remains clean, with only "the information I need to know" instead of "a bunch of intermediate results generated during the Subagent search process".

Comparison with other functions

Subagent vs Skills

This is the most common confusion. Core difference: Skills inject knowledge into Claude; Subagent creates independent workers.

To put it figuratively: Skills are like training materials, allowing Claude to learn how to do something; Subagent is like a full-time employee, who completes the task independently at his or her work station and reports the results.

The two can be combined: a code review Subagent can load the code specification Skill to achieve the combined effect of "expert + professional knowledge".

Subagent vs slash command

The slash command is a shortcut key, and you enter /review to trigger a predefined operation; Subagent is an independent worker that can complete complex multi-step tasks autonomously.

Subagent vs Plugin

Plugin is a "container" concept, which can contain Subagent:

Plugin（容器）
├── Commands（快捷命令）
├── Skills（知识包）
├── Agents（子代理）← 这就是 Subagent
└── Hooks（事件钩子）

You can define a Subagent in the Plugin's agents/ directory and distribute it with the Plugin.

Agentic design pattern

Anthropic summarizes six core Agentic design patterns in its official documentation. Understanding these patterns can help better design Subagent systems:

These modes can be used in combination. For example, a code quality system might use both:

• Parallelization: run security scans and performance analysis simultaneously
• Orchestrator-Workers: Master Claude coordinates multiple specialized Subagents
• Evaluator-Optimizer: Review code immediately after generation

Core Advantages

Context protection

Subagent's greatest value lies in protecting the context of the main conversation. Intermediate processes such as code search and file analysis will not be accumulated in the main dialogue, allowing the main dialogue to always focus on high-level goals.

Specialization capabilities

You can create specialized Subagents for specific domains, configured with detailed instructions and appropriate tools. A specialized Subagent performs better at a specific task than a general-purpose Claude.

Flexible permission control

Each Subagent can have different tool access rights. For example, the exploration class Subagent only gives read-only permissions, and the modification class Subagent only gives write permissions. This fine-grained control improves security.

Reusability

Once created, Subagent can be reused across projects or shared with teams via plugins.

When to use Subagent

Suitable scenarios for using Subagent:

• Requires independent context to run tasks
• Tasks are complex multi-step workflows
• Requires a different toolset than the main conversation
• Tasks may take a long time to run

Scenarios not suitable for using Subagent:

• Simple one-time query
• Requires close interaction with main dialogue
• Missions can be completed quickly

Typical application scenarios

Code review

代码审查 Subagent
├── 专门的审查提示
├── 只读工具（Read, Grep, Glob）
└── 输出：结构化的审查报告

When you complete a piece of code, you can have Code Review Subagent review it in an independent context without interfering with your main development work.

Debugging analysis

调试 Subagent
├── 错误分析专家提示
├── 读写工具
└── 输出：根因分析 + 修复方案

When an error is encountered, Debugging Subagent can deeply analyze the cause of the error, try various hypotheses, and finally provide repair suggestions.

Code base exploration

探索 Subagent
├── Haiku 模型（快速）
├── 只读工具
└── 输出：代码结构概览

When you're new to a new project, Explore Subagent can quickly map your code base without cluttering your main conversation with tons of search results.

Learning resources

Official resources

Community Resources

Summary

Claude Code Subagent is essentially a specialized, context-independent AI assistant. It solves the problem of information overload in complex tasks through context isolation, keeping the main conversation clear and focused at all times.

Remember three key words:

After understanding the concept, the next article "Claude Code Subagent Practical Guide" will take you to practice: creating a custom Subagent, configuring tool permissions, and best practices in actual projects.

If you want to know the Skills that Subagent can load, please read "What are Claude Skills". If you want to package Subagent for distribution, please read "What is Claude Code Plugin".