Using Subagents to Improve Claude Code Results: A Step-By-Step Guide – Software the Hard way

Skip to content

RP

Uncategorized

2026-07-13

31 Minutes

Unless you’ve been living under a rock, you’re well aware of AI agents like Claude Code and Codex revolutionizing software development. These tools are undoubtedly easy to learn, but are also hard to master. There are a ton of nuances and best-practices that can help you get much better results from your coding agent.

As someone who can be an obsessive perfectionist, I’ve spent (too) many hours reading up on and experimenting in this area. There are a ton of abstract ideas floating out there which I’ve learnt a lot from. Ideas like spec-driven-development, RPI, etc. But I’ve also noticed a dearth of step-by-step guides that show someone how to actually implement these abstract ideas. Hence why I decided to write this blog post.

Disclaimer: I just started using Claude Code six months ago, and am still learning these best practices as well. I’m sure this guide has tremendous room for improvement, and will also become woefully out-of-date in the near future when new models and agents come out. I would love to hear your ideas on how to improve upon my setup.

Guiding Principles

Before we get into the actual step-by-step guide, let’s briefly discuss the guiding principles behind each step, and why it enables your agent to produce better results. Understanding these principles will help you make better use of coding agents in your day-to-day work.

Context Use Minimization

Each session in a coding agent has a context window. Every time you send a prompt to the agent, every time the agent does anything, it uses up a bit more of this context window. This is eerily analogous to your own cognitive load while working on a task. Just like with your own cognitive load, coding agents perform far worse when their context window starts filling up. Hence why you should always strive to keep your context window usage as low as possible.

Of course, this is easier said than done. If you simply /clear your context window before every prompt, it will be like having a conversation with someone who doesn’t remember anything you said one minute ago. Agents need useful context in order to do a good job. So you need to find ways to minimize their usage of the context window, while still keeping the stuff that is important.

One extremely simple application of this principle: always /clear your context window before starting work on a new unrelated task. This is a good start, but there is also a lot more you can do.

Sub-Agents

The next best thing you can do is to use subagents (or independent agents) – each of which has its own independent context window. And delegate chunks of work to each subagent.

Imagine if you have a large codebase, and your agent needs to find all information relevant to fooBar. If your main agent simply starts grepping and reading your codebase in order to find the information it needs, it will rapidly start filling up its context window with a ton of useless information. This violates our earlier principle: we want to keep our context window usage as low as possible.

To achieve our goal, we can instead spin up a subagent whose sole job is to find all information relevant to fooBar, and send this relevant information back to the main agent. This way, all the useless information will only bloat that subagent’s context window. And the only information that lands in the main agent’s context window is the filtered and highly relevant information that was surfaced by the subagent.

This same principle can be applied not just to "codebase grepping", but to the entire software development workflow. For any significantly sized work, instead of doing it all on a single agent, you will get better results if you break up the work into multiple chunks, and assign each chunk to a different subagent.

Intermediate Artifacts

Of course, there is a downside to dividing up work among numerous subagents – the risk of misinterpretation and information loss when agents are sending results to one another. Anyone who has played a game of telephone knows how dangerous this risk is.

To mitigate this, it is helpful to have each agent output its result in a text file. This way, other agents can read the relevant file directly, instead of relying on second-hand or third-hand information. As a byproduct, these text files are also great for us humans to audit the work that each agent did, and root-cause the source of any errors.

Fresh Perspectives

It is tempting to think of AI agents as being consistent. After all, that’s how most computer systems operate. But AI agents are different. Give the same agent the same instructions on two different occasions, and it can produce two completely different results. Ask an AI agent to critique the results that it just spat out a minute ago, and it may tell you all the reasons why its own results are wrong.

This can certainly be...