Claude Code Subagents: How I Stopped Context-Switching and Started Delegating

If you've been using Claude Code for a while, you've probably hit the wall. Not the "I can't figure this out" wall. The "wait, why is Claude confused about what we were doing?" wall.

Claude Code subagents are how you fix that. They're specialized AI assistants that handle specific tasks without polluting your main conversation. I've been using them for a few months now, and they've genuinely changed how I work.

Here's everything you need to know to start using them.

//The Problem Subagents Solve

Here's what happens without subagents:

You're building a feature. You ask Claude to explore the codebase, find where authentication is handled, understand the patterns. It reads a bunch of files, gives you a summary. Great.

Then you start implementing. You ask it to write some code. But now the context window is stuffed with all that exploration output. Claude's responses get slower. It starts "forgetting" things you discussed earlier. The quality drops.

You're paying for context you don't need anymore.

Subagents solve this by isolating tasks. When Claude needs to explore your codebase, it spins up an Explore agent. That agent does its thing, returns a summary, and disappears. Your main conversation stays clean.

It's like having junior devs you can delegate to. "Hey, go figure out how auth works and report back." They do the legwork. You stay focused on the big picture.

//What Are Claude Code Subagents?

Claude Code subagents are pre-configured AI assistants that Claude can delegate tasks to. Each one:

• Has a specific purpose (code review, debugging, exploration)
• Runs in its own context window
• Can be restricted to certain tools
• Returns results to the main conversation

The key insight: subagents don't share context with your main conversation. This is a feature, not a bug. It means they can do messy, exploratory work without cluttering up your primary thread.

Claude Code delegates automatically based on what you're asking. You say "find all the places we handle errors," it spins up the Explore agent. You say "review the changes I just made," it can use a code reviewer agent.

Or you can invoke them explicitly: "Use the debugger agent to figure out why this test is failing."

//Built-in Subagents You Already Have

Claude Code ships with three subagents out of the box. You don't need to configure anything.

Explore Agent

This is the workhorse for codebase navigation. Fast, lightweight, read-only.

When you ask questions like "where is X handled?" or "how does Y work?", Claude delegates to the Explore agent. It uses Glob, Grep, and Read to find what you need without executing anything dangerous.

The Explore agent runs on Haiku for speed. It's designed to be quick and cheap. Perfect for "find me the file where..." type questions.

Plan Agent

Used in plan mode when Claude needs to research before proposing a solution.

You enable plan mode when you want Claude to think before acting. The Plan agent does the reconnaissance: reads files, searches patterns, understands the current state. Then it returns findings to help build your implementation plan.

General-Purpose Agent

The heavy hitter. This one uses Sonnet and has access to all tools.

For complex, multi-step tasks that need both exploration and modification, Claude delegates here. Unlike Explore, it can actually make changes. It's basically a full Claude Code session running as a subtask.

//Creating Your Own Subagents

The built-in agents are solid, but the real power comes from custom subagents tailored to your workflow.

The File Format

Subagents are Markdown files with YAML frontmatter. Drop them in .claude/agents/ for project-specific agents or ~/.claude/agents/ for global ones.

Basic structure:

---
name: my-agent
description: When to use this agent
tools: Read, Grep, Glob
model: sonnet
---

Your system prompt here. Tell the agent what it does,
how it should approach problems, what to focus on.

The description field is crucial. Claude uses it to decide when to delegate. Be specific about when this agent should be used.

Project vs User Agents

Project agents (.claude/agents/) only work in that project. Perfect for repo-specific workflows. Commit them to version control so your team benefits.

User agents (~/.claude/agents/) work everywhere. Good for personal productivity patterns you use across projects.

Project agents take precedence if names conflict.

//Subagents That Actually Help

Here are the custom subagents I actually use. Not theoretical "you could build this" stuff—agents that have saved me real time.

Code Reviewer

Runs automatically after I make significant changes. Checks for obvious issues before I even think about committing.

The key is the description: "Use proactively after code changes." Claude sees this and automatically triggers a review when I've been editing files.

I limit its tools to read-only operations. It shouldn't fix things, just report. That's intentional—I want to understand and approve fixes myself.

Debugger

When something breaks, I don't want to explain the whole situation to Claude. I want it to investigate.

The debugger agent is configured to: look at error messages, check recent changes, form hypotheses, and add strategic logging. It returns a diagnosis with evidence.

This one gets Edit access because sometimes adding a console.log is the fastest path to understanding. But it's trained to explain what it's doing, not just silently fix things.

Test Runner

This one watches for code changes and proactively runs relevant tests.

The trick is in the prompt: "When you see code changes, identify which tests are affected and run them. If they fail, analyze the failures and suggest fixes."

Having an agent that automatically runs tests after every significant edit has caught so many bugs before they became problems.

//How I Actually Use Them

My typical workflow:

1. Start a feature. I describe what I want to build. Claude might use the Plan agent to research the codebase first.

2. Implement. As I'm working, Claude handles the heavy lifting. If it needs to explore, it delegates to Explore. My main context stays clean.

3. Review. After significant changes, the code reviewer agent automatically runs. I see its feedback in the main conversation.

4. Debug. If something breaks, I tell Claude to use the debugger agent. It investigates and reports back.

The pattern is: main conversation for decisions, subagents for legwork.

I'm not constantly managing agents. Claude decides when to delegate based on the descriptions I've written. The experience feels seamless—I just work, and the right agent activates when needed.

//When Subagents Don't Make Sense

Not everything needs an agent.

Quick questions: If I just need to know what a function does, asking directly is faster than spinning up an agent.

Simple edits: Single-file changes where I know exactly what I want don't need delegation overhead.

Exploratory conversations: When I'm thinking out loud and want Claude to engage, subagents would just fragment the discussion.

Context-dependent work: If the whole conversation history is relevant to the current task, a subagent (with its fresh context) would miss important nuance.

The rule I use: if the task is self-contained and doesn't need the conversation history, it's a good candidate for a subagent. If it needs context from our discussion, keep it in the main thread.

//Tips From Real Usage

Write aggressive descriptions. If you want Claude to proactively use an agent, say "PROACTIVELY use this when..." in the description. Be explicit about triggers.

Limit tools intentionally. A code reviewer shouldn't have Write access. A debugger probably needs Edit. Think about what each agent actually needs and nothing more.

Start with built-ins. The Explore agent handles 80% of what I used to do with custom search agents. Don't over-engineer.

Check project agents into version control. Your teammates should benefit from agents you've refined.

Use inherit for model. Unless you have a specific reason to pin a model, model: inherit keeps your agents consistent with whatever you're running in your main session.

Iterate on prompts. Your first agent prompt will be mediocre. Refine it as you see what works. The /agents command lets you edit agents quickly.

//Verdict

Claude Code subagents solve a real problem: context pollution. When your AI assistant is doing exploratory work, you don't want that exploration cluttering your main conversation forever.

Subagents give you:

• Cleaner context. Delegate messy searches to specialized agents.
• Better focus. Main conversation stays on high-level decisions.
• Reusable workflows. Build agents once, use them across sessions.
• Team knowledge. Project agents codify your team's best practices.

Should you use them? If you're doing serious work with Claude Code—not just quick questions but actual development sessions—yes. The built-in agents help immediately. Custom agents take some setup but pay dividends.

The mental model shift is: you're not just chatting with Claude anymore. You're orchestrating a team of specialized assistants. Each one handles what it's good at. You stay in the conductor's seat.

That's a better way to work.

Now go build something.