On this page#
- The definition
- Why Claude Code subagents exist
- How it actually works
- When you need it and when you do not
- The part vendors leave out
- FAQ
The definition#
Claude Code subagents are specialized AI workers that a primary Claude Code session delegates bounded tasks to. Each subagent operates with its own instructions, context, and allowed tools, then returns a result to the parent session. Use one to isolate work, not to make a difficult prompt magically smarter.
A subagent is still powered by a large language model: software that generates responses from learned patterns and the context it receives. The important difference is architectural. Instead of asking one conversation to retain every requirement, investigate every file, and perform every action, you split a task into controlled roles.
In practical terms, a Claude Code subagent should have:
- One narrow responsibility.
- Explicit inputs and expected outputs.
- Only the tools needed for that responsibility.
- A stopping condition.
- A parent agent that reviews the result before accepting it.
That last point matters. Delegation is not verification. The Claude Code documentation explains the product mechanics; your repository’s invariants still define whether the output is correct.
Photo by Snapwire on Pexels.
Why Claude Code subagents exist#
Claude Code subagents exist because long, mixed-purpose agent sessions accumulate irrelevant context and conflicting instructions. Before subagents, engineers handled this by opening separate sessions, repeatedly pasting constraints, or forcing one oversized prompt to plan, inspect, edit, test, and review the same change.
Those workarounds can function, but they are fragile:
- Separate sessions require manual context transfer.
- One giant session mixes planning evidence with implementation noise.
- Repeated prompts drift as wording changes.
- Tool access is usually broader than each task requires.
- Review becomes self-review by the same context that produced the change.
The real benefit is context separation. A repository investigator can inspect dependencies and return findings without filling the implementation context with every dead end. A reviewer can receive the patch and invariants without inheriting the implementer’s assumptions.
This is also why a generic “spawn more agents” rule is wrong. More agents create more boundaries, and every boundary can lose information. The goal is not parallelism for its own sake; it is giving each unit of work the smallest context that still permits a correct result.
If your team has not yet written down repository constraints, delegation is premature. Start with repeatable agent foundations and explicit acceptance criteria; PairFoundry’s foundations guide is the relevant next step. A subagent cannot preserve an invariant nobody stated.
How it actually works#
A Claude Code subagent works through delegated context, constrained capability, and a return message. The parent selects a task, supplies the necessary instructions and evidence, and invokes a specialized agent. That agent performs its bounded work independently, then hands its conclusions or proposed changes back to the parent.
The mechanism is better understood as a contract:
| Contract element | What it must answer | |---|---| | Role | What kind of work does this subagent own? | | Input | Which task, files, constraints, and evidence does it receive? | | Tools | What may it inspect or change? | | Output | Must it return findings, a plan, a patch, or verification results? | | Exit condition | When should it stop or report that it is blocked? |
A useful configuration is concrete rather than theatrical. “You are an expert reviewer” is weak. “Review this patch for violations of these three invariants; do not modify files; return findings with file locations and explain any uncertainty” creates an auditable boundary.
The parent context and the subagent context are not one shared mind. Assume that information omitted from the delegation is unavailable. If a migration must remain backward-compatible, say so. If generated files must not be edited, say so. If a test failure already existed, pass that evidence instead of expecting the subagent to infer it.
The official Claude Code overview describes Claude Code as an agentic coding tool that can understand a codebase and perform development tasks. Subagents organize that capability; they do not replace repository discovery, permission design, or validation.
A reliable delegation sequence is:
- Define one outcome.
- Include the relevant invariants.
- Limit the accessible tools.
- Specify the response format.
- Require the parent to validate the returned work.
- Keep final integration in one accountable place.
Do not let multiple subagents make overlapping edits without an explicit ownership scheme. That turns context isolation into merge ambiguity.
Photo by Digital Buggu on Pexels.
When you need it and when you do not#
You need Claude Code subagents when a task contains separable responsibilities that benefit from different context or permissions. You do not need them for a short, linear change that one agent can inspect, implement, and verify without losing important constraints. Complexity alone is not a reason to delegate.
Use a subagent when at least one of these conditions is true:
- Investigation would generate substantial context that implementation does not need.
- A reviewer should approach the patch without the implementer’s reasoning bias.
- One task must be read-only while another may edit files.
- Independent areas can be analyzed without overlapping ownership.
- A recurring task has a stable input/output contract.
- The parent needs a specialist result, not another open-ended conversation.
Keep the work in one agent when:
- The change is localized and sequential.
- Every next step depends on the immediately previous result.
- The repository’s invariants are still being discovered.
- Delegation would require copying nearly the entire parent context.
- Two agents would need to edit the same files.
- The parent cannot independently verify the returned result.
A good test is subtraction: if removing the subagent makes the workflow clearer without weakening isolation, review, or permissions, remove it. “Subagent Claude Code” workflows often become elaborate because the structure looks sophisticated, not because the repository needs it.
For reusable workflow patterns beyond a single agent definition, compare the available PairFoundry packs. The useful unit is a repeatable engineering contract, not an impressive collection of personas.
The part vendors leave out#
The cost of Claude Code subagents is coordination, not merely additional output. Every delegation creates a lossy interface: the parent must decide what context to send, the subagent must interpret it, and the parent must evaluate a compressed result. Poor boundaries can make the workflow less reliable than one focused session.
Three limitations deserve explicit treatment.
First, context isolation can remove essential information. A narrow prompt is only good when it is complete enough. Missing constraints produce confident work against the wrong problem.
Second, specialization can create false authority. Naming an agent “security reviewer” does not give it guaranteed security judgment. Its findings remain model output and require normal engineering verification.
Third, parallel work increases integration risk. Two individually reasonable changes can conflict at the architectural level even when Git reports no textual conflict. One parent must own the combined acceptance decision.
The common misconception is that a claude code subagent is a smaller autonomous teammate. It is better treated as a scoped execution context. That framing encourages least-privilege tools, explicit handoffs, and reviewable outputs.
Official documentation can explain supported behavior, but it cannot define your repository’s correctness contract. That missing layer is where most failures originate. For more definitions that separate agent terminology from operational reality, see PairFoundry’s plain definitions.
Photo by ThisIsEngineering on Pexels.
Related reading#
- Claude Code commands: the definition, and the part vendors leave out
- Claude Code API key — a plain explanation for people with a real repo
FAQ#
Should every repository have a set of Claude Code subagents?#
No. Add a subagent only after a recurring boundary becomes visible, such as read-only investigation, independent review, or ownership of a well-defined subsystem. Creating generic agents in advance usually produces vague prompts and duplicated responsibility. A small repository with linear work may be safer and faster with one carefully constrained agent.
How is this different from simply opening another Claude Code session?#
A separate session provides isolation, but the engineer manually transfers the task, context, and result. A subagent makes that delegation part of the parent workflow and can encode a reusable role, tool boundary, and output contract. The engineering requirement is identical: omitted context does not transfer itself, and returned work still needs validation.
What is the biggest team collaboration mistake?#
The biggest mistake is sharing subagent definitions without sharing repository invariants. Teams then standardize the appearance of the workflow while each engineer supplies different constraints. Put ownership rules, forbidden changes, validation requirements, and escalation conditions into the contract. Otherwise the same named subagent will behave like several incompatible tools.
How should I recover when a subagent returns a bad result?#
Reject the result at the parent boundary, preserve the known-good repository state, and identify whether the failure came from missing context, excessive permissions, ambiguous output, or an unsuitable task split. Fix the contract before retrying. Do not ask the same agent to “be more careful” while leaving the defective boundary unchanged.
When should a subagent never be allowed to edit code?#
Keep it read-only when its job is discovery, review, risk analysis, or evidence collection. Editing access weakens independence and expands the failure surface without helping those tasks. It should also avoid edits when ownership overlaps another agent or when the parent lacks a reliable way to verify and integrate the change.