Module 02 · CLI Workflows
Subagents: Delegating Focused Tasks Without Losing Context
Open lesson + course map
On this lesson
Course outline
Module 1 · Claude Code Fundamentals
Module 2 · CLI Workflows
Module 3 · Model Context Protocol Basics
Module 4 · Building an MCP Server
Claude Code subagents can isolate a focused role, context, and tool set. They add coordination cost, so use them for independent analysis or clear specialization—not every small step.
// concept
Define the Subagent Contract
Specify:
role and task boundary
context it receives
allowed/disallowed tools
expected output schema
time/turn budget
what it must not do
handoff and stop conditionsGive the smallest context needed. A security reviewer may read the changed API and rules but should not edit. A test runner may run approved commands but not install dependencies.
// concept
Preserve Context Through Artifacts
The parent should delegate file/reference locations, acceptance criteria, and a structured output. The subagent returns evidence—not a long conversational recap. The parent validates before using the result.
Parallel work is safe only when tasks do not edit the same files or external records. Partition resources or keep subagents read-only. Never let a worker approve its own consequential action.
// worked_example
Worked Example
A monorepo change affects an API and UI. The parent asks two read-only subagents to inspect separate directories against path-specific rules. Each returns {severity, file, evidence, recommendation}. The parent reconciles duplicate findings and asks the human which repairs to authorize.
No subagent edits, installs, commits, or pushes. If a subagent needs a file outside its scope, it reports the dependency rather than expanding access.
// failure_cases
Failure Cases to Diagnose
6 cases to diagnose
Every task delegated
overhead exceeds benefit.
Full repository and secrets passed
minimize context and tools.
Two workers edit one file
serialize or partition.
Free-form outputs cannot merge
require a schema.
Worker recursively spawns
bound depth and count.
Parent trusts conclusion without evidence
verify references.
// concept
Operator Note
Keep a delegation ledger containing parent task, subagent name/version, scope, files read, tools used, elapsed time, result status, and accepted findings. This makes subagent value measurable. If the parent must reread every file and reconstruct every conclusion, the delegation contract is too weak. If a worker finds a consequential vulnerability, it should report and stop; discovery does not grant repair, disclosure, or production access.
// pakistan_angle
Pakistan Angle
For agency work, use separate project contexts per client. Never create a “research subagent” with access to all client folders. Synthetic samples should replace customer exports when testing delegation.
Budget parallel work in foreign currency and developer review time. More agents do not automatically mean faster or cheaper delivery, especially on limited connectivity.
// hands_on
Hands-On Exercise
5 steps
Pick two independent review tasks.
Define tool and context boundaries.
Require a structured evidence output.
Run sequentially, then parallel if safe.
Compare time, cost, conflicts, and quality.
// completion_rubric
Completion Rubric
6 checks — tick as you verify
// sources
Sources
2 official sources — check every claim yourself
// check_yourself
Check yourself
3 questions · answers and options are taken word-for-word from this course
1 / 3 · diagnose
Your work shows this failure mode: “Full repository and secrets passed.” What does the lesson tell you to do about it?