In this article
- π§© What a Claude Code subagent is
- π― Why a read-only reviewer
- ποΈ Where subagent files live
- π οΈ The sample project: a Minimal API
- π Writing code-reviewer.md
- π§ͺ Writing test-writer.md
- β Validating the files with a script
- π₯οΈ Check: validation and tests
- π Invoking the reviewer
- π The flow: reviewer, tests, fix
- π§° The same pattern with Codex: AGENTS.md
- β οΈ Common mistakes
- π¦ GitHub repo
- π§ Summary
π§© 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
.mdfile with YAML frontmatter and the prompt in the body. - Only
nameanddescriptionare required: thedescriptiontells Claude when to delegate. - Tools are inherited when omitted: to limit them I use
tools(allowlist) ordisallowedTools(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 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.
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;
}
}π 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.
---
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 β
π§ͺ 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.
---
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 β
β 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.
#!/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);π₯οΈ Check: validation and tests
I run the script and the test suite. Both pass: the two agents have valid frontmatter and the project builds.
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.
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.
- 01Reviewcode-reviewer reads the diff and returns the report.
- 02Red testtest-writer writes a test that reproduces the BLOCKER.
- 03FixThe main session edits src/ until the test passes.
- 04Review 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
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`β οΈ 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:
disallowedtoolsis ignored without an error. I use the validation script. - Omitted tools: without
toolsthe subagent inherits everything, writing included. - Trusting the prompt for
Bash: it is a rule, not a constraint. For hard control I use permissions or dropBash.
π¦ 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.
$ 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 β
π§ 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.



