Objective
What you're building
One real subagent-based workflow for a task you actually repeat — and, just as importantly, a clear-eyed comparison of whether delegating it was actually worth it, versus doing the same thing in your main conversation.
Why delegate at all: context isolation
A subagent gets a fresh context window, which is the entire point
Your main Claude Code conversation accumulates context as you work — every file read, every edit, every tool result. A task like "review this 2000-line diff and summarize the risks" run inline adds all of that reading to YOUR context, permanently, even after you've gotten the summary you needed. Delegated to a subagent, that reading happens in an isolated context that closes when the subagent finishes — you get the summary back, not the 2000 lines of diff that produced it.
Designing the subagent
---
name: diff-risk-reviewer
description: Reviews a git diff for risky changes (breaking API changes, removed error handling, security-sensitive code) and returns a short risk summary.
tools: Read, Bash, Grep
---
You review git diffs for risk. Given a diff, identify:
1. Breaking API/interface changes
2. Removed error handling or validation
3. Security-sensitive changes (auth, permissions, secrets handling)
Return a short summary: HIGH/MEDIUM/LOW risk per category, with the specific
line(s) that triggered each flag. Do not comment on style or formatting.
Notice the tools field is scoped down (Read, Bash, Grep only) -- a subagent doesn't need every capability your main session has, and limiting it is both a safety practice and a way to keep it focused on exactly one job. The description field matters more than it looks: it's what determines whether this subagent gets invoked appropriately for a given task.
When NOT to delegate
Reaching for a subagent by default is itself a mistake worth naming
Delegating a trivial, quick task (read one file and tell me what it does) to a subagent adds real overhead — spinning up a fresh context, the round-trip of invoking and waiting — for something that would have been faster done inline. Subagents earn their overhead when the task involves reading a LOT that you don't want to keep around (large diffs, whole-codebase scans), when it's genuinely parallelizable with other work, or when it needs a narrower, specialized prompt than your main conversation's context. "I have subagents available" isn't a reason to use one for everything.
You set up a subagent for "read this one config file and tell me what port it uses." Was this a good use of a subagent?
This is exactly the "when NOT to delegate" case from this lesson -- a single small file read doesn't produce enough context bloat to be worth isolating, and the overhead of subagent invocation for something this quick is a real cost with no real benefit here. The judgment call is proportional: bigger context-bloat risk and/or genuine parallelism potential justifies the overhead; a quick single-file lookup usually doesn't.
What you're building today
A real subagent (code review, test generation, or research — whichever matches a task you actually repeat), invoked against a real task in your repo, with a written comparison: how much context/time did the subagent version use versus doing the same task inline, and was the isolation genuinely worth it for this specific task.