Claude Code subagents for teams: three reviewers worth committing

Most teams that use Claude Code start with one shared file: a CLAUDE.md with the build commands, the conventions and the things nobody should do. That covers what every session needs. It doesn't cover the specialist jobs, such as reviewing a change against the team's standards, running the test suite until it passes, or checking a diff for leaked secrets.

Those jobs are what subagents are for. This post covers what a subagent is, where a team should keep them, and three worth committing to your repository.

What a subagent is

A subagent is a Markdown file with a short header. The header names it, says when Claude should use it and which tools it may use. The body is its instructions.

---
name: code-reviewer
description: "Reviews changes against this team's conventions. Use proactively after any code change."
tools: Read, Grep, Glob, Bash
---

You review code changes in this repository...

The difference from a normal prompt is isolation. In the docs' words, each subagent "runs in its own context window with a custom system prompt, specific tool access, and independent permissions." It does its work, such as reading forty files or a long test log, and hands back only a summary. Your main session stays short and focused.

A subagent still reads your CLAUDE.md files when it starts, so it follows the same team rules as the main session. You don't have to repeat them in every subagent.

Commit them where the team gets them

Subagents live in one of two places:

• .claude/agents/ in the repository, for the whole team. The docs recommend checking these into version control "so your team can use and improve them collaboratively."
• ~/.claude/agents/ in your home folder, for personal ones that follow you across projects.

If both define a subagent with the same name, the project one wins. That is the behavior a team wants: the shared reviewer is the reviewer, and a personal file with the same name doesn't quietly replace it.

Treat changes to .claude/agents/ like code. A subagent with write access and a vague prompt can do as much damage as a bad script, so put the folder under CODEOWNERS and review edits in pull requests.

Limit what each one can do

Without a tools line, a subagent inherits the tools of the main session. For a team file, be explicit. Two fields do the work:

• tools is an allowlist. A reviewer that only needs to read gets Read, Grep, Glob, and nothing that edits files.
• disallowedTools removes tools from what it would otherwise inherit, for example disallowedTools: Write, Edit for a subagent that should look but never touch.

Read-only reviewers are the safest place to start. They can't break anything, and their output is a report a human reads.

Write descriptions Claude acts on

Claude decides when to delegate from the description field. Write it as a trigger, not a job title. "Security reviewer" says what it is. "Checks a diff for secrets, unsafe queries and missing auth checks. Use proactively before any commit that touches auth or payments" says when to use it.

The docs suggest adding phrases like "use proactively" when you want Claude to delegate without being asked. Keep descriptions short too: they all load into context, and Claude Code warns at startup when the combined descriptions pass 15,000 tokens.

Anyone can also call a subagent by name: "Have the code-reviewer subagent look at my recent changes", or with an @-mention such as @agent-code-reviewer.

Three subagents worth committing

1. A code reviewer that knows your standards. Read-only. Its prompt lists what your team rejects in review: the patterns you moved away from, the error handling you expect, the naming rules. It reads the diff and reports problems with file and line. Human reviewers then spend their time on design rather than on the same five comments.

---
name: code-reviewer
description: Reviews the current diff against this team's conventions. Use proactively after code changes, before a pull request.
tools: Read, Grep, Glob, Bash
---

Review the changes from `git diff main...HEAD`. For each problem, give the
file, the line and the rule it breaks. Check: error handling, naming,
tests for new behavior, and anything in the "Things to avoid" section of
CLAUDE.md. Report only. Do not edit files.

2. A test runner that fixes its own failures. This one needs to edit, so it gets the edit tools but a narrow job: run the suite, read the failures, fix the code or the test, and run again until it passes or it's stuck. The long test output stays in its context, not yours. Say in the prompt that it must never delete or skip a failing test to get green.

3. A security check for sensitive paths. Read-only, with a description that names the folders that matter: auth, payments, anything that handles personal data. It looks for secrets in the diff, queries built from user input, missing permission checks and new dependencies. It won't replace a security review, but it catches the obvious mistakes before a human sees them.

Two details that save trouble

Start read-only. A reviewer that reports is useful from day one and can't do harm. Give a subagent edit access only when its job requires it, and keep that job narrow.

One job per subagent. A "full-stack expert" with every tool and a long prompt is just the main session again with less context. Small subagents with sharp descriptions get picked for the right tasks.

Where to start

Look at your last ten review comments. The ones that repeat are your code reviewer's prompt. Write it, keep it read-only, commit it to .claude/agents/, and run it on your next change.

The subagents only work as well as the shared rules underneath them, so the CLAUDE.md comes first. AI Workspace Builder generates one from the docs your team already has, along with a profile for each role and an install script, using your own Anthropic API key. No docs yet? Answer a short questionnaire and download a starter CLAUDE.md, no signup needed.