Agent Teams in Claude Code: Orchestrazione Multi-Agente per Progetti Software Complessi

1. Il Problema: Perché Servono Team di Agenti AI

Chiunque abbia usato un AI coding assistant per un progetto non banale conosce il momento in cui la conversazione diventa troppo lunga, il contesto si satura, e l'agente inizia a perdere il filo. Per un singolo file o una funzione isolata, l'AI è straordinaria. Per un refactoring che tocca frontend, backend e test contemporaneamente, una singola sessione non basta.

Nel mio lavoro quotidiano come consulente SEO e sviluppatore AI, mi trovo regolarmente ad affrontare task che richiedono competenze parallele e indipendenti: ricerca documentale, scrittura di codice, revisione di qualità, e deployment — tutti sullo stesso progetto, tutti nello stesso sprint. Delegare tutto a una singola sessione Claude Code significa accumulare contesto fino al punto di rottura.

Il problema fondamentale è la finestra di contesto. È la risorsa più preziosa di un LLM, e le sue prestazioni si degradano man mano che si riempie. Ogni file letto, ogni comando eseguito, ogni risposta generata consuma contesto. Quando si raggiunge il ~95% della capacità, la compattazione automatica interviene, ma a quel punto si è già perso il dettaglio di decisioni prese nelle prime fasi della conversazione.

La soluzione non è un modello con più contesto. La soluzione è un'architettura che distribuisce il lavoro tra agenti indipendenti, ognuno con il proprio contesto dedicato, che comunicano tra loro solo quando necessario. Esattamente come funziona un team di sviluppatori umani.

2. Architettura degli Agent Teams in Claude Code

2.1 Componenti del Sistema

Un Agent Team in Claude Code è composto da quattro componenti fondamentali che collaborano per distribuire il lavoro in modo efficace.

A differenza dei sub-agent, che vengono eseguiti all'interno di una singola sessione e possono solo riferire al main agent, i compagni di team sono istanze Claude Code completamente indipendenti. Ogni compagno ha il proprio context window, carica lo stesso contesto di progetto (CLAUDE.md, MCP servers, skills), ma non eredita la cronologia del lead.

2.2 Diagramma dell'Architettura

┌─────────────────────────────────────────────────┐
│                   TEAM LEAD                      │
│  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
│  │ Crea     │  │ Assegna  │  │ Sintetizza    │  │
│  │ Team     │→ │ Task     │→ │ Risultati     │  │
│  └──────────┘  └──────────┘  └───────────────┘  │
└────────┬──────────────┬──────────────┬───────────┘
         │              │              │
    SendMessage    SendMessage    SendMessage
         │              │              │
   ┌─────▼─────┐  ┌─────▼─────┐  ┌────▼──────┐
   │ Compagno  │  │ Compagno  │  │ Compagno  │
   │ #1        │←→│ #2        │←→│ #3        │
   │ (Context  │  │ (Context  │  │ (Context  │
   │  proprio) │  │  proprio) │  │  proprio) │
   └─────┬─────┘  └─────┬─────┘  └─────┬─────┘
         │              │              │
         └──────────────┼──────────────┘
                        │
              ┌─────────▼─────────┐
              │  TASK LIST        │
              │  (condiviso)      │
              │  ~/.claude/tasks/ │
              └───────────────────┘

2.3 Abilitazione e Requisiti

I team di agenti sono una feature sperimentale, disabilitata per default. Richiedono Claude Code v2.1.32 o successivo e si abilitano tramite variabile d'ambiente.

// settings.json (progetto o utente)
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

2.4 Quando Usare i Team di Agenti

Non tutti i task giustificano l'overhead di coordinamento di un team. Ho identificato quattro scenari dove i team eccellono rispetto a sessioni singole o sub-agent.

3. Il Sistema di Task e Coordinamento

3.1 Ciclo di Vita di un Task

Il cuore del coordinamento è l'elenco di attività condiviso. Ogni task attraversa tre stati: pending, in_progress, completed. I task possono avere dipendenze (blockedBy) che impediscono l'avvio fino al completamento delle dipendenze.

pending ──→ in_progress ──→ completed
   │                              ▲
   │         blockedBy            │
   └── (attende dipendenze) ──────┘

File locking per auto-rivendicazione:
  Compagno A completa Task #1
       ↓
  Compagno A cerca task pending senza owner
       ↓
  File lock acquisito → Task #2 assegnato
       ↓
  Nessuna race condition

3.2 Modalità di Assegnazione

I task possono essere assegnati in due modi, e nella pratica ho trovato che la combinazione di entrambi è la più efficace.

1. Assegnazione dal lead: si chiede al lead quale task assegnare a quale compagno. Utile per task che richiedono competenze specifiche o un ordine preciso.
2. Auto-rivendicazione: dopo aver completato un task, il compagno raccoglie automaticamente il prossimo task pending non assegnato e non bloccato. Il file locking previene race condition quando più compagni finiscono contemporaneamente.

Nella mia esperienza, il pattern migliore è assegnare i task iniziali esplicitamente (per dare a ogni compagno il contesto giusto nel prompt di generazione), e poi lasciare che l'auto-rivendicazione gestisca il flusso successivo.

3.3 Comunicazione tra Agenti

La comunicazione avviene tramite il sistema di mailbox con il tool SendMessage. Ogni compagno può inviare messaggi a qualsiasi altro compagno (indirizzando per nome) o in broadcast a tutto il team.

// Messaggio diretto a un compagno specifico
SendMessage({
  to: "researcher",
  message: "La ricerca è pronta, puoi iniziare a scrivere",
  summary: "Ricerca completata"
})

// Broadcast a tutto il team (usare con parsimonia!)
SendMessage({
  to: "*",
  message: "Problema critico trovato — stop a tutto il lavoro",
  summary: "Blocco critico"
})

// Richiesta di shutdown
SendMessage({
  to: "researcher",
  message: {
    type: "shutdown_request",
    reason: "Task completato, chiusura sessione"
  }
})

3.4 Prompt di Avvio del Team

Il modo più naturale per avviare un team è descrivere il compito e la struttura in linguaggio naturale. Claude crea il team, genera i compagni e coordina il lavoro automaticamente.

// Esempio di prompt per avviare un team di revisione parallela
"Crea un team di agenti per revisionare la PR #142. Genera tre revisori:
- Uno focalizzato sulle implicazioni di sicurezza
- Uno che controlla l'impatto sulle prestazioni
- Uno che convalida la copertura dei test
Che ognuno esamini e riporti i risultati."

// Esempio per debug con ipotesi concorrenti
"Gli utenti segnalano che l'app esce dopo un messaggio.
Genera 5 compagni per investigare diverse ipotesi.
Fate loro parlare tra loro per confutare le teorie reciproche,
come un dibattito scientifico."

4. Modalità di Visualizzazione e Controllo del Team

4.1 In-Process vs Split Panes

Claude Code supporta due modalità di visualizzazione per i team, con trade-off diversi.

// Configurazione in settings.json
{
  "teammateMode": "in-process"  // oppure "split-panes", "auto"
}

// "auto" (default): split panes se già in tmux, altrimenti in-process

// Flag per sessione singola
// $ claude --teammate-mode in-process

4.2 Interazione Diretta con i Compagni

Ogni compagno di team è una sessione Claude Code completa. Si può interagire direttamente senza passare dal lead, il che è una differenza fondamentale rispetto ai sub-agent.

4.3 Approvazione del Piano

Si può richiedere ai compagni di pianificare prima di implementare, dando al lead (o all'utente) la possibilità di approvare o rifiutare il piano con feedback.

// Nel prompt di generazione del compagno
"Genera un compagno architetto per refactorizzare il modulo auth.
Richiedi l'approvazione del piano prima che apportino modifiche."

// Il compagno entra in Plan Mode, analizza con operazioni read-only,
// propone un piano, e il lead lo approva o rifiuta con feedback.
// Solo dopo approvazione il compagno può modificare i file.

4.4 Shutdown e Cleanup

Lo shutdown di un compagno è collaborativo: il lead invia una richiesta, il compagno può approvare o rifiutare (se sta ancora lavorando). Per il cleanup del team, usare sempre il lead.

// Shutdown di un compagno specifico
"Chiedi al compagno ricercatore di spegnersi"
// Il lead invia shutdown_request, il compagno approva/rifiuta

// Cleanup dell'intero team
"Pulisci il team"
// Verifica che tutti i compagni siano fermi, poi rimuove il team
// FALLISCE se ci sono compagni ancora attivi

5. Sub-Agent: Tipologie e Quando Usarli

5.1 Differenza Fondamentale: Sub-Agent vs Team

La distinzione tra sub-agent e compagni di team è cruciale per scegliere l'architettura giusta. I sub-agent sono worker focalizzati che operano dentro una sessione e restituiscono un riassunto. I compagni di team sono sessioni indipendenti che comunicano tra pari.

5.2 Sub-Agent Integrati

Claude Code include diversi sub-agent integrati, ognuno ottimizzato per uno specifico tipo di lavoro.

La scelta del modello è strategica: Explore usa Haiku per la velocità (è un'operazione read-only che non richiede ragionamento complesso), mentre Plan eredita il modello principale perché la qualità della pianificazione impatta direttamente l'implementazione.

5.3 Creare Sub-Agent Personalizzati

La vera potenza dei sub-agent emerge quando si creano agent personalizzati, definiti come file Markdown con frontmatter YAML in .claude/agents/ (progetto) o ~/.claude/agents/ (utente).

---
name: code-reviewer
description: Expert code review specialist. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: sonnet
permissionMode: default
---

You are a senior code reviewer ensuring high standards.

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code that should be abstracted
- Proper error handling for edge cases
- No exposed secrets or credentials
- Input validation at system boundaries
- Good test coverage for new functionality
- Performance considerations addressed

5.4 Frontmatter: Tutti i Campi Disponibili

5.5 Priorità di Risoluzione

Quando esistono più definizioni dello stesso sub-agent, la priorità segue un ordine preciso.

5.6 Foreground vs Background

I sub-agent possono eseguire in foreground (bloccante, prompt di autorizzazione passati all'utente) o in background (concorrente, autorizzazioni pre-approvate, il resto auto-negato). Il flag background: true nel frontmatter forza l'esecuzione in background per ogni invocazione.

// Sub-agent in foreground (default)
// - Bloccante: il main agent attende il risultato
// - Utile quando il risultato è necessario prima di procedere

// Sub-agent in background
// - Concorrente: il main agent continua a lavorare
// - Notifica automatica al completamento
// - Ideale per task indipendenti (test, linting, ricerca)

// Esempio: lancio parallelo di più sub-agent
// Il main agent lancia 3 ricerche e continua a lavorare
Agent({ prompt: "Find auth files", subagent_type: "Explore", run_in_background: true })
Agent({ prompt: "Find test files", subagent_type: "Explore", run_in_background: true })
Agent({ prompt: "Find config files", subagent_type: "Explore", run_in_background: true })

6. Git Worktrees: Isolamento e Parallelismo

6.1 Il Problema dei Conflitti di File

Quando più agenti lavorano sullo stesso repository, i conflitti di file sono inevitabili. Due sessioni che modificano lo stesso file contemporaneamente producono risultati imprevedibili. Git worktrees risolvono questo problema alla radice: ogni sessione lavora su una copia isolata del repository, con il proprio branch.

6.2 Come Funzionano in Claude Code

# Avviare sessioni parallele con worktree denominati
claude --worktree feature-auth     # Worktree "feature-auth"
claude --worktree bugfix-123       # Worktree "bugfix-123"
claude --worktree                  # Nome auto-generato

# I worktree vengono creati in:
# <repo>/.claude/worktrees/<name>
# Su branch: worktree-<name>

Ogni worktree è una copia completa della working directory con il proprio branch Git. Le modifiche in un worktree non influenzano gli altri. Al termine, se non ci sono modifiche, il worktree viene rimosso automaticamente; se ci sono modifiche, Claude chiede se mantenerlo.

6.3 Worktree nei Sub-Agent

I sub-agent possono usare l'isolamento worktree con il parametro isolation: "worktree". Questo è particolarmente utile quando un sub-agent deve fare modifiche sperimentali senza rischiare di corrompere il repository principale.

// Lancio sub-agent con isolamento worktree
Agent({
  prompt: "Prova a refactorizzare il modulo auth usando il pattern Strategy",
  isolation: "worktree",
  run_in_background: true
})

// Il sub-agent lavora su una copia isolata
// Se le modifiche funzionano → branch e path restituiti nel risultato
// Se nessuna modifica → worktree rimosso automaticamente

6.4 Pattern Comune: Writer/Reviewer

Uno dei pattern più efficaci che utilizzo è il modello Writer/Reviewer con worktree separati: una sessione implementa le modifiche, l'altra revisiona in tempo reale.

Sessione 1 (Writer)                  Sessione 2 (Reviewer)
claude --worktree impl               claude --worktree review
         │                                     │
    Implementa feature                   Revisiona codice
    Scrive test                          Controlla qualità
    Commit su worktree-impl              Feedback al writer
         │                                     │
         └────── git merge ───────────→ Branch principale

7. CLAUDE.md: Il Contratto tra Sviluppatore e AI

7.1 Cos'è e Perché è Cruciale

Il file CLAUDE.md è il contesto persistente che viene caricato all'inizio di ogni sessione Claude Code. È il "contratto" tra lo sviluppatore e l'AI: definisce le regole, le convenzioni, i comandi e le stranezze del progetto che Claude deve conoscere. Ogni compagno di team e ogni sub-agent carica lo stesso CLAUDE.md, garantendo coerenza nelle convenzioni.

La regola d'oro: mantenere il CLAUDE.md sotto 200 righe. Un file troppo lungo degrada le prestazioni, perché consuma contesto prezioso ad ogni richiesta. Se cresce, spostare i contenuti in skills (caricate su richiesta) o in file .claude/rules/ (caricati per pattern).

7.2 Cosa Includere vs Cosa Escludere

7.3 Struttura di un CLAUDE.md Efficace

Dopo molti progetti, ho converguto su una struttura che funziona in modo affidabile. La chiave è essere chirurgici: ogni riga deve guadagnarsi il suo posto nel file.

# CLAUDE.md

## Commands
```bash
npm run dev          # Dev server (localhost:3000)
npm run build        # Production build
npm run lint         # ESLint
npm run test         # Jest con coverage
```

## Architecture
**Next.js 16 App Router + Sanity CMS + Tailwind CSS.**
Contenuti in Sanity (project: 5ipkzs9u, dataset: production).
Pages statiche con ISR (revalidate = 3600).

## Key Patterns
- Dynamic params: Next.js 15+ richiede `await params`
- Immagini: sempre <Image> con alt + title da Sanity
- PortableText: usare portableTextComponents ovunque

## Anti-patterns
- MAI usare `as any` per window.dataLayer (tipo in global.d.ts)
- MAI committare file .env
- MAI usare npm (progetto usa pnpm)

7.4 Posizioni e Cascading

I file CLAUDE.md possono esistere a più livelli e si sommano (sono additivi):

1. ~/.claude/CLAUDE.md — regole globali per tutti i progetti
2. <project-root>/CLAUDE.md — regole specifiche del progetto (in git)
3. <directory>/CLAUDE.md — regole per sotto-directory (override locale)

Tutti i livelli vengono caricati e contribuiscono al contesto. È possibile importare file esterni con la sintassi @path/to/file nel CLAUDE.md.

8. Best Practice di Prompt Engineering per Claude Code

8.1 Il Principio della Verifica

Dare a Claude un modo per verificare il suo lavoro è la singola azione con il massimo effetto leva. Claude funziona drammaticamente meglio quando può eseguire test, confrontare screenshot, convalidare output.

8.2 Esplora → Pianifica → Implementa

Il workflow più affidabile che ho trovato separa nettamente le tre fasi. Non è solo un buon consiglio — è un cambio di modalità esplicito in Claude Code.

Fase 1: ESPLORA (Plan Mode, Shift+Tab)
    Claude legge file, non modifica nulla
    Capisce la struttura, le dipendenze, i pattern
         │
         ▼
Fase 2: PIANIFICA
    Piano di implementazione dettagliato
    Ctrl+G per aprire nell'editor di testo
    Revisione e approvazione del piano
         │
         ▼
Fase 3: IMPLEMENTA (Normal Mode)
    Claude codifica verificando rispetto al piano
    Test dopo ogni modifica significativa
         │
         ▼
Fase 4: COMMIT
    Messaggio descrittivo
    PR con contesto

Per task piccoli e ben definiti (fix di un bug specifico, aggiunta di un campo), saltare il piano è legittimo. Ma per qualsiasi modifica che tocca più di 2-3 file, il piano si ripaga in tempo risparmiato.

8.3 Contesto Specifico vs Generico

La qualità del prompt determina la qualità dell'output. Prompt vaghi producono risposte generiche; prompt specifici producono codice corretto al primo tentativo.

Fornire contenuti ricchi

• @ per riferire file specifici: @src/utils/auth.js
• Incollare immagini con Ctrl+V per mockup e screenshot
• Fornire URL di documentazione che Claude può fetchare
• Pipe dati da comandi: cat error.log | claude -p "spiega"
• Lasciare che Claude esplori autonomamente la codebase quando il contesto non è chiaro

8.4 Gestione Aggressiva del Contesto

La finestra di contesto è una risorsa finita. Gestirla attivamente fa la differenza tra un agente che funziona e uno che perde il filo.

1. /clear frequentemente tra task non correlati — è l'azione più sottovalutata
2. /compact <instructions> per compattazione manuale con istruzioni su cosa preservare
3. Esc + Esc → "Summarize from here" per compattazione parziale
4. CLAUDE.md: "When compacting, preserve the full list of modified files" per mantenere traccia
5. /btw per domande rapide che non restano nel contesto principale
6. Sub-agent per investigazioni pesanti che leggono molti file — il risultato è sintetizzato

8.5 Thinking Mode e Ragionamento Adattivo

Il pensiero esteso è abilitato per default con Opus 4.6 e il ragionamento adattivo. Si può controllare il livello di sforzo e il budget di ragionamento.

• Livello di sforzo: configurabile via /model o CLAUDE_CODE_EFFORT_LEVEL
• ultrathink: parola chiave nel prompt per forzare sforzo alto
• Option+T / Alt+T: toggle on/off durante la sessione
• MAX_THINKING_TOKENS: variabile per limitare il budget di ragionamento
• Ctrl+O: modalità verbose per vedere il ragionamento

9. Memory System: Persistenza tra Conversazioni

9.1 Come Funziona la Memoria

Claude Code include un sistema di memoria basato su file che persiste tra conversazioni. La memoria è organizzata in tipi (user, feedback, project, reference) e indicizzata in un file MEMORY.md che viene caricato in ogni sessione.

~/.claude/projects/{project}/memory/
├── MEMORY.md              ← Indice (caricato ogni sessione)
├── user_role.md           ← Chi è l'utente
├── feedback_testing.md    ← Correzioni dell'utente
├── project_sprint.md      ← Stato del progetto
└── reference_linear.md   ← Dove trovare informazioni

Ogni file ha frontmatter:
---
name: user_role
description: Ruolo e competenze dell'utente
type: user
---
[contenuto della memoria]

9.2 Tipi di Memoria

9.3 Cosa NON Salvare

È importante sapere cosa non va in memoria, perché una memoria troppo piena degrada l'indice e consuma contesto inutilmente.

• Code pattern e convenzioni — derivabili leggendo il codice
• Git history e chi ha cambiato cosa — git log/blame sono autorevoli
• Soluzioni di debugging — il fix è nel codice, il contesto nel commit
• Cose già nel CLAUDE.md — evitare duplicazione
• Dettagli di task in corso — usare il sistema di task, non la memoria

9.4 Memoria nei Sub-Agent

I sub-agent personalizzati possono avere la propria memoria persistente, configurata nel frontmatter con il campo memory. La memoria è isolata per scope (user, project, local) e per nome dell'agent.

---
name: code-reviewer
description: Expert code reviewer
tools: Read, Grep, Glob, Bash
memory: project
---

# La memoria del reviewer persiste tra sessioni
# Scope project: .claude/agent-memory/code-reviewer/
# Il reviewer può ricordare pattern problematici già visti,
# preferenze di stile specifiche del progetto,
# e feedback ricorrenti.

10. Hooks e Automazione Deterministica

10.1 Cosa Sono gli Hooks

Gli hooks sono script deterministici che si eseguono automaticamente in risposta ad eventi nel ciclo agentico. A differenza delle istruzioni nel CLAUDE.md (che l'LLM può interpretare in modo variabile), gli hooks sono garantiti: si attivano sempre, eseguono codice predeterminato, e producono risultati prevedibili.

La distinzione chiave: gli hooks hanno costo di contesto zero (a meno che non restituiscano output). Non consumano la finestra di contesto, il che li rende ideali per automazioni frequenti come linting, formattazione, e validazione.

10.2 Tipi di Hooks

10.3 Hooks nei Sub-Agent

I sub-agent personalizzati possono definire i propri hooks nel frontmatter, permettendo automazione specifica per tipo di agent.

---
name: db-reader
description: Execute read-only database queries safely
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

#!/bin/bash
# scripts/validate-readonly-query.sh
# Hook che blocca query di scrittura nel sub-agent db-reader

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Blocca qualsiasi query di modifica
if echo "$COMMAND" | grep -iE \
  '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2  # Exit code 2 = blocca l'azione
fi

exit 0  # Exit code 0 = procedi

10.4 Quality Gate per Team

Gli hooks TeammateIdle e TaskCompleted fungono da quality gate per i team di agenti. Permettono di impedire che un compagno vada inattivo troppo presto o che un task venga completato senza le verifiche necessarie.

// settings.json — Hook per quality gate
{
  "hooks": {
    "TeammateIdle": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/check-teammate-done.sh"
            // Exit code 2 → rimanda il compagno al lavoro
          }
        ]
      }
    ],
    "TaskCompleted": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/validate-task-output.sh"
            // Exit code 2 → impedisce il completamento
          }
        ]
      }
    ]
  }
}

11. Pattern di Orchestrazione Multi-Agente

11.1 Pattern: Ricerca → Scrittura → Revisione

Questo è il pattern che ho usato per scrivere questo stesso paper. Un team di 3 agenti con dipendenze sequenziali.

Task #1: Ricercatore                  Task #2: Writer
(raccoglie documentazione)             (scrive il paper)
         │                                     │
    Legge 5 URL                         Attende Task #1
    Estrae contenuto                    Legge ricerca
    Salva in docs/                      Scrive paper .ts
         │                                     │
    completed ─── sblocca ───→         in_progress
                                               │
                                          completed
                                               │
                                    ─── sblocca ───→
                                               │
                                    Task #3: Brand Reviewer
                                    (verifica coerenza brand)

11.2 Pattern: Debug con Ipotesi Concorrenti

Quando un bug è complesso e le cause possibili sono molteplici, lanciare più agenti che investigano teorie diverse è estremamente efficace. Ogni agente ha una teoria specifica, e possono comunicare peer-to-peer per confutare le ipotesi degli altri.

// Prompt per il team lead
"Gli utenti segnalano latenza intermittente nelle API.
Genera 4 compagni per investigare in parallelo:

1. 'db-investigator': Analizza query lente, indici mancanti, lock contention
2. 'network-investigator': Controlla DNS, connection pool, timeout
3. 'memory-investigator': Cerca memory leak, GC pause, cache eviction
4. 'code-investigator': Profila hot path, N+1 query, serializzazione

Fate loro parlare tra loro per escludere ipotesi.
Aggiornate un documento di risultati con il consenso."

11.3 Pattern: Feature Multi-Layer

Per feature che attraversano più layer (database, API, frontend, test), ogni compagno possiede un layer e lavora in parallelo.

11.4 Pattern: Fan-Out per File

Per operazioni ripetitive su molti file (migrazione di framework, aggiornamento API, formattazione), il fan-out automatizza il lavoro.

# Fan-out: migrazione React → Vue su tutti i componenti
for file in $(cat components-to-migrate.txt); do
  claude -p "Migrate $file from React to Vue. \
    Follow the pattern in @src/components/Button.vue." \
    --allowedTools "Edit,Bash(git commit *)" &
done
wait  # Attendi il completamento di tutti i processi paralleli

# Ogni invocazione è una sessione separata con il proprio contesto
# Nessun rischio di saturazione: un file per sessione

12. Workflow Comuni con Esempi Reali

12.1 Esplorare una Codebase Sconosciuta

Quando inizio a lavorare su un progetto nuovo — che sia un sito Next.js per un cliente o un'integrazione con Sanity CMS — il primo passo è sempre una sessione di esplorazione guidata. Claude Code eccelle in questo, specialmente usando il sub-agent Explore che opera con Haiku per velocità.

# Sessione di esplorazione
$ claude

> give me an overview of this codebase

> explain the main architecture patterns used

> what are the key data models?

> how is authentication handled?

> trace the login process from front-end to database

# Per esplorazioni più profonde, Claude delega
# automaticamente al sub-agent Explore (Haiku)
# che legge file senza consumare il contesto principale

12.2 Bug Fixing con Verifica

Il workflow di bug fixing più efficace che ho trovato segue un pattern preciso: condividere l'errore, chiedere analisi, applicare il fix, verificare.

# 1. Condividere l'errore specifico
> I'm seeing "TypeError: Cannot read property 'id' of undefined"
> when calling POST /api/users with an empty body.
> The error is in src/api/users.ts:42.

# 2. Claude analizza, suggerisce fix
# 3. Applicare e verificare
> apply the fix and run the test suite to verify

# 4. Se il fix introduce regressioni
> the fix works for the empty body case but now the test
> "should create user with valid data" fails. Fix it.

12.3 Creare Pull Request

Claude Code può gestire l'intero ciclo di una PR, dal riassunto delle modifiche alla creazione con gh.

# Riassumere le modifiche
> summarize the changes I've made to the authentication module

# Creare la PR
> create a pr

# Claude usa gh pr create con titolo e body appropriati.
# La sessione viene automaticamente collegata alla PR.
# In futuro: claude --from-pr 142 per riprendere.

12.4 Claude come Utilità Unix

Claude Code si integra perfettamente nella pipeline Unix: accetta input da stdin, produce output su stdout, e supporta formati strutturati.

# Pipeline Unix: analisi di un log di errori
cat build-error.txt | claude -p 'explain the root cause' > analysis.txt

# JSON strutturato per automazione
claude -p "list all TODO comments in src/" --output-format json

# Streaming JSON per processi lunghi
claude -p "refactor all components" --output-format stream-json

# Linter personalizzato in package.json
{
  "scripts": {
    "lint:claude": "claude -p 'you are a linter. Check src/ for...'"
  }
}

12.5 Riprendere Conversazioni

La possibilità di riprendere conversazioni è fondamentale per progetti che durano più sessioni. Claude Code offre diverse modalità.

# Riprendere la conversazione più recente
claude --continue

# Selettore interattivo con anteprima
claude --resume

# Riprendere sessione collegata a una PR
claude --from-pr 142

# Dare nomi descrittivi alle sessioni
/rename "refactoring auth module"

13. L'Ecosistema di Estensibilità di Claude Code

13.1 Panoramica delle Estensioni

Claude Code non è un tool monolitico ma una piattaforma estensibile. Le estensioni si collegano a diverse parti del ciclo agentico, dalla configurazione persistente all'automazione deterministica.

13.2 Combinazioni Efficaci

Le estensioni non sono mutuamente esclusive — le combinazioni più potenti emergono dall'uso congiunto.

13.3 Skills: Conoscenze Riutilizzabili

Le skills sono file SKILL.md in .claude/skills/ con frontmatter YAML. Possono essere di riferimento (caricate quando rilevanti) o invocabili (attivate con /<name>).

---
name: deploy
description: Checklist di distribuzione per il progetto
user-invocable: true
---

# Deployment Checklist

1. Verificare che tutti i test passino: `npm run test`
2. Build di produzione: `npm run build`
3. Controllare bundle size con `npx next-bundle-analyzer`
4. Creare tag git: `git tag v$(date +%Y.%m.%d)`
5. Push con tags: `git push --tags`
6. Verificare deploy su Vercel dashboard

13.4 Stratificazione e Priorità

Quando la stessa estensione è definita a più livelli, la regola di precedenza varia per tipo.

• CLAUDE.md: additivi — tutti i livelli contribuiscono
• Skills e sub-agent: si sovrascrivono per nome (gestito > utente > progetto)
• Server MCP: si sovrascrivono per nome (locale > progetto > utente)
• Hooks: si uniscono — tutti si attivano per i loro eventi

14. Confronto Funzionalità e Scelte Architetturali

14.1 Skill vs Sub-Agent

14.2 CLAUDE.md vs Skill

14.3 Sub-Agent vs Compagno di Team

La scelta tra sub-agent e compagno di team dipende dalla natura del lavoro e dal livello di collaborazione richiesto.

14.4 MCP vs Skill

15. Anti-Pattern e Errori Comuni

15.1 I Cinque Anti-Pattern Più Costosi

Dopo mesi di utilizzo intensivo di Claude Code — dal refactoring del mio sito alla creazione di pipeline AI — ho identificato cinque anti-pattern ricorrenti che consumano tempo e token in modo sproporzionato.

Anti-Pattern 1: La Sessione Lavandino

Sintomo: una singola sessione accumula task di natura diversa — bug fix, refactoring, nuova feature, documentazione — fino a quando il contesto si satura e Claude perde il filo.

Soluzione: /clear tra task non correlati. Ogni task merita un contesto pulito. Il costo di un /clear è zero; il costo di un contesto inquinato è alto.

Anti-Pattern 2: Correggere più di Due Volte

Sintomo: il primo tentativo non funziona, si corregge, il secondo fallisce, si corregge ancora. Ogni correzione inietta approcci falliti nel contesto, peggiorando le iterazioni successive.

Soluzione: dopo due correzioni fallite, /clear e ricominciare con un prompt migliore. La terza correzione sullo stesso contesto inquinato quasi mai funziona.

Anti-Pattern 3: CLAUDE.md Eccessivo

Sintomo: un CLAUDE.md di 500+ righe con istruzioni dettagliate per ogni file. Il modello ignora regole in fondo al file; il contesto viene consumato inutilmente ad ogni richiesta.

Soluzione: potare spietatamente. Spostare contenuti in skills (su richiesta) e .claude/rules/ (per pattern). Obiettivo: sotto 200 righe, ogni riga giustificata.

Anti-Pattern 4: Fiducia Senza Verifica

Sintomo: accettare l'implementazione di Claude senza mai eseguire test o verificare visivamente. "Sembra giusto" non è un criterio.

Soluzione: includere sempre criteri di verifica nel prompt. "Implementa X e poi esegui i test" è sempre meglio di "Implementa X".

Anti-Pattern 5: Esplorazione Infinita

Sintomo: Claude legge centinaia di file cercando qualcosa, consumando il contesto senza arrivare a una risposta.

Soluzione: limitare l'ambito con direttive specifiche, oppure delegare al sub-agent Explore (che ha il proprio contesto isolato e usa Haiku per velocità).

16. Metriche e Performance

16.1 Consumo di Contesto per Funzionalità

16.2 Linee Guida per il Sizing del Team

16.3 Trade-Off: Token vs Tempo

I team di agenti consumano significativamente più token rispetto a una singola sessione, ma possono ridurre il tempo wall-clock in modo sostanziale quando il lavoro è parallelizzabile.

Sessione Singola:
  Task A (20min) → Task B (15min) → Task C (10min)
  Totale: 45 minuti, ~50K token

Team 3 Compagni:
  Task A (20min) ─┐
  Task B (15min) ─┼── Parallelo
  Task C (10min) ─┘
  Totale: ~20 minuti, ~120K token

Trade-off: 2.4x token, ma 2.25x più veloce

17. Case Study: Questo Paper come Meta-Esempio

17.1 Setup del Team

Questo paper è stato scritto utilizzando esattamente l'architettura multi-agente che descrive. Un team di 3 agenti Claude Code, coordinati da un team lead, ha collaborato per produrre il contenuto.

Nella screenshot qui sotto si vede il setup reale: il terminale principale (team lead) al centro, con i tre compagni di team visibili nei pannelli laterali — ognuno che lavora autonomamente sul proprio task.

17.2 Flusso di Lavoro

Team Lead (crea team e task)
         │
    Task #1 → Researcher
         │     Legge 5 pagine di documentazione
         │     Salva in docs/paper-02-research.md
         │     Notifica il writer via SendMessage
         │
    Task #2 → Writer (bloccato da #1)
         │     Legge la ricerca
         │     Legge il paper 01 come riferimento
         │     Scrive 02-agent-teams-claude-code.ts
         │     Notifica il brand-reviewer
         │
    Task #3 → Brand Reviewer (bloccato da #2)
               Verifica tono, coerenza, qualità
               Applica modifiche direttamente

17.3 Cosa Ha Funzionato

1. Separazione dei contesti: il researcher ha potuto leggere migliaia di righe di documentazione senza saturare il contesto del writer.
2. Dipendenze esplicite: il blockedBy ha impedito al writer di iniziare prima che la ricerca fosse completa, evitando lavoro su dati parziali.
3. Comunicazione diretta: il researcher ha notificato il writer via SendMessage al completamento, senza bisogno di polling.
4. Specializzazione: ogni agente aveva un prompt di sistema focalizzato sul suo ruolo, con istruzioni specifiche per il tipo di output atteso.

17.4 Lezioni Apprese

• Il prompt di generazione dei compagni deve includere tutto il contesto necessario — non ereditano la cronologia del lead.
• I task sequenziali (come in questo caso) beneficiano meno del parallelismo rispetto a task indipendenti. Per un paper lineare, la pipeline sequenziale era comunque la scelta giusta.
• Il formato del file di output (TypeScript con helper functions) doveva essere specificato esplicitamente nel prompt del writer, con riferimento al paper 01 come template.

18. Permessi e Sicurezza nei Team Multi-Agente

18.1 Ereditarietà dei Permessi

I compagni di team ereditano le impostazioni di permesso del lead al momento della generazione. Se il lead usa --dangerously-skip-permissions, lo fanno anche i compagni. Questo rende cruciale configurare i permessi correttamente prima di avviare un team.

18.2 Modalità di Autorizzazione

18.3 Sandbox e Isolamento

Per sessioni automatizzate o CI/CD, Claude Code supporta sandbox a livello di OS con /sandbox. Combinato con --dangerously-skip-permissions in un ambiente senza accesso Internet, permette esecuzione completamente non presidiata in sicurezza.

19. Limitazioni Note e Roadmap

19.1 Limitazioni Attuali dei Team

I team di agenti sono una feature sperimentale con limitazioni concrete che è importante conoscere prima dell'adozione.

• Nessuna ripresa della sessione con compagni in-process — se il terminale si chiude, i compagni sono persi
• Lo stato dei task può ritardare nella propagazione tra compagni
• Lo shutdown dei compagni può essere lento (negoziazione collaborativa)
• Un solo team per sessione — non si possono annidare team
• Il lead è fisso — non si può promuovere un compagno a lead
• I permessi sono impostati al momento della generazione — non modificabili a runtime
• Split panes richiedono tmux o iTerm2 — non disponibili su tutti i setup

19.2 Dove Stanno Andando

Nonostante le limitazioni attuali, la direzione è chiara: i team multi-agente diventeranno il modo standard di affrontare progetti complessi con AI. I pattern che funzionano oggi — separazione dei contesti, task list condivisa, comunicazione peer-to-peer — sono fondamentali e continueranno a evolversi.

20. Conclusioni

L'orchestrazione multi-agente in Claude Code non è una feature nice-to-have — è un cambio di paradigma nel modo in cui si lavora con gli AI coding assistant. La differenza tra usare una singola sessione e coordinare un team di agenti specializzati è paragonabile alla differenza tra avere un singolo sviluppatore e un team completo.

Le lezioni chiave che ho tratto dall'esperienza diretta con i team di agenti sono tre.

Prima: il contesto è la risorsa più preziosa. Ogni scelta architetturale in Claude Code — sub-agent, team, worktrees, skills — ruota intorno alla gestione efficace del contesto. Capire questo principio guida tutte le decisioni operative.

Seconda: la specializzazione batte la generalizzazione. Un sub-agent con prompt focalizzato e strumenti limitati produce risultati migliori di una sessione generale con accesso a tutto. La restrizione è una feature, non un limite.

Terza: l'automazione deterministica è complementare all'AI, non sostitutiva. Gli hooks garantiscono azioni che l'LLM potrebbe dimenticare (linting, validazione, notifiche). L'AI si occupa del ragionamento; gli hooks si occupano della disciplina.

Il futuro del development con AI non è un singolo agente onnisciente. È un ecosistema di agenti specializzati che collaborano, ognuno eccellente nel suo dominio, coordinati da un'architettura che distribuisce il lavoro e gestisce il contesto in modo intelligente. Nella mia esperienza quotidiana — dalla costruzione di questo sito alla pipeline di generazione carousel, fino alla stesura di questo stesso paper — i team multi-agente hanno già cambiato concretamente il modo in cui lavoro. Le fondamenta sono solide e utilizzabili oggi.

Appendice: Cheat Sheet Comandi e Scorciatoie

A.1 Comandi CLI Essenziali

A.2 Scorciatoie da Tastiera

A.3 Comandi In-Session