Subagents are a popular capability of Claude Code, which allow you to get specialized advice/aid during your dev sessions. Here’s what they are, how to define them, and a few starter subagent personas.
What are subagents?
Claude Code’s subagents are simply Claude instances with different areas of expertise. Instead of asking one generalist agent to do everything (e.g. classic Claude Code), you create specialists.
Within a Claude Code session, you can invoke these subagents for tasks that might require more specialization, and thanks to their system prompts, you’ll see better results. Subagents also benefit from having their own context windows, so they only ingest info relevant to their tasks. You’ll save tokens, and see less of the “output degradation” that happens when the context window fills up during a long Claude session.
How to add subagents to Claude Code
Claude Code makes it simple to write/customize/generate your own subagents.
First, make sure you’re using CC’s latest version (or at least ≤ 1.0.60):
claude --version
You can upgrade by running:
npm update -g @anthropic-ai/claude-code
Start a CC session and run the /agents slash command. From here, you’ll be able to define a subagent at the project or user level. (We recommend starting out with project-level subagents, so you can customize them to use project-specific tools and domain knowledge).
Claude will prompt you whether you want to create the subagent with Claude’s help. This is a good move, since CC will use the context from your project to customize an agent to your needs. You’ll write a summary of its responsibilities and Claude will fill out the rest. Agents are defined in natural language, but you’ll want to use good prompt engineering practices to get the best results.
Once you’ve finished the setup process, you can open up the resulting Markdown file and tweak it. For example, this is a snippet of the markdown config that Claude generated when asked to create a technical docs proofreader:
---
name: proofreader
description: Use this agent when you need to proofread and correct grammar in markdown files, especially technical documentation or blog posts. Examples: <example>Context: User has written a technical blog post about API development and wants it reviewed before publishing. user: 'I just finished writing a blog post about REST APIs. Can you review it for grammar and formatting?' assistant: 'I'll use the proofreader agent to review your blog post for grammar, formatting, and technical accuracy.' <commentary>Since the user wants proofreading of technical content, use the proofreader agent to handle grammar correction and markdown formatting review.</commentary></example> <example>Context: User has updated documentation with technical content that needs review. user: 'I updated the README with new installation instructions. Could you check it over?' assistant: 'Let me use the proofreader agent to review your README for clarity, grammar, and proper markdown formatting.' <commentary>The user wants documentation reviewed, so use the proofreader agent to ensure proper grammar and markdown syntax.</commentary></example>
model: sonnet
color: orange
---
You are an expert technical proofreader and grammar specialist with deep knowledge of software development terminology, markdown syntax, and technical writing conventions. You excel at maintaining clarity while preserving the author's intended casual tone and technical accuracy.
In the Markdown frontmatter, you can customize the name, description, choose your preferred Claude model, and set the agent’s UI color. Optionally, you can grant it access to only select tools (read, write, grep, etc) instead of all by default.
In the content section, you’ll be able to go into more detail on what the agent should know, and how it should respond to certain scenarios. Here you may want to list out workflows and define rules.
What subagents do I need?
Think about what tasks you use Claude Code for. They probably can be boiled down into a few roles. Which agents you’ll want really comes down to personal preference, but here are a few that we’ve found useful.
Tip: You can paste these descriptions into CC during agent creation.
The System Architect
This is a big-picture agent that advises you and nitpicks your design patterns. Use it to help you think through large features. It chimes in when you drift towards an anti-pattern.
It’s well-versed in the frameworks your app uses, and has plenty of expertise in systems at scale.
This agent will be helpful when you ask it about optimizing logic, database choices, and why your monolith might need to become microservices.
The Code Reviewer
This is a very thorough agent that nitpicks every PR to find security holes, performance issues, unresolved comments, etc. This agent should be well-versed on optimal algorithms (e.g. critiquing your nested loops), but also understand that good code is elegant, not complicated.
It has a sophisticated understanding of code syntax and style. This agent can act as one (of your many) checks and balances against LLM hallucinations.
The Debugger
This debugging agent is methodical and patient. It traces your internal docs to run your code properly, and then ingests/analyzes logs to find the point of failure. It understands your services enough to recognize where a bug is coming from, and might recognize some common failure patterns.
This agent works best alongside a dev, and asks questions to help it solve the problem (e.g. “when did this last work?”, “what changed recently?").
The DevOps Engineer
This agent understands your deployment process + pipeline. It knows Docker, Kubernetes, and your CI/CD framework. It can help proofread your config files, and cross-reference with logs when you’re not getting the expected behavior. You should be able to ask it how to optimize/implement best practices, and it should confidently answer from its glossary of DevOps patterns.
Creating smart personas
What you need in a subagent will become more clear to you as you use Claude Code. Think about which tasks you’d like more sophisticated help from Claude during. Think about which parts matter less to you.
Even though subagents are specialized and generally perform better for domain-specific tasks than stock Claude, they’ll still have their blind spots and weaknesses. Engineers have reported strong results when including these weaknesses in their subagent system prompts. Also important to only throw each subagent the tasks that are in its wheelhouse.
In your system prompt, it helps to instruct your agent to “be honest” or “be critical” or “be realistic”. Many LLM system prompts default to an agreeable demeanor, so you’ll want to be sure yours overrides this.
You can also suggest that the subagent checks your reasoning with follow-up questions (e.g. “why do you want to make this change?”, “how do you know this is the root of the problem?"). Making subagents a little argumentative and opinionated will protect you from bad design decisions.
Your subagent team
In the beginning, you’ll want to define and deploy your subagents one at a time. Get used to how they work, and how you can use them to get better results. You’ll probably max out at about 3 or 4 subagents total; after that your own productivity may drop.
You may rest on stock Claude Code for most of your general programming tasks, whereas your subagents will pick up anything more senior-level.
Using Claude Code? Give your agents ephemeral environments. They can deploy the code they write, pull logs, find + fix bugs, all with little-to-no human intervention. Try it free for 30 days.
