The deciding question

Subagents are powerful — but using one when it isn’t needed is worse than not using one: you fragment continuous reasoning and waste context. This module’s heuristic fits in one line, but it needs concrete signals to work.

Decision flow — start with the main question; if "no," go through the follow-up questions.

Detailed content

What it is

The heuristic isn’t technical — it’s about what the result does with your context. If the task produces a mountain of data that you’ll receive as a summary and never reread line by line, the work belongs to a subagent. The main chat is your working memory — don't dump clutter into it.

One question filters out 80% of cases — with no complex rules.

Output that won’t be reread: logs, lists, raw search results.

Summary back: instruct "bring only the summary" — it's part of the prompt.

What it is

Five recurring patterns that almost always call for a subagent — recognizing them avoids the cycle of "starting in chat and realizing too late that you should have delegated."

The five signals

📁

Many files

Scanning an entire repository, auditing 40 components, refactoring a folder—anything that needs to read N files before acting.

📊

Output wall

CI logs, grep results, long lists of errors—you want the diagnosis, not the raw output.

🔁

Repeatable task

Something you’ll ask for again tomorrow, with different data. A subagent is easier to reuse than an improvised prompt.

⚡

Parallel/independent jobs

Three analyses that don't depend on one another can run at the same time—the orchestrator waits for all of them to finish and aggregates the results.

🔍

Impartial reviewer

The same chat that wrote the code is biased toward defending it. A subagent with no memory of what was written reviews it without filters.

Closed scope: clear start and end points—the subagent knows when it’s done.

Contained output: "give me only N bullets" sets the response length before launching.

Independence: the subagent doesn’t ask questions during execution.

The five signs to avoid

✗

Quick edit

Adjusting a line, renaming a variable, fixing a typo — the overhead of creating the agent is greater than the task itself.

✗

Dependent steps in sequence

If step B can only start after you’ve seen the result of step A and made a decision, that’s reasoning—stay in chat.

✗

Agents that would need to talk to each other

Subagents don’t talk to each other — if the task requires side-to-side coordination, it can’t be parallelized.

✗

Needs the conversation context

The subagent starts with a clean context—if it needs to know what was said earlier, it’s in the wrong place.

✗

Needs to ask you questions

If the agent will pause to ask for clarification, the independence that justifies using a subagent isn’t there.

Ongoing reasoning: A→B→C decisions belong in the chat, not with separate agents.

Setup cost: creating an agent has friction; for a 10-second task, it isn't worth it.

Clean context = blind to the past: if the agent needs the history, pass everything in the prompt.

What it is

When you’re still unsure after the filter question, there’s a numerical criterion that resolves most of the remaining cases: 10 or more files, or any output that, if dumped into the chat, you’d never read line by line.

💡

Practical rule

10+ files for scanning, or any output you’ll never reread = subagent. Fewer than 10 files and readable output = stay in chat.

Numerical criterion: 10 is concrete and quick to assess — no ambiguity around "many."

Output that won’t be reread: 3 huge log files also trigger it — it’s not just a count.

Scale: 5 files today could become 50 tomorrow — design the subagent early.

What it is

The decision isn't always binary — the conductor starts working, realizes the scope has grown, and decides on the spot trigger subagents. This is a dynamic workflow: runtime delegation, not in the original prompt.

Runtime decision: the maestro delegates when it sees the actual scope — it doesn’t need to be specified in the original prompt.

Dynamic fan-out: 1 task → N agents generated on the fly, each with a clear scope.

Maestro as a router: decides, delegates, and aggregates — never does the raw work.

What it is

After learning about subagents, there’s a natural tendency to want to use them for everything — the the new tool’s trap. Forcing a subagent where it's not needed fragments context, increases latency, and complicates debugging.

Consequences of forcing

✗ Fragmented context: the subagent starts from scratch; the reasoning that should flow gets broken into pieces.

✗ Latency without benefits: creating an agent takes time — for quick tasks, you finish more slowly.

✗ Difficult debugging: What went wrong? Was it the maestro? The subagent? The delegation prompt?

Simplicity principle: a subagent is a ladder — use it only when you need to climb.

Actual cost: setup + latency + potential debugging — the gains need to offset these costs.

Back to chat: when in doubt, start in chat; delegate if the scope grows.

Example: the same type of request in two scenarios

✓ Becomes a subagent

"Scan all files in src/components/ (there are ~60 components), check which ones are importing the legacy library lodash directly, and bring me only the list with the path and line number. Without showing me the file contents."

→ 60 files to scan (10+)
→ Output will never be reread line by line
→ Closed, independent scope

✗ Stays in the chat

"Look at this file utils/format.ts — it makes sense to move this function to the module for helpers? What do you think?"

→ 1 file, can be decided in chat
→ Needs the previous conversation (context)
→ Ongoing reasoning, not a one-off task

How it works in practice: the conductor making the decision

claude-code — maestro

You: audits all modules in src/ and tell me which ones have coverage below 60%

Claude: There are 48 modules. I’ll launch a subagent to scan them — it will return only the list with coverage. One moment...

⚙ Subagent started: scanning 48 coverage files...

Claude: Done. 7 modules below 60%: auth/session.ts (42%), api/retry.ts (38%), and 5 more. Do you want me to prioritize by risk or by ease of fixing?

You: by risk

✓ Raw output stayed in the subagent. The chat stayed clean.

Prompts ready to use

Prompt 1 — repository scan

"Scan all files in [folder], find [pattern/problem], and bring me only the list of affected files with the relevant line. Don’t paste the file contents."

Apply the criterion: many files + output that isn't reread = subagent.

Prompt 2 — parallel analysis

"Analyze [module-A], [module-B] e [module-C] in parallel—each independent. For each one, provide: the biggest technical risk and a refactoring suggestion in 3 bullets. Nothing else."

Independent jobs + contained output = parallel subagent.

Prompt 3 — impartial reviewer

"Review the code in [file] without looking at our conversation history. Search only for: logic bugs, unhandled edge cases, and dead code. 5 findings maximum, ordered by severity."

Impartial reviewer + clean context = a subagent is an advantage, not a limitation.

🏋️

Exercise: apply the question to 5 of your tasks

Use this module’s heuristic to classify real tasks from your day.

What to do

List 5 tasks you usually ask Claude Code to handle—the more varied, the better.
For each one, answer: “Will this dump output that I’ll never reread?”
If the answer is “no,” go through the follow-up questions: 10+ files? Parallel? Impartial reviewer?
Classify each task: subagent, direct chat or depends on the scope.
Note the reason in one sentence.

Success criterion

✓ Can classify at least 4 of the 5 tasks without hesitation.

✓ For each “subagent,” you can formulate the prompt with the output contained in one sentence.

✓ For each “direct chat,” you can explain which AVOID signal applies.

✓ Identifies at least 1 task where the decision depends on the actual scope revealed at the time.

Module summary

✓

The central question — "Will this dump output I'll never reread?" decides 80% of cases.

✓

5 signs to USE — many files, wall of output, repeatable, parallel, impartial reviewer.

✗

5 signs to AVOID — quick edit, dependent steps, side conversation, needs the context, needs to ask you.

✓

The 10+ rule — 10 or more files or output you won't reread = subagent, no debate.

✓

Dynamic workflow — the decision can happen at runtime as the scope grows.

→

Don't force — simpler is better; use a subagent only when the heuristic points to one, not out of habit.

Next module:

1.6 — Anatomy of a subagent. The file .md: frontmatter (config) + body (brain).

← Previous module Next module →