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.
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 conditions
Give 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.
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
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 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.
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
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 Exercise
- 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
- Delegation has a measurable reason.
- Context and tools are minimal.
- Shared writes cannot conflict.
- Output is structured and evidence-backed.
- Depth, turns, and cost are bounded.
- Parent/human retains approval.
Sources
Key takeaway: delegate only focused, separable work and exchange evidence through strict contracts; isolation is the value, not the number of agents.