Claude Code subagents: my 4 keepers, 3 I deleted (June 2026)

> Quick Answer (June 2026): I wrote 7 Claude Code subagents in a single week of June 2026. Four now run daily on my own repo. Three are deleted. The keepers are scope-narrow, single-purpose, and have ruthlessly short tool whitelists. The deletes were over-eager wrappers around git grep plus a prompt. Cost per invocation: about $0.003 on Haiku 4.5, $0.04 to $0.18 on Sonnet 4.6. The pattern that mattered: write the YAML last, after you have run the task by hand three times.

Last Tuesday I sat down and wrote seven

This is the field log nobody is publishing. The SERP for "claude code subagents" in June 2026 is a stack of YAML tutorials, a 154-agent community awesome list, and an official Skilljar lesson. All useful. None tell you what to delete.

So that is what this post is. The 7 I wrote, the 4 I kept, the 3 I binned, and the receipts.

What a Claude Code subagent is, in one sentence

A subagent is a named YAML file in .claude/agents/ (project) or ~/.claude/agents/ (user), with its own system prompt and its own allowed tool list, that Claude Code can hand a job to without burning your main context window.

That is the whole pitch. The reason context-window math matters here is well covered in Anthropic's own Claude Code subagents docs, so I will not re-explain it. What I will do is show you what happens after you take that pitch literally for a week.

The 7 subagents I wrote

I will walk through each, briefly.

The 4 keepers

repo-explore (Haiku 4.5, read-only)

This one earned its keep on day one. The job is to answer "where is X defined, where is Y referenced, what files would I touch to change Z." It runs on

Cost per call on this week's repo (Next.js, around 1,400 files): about $0.003. The main session got back roughly 700 tokens instead of the 14,000 it would have consumed doing the search inline. That ratio is the whole reason subagents exist.

name: repo-explore
description: Find files, definitions, references. Return a tight summary. Read-only.
model: haiku-4-5
tools: [Read, Grep, Glob]

I do not even think about invoking it. Claude Code routes to it automatically when I ask "where is the auth middleware."

test-fix (Sonnet 4.6, narrow Bash)

The job is to run the test suite, read the failure, and propose a one-file fix. Sonnet 4.6, allowed Read, Edit, and Bash(npm:*) only. It cannot touch package.json, cannot install new deps, cannot run arbitrary shell.

It worked on 11 of 14 invocations this week. The 3 failures were all the same shape: the failing test was a symptom of a bug in a different file than the one with the test. That is a real limit of the "narrow scope, narrow tools" pattern. The subagent does what you scope it to and no more.

Cost per call: $0.04 to $0.11. Worth it on every green PR.

migration-writer (Sonnet 4.6)

Reads my Prisma schema, the last 5 migrations, and the open feature branch. Proposes a new migration plus a rollback. Then I run it.

The pattern that made this stick: I never let it apply the migration. Tool whitelist excludes prisma migrate deploy. The subagent stops at "here is the SQL, here is the rollback." I am the one who runs it. Same reason airline pilots have a stick that is not connected to the engines.

pr-prep (Sonnet 4.6)

The job is to summarize the diff, propose a PR title, propose a PR body with a "what changed / why / how I tested" structure, and flag anything risky. Reads diff, runs git log, returns text. No write tools. No gh CLI.

I copy-paste the body into

The 3 I deleted

lint-fix (deleted, day 3)

A Haiku 4.5 subagent that read the eslint output and proposed edits. Sounded great. In practice my IDE auto-fixes 95% of lint on save, and the 5% it cannot fix are usually genuine logic decisions, not lint. The subagent kept proposing "auto-fix" patches that the IDE had already auto-fixed.

Net token cost: nonzero. Net value: nothing. Deleted.

naming-critic (deleted, day 4)

I had read the awesome-claude-code-subagents repo, which has 154 community-contributed agents across 10 categories, and I wanted my own opinionated style critic. The agent would scan a diff and complain about variable names.

It complained about good names. Often. The subagent prompt could not encode my taste, and a prompt that encoded my taste was longer than the original PR description. Deleted after two days.

The takeaway: if the subagent prompt would be longer than the thing you would write by hand, do not write the subagent.

meta-planner (deleted, day 5)

The most embarrassing one. An Opus 4.7 subagent that would read my goals.md, scan a few WebFetch sources, and propose what I should work on next. I wanted a Claude minion to plan my week.

It cost $0.18 per invocation, returned plausibly intelligent answers, and was indistinguishable from me opening a notebook and thinking for four minutes. Deleted on Friday.

Three anti-patterns I will not repeat

Anti-pattern 1: writing a subagent for a task you have not done by hand three times. The YAML feels like a substitute for the muscle memory of doing the work. It is not. Do the task three times by hand, notice the repeated steps, then write the agent for the repeated steps only.

Anti-pattern 2: giving a subagent write tools because "it would be easier." Easier is not always better. The pattern that made pr-prep and migration-writer keepers was that they propose, I commit. Every subagent that pushed straight to a tool got deleted within 48 hours.

Anti-pattern 3: using Opus for orchestration. Opus 4.7 is great at thinking. Sonnet 4.6 is great at acting. Haiku 4.5 is great at fetching. The orchestrator that reads files and routes to other agents almost never needs Opus. The cheap-then-deep routing essay on PromptAttic, "Cheap-then-deep routing: Haiku 4.5 first, Opus 4.7 only when it earns it", made me redo this on every keeper, and the bills dropped by about 60%.

Where Claude Code subagents are the wrong tool

Inside an existing repo, on repeat tasks, with narrow scope, a Claude Code subagent is the right tool. Outside that envelope, three honest carve-outs:

1. First-time scaffolding of a new app. If you do not have a repo yet, a Claude Code subagent has nothing to chew on. This is the part of the workflow where an AI app builder like Totalum.app reaches further: it scaffolds a real Next.js + auth + payments + database project on day one, and you can keep the subagents for tomorrow when there is a repo to edit. Different tools, different jobs.
2. Cross-repo or multi-app orchestration. Subagents see one repo at a time. If you are coordinating six client apps as an agency, a comparator like the Builderdex round-up of AI builders for building AI agents is a better starting point than 30 subagent YAML files.
3. The "thousands of subagents overnight" pattern. Claude Code's creator Boris Cherny told Business Insider in May 2026 that his own setup runs thousands of subagents overnight. Cool. Different infra, different problem. Not a small-team default in June 2026.

Most of us are in the middle ground. Four to eight well-scoped subagents per repo. Boring. Effective.

FAQ

How many Claude Code subagents should I write?
Start with zero. After a week of using Claude Code on a real repo, write one for the most repeated task. Add a second only when you have done that second task by hand three times. The "kept vs deleted" ratio for first-time subagent authors I have watched is roughly 1 in 2. Expect to delete half of what you write.

Should I use Haiku, Sonnet, or Opus for a subagent?
Haiku 4.5 for read-only fetch and search. Sonnet 4.6 for the actual editing or fixing work. Opus 4.7 only when the subagent has to reason across many files (rare in practice). The Boris Cherny overnight setup leans on cheap models because the orchestration cost would otherwise be ruinous. PromptAttic's cheap-then-deep routing essay (linked above) is the cleanest framing of the same idea I have read.

Can I give a subagent the Bash tool?
Yes, but whitelist exactly which binaries. Bash(npm:*) is fine for a test fixer. Plain Bash is a footgun. The pr-prep failure I described above was a direct result of giving gh CLI access to an agent that did not need it.

What happens when a subagent returns wrong-shaped output?
This is the failure mode the existing SERP results barely cover. The main session reads the structured summary, treats it as truth, and three turns later you realize the subagent invented a file path that does not exist. The fix is the same fix as for human delegation: ask the subagent for citations or line numbers, and verify before you act on the answer. Adding "must include file:line for every claim" to the system prompt of my read-only agents killed about 80% of the hallucinated-path problems.

Claude Code subagents vs Anthropic Dynamic Workflows?
Anthropic shipped Dynamic Workflows on May 28, 2026, capped at 1,000 subagents per workflow. Dynamic Workflows is for scripting the orchestration declaratively. Subagents are what the workflow calls. Most solo devs do not need Dynamic Workflows yet. Most teams running more than 50 nightly subagents do.

Cursor background agents vs Claude Code subagents?
Different tools, same general space. I wrote a 7-day field log of Cursor background agents on this blog yesterday. The TLDR: Cursor BG agents are queue-of-tasks oriented; Claude Code subagents are context-isolation oriented. Pick the one that matches the bottleneck you actually have. If your bottleneck is "I lose track of what I was doing in a long session," subagents win. If your bottleneck is "I have 23 tickets and want them all opened as PRs by morning," BG agents win.

Can I see your full agents/ folder?
I will publish the 4 keepers as a public gist next week. The system prompts are short. The discipline is in what they do not do.

Are subagents worth it for a solo dev in June 2026?
Yes, with the kept-vs-deleted ratio above. The win is not "more parallelism." The win is "your main session stays usable past hour three." That alone earns its keep on any project bigger than a weekend hack.

P.S. The seven-subagent week started because I read a vibe-coding session log on this blog and felt jealous. Two weeks later I am a delete-three-subagents richer. Worth it.