Claude Code subagents best practices for team governance

Claude Code subagents best practices matter most when a team moves from individual experimentation to shared automation. A subagent can keep noisy research, log reading, and review work out of the main conversation. It can also create unmanaged tool access, extra model spend, and hard-to-audit decisions if every developer imports public agent files without review.

For a platform or security lead, the right question is not "How many subagents can we create?" It is "Which tasks deserve isolated workers, what can those workers touch, and how do humans review their output?"

The practical baseline is small: keep a reviewed project library in .claude/agents/, start with read-only agents, require clear handoff contracts, and treat subagent output as untrusted until tests, code review, and permission controls support it.

Start with the decision rule

Anthropic defines subagents as specialized assistants with their own context window, custom system prompt, specific tool access, and independent permissions. That makes them useful for side tasks that would otherwise flood the main thread with file reads, logs, web pages, command output, or exploratory notes.

The distinction matters because teams often blur subagents with skills, commands, plugins, and plain prompts. Community discussion around Claude Code shows that best practices are still forming, and one Hacker News commenter summarized the state plainly: "no clear best practices seem to have emerged yet."

Use this rule when setting team policy:

Internal link suggestion: Link "skills, commands, plugins, and plain prompts" to a future explainer comparing Claude Code extension points.

The team baseline: five approved agents, not fifty

A large agent catalog looks productive until the team has to audit it. The VoltAgent public repository listed 154+ Claude Code subagents across 10 categories and 23.5k stars when accessed, which shows strong demand for ready-made roles. It also shows why teams need restraint. Public catalogs are useful as reference material, not as production policy.

Start with a small shared library. Five agents are enough for most teams to learn what works without creating prompt sprawl.

This starter set matches the strongest subagent pattern: separate lanes of analysis that return findings. A Claude Code team member in a Hacker News discussion described the built-in /code-review direction as using independent subagents for multiple review angles, with the prompt balanced for "precision, recall, and cost." That is a useful signal, but it is not a promise that subagents catch every issue. Teams still need measurement.

Claude Code subagents best practices for permissions

Permissions are the governance center of subagent design. Anthropic explicitly recommends focused subagents and limited tool access. If the tools field is omitted, access can inherit from the current session, which is rarely the right default for shared team agents.

For project agents, require every agent file to state its tool access. Broad examples from public catalogs often include Read, Write, Edit, Bash, Glob, and Grep. That may be convenient for a personal experiment, but it is too permissive for a shared reviewer unless the workflow truly edits code.

Anthropic's security guidance recommends managed settings to enforce organizational standards. It also recommends approved permission configurations in version control, OpenTelemetry metrics, ConfigChange hooks, dev containers for sensitive repositories, and regular /permissions audits. Those controls apply directly to subagent governance because subagents are another path to tool execution.

Internal link suggestion: Link "regular /permissions audits" to an internal article on Claude Code hooks and permissions.

Project agents should be treated like code

Claude Code supports custom subagents as Markdown files with YAML frontmatter. Only name and description are required, but team-relevant controls include tools, disallowedTools, model, permissionMode, maxTurns, mcpServers, hooks, skills, memory, background, effort, and isolation.

Scope precedence also matters. Managed settings have highest precedence, followed by --agents CLI definitions, project .claude/agents/, user ~/.claude/agents/, and plugin agents. For a team, project agents should live in version control so changes are reviewed, attributed, and reversible.

A workable governance model has four parts:

• Ownership: every shared subagent has an owner or owning team.
• Promotion: personal agents stay in ~/.claude/agents/ until a pull request promotes them to the project library.
• Review: changes to descriptions, tools, MCP access, hooks, models, and permission modes require the same scrutiny as code that changes deployment or data access.
• Deprecation: stale agents are removed or renamed intentionally so developers do not keep invoking old behavior.

The description field deserves special review. Claude uses it to decide when to delegate. A vague role such as "senior security expert" can trigger in the wrong places. A better description starts with "Use when..." and names the exact task, inputs, allowed files or systems, and expected output.

Use isolation for write-capable work

Read-only agents are easier to defend because they create reports, not changes. Write-capable subagents need a higher bar. Claude Code supports isolated git worktrees with isolation: worktree, which is relevant when background or write-capable agents might collide with the main checkout.

A conservative rule is simple: if a shared subagent can write, edit, or run background work, require worktree isolation unless there is a documented reason not to. That does not make the output correct, but it reduces checkout collisions and makes the resulting diff easier to inspect.

Nested subagents also need limits. Anthropic docs say a subagent at depth five does not receive the Agent tool and cannot spawn further. Teams should still avoid nested delegation for sensitive workflows unless transcripts and handoffs make the chain clear enough to review.

Cost and model routing are design choices

Subagents can save context in the main conversation, but parallel work multiplies model calls. Treat model choice as part of the agent definition, not as an afterthought.

Anthropic says enterprise Claude Code deployments average around $13 per developer per active day and $150 to $250 per developer per month, while 90% of users stay below $30 per active day. For simple subagent tasks, Anthropic recommends model: haiku. Team policies should convert that guidance into routing rules.

Use /usage where available to attribute recent usage to skills, subagents, plugins, and MCP servers. Team and Enterprise analytics can track daily active users, sessions, suggestion accept rate, accepted lines, pull requests with Claude Code, and spend reports. Those metrics help answer the practical question: did the subagent reduce review time and context load, or did it add cost without better outcomes?

Internal link suggestion: Link "did it add cost without better outcomes" to a cost monitoring guide for coding agents.

Handoff contracts make subagents reviewable

A subagent that returns a polished paragraph but hides what it inspected is hard to trust. The main conversation should receive a compact handoff that humans can audit.

Standardize this output for every shared subagent:

• Task interpreted: what the agent believes it was asked to do.
• Files inspected: exact files or directories reviewed.
• Commands run: command names and purpose, not a full transcript unless needed.
• Assumptions: facts the agent relied on but did not prove.
• Findings: severity, evidence, and affected files.
• Confidence: high, medium, or low, with one sentence explaining why.
• Unresolved risks: what still needs human review or tests.
• Next action: one concrete recommendation.

This format also helps the main agent synthesize multiple review lanes. Security, architecture, performance, migration, and test reviewers can each return structured findings, then the main conversation can prioritize them. The goal is not to produce more text. The goal is to make each claim traceable.

Hooks help, but they are also code

Anthropic's hooks documentation includes events such as SubagentStart and SubagentStop, prompt hooks, agent hooks, and blocking behavior. The brief notes one strong pattern: a database query validator can use a PreToolUse hook that blocks write operations. Anthropic's example exits with code 2 to block statements such as INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE, REPLACE, and MERGE.

That is a useful control because it is deterministic. It does not ask the model to remember a policy. It enforces one.

But hooks are also an attack surface. Hook scripts should be reviewed, sanitized, path-safe, and maintained with the same discipline as other automation. Anthropic notes that agent hooks are experimental and that production workflows should prefer command hooks. A team policy should reflect that difference.

Treat subagent output as untrusted

Claude Code v2.1.210+ scans subagent output for instruction-shaped patterns. That scan is useful, but it is not a substitute for least privilege. A subagent that can read sensitive systems, call broad MCP servers, or run powerful shell commands still needs explicit boundaries.

The safest operating model is boring by design:

• Read-only first for shared agents.
• No MCP access unless the server and data scope are approved.
• No write access for review agents.
• No broad Bash access without hooks, command review, and logging.
• Dev containers for sensitive repositories where isolation matters.
• Managed settings for organization-wide standards.
• Regular permission audits with evidence, not memory.

This is especially important for community agent packs. A public agent can contain broad permissions, vague role language, or optimistic checklist claims. Strip it down before adoption: rewrite the description, remove unnecessary tools, choose the model route, define the handoff schema, and add organization-specific controls.

Roll out with metrics, not belief

Start with one repository and one team. Pick two or three read-only agents from the starter set and run them for a defined pilot period. Do not begin with a wide internal marketplace of agents. That creates too many variables.

Measure a small set of outcomes:

Community users have pushed back on broad claims for expensive review modes. Treat that skepticism as useful operating advice. Independent review lanes can improve coverage, but teams should measure misses, false positives, cost, and accepted output before expanding the library.

A practical policy template

A minimal team policy for Claude Code subagents can fit on one page:

1. Shared subagents live in .claude/agents/ and are reviewed through pull requests.
2. Every subagent has an owner, clear "Use when..." description, explicit tools, model route, and maxTurns.
3. Review and research agents are read-only by default.
4. Write, Edit, broad Bash, MCP access, and permission exceptions require documented approval.
5. Write-capable and background agents use isolation: worktree unless an exception is approved.
6. Hooks used as controls are reviewed as code and kept deterministic.
7. Every subagent returns the standard handoff contract.
8. Usage, cost, accepted output, and permission exceptions are reviewed during rollout.
9. Public subagents are treated as examples until stripped down, reviewed, and adapted to the organization.

This policy is intentionally small. The point is to make safe use the default path, then let teams request exceptions when a workflow proves its value.

Govern the worker, not the label

Subagents are best understood as isolated workers with clean context, tool boundaries, and a handoff back to the main conversation. That makes them valuable for codebase exploration, independent review lanes, test and log analysis, and tightly scoped validators.

The risk is not the word "subagent." The risk is unmanaged automation: inherited permissions, public agent packs imported without review, vague descriptions that over-trigger, write-capable workers in the main checkout, and outputs that humans cannot trace.

For platform and security leads, the durable standard is clear: small library, least privilege, reviewed project files, explicit model routing, worktree isolation for edits, measurable outcomes, and handoffs that make every finding auditable.