Claude Code Sub-Agents: Manage Context and
Delegate Complex Tasks

Claude Code sub-agents solve one of the hardest problems in agentic AI: context. A single Claude session has a finite context window. When you ask it to refactor a 200,000-line codebase, migrate a legacy monolith to microservices, or audit an entire product for security vulnerabilities, you will hit that limit — and the session will degrade or fail. Sub-agents are how you work around this without abandoning the task.

The sub-agent architecture in Claude Code lets you spawn child agents from within a parent session. Each child agent gets its own isolated context window, executes a specific subtask, and returns its result back to the orchestrating parent. The parent never loads the full problem into a single context — it delegates intelligently, accumulates results, and coordinates the final output. This is how production-grade Claude Code workflows are built.

This guide covers how Claude Code sub-agents work technically, when to use them, how to structure parallel versus sequential delegation, and the architectural patterns we use across our enterprise Claude Code deployments. If you're using Claude Code at the enterprise level, sub-agents are not optional — they're the architecture that makes large-scale automation viable.

What Are Claude Code Sub-Agents?

A sub-agent in Claude Code is a child Claude session launched programmatically from within a parent session. The parent uses the Task tool to spawn it, passing a description of the work to be done and the context the child needs. The child runs to completion, using its own tool calls (file reads, bash commands, searches), then returns a structured result. The parent continues with that result as an input.

This architecture mirrors how software teams actually work. A tech lead doesn't write every line of code — they define the work, delegate to engineers, review the output, and integrate it. Claude Code sub-agents implement the same model: one orchestrator, multiple executors, clear interfaces between them.

The key constraint to understand is that sub-agents do not share the parent's context. Each child starts fresh, with only what you explicitly pass in the task description. This is a feature, not a limitation — it means each agent is focused and context-clean, which keeps output quality high even on complex tasks. It also means the parent must be deliberate about what information each child needs.

The Task Tool

The mechanism for launching sub-agents in Claude Code is the Task tool. It appears in Claude Code's standard tool set alongside Read, Write, Bash, and Grep. When Claude Code calls the Task tool, it specifies a prompt for the sub-agent and an optional description. The sub-agent runs asynchronously in an isolated environment and returns its output when complete.

# Example: parent agent delegates a code review subtask
Task(
  description="Review authentication module for security vulnerabilities",
  prompt="""
  Review the authentication module at src/auth/*.ts.
  Check for: SQL injection, improper token validation, missing rate limiting,
  hardcoded credentials, insecure session handling.
  Return a structured list of issues with file path, line number, severity, and fix.
  """
)

The sub-agent that receives this task will read the relevant files, analyse them, and return a structured report. The parent agent never loaded those files into its own context — it simply received the analysis. This is the core pattern.

When to Use Sub-Agents: The Context Problem

The primary trigger for sub-agents is context exhaustion — when the task is too large to fit in a single session. But there are four distinct scenarios where sub-agents improve output quality beyond just the context limit:

1. Large Codebase Operations

Any task that requires reading, reasoning about, and modifying more than a few hundred files should use sub-agents. Migrating a Node.js API to TypeScript, refactoring a monolith into services, or upgrading all dependencies across a multi-module project — these tasks require sub-agents. The parent defines the migration strategy and delegates each module or file group to a child agent.

2. Parallel Independent Tasks

When a task has multiple independent subtasks, sub-agents can run them concurrently. Generating test coverage across five independent microservices, running security audits on parallel code paths, or producing API documentation for each module — these all benefit from parallel sub-agents. You get near-linear speedup: five sub-agents running in parallel complete in roughly the time of one.

3. Specialisation and Role Separation

Some tasks benefit from specialised agents with different system prompts. A parent agent might delegate to a "security reviewer" sub-agent with a security-focused system prompt, a "performance analyser" sub-agent trained on benchmarking patterns, and an "API documentation writer" sub-agent that produces consistent OpenAPI output. Role-specialised sub-agents produce better output than a single generalist agent switching between modes.

4. Long-Running Workflows with Checkpoints

For workflows that span hours — a full codebase migration, a complete audit with remediation — sub-agents provide natural checkpointing. Each sub-agent completion is a committed result. If something fails midway, you restart from the last successful checkpoint, not from scratch. Our code modernisation service uses sub-agents with checkpoint patterns for all legacy migration work.

Parallel vs Sequential Sub-Agents

The decision between parallel and sequential sub-agents is architectural. Get it wrong and you'll either have slow sequential execution where parallelism was possible, or race conditions and conflicting writes where sequential was required.

Sequential Sub-Agents

Use sequential sub-agents when each step depends on the output of the previous. Phase-gated workflows are the clearest example: first, a sub-agent reads all source files and produces a migration plan; second, a sub-agent implements the plan; third, a sub-agent validates the implementation against tests; fourth, a sub-agent updates all documentation. Each phase requires the prior phase's output — sequential is correct here.

Sequential sub-agents are also required when tasks share write targets. If two sub-agents both modify the same file, you need one to complete before the other starts. Any workflow with shared mutable state must be sequential or have explicit merge logic.

Parallel Sub-Agents

Parallel sub-agents are appropriate when tasks are independent: no shared writes, no sequential dependencies. Classic examples include running tests across multiple microservices simultaneously, generating documentation for independent modules, performing security scans on separate code paths, or producing localised versions of the same content.

Claude Code launches parallel sub-agents by calling the Task tool multiple times without awaiting each result before launching the next. The framework manages the concurrency. When all tasks complete, the parent collects results and proceeds. The performance gain can be substantial — a task that would take 40 minutes sequentially can complete in under 10 with four parallel sub-agents.

# Pattern: parallel sub-agents for independent microservices
tasks = [
  Task(description="Audit auth-service", prompt=audit_prompt("auth-service/")),
  Task(description="Audit payment-service", prompt=audit_prompt("payment-service/")),
  Task(description="Audit notification-service", prompt=audit_prompt("notification-service/")),
  Task(description="Audit reporting-service", prompt=audit_prompt("reporting-service/")),
]
# All 4 run concurrently; parent waits for all to complete

Structuring Effective Sub-Agent Prompts

Sub-agent quality is determined almost entirely by prompt quality. Because each child agent starts with no context from the parent, the task prompt must be self-contained. It must include everything the agent needs: what to do, what files or systems to look at, what format to return results in, and any constraints or standards to apply.

The Three-Part Sub-Agent Prompt

Every sub-agent prompt should have three parts. First, the objective: a clear, one-sentence statement of what the agent must accomplish. Second, the scope: exactly which files, directories, APIs, or systems the agent should work on. Third, the output specification: exactly what format the agent should return results in — whether that's a structured JSON report, modified source files, a markdown document, or a specific function signature.

Vague prompts produce vague results. "Review the authentication code" will get you a general commentary. "Review src/auth/jwt.service.ts and src/auth/session.middleware.ts for OWASP Top 10 vulnerabilities, returning a JSON array with fields: file, line, vulnerability_type, severity (critical/high/medium/low), description, recommended_fix" will get you actionable, structured output the parent can process.

Passing Context Explicitly

When a sub-agent needs context from the parent's work — for example, the output of a previous sub-agent, a migration plan, or configuration parameters — that context must be included inline in the task prompt. Do not assume the child has access to any information the parent holds. Embed it directly in the prompt string, truncated or summarised if necessary.

This is one of the areas where enterprise deployments most often get tripped up. Teams build sub-agent architectures that work in small tests but fail on large tasks because they try to pass too much context to child agents. The discipline required is the same as writing a good task brief: include what matters, exclude what doesn't, and trust the agent to do the work.

Enterprise Patterns: Real-World Sub-Agent Architecture

Across the Claude Code enterprise deployments we run, three sub-agent patterns appear repeatedly. Each addresses a specific class of large-scale engineering problem.

The Audit Pattern

A parent agent identifies all modules or components in scope. It spawns one sub-agent per module in parallel, each with an audit-focused prompt scoped to that module. All sub-agents run concurrently and return structured reports. The parent collects all reports, deduplicates overlapping findings, ranks issues by severity, and produces a consolidated audit output. This pattern is used for security audits, accessibility reviews, performance profiling, and API contract validation.

The Migration Pattern

A parent agent first runs a single sequential sub-agent to analyse the codebase and produce a migration plan — a structured list of files to change, changes required, and the order in which they should be applied. The parent then spawns sub-agents to execute each migration batch, in sequence where there are dependencies and in parallel where there are none. A final validation sub-agent runs the test suite and confirms correctness. Our code modernisation engagements use this pattern for Python 2 to 3 migrations, framework upgrades, and database ORM migrations.

The Generation Pattern

A parent agent defines a generation specification and spawns sub-agents to produce independent pieces of content in parallel. API documentation for each endpoint, unit tests for each module, localised content for each market, migration scripts for each schema version — these all map cleanly to the generation pattern. The parent assembles the outputs, validates consistency, and produces the final deliverable.

For teams building custom agent workflows, see our AI agent development service and the Claude Code Enterprise deployment guide for how to integrate sub-agent workflows into CI/CD pipelines.

Common Sub-Agent Mistakes (and How to Avoid Them)

Sub-agent architecture is powerful but introduces failure modes that don't exist in single-agent workflows. These are the mistakes we see most frequently in enterprise deployments.

Insufficient Prompt Specificity

The number one failure is vague sub-agent prompts. When a child agent has insufficient direction, it makes autonomous decisions about scope and approach — often the wrong ones. The fix is to treat sub-agent prompts like production API contracts: formally specify inputs, outputs, constraints, and error conditions. Never launch a sub-agent with a prompt you wouldn't be comfortable defending in a code review.

Missing Output Format Specification

If you don't tell a sub-agent exactly what format to return results in, you'll get inconsistent outputs that are hard to process programmatically. One agent returns markdown, another returns JSON, a third writes directly to files. Specify the output format in every sub-agent prompt. If the parent needs to parse the output, specify the exact schema.

Parallel Agents with Shared Write Targets

Running parallel agents that write to the same files or database tables produces race conditions and conflicting changes. Before launching any parallel sub-agents, explicitly enumerate their write targets and verify there is no overlap. If overlap exists, serialise those agents or use a merge pattern where each agent writes to a dedicated output and a final agent performs the merge.

Not Handling Sub-Agent Failures

Sub-agents can fail — due to context overflow, tool errors, or unexpected input. A production sub-agent orchestrator must have explicit handling for child agent failures: retry logic, fallback prompts, and graceful degradation. A parent agent that assumes all children succeed will produce silent errors in production. Configure Claude Code hooks to capture and log sub-agent failures in enterprise deployments.

Configuring Sub-Agents with CLAUDE.md

The CLAUDE.md file in your repository root is loaded by Claude Code at session start. It defines project-level configuration, coding standards, tool permissions, and instructions that apply to every Claude Code session — including sub-agent sessions. This makes CLAUDE.md a powerful mechanism for ensuring sub-agents follow the same standards as interactive sessions.

For sub-agent workflows, your CLAUDE.md should define the output formats your orchestrator expects, the tool permissions sub-agents require, the coding standards they must apply, and any project-specific context (architecture overview, directory structure, naming conventions) they need to do their work without being briefed individually in every task prompt.

A well-configured CLAUDE.md reduces the length and complexity of individual sub-agent prompts significantly — the project-level context lives in CLAUDE.md, and individual task prompts focus purely on the specific work. See our CLAUDE.md configuration guide for a detailed walkthrough. The Claude Code skills guide covers how to create reusable sub-agent patterns as skills.

Sub-Agents, Security, and Enterprise Governance

Sub-agents inherit the security context of their environment — which means your tool permission model must account for the full scope of what sub-agents can do. If a sub-agent has write access to production systems, you need explicit approval gates. If it has access to secrets in environment variables, you need audit logging. The blast radius of a misconfigured sub-agent is larger than a misconfigured single-agent session because multiple sub-agents can run in parallel.

In enterprise deployments, we apply the principle of least privilege to sub-agents: each child agent gets only the tool permissions it needs for its specific task. A documentation-writing sub-agent has read access but no write access to source code. An audit sub-agent can read but cannot modify files. A migration sub-agent has write access to source code but not to infrastructure configuration. This compartmentalisation is a core part of our Claude security and governance framework.

For a comprehensive view of securing Claude Code in enterprise environments, read our Claude Code enterprise security guide. For teams building MCP server integrations for sub-agents to use, see the Claude Code MCP servers guide.

Related Articles