Salta al contenuto principale

10 - Agent orchestration: delegare a sub-agent senza perdere il filo

Come delegare a un sub-agent di Claude Code: file di definizione, contesto ricevuto, prompt come contratto, limiti e trappola dello stash, con script di prova.

Cosa ne pensi di questo articolo?

10 - Agent orchestration: delegare a sub-agent senza perdere il filo
Claude Code WorkflowFoto:PixabayPexels

In Breve

Come delegare a un sub-agent di Claude Code: file di definizione, contesto ricevuto, prompt come contratto, limiti e trappola dello stash, con script di prova.

Delegare a un sub-agent vuol dire affidare un compito a un'istanza separata di Claude Code, con una finestra di contesto sua, e ricevere indietro solo il risultato finale. Quello che il sub-agent non riceve nel messaggio di delega, nel suo file di definizione o nei file di istruzioni del progetto, per lui non esiste: per questo il prompt di delega è il vero contratto. Qui vedi come è fatto un sub-agent secondo la documentazione ufficiale, che cosa riceve all'avvio, come lo lancia GSD, e tre piccoli programmi che puoi rifare per provare le parti che non richiedono un modello.

Disclaimer di indipendenza: non sono affiliato agli autori di GSD né ad Anthropic. Non ho eseguito Claude Code né alcun sub-agent: i fatti su Claude Code vengono dalla documentazione ufficiale consultata il 2026-11-13, quelli su GSD dal repository pubblico letto lo stesso giorno al commit 7706093. Il materiale sulla mia esperienza è segnalato come racconto personale.

Perché delegare, e quando no

La documentazione ufficiale dà il criterio in una riga: usa un sub-agent quando un compito laterale riempirebbe la conversazione principale di risultati di ricerca, log o contenuti di file che non ti serviranno più; il sub-agent lavora nel suo contesto e restituisce solo il riassunto. Gli altri vantaggi dichiarati sono questi.

  • Preservare il contesto: l'esplorazione e l'implementazione restano fuori dalla conversazione principale.
  • Imporre vincoli: limiti gli strumenti che il sub-agent può usare.
  • Riusare configurazioni: un file di definizione a livello utente vale per più progetti.
  • Specializzare: un prompt di sistema mirato a un dominio.
  • Controllare i costi: instradare compiti semplici verso modelli più veloci e meno costosi.

Sono cinque leve diverse, e la più sottovalutata è la seconda: restringere gli strumenti non migliora il risultato ma rende il sub-agent prevedibile, per esempio un revisore che può solo leggere. Un esempio quotidiano: se chiedi di cercare in tutto il repository dove viene usata una funzione, la ricerca produce centinaia di righe che a te servono per un secondo e al contesto principale costano per l'intera sessione; delegata, ti torna una riga di sintesi.

La stessa pagina elenca anche i casi in cui conviene restare nella conversazione principale: quando il compito richiede continui scambi e rifiniture, quando più fasi condividono molto contesto (pianificazione, implementazione e test), quando la modifica è piccola e mirata, e quando conta la latenza, perché un sub-agent che non sia un fork parte da zero e può impiegare tempo a raccogliere il contesto. Un sub-agent non è quindi una scorciatoia per ogni compito: è uno strumento per il lavoro autonomo e circoscritto.

Com'è fatto un sub-agent: il file di definizione

Un sub-agent personalizzato è un file Markdown in .claude/agents/ (progetto) o in ~/.claude/agents/ (utente), con un frontmatter YAML e, dopo il secondo ---, il prompt di sistema. Solo name e description sono obbligatori. Ecco un esempio mio, un revisore di piani a sola lettura. È uno schema da adattare, e lo verifico con lo script più sotto.

---
name: revisore-piani
description: Rilegge un piano di lavoro e segnala requisiti scoperti. Usalo prima di eseguire un piano.
tools: Read, Glob, Grep
model: sonnet
maxTurns: 20
---
Sei un revisore di piani. Leggi solo i file che ti vengono indicati,
non modificare nulla e chiudi sempre con una riga "## ESITO: OK" oppure "## ESITO: PROBLEMI".

Le righe che contano: description è ciò che Claude legge per decidere quando delegare, quindi dice quando usarlo; tools limita il revisore a lettura e ricerca, e se la omettessi erediterebbe tutti gli strumenti disponibili ai sub-agent; model: sonnet sceglie il modello; maxTurns limita i giri, e se il sub-agent arriva al limite l'esito torna segnato come parziale e può essere ripreso. Il corpo diventa il prompt di sistema: il sub-agent riceve quello più i dettagli dell'ambiente, come la cartella di lavoro, non il prompt di sistema di Claude Code.

La trappola più subdola è scritta nella documentazione: i nomi dei campi con più parole sono in camelCase e devono combaciare esattamente, perché Claude Code ignora senza segnalare un campo che non riconosce. Un maxturns scritto in minuscolo non dà errore e non limita nulla. Inoltre un file senza name, o con name ma senza description, o con YAML non valido, viene saltato senza avvisi nella sessione. Ho scritto un controllore che applica queste regole, con i campi della tabella ufficiale.

"""Controlla una cartella di agenti secondo la documentazione di Claude Code (pagina sub-agents, letta il 2026-11-13).

Uso: python3 validate_agents.py <cartella>
Regole di caricamento e campi riconosciuti: tabella 'Frontmatter reference' e sezione 'Subagent files Claude Code skips'.
"""
import difflib
import sys
from pathlib import Path

import yaml

CAMPI = {
    "name", "description", "tools", "disallowedTools", "model", "permissionMode", "maxTurns",
    "autoCompactWindow", "skills", "mcpServers", "hooks", "memory", "background", "omitClaudeMd",
    "effort", "isolation", "color", "initialPrompt", "experimental",
}


def frontmatter(testo):
    righe = testo.split("\n")
    if righe[0].strip() != "---":
        return None, "nessun frontmatter alla prima riga: trattato come documentazione"
    try:
        fine = righe[1:].index("---") + 1
    except ValueError:
        return None, "frontmatter non chiuso"
    try:
        return yaml.safe_load("\n".join(righe[1:fine])) or {}, None
    except yaml.YAMLError as e:
        return None, f"YAML non valido: {e}"


def esamina(percorso):
    meta, errore = frontmatter(percorso.read_text(encoding="utf-8"))
    if errore:
        return "SALTATO", [errore]
    nome = meta.get("name")
    if not nome:
        return "SALTATO", ["manca name: trattato come documentazione"]
    if str(nome).startswith("-") or ":" in str(nome) or len(str(nome)) > 256:
        return "SALTATO", [f"name non valido ({nome!r}): inizia con '-', contiene ':' o supera 256 caratteri"]
    if not meta.get("description"):
        return "SALTATO", ["manca description: il file viene saltato"]
    note = []
    for campo in meta:
        if campo not in CAMPI:
            vicino = difflib.get_close_matches(campo, CAMPI, n=1, cutoff=0.6)
            suggerimento = f", forse intendevi {vicino[0]}" if vicino else ""
            note.append(f"campo '{campo}' ignorato in silenzio{suggerimento}")
    return "CARICATO", note


if __name__ == "__main__":
    for p in sorted(Path(sys.argv[1]).glob("*.md")):
        stato, note = esamina(p)
        print(f"{p.name:28} {stato:9} " + ("; ".join(note) if note else "nessuna segnalazione"))

La funzione frontmatter separa e interpreta l'intestazione e restituisce un errore se manca o non si legge; esamina applica nell'ordine le regole di salto e poi confronta ogni campo con l'insieme CAMPI, proponendo il nome più vicino con difflib (la documentazione dice che anche il log di debug suggerisce il nome probabile). Il set dei campi è copiato dalla tabella di oggi: se Anthropic ne aggiunge, vanno aggiunti qui, ed è un limite del controllore. Ho preparato cinque file di prova, tra cui uno con due campi scritti male:

python3 -I validate_agents.py agents

# appunti.md                   SALTATO   nessun frontmatter alla prima riga: trattato come documentazione
# errore-di-battitura.md       CARICATO  campo 'maxturns' ignorato in silenzio, forse intendevi maxTurns; campo 'modello' ignorato in silenzio, forse intendevi model
# nome-con-due-punti.md        SALTATO   name non valido ('team:revisore'): inizia con '-', contiene ':' o supera 256 caratteri
# revisore-piani.md            CARICATO  nessuna segnalazione
# senza-descrizione.md         SALTATO   manca description: il file viene saltato

Il file errore-di-battitura.md risulta caricato, ed è il punto: Claude Code lo caricherebbe e ignorerebbe maxturns e modello senza dire nulla, quindi quell'agente avrebbe tutti gli strumenti e nessun limite di giri. Gli altri tre casi sono saltati senza avviso in sessione. Per un controllo ufficiale sui file la documentazione cita claude plugin validate su una cartella di agenti (da una certa versione in poi); non l'ho eseguito, perché richiede Claude Code.

Che cosa riceve davvero il sub-agent

Una versione di questo articolo diceva che il sub-agent «vede solo ciò che c'è nel prompt». La documentazione è più precisa: un sub-agent che non sia un fork parte con la sua finestra di contesto e non vede la cronologia della conversazione, né le skill già invocate, né i file già letti. Riceve invece:

  • il proprio prompt di sistema più i dettagli dell'ambiente;
  • il messaggio di delega scritto da Claude;
  • i file CLAUDE.md di tutta la gerarchia che la conversazione principale carica, salvo che la definizione imposti omitClaudeMd: true;
  • un'istantanea dello stato di git, il contenuto completo delle skill elencate nel campo skills, e un elenco degli altri agenti nominati quando ha lo strumento SendMessage.

La conseguenza pratica è doppia. Le regole di progetto in CLAUDE.md arrivano al sub-agent senza che tu le ripeta; ciò che non arriva è la memoria automatica della conversazione principale, lo stile di output e tutto quello che hai detto in chat. Se una regola serve davvero a quel compito, per esempio «ignora la cartella vendor/», la documentazione consiglia di riscriverla nel prompt di delega.

Il prompt di delega come contratto

Il messaggio di delega ha cinque parti che nei flussi GSD ritrovo di continuo: un obiettivo di una frase, i file da leggere per primi, le decisioni già prese (da ribadire anche se stanno in un file), il formato dell'esito atteso e i divieti. È una pratica di GSD e mia, non una regola di Claude Code. Il vantaggio è che ciascuna parte si può controllare con un programma, prima di spendere un lancio.

Objective: produrre i PLAN.md della fase "prenotazione di un campo da padel" (requisiti PAD-01..PAD-04).

Files_to_read:
- .planning/ROADMAP.md
- .planning/phases/03-prenotazioni/03-CONTEXT.md
- CLAUDE.md

Locked decisions:
- Lo slot dura 90 minuti.
- Le prenotazioni sono salvate in UTC.

Output expected: termina con una riga "## PLANNING COMPLETE" seguita dall'elenco dei piani, oppure con "## PLANNING INCONCLUSIVE" e il motivo.

Constraints:
- Non lanciare altri agenti.
- Non modificare CONTEXT.md.

Nel prompt la parte più importante è «Output expected»: dice all'orchestratore come riconoscere l'esito. Nei file degli agenti GSD che ho letto compaiono titoli come ## PLANNING COMPLETE, ## PLANNING INCONCLUSIVE, ## VERIFICATION PASSED, ## ISSUES FOUND, ## CHECKPOINT REACHED e ## REVISION_CONFLICT. Un esito senza un marcatore costringe l'orchestratore a interpretare testo libero, ed è fragile. Lo script seguente verifica le cinque parti in un prompt e legge il marcatore in una risposta, tenendo l'ultimo trovato.

"""Due controlli sul lato dell'orchestratore: il prompt di delega e l'esito restituito dall'agente."""
import re
import sys
from pathlib import Path

SEZIONI = ("Objective", "Files_to_read", "Locked decisions", "Output expected", "Constraints")
# marcatori che compaiono davvero nei file degli agenti GSD letti il 2026-11-13
MARCATORI = ("PLANNING COMPLETE", "PLANNING INCONCLUSIVE", "VERIFICATION PASSED", "ISSUES FOUND",
             "CHECKPOINT REACHED", "REVISION_CONFLICT")


def sezioni_mancanti(prompt):
    return [s for s in SEZIONI if not re.search(rf"^{re.escape(s)}\s*:", prompt, re.M | re.I)]


def esito(risposta):
    """Cerca un marcatore di esito in una riga '## MARCATORE'; vale l'ultimo."""
    trovati = re.findall(r"^## ([A-Z_ ]+?)\s*$", risposta, re.M)
    validi = [t for t in trovati if t in MARCATORI]
    return validi[-1] if validi else None


if __name__ == "__main__":
    for nome in sys.argv[1:]:
        manca = sezioni_mancanti(Path(nome).read_text())
        print(f"{Path(nome).name:14} " + ("completo" if not manca else "manca: " + ", ".join(manca)))
    for risposta in ("Ho letto i file.\n## PLANNING COMPLETE\n3 piani", "Ho finito, mi sembra tutto a posto.",
                     "## ISSUES FOUND\n...\n## PLANNING INCONCLUSIVE"):
        print(f"esito: {esito(risposta)!r}")

Il controllo sezioni_mancanti cerca ogni etichetta a inizio riga con i due punti; esito raccoglie le righe che sono titoli in maiuscolo e conserva solo quelle nell'elenco MARCATORI, restituendo l'ultima: se un agente scrive prima ISSUES FOUND e poi chiude con PLANNING INCONCLUSIVE, vale la seconda. Ho provato il prompt vago «Pianifica la fase delle prenotazioni» e quello completo del blocco precedente, e tre risposte inventate:

python3 -I delega.py prompts/vago.txt prompts/completo.txt

# vago.txt       manca: Objective, Files_to_read, Locked decisions, Output expected, Constraints
# completo.txt   completo
# esito: 'PLANNING COMPLETE'
# esito: None
# esito: 'PLANNING INCONCLUSIVE'

Il prompt di una sola riga fallisce tutti e cinque i controlli; la risposta senza marcatore dà None, cioè nessun esito leggibile. Lo script non giudica se il prompt sia buono, controlla soltanto che le parti ci siano: la qualità di un obiettivo o di un divieto resta un giudizio tuo.

Come GSD lancia i sub-agent

Lo strumento che avvia un sub-agent in Claude Code si chiama Agent. Nel workflow di esecuzione di GSD la chiamata è scritta come Agent(subagent_type="gsd-executor", ...), con un parametro description, un prompt, un model omesso quando vale inherit (in quel caso il sub-agent eredita il modello dell'orchestratore) e run_in_background: true per l'esecuzione parallela. Il file dice anche una cosa non ovvia: quando una wave ha due o più agenti, le chiamate vanno inviate una per messaggio, perché più git worktree add simultanei competono sul blocco .git/config.lock; gli agenti poi lavorano comunque in parallelo. Di questo riparlo nell'articolo sull'esecuzione a wave.

Sul modello, la documentazione di Claude Code fissa un ordine di risoluzione: prima il parametro della singola chiamata, poi il campo model della definizione, poi la variabile d'ambiente CLAUDE_CODE_SUBAGENT_MODEL, infine il modello della conversazione principale. L'ordine è sostanziale: una definizione con model: haiku viene battuta da una chiamata che chiede opus.

  1. parametro model della chiamata;
  2. campo model nel frontmatter;
  3. variabile CLAUDE_CODE_SUBAGENT_MODEL;
  4. modello della conversazione principale.

Se scambi le voci cambia chi vince quando due fonti dicono cose diverse, ed è per questo che la lista è numerata. Un dettaglio: per un alias di famiglia come opus, se anche la conversazione principale è di quella famiglia il sub-agent usa il modello esatto della conversazione. Sui prezzi non do cifre: vanno lette dalla pagina ufficiale dei prezzi al momento della scelta, e qui non le ho consultate.

Quando il sub-agent non finisce

Racconto personale, non misurato: una volta ho chiesto a un researcher di coprire sedici aree in un solo giro, e non è tornato con un risultato. Ho scritto a mano il documento, e col senno di poi avrei dovuto dividere la ricerca in tre. La documentazione offre due strumenti che allora non usavo: maxTurns, che fa tornare un risultato segnato come parziale invece di un silenzio, e la ripresa, con cui Claude può continuare lo stesso sub-agent con la sua cronologia usando SendMessage con l'identificativo o il nome. I sub-agent integrati Explore e Plan non si possono riprendere.

Sul tempo massimo non riporto numeri: la versione precedente parlava di «60+ minuti» e non ho trovato una fonte. Nei file GSD letti, la regola difensiva è un'altra: se l'agente ha concluso il lavoro (commit visibili, SUMMARY.md presente) ma l'orchestratore non riceve il segnale di completamento, si considera riuscito in base alla verifica su filesystem e git, e non si resta mai in attesa indefinita. È un buon principio di orchestrazione: fidarsi di ciò che è sul disco, non della notifica.

Parallelismo, worktree e il caso dello stash

I sub-agent non sono limitati a pochi: di default, con 20 in esecuzione nella sessione, un nuovo lancio con lo strumento Agent fallisce con Concurrent subagent limit reached, e il limite si cambia con CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. Il limite vero è un altro: più agenti che scrivono nella stessa cartella si pestano i piedi. Per questo la definizione ha il campo isolation: worktree, che esegue il sub-agent in un worktree git temporaneo, ripulito da solo se non ci sono modifiche.

Qui c'è un fatto che ho potuto verificare. I worktree condividono refs/stash: uno stash fatto in un worktree compare negli altri. Il workflow di GSD lo dice in un commento (issue #3542) e vieta agli esecutori qualsiasi sottocomando di stash. L'ho riprodotto in un repository di prova con git 2.53:

#!/usr/bin/env bash
# Mostra che refs/stash e' condiviso tra il repository e i suoi worktree. Gira in una cartella temporanea.
set -e
d=$(mktemp -d)
cd "$d"
git init -q principale && cd principale
git config user.email prova@example.invalid && git config user.name prova
echo uno > file.txt && git add file.txt && git commit -qm base
git worktree add -q ../secondo -b ramo-secondo
echo "lavoro in corso nel secondo worktree" >> ../secondo/file.txt
(cd ../secondo && git stash push -q -m "stash fatto nel secondo worktree")
echo "--- git stash list, eseguito nel worktree principale:"
git stash list

# Output:
# --- git stash list, eseguito nel worktree principale:
# stash@{0}: On ramo-secondo: stash fatto nel secondo worktree

Lo script crea un repository, un secondo worktree su un ramo nuovo, scrive una modifica lì e fa git stash push; poi lo stash compare nell'elenco del worktree principale, con il ramo ramo-secondo nel messaggio. Una modifica «in corso» messa da parte in un worktree può quindi essere recuperata, o peggio rimessa, da un altro. L'uscita è deterministica (due esecuzioni identiche) e dipende solo dal comportamento di git, non da Claude Code.

Sub-agent che lanciano sub-agent

La versione precedente affermava che la ricorsione è vietata. La documentazione dice il contrario: per impostazione predefinita un sub-agent può lanciarne altri, fino a tre livelli sotto la conversazione principale, e a quella profondità lo strumento Agent viene tolto. Il limite si regola con CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH (il valore 1 spegne l'annidamento), e un singolo sub-agent si tiene piatto omettendo Agent dai suoi tools. Gli agenti GSD che ho letto (planner, plan-checker, executor) non elencano Agent tra gli strumenti, quindi nel loro caso la struttura è piatta per scelta di configurazione, non perché Claude Code lo imponga.

La mia regola, che resta un'opinione, è comunque tenere la struttura piatta: se un compito si divide in sotto-compiti, a dividerlo dovrebbe essere l'orchestratore, perché in una catena a tre livelli non sai dove si è perso il contesto quando qualcosa fallisce. La documentazione stessa riconosce che l'annidamento ha senso quando il compito delegato si divide da solo in parti parallele, come un revisore che lancia un verificatore per ogni problema trovato.

Che cosa sai fare adesso

Sai scrivere un file di sub-agent con i campi che esistono davvero e accorgerti di quelli che Claude Code ignora in silenzio; sai che cosa il sub-agent riceve all'avvio e che cosa no, quindi che cosa va ripetuto nel messaggio di delega; sai scrivere quel messaggio come un contratto con un esito riconoscibile e controllarlo con un programma; conosci i limiti documentati di concorrenza e di profondità, il campo di isolamento e la trappola dello stash condiviso. Il passo successivo è il parallelismo organizzato in ondate, nell'articolo sull'esecuzione a wave; se arrivi da qui, il plan-checker è il controllo che precede la delega, e per la mappa dell'insieme c'è la guida pratica al workflow. I modelli, i costi e i worktree sono ripresi in cost optimization.

Domande frequenti

Che cosa vede un sub-agent di Claude Code all'avvio?

Un sub-agent non fork parte con un contesto vuoto: non vede la cronologia della conversazione. Riceve il proprio prompt di sistema, il messaggio di delega, i file CLAUDE.md della gerarchia (salvo omitClaudeMd), l'istantanea dello stato di git e le skill elencate nel campo skills.

Un sub-agent può lanciare altri sub-agent?

Sì, per impostazione predefinita fino a tre livelli sotto la conversazione principale. Il limite si regola con CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH e un singolo sub-agent si tiene piatto omettendo lo strumento Agent dai suoi tools.

Che cosa succede se scrivo male un campo del frontmatter?

Claude Code ignora senza segnalarlo un campo che non riconosce, e i nomi in camelCase devono combaciare esattamente: maxturns al posto di maxTurns non limita nulla. Con il log di debug si trovano i campi non riconosciuti.

Come si riprende un sub-agent che si è fermato?

Se si ferma al limite maxTurns il risultato torna segnato come parziale, e Claude può riprenderlo con SendMessage usando l'identificativo o il nome, ritrovando la cronologia completa. Explore e Plan, integrati, non si riprendono.

Nella stessa serie trovi anche la gestione della memoria, il debug end-to-end con plan-checker e agenti e l'integrazione fra Superpowers e GSD.

Fonti

Prova Questi Strumenti

Strumenti gratuiti correlati a questo argomento.

Commenti

Caricamento commenti...

Accedi per commentare

Discuti questo articolo nella community

Unisciti al gruppo Telegram per discutere con altri sviluppatori, fare domande e condividere le tue esperienze.

Ti è piaciuto questo articolo?

Esplora altri contenuti sul blog o scopri i miei progetti