Claude Code Subagents: The 2 I Actually Kept (2026 Field Log)

For two weeks I stopped doing everything in the main Claude Code window. I pushed the messy work, the searching, the log-reading, the first-pass reviews, onto subagents instead.

My main context stayed clean. My token bill went down. And I learned that most of what people write about subagents misses the part that actually matters.

This is the field log. The two subagents I kept, the frontmatter line that does the real work, and the gotcha that cost me an afternoon.

Quick answer

A Claude Code subagent is a specialized assistant defined as a Markdown file with YAML frontmatter, stored in .claude/agents/ (per project) or ~/.claude/agents/ (all your projects) (subagents docs, 2026). Each one runs in its own separate context window with its own system prompt and its own tool allowlist, then hands back only a summary. After two weeks I kept exactly two: a read-only explorer that protects my main context, and a reviewer scoped to Read plus Grep. The thing nobody stresses enough: the description field is not a label, it is the prompt that decides when Claude delegates. Write it wrong and your subagent never fires, or fires constantly.

What a subagent actually is

Strip away the marketing and a subagent is three things in one file: a name, a description that triggers delegation, and a system prompt (the Markdown body). Optionally a tool allowlist and a model.

---
name: explorer
description: Searches the codebase to answer "where is X" and "how does Y work". Use proactively for any multi-file lookup before editing.
tools: Read, Grep, Glob
model: haiku
---
You are a codebase explorer. Find the relevant files, read only what you need,
and return a short answer with file paths and line numbers. Do not edit anything.

Drop that in .claude/agents/explorer.md and it is live within a few seconds. No restart, no wizard. As of recent versions the /agents command does not even open a creation UI anymore, it just tells you to write the file.

The key mechanic: each subagent runs in its own context window. It reads fifty files, burns through its own tokens, and returns one paragraph to your main conversation. The search noise never touches your primary context. That is the whole point.

The two I kept

1. A read-only explorer

This is the one that earned its keep on day one. Any time I need to answer "where does this get validated" or "how does the auth flow work," the explorer does it in its own window and comes back with paths and line numbers.

Two frontmatter choices make it work:

• tools: Read, Grep, Glob. No Edit, no Write, no Bash. It physically cannot change anything, so I never worry about a research pass mutating a file.
• model: haiku. Searching is cheap cognitive work. Routing it to a faster, cheaper model dropped the cost of exploration without hurting the answers.

Why it stuck: my main window used to fill up with grep output I would never read again. Now it does not. I get more real work done before a compaction.

2. A reviewer that cannot touch the code

My second keeper reviews a diff and reports problems. Scoped to Read, Grep, model left on the default. Its whole job is to be a skeptical second pair of eyes that returns a list, not a patch.

---
name: reviewer
description: Reviews a diff for correctness bugs and risky changes. Use after a feature is written, before committing.
tools: Read, Grep
---
You review code changes. Report concrete bugs with file and line, ranked by
severity. Do not fix anything. If you find nothing real, say so plainly.

Why it stuck: separating "write the code" from "criticize the code" into two contexts genuinely surfaces more. The reviewer has not seen my reasoning, so it does not rubber-stamp it.

The frontmatter line that does the real work

Everyone obsesses over tools and model. The line that actually decides whether a subagent is useful is description.

Claude reads the description to decide when to delegate. It is a prompt, not a caption. Compare:

• Weak: description: Code reviewer. Vague. Claude almost never delegates to it because it does not know when it applies.
• Strong: description: Reviews a diff for correctness bugs. Use after a feature is written, before committing. Now there is a trigger condition. Delegation happens when it should.

The phrase "use proactively" in a description measurably increases auto-delegation. If your subagent never fires, the fix is almost always the description, not the body.

The gotcha that cost me an afternoon

I created ~/.claude/agents/ for the first time in the middle of a session, added a subagent, and spent an hour wondering why Claude ignored it.

The reason: if the ~/.claude/agents/ directory did not exist when the session started, a running session does not detect it being created (subagents docs, 2026). Editing an existing subagent file is picked up within seconds. Creating the whole directory for the first time is not. Restart Claude Code once and it works forever after.

Two smaller traps worth knowing:

• Context does not come back. A subagent returns a summary, not its transcript. If you need the detail it saw, tell it in the system prompt to return that detail. You cannot go fishing in its context afterward, it is gone.
• Name collisions resolve quietly. Two files with the same name under the same .claude/agents/ tree and only one loads, chosen by read order. If a subagent behaves like a different one, check for a duplicate name before you debug anything else.

How I would start

Do not build a fleet. I tried, and I use two.

Write one read-only explorer with tools: Read, Grep, Glob and model: haiku. Live with just that for a few days and watch how much cleaner your main context stays. Add a reviewer when you want a second opinion that has not seen your work. That is a complete, useful setup.

When you do want a subagent to enforce a rule every single time rather than only when Claude chooses to delegate, that is a job for a hook, not a subagent, and I wrote up the hooks I actually kept separately. For the MCP servers I hand these subagents, see the ones I actually run.

P.S. My explorer once confidently returned the wrong file because I never told it to verify the match. A subagent is only as careful as its system prompt. Write the boring instructions.