How to use Claude Code subagents to parallelize development

As someone who's built a project in this space, this is incredibly unreliable. Subagents don't get a full system prompt (including stuff like CLAUDE.md directions) so they are flying very blind in your projects, and as such will tend to get derailed by their lack of knowledge of a project and veer into mock solutions and "let me just make a simpler solution that demonstrates X."

I advise people to only use subagents for stuff that is very compartmentalized because they're hard to monitor and prone to failure with complex codebases where agents live and die by project knowledge curated in files like CLAUDE.md. If your main Claude instance doesn't give a good handoff to a subagent, or a subagent doesn't give a good handback to the main Claude, shit will go sideways fast.

Also, don't lean on agents for refactoring. Their ability to refactor a codebase goes in the toilet pretty quickly.

It was my understanding that the subagents have the same system prompt. How do you know that they don’t follow CLAUDE.md directions?

I’ve been using subagents since they were introduced and it has been a great way to manage context size / pollution.

A few youtubers have done deep dives on this, monitoring claude traffic through a proxy. Subagents don't get the system prompt or anything else, they get their subagent prompt and whatever handoff the main agent gives them.

I was on the subagent hype train myself for a while but as my codebases have scaled (I have a couple of codebases up to almost 400k now) subagents have become a lot more error prone and now I cringe when I see them for anything challenging and immediately escape out. They seem to work great with more greenfield projects though.