Set Up Claude Code Subagents: Three, Not Forty-Seven

Summary:

1. Install three Claude Code subagents (planner, coder, reviewer) in .claude/agents/, not a 47-specialist library.
2. Each file is YAML frontmatter plus a system prompt: name, description, scoped tools, and a model.
3. The planner runs on your main thread and dispatches the two workers, because subagents cannot spawn subagents.
4. Bonus: a “read before you install” check that catches the most common scoping mistake in community agent files.

You spawned a few Claude Code subagents, watched them step on each other, and quietly went back to the chat box. The fix is not more agents. It is three. A planner that breaks the work down, a coder that makes the change, and a reviewer that checks it. You can ls .claude/agents/ and see exactly three files doing exactly three jobs.

How many Claude Code subagents should you actually run?

Three. A subagent is a fresh, isolated context window that does one focused job and returns a summary to whoever dispatched it. One subagent is not enough separation, because a single agent planning, coding, and reviewing in the same window is just a verbose main session with extra steps. Forty-seven is the failure mode the most-quoted Reddit thread on this names: “Everyone’s making these massive subagent libraries with 47 different specialists and wondering why their code still sucks.” Three is the number where the responsibility boundary is sharp enough to debug (the planner picked the wrong file, the coder skipped the test, the reviewer was too soft) and small enough to fit in your head.

Run this on your own setup right now:

ls .claude/agents | wc -l

If that number is in the double digits, you have a library, not a stack. The three roles, one line each:

• planner — reads the task, names the files to touch and the boundaries, dispatches to coder then reviewer.
• coder — takes the plan, makes the edit, runs the named test, returns what changed.
• reviewer — reads the diff against the plan, confirms nothing outside scope moved, returns pass or fail.

What goes in the three subagent files?

A subagent file is YAML frontmatter plus a system prompt. Two fields are required: name (lowercase and hyphens) and description (the string Claude reads to decide when to delegate). Add tools to scope access and model to pick the engine. Drop these three into .claude/agents/.

# .claude/agents/planner.md
---
name: planner
description: Breaks work down and orchestrates. Names the files to touch and the boundaries, then dispatches to coder and reviewer.
tools: Read, Grep, Glob, TodoWrite
model: opus
---

# Planner
Read the task, glob for related files, write a 5-line plan (files changed, what changes, what does not, test to run, rollback), then dispatch.

# .claude/agents/coder.md
---
name: coder
description: Writes code and fixes issues per a plan. Reads the files the plan names, makes the edits, runs the named test.
tools: Read, Edit, Bash, Grep, Glob
model: sonnet
---

# Coder
Read every file the plan names. Make the edits. Run the test the plan named. Return files changed, lines changed, test result.

# .claude/agents/reviewer.md
---
name: reviewer
description: Reviews changes and improves quality. Checks the diff against the plan and that nothing outside scope moved.
tools: Read, Grep, Edit, Bash
model: sonnet
---

# Reviewer
Read the plan and the coder's diff. Confirm the change matches scope and nothing else moved. Run the named test. Return pass or fail with line-level notes.

The planner runs on Opus because planning is the strategic step. The workers run on Sonnet because focused execution does not need the most expensive model. That split is deliberate, and it is the lever the cost chapter pulls later.

How do you wire three subagents to a planner?

You run the planner on your main thread, because subagents cannot spawn subagents. Start a planner-scoped session in your repo:

mkdir -p .claude/agents          # drop the three files in here first
claude --agent planner           # your session IS the planner now

Then hand it a real task and let it dispatch:

Add a typed config loader to this codebase.

Read the existing config file and the modules that consume it.
Write a plan: files changed, what the loader does, what does not change, the test, the rollback.
Then dispatch to the coder with the plan. After the coder returns, dispatch to the reviewer with the plan and the coder's summary.
Return a one-paragraph summary.

The planner globs for the config consumers, writes a five-line plan, invokes the Agent tool with coder, reads the returned summary, invokes the Agent tool with reviewer, and hands you one paragraph. Two dispatches per task. No nested delegation. The typed config loader is a file in your repo, the test passes when you run it yourself, and the reviewer’s notes are in the planner’s final summary.

What broke: the reviewer that could ship code

The first time most people pull a subagent off a public library, they install it without reading it. That is the expensive mistake, because the body of the file is the system prompt that runs on every invocation, and the tools line is the access it carries. Here is a real, popular community code-reviewer.md from VoltAgent/awesome-claude-code-subagents:

---
name: code-reviewer
description: "Use this agent when you need to conduct code reviews focusing on code quality, security vulnerabilities, and best practices."
tools: Read, Write, Edit, Bash, Glob, Grep
model: opus
---

Look at the tools line. A reviewer with Write can ship code straight to disk without going back through anyone. That is a hole in the discipline: the whole point of a reviewer is that it does not get to merge its own opinion into the repo. It also runs on model: opus, which is the priciest engine doing a job a cheaper one handles. The library file is a fine starting point, but you scope it down before it goes in your folder. My reviewer above has no Write and runs on Sonnet. That is the difference between reading the file and trusting the star count.

The discipline is six minutes: read the frontmatter (does description delegate the right tasks, does tools give exactly what the job needs), then read the body sentence by sentence for baked-in assumptions. You would not add an npm package without skimming its main file. Same rule.

What should you actually do?

• If you have a 47-agent library → archive all but three this week. Pick planner, coder, reviewer. Run them on a real task before you add a fourth.
• If you have zero subagents → copy the three files above, drop them in .claude/agents/, and run the typed-config-loader task on a repo you maintain.
• If you pulled an agent from a public repo → open it, read the tools line, and strip any access the job does not need before it ships.

The bottom line

• Three subagents that ship beat forty-seven that sit in a folder. The number is a feature, not a limitation.
• Scope every subagent’s tools to its job. A reviewer with Write is not a reviewer, and an Opus worker is a budget leak.
• The planner lives on your main thread and owns the dispatch. Everything else returns a summary and gets out of the way.