In questo articolo
- 🧩 Cos'è un subagent di Claude Code
- 🎯 Perché un reviewer in sola lettura
- 🗂️ Dove vivono i file dei subagent
- 🛠️ Il progetto di esempio: una Minimal API
- 🔒 Scrivere code-reviewer.md
- 🧪 Scrivere test-writer.md
- ✅ Validare i file con uno script
- 🖥️ Verifica: validazione e test
- 🚀 Invocare il reviewer
- 🔁 Il flusso: reviewer, test, correzione
- 🧰 Lo stesso schema con Codex: AGENTS.md
- ⚠️ Errori comuni
- 📦 GitHub repo
- 🧭 In sintesi
🧩 Cos'è un subagent di Claude Code
Un subagent è un assistente specializzato che Claude Code avvia in un contesto separato: ha il suo prompt di sistema, i suoi tool e (se vuoi) il suo modello. Fa il lavoro, e alla sessione principale torna solo il report finale.
Il vantaggio è doppio. La sessione principale non si riempie di file letti e output di comandi. E posso togliere al subagent i tool che non gli servono: un reviewer che non può scrivere non può rovinare il codice.
- File Markdown: un subagent è un file
.mdcon frontmatter YAML e il prompt nel corpo. - Solo
nameedescriptionsono obbligatori: ladescriptiondice a Claude quando delegare. - Tool ereditati se omessi: per limitarli uso
tools(allowlist) odisallowedTools(denylist).
🎯 Perché un reviewer in sola lettura
Se chiedo a Claude di rivedere il codice che ha appena scritto, la review è nella stessa conversazione: vede le sue stesse ipotesi e tende a confermarle. Un subagent parte da un contesto pulito e guarda solo il diff.
Tolgo a questo subagent i tool di scrittura. Così il suo unico effetto è un report: nessuna "correzione al volo" che sfugge alla review. Le correzioni le decido io, nella sessione principale.
Review nella stessa sessione
- Stesso contesto, stesse ipotesi
- Può modificare file mentre rivede
- La conversazione si riempie di letture
Subagent in sola lettura
- Contesto pulito, solo il diff
- Nessun tool di scrittura
- Torna un solo report
Il confine tra chi giudica e chi modifica è un file di configurazione.
🗂️ Dove vivono i file dei subagent
Un subagent di progetto sta in .claude/agents/ e si committa nel repository: lo stesso file vale per tutto il team. Uno personale sta in ~/.claude/agents/ e vale per ogni progetto.
Con lo stesso nome vince la posizione con priorità più alta: prima la configurazione gestita dall'organizzazione, poi il flag --agents, poi .claude/agents/, poi ~/.claude/agents/, infine i plugin. Le sottocartelle sono scansionate in modo ricorsivo.
🛠️ Il progetto di esempio: una Minimal API
Parto da una piccola Minimal API ASP.NET Core per gli ordini. Contiene una debolezza voluta: DiscountPercent non è validato, quindi 150 produce un totale negativo. Il reviewer dovrà trovarla.
Ci sono un solo endpoint di scrittura, un calcolatore statico e un test xUnit che passa. Il progetto compila con .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;
}
}🔒 Scrivere code-reviewer.md
Il frontmatter fa tre cose. tools elenca ciò che il reviewer può usare. disallowedTools toglie esplicitamente i tool di scrittura. description contiene "use proactively", che incoraggia Claude a delegare dopo ogni modifica.
Il corpo è il prompt di sistema. Impongo un formato di report fisso: BLOCKER, WARNING, NIT e un verdetto finale. Un formato fisso rende il report facile da leggere e da controllare con uno script.
Attenzione: Bash non è in sola lettura di suo. Il prompt chiede di usarlo solo per git, ma è una regola di prompt, non un vincolo. Per un vincolo duro tolgo Bash e passo il diff nel 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 ↗
🧪 Scrivere test-writer.md
Il secondo subagent scrive test. Qui servono Edit e Write, ma la regola nel prompt li limita a tests/. Se un test fallisce per un bug in src/, non lo corregge: lo segnala.
Separo i ruoli per scelta: chi trova il problema (reviewer), chi lo copre con un test (test-writer), chi lo corregge (sessione principale). Ogni passo ha un report e un confine di tool diverso.
---
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 ↗
✅ Validare i file con uno script
I file degli agenti sono configurazione: un errore di battitura nel frontmatter e il subagent perde un campo. I nomi dei campi sono sensibili alle maiuscole e quelli sconosciuti sono ignorati senza avviso.
Per questo metto nel repo uno script Node senza dipendenze. Controlla name, description, che il nome coincida col file e che il reviewer non abbia tool di scrittura.
#!/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);🖥️ Verifica: validazione e test
Lancio lo script e la suite. Entrambi passano: i due agenti hanno frontmatter valido e il progetto compila.
Validazione e test dal repo di esempio. Codice completo nel repo: https://github.com/fscamuzzi/claude-code-subagent-reviewer-dotnet
🚀 Invocare il reviewer
Ci sono quattro modi. Per delega automatica Claude sceglie il subagent dalla description. Per linguaggio naturale scrivo "usa il subagent code-reviewer". Con @-mention scrivo @agent-code-reviewer. Per tutta la sessione avvio claude --agent code-reviewer.
Qui sotto un esempio illustrativo del report: il testo cambia a ogni esecuzione, ma il formato è quello imposto dal prompt.
Esempio illustrativo di report: il formato è fisso, il contenuto varia. Codice completo nel repo: https://github.com/fscamuzzi/claude-code-subagent-reviewer-dotnet
🔁 Il flusso: reviewer, test, correzione
Il flusso che uso ha tre passi. Primo: il reviewer produce il report. Secondo: il test-writer scrive un test che fallisce per il BLOCKER. Terzo: nella sessione principale correggo src/ finché il test passa.
Un subagent non può avviare altri subagent se Agent non è tra i suoi tool. I miei due non lo hanno: l'orchestrazione resta nella sessione principale e si legge in un solo punto.
- 01Reviewcode-reviewer legge il diff e restituisce il report.
- 02Test rossotest-writer scrive un test che riproduce il BLOCKER.
- 03CorrezioneLa sessione principale modifica src/ finché il test passa.
- 04Nuova reviewIl reviewer ricontrolla: VERDICT approve chiude il ciclo.
🧰 Lo stesso schema con Codex: AGENTS.md
Codex legge AGENTS.md, non i file in .claude/agents/. Non ho verificato un equivalente dei subagent con tool limitati in Codex, quindi qui riporto solo le stesse regole come istruzioni: formato del report, nessuna modifica durante la review, comandi di verifica.
La differenza è sostanziale: in Claude Code il limite è nei tool, in AGENTS.md è solo testo. Lo dichiaro così com'è.
# 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`⚠️ Errori comuni
Quattro errori che ho visto o che evito.
- Description vaga: Claude non sa quando delegare. Scrivo quando usare il subagent, non cosa è.
- Campo con maiuscole sbagliate:
disallowedtoolsè ignorato senza errore. Uso lo script di validazione. - Tool omessi: senza
toolsil subagent eredita tutto, scrittura compresa. - Fiducia nel prompt per
Bash: è una regola, non un vincolo. Per un controllo duro uso i permessi o tolgoBash.
📦 GitHub repo
Tutto il codice dell'articolo è in un repository pubblico: claude-code-subagent-reviewer-dotnet. Contiene la Minimal API, il test xUnit, i due subagent, AGENTS.md e lo script di validazione.
Non servono servizi esterni, quindi non c'è un docker-compose.yml. Bastano .NET 8, Node.js 18 e Claude Code.
$ 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 ↗
🧭 In sintesi
Un subagent è un file Markdown con tool e prompt propri. Per il reviewer: tools limitati, disallowedTools per la scrittura, formato di report fisso.
Il confine più solido è nei tool, non nel prompt. Dove il prompt è l'unico vincolo, lo dichiaro e lo controllo con uno script.
Domande frequenti su subagent Claude Code
Un subagent può modificare i file?
Dipende dai tool. Se tools è omesso eredita tutto, scrittura compresa. Per un reviewer uso tools come allowlist e disallowedTools: Edit, Write, NotebookEdit.
Dove salvo un subagent condiviso col team?
In .claude/agents/ del repository, committato. I subagent personali stanno in ~/.claude/agents/.
Come invoco un subagent?
Per delega automatica dalla description, in linguaggio naturale, con @agent-nome, oppure per l'intera sessione con claude --agent nome.
`Bash` rende il reviewer scrivibile?
Sì, in teoria: Bash può eseguire comandi che scrivono. Il prompt chiede di usarlo solo per git, ma è una regola di prompt. Per un vincolo duro tolgo Bash.
Codex ha i subagent?
Non ho verificato un equivalente con tool limitati. Codex legge AGENTS.md, dove posso scrivere le stesse regole come testo.
Parliamone
Se questo tema ti riguarda, scrivimi: confrontarsi su codice e AI è sempre tempo speso bene.



