Subagent Conventions for Claude Code Teams

Use Claude Code subagents when work can be split into bounded roles with clear inputs, permissions, and review rules. For a team, the winning move is to define those roles in repository conventions first, then let subagents, hooks, MCP, and skills follow the convention.

Claude Code, Anthropic's coding agent, works best in teams when shared context is written down instead of repeated in chat. A Claude Code subagent is a specialized agent role with a narrow job, its own context, and an expected output that another human or agent can review.

As of June 2026, the official Claude Code 2.1.186 changelog belongs in the MCP and integrations lane, so treat it as a good moment to check your integration boundaries. This is exactly the kind of topic we cover in the related training topic: make the team habit visible, copyable, and reviewable.

Start with the convention, not another agent

Decide what your Claude Code team is allowed to delegate before you add more Claude agents. In practice, Claude Code agent teams work best when each agent owns a repeatable slice of work: test triage, API migration, documentation cleanup, security review, or release-note drafting.

The convention should live close to the code. Put durable repository rules in CLAUDE.md, keep local rules in nested CLAUDE.md files when one package differs from another, and leave task-specific instructions in the prompt or issue.

The trap is treating subagents as a productivity shortcut for vague work. If nobody can say what the agent should read, change, avoid, and hand back, the role is not ready.

Copy this operating convention into your repo

Paste this into CLAUDE.md or adapt it into a nested CLAUDE.md for one service. It gives claude code subagents enough structure to be useful without pretending they are exempt from review.

# Claude Code Team Convention

## When to use subagents

Use a subagent only when the task has a bounded role and a reviewable output.
Good fits:
- Test failure triage
- Mechanical refactors inside one package
- Documentation updates from merged code
- Security or permissions review
- Migration planning with no code changes

Do not use a subagent for:
- Product decisions without an issue owner
- Cross-service changes without an explicit plan
- Secrets, credentials, or customer data inspection
- Unreviewed production config changes

## Shared context

Claude should read this file before starting repo work.
Package-specific rules live in the nearest nested CLAUDE.md.
Task-specific constraints belong in the prompt or issue, not in long-term memory.

## MCP and integration boundaries

Allowed MCP usage:
- GitHub: read issues, PRs, diffs, and CI status
- Jira: read linked ticket requirements
- Docs store: read architecture docs tagged for this repo

Ask before:
- Writing to external systems
- Creating or editing tickets
- Reading private documents not linked from the task
- Running commands that touch production-like data

## Hooks

Before code changes are proposed, run formatting and the package test command.
Before a commit or PR summary, include:
- Files changed
- Tests run
- Known risks
- Follow-up work

Hooks may block formatting, lint, test, or permission violations.
Hooks should not silently rewrite business logic.

## Review expectations

Every agent-produced change gets the same review bar as human-authored code.
The reviewer checks:
- The diff matches the issue
- The right CLAUDE.md scope was followed
- MCP access was appropriate
- Tests are named in the summary
- Risky assumptions are called out

## Subagent output format

Each subagent must end with:
- Decision or change made
- Evidence used
- Files touched or inspected
- Tests run or not run
- Human decision still needed

This is intentionally plain. Fancy orchestration can come later; the first useful artifact is a shared agreement your next reviewer can enforce.

Adopt it like code

Have the person proposing the agent workflow open a normal pull request. The PR should include the CLAUDE.md change, one example prompt, and one example output from a dry run on a low-risk task.

Ask the code owner for the affected package to review it. If the convention touches MCP permissions, hooks, or data access, add the security or platform owner too.

The file should live where the rule applies. A root CLAUDE.md is good for repo-wide expectations; a nested services/billing/CLAUDE.md is better for billing-specific invariants like idempotency keys, ledger constraints, or audit logging.

The trap is approving a convention in a meeting and never landing it in the repo. If it is not versioned, diffed, and reviewed, it will drift by Friday.

Keep MCP and hooks boring

MCP is the integration layer that lets Claude connect to external tools and context sources, such as GitHub, issue trackers, document stores, databases, or private knowledge bases. In Claude Code for teams, MCP should be treated like any other integration boundary: useful, permissioned, and easy to audit.

Start with read-only access for most workflows. Let a subagent read PR diffs, CI logs, and linked architecture docs before you let it create tickets, update project status, or write to a database-backed tool.

Hooks should enforce the parts humans forget. A pre-submit hook can require tests, block forbidden paths, or ask for confirmation before a risky command; it should not become a hidden second agent that changes code behind the reviewer’s back.

If you later use skills, slash commands, or the Claude Code Agent SDK, keep the same boundary. The interface can change, but the convention should still answer who proposed the action, what context was used, what changed, and who reviews it.

Review agent work with a visible checklist

The review rule is simple: subagent work is reviewed like teammate work, with one extra question about context. The reviewer should be able to see what the agent used, what it ignored, and where a human decision remains.

For a real workflow, imagine a payments service refactor. A test-triage subagent reads failing CI logs and services/payments/CLAUDE.md, proposes that a flaky fixture is sharing state, changes only the test fixture, runs the package test command, and leaves a summary with the risk that it did not inspect production code.

That is reviewable. A subagent that says “fixed payments tests” and touches five unrelated files is not.

A lightweight team pattern is to require this checklist in every PR summary:

• Did the agent follow the nearest CLAUDE.md?
• Which MCP tools or external systems were used?
• Which files were inspected but not changed?
• Which tests ran, and what failed?
• What assumption needs human confirmation?

For a broader operating model, pair this with Team Conventions for Claude Code so memory, review, and adoption patterns do not become three separate conversations.

Common questions

• When should I use Claude Code subagents instead of one main session?

  Use subagents when the work splits into independent roles with clear outputs. A good rule is one role, one scope, one handoff: for example, one agent investigates failing tests while another drafts docs from the final diff, but neither merges code without the normal review path.

• Do agent teams in Claude Code replace code review?

  No, agent teams Claude Code workflows should make review easier, not optional. The minimum review artifact is a summary that names files touched, tests run, MCP tools used, and any human decision still needed before merge.

• Should CLAUDE.md include every prompt we like?

  No, CLAUDE.md should hold durable repo rules, architecture constraints, and team conventions. Put temporary task instructions in the issue, prompt, or PR description so the repository memory stays short enough for people and Claude to actually follow.

• How strict should MCP permissions be for Claude Code enterprise teams?

  Start stricter than you think, especially around write access and sensitive systems. Read access to linked issues and CI logs is often enough for early workflows; writes to trackers, databases, document stores, or production-adjacent tools should have explicit approval and audit expectations.

• Where do skills fit with subagents and conventions?

  Claude skills package repeatable workflows and reference material, while subagents provide specialized execution roles. Use skills for reusable know-how, CLAUDE.md for repo rules, and subagents for bounded work that produces a reviewable handoff.

Further reading

• Claude Code — getting started
• Claude Code — skills
• Claude Code — hooks
• Claude Code — permissions
• Model Context Protocol — specification
• Anthropic — Claude Code product page
• GitHub — anthropics/skills

Make the next run boring

Pick one low-risk workflow this week, add the convention to CLAUDE.md, and run it through a normal PR review. If the reviewer can understand the agent’s scope, tools, tests, and remaining risks in under two minutes, you are on the right path.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.