In questo articolo

🧩 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 .md con frontmatter YAML e il prompt nel corpo.
  • Solo name e description sono obbligatori: la description dice a Claude quando delegare.
  • Tool ereditati se omessi: per limitarli uso tools (allowlist) o disallowedTools (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 sessione vs. subagent reviewer

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.

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;
    }
}
Il calcolo non controlla l'intervallo dello sconto. Codice completo nel repo: https://github.com/fscamuzzi/claude-code-subagent-reviewer-dotnet

🔒 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.

.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 ↗

L'agente di review: tool limitati e formato di report fisso. Codice completo nel repo: https://github.com/fscamuzzi/claude-code-subagent-reviewer-dotnet

🧪 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.

.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 ↗

Il perimetro `tests/` è una regola di prompt: la verifico in review. Codice completo nel repo: https://github.com/fscamuzzi/claude-code-subagent-reviewer-dotnet

✅ 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.

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);
Esce con codice 1 se una regola è violata: adatto alla CI. Codice completo nel repo: https://github.com/fscamuzzi/claude-code-subagent-reviewer-dotnet

🖥️ Verifica: validazione e test

Lancio lo script e la suite. Entrambi passano: i due agenti hanno frontmatter valido e il progetto compila.

Validazione degli agenti e test
Terminale con tema scuro: node scripts/validate-agents.mjs stampa due righe ok per code-reviewer e test-writer, poi dotnet test mostra 1 test superato.

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.

Il report del reviewer
Terminale con tema scuro: il subagent code-reviewer legge OrderCalculator.cs e Program.cs e restituisce un BLOCKER sullo sconto non validato, due WARNING, un NIT e il verdetto changes requested.

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.

Review, test, correzione
  1. 01
    Reviewcode-reviewer legge il diff e restituisce il report.
  2. 02
    Test rossotest-writer scrive un test che riproduce il BLOCKER.
  3. 03
    CorrezioneLa sessione principale modifica src/ finché il test passa.
  4. 04
    Nuova 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
# 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`
Le stesse regole di review come istruzioni di testo. Codice completo nel repo: https://github.com/fscamuzzi/claude-code-subagent-reviewer-dotnet

⚠️ 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 tools il subagent eredita tutto, scrittura compresa.
  • Fiducia nel prompt per Bash: è una regola, non un vincolo. Per un controllo duro uso i permessi o tolgo Bash.

📦 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.

Clona e prova il 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 ↗

Codice completo nel repo: https://github.com/fscamuzzi/claude-code-subagent-reviewer-dotnet

🧭 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.