Raising Claude Code - Part 5: Subagent implementation

Part 4 (Extension) covered when to use Skills vs Subagents — the conceptual side. Subagents are easy to grasp at the concept level. Where most people stall is “how do I actually implement one?”

That’s what this post is about.

But before getting into it, I want to be clear about my position.

I’m against treating multiple agents as “peers”

There’s a recurring pattern in the AI space lately:

• Have agents talk to each other
• Split roles and run them in parallel
• Make them behave like a human organization

I’ve written about this elsewhere (“It’s too early to ‘organize’ AI agents”), and I’m against this pattern.

Reasons:

• Communication cost balloons fast (tokens = money)
• Consensus across agents lowers accuracy (LLMs get pulled toward the majority / the most-confident one)
• Decisions become hard to trace (black-boxing, debugging hell)

But hierarchical Subagents are fine

Equal-peer consensus: no. Main agent calling Subagents in a hierarchical structure: different story.

• Main agent (1)
• Subagents (multiple, only invoked by the main)
• Human (final decision)

In this shape:

• Subagents don’t talk to each other → no round-trip cost ballooning
• Adoption is decided by human + main agent (no accuracy loss from consensus)
• Chain of command is clear (traceable)

In other words: don’t make them peers. don’t let them chat. final call stays with the human. This is the same idea as Part 4 (Extension).

When to reach for a Subagent (recap)

Good fit:

• You want behavior fundamentally different from the main role (e.g., a strict reviewer)
• You need to read a lot of files and don’t want to pollute the main context
• You want multiple investigations to run in parallel
• You want trial-and-error work hidden from the main thread

Avoid when:

• You’ll be syncing back-and-forth a lot (a Skill is enough)
• The decision needs the main context
• It’s a single-turn simple operation

Step 1: create the directory

project-root/
  .claude/
    agents/
      code-reviewer.md
      security-reviewer.md
      research-explorer.md

One file = one Subagent under .claude/agents/. Match the filename (without extension) to the name field in frontmatter when you can — it isn’t strictly required, but if you don’t, you lose track of which file is which Subagent.

Step 2: write the Subagent file

.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Conducts code reviews focused on separation of concerns,
  KISS / SOLID, security, error handling, and testability.
  Invoked when the main agent "delegates a review."
  Final adoption decision is made by main agent + human.
tools: Read, Grep, Glob, Bash
model: sonnet
---

# Code Reviewer

You are a dedicated code-review agent.
Review the code/diff handed to you by the main agent and return
a list of findings.

## Review perspectives

- Separation of concerns (no bloated single-file/single-function responsibilities)
- KISS / SOLID (over-abstraction, complex inheritance)
- Security (input validation, authorization, leaked secrets)
- Error handling (swallowed exceptions, re-raise, error types)
- Testability (DI, isolation of side effects)

## Output format

| ID | Severity (high/medium/low) | Category | Problem | Required Action | Verification |

## Constraints

- Don't make adopt/reject decisions (just hand findings back to main)
- Don't edit files (read and report only)
- Don't invoke other Subagents on your own

Key points:

• Be concrete in description (same lesson as Part 4)
• Restrict tools: a reviewer doesn’t need Edit / Write; Read / Grep is enough
• Pick a model: haiku for light scans, sonnet for substantive reviews, opus for design proposals
• State what the Subagent does NOT do in the body (system prompt) — this is how you keep the hierarchy intact

Step 3: invoke from the main agent

The main agent calls Subagents through the Agent tool (formerly Task, renamed in v2.1.63).

Auto-invocation (triggered by description match):

User: review src/auth/login.ts
Main: launch code-reviewer Subagent → get findings list →
  present to user → ask "adopt these?"

Explicit invocation:

User: have code-reviewer look at src/auth/login.ts

Note: invocation is the main agent’s call. Don’t let a Subagent invoke another Subagent (don’t break the hierarchy).

Step 4: codify the hierarchy in CLAUDE.md

Write this in the main agent’s CLAUDE.md:

# Subagent usage rules

- Subagents are invoked one-way from the main agent
- Subagents must not talk to each other directly
- Whether to adopt a Subagent's output is decided by the main agent + user
- Don't have Subagents make final decisions or do heavy operations like prod deploys

This is the Part 3 (Persuasion) layer applied to Subagents. Codify “don’t make them peers” as an explicit rule.

Without this, Claude has learned the “organized multiple agents” pattern from training data and may try to coordinate Subagents on its own.

Step 5: smoke test (replay test)

1. Place the Subagent file
2. Send a simple task from the main
3. Confirm the Subagent gets invoked as expected
4. Confirm it still gets invoked in a fresh session (same idea as the replay test in Part 6)

Common reasons it doesn’t get invoked:

• description is too vague → add “when to fire”
• name and filename don’t match → align them
• A required tool was excluded from tools → add it

Subagents that pay off when you build them first

• code-reviewer — separates the reviewer perspective (doesn’t make final calls)
• security-reviewer — strict only on the security angle
• research-explorer — read-heavy investigations, kept out of the main context
• doc-writer — generates docs against a fixed template

Subagents to avoid building:

• ❌ decision-maker — a Subagent that makes the final decision. Steals the role from the human and the main agent
• ❌ planner + implementer + reviewer as a 3-peer setup → ends up as consensus
• ❌ manager — a Subagent that supervises other Subagents. Deepens the hierarchy and becomes untraceable

Anti-patterns

The ones that bite hardest in practice:

• ❌ Subagent invoking another Subagent → hierarchy breaks, traceability gone
• ❌ Granting write access (Edit/Write) to a Subagent → blast radius is unreadable
• ❌ Vague description → won’t auto-fire, or fires on the wrong thing
• ❌ Delegating with zero main-context → results land off-target
• ❌ Main adopting Subagent output unconditionally → drifts toward consensus. The main must always evaluate
• ❌ Multiple Subagents in the same role, used as a vote → same failure mode as “equal peers”

Wrap-up

Treating multiple agents as peers: no. But hierarchical Subagents: yes.

Implementation keys:

• Define them in .claude/agents/<name>.md
• Restrict description / tools / model in the frontmatter
• Use the body (system prompt) to spell out what the Subagent does NOT do
• Invoke one-way from the main. No Subagent-to-Subagent conversation
• Final call stays with the human + the main agent

Operate Subagents under these constraints and you keep the main context clean while avoiding the accuracy loss that comes from consensus.

This is the implementation side of “make the chain of command explicit” — the throughline of the whole series.

Next is Part 6, the final post — Operations: the improvement loop and anti-patterns for keeping the whole setup healthy over time.