---
title: "Claude Code: Subagents"
slug: "claude-code-subagents"
category: "ai-agents"
tags: ["claude-code", "subagents", "multi-agent", "worktrees", "ai-agents", "orchestration"]
status: "stable"
last_updated: 2026-05-29
summary: "Define subagents as .claude/agents/*.md files with scoped tools, isolate workers in git worktrees, and coordinate through branches with one PR per agent."
related: ["[[ai-agents/claude-code]]", "[[ai-agents/multi-agent]]", "[[ai-agents/claude-code-skills]]", "[[ai-agents/claude-code-claude-md]]", "[[tooling/claude-code-workflow]]", "[[tooling/github]]", "[[prompt-engineering/prompt-design]]"]
---

## Overview

Subagents are Claude Code instances spawned by a parent agent to parallelize work. Each subagent runs in its own isolated context window, reads the same `CLAUDE.md`, and produces a branch for the parent to merge. The hardest part of multi-agent file work is conflict avoidance, not spawning. Get isolation right first. See [[ai-agents/multi-agent]] for the coordination patterns; this page covers the Claude Code specifics.

## Define each subagent as a Markdown file in .claude/agents/

Subagents are not configured through a settings.json key. Each one is a Markdown file with YAML frontmatter in `.claude/agents/` (project) or `~/.claude/agents/` (user). The frontmatter declares the subagent's identity and scope; the body is its system prompt.

```markdown
---
name: page-writer
description: Drafts a single content page from a brief. Use for independent page work.
tools: Read, Write, Edit, Bash
model: sonnet
permissionMode: acceptEdits
---

You write one content page per invocation. Follow the schema in CLAUDE.md.
Commit your work to the branch the parent assigns. Touch only the file you own.
```

Common frontmatter fields: `name`, `description` (the routing hint the parent matches against), `tools` (the allowed tool set), `model`, `permissionMode`, and `mcpServers`. Scope `tools` tightly so a research subagent cannot write and a writer cannot reach unrelated servers.

## Isolate every file-writing subagent in a git worktree

Context isolation prevents prompt collisions, not filesystem collisions. A subagent that writes files in the shared working tree still races with every other agent touching the same tree. Give each file-writing worker a private git worktree, created by the parent as an orchestration step (`git worktree add .claude/worktrees/<id> -b claude/<task-id>`). This is a pattern the parent implements, not a built-in mode.

The cost is a few seconds per worktree setup. The benefit is that two subagents can write to the same filename without one overwriting the other.

Skip worktree isolation only for read-only subagents: research, search, diff analysis. If the agent calls `Write`, `Edit`, or `Bash` with side effects, give it a worktree.

## Assign each subagent its own branch

Worktree isolation alone is not enough. Commit every subagent's work to a named branch.

```text
Parent creates worktrees:
  .claude/worktrees/agent-abc/  → branch: claude/feature-abc
  .claude/worktrees/agent-def/  → branch: claude/feature-def

Agents commit to their own branches.
Parent merges or opens PRs from each branch.
```

Name branches deterministically so the parent can find them: `claude/<task-id>` or `claude/<slug>`. Avoid generic names like `claude/work-1` that clash across sessions.

## Run subagents in parallel for independent tasks

Parallel execution makes sense when tasks do not share output files and do not depend on each other's results.

Good candidates for parallelism: generating independent content pages, reviewing a list of PRs, running tests for separate packages in a monorepo, scraping a list of URLs.

Bad candidates: tasks where agent B needs the output of agent A; tasks where both agents write to the same file. Sequential execution is cheaper to debug and produces less merge noise when the dependency is real.

The [[ai-agents/multi-agent]] orchestrator-worker pattern applies here: the parent decomposes, fans out, and merges. Workers do not communicate with each other.

## Use the one-PR-per-agent rule to keep reviews tractable

Each subagent opens exactly one pull request against a staging branch or `main`. The parent reviews the diffs independently before merging any.

Reasons this rule exists:

- A diff from one agent is reviewable in isolation. A diff from three merged agents is not.
- A broken agent's PR can be closed without reverting work from other agents.
- CI runs per PR, giving per-agent signal.

When a task genuinely requires all agents' work to land together, use a staging branch. Each agent's PR merges into the staging branch; the staging branch merges into `main` as a single merge commit.

## Pass context through the brief, not through shared state

Subagents read `CLAUDE.md` and the task brief. They do not read each other's in-progress work. Design tasks so each agent gets everything it needs in its brief.

If agent B genuinely needs agent A's output, sequence them: A runs, commits, and the parent feeds A's output into B's brief. Parallel execution with shared state produces non-deterministic output and is hard to replay.

## Avoid conflict zones in parallel runs

Before spawning parallel agents, identify the files that every agent will plausibly touch.

High-conflict files: `index.md` MOCs, `llms.txt`, shared config files, schema definitions. Route all writes to these files through the parent agent or a designated merge agent, not through individual workers.

Workers write to their own scoped files. The parent reads all branches and produces the merge. See [[tooling/claude-code-workflow]] for the concrete merge flow.

## Related

- [[ai-agents/claude-code]]
- [[ai-agents/multi-agent]]
- [[ai-agents/claude-code-skills]]
- [[ai-agents/claude-code-claude-md]]
- [[tooling/claude-code-workflow]]
- [[tooling/github]]