Claude Code Subagents for Production Teams

The Verdict

Claude Code subagents are worth adding when a task is self-contained, noisy, and easy to summarize back to the main session. They are the right fit for code review, test triage, dependency impact checks, migration research, documentation sweeps, and log analysis. They are the wrong fit for open-ended product judgment, final writes without review, broad repo ownership, or anything that needs the whole conversation history to make the call.

The useful mental model is not "more agents." It is bounded delegation inside one repository workflow. Anthropic's current Claude Code subagent docs define subagents as specialized assistants with their own context window, system prompt, tool access, and permissions. That isolation is the feature. It keeps verbose exploration out of the main conversation and lets the parent session receive a compact result.

Treat the parent Claude Code session as the control plane. The parent decides the plan, owns final edits, sees permission prompts, and checks the summary. The subagent does the narrow work.

What Subagents Actually Change

Subagents change context flow first, not team structure. A normal Claude Code session accumulates search output, file reads, logs, test failures, and dead ends in one conversation. A subagent moves a bounded chunk of that work into a fresh context and returns only the result.

That is useful when the task produces large intermediate output:

• Search the auth module and summarize risky call sites.
• Run the test suite, cluster failures, and return the failing files.
• Review a migration diff against project conventions.
• Read vendor docs and return the exact integration constraints.
• Inspect a dependency update and report breaking API changes.

The main session stays focused on the plan and decision. The subagent absorbs the clutter.

The docs make two boundaries explicit. Subagents work within a single Claude Code session. If you need many independent sessions monitored from one place, Anthropic points to background agents. If you need sessions that communicate with each other, it points to agent teams. That distinction matters for production teams because a subagent is not a durable worker fleet. It is an isolated helper inside a controlled session.

Built-in subagents are also not all the same. Claude Code includes Explore, Plan, and general-purpose subagents. Explore and Plan skip CLAUDE.md files and the parent session's git status, while custom subagents load them. If your policy lives in repo memory, use custom project subagents for repo-specific behavior instead of assuming every built-in helper has the same context.

The Production Pattern

The first production subagent should be a read-only reviewer that returns structured findings and cannot edit files. That gives the team value without moving the approval boundary.

Put repo-specific subagents in .claude/agents/ and check them into version control. Use ~/.claude/agents/ for personal helpers that should travel across projects. Subagent files are Markdown files with YAML frontmatter, and only name and description are required, but a production repo should almost always specify tools, model behavior, and output rules.

---
name: security-reviewer
description: Use proactively after auth, billing, permissions, or data-access changes. Review the diff and return risk-ranked findings with file paths, evidence, and required approval gates.
tools: Read, Grep, Glob, Bash
model: sonnet
permissionMode: plan
isolation: worktree
background: true
maxTurns: 6
---

You are a security review subagent for this repository.

Work only from repository files, test output, and command results. Do not edit files.

Return:
- Scope reviewed
- High-risk findings with file paths
- Missing tests or logs
- Approval gates required before merge
- A final verdict: block, revise, or pass

This file does four important things.

It names a precise trigger. Claude delegates based on the request, current context, and the subagent's description field. Vague descriptions cause bad routing. "Use proactively after auth, billing, permissions, or data-access changes" is better than "security expert."

It allowlists tools. The tools field restricts the subagent to file reads, search, and Bash. If you omit tools, the subagent inherits all tools. That is convenient in a personal session and risky in a team repo.

It makes the review observable. The required output gives the parent session something checkable. A subagent that returns "looks good" is useless. A subagent that returns file paths, evidence, missing tests, and a merge verdict can feed a real review gate.

It keeps risky execution constrained. permissionMode: plan keeps the subagent in a read-only exploration posture. isolation: worktree gives the subagent a temporary git worktree when it does need an isolated copy of the repo. The docs say that worktree is branched from the default branch by default and cleaned up if the subagent makes no changes.

Scope, Precedence, And Team Ownership

Project subagents should carry the repo contract. User subagents should carry personal preference. Managed subagents should carry organization policy.

Anthropic documents several subagent scopes. Managed settings have the highest priority. Project subagents live in .claude/agents/. User subagents live in ~/.claude/agents/. Plugin subagents come from enabled plugins. CLI-defined subagents can be passed for one session and are not saved to disk.

For a software team, .claude/agents/ is the default place for durable repo behavior because the files can be reviewed like code. That is where you put rules such as:

• This repo uses pnpm, not npm.
• Security findings must cite file paths and line-level evidence.
• Database review must never run write queries.
• Migration work must update tests and rollout notes.
• Any billing, auth, or tenant-boundary change needs human approval.

The nested directory rule is useful for monorepos. Claude Code discovers project subagents by walking up from the current working directory. As of v2.1.178, when nested .claude/agents/ directories define the same name, the definition closest to the working directory wins. That lets a platform repo use a base test-triage agent while a payments package overrides it with stricter rules.

Keep names unique anyway. Claude Code scans .claude/agents/ and ~/.claude/agents/ recursively, but local subagent identity comes from the name frontmatter field, not the subfolder path. A tidy folder tree helps humans; unique names help Claude.

Permissions Beat Persona

The prompt tells a subagent how to think. The tool and permission model decides what damage it can do. Production teams should spend more time on the second part.

Claude Code supports tools and disallowedTools. Use tools when you want a strict allowlist. Use disallowedTools when you want to inherit most of the parent session but remove known-dangerous tools. For review agents, prefer tools. It is easier to reason about a small allowlist than a broad inheritance model.

---
name: test-triage
description: Use after a failed test run. Cluster failures, identify likely owners, and propose the smallest next command.
tools: Read, Grep, Glob, Bash
permissionMode: plan
background: true
---

You are a test triage subagent. You may inspect files and run read-only diagnostic commands.
Return failing test names, likely cause, files to inspect, and the next command the parent session should approve.

Do not use bypassPermissions for team subagents. The docs state that bypassPermissions skips permission prompts and can allow writes to sensitive directories including .git, .claude, .vscode, .husky, .devcontainer, and others. That is the opposite of a controlled rollout.

Parent mode also matters. If the parent session uses bypassPermissions or acceptEdits, that takes precedence and cannot be overridden by the subagent. If the parent uses auto mode, the subagent inherits auto mode and its frontmatter permissionMode is ignored. In practical terms: you cannot make a risky parent session safe by giving the subagent safer-looking frontmatter.

Hooks are the deterministic layer. For example, a database review subagent may need Bash to run a local SQL inspection command, but a PreToolUse hook can block write queries. Anthropic's docs show PreToolUse hooks validating commands before execution, with exit code 2 blocking the operation. That is the right shape for anything that touches data, infra, deploys, or secrets.

This is where Claude Code hooks and subagents fit together. Subagents divide attention. Hooks enforce policy.

MCP, Skills, Memory, And Worktrees

Subagents should get extra capability only when the capability is tied to the job. Claude Code supports mcpServers, skills, memory, and isolation, but each one changes the risk profile.

Use mcpServers when a subagent needs a tool the parent should not carry in its main context. Inline MCP servers connect when the subagent starts and disconnect when it finishes. String references share the parent session connection. For a browser-testing subagent, scoping Playwright or a staging-only browser MCP server to that agent can keep the main session cleaner.

Use skills when the subagent needs a known workflow loaded at startup. The docs say the full skill content is injected into the subagent's context. That is useful for a review agent that must always follow one security checklist, but it also consumes context. Do not preload a stack of skills just because they exist.

Use memory sparingly. The memory field supports user, project, and local scopes. The project path is .claude/agent-memory/<name-of-agent>/, which makes it shareable in version control. That is useful for recurring review knowledge, such as "this repo's billing permission boundary lives in these files." The tradeoff is important: when memory is enabled, Read, Write, and Edit tools are automatically enabled so the subagent can manage memory files. If your reviewer was meant to be read-only, memory changes that.

Use isolation: worktree for agents that may need to experiment. It gives the subagent a temporary git worktree rather than the parent checkout. That is a good fit for migration attempts, dependency updates, or alternative fixes. It is overkill for a docs research agent.

Plugin subagents deserve a special warning. Anthropic documents that plugin subagents do not support hooks, mcpServers, or permissionMode; those fields are ignored for plugin subagents. If you need those controls, copy the agent into .claude/agents/ or ~/.claude/agents/ and own the file.

Background And Nested Subagents

Background subagents are useful when work is long-running and reviewable. They are a poor fit when the parent needs tight step-by-step control.

Good background tasks:

• Run tests and summarize failures.
• Search a large repo for ownership and dependency paths.
• Read a set of docs and return integration constraints.
• Compare a diff against repo conventions.
• Inspect logs and cluster recurring errors.

Risky background tasks:

• Modify files while the parent session keeps moving.
• Spawn more agents without a clear stop condition.
• Touch production data or infrastructure.
• Run commands whose output changes the next decision immediately.

As of v2.1.186, background subagent permission prompts surface in the main session and name the subagent that is asking. That is a meaningful safety improvement because the reviewer can see which helper wants permission. Before you rely on it, make sure your team is running a version with that behavior and that reviewers know denial does not necessarily stop the whole subagent.

Nested subagents should be rare. As of v2.1.172, a subagent can spawn its own subagents, and a subagent at depth five does not receive the Agent tool. That limit keeps runaway recursion in check, but production teams should not design workflows that need that much nesting. If a review subagent wants to spawn separate verifiers per finding, require a fixed output shape and a max-turn cap.

The simpler rule is better: one parent session, one or two subagents, one explicit summary, one human-visible decision.

The Rollout Checklist

Ship subagents like repo infrastructure, not personal snippets.

1. Put repo-owned agents in .claude/agents/.
2. Give every agent a narrow description that names the trigger.
3. Prefer tools allowlists over broad inherited access.
4. Keep review, triage, and research agents read-only at first.
5. Use permissionMode: plan for exploration agents.
6. Add isolation: worktree before allowing experimental edits.
7. Add hooks for commands that can touch data, infra, deploys, secrets, or protected files.
8. Require structured output with file paths, evidence, missed tests, and a verdict.
9. Log which subagent ran, what prompt it received, what tools it used, and what it returned.
10. Review subagent files in pull requests like CI config or deployment scripts.

The first metric is not how many tasks subagents run. It is how often their output changes the parent session's decision without forcing a human to inspect raw tool noise.

For teams already using plan-first development, subagents fit naturally after the plan and before edits. The pattern is: use Claude Code planning mode, run a read-only reviewer or researcher, update the plan, then approve the edit path.

What Breaks First

The first failure mode is vague routing. If two subagents both say "use for code review," Claude will make weak delegation choices. Use descriptions that name file types, risk areas, or workflow stages.

The second failure mode is hidden authority. A subagent can sound confident because it saw a lot of files. That does not make it the approver. Require it to cite evidence and return a verdict the parent session can challenge.

The third failure mode is permission drift. A personal ~/.claude/agents/ helper may work well for one engineer, then behave differently from the checked-in project agent. Keep production behavior in project files, and make personal agents opt-in.

The fourth failure mode is memory creep. Persistent memory can make a reviewer smarter, but it can also stale out or collect irrelevant local context. Use project memory when the knowledge belongs to the repo, local memory when it must not be checked in, and no memory when the agent only needs the current diff.

The fifth failure mode is treating subagents as a substitute for CI. They are not. A subagent can find risky code paths and propose tests, but the release gate still belongs in deterministic checks, evals, CI, and human approval for high-risk changes.