Mastering Claude Code: The Sub-agent Pattern

tldr; to invoke sub-agent. Tell Claude: "complete this task, deploy multiple sub-agents, run them in parallel."

Today I discovered sub-agent, and has been using it to speed up the burn rate on my Claude Code MAX plan drastically. 😄

Sub-agent is a built-in feature of Claude Code, but it is a hidden feature. It is basically mini Claude Code instances running inside your main Claude Code session. The mini instances was assigned a task, run in its own context, can use any tools that CC can use, and dies when it accomplish it's task, giving back control the main CC instance (which acts as the orchestrator).

What are the benefits of sub-agents?

There are 2 main benefits:

1. It helps speed up the development speed by a lot.
   
   Sub-agents speed up development by parallelizing tasks. Instead of editing 1 file at a time, multiple sub-agents can be deployed at the same time, each editing its own files.
   Depending on how dependency and granularity of the tasks, I sometimes see 5+ sub-agents being deployed at the same time, each working on it's own task.
   
   
2. It conserves the main CC chat context, reducing the context loss during context compacting.

Problems with Sub-agents

1. Do you have enough tasks?
   
   Using sub-agents require a different way of thinking compared to how one would traditionally interact with CC.
   
   The most common way people use CC is to use it interactively. For example, by asking it to add a new feature, or troubleshoot this error message, etc.
   
   These types of small change doesn't justify the need for sub-agents, whose main benefit is to increase development velocity through parallelism.
   
   Therefore, a new paradiagm of CC'ing is needed:
   
   PLAN -> TASK CREATION -> EXECUTE
   
   In the PLAN phase, you could describe and clarify what you want to achieve. But ask CC to not implement anything.
   
   For example, you will describe a new feature, and have CC break it down into a requirement spec. You review the spec and either approve or revise it by talking with it more.
   
   You should spend a lot of time in the PLAN phase, it is the most important part, even more important than execution.
   
   A trick to use in this part is to use the keyword "ultrathink". This is suggested by Anthropic to increase the thinking phase so that CC can provide more thoughout plan.
   
   Once you are satisified with the plan, you can move on to TASK CREATION.
   
   You can simply prompt it with:
   
   create the tickets necessary to implement the entire plan. ULTRATHINK
   
   CC will create a long list of tasks to work on. These tasks can later be assigned to sub-agents for parallelism.
   
   And for the last part:
   
   go ahead and implement each tickets, deploy sub-agents to help you parallelize tasks. Use tests to help you discover bugs. do not stop until you finish everything.
   
   This will kick start the orchestrator, and it will create sub-agents to help it complete the tasks. Note that it is helpful to have --dangerously-skip-permissions flag on, so that you don't have to confirm each time it wants to edit a file or run a command.
   
   
2. Each sub-agents might overwrite files from each other
   
   You can kind of solve this by asking the orchestrator to add a CLAUDE.md file to instruct the sub-agents to not overwriting each other's files:

I want to remind you that sub agents could compete each other and erase each others change. I think you should create or update the CLAUDE.md file to instruct the sub-agents to be respectful of changes not made by them.

Conclusion

What's my experience so far? I'm very surprised at how quick an entire project with lots of features can be created in such a short amount of time. That being said, there are always bugs that needs fixing after the execution completes. The more token you burn, the more bugs you usually get.

I think bugs can be squashed early on if better testing mechanism is in place. For example, running tsc --noEmit has definitely helped fixing lots of bugs, but being able to run the dev server and actually check the runtime errors would be even more helpful. Albeit hard to implement such a sophisticated testing system.

I do want to give credit to how fast it can create an MVP for you to demo your idea. It's so easy now to take your idea from your head into a demo prototype. And play with it so that you can experience if the idea is actually worth pursuing.