In this article

🧩 What a Claude Code subagent is

A subagent is a specialised assistant that Claude Code starts in a separate context. It has its own system prompt, its own tools and, if you want, its own model. It does the work, and only the final report goes back to the main session.

The benefit is twofold. The main session does not fill up with files read and command output. And I can remove the tools a subagent does not need: a reviewer that cannot write cannot damage the code.

  • Markdown file: a subagent is a .md file with YAML frontmatter and the prompt in the body.
  • Only name and description are required: the description tells Claude when to delegate.
  • Tools are inherited when omitted: to limit them I use tools (allowlist) or disallowedTools (denylist).

🎯 Why a read-only reviewer

If I ask Claude to review the code it just wrote, the review happens in the same conversation: it sees its own assumptions and tends to confirm them. A subagent starts from a clean context and looks only at the diff.

I remove the write tools from this subagent. Its only effect is a report: no "quick fix" that escapes review. I decide the fixes in the main session.

Review in the session vs. reviewer subagent

Review in the same session

  • Same context, same assumptions
  • Can edit files while reviewing
  • The conversation fills up with reads

Read-only subagent

  • Clean context, diff only
  • No write tools
  • One report comes back

The line between who judges and who edits is a configuration file.

πŸ—‚οΈ Where subagent files live

A project subagent lives in .claude/agents/ and is committed to the repository: the same file applies to the whole team. A personal one lives in ~/.claude/agents/ and applies to every project.

With the same name, the higher-priority location wins: first the organisation-managed configuration, then the --agents flag, then .claude/agents/, then ~/.claude/agents/, and finally plugins. Subfolders are scanned recursively.

πŸ› οΈ The sample project: a Minimal API

I start from a small ASP.NET Core Minimal API for orders. It contains a deliberate weakness: DiscountPercent is not validated, so 150 produces a negative total. The reviewer has to find it.

There is one write endpoint, a static calculator and one xUnit test that passes. The project builds with .NET 8.

OrderCalculator.cs Β· C#
namespace OrdersApi.Orders;

public static class OrderCalculator
{
    // Intentionally imperfect: the review agent should flag the missing validation.
    public static decimal Total(IReadOnlyList<OrderLine> lines, int discountPercent)
    {
        var subtotal = lines.Sum(l => l.Quantity * l.UnitPrice);
        return subtotal - subtotal * discountPercent / 100;
    }
}
The calculation does not check the discount range. Full code in the repo: https://github.com/fscamuzzi/claude-code-subagent-reviewer-dotnet

πŸ”’ Writing code-reviewer.md

The frontmatter does three things. tools lists what the reviewer can use. disallowedTools explicitly removes the write tools. description contains "use proactively", which encourages Claude to delegate after every change.

The body is the system prompt. I enforce a fixed report format: BLOCKER, WARNING, NIT and a final verdict. A fixed format makes the report easy to read and to check with a script.

Note: Bash is not read-only by itself. The prompt asks to use it only for git, but that is a prompt rule, not a constraint. For a hard constraint I drop Bash and pass the diff in the prompt.

.claude/agents/code-reviewer.md
---
name: code-reviewer
description: Read-only reviewer for C# / ASP.NET Core changes. Use proactively after code is written or modified, before committing.
tools: Read, Grep, Glob, Bash
disallowedTools: Edit, Write, NotebookEdit
model: sonnet
color: blue
---

You are a senior .NET reviewer. You never modify files.
Use Bash only for `git diff`, `git status` and `git log`.

Process:

1. Run `git diff` to see the change. If it is empty, review `src/`.
2. Read the touched files in full before judging them.
3. Check, in this order: correctness, input validation, error handling, concurrency, test coverage.

Report format (and nothing else):

- `BLOCKER` / `WARNING` / `NIT`, one per line.
- Each line: `path:line - problem - suggested fix`.
- Final line: `VERDICT: approve` or `VERDICT: changes requested`.

Create custom subagents Β· Claude Code Docs β†—

The review agent: limited tools and a fixed report format. Full code in the repo: https://github.com/fscamuzzi/claude-code-subagent-reviewer-dotnet

πŸ§ͺ Writing test-writer.md

The second subagent writes tests. It needs Edit and Write, but the prompt rule limits them to tests/. If a test fails because of a bug in src/, it does not fix it: it reports it.

I separate the roles on purpose: who finds the problem (reviewer), who covers it with a test (test-writer), who fixes it (main session). Each step has a different report and tool boundary.

.claude/agents/test-writer.md
---
name: test-writer
description: Writes and runs xUnit tests for a given class or endpoint. Use when a change has no test or a review reports missing coverage.
tools: Read, Grep, Glob, Edit, Write, Bash
model: sonnet
color: green
---

You write xUnit tests for ASP.NET Core code.

Rules:

- Touch only files under `tests/`. Never edit `src/`.
- One behaviour per test. Name: `Method_Condition_Expected`.
- Run `dotnet test` after writing. Report the pass/fail count.
- If a test fails because of a bug in `src/`, do not fix it. Report the bug.

Create custom subagents Β· Claude Code Docs β†—

The `tests/` perimeter is a prompt rule: I check it in review. Full code in the repo: https://github.com/fscamuzzi/claude-code-subagent-reviewer-dotnet

βœ… Validating the files with a script

Agent files are configuration: a typo in the frontmatter and the subagent loses a field. Field names are case-sensitive and unknown ones are silently ignored.

For this reason I put a dependency-free Node script in the repo. It checks name, description, that the name matches the file, and that the reviewer has no write tools.

scripts/validate-agents.mjs
#!/usr/bin/env node
// Validates .claude/agents/*.md: required frontmatter, read-only guarantee for reviewers.
import { readdirSync, readFileSync } from "node:fs";
import { join } from "node:path";

const dir = ".claude/agents";
const WRITE_TOOLS = ["Edit", "Write", "NotebookEdit"];
let failed = false;

for (const file of readdirSync(dir).filter((f) => f.endsWith(".md"))) {
  const text = readFileSync(join(dir, file), "utf8");
  const match = text.match(/^---\n([\s\S]*?)\n---\n/);
  const fail = (msg) => {
    console.error(`FAIL ${file}: ${msg}`);
    failed = true;
  };
  if (!match) {
    fail("missing frontmatter");
    continue;
  }
  const fields = Object.fromEntries(
    match[1].split("\n").map((l) => [l.slice(0, l.indexOf(":")).trim(), l.slice(l.indexOf(":") + 1).trim()]),
  );
  if (!fields.name) fail("missing name");
  if (!fields.description) fail("missing description");
  if (fields.name && fields.name !== file.replace(/\.md$/, "")) fail("name differs from file name");
  if (fields.name === "code-reviewer" && WRITE_TOOLS.some((t) => (fields.tools ?? "").includes(t)))
    fail("reviewer must not have write tools");
  if (!failed) console.log(`ok   ${file} (tools: ${fields.tools ?? "inherit all"})`);
}
process.exit(failed ? 1 : 0);
It exits with code 1 when a rule is violated: suitable for CI. Full code in the repo: https://github.com/fscamuzzi/claude-code-subagent-reviewer-dotnet

πŸ–₯️ Check: validation and tests

I run the script and the test suite. Both pass: the two agents have valid frontmatter and the project builds.

Agent validation and tests
Dark terminal: node scripts/validate-agents.mjs prints two ok lines for code-reviewer and test-writer, then dotnet test shows 1 passed test.

Validation and tests from the sample repo. Full code in the repo: https://github.com/fscamuzzi/claude-code-subagent-reviewer-dotnet

πŸš€ Invoking the reviewer

There are four ways. With automatic delegation Claude picks the subagent from its description. With natural language I write "use the code-reviewer subagent". With an @-mention I write @agent-code-reviewer. For the whole session I start claude --agent code-reviewer.

Below is an illustrative example of the report: the text changes on every run, but the format is the one the prompt enforces.

The reviewer report
Dark terminal: the code-reviewer subagent reads OrderCalculator.cs and Program.cs and returns one BLOCKER for the unvalidated discount, two WARNINGs, one NIT and the verdict changes requested.

Illustrative report example: the format is fixed, the content varies. Full code in the repo: https://github.com/fscamuzzi/claude-code-subagent-reviewer-dotnet

πŸ” The flow: reviewer, tests, fix

The flow I use has three steps. First: the reviewer produces the report. Second: the test-writer writes a test that fails for the BLOCKER. Third: in the main session I fix src/ until the test passes.

A subagent cannot start other subagents unless Agent is among its tools. Mine do not have it: orchestration stays in the main session and is readable in one place.

Review, test, fix
  1. 01
    Reviewcode-reviewer reads the diff and returns the report.
  2. 02
    Red testtest-writer writes a test that reproduces the BLOCKER.
  3. 03
    FixThe main session edits src/ until the test passes.
  4. 04
    Review againThe reviewer checks again: VERDICT approve closes the loop.

🧰 The same pattern with Codex: AGENTS.md

Codex reads AGENTS.md, not the files in .claude/agents/. I have not verified an equivalent of subagents with limited tools in Codex, so here I only carry the same rules as instructions: report format, no edits during review, verification commands.

The difference is substantial: in Claude Code the limit is in the tools, in AGENTS.md it is only text. I state it as it is.

AGENTS.md
# AGENTS.md

Instructions for Codex (and any agent that reads AGENTS.md).

## Review

Before proposing a commit, review `git diff` as a read-only reviewer:

- Report `BLOCKER` / `WARNING` / `NIT` as `path:line - problem - fix`.
- Do not edit files during the review step.
- End with `VERDICT: approve` or `VERDICT: changes requested`.

## Checks

- `dotnet build`
- `dotnet test`
The same review rules as plain instructions. Full code in the repo: https://github.com/fscamuzzi/claude-code-subagent-reviewer-dotnet

⚠️ Common mistakes

Four mistakes I have seen or that I avoid.

  • Vague description: Claude does not know when to delegate. I write when to use the subagent, not what it is.
  • Wrong field case: disallowedtools is ignored without an error. I use the validation script.
  • Omitted tools: without tools the subagent inherits everything, writing included.
  • Trusting the prompt for Bash: it is a rule, not a constraint. For hard control I use permissions or drop Bash.

πŸ“¦ GitHub repo

All the code of the article is in a public repository: claude-code-subagent-reviewer-dotnet. It contains the Minimal API, the xUnit test, the two subagents, AGENTS.md and the validation script.

No external services are needed, so there is no docker-compose.yml. .NET 8, Node.js 18 and Claude Code are enough.

Clone and try the repo
$ git clone https://github.com/fscamuzzi/claude-code-subagent-reviewer-dotnet.git
$ cd claude-code-subagent-reviewer-dotnet
$ dotnet test
$ node scripts/validate-agents.mjs
$ claude
> Use the code-reviewer subagent to review my changes.

claude-code-subagent-reviewer-dotnet Β· GitHub β†—

Full code in the repo: https://github.com/fscamuzzi/claude-code-subagent-reviewer-dotnet

🧭 Summary

A subagent is a Markdown file with its own tools and prompt. For the reviewer: limited tools, disallowedTools for writing, a fixed report format.

The strongest boundary is in the tools, not in the prompt. Where the prompt is the only constraint, I say so and check it with a script.

Frequently asked questions about Claude Code subagent

Can a subagent edit files?

It depends on the tools. If tools is omitted it inherits everything, writing included. For a reviewer I use tools as an allowlist and disallowedTools: Edit, Write, NotebookEdit.

Where do I store a subagent shared with the team?

In .claude/agents/ in the repository, committed. Personal subagents live in ~/.claude/agents/.

How do I invoke a subagent?

By automatic delegation from the description, in natural language, with @agent-name, or for the whole session with claude --agent name.

Does `Bash` make the reviewer writable?

In theory yes: Bash can run commands that write. The prompt asks to use it only for git, but that is a prompt rule. For a hard constraint I drop Bash.

Does Codex have subagents?

I have not verified an equivalent with limited tools. Codex reads AGENTS.md, where I can write the same rules as text.

Let's talk

If this topic is relevant to you, write to me: comparing notes on code and AI is always time well spent.

All articles