Skip to main content
Aotokitsuruya
Aotokitsuruya
Senior Software Developer
Published at

Using Claude Code's Agent Feature Correctly

This article is translated by AI, if have any corrections please let me know.

Have you seen Claude Code’s Sub-Agent feature and immediately wanted to design a bunch of them? Backend Agent, Frontend Agent, and so on—it feels like getting more powerful tools. But do you really need them?

During WebConf 2025, chatting with friends about this topic revealed that many people are still unfamiliar with when to use Sub-Agents. Two talks at the conference provided good entry points: ihower’s AI Agents Development and 91APP’s Chief Architect Andrew’s From Service to Agent.

Skipping Sub-Agents is normal

After Anthropic launched a subscription plan this year that allows nearly unlimited use of Claude Code, many people went crazy designing Sub-Agents as soon as Anthropic released the feature—Backend Agent, Frontend Agent, and more. But do most scenarios really need Sub-Agents?

In reality, most scenarios don’t need Sub-Agents. Before Sub-Agents existed, using Claude Code for development assistance worked fine. Adding Sub-Agents shouldn’t dramatically improve things—this is likely a misunderstanding of the feature. The cost of using Sub-Agents multiplies: having two Sub-Agents roughly doubles the cost because each Agent calculates token usage independently. That’s why expenses can quickly escalate. If Anthropic charged actual rates, you probably wouldn’t choose this approach.

Therefore, it’s important to first understand what types of applications Claude Code’s Sub-Agent can provide, as there are many varieties in practice. You can observe the different types from ihower’s talk.

During WebConf, a friend happened to share the paper Towards a Science of Scaling Agent Systems, which tests multi-Agent performance. In some scenarios, using multiple Agents actually causes regression.

When to use

Generally, Sub-Agents are useful in two scenarios: one is for collecting data, and the other is for tasks suitable for parallel processing. In all other cases, there’s no need to deliberately use them.

Starting with the data collection scenario: the problem here is the Context Window limit. If you use a single Agent to collect information, you easily get too much noise and exceed the Context Window limit. Therefore, Sub-Agents are well-suited for this—DeepResearch is a classic example.

If you observe newer versions of Claude Code’s design closely, “code searching” scenarios may also automatically switch to using Sub-Agents. This is clearly a data collection scenario, but you’ll notice Claude Code doesn’t use a “specific Sub-Agent”—instead, it uses tools like Task to handle this.

This leads to the other scenario: using the Task tool for parallel processing. In Agent operations, the flow is linear, so waiting for each action to complete takes a long time. Using the Task tool allows splitting work to another Agent to “focus on processing” and report results back, which can significantly speed up the process.

If you look closely at how DeepResearch operates, it’s essentially a combination of these two characteristics. This multi-Agent mechanism follows a Master-Slave architecture, which is why it’s called “Sub-Agent”—it provides the main Agent with management and summarization capabilities.

Basically, when using Claude Code with Sub-Agents, these are the usage scenarios. Understanding this helps you better judge what to do next.

For example: If you want Claude Code to collect data, you can ask it to break down multiple tasks, use the Task tool to parallelize WebSearch tool calls for data collection, then consolidate everything. This works great for scenarios requiring quick searches across large volumes of documents.

Practical applications

With the usage scenarios now clear, it’s still important to distinguish between two different approaches: using the Task tool versus defining Sub-Agents. The following practical examples help illustrate this.

First, don’t immediately define Sub-Agents and write System Prompts to solve specific problems. Initially, you should start with the Task tool to “observe” usage patterns.

Suppose the goal is to collect information about a project. Initially, it should look like this:

1Use the Task tool to check the contents of `src/modules/` directory in parallel and create a module analysis report at `docs/modules.md`
2
3- Each directory under `src/modules/*` is an independent module; use one Task to inspect each
4- Each module should have its own section in the document
5- Explain each module's characteristics; the first paragraph should cover the general design across modules
6
7Please confirm the directory structure first, plan the tasks, then begin detailed analysis

Roughly speaking, Claude Code first uses commands like ls src/modules/ to understand each module’s general situation, then generates multiple Task(...) calls to verify. Before using Tasks, it might also sample a few files.

At this point, use Ctrl + O to view details and Ctrl + E to expand Claude Code’s instructions for each Task. These become potential System Prompts for future Sub-Agents.

The next stage requires analyzing whether Sub-Agents are actually needed.

  • If dynamically generated Tasks already work well, you basically don’t need Sub-Agents
  • This specific task requires dedicated instructions

If Tasks don’t perform well and Claude Code can’t write good instructions either, only then should you move toward Sub-Agents for more detailed customization.

Simply put, Sub-Agents are most useful in situations with specific requirements, wide-ranging data collection needs, and tasks with no dependencies.

Designs like Frontend Agent or Ruby Agent are quite poor. In Claude Code’s official examples, most are forms like Code Review Agent (specialized) rather than somewhat broad task definitions.

As an example, one rarely used Rubric Code Analyzer Agent exists in this author’s Claude Code setup, only activated when working with legacy projects. This is because Rubric is a design to constrain Claude Code’s code implementation, but organizing these rules for legacy projects requires searching through lots of source code.

So, a Sub-Agent helps with searching, and these searches follow specific rules:

  • Conventions
  • Patterns
  • Best Practices
  • Agreements

This Sub-Agent must filter information according to requirements. For conventions, it might discover that variable naming consistently uses snake_case instead of camelCase. That means it needs to review most of the source code and find the most frequent approach. Other rules work similarly.

This approach is essentially heavy searching combined with parallel reading. After collecting information and passing it back for synthesis, it usually produces reasonably good rules.

Outside of these types of situations, you mostly don’t need to specifically use Sub-Agents.

Frontend-backend separation might seem like it could use two Sub-Agents, but it’s too broad. Plus, frontend and backend capabilities basically still rely on the model itself. In this case, letting Claude Code assign tasks via Task is more reasonable. But you might find it breaks things down into two small features working on both frontend and backend simultaneously, rather than one doing frontend and another doing backend.