4 sub-agenti in Claude Code: i file .md pronti

4 file. 5 righe per ciascuno. La sessione principale orchestra e non esegue.

Questo è il pattern per i sub-agenti in Claude Code: ogni agente vive in .claude/agents/ come un file markdown con un frontmatter minimo. La sessione principale li chiama, loro eseguono, restituiscono il risultato.

Niente prompt copiato ogni volta. Il file è il prompt.

Il formato del file

---
name: verificatore
description: Legge stato e inventari. Read-only, mai scrive.
model: claude-sonnet-4-6
tools: Read, Glob, Grep
---

4 campi nel frontmatter: name, description, model, tools. Claude Code legge i file in .claude/agents/ all'avvio della sessione. Da quel momento la sessione principale può assegnare task per nome.

Il corpo del file (dopo il frontmatter) è opzionale: puoi aggiungere istruzioni più dettagliate sul comportamento. Per la maggior parte dei task basta il frontmatter.

I 4 agenti del mio sistema

1. verificatore, model: claude-sonnet-4-6, tools: Read, Glob, Grep

Legge stato, inventari e configurazione del sistema. Non ha permessi di scrittura: non può rompere nulla per sbaglio.

Perché Sonnet: il task è leggere e riportare. Non serve il modello più capace per aprire un file e restituire il contenuto. Sonnet costa meno e per questo task non si nota la differenza.

Uso tipico: "controlla se reel-queue/slug.json esiste", "lista i report in reports/ degli ultimi 7 giorni con data e titolo".

1. builder, model: claude-opus-5, tools: Edit, Write, Bash, Glob, Grep, Read

Scrive codice, fa deploy, gestisce git. Permessi completi.

Perché Opus 5: qui si sbaglia se il contesto non è capito bene. Il builder tocca il codice, esegue bash, modifica file. Un errore ha impatto reale: codice rotto, commit sbagliato, deploy fallito. Vale il costo del modello più capace.

Uso tipico: "modifica il file X aggiungendo la funzione Y", "esegui il deploy su Cloud Run e riporta il log di build".

1. ricercatore, model: claude-opus-5, tools: WebFetch, WebSearch, Read, Write (limitato a reports/)

Ricerca su web, analisi di fonti esterne, monitoring news. Consegna il risultato in reports/ con le fonti citate esplicitamente.

Perché Opus 5: sintetizzare più fonti e distinguere il segnale dal rumore richiede ragionamento. La scrittura è limitata alla cartella reports/: non tocca il codice, non modifica la configurazione.

Uso tipico: "cerca le news Anthropic delle ultime 24h e salva un report in reports/news-YYYYMMDD.md con fonti verificate".

1. revisore, model: claude-opus-5, tools: Read, Glob, Grep (solo lettura)

Revisione adversarial: cerca problemi, contraddizioni, claim non supportati. Nessun permesso di scrittura: il suo compito è trovare, non sistemare.

Perché Opus 5: il pensiero critico ha bisogno del modello più capace. La read-only non è un risparmio di costi: è un guardrail. Il revisore segnala, la sessione principale decide.

Uso tipico: "revisione adversarial del deliverable in reel-queue/slug.json: cerca claim non verificabili o incoerenze con ground-truth".

Il principio che li rende utili

Il modello si sceglie per delicatezza del compito, non per prestigio. Opus 5 non è "il modello buono" e Sonnet "quello di ripiego". Sono strumenti diversi per task diversi.

Tre vantaggi concreti:

1. Meno contesto consumato nella sessione principale. Ogni agente lavora nel suo scope, riporta il risultato.
2. Gli errori si isolano. Il builder può sbagliare: il revisore legge il risultato prima che vada in produzione.
3. Il file documenta il sistema. Tra 3 mesi sai esattamente cosa fa il verificatore, quali tools ha, su quale modello gira.

I 4 file pronti

Copia in .claude/agents/ del tuo progetto, adatta description e tools al tuo sistema.

---
name: verificatore
description: Legge stato e inventari. Read-only, mai scrive.
model: claude-sonnet-4-6
tools: Read, Glob, Grep
---

---
name: builder
description: Scrive codice, esegue deploy, gestisce git. Permessi completi.
model: claude-opus-5
tools: Edit, Write, Bash, Glob, Grep, Read
---

---
name: ricercatore
description: Ricerca su web e fonti esterne. Consegna report in reports/ con fonti.
model: claude-opus-5
tools: WebFetch, WebSearch, Read, Write
---

---
name: revisore
description: Revisione adversarial. Trova problemi, non li sistema. Read-only.
model: claude-opus-5
tools: Read, Glob, Grep
---