Working with Claude Code Subagents

Instead of writing dozens of individual prompts, we can execute a single command — such as /cook — which orchestrates a team of specialised AI agents. Each agent is designed to perform a single task, but to perform that task exceptionally well. This chapter shows you how to build, configure, test, and scale these agents.

We begin by understanding what subagents are and why context isolation is central to their design. We then move into hands-on work: configuring a custom subagent, testing it against real code, and finally scaling execution using concurrent subagents through the Infinite Agentic Loop pattern.

This chapter covers the following topics:

1. Introduction to Claude Code subagents
2. Configuring the first subagent
3. Testing our subagent
4. Maintaining content flow while using subagents
5. Scaling with concurrent subagents
6. The Infinite Agentic Loop pattern

1. Introduction to Claude Code Subagents

According to the official Claude Code documentation, subagents are preconfigured AI personalities that Claude Code can delegate tasks to. Each subagent has its own purpose and area of expertise. In practical terms, each subagent is defined by a specific system prompt — a set of instructions that shapes its behaviour, tool access, and area of focus.

Why Subagents?

When you work on a complex project, you rarely need a single generalist to do everything. You want specialists: one person focused on security, another on performance, another on documentation. Subagents bring that same structure to AI-assisted coding. Each agent stays in its lane, does its job well, and reports back with a clean result.

Without subagents, a long Claude Code conversation accumulates context from many tasks: search results, file contents, tool outputs, and reasoning traces. This growing context can cause context confusion — irrelevant earlier content distracts the model from the current task. Subagents solve this by running in their own, isolated context windows. They receive only their own system prompt; they do not inherit the main conversation's history.

Core Properties of Subagents

Every Claude Code subagent has four defining characteristics:

1. Own system prompt. You write it, you control it. The system prompt defines what the agent knows, how it should reason, and what it should produce. This is the agent's identity.
2. Isolated context window. The subagent starts with a blank slate — no history from the main conversation, no tokens from other tasks. This is the most important property. Only the subagent's final result flows back to the main agent.
3. Restricted tool access. Each subagent is given a specific list of tools it can call. This implements the principle of least privilege: a code-reviewer should be able to read files but should not be allowed to delete them. Tool access covers both native Claude Code tools (Read, Bash, Grep, etc.) and any MCP server integrations you have configured.
4. Reusability. Define once, use everywhere. Subagent definitions are plain Markdown files that can be committed to a repository and shared with your whole team. They work across projects and compose into larger workflows.

Remember: Tool access in subagents is about the tools the agent can call (Read, Grep, Bash, MCP servers). Skills, which we cover later in the course, operate at a different layer and define structured, reusable capabilities rather than raw tool permissions.

Subagent Scopes

There are two places where subagent definition files can live, each serving a different purpose:

2. Subagent File Structure

Every subagent is a single .md file. The file is divided into two parts: a YAML frontmatter block at the top (enclosed by --- delimiters), followed by the system prompt in plain Markdown.

Frontmatter Fields Reference

The YAML frontmatter supports the following fields (see the official documentation for the complete schema):

The System Prompt Section

Everything below the closing --- of the frontmatter becomes the agent's system prompt. You have full control over this text. Well-structured system prompts typically include:

1. A one-sentence role declaration ("You are a senior security reviewer…")
2. A numbered workflow (the steps the agent must follow)
3. Explicit severity levels or output formats
4. Project-specific rules (naming conventions, forbidden patterns, etc.)

The more precise and structured this section is, the more reliable and consistent the agent's output will be.

3. Relationship to ReAct Agents

If you have built LLM applications before, the subagent structure may look familiar. It closely resembles the ReAct agent pattern, where the model is given a set of tools (each with a name and description) plus a system prompt that scopes its expertise and defines general instructions:

The pattern is the same: a model, a set of tools, and a prompt that constrains behaviour. But there is a critical difference in depth.

Shallow Agents vs. Deep Agents

A standard ReAct agent typically executes a short, bounded task: look something up, call an API, return a value. These are shallow agents. Claude Code's subagents — and the main coding agent itself — belong to a different category: deep agents.

A deep agent is capable of:

1. Running long multi-step tasks (reading dozens of files, iterating through errors, refactoring across layers)
2. Maintaining an internal plan and revisiting it as new information arrives
3. Using tools repeatedly and adapting strategy based on intermediate results
4. Implementing a complete feature end-to-end, not just answering a single question

This distinction matters for how you design subagent prompts. A shallow-agent prompt can be vague; a deep-agent prompt must be precise, because the agent will autonomously make many decisions over a long execution.

4. Configuring the First Subagent

Now that we understand the theory, let us create a real subagent. Open a Claude Code session and type the /agents command to see the current list of available agents:

At this point you will see only the general-purpose built-in agent — no custom project-level or user-level agents exist yet. There are two ways to create one:

1. Generate with Claude — an interactive wizard inside Claude Code
2. Manual configuration — write the .md file directly

We start with the first approach. It is the fastest route and is the recommended starting point for beginners.

Step 1 — Define the Agent Description

Click Create new agent (or press the corresponding key) and enter the agent description when prompted. This description defines the agent's goal and its invocation conditions. For our example:

Two things are happening here. First, we are defining the agent's personality: a witty but technically rigorous senior engineer. Second, we are providing an explicit trigger phrase ("funny review") so that Claude knows when to delegate to this agent automatically.

Tip: If your description feels too vague, open a separate Claude instance and ask it to expand your rough description into a detailed system prompt. Paste the result into the wizard. This is a fast way to produce high-quality agent prompts without writing them from scratch.

Step 2 — Confirm Activation Triggers

After you submit the description, Claude Code suggests activation triggers — the phrases that will cause the main agent to delegate to this subagent. For our example these are automatically suggested as funny review and funny code review.

Review them, adjust if needed, and press Enter to continue.

Step 3 — Select Tools

The next step is selecting which tools the agent is allowed to use. Because this is a code reviewer, it only needs to read — not modify — files. Select the read-only tools:

1. Glob — pattern-based file listing
2. Grep — text search across files
3. LS — directory listing
4. Read — file content reading
5. NotebookRead — notebook cell reading
6. WebFetch — reading public documentation pages
7. WebSearch — searching the web for library references

MCP tools (for example Context7 library documentation access) can also be added from this screen. In our case we add them so the reviewer can look up official documentation when evaluating code patterns.

Write tools (Edit, Write) and execution tools (Bash) are intentionally omitted. A reviewer has no business executing code or changing files.

Step 4 — Choose the Model and Colour

Select the model that will power this subagent. Sonnet is a good default: it balances quality, speed, and cost. If the agent needs to handle very long files or complex reasoning, consider Opus. For fast, cheap, read-only tasks, Haiku is the most economical choice.

Choose a colour (in our case yellow) so the agent is easy to identify in the Claude Code UI when multiple subagents are running simultaneously.

Step 5 — Review and Save

Claude Code displays a summary of all configuration choices. You can edit any field before saving. When you confirm, the agent file is written to .claude/agents/code-comedy-carl.md.

Open the generated file and you will see the complete definition:

This file is also available as a companion download in this article's folder: code-comedy-carl.md.

5. Testing Our Subagent

Now that the review subagent is configured, we need a concrete way to validate that it behaves as intended. We will create a small sample file that the subagent can analyse. The goal is not to build production-ready logic, but to generate simple code that lets us observe how the subagent performs a review.

Creating a Test File

Ask Claude Code to generate a simple C# file that exposes a product catalogue endpoint:

Claude will produce something like this:

This endpoint has several intentional review targets: Results.Ok(null) is returned when the product is not found (should be Results.NotFound()), out-of-stock items are returned without any warning, there is no structured logging, and there are no unit tests. These give Code Comedy Carl plenty of material.

Running the Code Review Subagent

With the file in place, invoke the subagent using the trigger phrase and a file reference:

Claude Code recognises the trigger, selects the code-comedy-carl subagent, and spawns an instance of it. You can watch the agent initialise, read the file, and begin acting on it.

By expanding the agent view with Ctrl+R (Windows/Linux) or Cmd+R (macOS), you can see all of the agent's internal steps: which tools it called, what it read, and how it arrived at its response.

Spawning Multiple Review Instances

You can ask for more than one review in a single request:

Claude Code will spawn two instances of code-comedy-carl. An important observation: these instances often run sequentially, not concurrently. Claude Code does not always assume that tasks are independent. If there is any ambiguity about dependencies between tasks, it errs on the side of running them one after another.

Each instance still operates in its own isolated context — they cannot see each other's work — but they are serialised in time rather than parallelised. The next section addresses how to change this.

6. Maintaining Content Flow While Using Subagents

When you delegate tasks to subagents, the way you phrase your request has a direct impact on how Claude orchestrates execution. Understanding this lets you control whether agents run in series or in parallel — and ensures that the main conversation stays coherent as results flow back.

Implicit vs. Explicit Independence

Claude Code is conservative by default. If it cannot determine whether two tasks share a dependency, it will run them sequentially to be safe. Consider these two phrasings:

Structuring the request so that independence is obvious significantly increases the likelihood of concurrent execution. Phrase tasks as parallel units of work whenever you know they do not depend on each other.

Keeping the Main Conversation Clean

Each subagent runs in isolation and returns only its final output to the main conversation. This is what makes them powerful for maintaining a clean context: all intermediate tokens (file reads, search results, reasoning traces) stay inside the subagent's context window and are never surfaced to the parent.

Best practices for clean context flow:

1. Ask subagents to return structured summaries, not raw dumps. A terse JSON or Markdown report is far less polluting than a full file listing.
2. If you run multiple subagents in sequence, ask the first to produce output in a format the second can consume directly. This reduces the back-and-forth parsing you need to do in the main conversation.
3. Use the subagent's system prompt to enforce a consistent output format — for example, always return findings as a Markdown table with columns for severity, file, and description.

Foreground vs. Background Execution

By default, a subagent runs in the foreground — it blocks the main conversation until it finishes. If you want to start a long-running subagent and continue working in the main session, you can move it to the background:

1. Press Ctrl+B while a foreground subagent is running to move it to the background.
2. Results will be merged back into the main conversation when the subagent finishes.

Background execution is useful when a subagent is doing exploratory research that will take several minutes. You can continue refining the main plan while the subagent works independently.

7. Scaling with Concurrent Subagents

The real power of subagents becomes visible when you run many of them simultaneously on independent tasks. Parallel subagent execution is the foundation of what Anthropic calls multi-agent workflows, and it enables approaches that would be impractical in a single sequential conversation.

When to Run Agents in Parallel

Parallel execution is most valuable when:

1. You have multiple files or modules that each need the same operation (review, migration, documentation)
2. You want to explore several implementations of the same problem and pick the best one
3. You need to run independent validations simultaneously (security scan, performance check, style review) and aggregate the results
4. The work is too large for a single context window and must be partitioned

A Concrete Parallel Example

Suppose your ASP.NET Core application has four controllers. You want each one reviewed independently. Instead of a sequential review, you can phrase the request to drive parallel execution:

Claude Code will spawn four code-comedy-carl (or whichever reviewer you have configured) instances simultaneously. Each agent reads its own controller, applies its review logic, and returns its findings. The main conversation receives four separate reports — one per controller — in whatever order the agents finish.

8. The Infinite Agentic Loop

The Infinite Agentic Loop is an advanced orchestration pattern that combines three ideas:

1. Parallel generation — many subagents produce independent versions of the same artefact
2. Evaluation — the main agent (or a dedicated evaluator subagent) scores each version
3. Selection and iteration — the best version advances, or the loop continues until a quality threshold is met

The pattern was coined and popularised in the Claude Code community as a way to escape the single-path problem: traditional AI-assisted coding produces one solution and you accept or reject it. The Infinite Agentic Loop produces many solutions and selects the strongest.

The Infinite Prompt

The driving instruction is called the Infinite Prompt. It instructs Claude to:

1. Spawn N subagents, each implementing the same feature independently
2. Evaluate each implementation against a set of criteria
3. Merge the best-performing elements or pick the winner outright
4. Optionally loop — take the winner as the new baseline and generate another round of variations

A minimal Infinite Prompt looks like this:

Why This Pattern Matters

The Infinite Agentic Loop shifts the model of AI-assisted coding from generate → accept to generate → compete → select. This has several practical advantages:

1. Diversity of approach. Each subagent's isolated context means it arrives at its solution without being anchored to the others. You get genuinely different implementations, not variations on one idea.
2. Built-in quality gate. The evaluation step is an explicit quality check embedded in the workflow. You do not have to review three implementations manually — the evaluator does it for you.
3. Scalable exploration. Increasing the number of agents from 3 to 10 costs only compute time. For hard problems where the optimal solution is unknown, wider exploration increases the chance of finding it.
4. Iterative improvement. By looping — using the winning implementation as the new baseline — you can progressively refine quality over many generations, much like an evolutionary algorithm.

A Full Infinite Agentic Loop for ASP.NET Core

Here is a more detailed example applied to a real engineering task. We want to add distributed caching to an existing ASP.NET Core endpoint. We do not know which caching strategy — in-memory, Redis, or a hybrid — will be best for our use case, so we explore all three in parallel:

Notice how each agent gets a fully specified, independent task. The evaluation criteria are explicit and measurable. The merge instruction handles the case where no single winner is obvious.

Adding Another Subagent

If the workflow grows and you need a specialised evaluator — rather than relying on the main agent to evaluate — you can create a dedicated evaluator subagent. Add a new definition file under the agents directory:

The senior code reviewer example used throughout this chapter is also included as a companion file: code-reviewer.md.

9. Summary

Subagents are the building block of scalable, structured Claude Code workflows. Their defining characteristic is context isolation: each subagent runs in its own context window, unaffected by the noise of the main conversation. This isolation is not just a technical detail — it is the foundation of reliable, predictable AI-assisted engineering.

You now know how to create a subagent using both the interactive wizard and a raw Markdown file, how to control its tool access, how to phrase requests that drive parallel execution, and how to use the Infinite Agentic Loop to explore competing implementations and select the strongest outcome. These patterns compose: a team of specialised subagents, orchestrated thoughtfully, can tackle engineering challenges that would overwhelm any single conversation.

Key Points

1. Subagents are preconfigured AI specialists defined by a YAML frontmatter + system prompt Markdown file.
2. Each subagent runs in an isolated context window — no main conversation history, no cross-contamination.
3. The tools field implements least privilege: give each agent only the tools it needs.
4. Project-level agents live in .claude/agents/; user-level agents live in ~/.claude/agents/.
5. To trigger parallel execution, phrase tasks as explicitly independent units of work.
6. The Infinite Agentic Loop spawns multiple agents to explore competing solutions and selects the best.
7. Claude Code subagents are deep agents — capable of long, autonomous, multi-step execution, unlike shallow ReAct agents.