How to enable agent teams in Claude Code

You enable agent teams in Claude Code by writing down the rules a human team already follows, then handing the agents the same playbook. An agent team is a coordinated group of Claude agents and subagents that share your repository instructions, tool permissions, and review rules so parallel work happens without hiding risk. Claude Code, Anthropic's coding agent, can move fast in parallel, but only when your team owns the operating model around it.

The trick is not the parallelism. It is the contract. Give the agents a clear CLAUDE.md, scoped roles, hooks around risky actions, an MCP allow-list, and a review receipt, and the speed becomes safe to use.

Skip the loose prompt that ends in archaeology

Most teams start with "spin up some agents and fix the issue." It feels quick. Then three agents edit the same files, one misses a local convention, and your review turns into digging through chat logs to figure out what happened.

The problem is usually missing context, not model quality. CLAUDE.md is too vague, subagents have no names, hooks are absent, MCP access is wider than the task needs, and the pull request arrives with no record of what the agents did.

So narrow the work instead of widening the autonomy. As of June 15, 2026, the Claude Code changelog lists version 2.1.178, which tells you what product surface exists. It does not tell your team who is allowed to change schema files, bump dependencies, or merge generated code. That part is yours to decide.

Write a CLAUDE.md your team will actually keep

Start with memory. A root CLAUDE.md that says "follow our conventions" gives an agent nothing to act on. Write a short, durable file that names your architecture boundaries, test commands, code style, and forbidden shortcuts. Keep ticket-specific notes out of it. Memory should carry the rules that outlive any one task.

Then name your roles. If every agent has the same vague job, you cannot reason about coverage. Give them names: implementer, reviewer, test writer, migration scout, docs updater. The Claude Code docs on subagents let you make delegation visible instead of magical, so a reviewer can see who did what.

Add hooks for the things that should never depend on memory. Use hooks to block unsafe file paths, require tests before an agent calls itself done, or log tool use for later review. Hooks are not culture. They are the guardrail for the moments when culture is too slow to catch a mistake.

Keep MCP and review scoped to the task

MCP is useful because it gives Claude Code a standard way to reach issue trackers, code hosts, and internal services. That same reach is the risk. Connect systems per workflow, not all at once, and match access to the agent's role. Your implementer does not need the production database, and the MCP specification makes it easy to be precise about this.

Review is the last failure mode, and the sneakiest. Agent output looks finished before anyone understands it. The fix is a review receipt: what changed, which role did it, what was tested, what was not, and which files a human should read closely. The reviewer should see the shape of the work before reading a single diff line.

One repo, one workflow, one artifact. Do not roll agent teams across ten services before one service can review them cleanly. If you are building an internal training path, anchor it in team conventions rather than one-off prompt tricks.

Copy this operating checklist into your repo

Here is a starter CLAUDE.md fragment plus a review checklist. Keep it short enough that engineers will keep it current.

# CLAUDE.md: agent-team operating rules

## Repository context
- Primary application: <name and purpose>
- Main language/runtime: <language, version, package manager>
- Architecture boundary: <service/module boundaries agents must respect>
- Do not edit without human approval: <schema, auth, billing, infra, generated files>

## Agent roles allowed in this repo
- implementer: may edit feature code and local tests for the assigned ticket
- reviewer: may inspect diffs, identify risks, and suggest changes; does not rewrite broad areas
- test-writer: may add or update tests; must not weaken assertions to pass
- docs-updater: may update docs tied to changed behavior only

## Tool and integration boundaries
- MCP servers allowed for this workflow: <github/jira/docs/etc.>
- MCP servers not allowed for this workflow: <prod database/secrets/etc.>
- Commands that require approval: <migration, deploy, dependency upgrade, destructive file operation>
- Hook checks expected before completion: <format, lint, unit tests, forbidden paths>

## Review receipt required in every agent-assisted PR
- Agent roles used:
- Files intentionally changed:
- Tests run and result:
- Tests not run and why:
- Risk areas for human review:
- Follow-up work not included:

This artifact is deliberately plain. You can convert pieces into skills, slash commands, hooks, or plugin packaging later. Start with the contract a human can read in one sitting.

Common questions

• How do I enable agent teams in Claude Code without a swarm?

  Turn each rule into one visible team convention, not a loose preference. Write a short CLAUDE.md, name your agent roles, add hooks around risky actions, scope MCP access per workflow, and require a review receipt on every PR. One owner should be able to reject agent output when the evidence is missing.

• Which Claude Code artifact should we standardize first?

  Standardize the smallest artifact your reviewers already touch: a CLAUDE.md note, a hook checklist, or an MCP permission rule. The goal is not documentation volume. It is one shared place where scope, allowed tools, expected tests, and rollback notes are visible before generated code reaches review.

• How do we know the convention is actually working?

  It works when reviewers can approve or reject agent output from the artifact and the evidence alone. Track whether pull requests name the rule they followed, include the promised checks, and let a reviewer understand the change without replaying the whole chat session.

• Do hooks replace a code review?

  No. Hooks catch the mechanical failures: unsafe paths, missing tests, skipped formatting. They run the same way every time, which is their value. A human reviewer still judges intent, scope, and the risks a hook cannot see, so keep both in the loop rather than trading one for the other.

Start with one workflow

Pick a single repo, write the CLAUDE.md fragment above, and require the review receipt on the next agent-assisted PR. Then take it into team conventions and check whether a new reviewer can defend the merge without replaying the chat.

Further reading

• Claude Code docs: getting started
• Claude Code docs: skills
• Claude Code docs: hooks
• Claude Code docs: permissions
• MCP specification 2025-11-25
• Claude Code product page
• Anthropic skills on GitHub