Run Claude Subagents as a Team

Claude Code, Anthropic’s coding agent, works better for teams when subagents follow shared repository rules instead of one person’s prompt habits. Treat Claude Code 2.1.186, listed in the official changelog on June 22, 2026, as a good moment to check whether your team conventions still match the way you use agents, MCP, hooks, and review.

A Claude Code subagent is a scoped agent with a job, context, and boundaries that are smaller than the whole repo. Claude Code agent teams need the same thing human teams need: clear ownership, review expectations, and a small set of rules everyone can find.

Start with the release, then update the convention

Read the changelog first, but do not turn every patch release into a repo-wide rewrite. For a Claude team, the useful move is to ask which working agreement changed: should a subagent use a different review path, call an MCP server, run a hook, or load a skill?

This matters because agent behavior becomes team behavior once it lands in a pull request. A backend migration subagent that silently edits generated files, test fixtures, and API docs is not just doing work; it is changing how your repo is maintained.

The trap is chasing version numbers instead of tightening the operating model. For Claude Code 2.1.186, do not assume a new convention is required unless the official changelog or docs point at a workflow you actually use.

Put durable rules in CLAUDE.md

Use CLAUDE.md for durable context the agent should always know in that part of the repository. Put local rules near the code they govern, because a payments package and a docs package rarely need the same agent behavior.

This is the core Claude Code memory habit for teams: keep global guidance short, then scope specific rules to the directory where they matter. A useful root memory might say that PRs need tests, changelog notes, and security review for auth changes; a nested memory in services/billing/ can describe billing invariants.

The trap is turning CLAUDE.md into a scrapbook. Task-specific instructions, one-off debugging notes, and half-finished debates belong in the conversation or the PR, not in long-lived memory.

For a broader path through shared repo context, see the related training topic. If you want a deeper companion piece focused only on subagent norms, read Subagent Conventions for Claude Code Teams.

Give each subagent one job and one review path

Name subagents by responsibility, not by ambition. Good names sound boring: api-contract-reviewer, test-failure-triager, migration-planner, docs-sync-checker.

This matters because Claude agents are easiest to review when their output shape is predictable. A test-failure-triager should summarize failing tests, identify likely causes, and propose the smallest fix; it should not also refactor the data layer.

The trap is making a generalist agent and calling it a team. People exploring claude code agent teams often start with too much autonomy; start instead with narrow roles, visible receipts, and a reviewer who owns the final merge.

Connect hooks, MCP, and permissions to the job

MCP is the integration layer that lets Claude connect to external systems such as GitHub, Slack, document stores, databases, design tools, and internal knowledge bases. Hooks are the guardrails that run at defined points in the workflow, such as before a tool call or after a file change.

Use MCP only when the subagent’s job needs external context. A release-note subagent might read merged PRs from GitHub through MCP; a local test triage subagent may only need the repo and test output.

The trap is giving every subagent every integration. In Claude Code for teams, permissions should explain why access exists, what the agent may read or write, and which human review catches mistakes.

Paste this subagent convention into your repo

Use this as a starting convention in CLAUDE.md, then trim it until it sounds like your team. The block is intentionally small; a convention people actually follow beats a perfect policy nobody reads.

# Claude Code subagent convention

## Scope
Use subagents for bounded work that has a clear owner, input, and review path.
Do not use subagents to bypass code ownership, security review, or release approval.

## Allowed roles
- test-failure-triager: reads test output, proposes the smallest fix, and lists files touched
- api-contract-reviewer: checks API changes against existing clients and migration notes
- docs-sync-checker: compares code changes with docs, examples, and changelog entries
- migration-planner: drafts migration steps but does not apply production data changes

## Required context
Before starting a subagent task, include:
- the goal in one sentence
- the files or directories in scope
- the expected output format
- the reviewer or code owner
- whether MCP access is needed, and why

## MCP and permissions
Subagents may use MCP only for the system named in the task.
Read access must be enough for most tasks.
Write access requires a human-approved issue or PR comment.
Secrets, credentials, customer data, and production databases are out of scope unless the security owner approves the task.

## Hooks
Run repository checks before a PR is marked ready:
- formatter or linter for touched languages
- unit tests for touched packages
- generated-file check when generated artifacts change
- security check for auth, billing, permissions, or data export paths

## Review rule
Every subagent PR must include:
- what the subagent was asked to do
- what it changed
- what it did not check
- test results or a reason tests were not run
- the human reviewer responsible for merge

## Stop conditions
Stop and ask before changing public APIs, database migrations, auth logic, billing behavior, dependency policy, or files outside the stated scope.

The adoption path is simple. A developer proposes this convention in a normal PR, the code owners for the affected area review it, and the final version lives in the nearest relevant CLAUDE.md so local scope wins.

The review rule is the enforcement mechanism. If a PR used a subagent, the reviewer should be able to see the task, scope, tests, missing checks, and any MCP access without reading the whole chat transcript.

If your team later moves beyond prompts into automation through the Claude Code Agent SDK, keep the same convention. The SDK can change how work is launched, but it should not remove ownership, permissions, or review.

Common questions

• What are Claude Code subagents for?

  Claude Code subagents are for bounded jobs that benefit from focused context and a clear output. Use them for tasks like test triage, API review, docs synchronization, or migration planning. The caveat is important: a subagent should have one job, one scope, and one review path, not broad permission to roam the repo.

• How do Claude Code agent teams differ from one big prompt?

  Claude Code agent teams split work into roles that can be reviewed separately. One big prompt often mixes planning, editing, testing, and review in a way that is hard to audit. A practical team convention names each role, states its allowed tools, and requires a short receipt in the PR.

• Should this live in CLAUDE.md or AGENTS.md?

  For Claude Code, put Claude-specific durable context in CLAUDE.md. If your repo also supports other coding agents, an AGENTS.md can hold shared cross-tool rules, while CLAUDE.md keeps Claude Code memory, hooks, permissions, and subagent expectations. Avoid duplicating rules in both places unless you have an owner for keeping them in sync.

• Do we need MCP before we use subagents?

  No, you do not need MCP to start using subagents well. Many useful subagent jobs only need repository files, test output, and a clear review checklist. Add MCP when the job truly needs external context, such as GitHub issues, release notes, design documents, or internal service documentation.

• How strict should hooks be for agent work?

  Hooks should be strict enough to catch predictable mistakes and light enough that engineers keep using them. Start with formatting, linting, unit tests, generated-file checks, and security checks for sensitive paths. The useful number is not more hooks; it is one required check per failure mode your team already sees.

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

Ship the convention in one PR

Pick one repo, one subagent role, and one nested CLAUDE.md to update this week. Then make the review checklist mandatory for any PR that used a subagent.

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.