Claude Code Subagents in Production: When They Help, When They Hurt

Every few weeks someone in the r/ClaudeAI threads asks the same thing: “What’s your best way to actually use Claude Code subagents?” The replies are always the same — a copy-pasted config, a link to Anthropic’s course, a screenshot of five specialist agents with clever names. Nobody shows you the part that matters: a real subagent workflow doing real work, end to end, with the receipts to prove it paid off.

That’s what this post is. I run a fleet of autonomous businesses on Claude Code — this brand you’re reading is one of them — and subagents are wired into the pipeline that researches, writes, and ships content while I’m asleep. So I’m going to give you the honest operator’s view: what subagents are, the config that actually matters, how to invoke them, a real workflow from my own stack, and — the part everyone skips — when subagents quietly hurt you instead of helping.

No fluff, no “10x your productivity” nonsense. Just what works, what doesn’t, and how to tell the difference.

What Claude Code Subagents Actually Are (vs Just Prompting Harder)

A subagent is a separate Claude instance your main session can spawn to handle a scoped task. Think of it as hiring a specialist for one job: it runs in its own context window, with its own system prompt, its own tool permissions, and it hands back only a result — not the whole messy transcript of how it got there.

That last part is the entire point, and it’s the part most guides bury. When your main agent delegates “go read these twelve files and tell me which ones touch authentication” to a subagent, the subagent burns its own context reading all twelve files. Your main session never sees that noise. It gets back a clean two-sentence answer and keeps its context window lean for the work that actually needs continuity.

The clearest mental model I’ve found: your main session is a project manager with a limited desk. Everything it reads stays on that desk — every file, every search result, every tangent — until the desk is buried and the PM starts forgetting what it was doing. A subagent is a colleague you send to the archive room. They dig through the boxes, come back with one sticky note, and your desk stays clear. You didn’t get a smarter PM; you got one who isn’t drowning in paper. Once that clicks, you stop asking “what cool agents can I make” and start asking “what’s cluttering my desk that I can send away.”

So the honest framing isn’t “subagents make Claude smarter.” They don’t. A subagent is the same model you’re already talking to. What they change is where the tokens go. You’re trading a little coordination overhead for a lot of context hygiene. That’s a great trade for some tasks and a terrible one for others — which is exactly the distinction we’ll draw a line under later.

If you’ve read my breakdown of everything Claude Code actually gives you, subagents sit alongside slash commands, hooks, and MCP as one of the four levers that separate people who “use Claude Code” from people who operate it.

Anatomy of a Subagent: The Config That Actually Matters

A subagent is just a Markdown file with frontmatter, dropped in .claude/agents/ (project-level) or ~/.claude/agents/ (global). Here’s a stripped-down real one:

---
name: doc-scout
description: Read-only researcher. Use PROACTIVELY to locate code, configs,
  and naming conventions across the repo. Returns findings, never edits.
tools: Read, Grep, Glob
model: haiku
---

You are a read-only search agent. Given a question, sweep the codebase and
return: (1) the exact files and line ranges that answer it, (2) a two-sentence
summary. Do NOT read whole files when an excerpt will do. Do NOT propose edits.

Four fields carry almost all the weight, and getting them wrong is why people’s subagents feel useless:

• description — this is not documentation, it’s the routing signal. Claude reads it to decide when to auto-delegate. Vague descriptions (“helps with code”) never get called. Put the trigger in the description: “Use PROACTIVELY when reviewing a diff.” The word “proactively” genuinely nudges delegation.
• tools — scope them down hard. A research subagent that can only Read, Grep, and Glob physically cannot wander off and edit a file. Least-privilege isn’t just security theater here; it makes the subagent’s behavior predictable.
• model — you do not need Opus to grep a repo. Point cheap, high-volume subagents at a smaller model and save the expensive one for reasoning. This single line is the difference between a pipeline that’s affordable to run daily and one that isn’t.
• the system prompt — the body of the file. Be specific about what it returns and what it must never do. A subagent that returns a tidy structured result is worth ten that dump a wall of text back into your main context.

Two organizational notes that save headaches later. Project-level agents in .claude/agents/ ship with the repo, so your whole team (or your whole fleet of containers) inherits the same roster — that’s how I keep ten brands behaving consistently. Global agents in ~/.claude/agents/ are your personal toolkit that follows you everywhere. When a name collides, project wins. Keep the roster small and named for jobs, not personalities: doc-scout and dedup-checker tell Claude (and future you) exactly when to reach for them; “Alfred” and “Jarvis” tell it nothing.

The mistake I see constantly: people write a subagent with the full tool belt and a two-line prompt, then wonder why it behaves like a slightly worse version of their main session. The constraints are the value.

How to Invoke Subagents: Auto-Delegation vs Explicit Calls

There are two ways a subagent gets used, and knowing which one you want changes how you write the config.

Auto-delegation is when Claude decides on its own to hand a task to a subagent, based on that description field. You just work normally — “review the changes on this branch” — and if a code-reviewer subagent exists with a matching description, Claude routes to it. This is magic when it works and maddening when it doesn’t, and the difference is entirely down to how sharp your descriptions are.

Explicit invocation is when you name it: “Use the doc-scout subagent to find every place we read the config file.” No guessing. You get determinism at the cost of having to remember your roster. In practice I lean explicit for anything in a scripted pipeline and let auto-delegation handle the interactive, exploratory work.

The nuance nobody mentions: a subagent starts with a clean context every time. It does not see your conversation history unless you put it in the invocation. That’s a feature for isolation but a trap if you assume it “knows what we were just talking about.” It doesn’t. Brief it like a contractor walking in cold — because that’s exactly what it is.

A concrete auto-delegation example from my own setup: I never type “review this.” I just finish a change and say “check the diff on this branch.” Because my code-reviewer subagent’s description literally reads “Use PROACTIVELY to review the current diff for correctness and reuse issues,” Claude routes to it without being told. The first week I ran it, the description said only “reviews code” — and it never fired once. Same subagent, one sentence rewritten, completely different behavior. That’s how much the description carries.

You can also fan several subagents out in parallel — send multiple delegations in one turn and they run concurrently. That’s where the real wall-clock savings live, and also where the coordination overhead starts to bite. Hold that thought.

A Real Claude Code Subagents Workflow From My JonOps Content Pipeline

Here’s the part the SERP is missing. Every guide stops at “here are five personas you could make.” Nobody shows a subagent actually earning its keep. So here’s a real one from JonOps — the system that runs this brand.

When a blog post gets written, the orchestrator (the main Claude Code session) doesn’t do everything itself. It delegates:

1. A research subagent (cheap model, Read/Grep/web tools only) sweeps the SERP and competitor pages for the target keyword and returns a structured brief: what’s covered, what’s missing, average word count. It reads roughly 40KB of competitor markdown so the main session never has to.
2. The orchestrator takes that clean brief — a few hundred tokens, not 40KB — and writes the draft itself, because writing needs continuity and voice that you don’t want to hand off.
3. A dedup subagent checks the live site for cannibalization before anything publishes, and returns a single verdict: safe, or here’s the conflicting URL.

The receipts: the research step alone would blow 30–50K tokens of the main context if I did it inline. Pushed to a subagent, the main session stays under budget and can hold the entire post structure in working memory through the whole write. The dedup check has caught two near-duplicate posts before they went live this quarter — each one would have split ranking signal and quietly cost me traffic. That’s not a demo. That’s a subagent preventing a real, measurable mistake on a live site.

Notice what I did not delegate: the actual writing. That’s deliberate, and it’s the lesson. Subagents are for bounded, context-heavy, low-continuity work — research, search, verification. The creative through-line stays with the orchestrator. If you want the broader orchestration philosophy behind this, I go deep on it in Claude Code agent teams: when parallel agents beat one.

If you’d rather have a pipeline like this built for you instead of assembling it yourself, that’s literally the work I do — done-for-you automation builds that ship subagent systems into your business.

When Subagents Hurt: Context Bloat and Coordination Overhead

This is the section every other guide leaves out, and it’s the one that’ll save you the most pain.

Subagents are not free. Every delegation has a cost the tutorials never mention:

• Coordination overhead. The orchestrator has to write the brief, spawn the subagent, wait, and parse the result back. For a trivial task — “rename this variable” — that round-trip costs more tokens and more wall-clock time than just doing it. Delegating a five-second job is pure waste.
• The result still lands in your context. Isolation protects you from the process, not the output. If your subagent returns a 5,000-word dump instead of a summary, you’ve moved the bloat, not removed it. A chatty subagent is worse than no subagent.
• Lost shared context. Because subagents start cold, tightly-coupled work — where step two depends on the reasoning from step one — gets clumsy. You end up re-explaining state across the boundary, and things fall through the cracks.
• Parallel ≠ faster if they collide. Fan out ten subagents that all want to edit the same files and you’ve built a merge conflict generator. Parallelism only pays when the work is genuinely independent.

Put a number on it so the trade is concrete. Say a review subagent reads a 30-file diff — that’s easily 40K tokens of reading. Done inline, that 40K sits in your main context for the rest of the session, crowding out the actual work and inching you toward a compaction you didn’t want. Done in a subagent, those 40K tokens live and die in the subagent’s window; your main session pays only for the ~300-token verdict that comes back. Now flip it: delegating “rename foo to bar” costs you a brief, a spawn, a wait, and a parse — call it a few hundred tokens and several seconds — to save a single edit you could’ve made instantly. The first trade is a steal. The second is a tax you’re paying for the aesthetic of having a subagent. Learn to feel the difference and you’ve learned 80% of using them well.

My rule of thumb after running these daily: reach for a subagent when a task is context-heavy, bounded, and low-continuity — big reads, wide searches, independent verification. Keep it in the main session when the work is small, tightly-coupled, or needs the thread’s memory. When you catch yourself delegating something you could’ve done in two tool calls, stop. That’s the tell that you’re cargo-culting subagents because a blog post told you to have five of them.

Subagents vs Agent Teams vs One Big Agent

Three patterns get blurred together constantly. Here’s the clean split:

• One big agent. A single session doing everything in one context. Best for tightly-coupled work with a strong creative or logical through-line — writing, refactoring a module, anything where losing the thread costs you. Simplest to reason about. The default, and often the right one.
• Subagents. A main session that delegates scoped, isolated tasks to specialists and gets structured results back. Best when you want context hygiene without giving up central control. The orchestrator stays the brain; subagents are its hands for the dirty, context-heavy jobs.
• Agent teams. Multiple peer agents working in parallel on a larger problem, coordinating with each other rather than reporting to one boss. Best for genuinely parallelizable work at scale — sweeping a huge migration, reviewing a big diff across many dimensions at once. More power, more token burn, more ways to go wrong.

The progression is about how much coordination you’re willing to pay for. One agent: none. Subagents: a little, in exchange for context isolation. Agent teams: a lot, in exchange for real parallelism. Most people should live in the first two and only reach for agent teams when the problem genuinely can’t fit one context and can’t be handled by a boss-and-helpers shape.

I laid out exactly when parallel teams beat a single agent — and when they’re just expensive theater — in the agent teams operator guide. And if you’re still deciding which coding agent to build all this on, my Claude Code vs Codex breakdown covers the platform choice. Once your fleet is running, running it from your phone is the natural next step.

Claude Code Subagents FAQ

What are Claude Code subagents?

Separate Claude instances your main session spawns to handle scoped tasks. Each runs in its own context window with its own prompt, tools, and permissions, and returns only a result — keeping your main session’s context clean.

How do I create a subagent?

Drop a Markdown file with frontmatter in .claude/agents/ (project) or ~/.claude/agents/ (global). Set name, a routing-friendly description, a scoped tools list, an optional model, and a specific system prompt in the body.

Are subagents free?

No — they consume tokens like any Claude call. The win is where those tokens go: context-heavy work happens in the subagent’s window instead of polluting your main session. Point high-volume subagents at a cheaper model to keep costs sane.

Can I run multiple subagents in parallel?

Yes. Send several delegations in one turn and they run concurrently. This only pays off when the tasks are genuinely independent — parallel subagents editing the same files just manufacture conflicts.

What’s the difference between subagents and agent teams?

Subagents report to one orchestrator that stays in control. Agent teams are peer agents coordinating with each other on a larger, parallelizable problem. Subagents = boss and helpers; agent teams = a crew. Start with subagents; graduate to teams only when the problem truly needs it.

When should I NOT use a subagent?

Skip them for trivial tasks (the round-trip costs more than the work), tightly-coupled steps that need shared context, and any session where you’re tight on token budget and the delegation won’t actually save context.

Final Thoughts: Use Subagents Like a Foreman, Not a Fanboy

The people getting real leverage out of Claude Code subagents aren’t the ones with the most agents. They’re the ones who delegate the right work — big, bounded, context-heavy jobs — and keep the connective tissue in one place. Treat your orchestrator like a foreman: it holds the plan, and it sends specialists to do the heavy, isolated lifting.

Start with one. Give a research or dedup subagent a razor-sharp description, lock down its tools, point it at a cheap model, and watch how much cleaner your main session runs. Then add the next one only when a real task demands it. That’s how you end up with a pipeline that ships work while you sleep — instead of a folder full of clever configs that never get called.