Set Up Claude Code Agent Teams

Do not start a Claude Code agent team by asking several agents to look around. Claude Code agent teams work when the team convention says who owns the plan, which Claude Code subagents may edit, how they hand off work, and what evidence reviewers must see before merge.

In Claude Code training, I make this boring on purpose. When teams ask for agent teams Claude Code conventions, I steer them toward one lead session, bounded worker sessions, and a review rule that survives the first busy sprint.

Start with one lead session

Give one Claude Code session the job of planning and merging the work. That session decides the slices, names the files or packages each worker may touch, and keeps the final pull request coherent.

Claude agents should not all share the same broad mission. If every worker can rewrite the API layer, tests, and docs, you have parallel activity without ownership.

This sits in the Delegate and Review parts of our methodology: delegate a narrow slice, then review the evidence before accepting the result. The lead session is responsible for that evidence, not just for a green final diff.

Choose the agent shape before work starts

As of November 2026, the Claude Code docs cover agent teams, custom subagents, agent view, cross-session messaging, dynamic workflows, worktrees, skills, hooks, MCP, and the Claude Code Agent SDK. The practical choice is not whether to use all of them. The choice is how much autonomy the change deserves.

For a normal GitHub pull request workflow, I would split a checkout bug like this: one worker inspects failing tests, one worker changes the pricing path, and the lead session writes the PR summary and asks for the exact test command output. That is concrete enough for review and small enough to recover if one worker goes wrong.

Split work where the repo can prove it

Use repo boundaries that your tools can verify. Packages, directories, test suites, generated clients, migrations, and docs pages are better boundaries than vague roles like backend agent or quality agent.

Keep durable repo constraints in CLAUDE.md if your team already uses it, but do not make the memory file carry the whole operating model. The agent team convention should live near the workflow that invokes it, so people can change it when the PR process changes.

A good slice sounds like: worker A may edit src/checkout/pricing.ts and its tests; worker B may inspect docs and propose wording only; the lead may merge both after running npm test -- checkout. That gives the reviewer a path to verify the work without replaying the chat.

Bound integrations before agents run

MCP is the integration route to external systems such as GitHub, issue trackers, document stores, and databases. For agent teams, the rule should be stricter than for a single session, because mistakes can happen in parallel.

Start read-only unless the task needs writes. If an agent needs GitHub access, decide which operations are allowed before the run, and keep the permission note with the PR workflow. I covered that boundary in more detail in Claude Code GitHub MCP Permissions.

Hooks are useful when the rule must run every time, such as blocking a commit when tests were not run or when a worker touched files outside its slice. Do not use hooks to hide unclear ownership. Fix the convention first.

Paste this operating checklist

# Claude Code agent team convention

Owner: lead Claude Code session
Applies to: pull requests using two or more Claude Code workers or subagents

Before starting
- Name the change in one sentence.
- Name the lead session.
- List each worker and its allowed files, directories, or commands.
- Mark each MCP server as read-only, write-approved, or unavailable.
- Decide whether workers share a branch or use separate worktrees.

During the run
- The lead assigns one slice at a time.
- Workers report changed files, commands run, and open questions.
- Workers do not expand scope without lead approval.
- Any worker that needs new permissions pauses and asks.

Before opening or updating the PR
- The lead reviews each worker diff.
- The lead resolves conflicts and removes duplicate work.
- The lead runs the agreed test command.
- The PR description includes changed areas, test evidence, and known limits.

Do not use an agent team when
- The task is smaller than the coordination cost.
- The repo boundary is unclear.
- Required write permissions have not been approved.
- No human reviewer is available for the final diff.

Adoption path: propose this as a small workflow rule, not as a platform change. Put it with your Team conventions, ask one maintainer and one frequent Claude Code user to review it, then run it on a low-risk PR before making it default.

Review rule: a pull request that used a Claude Code agent team should say which workers ran, what each changed, which commands passed, and which permissions were used. If that evidence is missing, review the PR as incomplete even when the diff looks plausible.

Further reading

• Claude Code docs
• Claude Code skills
• Claude Code hooks

Run it once on a small change

Take one open bug with a clear test path and run this convention once before using it on larger work; if you want a facilitated version, use our hands-on training for Claude Code team workflow practice.