Tutti parlano dei loop. Quasi nessuno parla di ciò su cui il loop si basa. 9 sviluppatori su 10 eseguono Claude Code sull'infrastruttura predefinita - niente regole, niente sottoagenti, niente hook, niente memoria.
Poi si chiedono perché il loro loop produce robaccia. La verità è semplice: un loop vale quanto l'infrastruttura su cui si basa. Questa è la roadmap in 14 passi per costruire l'infrastruttura - da un singolo agente a un sistema che migliora se stesso.
Seguimi su Substack per ricevere novità sull'AI:
L'ingegneria dei loop - costruire un sistema che interroga il tuo agente a intervalli regolari - ha ricevuto tutta l'attenzione questo mese. Ma Addy Osmani, che ha scritto l'articolo approfondito sui loop, è stato attento a sottolineare ciò che sta alla base:
"L'ingegneria dei loop si trova un piano sopra l'infrastruttura. L'infrastruttura è l'ambiente in cui un singolo agente opera. Il loop è l'infrastruttura, ma gira su un timer, genera assistenti e si auto-alimenta."
L'ingegneria dell'infrastruttura consiste nel progettare quell'ambiente: il modello, gli strumenti, i permessi, il contesto, la memoria.
È lo strato poco appariscente - ed è quello che determina se tutto ciò che sta sopra funziona. Un grande loop su una cattiva infrastruttura è un modo rapido per produrre spazzatura su larga scala.
14 passi. 3 livelli. Le fondamenta su cui tutto il resto si regge.
Parte 1 · Cos'è l'infrastruttura
01. Un'infrastruttura è l'ambiente in cui un agente opera.
Togliendo il gergo, un'infrastruttura è composta da quattro cose: il modello che elabora, gli strumenti a cui può accedere, i permessi su quegli strumenti e il contesto che legge all'inizio di ogni esecuzione.
Questa è l'intera superficie. Tutto il resto - sottoagenti, hook, memoria - è un modo per modellare uno di questi quattro elementi.
Il motivo per cui l'infrastruttura è più importante di quanto si pensi: l'agente è un ciclo while True che sceglie uno strumento, lo esegue, osserva il risultato e decide la prossima mossa.
L'infrastruttura definisce quali strumenti esistono, cosa l'agente può fare e cosa sa all'avvio. Stesso modello, infrastruttura diversa, agente completamente diverso.
02. L'intera infrastruttura vive in una cartella. .claude/
Tutto ciò che modella il tuo agente risiede in una singola directory nella root del tuo progetto. Impara questa struttura e potrai leggere l'infrastruttura di chiunque a colpo d'occhio:
1.claude/2├─ CLAUDE.md # fatti permanenti — letti a ogni sessione3├─ settings.json # permessi, modello, hook4├─ .mcp.json # connessioni a strumenti esterni5├─ rules/ # comportamenti specifici per percorso6│ ├─ tests.md7│ └─ python-types.md8├─ agents/ # definizioni dei sottoagenti (~30 righe ciascuna)9│ ├─ reviewer.md10│ └─ eval-runner.md11├─ skills/ # flussi di lavoro riutilizzabili12│ └─ pr-checklist/13│ └─ SKILL.md14└─ agent-memory/ # ciò che sopravvive tra un'esecuzione e l'altra15 └─ STATE.md
Una regola che distingue un'infrastruttura pulita da un caos: mantienila abbastanza piccola da poter spiegare perché ogni file esiste. Se non sai dire a cosa serve una regola, un hook o un sottoagente, cancellalo.
03. Infrastruttura vs loop vs sistema. Tre piani, non mischiarli.
La maggior parte dei problemi del tipo "la mia configurazione dell'agente è un disastro" nasce dalla confusione tra i tre piani. Tienili distinti:
- L'infrastruttura è l'ambiente di esecuzione in cui vive un agente. Configurazione statica: modello, strumenti, permessi, contesto. Questo numero.
- Il loop interroga l'agente su un timer, genera assistenti, si auto-alimenta. Gira sopra l'infrastruttura.
- Il sistema auto-migliorante è un loop più memoria che si accumula - ogni esecuzione lascia la successiva più affinata.
La versione pratica: metti i fatti permanenti nel contesto, le imposizioni negli hook, le procedure nelle skill e l'isolamento nei sottoagenti.
Confondere queste cose - imposizioni in CLAUDE.md, procedure che appesantiscono il contesto - è la causa principale di agenti incoerenti e costosi.
04. L'infrastruttura predefinita. Quello che ottieni subito.
Installa Claude Code, apri una cartella e hai già un'infrastruttura - solo che è vuota. Quella predefinita ti dà un modello capace, gli strumenti integrati (leggi, scrivi, bash, cerca) e richieste di approvazione per tutto ciò che è rischioso. Nessun contesto di progetto, nessun sottoagente personalizzato, nessuna memoria.
Per un'attività una tantum, quella predefinita va bene. Per qualsiasi cosa tu faccia più di una volta, quella predefinita costringe l'agente a re-imparare il tuo progetto da zero a ogni sessione, a chiedere il permesso per operazioni sicure e a dimenticare tutto quando chiudi il terminale.
I prossimi dieci passi servono a colmare questo divario.
05. CLAUDE.md: fatti permanenti, mantenuti brevi.
CLAUDE.md viene letto all'inizio di ogni sessione. È la conoscenza permanente che l'agente ha del tuo progetto - convenzioni, architettura, il "non lo facciamo così perché di quell'incidente."
L'errore più comune in assoluto: lasciare che diventi un enorme documento di procedure che appesantisce ogni sessione.
La regola di chi lo usa quotidianamente: mantieni il file di memoria principale sotto i ~500 token. I fatti permanenti vanno qui.
Le procedure multi-step vanno nelle skill (passo 8). I comportamenti specifici per percorso vanno nei file rules/ limitati al percorso in cui si applicano. Se una sezione di CLAUDE.md è diventata una procedura invece che un fatto, appartiene a un altro posto.
Leggi il tuo CLAUDE.md ad alta voce. Ogni riga dovrebbe essere un
fatto
di cui l'agente ha bisogno in ogni sessione ("usiamo pnpm, non npm"). Se una riga è una
procedura
("per aggiungere una funzionalità, prima..."), spostala in una skill.
Se è una regola per una cartella specifica, spostala in rules/.
06. settings.json: permessi e modello, impostati una volta.
L'infrastruttura predefinita chiede il permesso prima di ogni azione rischiosa. È giusto quando stai guardando, è sbagliato quando non ci sei. settings.json è dove pre-approvi le cose sicure, neghi quelle pericolose e scegli quale modello eseguire.
1{2 "model": "claude-sonnet-4-6",3 "permissions": {4 "autoApprove": [5 "Read(*)", "Grep(*)",6 "Bash(npm test)", "Bash(git status)"7 ],8 "deny": [9 "Bash(rm -rf*)", "Bash(git push*)",10 "Edit(.env*)", "Edit(secrets/*)"11 ]12 }13}
Il test per decidere cosa auto-approvare: se va storto, quanto è difficile rimediare? Economico da annullare → auto-approva.
Costoso da annullare (force-push, cancellare file, toccare segreti) → nega sempre o chiedi conferma. La via di mezzo va bene per l'auto-approvazione se tieni un registro.
07. Sottoagenti: contesto isolato per il lavoro sporco.
Un sottoagente è una sessione Claude indipendente lanciata da quella principale - la sua finestra di contesto, la sua lista di strumenti. Il punto non è il parallelismo fine a se stesso. È tenere il rumore fuori dal contesto principale.
Un'attività di ricerca che legge 40 file, un passaggio di revisione che necessita di una prospettiva fresca, un'esecuzione di valutazione che produce un muro di log - queste cose appartengono a un sottoagente in modo da non inquinare il thread principale.
GIF
Il sottoagente più prezioso in qualsiasi infrastruttura è quello che controlla il lavoro fatto dall'agente principale. Un modello che rivede il proprio output è troppo indulgente con se stesso;
Un revisore separato con una finestra di contesto fresca coglie ciò che lo scrittore si è fatto passare. Questa è la divisione scrittore-controllore che rende affidabile ogni loop sopra l'infrastruttura.
08. Skill: procedure che l'agente riutilizza.
Una Skill è un file SKILL.md che l'agente esegue - sia quando lo chiami con /skill-name sia automaticamente quando l'attività corrisponde alla sua descrizione.
A differenza di un sottoagente, viene eseguita nella stessa finestra di contesto. Sono solo istruzioni riutilizzabili che diventano parte della sessione.
Il segnale per crearne una: noti di aver incollato le stesse istruzioni in ogni nuova conversazione. Questa è una skill in attesa di nascere. Una checklist per la PR, una procedura di valutazione, un processo di rilascio - scritta una volta, richiamata per sempre.
E poiché le skill sono l'unità riutilizzabile, sono ciò che fa migliorare l'infrastruttura nel tempo: ogni volta che la procedura fallisce in un modo nuovo, aggiungi la lezione alla skill, e l'esecuzione successiva la eredita.
09. Hook: regole deterministiche che il modello non può allucinare.
Tutto ciò che abbiamo visto finora dipende dalla capacità del modello di comprendere le tue istruzioni. Gli hook no.
Un hook è un comando shell che si attiva in un punto fisso del ciclo di vita dell'agente - prima che uno strumento venga eseguito, dopo che un file viene modificato, quando la sessione termina - e il suo codice di uscita può bloccare l'azione. Gli hook sono imposizioni, CLAUDE.md è un suggerimento.
Due hook meritano un posto in quasi tutte le infrastrutture:
- Un gate PreToolUse che blocca i comandi pericolosi in modo deterministico — rm -rf, lettura di .env, push su main. Il codice di uscita 2 ferma la chiamata prima che avvenga. Il modello non può convincerlo a farlo passare.
- Un formattatore PostToolUse che esegue il linter o il formattatore dopo ogni modifica. L'agente non spedirà mai codice non formattato perché l'infrastruttura lo formatta automaticamente.
1"hooks": {2 "PreToolUse": [{3 "matcher": "Bash",4 "command": "./.claude/hooks/block-dangerous.sh"5 // exit 2 = blocca la chiamata prima che venga eseguita6 }],7 "PostToolUse": [{8 "matcher": "Edit|Write",9 "command": "prettier --write \"$CLAUDE_FILE_PATH\""10 }]11}
Usa gli hook per qualsiasi cosa che deve accadere o non deve mai accadere - sicurezza, formattazione, registrazione di controllo.
Non usarli per decisioni che richiedono giudizio; è a questo che serve il modello. Una buona infrastruttura ha uno o due hook precisi, non venti.
Parte 3 · Fallo accumulare
10. Aggiungi un loop. Ora l'infrastruttura gira su un timer.
Un'infrastruttura configurata aspetta ancora che tu scriva qualcosa. Un loop la fa funzionare da sola. La versione più semplice è /loop in Claude Code - un prompt ricorrente con una certa cadenza.
Abbinalo a /goal e il loop continua finché una condizione obiettiva non è vera, verificata da un valutatore indipendente piuttosto che dall'agente che valuta se stesso.
1> /loop 30m /goal Tutti i test passano e il lint è pulito.2 Classifica i nuovi fallimenti, abbozza le correzioni nei branch claude/.34▲ Claude usa l'infrastruttura che hai costruito:5 - rules/ per le convenzioni6 - sottoagente reviewer per controllare ogni correzione7 - hook PreToolUse blocca i push su main8✓ In loop. Il valutatore indipendente decide quando è "fatto."
Nota cosa è successo: il loop non ha aggiunto intelligenza. Ha riutilizzato tutto ciò che era nell'infrastruttura - le regole, il sottoagente revisore, l'hook di sicurezza. Una buona infrastruttura rende un loop banale. Questo è il senso di costruire prima le fondamenta.
11. Aggiungi flussi di lavoro dinamici. L'infrastruttura scrive la propria orchestrazione.
Per attività troppo complesse per un singolo loop - massivamente parallele, altamente strutturate, avversarie - Claude può scrivere al volo la propria infrastruttura JavaScript.
Questo è un flusso di lavoro dinamico: agent() per generare, parallel() per diramare, pipeline() per mettere in sequenza. Compone i sottoagenti che la tua infrastruttura definisce in schemi come dirama-e-sintetizza o verifica avversaria.
Il collegamento con l'ingegneria dell'infrastruttura: un flusso di lavoro dinamico vale quanto i sottoagenti e le skill che può chiamare.
Se la tua infrastruttura ha un sottoagente revisore affilato e una skill di valutazione ben scritta, il flusso di lavoro ha buoni elementi da orchestrare. Se l'infrastruttura è vuota, il flusso di lavoro non ha nulla con cui lavorare.
Il flusso di lavoro è il direttore d'orchestra, la tua infrastruttura è l'orchestra.
12. Aggiungi memoria. Ciò che l'agente dimentica, l'infrastruttura lo ricorda.
Questo è il passo che trasforma un'infrastruttura configurata in un sistema che migliora davvero. L'agente dimentica tutto tra un'esecuzione e l'altra. L'infrastruttura non deve farlo.
Un file di stato - un file markdown in agent-memory/, o una bacheca Linear - registra cosa è stato provato, cosa ha funzionato, cosa ha fallito, quali regole sono sopravvissute.
Lo schema che fa accumulare la memoria, tratto da come gli agenti più potenti la usano:
- Scrivi prima di andartene. Ogni esecuzione termina aggiornando il file di stato - lezioni apprese, fatti verificati, cosa fare dopo.
- Leggi all'inizio. Ogni esecuzione inizia leggendo il file di stato e le skill pertinenti, in modo da riprendere invece di ricominciare.
- Distilla in skill. Quando una lezione è generale ("i runner Windows hanno bisogno di bash, non PowerShell"), passa dal file di stato a una skill, dove si applica a ogni progetto futuro.
1# Memoria di progetto23## Fatti verificati # smetti di indovinarli4- prc è in dollari, non in centesimi (verificato con SELECT MIN/MAX)5- ordine middleware auth: rate_limit -> jwt -> rbac67## Lezioni apprese # distilla quelle generali in skill8- I runner CI Windows falliscono TLS 1.2 in PowerShell — usa bash9- Le migrazioni su tabelle >1M righe devono essere batch in blocchi da 10k1011## Ultima sessione # riprendi, non ricominciare122026-06-11 · 3 correzioni unite, 2 escalate. Prossimo: verificare la correzione del rate-limit.
13. Chiudi il ciclo. Output → lezione → skill → output migliore.
Ecco dove i tre piani si incastrano in qualcosa che migliora se stesso. Ogni esecuzione produce un output. Il sottoagente revisore (passo 7) lo controlla.
Il risultato - cosa è passato, cosa è fallito, cosa è stato imparato - viene scritto nella memoria (passo 12). Le lezioni generali vengono distillate in skill (passo 8).
L'esecuzione successiva eredita skill più affinate e una memoria più ricca.
Questo è l'intero ciclo auto-migliorante, e nota che è costruito interamente con parti dell'infrastruttura:
- Sottoagente valuta il lavoro - controllo obiettivo, contesto fresco.
- Memoria registra il verdetto - sopravvive tra un'esecuzione e l'altra.
- Skill lo rendono riutilizzabile - le lezioni generali diventano permanentemente applicabili.
- Il loop lo esegue di nuovo - ora con tutto ciò che l'esecuzione precedente ha imparato.
Il modello non è mai cambiato. L'infrastruttura intorno ad esso è diventata più affilata. Questo è ciò che "auto-migliorante" significa onestamente - non un modello che impara, ma un'infrastruttura che accumula.
14. Distribuisci l'infrastruttura. Impacchettala. Condividila. Riutilizzala.
Un'infrastruttura che funziona su un progetto è un asset.
Raggruppa le skill, i sottoagenti e le regole in un plugin e tutto il tuo team installa la stessa configurazione in un unico passaggio - stesse convenzioni, stessi hook di sicurezza, stesso revisore.
L'infrastruttura smette di essere la tua configurazione personale e diventa un'infrastruttura condivisa.
L'ordine di costruzione, un'ultima volta, perché l'ordine è la lezione: rendi affidabile una singola esecuzione manuale su un'infrastruttura pulita.
Aggiungi il contesto e i permessi. Aggiungi un sottoagente revisore. Aggiungi memoria. Poi, e solo allora, avvolgilo in un loop. Un loop su una buona infrastruttura si accumula. Un loop su una cattiva infrastruttura sanguina solo più velocemente.
§ Gli errori dell'infrastruttura che peggiorano ogni loop
- Eseguire sulla configurazione predefinita. Nessun contesto, nessuna regola, nessuna memoria - l'agente re-impara il tuo progetto a ogni sessione.
- Un CLAUDE.md gonfio. Procedure infilate nel contesto permanente, appesantendo ogni esecuzione. Spostale nelle skill.
- Imposizioni in CLAUDE.md invece che negli hook. Il modello può ignorare un suggerimento. Non può ignorare un hook che esce con codice 2.
- Un singolo agente che scrive e valuta il proprio lavoro. Aggiungi un sottoagente revisore con una finestra di contesto fresca.
- Nessuna memoria. Ogni esecuzione riparte da zero. Il file di stato è ciò che permette di riprendere domani.
- Avvolgere un loop intorno a una cattiva infrastruttura. Il loop produce solo robaccia più velocemente. Costruisci prima le fondamenta.
- Venti hook. Uno o due precisi battono un mucchio che nessuno capisce.
- Distribuire un'infrastruttura senza scannerizzarla. Segreti trapelati e permessi troppo ampi si diffondono a chiunque la installi.
Conclusione:
Il loop riceve la gloria. L'infrastruttura fa il lavoro.
L'ingegneria del loop è la parte entusiasmante - l'agente che si auto-interroga, che funziona mentre dormi. Ma un loop è solo un'infrastruttura su un timer.
Tutto ciò che decide se l'output è buono o spazzatura vive un piano più in basso, nel modello che hai scelto, negli strumenti che hai permesso, nel contesto che hai scritto, nel revisore che hai aggiunto, nella memoria che hai conservato.
Costruisci bene quel piano e tutto ciò che sta sopra si accumula: il loop riutilizza i tuoi sottoagenti, il flusso di lavoro orchestra le tue skill, la memoria rende ogni esecuzione più affilata della precedente.
L'auto-miglioramento non è mai stato una proprietà del modello. È una proprietà dell'infrastruttura che costruisci intorno ad esso.
Scegli una cosa che non stai ancora facendo - probabilmente un sottoagente revisore, un hook di sicurezza o un file di stato — e aggiungila oggi. Mantieni l'infrastruttura abbastanza piccola da poterla spiegare. Poi mettici un loop sopra, e guarda le fondamenta fare il lavoro.
