A Claude Code Subagent Playbook

Use claude code subagents as named, scoped helpers with a clear job, a clear output, and a clear permission boundary. For Claude Code agent teams, the winning move is not “more agents”; it is shared conventions that make agent work reviewable.

Claude Code, Anthropic’s coding agent, can work much better in real repositories when the team writes down how subagents, CLAUDE.md, hooks, skills, and MCP access fit together. A subagent convention is a repo-level agreement that tells Claude which specialist agents may be used, what they may touch, and what evidence they must leave for humans.

Treat subagents as a team convention

Start by deciding which kinds of work deserve a subagent. Good candidates are narrow and repeatable: security review, test repair, migration planning, API contract checks, docs updates, or dependency cleanup.

This matters because subagents can make parallel work feel effortless, but parallel work also multiplies ambiguity. If one agent changes tests while another changes the implementation, reviewers need to know which agent owned which decision.

As of June 2026, the official Claude Code changelog is still the place to verify exact version behavior, including entries like Claude Code 2.1.186 from June 22, 2026. The team habit to build around that is simple: when MCP or integration behavior changes, review your conventions before giving agents wider access.

The trap is treating claude code subagents as a prompt trick. They are closer to lightweight teammates with job descriptions. Put the expectations somewhere durable, then make code review check them.

For a broader operating model, keep this article next to the related training topic and one deeper companion piece, Subagent Conventions for Claude Code Teams.

Put durable rules in CLAUDE.md

Put the durable rules in CLAUDE.md, not in a one-off prompt. The root file should describe repo-wide expectations, while nested CLAUDE.md files can handle local rules for apps/web, packages/api, or infra.

For example, a payments service might tell Claude that API handlers must preserve idempotency keys, database migrations must include rollback notes, and generated tests must avoid live payment provider calls. Those are not task instructions. They are standing constraints.

The trap is turning CLAUDE.md into a junk drawer. Keep it short enough that a new teammate would actually read it. If a rule only matters for one task, put it in the prompt or slash command instead.

A useful Claude Code training exercise is to ask each team to delete 30 percent of its first CLAUDE.md draft. The rules that survive are usually the real conventions.

Give every subagent a boundary

Each subagent should have three things: a role, a tool boundary, and an output contract. “Review auth changes” is vague. “Review auth changes, read only changed files and auth docs, then return risks and missing tests” is usable.

MCP is the integration layer that lets Claude connect to external systems such as GitHub, Slack, Jira, databases, document stores, and private knowledge bases. That makes MCP powerful, but it also means access should be explicit.

A practical pattern is to let a reviewer subagent read GitHub pull requests and internal docs, but not write comments automatically. Let a migration-planner subagent read schema metadata through MCP, but require human approval before generating or applying migrations.

Hooks help with the boring guardrails. A pre-tool or pre-commit hook can block risky paths, require test commands, or stop an agent from touching generated files. The trap is using hooks as a substitute for judgment; hooks should catch obvious mistakes, not encode the whole architecture.

Paste this convention into your repo

Use this as a starter convention. Put it in CLAUDE.md, or split it into a nested CLAUDE.md plus a team review checklist if your repo is large.

# Claude Code subagent convention

## When to use subagents

Use a subagent only when the task has a narrow specialty and a reviewable output.
Good uses:
- Security review of changed auth, payments, or permissions code
- Test repair after an implementation change
- Migration planning for database or API contract changes
- Documentation updates tied to a specific diff
- Dependency cleanup with a written risk summary

Do not use a subagent to make open-ended product, architecture, or ownership decisions.
Ask the human owner first.

## Required subagent contract

Every subagent request must include:
- Role: what specialist perspective the agent should take
- Scope: files, packages, services, or docs it may inspect
- Tools: which MCP servers or repository tools it may use
- Output: the exact artifact expected, such as risks, patch, tests, or checklist
- Stop rule: when it must pause and ask for human review

## MCP and integration rules

- Read access is preferred by default.
- Write access to GitHub, Jira, Slack, databases, or production-like systems requires explicit human approval.
- Agents may summarize external context, but must link or name the artifact they used when possible.
- No subagent may apply migrations, rotate secrets, change permissions, or deploy.

## Hook boundary

Hooks may block unsafe actions, generated-file edits, missing tests, or protected paths.
Hooks should explain the blocked action and the safe next step.
Do not bypass a hook without noting it in the PR.

## Review checklist

Before merging agent-assisted work, the reviewer checks:
- The subagent role and scope were clear
- External MCP context was relevant and allowed
- The final diff matches the requested task
- Tests or verification steps are included
- Risky files have human-owner review
- Any hook bypass or failed command is explained

Adoption should be boring. One engineer proposes the convention in a pull request, the code owners review it, and the final version lives in the root CLAUDE.md with narrower overrides in nested files.

The review rule is what keeps it alive: any PR that uses Claude agents for scoped work must include the subagent role, the files touched, and the verification performed. If the author cannot explain those three things, the team treats the agent output as unreviewed draft work.

Keep skills, commands, and the Agent SDK separate

Claude skills are reusable capabilities. They are a good home for repeatable workflows, scripts, templates, and reference material that should activate on demand.

Slash commands are better for team rituals: “prepare release notes,” “triage flaky test,” or “review API contract.” A command can call the convention, ask for the right inputs, and produce the same shape of output every time.

The Claude Code Agent SDK is a different layer again. Use it when you are building custom agent workflows outside the normal interactive loop, but keep the same contracts: role, scope, tools, output, and stop rule.

The trap is bundling everything into one giant agent definition. Smaller pieces are easier to review. A skill can teach the workflow, a command can start it, a subagent can do the narrow work, and CLAUDE.md can hold the team rules.

Common questions

• How should we use subagents in Claude Code?

  Use subagents for narrow, reviewable work where a specialist perspective helps. A good subagent request names one role, one scope, one tool boundary, and one expected output; without those four pieces, the result is usually harder to review than a normal Claude Code session.

• Do Claude Code subagents replace CLAUDE.md?

  No, subagents do not replace CLAUDE.md; they depend on it. CLAUDE.md should hold durable repository memory and team conventions, while the subagent request should hold task-specific instructions, usually scoped to a single change, package, or review pass.

• Where should MCP permissions live for agent teams in Claude Code?

  MCP permissions should be documented where reviewers will see them, usually in CLAUDE.md plus managed configuration for the environment. The practical caveat is that write access to GitHub, Jira, Slack, databases, or production-like systems should require explicit approval, not just a helpful-sounding prompt.

• Should hooks enforce our subagent rules?

  Yes, hooks should enforce the parts of your subagent rules that are mechanical. Use them for protected paths, missing test commands, generated-file edits, or dangerous tool use; keep architecture judgment, risk acceptance, and product decisions in human review.

• Do we need the Claude Code Agent SDK for this?

  No, you can start with CLAUDE.md, subagent prompts, hooks, and MCP configuration before using the Claude Code Agent SDK. Reach for the SDK when you need custom orchestration or repeatable agent workflows outside an interactive coding session.

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
• Claude Code — changelog

Make the next PR easier to review

Pick one subagent use case this week, add the convention above to your repo, and require the three-line review note on the next agent-assisted PR. Small, visible habits beat a perfect policy nobody opens.

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.