Dizionario dell'IA

Un’etichetta in movimento, non una tecnologia. «IA» non indica una cosa fissa come model o token: si riferisce a ciò che i computer riescono a fare di nuovo e in modo sorprendente. Oggi indica i modelli linguistici di grandi dimensioni; in passato ha indicato cose molto diverse:

L’etichetta si sposta attraverso un meccanismo noto, talvolta chiamato «effetto IA»: quando una tecnica funziona in modo affidabile, la si ribattezza — è «solo» ricerca, «solo» statistica — e «IA» avanza verso la successiva questione irrisolta. L’osservazione è datata. Nel 1971 Bertram Raphael la formulò così: «L’IA è il nome collettivo dei problemi che non sappiamo ancora risolvere correttamente con un computer.» La versione di Larry Tesler, intorno al 1979, era: «L’intelligenza è ciò che le macchine non hanno ancora fatto.»

Ecco perché nelle conversazioni sull’IA spesso non ci si capisce. Un’affermazione come «l’IA non sa ragionare» o «l’IA è sopravvalutata» nasconde una data: potrebbe riferirsi ai sistemi esperti, ai classificatori di immagini degli anni 2010 o al modello linguistico del mese scorso, e ogni riferimento porta a conclusioni diverse. Quando una discussione sull’IA si blocca, di solito basta sostituire la parola con il termine preciso che si intende: il model, l’harness, l’agent, il contesto che gli è stato dato.

Evitare: «IA» in un’affermazione tecnica: specifica la componente a cui ti riferisci. «Programmazione con l’IA» va bene come nome della pratica; «l’IA sta allucinando» no.

Uso:

«Il CTO vuole sapere se l’IA può gestire la coda di triage.»

«Chiariscilo prima di definire l’ambito: intende un modello linguistico in un harness con accesso al sistema di ticket. «IA» da sola non è una specifica.»

I parametri. Non conserva lo stato: esegue la predizione del token successivo e nient’altro. «Claude Opus 4.x» e «GPT-5.x» sono modelli. Da solo un modello non può svolgere azioni da agente: deve essere inserito in un harness.

I modelli non possono leggere file, eseguire comandi, navigare sul web o ricordare il giorno prima: ricevono token e ne predicono altri in uscita, una volta per ogni richiesta al provider del modello. Tutto ciò che sembra un agente al lavoro — scegliere strumenti, leggere risultati, ripetere il ciclo fino al completamento del compito — è l’harness che coordina in sequenza molte di queste predizioni.

I provider di modelli offrono modelli in diverse fasce: uno grande, più intelligente ma lento e costoso, e modelli più piccoli, più rapidi ed economici ma meno capaci. Scegliere una fascia è una decisione concreta: un modello potente per pianificare e risolvere bug difficili, uno leggero per modifiche meccaniche. Gli harness permettono di cambiare modello anche a metà sessione.

Usare il termine con precisione aiuta anche nella diagnosi. «Il modello non è bravo in questo» è un’affermazione specifica: lo stesso modello in un harness diverso o con un contesto diverso può comportarsi in modo completamente diverso. Prima di dare la colpa al modello, controlla che cosa gli è stato fornito: la maggior parte dei risultati deludenti dipende dal contesto o dall’harness, non dai parametri.

Uso:

«Per la fase di pianificazione, dovremmo passare da Sonnet a Opus?»

«Proviamo, ma in questo compito gran parte del lavoro la svolge l’harness. Cambiare modello non aiuterà se il prompt di sistema e gli strumenti non sono quelli giusti.»

I numeri contenuti in un modello, spesso miliardi, regolati durante il training. Tutto ciò che il modello «sa» è racchiuso in quei numeri. Il training li imposta; l’inferenza li usa senza modificarli. Sono chiamati anche pesi.

Dal punto di vista operativo, sono i parametri a trasformare l’input in output. La predizione del token successivo è un calcolo enorme: i token nella finestra di contesto vengono elaborati attraverso i parametri e ne emerge una previsione del token successivo. Nel modello non c’è un database di fatti né una tabella di ricerca del codice, ma solo questi numeri, organizzati in modo che il calcolo tenda a produrre risultati utili. I fatti che il modello riesce a ripetere grazie al training, come l’API di una libreria standard, sono conoscenze parametriche: sono conservati nei parametri, non recuperati da una fonte esterna.

Il dettaglio da tenere a mente è che i parametri vengono congelati dopo il training. Nulla di ciò che fai in una sessione li modifica: nessuna correzione, nessuna codebase che mostri al modello, nessun errore da cui possa imparare. Ogni sessione usa gli stessi numeri. Ecco perché il modello non conserva lo stato, perché le sue conoscenze integrate si fermano alla soglia di conoscenza e perché le informazioni specifiche di un progetto devono arrivare tramite il contesto. I parametri cambiano solo con altro training, che produce, in pratica, un modello diverso.

Uso:

«Possiamo perfezionarlo sulla nostra codebase?»

«Questo aggiornerebbe i parametri: dopo avresti un modello diverso. Per un singolo progetto, di solito costa molto meno caricare la codebase come contesto che ripetere il training.»

Il processo che imposta i parametri di un modello, esponendolo a enormi quantità di testo e modificando i parametri per migliorare la predizione del token successivo. È un processo costoso, eseguito una volta dal provider del modello. Comprende sia il pre-training, cioè la fase principale, sia il post-training, cioè i perfezionamenti successivi per capacità come il rispetto delle istruzioni e la sicurezza; a questo livello del glossario la distinzione non è rilevante.

Il meccanismo consiste nel ripetere un’operazione su vasta scala: si mostra al modello un brano di testo, gli si chiede di prevedere il token successivo, si spostano i parametri verso il token che viene davvero dopo e si ripete il ciclo su migliaia di miliardi di token. Non vengono memorizzati fatti o regole: tutto ciò che il modello «sa» è un effetto collaterale del miglioramento nelle previsioni, compresso nei parametri sotto forma di conoscenze parametriche.

Due conseguenze sono importanti nel lavoro quotidiano. Il training termina in un determinato momento, perciò il modello ha una soglia di conoscenza: non ha visto la versione della libreria a cui hai aggiornato il mese scorso. Inoltre, non puoi eseguire tu il training: se il modello non conosce la tua codebase, le tue convenzioni o le API interne, la soluzione non è «insegnarlo al modello», ma inserire quel materiale nel contesto, l’unico input che puoi controllare.

Uso:

«Possiamo fargli conoscere la nostra API interna?»

«Non tramite il training: è un processo che richiede mesi e viene svolto dal provider del modello. Carica invece la documentazione dell’API nel contesto: è la leva che hai davvero a disposizione.»

Eseguire un modello addestrato per generare un risultato: è ciò che accade a ogni richiesta al provider del modello. I parametri restano invariati; il modello esegue la predizione del token successivo sul contesto che riceve. Costa poco rispetto al training, ma viene fatturato per token ed è il costo principale dell’utilizzo di un modello.

La vita di un modello si divide in due fasi:

Nulla di ciò che fai durante l’inferenza viene scritto di nuovo nei parametri: ecco perché una correzione di oggi non resta valida domani. Se il modello commette lo stesso errore nella sessione successiva dopo che gli hai spiegato con cura la soluzione, non ti ha ignorato: non è in grado di imparare da quello scambio. Il modello non conserva lo stato, quindi la continuità deve provenire dall’esterno: dalla finestra di contesto o da un sistema di memoria.

Questo meccanismo spiega anche la fatturazione. Ogni richiesta esegue il modello sull’intero contesto, perciò il costo dipende dai token di input e dai token di output; un agente che effettua decine di chiamate agli strumenti paga l’inferenza a ogni ciclo di andata e ritorno. Ecco perché la dimensione del contesto incide sia sul costo sia sulla qualità.

Uso:

«Perché la fattura aumenta con l’utilizzo invece di essere una licenza a tariffa fissa?»

«Paghi l’inferenza: a ogni richiesta al provider del modello, il modello viene eseguito sull’hardware del provider. Il training è già avvenuto, ma i costi di inferenza si accumulano per ogni richiesta e un singolo turno può trasformarsi in molte richieste quando vengono chiamati degli strumenti.»

Il livello di ragionamento è una manopola che regola quanto ragionamento un modello svolge prima di rispondere. Si imposta per ogni richiesta al provider del modello e controlla quanto a lungo il modello pensa prima di iniziare a scrivere la risposta che vedi. Come tutto il resto, quel ragionamento viene generato al momento dell’inferenza; spesso l’harness lo nasconde, ma è lavoro effettivo svolto dal modello.

Un livello più alto costa di più e rallenta l’esecuzione. Il ragionamento viene emesso sotto forma di token, conteggiato come token di output anche quando non lo vedi e prodotto un token alla volta: aumentare il livello allunga quindi l’attesa prima della risposta e fa salire il costo. Il compromesso è tra maggiore ponderazione, velocità e costo.

La maggior parte degli harness presenta il livello di ragionamento come una breve scala:

Gli effetti di un’impostazione inadeguata si manifestano in entrambe le direzioni. Se imposti un livello troppo basso per un problema difficile, ottieni una risposta sicura ma superficiale, che ha saltato il ragionamento necessario: sembra corretta, ma sbaglia in un modo che ti costerà in seguito. Se imposti il massimo per rinominare una riga, aspetti a lungo per un ragionamento che non produce nulla che il livello minimo non avrebbe prodotto.

Regola il livello in base al compito, non alla sessione. Alzalo per la parte che richiede davvero ragionamenti complessi e abbassalo per il lavoro meccanico che la circonda.

Uso:

«Continua a sbagliare questa correzione di concorrenza: gliel’ho rispiegata tre volte.»

«Alza il livello di ragionamento. È un bug che richiede analisi e, con l’impostazione predefinita, non sta riflettendo abbastanza prima di scegliere un approccio.»

L’unità atomica letta e scritta da un modello. È più o meno grande come una parola, ma non esattamente: le parole comuni corrispondono a un token, quelle rare o lunghe vengono suddivise in più token. La dimensione della finestra di contesto, il costo e la latenza vengono tutti misurati in token.

Il testo viene convertito in token da un tokenizzatore: un vocabolario fisso di decine di migliaia di frammenti, appreso prima del training, che suddivide qualsiasi input in una sequenza di voci del vocabolario. Il modello non vede mai caratteri o parole: ogni testo viene convertito in token in ingresso e la predizione del token successivo genera l’output un token alla volta.

Come regola approssimativa, un token equivale a circa tre quarti di una parola inglese, quindi mille token corrispondono a circa 750 parole. Il codice è meno prevedibile: le parole chiave e le espressioni comuni si tokenizzano in modo compatto, mentre identificatori generati, hash, dati codificati in base64 e output minificato vengono suddivisi in molti token per «parola». Il criterio è questo: il testo che compare spesso nei materiali usati per il tokenizzatore riceve codifiche brevi ed efficienti; quello che non compare viene scomposto in tanti piccoli frammenti. Un hash come `a3f9c2e1` non è mai apparso da nessuna parte, quindi viene suddiviso in molti token, mentre `function` è un solo token. Ecco perché un file apparentemente piccolo, ma pieno di stringhe insolite, può occupare una parte sorprendente della finestra di contesto.

Tutto il resto viene misurato in token. Il costo è per token: i provider fatturano separatamente i token di input e quelli di output. La velocità si misura in token al secondo, dato che l’output viene generato un token alla volta. La finestra di contesto contiene un numero fisso di token, quindi è il conteggio dei token nei tuoi file a determinare quanto ci sta.

Evitare: «parola»: i confini dei token non coincidono con quelli delle parole, e le unità che contano davvero sono token al secondo e token per dollaro.

Uso:

«Quanto sarà grande questo prompt?»

«Passalo nel tokenizzatore: lo schema è compatto, ma le chiavi JSON sono insolite, quindi verranno suddivise in più token di quanto pensi.»

Ciò che il modello fa davvero. Dato un contesto, estrae a campione un token successivo, lo aggiunge al testo e ricomincia. Ogni output — una frase, una chiamata a uno strumento, un file di mille righe — viene costruito un token alla volta. Il modello non opera in nessun altro modo.

Ogni passaggio funziona allo stesso modo: i token nella finestra di contesto vengono elaborati attraverso i parametri, che assegnano una probabilità a ogni token del vocabolario: questo token è molto probabile come successivo, quello un po’ meno. Si estrae un token da queste probabilità, lo si aggiunge e il ciclo ricomincia con un contesto leggermente più lungo. Questa estrazione spiega perché lo stesso prompt produca risultati diversi a ogni esecuzione: il non determinismo è incorporato nel meccanismo, non è un bug aggiunto in seguito.

Tenere presente questo meccanismo spiega comportamenti che altrimenti sembrerebbero strani. Prima di emettere un token, il modello non verifica se sia vero, ma solo se sia probabile: è la causa fondamentale delle allucinazioni. Si impegna a produrre un token alla volta, quindi una frase iniziale che sembra sicura può indirizzare male il resto della risposta. Inoltre, poiché i token di output vengono prodotti strettamente uno alla volta, la velocità di generazione pone un limite minimo alla rapidità con cui può lavorare qualsiasi agente.

Uso:

«Come fa l’agente a “decidere” di chiamare uno strumento?»

«Non decide: è sempre e solo predizione del token successivo. La chiamata allo strumento è una stringa strutturata che l’harness estrae dal flusso di output.»

Lo stesso input può produrre output diversi. Esegui due volte un modello con contesto identico e potresti ottenere due risposte diverse: a volte cambia una parola, a volte l’approccio è completamente diverso. Non è necessario modificare nulla nel codice perché accada.

Dipende da come i modelli generano testo e da come i provider di modelli servono le richieste. Durante l’inferenza, il modello produce una distribuzione di probabilità sui possibili token successivi e ne estrae uno a campione. Di solito si introduce deliberatamente una certa casualità, perché scegliere sempre il token più probabile produrrebbe un testo ripetitivo e di qualità inferiore. Un token diverso, scelto all’inizio della risposta, cambia tutti quelli successivi: così una sola parola diversa può portare a un approccio completamente differente. Il servizio sul lato del provider aggiunge altra variazione: le richieste vengono raggruppate ed eseguite sullo stesso hardware, e minuscole differenze in virgola mobile tra gruppi possono far prevalere uno o l’altro token quando la scelta è incerta. Non esiste un’impostazione che possa eliminare tutto questo.

Aspettati una varietà di risultati dall’agente anche sullo stesso compito. La maggior parte delle risposte rientra in una fascia di qualità ragionevole — per questo il non determinismo è tollerabile — ma i casi estremi esistono: alcuni giorni il modello sembra lucido, altri sembra aver perso il filo. Stesso compito, esiti diversi. Ne derivano due conseguenze pratiche. Riprovare è una strategia legittima: un tentativo fallito è solo un’estrazione dalla distribuzione, e un nuovo tentativo sullo stesso compito può riuscire meglio. Inoltre, la verifica è più importante che con strumenti deterministici: non puoi testare una volta il comportamento di un agente e confidare che si ripeta, quindi i controlli automatizzati devono intercettare gli esiti negativi.

Evita di costruire una storia più ampia del necessario. Le persone cercano schemi e una serie di sessioni negative può sembrare la prova che «questa settimana il modello è peggiorato». Di solito è solo la distribuzione.

Uso:

«Oggi Claude è stato pessimo. Hanno rilasciato una versione peggiore?»

«Probabilmente no: l’output del modello è non deterministico. Lo stesso compito può dare giornate buone e cattive. Riprova domani prima di cercare una causa.»

Chiunque fornisca inferenza a un modello. Di solito è un servizio remoto, come Anthropic, OpenAI o Google, ma può essere anche locale, come Ollama, LM Studio o llama.cpp in esecuzione sulla tua macchina. L’harness non esegue direttamente il modello: si rivolge a un provider.

Il provider possiede l’infrastruttura: i parametri risiedono sul suo hardware e a ogni richiesta al provider del modello l’harness invia token tramite la rete e riceve previsioni in risposta. Il provider è quindi all’origine di una categoria di problemi che vengono attribuiti erroneamente al modello o all’harness: limiti di frequenza, capacità ridotta e interruzioni del servizio. Se l’agente si blocca a metà sessione o genera un errore a ogni turno, prima di tutto conviene controllare la pagina di stato del provider.

Il provider stabilisce anche le condizioni commerciali: i prezzi per token di input e output, gli sconti della cache del prefisso e i modelli disponibili. Il provider e chi ha creato il modello possono essere aziende diverse: Bedrock, Vertex e OpenRouter offrono modelli di altri.

I provider locali scambiano capacità con controllo: i modelli che entrano nel tuo hardware sono molto più piccoli di quelli di frontiera, ma nulla lascia la macchina e non paghi per token.

Uso:

«Possiamo eseguirlo offline per il cliente con la rete isolata?»

«Passa a un provider locale, come Ollama o llama.cpp sulla sua macchina. All’harness non importa: contatta semplicemente un endpoint diverso.»

Tutto ciò che circonda il modello e lo trasforma in un agente: strumenti, prompt di sistema, gestione della finestra di contesto, permessi, hook. Claude.ai e Claude Code usano lo stesso modello, ma si comportano in modo diverso perché i rispettivi harness sono diversi.

Il modello in sé fa una cosa sola: riceve testo e produce testo. Non può leggere file, eseguire comandi o ricordare l’ultimo turno. È l’harness a fornire tutto questo. Prepara il contesto per ogni richiesta al provider del modello, esegue le chiamate agli strumenti richieste dal modello, gli restituisce i risultati degli strumenti, conserva la cronologia della sessione, ti chiede il permesso prima delle azioni rischiose e decide quando compattare il contesto. Il ciclo dell’agente — il modello propone, l’harness esegue, e il ciclo ricomincia — è gestito dall’harness.

Questo è importante per la diagnosi. Quando il comportamento cambia tra due prodotti, o tra ieri e oggi, spesso la variabile non è il modello, ma l’harness. Un prompt di sistema diverso, un insieme diverso di strumenti, un’impostazione predefinita dei permessi modificata o una nuova strategia di gestione del contesto possono cambiare il comportamento senza che cambi il modello. Significa anche che la maggior parte della configurazione risiede nell’harness: i file AGENTS.md, le impostazioni dei permessi e gli hook sono istruzioni rivolte all’harness, non al modello.

Esempi: Claude Code, Cursor, Codex CLI e Claude.ai, che è un harness per chat, non per programmazione.

Uso:

«Stesso modello: perché Claude Code modifica i file mentre Claude.ai si limita a rispondere alle domande?»

«Gli harness sono diversi: Claude Code dispone di strumenti per il filesystem, di un prompt di sistema diverso e di un livello di permessi. Qui la variabile non è il modello.»

Un ciclo di andata e ritorno tra l’harness e il provider del modello. L’harness invia il contesto corrente; il provider restituisce una risposta (una chiamata a uno strumento o una risposta finale). Un singolo messaggio dell’utente può generare molte richieste al provider del modello se l’agente chiama strumenti: ogni risultato dello strumento genera un’altra richiesta.

Ogni richiesta contiene tutto: il prompt di sistema, l’intera conversazione fino a quel momento e ogni risultato degli strumenti. Il modello non conserva lo stato, quindi il provider non conserva nulla tra le richieste: la richiesta numero quaranta reinvia ciò che era stato inviato nella trentanovesima, più un altro risultato di uno strumento. La cache del prefisso serve a rendere sostenibile questa ripetizione.

La richiesta è anche l’unità di fatturazione. I token di input, i token di output e gli sconti sulla cache vengono conteggiati per richiesta; ecco perché una domanda apparentemente innocua può costare sorprendentemente tanto. Il costo non è proporzionale al tuo messaggio, ma al numero di richieste moltiplicato per la quantità di contesto che ciascuna trasporta.

È utile distinguere una richiesta da un turno. Un turno è uno scambio con te; un singolo turno — «correggi il test che fallisce» — si svolge come una catena di richieste:

Sei richieste per un turno: ciascuna reinvia l’intero contesto. Quando ti chiedi dove siano finiti i token, conta le richieste, non i turni.

Uso:

«Una sola domanda ha consumato quarantamila token?»

«Guarda le chiamate agli strumenti: dodici grep, otto letture, quattro modifiche. Ogni risultato degli strumenti genera un’altra richiesta al provider del modello, che ogni volta reinvia il prefisso dell’intera sessione.»

I token che l’harness invia a ogni richiesta al provider del modello: il prompt di sistema, la cronologia della conversazione, i risultati degli strumenti, tutto ciò che il modello legge prima di scrivere. Sono fatturati a una tariffa inferiore rispetto ai token di output, perché elaborarli costa meno che produrre gli output.

Nella programmazione con l’AI, i token di input costituiscono la maggior parte del conto. Il modello non conserva lo stato, quindi a ogni turno viene reinviata come input l’intera sessione: il tuo primo messaggio, ogni risposta e tutti i risultati degli strumenti successivi. L’input del cinquantesimo turno contiene i quarantanove turni precedenti. Una singola richiesta al provider del modello potrebbe generare alcune centinaia di token di output e reinviare centomila token di input della cronologia accumulata.

La cache del prefisso riduce il costo: la cronologia identica a quella di una richiesta precedente viene fatturata come economici token di cache, invece che come input a tariffa piena. Se i costi di input restano alti, riduci ciò che viene reinviato: svuota o compatta il contesto tra un compito e l’altro.

Uso:

«Il conto è alto, ma l’agente scrive pochissimo.»

«Sono i token di input: ogni turno reinvia l’intera sessione. Senza la cache del prefisso, paghi di nuovo la cronologia a ogni richiesta.»

I token generati dal modello. Sono fatturati a una tariffa superiore rispetto ai token di input, in genere circa cinque volte maggiore, perché richiedono più calcolo per essere prodotti.

Viene conteggiato tutto ciò che scrive il modello: il testo che leggi, il codice che genera, le chiamate agli strumenti e qualsiasi ragionamento esteso prima della risposta. Quest’ultimo sorprende molte persone: i token di ragionamento vengono fatturati come output anche quando spesso l’harness non te li mostra, e aumentare il livello di ragionamento ne consuma di più.

I token di output determinano anche il ritmo di una sessione. Il modello legge rapidamente l’input, ma genera l’output un token alla volta; quando un turno sembra lento, quasi sempre la causa è il testo che viene generato, non quello che viene letto. Un’attesa lunga di solito significa che sta arrivando una risposta lunga.

Uso:

«La sessione di refactoring consuma credito anche se gli input sono piccoli.»

«L’agente sta riscrivendo interi file invece di applicare patch. I token di output costano circa cinque volte la tariffa di input: chiedigli di produrre modifiche e il conto scenderà.»

L’archivio del provider che consente a richieste consecutive al provider del modello di evitare di rielaborare un prefisso condiviso. Se l’inizio di una richiesta coincide con quello di una richiesta recente — stesso prompt di sistema, stessa cronologia fino a un certo punto — il provider riutilizza il lavoro precedente e fattura quei token come token di cache, a una tariffa molto più bassa.

La cache conviene perché le sessioni crescono solo in aggiunta. Ogni richiesta reinvia l’intera cronologia come token di input (vedi quella voce per il motivo); in una sessione normale, la cronologia cambia solo alla fine: ogni richiesta contiene la precedente più qualche nuovo messaggio. Il provider elabora una volta il lungo inizio condiviso, ne salva il risultato e riprende da dove finisce il prefisso. Senza la cache, una sessione di 50 turni comporterebbe il pagamento della rielaborazione del primo turno cinquanta volte.

Anche le cache scadono. La durata di una voce resta valida varia secondo il provider del modello, ma in genere si parla di minuti, non di ore. Se lasci inattiva una sessione oltre quel periodo, la richiesta successiva ricostruisce il prefisso al prezzo pieno prima che la cache torni attiva. È un aspetto che riguarda soprattutto chi costruisce l’harness; per l’utente, l’effetto visibile è che le richieste dopo una lunga pausa costano più di quelle precedenti.

Uso:

«Perché la fattura è aumentata a metà sessione?»

«L’harness ha iniziato a inserire l’ora corrente nel prompt di sistema a ogni turno. La cache del prefisso si interrompe al primo token modificato, quindi da quel momento ogni richiesta è stata fatturata alla tariffa piena.»

Token di input già memorizzati nella cache dal provider durante una richiesta al provider del modello precedente, in modo che non debba elaborarli di nuovo. Quando richieste consecutive condividono un prefisso, il provider riutilizza il lavoro tramite la cache del prefisso e fattura la parte memorizzata a una tariffa molto più bassa. È il meccanismo che rende sostenibili le sessioni lunghe: senza, ogni turno farebbe pagare di nuovo l’intera cronologia.

Questo è importante per via del modo in cui vengono fatturate le sessioni. Il modello non conserva lo stato, quindi ogni richiesta reinvia l’intera conversazione come token di input: prompt di sistema, ogni messaggio, ogni risultato degli strumenti. Al cinquantesimo turno, ogni richiesta trasporta cinquanta turni di cronologia e dovresti pagarli ogni volta a tariffa piena. La cache cambia il calcolo: i token di un prefisso identico che il provider ha già elaborato vengono fatturati come token di cache, spesso a un decimo della tariffa di input o meno. In una sessione lunga, la maggior parte dei token inviati viene dalla cache e il conto resta ragionevole.

Ecco quando i token vengono memorizzati in cache e quando no. Ogni lettera rappresenta un blocco di contenuto della conversazione; ogni richiesta invia la conversazione svolta fino a quel momento:

La cache è fragile in un modo specifico: confronta prefissi esatti. Se cambia qualcosa in una parte precedente della conversazione — l’harness riordina il contenuto, cambia un timestamp o cambia la rappresentazione di un file — la cache non trova più una corrispondenza da quel punto in poi e tutto il resto viene fatturato alla tariffa piena dei token di input. Le cache scadono anche dopo alcuni minuti di inattività; quando si riprende una sessione dopo una lunga pausa, si paga di nuovo una volta per la cronologia. Se il costo di una sessione aumenta senza una causa evidente, confronta i token di cache con i token di input nel rapporto di utilizzo: la prima indicazione di una cache interrotta si trova lì.

Uso:

«Le sessioni lunghe costano moltissimo: otto dollari per un refactoring.»

«Controlla i token di cache. Se l’harness riordina il prompt di sistema o i file tra un turno e l’altro, il prefisso si interrompe e paghi di nuovo la tariffa piena di input a ogni richiesta.»

Non trasporta informazioni nel tempo. Il modello non conserva lo stato tra le richieste al provider del modello: ogni richiesta invia di nuovo l’intera finestra di contesto, perché il modello non può vedere nient’altro. Per impostazione predefinita, anche un agente non conserva lo stato tra le sessioni: una nuova sessione inizia vuota, senza traccia di quelle precedenti. È il contrario di stateful.

Il modello stesso è permanentemente privo di stato: i suoi parametri vengono congelati dopo il training e nulla di ciò che fai durante l’inferenza li modifica. Il modello non impara dalle tue correzioni, non ricorda che ieri gli hai detto la stessa cosa e non impara a conoscerti, per quanto la conversazione possa dare questa impressione. La sensazione di continuità all’interno di una sessione è prodotta dall’harness, che conserva la trascrizione e la reinvia a ogni richiesta. Il modello non ricorda la conversazione: la rilegge.

Concretamente, se vuoi che qualcosa venga ricordato tra le sessioni, devi scriverlo in un posto che l’agente rileggerà. A questo servono i file AGENTS.md, i sistemi di memoria e gli artefatti di handoff: sono file caricati nel contesto delle sessioni future e suppliscono alla memoria che il modello non possiede. Se l’agente continua a ripetere un errore che gli hai già corretto, la domanda non è perché non abbia imparato — non può farlo — ma dove annotare la correzione affinché venga letta in ogni sessione futura.

Uso:

«Perché dimentica la convenzione ogni volta che svuoto il contesto?»

«Il modello non conserva lo stato: la nuova sessione parte vuota. Se vuoi che l’informazione venga mantenuta, scrivila in AGENTS.md o in un file di memoria caricato dall’harness all’avvio della sessione.»

Le informazioni pertinenti a cui l’agente ha accesso in questo momento. È il sostantivo astratto: non l’input grezzo che vede il modello, cioè la finestra di contesto, né la cronologia in corso, cioè la sessione, ma ciò che l’agente sa e che è pertinente al compito. «Caricare qualcosa nel contesto» significa aggiungerlo a questo insieme; l’«ingegneria del contesto» è la disciplina che lo seleziona.

I tre termini si distinguono nettamente:

La distinzione conta perché il contesto misura la qualità, non la quantità. Una finestra di contesto può essere quasi piena e contenere comunque un contesto scadente: migliaia di token di risultati degli strumenti obsoleti, nessuno pertinente al compito attuale. Può anche essere quasi vuota e offrire un contesto eccellente: l’unica definizione di tipo da cui dipende il compito.

La maggior parte dei problemi quotidiani riconduce al contesto. Quando l’agente inventa un’API, contraddice una decisione o tira a indovinare uno schema, la prima domanda è che cosa fosse nel contesto: di solito il fatto pertinente non era stato caricato o era sepolto sotto il degrado dell’attenzione. La soluzione è selezionare con cura: carica ciò che serve al compito e tieni fuori ciò che non serve.

Uso:

«Continua a inventarsi campi che non esistono nei tipi.»

«Il file dei tipi non è nel contesto: sta leggendo i punti in cui viene chiamato il codice e indovina. Carica prima la definizione.»

Tutto ciò che il modello vede a ogni richiesta al provider del modello. È finito, varia da modello a modello ed è l’unica superficie attraverso cui il modello percepisce qualcosa.

È un’unica sequenza di token: il prompt di sistema, la conversazione fino a quel momento e ogni risultato degli strumenti reinserito dall’harness. Se qualcosa fa parte di quella sequenza, il modello può usarlo; altrimenti non sa che esista: né la tua codebase, né il file che hai modificato ieri, né l’istruzione data tre sessioni fa. Tutto ciò che è fuori dalla finestra deve essere introdotto, di solito tramite una chiamata a uno strumento, prima di poter avere effetto.

La finestra è finita, quindi si riempie. Ogni turno aggiunge altro: i tuoi messaggi, le risposte del modello, i risultati degli strumenti; prima o poi una sessione lunga raggiunge il limite e impone una compattazione o uno svuotamento. Inoltre, tutto ciò che si trova nella finestra è in competizione: ogni token caricato ne lascia uno in meno a disposizione degli altri e il contenuto superfluo continua a occupare il budget di attenzione del modello. Conviene trattare la finestra come un budget: carica ciò che serve al compito e lascia fuori il resto.

Evitare: «memoria»: la finestra di contesto è uno stato di lavoro e non persiste tra le sessioni. La memoria è un concetto distinto, costruito sopra di essa.

Uso:

«Posso semplicemente incollare l’intero monorepo nel prompt?»

«La finestra di contesto contiene 200.000 token: forse un quinto del repository. Scegli i file interessati dal compito e lascia il resto dietro una chiamata a uno strumento.»

Trasporta informazioni nel tempo. Una sessione conserva lo stato tra i turni: il contesto si accumula durante la sessione, ed è per questo che le sessioni lunghe scivolano nella zona stupida. È possibile rendere un agente persistente tra più sessioni aggiungendo un sistema di memoria che salva informazioni nell’ambiente e le ricarica all’inizio delle sessioni successive. Il modello non conserva mai lo stato; ogni apparente continuità deriva dal fatto che l’harness gli reinvia il contesto. È il contrario di stateless.

Dove risiede lo stato a ciascun livello:

Lo stato di ogni livello si costruisce rileggendo qualcosa salvato nel livello sottostante: la sessione sembra continua perché l’harness invia di nuovo la cronologia dei messaggi al modello senza stato; l’agente mantiene la memoria tra le sessioni perché l’harness ricarica i file dall’ambiente. Nessuno stato viene mai salvato nel modello stesso.

Non sempre si desidera mantenere lo stato. Tutto ciò che viene trasportato nel tempo influenza ciò che accade dopo, quindi anche un’ipotesi sbagliata fatta all’inizio della sessione viene mantenuta. Svuotare è l’atto intenzionale di eliminare lo stato della sessione e ripartire da ciò che è stato messo per iscritto.

Uso:

«Ricordava le mie preferenze di ieri: vuol dire che il modello le ha imparate?»

«No, l’agente conserva lo stato perché l’harness ha scritto le preferenze in un file di memoria e l’ha ricaricato all’inizio della sessione. Il modello non ha visto nulla di ieri.»

Un model inserito in un harness con strumenti, un prompt di sistema e una finestra di contesto, che interagisce a turni con un utente. Claude Code è un agent. Cursor è un agent. Claude.ai è un agent. Un agent è ciò con cui parli davvero: è il model in azione, configurato per uno scopo.

A differenza della maggior parte dei termini di questo dizionario, «agent» non indica un componente meccanico. Il model è un insieme di parametri; l’harness è un software che puoi configurare. L’agent non è né l’uno né l’altro: è l’unità con cui parli. Le persone antropomorfizzano continuamente l’IA, e l’agent è l’unità antropomorfizzata: a cui deleghi, che legge il tuo messaggio e risponde, il «lui» di «ha rotto di nuovo la build». Quando dici che l’agent ha fatto qualcosa, intendi che l’hanno fatto insieme model e harness, ma ti rivolgi alla combinazione come a un unico attore.

L’idea è più antica di questa ondata di IA. Gli agenti software, cioè programmi a cui deleghi un obiettivo e che agiscono per tuo conto, esistono come concetto da quando esiste l’intelligenza artificiale.

Evitare: «l’IA», «il bot» (troppo vaghi: nascondono se si intende il model o l’elemento dotato di harness).

Uso:

«Quale agent usi per la migrazione?»

«Claude Code in locale, Cursor per il lavoro sull’interfaccia: sotto c’è lo stesso model, ma gli harness sono diversi.»

Le istruzioni che l’harness antepone a ogni richiesta al provider del modello: il briefing permanente dell’agente, che indica chi è, come deve comportarsi, quali strumenti può chiamare e quali convenzioni deve seguire. Di solito rimane stabile per tutta la sessione.

Il prompt di sistema viene scritto dal fornitore dell’harness, non da te; negli harness per la programmazione è lungo, spesso contiene decine di migliaia di token tra regole di comportamento, descrizioni degli strumenti e gestione dei casi limite, e viene fatturato come token di input a ogni turno. Anche le tue istruzioni permanenti lo accompagnano: file come AGENTS.md vengono caricati accanto al prompt di sistema all’inizio della sessione, così il modello legge insieme il briefing del fornitore e il tuo prima ancora di vedere il tuo messaggio.

Poiché è identico a ogni richiesta, costituisce l’inizio della cache del prefisso: ecco in parte perché gli harness lo mantengono invariato per tutta la sessione invece di modificarlo strada facendo.

I modelli sono addestrati a dare priorità al prompt di sistema rispetto ai messaggi dell’utente. Quindi, quando un agente insiste su una convenzione che non hai mai richiesto o formatta l’output in un modo da cui non riesci a distoglierlo, di solito sta seguendo il prompt di sistema e il tuo messaggio perde il confronto. Alcuni harness sono personalizzabili e ti danno accesso completo al prompt di sistema: puoi leggere le istruzioni effettive ricevute dall’agente e modificarle.

Uso:

«Due harness, stesso modello, comportamento completamente diverso con lo stesso prompt.»

«I prompt di sistema sono diversi. Uno è configurato per modifiche al codice concise, l’altro per spiegare: la divergenza nasce lì, prima ancora che arrivi il tuo messaggio.»

Un’interazione delimitata con un agente. Inizia vuota, accumula messaggi, risultati degli strumenti e file letti, e termina quando viene svuotata, chiusa o compattata in una sessione nuova. È la sessione a riempire la finestra di contesto: se la finestra è una scatola, la sessione è ciò che la riempie lentamente. Un lavoro troppo grande per una sola finestra di contesto va suddiviso in più sessioni.

La cronologia dei messaggi della sessione è la memoria di lavoro dell’agente. Il modello non conserva lo stato, quindi tutto ciò che sembra ricordare — ciò che gli hai chiesto, cosa hanno indicato i test, cosa ha deciso tre turni fa — si trova nella cronologia dei messaggi, reinviata a ogni richiesta al provider del modello. Ciò che non è nella sessione non esiste per l’agente.

Quella memoria finisce con la sessione. Una nuova sessione riparte da zero: l’agente che alla fine della sessione di ieri conosceva bene la tua codebase stamattina non ne sa nulla. Ciò che sopravvive è il filesystem: i file scritti durante una sessione possono essere letti da quella successiva, ed è su questo che si basano gli handoff, i sistemi di memoria e AGENTS.md.

Sei tu a scegliere quando termina una sessione. Tutto ciò che vi accade influenza ogni turno successivo, quindi i compiti non pertinenti svolti nella stessa sessione lasciano residui che condizionano la risposta seguente. Una sessione per ciascun compito mantiene pertinente il contesto; concludere un compito è un momento naturale per svuotarlo.

Uso:

«Quanto può durare una sessione prima di iniziare a cedere?»

«Dipende dal lavoro: un refactoring mirato resta lucido più a lungo di una ricerca senza confini. Quando la sessione si gonfia, fai un handoff o compatta; non forzare oltre.»

Un messaggio dell’utente insieme a tutto ciò che l’agente fa in risposta, fino a quando restituisce il controllo all’utente. Contiene una o più richieste al provider del modello: molte, se l’agente chiama strumenti. Una domanda di chiarimento conclude il turno; la tua risposta apre quello successivo. La gerarchia è sessione > Turno > Richiesta al provider del modello.

Il turno merita di avere un nome perché la sua durata dipende dalle decisioni dell’agente, non dalle tue. Tu invii un messaggio; l’agente decide quante chiamate agli strumenti concatenare prima di restituire il controllo. Un turno può essere una risposta di una frase oppure venti minuti di lettura, modifica ed esecuzione dei test. È la stessa proprietà osservata da due prospettive: i turni lunghi rendono possibili le sessioni AFK, ma sono anche quelli in cui le cose possono andare male senza supervisione. Quando l’agente restituisce il controllo, potrebbe essersi allontanato molto da ciò che intendevi.

Il turno è anche l’unità naturale per dirigere il lavoro. Tutto ciò che avviene al suo interno procede senza di te; gli intervalli tra i turni sono i momenti in cui puoi reindirizzare l’agente. La maggior parte degli harness attenua questa separazione: puoi interrompere il turno per fermare e reindirizzare l’agente o scrivere un messaggio mentre lavora, che verrà letto quando il turno sarà terminato. Se il risultato dei turni ti delude ripetutamente, di solito conviene chiederne di più brevi — prima un piano, poi un passaggio alla volta — scambiando autonomia con occasioni più frequenti per intervenire.

Uso:

«Un turno è durato due minuti?»

«Ha effettuato quattordici chiamate agli strumenti durante quel turno: ognuna è una richiesta separata al provider del modello. La latenza si accumula prima che l’agente restituisca il controllo.»

Il mondo in cui l’agente opera: tutto ciò che è fuori dall’harness e che l’agente percepisce tramite i risultati degli strumenti e modifica tramite le chiamate agli strumenti. L’harness esegue l’agente; l’ambiente è ciò in cui l’agente lavora. Un file come `AGENTS.md` risiede nell’ambiente; è l’harness a caricarlo nella finestra di contesto. Il filesystem è l’ambiente più comune, ma non l’unico: possono esserlo anche un database, un’API remota o una sessione del browser.

L’agente vede l’ambiente soltanto quando lo esamina. Tutto ciò che ne sa è arrivato attraverso un risultato di uno strumento, quindi la sua rappresentazione è una raccolta di istantanee, ciascuna corretta nel momento in cui è stata acquisita. Se un file cambia dopo che l’agente l’ha letto — lo modifichi a mano o venga rigenerato da una fase di build — l’agente continua a ragionare sulla copia obsoleta finché qualcosa non lo induce a leggerlo di nuovo. Quando descrive con sicurezza un file che non è più così, di solito è successo questo: l’ambiente è cambiato, l’istantanea no.

L’ambiente è anche il livello che persiste: l’unico che conserva sempre lo stato. Il contesto di una sessione scompare quando termina la sessione, ma i file scritti nell’ambiente restano disponibili alla sessione successiva: è su questo che fanno affidamento i sistemi di memoria, gli artefatti di handoff e `AGENTS.md`. Qualsiasi cosa l’agente debba ricordare domani deve finire nell’ambiente.

Sei tu a decidere quanto sia grande l’ambiente. Una sandbox lo restringe e limita ciò che l’agente può raggiungere; aggiungere uno strumento lo estende e permette di accedere a un database o a un’API. Ciò che rientra nel confine può essere percepito e modificato dall’agente; tutto ciò che ne resta fuori per lui non esiste. Quanto l’ambiente sia predisposto per supportare il lavoro dell’agente è una misura dell’AX della codebase.

Evitare: usare «ambiente» per indicare il runtime o l’harness stesso: l’harness è il livello di controllo, l’ambiente è lo spazio di lavoro.

Uso:

«L’agente non può vedere lo schema del database di staging.»

«Collegalo all’ambiente: dagli uno strumento `psql` con accesso in sola lettura allo staging. L’harness va bene; è solo che non ha nulla su cui agire.»

Una gerarchia di file e directory in cui l’agente legge, scrive ed esegue operazioni: è il tipo predefinito di ambiente per un agente di programmazione. AGENTS.md, le skill, il codice sorgente, gli script di build e le configurazioni degli strumenti risiedono tutti in un filesystem. Quando un harness «si avvia nel tuo progetto», sta indirizzando l’agente verso un filesystem.

L’agente interagisce con esso solo tramite chiamate agli strumenti: leggere un file, scriverne uno, eseguire un comando shell. Nulla su disco entra nella finestra di contesto finché una chiamata a uno strumento non lo carica; è questo che consente all’agente di lavorare in un repository molto più grande della finestra, perché il filesystem contiene tutto mentre il contesto contiene solo ciò che il compito ha richiesto di leggere. Alcuni harness caricano per impostazione predefinita nella finestra di contesto i nomi dei file nella directory corrente — non i contenuti, solo la struttura — che fungono da puntatori al contesto: l’agente vede cosa esiste e legge i file necessari.

Il filesystem è condiviso anche con te. I file modificati dall’agente sono gli stessi che apri nell’editor e visualizzi con git diff: è lo spazio di lavoro comune in cui puoi esaminare il suo operato.

Uso:

«Perché non rileva il mio AGENTS.md?»

«Sta lavorando su un filesystem diverso: la sandbox ha montato la directory genitore, non la radice del progetto. Indirizza di nuovo l’harness.»

Una funzione che l’harness mette a disposizione dell’agent — Read, Write, Bash, Search. Gli strumenti sono il modo in cui un agent percepisce e agisce sull’ambiente: non può vedere l’ambiente se non attraverso i risultati degli strumenti, né modificarlo se non attraverso le chiamate agli strumenti. Ogni chiamata a uno strumento costa un’ulteriore richiesta al provider del model, perché il risultato deve tornare al model prima che possa decidere il da farsi.

Gli strumenti inclusi nella maggior parte degli agent di programmazione:

Uno strumento è definito da tre elementi: un nome, una descrizione della sua funzione e uno schema dei parametri. L’harness invia queste definizioni al model a ogni richiesta, e il model sceglie uno strumento come produce qualsiasi altra cosa: scrivendo token, in questo caso una chiamata strutturata con argomenti. Il model non esegue mai nulla direttamente: l’harness legge la chiamata, esegue la funzione e restituisce il risultato.

L’elenco degli strumenti determina ciò che l’agent può fare. Un model capace con pochi strumenti è un agent limitato: farà passare tutto da ciò che ha a disposizione, ecco perché gli agent si affidano così tanto a Bash — una shell è uno strumento che raggiunge gran parte del sistema. Per dare una capacità in modo pulito a un agent, aggiungi uno strumento apposito; MCP è lo standard per integrare strumenti esterni all’harness.

Le definizioni degli strumenti occupano spazio nel contesto a ogni richiesta, quindi un elenco ampio ha un costo permanente anche prima di chiamare uno strumento; inoltre, molti strumenti descritti in modo simile rendono più difficile al model scegliere quello giusto.

Uso:

«L’agent può interrogare direttamente lo staging?»

«Aggiungi all’harness uno strumento `psql` con accesso in sola lettura allo staging. Senza uno strumento dedicato, l’agent non può vedere nulla al di fuori del filesystem.»

L’output del modello che nomina uno strumento e i relativi argomenti: è solo testo strutturato. Da solo non esegue alcuna azione; l’harness deve leggerlo ed eseguirlo. Il modello lo produce in una richiesta al provider del modello.

Il ciclo di vita di una chiamata a uno strumento:

Un singolo turno di lavoro dell’agente consiste di solito in molti cicli di andata e ritorno concatenati.

Come qualsiasi altro risultato, la chiamata viene generata tramite la predizione del token successivo e può quindi essere sbagliata: un percorso inesistente, un’opzione non supportata dal comando o argomenti plausibili ma non corretti. L’harness esegue ciò che è stato scritto, non ciò che si intendeva fare: un percorso digitato male non genera necessariamente un errore innocuo, può modificare il file sbagliato.

Uso:

«Ha detto di aver eseguito i test, ma i timestamp dei file non sono cambiati.»

«Guarda la trascrizione: ha davvero emesso una chiamata a uno strumento oppure ha solo descritto l’esecuzione dei test? Il modello produce la chiamata, ma se l’harness non l’ha eseguita non è successo nulla.»

Ciò che l’harness restituisce dopo aver eseguito una chiamata a uno strumento: il contenuto del file, l’output del comando o l’errore. È l’unico modo in cui l’agente può osservare l’ambiente. Nel turno successivo, viene inviato al modello con la richiesta al provider del modello, e il modello decide che cosa fare. La chiamata allo strumento e il risultato sono i due estremi dello stesso scambio, entrambi all’interno di un turno.

Il ciclo di vita del risultato di uno strumento:

Il risultato rimane nel contesto per il resto della sessione. Di solito i risultati degli strumenti costituiscono la maggior parte del contesto di una sessione di programmazione: ogni file letto, ogni esecuzione di test e ogni ricerca viene inserita per intero e continua a occupare token anche molto tempo dopo aver perso utilità. Bastano pochi risultati voluminosi — un log di test prolisso o un file generato letto per intero — per portare una sessione al limite della finestra di contesto più rapidamente della conversazione stessa.

Poiché il risultato è tutto ciò che il modello vede, il modello non può verificare l’ambiente alle sue spalle. Se l’output è stato troncato, il comando è fallito senza segnalarlo o l’harness ha restituito un errore invece del contenuto, il modello ragiona su ciò che gli è stato fornito. Se la rappresentazione del sistema da parte dell’agente sembra sbagliata, controlla i risultati degli strumenti: nella trascrizione ci sarà un risultato che dice qualcosa di diverso da ciò che sai essere vero.

Uso:

«Ragiona sul file come se fosse vuoto.»

«Il risultato dello strumento era un diniego di autorizzazione, non il contenuto. Il modello ha visto solo il testo dell’errore: non ha altro modo per vedere il file.»

Model Context Protocol. Un protocollo per collegare server di strumenti esterni a un harness: definisce come un agent ottiene tools oltre a quelli inclusi nell’harness. L’agent non «chiama MCP»: chiama uno strumento, che l’harness ha ricevuto da un server MCP. Il protocollo espone anche risorse (dati di sola lettura) e prompt (modelli riutilizzabili), ma il suo uso principale è fornire strumenti.

Il protocollo risolve un problema di integrazione. Senza uno standard, ogni harness dovrebbe avere una propria integrazione con Linear, una propria integrazione con Slack, una propria integrazione con il database: ciascuna scritta e mantenuta separatamente. Con MCP, l’integrazione si scrive una sola volta come server e qualsiasi harness compatibile con MCP può usarla. L’harness si collega al server, che dichiara gli strumenti disponibili; questi diventano accessibili all’agent insieme a quelli integrati.

Il costo si paga in context. Ogni strumento dichiarato da un server arriva come definizione: nome, descrizione e schema dei parametri; il model può chiamare soltanto gli strumenti che conosce. L’approccio ingenuo carica in anticipo tutte le definizioni nella context window: installa qualche server generoso e una session inizia con migliaia di tokens di schemi degli strumenti prima ancora che tu abbia scritto qualcosa, consumando il attention budget con strumenti che il compito non userà mai.

Molti harness oggi attenuano questo costo con la ricerca degli strumenti: invece delle definizioni complete, il contesto contiene un context pointer agli strumenti disponibili; l’agent cerca uno strumento per nome o funzione e ne carica la definizione solo quando serve. Se il tuo harness non lo fa, il costo iniziale resta e conviene abilitare soltanto i server davvero necessari al progetto.

Uso:

«L’agent deve leggere i ticket da Linear.»

«Configura l’harness per usare il server MCP di Linear: espone l’API di Linear come strumenti che l’agent può chiamare. Così non devi scrivere wrapper personalizzati per gli strumenti.»

Ciò che l’harness mostra all’utente prima di eseguire una chiamata a uno strumento non preautorizzata. Il modello produce la chiamata, ma invece di eseguirla subito l’harness si ferma e chiede il permesso. Se approvi, la esegue; se neghi, restituisce il diniego al modello come risultato dello strumento. È il meccanismo con cui un harness mette una persona nel ciclo per le azioni rischiose o sensibili.

Il ciclo di vita di una richiesta di autorizzazione:

Negare una richiesta permette di dirigere l’agente. Il modello legge il diniego come qualsiasi altro risultato di uno strumento e vi reagisce: prova un approccio diverso oppure chiede cosa preferisci. La maggior parte degli harness permette di allegare un messaggio al diniego; la richiesta diventa così un’occasione per orientare il lavoro: «non così, usa invece lo script di migrazione» viene ricevuto proprio mentre il modello decide che cosa fare dopo.

Il costo è che ogni richiesta ti costringe ad aspettare una risposta. L’agente resta bloccato finché non rispondi: va bene quando lo stai osservando, ma è un problema quando non ci sei. Un agente che genera richieste di continuo non può essere lasciato lavorare AFK. La modalità dei permessi è la manopola: decide quali chiamate possono procedere liberamente e quali devono chiedere prima, idealmente con una sandbox che rende sicuro ampliare l’insieme delle chiamate libere.

Uso:

«È rimasto bloccato su una richiesta di autorizzazione per dieci minuti: ero in riunione.»

«Questo è il costo di avere una persona nel ciclo. Preautorizza gli strumenti sicuri, così la richiesta scatta solo per le chiamate davvero rischiose.»

La parte della modalità dell’agente che regola i permessi: stabilisce quali chiamate agli strumenti generano una richiesta di autorizzazione e quali vengono eseguite automaticamente. Questo era lo scopo originario dei sistemi di modalità, prima che gli harness iniziassero ad aggiungere istruzioni sul comportamento.

Gli harness offrono una scala di modalità di questo tipo:

Scegliere un livello comporta un compromesso tra sicurezza e interruzioni, e i problemi si avvertono in entrambe le direzioni. Se la modalità è troppo restrittiva, diventi tu il collo di bottiglia: l’agente si ferma ogni pochi secondi per letture innocue, approvi in automatico e le autorizzazioni smettono di avere significato. Approvare acriticamente è il peggio dei due mondi: tutte le interruzioni e nessuna protezione. Se invece la modalità è troppo permissiva, l’agente modifica file ed esegue comandi che avresti voluto esaminare prima.

La permissività è più difendibile all’interno di una sandbox, che contiene il raggio d’impatto di una chiamata a uno strumento sbagliata. Fuori da una sandbox, molte persone scelgono l’approvazione automatica per le letture e mantengono una persona nel ciclo per tutto ciò che è irreversibile.

Uso:

«Si fermava a ogni grep: ha completamente rovinato la sessione AFK.»

«Allenta la modalità dei permessi per gli strumenti di sola lettura, ma continua a chiedere per le scritture e la shell. In una sessione di ricerca, la maggior parte delle richieste di autorizzazione è solo rumore.»

Una preimpostazione che definisce come opera l’agent durante l’esecuzione: combina una modalità di autorizzazione con istruzioni comportamentali inserite nel prompt di sistema. Esempi: un’impostazione predefinita che chiede conferma per le chiamate rischiose; una modalità di pianificazione che blocca le modifiche e indirizza l’agent verso la ricerca; una modalità accept-edits che approva automaticamente le modifiche; una modalità bypass permissions (detta colloquialmente modalità YOLO) che approva tutto in automatico. Si può cambiare anche a sessione in corso.

È proprio la combinazione a distinguere una modalità da una semplice impostazione di autorizzazione. Una modalità di autorizzazione è solo un gate: decide quali tool call possono passare. Da sola, genera un agent che vorrebbe modificare ma non può: propone la scrittura, viene bloccato e prova un’altra strada. Le istruzioni inserite eliminano il desiderio: la modalità di pianificazione non si limita a bloccare le modifiche, dice all’agent che si trova in una fase di pianificazione, quindi legge, fa domande e propone invece di forzare il gate. Gate e orientamento puntano nella stessa direzione.

In pratica, cambi modalità quando cambia la tua fiducia durante il compito. Lo stesso compito può attraversare varie modalità: modalità di pianificazione mentre definisci l’approccio, impostazione predefinita con richieste di conferma per le prime modifiche delicate, accept-edits dopo che l’agent ha dimostrato di aver capito il cambiamento, bypass per un’esecuzione AFK dentro un sandbox. Cambiare modalità non costa nulla: la conversazione continua esattamente dal punto in cui si trova, con nuove autorizzazioni e nuove istruzioni. Se approvi ogni richiesta senza leggerla, la modalità è più restrittiva della fiducia che hai davvero; se continui a rifiutare modifiche, è troppo permissiva.

Termini dei fornitori: Claude Code le chiama «permission modes», Codex le chiama «approval modes»: entrambi i termini sono anteriori alla combinazione con istruzioni comportamentali.

Uso:

«Continua a modificare file mentre io voglio soltanto un piano.»

«Passa alla modalità di pianificazione: bloccherà le scritture e resterà nella fase di ricerca.»

«E per la successiva esecuzione AFK?»

«Modalità bypass, ma solo dentro il sandbox.»

Un ambiente isolato in cui opera l’agente: un container, una VM, un filesystem effimero o una shell con permessi limitati. Riduce il raggio d’impatto delle azioni dell’agente: anche se esegue comandi distruttivi o scarica qualcosa di malevolo, il danno resta contenuto. È la base di sicurezza che rende pratico l’uso AFK.

La sandbox e la modalità dei permessi risolvono lo stesso problema da estremi opposti. I permessi chiedono conferma prima di eseguire un’azione; una sandbox limita ciò che l’azione può raggiungere se viene eseguita. I permessi richiedono che tu resti nel ciclo: ogni richiesta interrompe il lavoro e una sessione che chiede continuamente è a malapena autonoma. Una sandbox consuma infrastruttura invece di attenzione: più forte è l’isolamento, meno domande occorre fare.

L’isolamento ha diversi livelli:

Nessuna sandbox contiene le azioni che ne escono legittimamente. Un agente con le tue credenziali git può fare push; uno con accesso alla rete può chiamare API di produzione. Decidi cosa può attraversare il confine prima di stabilire quanto debba essere spesso.

Uso:

«Vorrei lasciarlo lavorare senza permessi durante la notte, ma non sono ancora pronto.»

«Mettilo in una sandbox: container nuovo, nessuna credenziale montata e niente traffico in uscita. Nel caso peggiore cancella il proprio filesystem e poi elimini il container.»

Una risposta del modello compiacente e sicura di sé. È causata dal training: il modello è stato plasmato per favorire le risposte che piacciono alle persone, e alle persone piace più sentirsi dare ragione che sentirsi dire che hanno torto. Il modello ha quindi imparato che essere d’accordo viene premiato, anche quando l’accordo è scorretto.

Si manifesta così:

• Cede alle obiezioni — ritratta una risposta corretta quando chiedi «ne sei sicuro?».
• Loda un input scadente — approva il tuo piano difettoso come brillante prima ancora di analizzarlo.
• Inquadramento distorto — la revisione è positiva quando segnali di aver scritto tu il testo, negativa quando dici che l’ha scritto qualcun altro. Stesso artefatto, giudizio diverso.
• Imitazione — ti ripete gli errori come se fossero conferme.

Test diagnostico: il modello avrebbe risposto così anche senza il tuo suggerimento? Se è cambiato solo il tono o l’inquadramento, si tratta di compiacenza, non di un vero cambiamento nell’analisi.

Rimedio: nascondi le tue preferenze. Formula prompt neutrali: «esamina questo codice», non «questo codice è valido?».

Evitare: usare «compiacenza» per qualsiasi risposta sbagliata che ti faccia piacere. Senza il test diagnostico, il termine non vale più di «sbagliato».

Uso:

«Ha detto che il mio piano di refactoring era ottimo; poi ho chiesto “ne sei sicuro?” e ha ritrattato tutto.»

«Classica compiacenza: prima ti ha dato ragione perché sembravi sicuro, poi ha ceduto perché sembravi dubbioso. La qualità del piano non è cambiata, è cambiato il tuo tono. Svuota il contesto e chiedi di nuovo senza suggerire una risposta.»

Una risposta del modello sbagliata, ma espressa con sicurezza. Esistono due forme, con cause e rimedi diversi:

La predizione del token successivo produce un testo fluido indipendentemente dalla realtà del fatto sottostante: il modello non ha un segnale interno che gli indichi di non sapere qualcosa, quindi un metodo inventato viene presentato con la stessa sicurezza di uno corretto. Il codice allucinato è plausibile per costruzione: è l’aspetto che avrebbe l’API se esistesse, ed è proprio questo a fargli superare una revisione superficiale e fallire solo quando viene eseguito.

Devi capire quale forma stai osservando, perché il rimedio per una peggiora l’altra. Un problema di accuratezza indica conoscenze mancanti: la soluzione è aggiungere contesto — documentazione, definizioni dei tipi, file. Un problema di fedeltà indica che le conoscenze sono presenti ma perdono la competizione per l’attenzione: la soluzione è rimuovere contesto. Se scambi la mancanza di fedeltà per un problema di accuratezza, incolli altra documentazione, allarghi il contesto e peggiori la deriva. Quando l’agente sbaglia, verifica se l’informazione corretta era già nel contesto prima di decidere quale problema hai davanti.

Evitare: usare «allucinazione» come sinonimo generico di «sbagliato»: senza indicare il tipo, il termine non ha valore diagnostico.

Uso:

«Ha inventato un metodo `parseAsync` per lo schema.»

«Accuratezza o fedeltà?»

«Il metodo esiste nella documentazione che ho incollato: ha solo smesso di leggerla dopo il turno numero quaranta.»

«Allora è un problema di fedeltà. Compatta e ricarica, non aggiungere altra documentazione.»

Ciò che il modello «sa» grazie al training, conservato nei suoi parametri. I parametri vengono congelati durante il training: il modello non può vederli né aggiornarli. Il processo di compressione lascia fuori dettagli: miliardi di fatti vengono stipati in un numero fisso di parametri e quelli rari si confondono. È la fonte della fluidità sugli argomenti comuni e delle invenzioni su quelli meno comuni. È il contrario delle conoscenze contestuali.

Le conoscenze parametriche non sono conservate sotto forma di fatti. Il training non fornisce al modello un database da consultare: modifica i parametri finché il modello non predice bene il testo, e un modello che predice bene il testo su un argomento si comporta come se lo conoscesse. L’affidabilità della conoscenza dipende da quante volte un argomento è comparso nei dati di training: il modello riproduce con precisione un argomento con milioni di esempi, mentre per uno con pochi esempi indovina sulla base di argomenti simili. Per il modello, riprodurre e indovinare sono lo stesso processo, quindi non può sapere quale dei due stia svolgendo. Una risposta inventata arriva con la stessa fluidità di una corretta. Un’allucinazione è un’ipotesi sbagliata del modello.

Le conoscenze parametriche invecchiano. I parametri smettono di cambiare alla soglia di conoscenza, quindi una libreria pubblicata o rinominata dopo quella data non è presente e un’API modificata viene ricordata nella sua vecchia forma.

Per entrambe le lacune — informazioni troppo rare o troppo recenti — il rimedio è lo stesso: non si possono aggiungere ai parametri, quindi vanno fornite come conoscenze contestuali.

Uso:

«Scrive codice React impeccabile, ma si inventa metodi per il nostro SDK interno.»

«React è presente in abbondanza nelle conoscenze parametriche: milioni di esempi di training. Il tuo SDK no, quindi il modello completa i vuoti con forme plausibili. Carica la documentazione dell’SDK nel contesto.»

La data oltre la quale un modello non dispone di conoscenze parametriche. Librerie, API ed eventi successivi alla soglia possono indurre il modello a inventare informazioni, a meno che la relativa documentazione non venga caricata come conoscenza contestuale. Ogni versione di un modello ha la propria soglia.

Questa soglia dipende dal modo in cui vengono realizzati i modelli: il training incorpora nei parametri un’istantanea del testo, poi i parametri vengono congelati. Il modello non sa che le sue conoscenze hanno un limite: se gli chiedi qualcosa che risale a dopo la soglia, non si rifiuta, ma estrapola a partire dall’informazione più simile che conosce. È questo che rende silenziosa la trappola: il codice scritto per una vecchia versione di una libreria sembra plausibile, spesso viene compilato e poi fallisce proprio nei punti che sono cambiati.

La soluzione è sempre la stessa: inserire informazioni aggiornate nel contesto. Carica il changelog, indica le definizioni dei tipi della versione installata oppure chiedi all’agente di leggere la documentazione sul web. Qualsiasi cosa nel contesto prevale sull’assenza di informazioni nei parametri.

Uso:

«Continua a scrivere la sintassi dell’SDK v3, ma noi usiamo la v5.»

«La v5 è stata pubblicata dopo la soglia di conoscenza. Carica il changelog della v5 come conoscenza contestuale, altrimenti continuerà a inventare partendo dalla versione parametrica precedente.»

Fatti che l’agente può leggere direttamente dal contesto in questo momento: il compito dell’utente, i file che l’agente ha caricato, i risultati degli strumenti e il contenuto di AGENTS.md caricato all’inizio della sessione. È il contrario delle conoscenze parametriche: le conoscenze parametriche vengono richiamate dai parametri, quelle contestuali vengono lette dalla finestra. Le allucinazioni sono molto meno frequenti quando l’agente lavora a partire da conoscenze contestuali: la risposta è sotto i suoi occhi, non viene ricavata da una memoria sfocata.

Tra i due tipi di conoscenza, soltanto quello contestuale è sotto il tuo controllo. I parametri sono congelati, quindi l’unico modo per fornire al modello conoscenze che gli mancano — un SDK interno, una libreria pubblicata dopo la soglia di conoscenza, una decisione presa ieri — è inserirle nel contesto. Gran parte del lavoro pratico di programmazione con l’AI consiste proprio nel mettere i fatti giusti davanti al modello nel momento in cui gli servono.

Quando le conoscenze contestuali e quelle parametriche sono in conflitto, di solito prevalgono le prime. Incolla la documentazione API aggiornata e il modello la seguirà invece di affidarsi al ricordo obsoleto della vecchia API, anche se la vecchia versione può ancora riaffiorare, soprattutto nel corso di una sessione lunga. Se l’agente continua a tornare a un modello superato nonostante la documentazione sia caricata, sono le conoscenze parametriche a trapelare oltre quelle contestuali; ripetere la correzione o avvicinarla al punto in cui serve può aiutare.

A differenza delle conoscenze parametriche, quelle contestuali hanno un costo. Tutto ciò che carichi nella finestra consuma token e compete per il budget di attenzione del modello, quindi caricare più informazioni non è automaticamente meglio: l’obiettivo è avere nella finestra i fatti pertinenti, non tutti i fatti.

Ricorri a questo termine solo quando vuoi metterlo a confronto con «conoscenze parametriche»; altrimenti basta dire contesto.

Evitare: «memoria di lavoro»: le conoscenze contestuali sono ciò che si trova nella finestra ora; un sistema di memoria è ciò che inserisce nella finestra i contenuti tra una sessione e l’altra. Sono livelli diversi, da non confondere.

Uso:

«Perché usa correttamente l’API quando incollo la documentazione e se la inventa quando non lo faccio?»

«Con la documentazione, sono conoscenze contestuali: legge direttamente dalla pagina. Senza, sono parametriche e gli endpoint meno comuni diventano confusi.»

Quando prevede ciascun token, il modello considera tutti gli altri token nel contesto: alcuni hanno molta influenza, altri quasi nessuna. L’associazione tra due token è una relazione di attenzione; le coppie significative — per esempio «lei» e «Sarah», oppure una chiamata a `getUser()` e la sua definizione `function getUser` — si influenzano più delle coppie non correlate. Un contesto di N token contiene all’incirca N² relazioni.

È in queste associazioni che risiede l’apparente comprensione del modello. Se risolve il riferimento di un pronome, è perché la relazione di attenzione tra «lei» e «Sarah» è forte. Se chiama una funzione con gli argomenti corretti, è la relazione tra il punto della chiamata e la definizione letta in precedenza a svolgere il lavoro. Nulla viene cercato in una tabella: il calcolo viene rifatto a ogni richiesta al provider del modello, per ogni coppia.

Vale la pena soffermarsi sul valore N², perché cresce più rapidamente di quanto suggerisca l’intuizione:

Ogni coppia viene anche calcolata più di una volta. I modelli hanno più teste di attenzione: il numero esatto dei modelli di frontiera non è pubblicato, ma una stima ragionevole va da cinquanta a cento. Ogni testa calcola una propria versione di ciascuna relazione, quindi tutte le coppie nella tabella qui sopra vengono replicate per ogni testa. Sono davvero tante associazioni.

Per un dato compito, solo poche relazioni sono importanti. L’associazione tra la tua istruzione e il codice a cui si applica è una delle poche rilevanti; quasi tutte le altre sono rumore. Inoltre, le due quantità crescono a velocità diverse: le relazioni importanti restano più o meno costanti, mentre il totale cresce in modo quadratico con la dimensione del contesto. Con 1.000 token, la relazione che ti interessa è una su un milione; con 100.000 token, una su dieci miliardi. È l’aritmetica alla base del budget di attenzione; il degrado dell’attenzione è ciò che si avverte quando le relazioni importanti ricevono una quota troppo piccola.

Uso:

«Continua a confondere i due simboli `user` nella differenza di codice: sembra che siamo nella zona stupida.»

«Sì, la relazione di attenzione tra ciascun punto di chiamata e la sua dichiarazione è in competizione con l’altra: stessa forma del token, associazioni diverse. Rinomina uno dei due e le associazioni si distinguono meglio.»

Ogni token dispone di una quantità finita di influenza da distribuire sul resto del contesto. Una forte influenza su una relazione lascia meno influenza alle altre. Il budget è assegnato a ciascun token e non aumenta quando cresce il contesto: per questo le sessioni lunghe diluiscono il segnale.

Pensala come segnale e rumore. La tua istruzione è un segnale a volume fisso; ogni altro token nella finestra di contesto è un suono concorrente. L’istruzione non diventa mai più bassa: è ancora lì, carattere per carattere. Ma, mentre il contesto cresce, la stanza intorno diventa più rumorosa e il rapporto segnale-rumore diminuisce. Un’istruzione che spiccava quando il contesto conteneva 10.000 token diventa un brusio di fondo a 150.000. Questo è il meccanismo alla base del degrado dell’attenzione: il modello non dimentica, è il segnale a perdersi nel rumore.

Il sintomo sembra disobbedienza: l’agente accetta un vincolo all’inizio e poi se ne allontana; ripetere il vincolo aiuta solo per poco. La causa non è l’istruzione, ma tutto il resto nella finestra che compete con essa.

Puoi controllare ciò che entra nel contesto. Il contenuto che non serve al compito non è neutro: aggiunge rumore a tutto ciò che invece serve. Mantieni ridotta la finestra, svuotala quando il contesto accumulato non è più utile e ripeti i vincoli importanti, invece di confidare che basti averli menzionati all’inizio.

Uso:

«Perché continua a ignorare lo schema che ho incollato all’inizio?»

«Siamo già nella zona stupida: il budget di attenzione di ogni token è fisso, ma il contesto ha continuato a crescere. Ora il segnale dello schema compete con migliaia di token più recenti.»

Man mano che una sessione cresce, il budget di attenzione di ogni token si distribuisce tra un numero maggiore di concorrenti. Il segnale di ogni relazione significativa si indebolisce; il rumore del contesto irrilevante si accumula. Stesso modello, stessi parametri: semplicemente, più bocche da sfamare con lo stesso piatto. È la causa dell’effetto della zona intelligente e della zona stupida.

Si manifesta come un peggioramento del modello a metà sessione: i vincoli rispettati per un’ora cominciano a sfuggirgli, ripete domande a cui aveva già ricevuto risposta e scrive codice ignorando un file che aveva letto prima. Il modello non è cambiato: l’unica variabile è la quantità di contesto a cui ora deve prestare attenzione.

È un fenomeno graduale, e per questo è difficile accorgersene dall’interno della sessione. Non c’è un errore né una soglia: ogni turno è appena un po’ peggiore del precedente e, quando gli errori diventano evidenti, sei già da un po’ nella zona stupida.

Per recuperare, rimuovi contesto invece di aggiungerne. Incollare di nuovo l’istruzione ignorata aggiunge un altro concorrente alla stessa finestra sovraffollata e aiuta solo per poco. Funzionano invece queste opzioni: svuotare il contesto e ricaricare solo ciò che serve al compito, compattare oppure fare un handoff a una sessione nuova. Considera il calo nel rispetto delle istruzioni un segnale sulla lunghezza del contesto, non sul modello.

Uso:

«È in piena zona stupida: si sta inventando generici che non esistono nel file dei tipi.»

«Degrado dell’attenzione. Le definizioni dei tipi sono ancora nel contesto, ma il loro segnale è sepolto sotto tutto ciò che abbiamo aggiunto. Svuota e ricarica.»

All’inizio di una sessione, l’agente si trova nella «zona intelligente»: è lucido, concentrato e ricorda bene. Man mano che la sessione prosegue, scivola nella «zona stupida»: diventa più impreciso, smemorato e incline agli errori e alle allucinazioni di fedeltà. Stesso modello, stesso harness, solo più contesto. È l’effetto percepito del degrado dell’attenzione. Nei modelli di frontiera, la zona stupida spesso inizia intorno ai 125.000-150.000 token, anche se la questione è dibattuta. Svuota o compatta la sessione quando si gonfia: non cercare di forzare oltre.

Il calo è graduale e per questo è facile non accorgersene. Non compare un messaggio d’errore né un limite visibile: l’agente comincia semplicemente a rendere un po’ peggio, poi in modo evidente. Tra i segnali comuni: dimentica un’istruzione data venti turni prima, ripete un errore che aveva già corretto o afferma con sicurezza qualcosa che contraddice il contesto. Poiché il peggioramento è progressivo, la risposta abituale è insistere e spiegare di nuovo, aggiungendo altro contesto e aggravando il problema.

Le zone non corrispondono al limite della finestra di contesto. Una sessione può essere profondamente nella zona stupida con gran parte della finestra ancora libera: il limite è il punto in cui l’harness rifiuta di proseguire, ma la qualità cala molto prima. Organizzati intorno alla zona intelligente, non alla finestra: il budget pratico di un compito è la quantità di token entro cui l’agente lavora bene, non quella che può contenere tecnicamente.

La zona intelligente è un budget, e il lavoro non pertinente lo consuma. Ogni compito svolto in una sessione usa token; iniziarne un secondo nella stessa sessione significa cominciarlo più vicino alla zona stupida. Dedicare una sessione a ciascun compito consente a ognuno di usare la parte più lucida della sessione. Se un singolo compito supera una zona intelligente, dividilo: fai un handoff o compatta il contesto a un confine naturale, poi lascia che una sessione nuova svolga la parte successiva.

Uso:

«Ha realizzato alla perfezione i primi tre componenti e ha rovinato completamente il quarto.»

«Sei uscito dalla zona intelligente: stesso modello, solo molto più in profondità nella zona stupida. Compatta e ricarica il piano; il prossimo componente verrà meglio.»

Terminare la sessione corrente e avviarne una nuova. Il messaggio successivo inizierà in una sessione vuota, con una finestra di contesto vuota. Di solito è un’azione avviata dall’utente.

Svuotare il contesto è la cura per un contesto contaminato. Una sessione accumula tutto: tentativi falliti, vicoli ciechi, risultati degli strumenti ormai obsoleti, piani abbandonati. A ogni turno, il modello rilegge tutto e la cronologia sbagliata si trascina nel nuovo lavoro. Nel corso di una sessione lunga, l’agente diventa più vago e meno incline a seguire le istruzioni: istruzioni che avevi formulato chiaramente vengono ignorate, la qualità cala e insistere perché faccia meglio non serve, perché il rumore che deve attraversare è ancora nel suo contesto. Svuotare elimina quel rumore.

Svuotare non cancella la conversazione. La maggior parte degli harness conserva la cronologia delle sessioni sul computer, così la trascrizione resta disponibile per leggerla o riprenderla. Ciò che scompare è lo stato di lavoro dell’agente: il modello non conserva lo stato, quindi la nuova sessione non sa nulla di ciò che sapeva la precedente. Se la sessione contiene decisioni o progressi utili alla successiva, fai prima scrivere all’agente un artefatto di handoff, poi avvia la nuova sessione indicandogli quel documento.

Confronta questa operazione con la compattazione, che riassume la sessione nel nuovo contesto invece di ripartire da zero. Svuotare è lo strumento più drastico: non viene mantenuto nulla, nemmeno la spazzatura.

Uso:

«È bloccato in un ciclo sul test che fallisce.»

«Svuota il contesto: avvia una sessione nuova con il documento del piano e il file di test. Non vale la pena lottare contro il contesto attuale.»

Trasferire contesto dell’agente da una sessione a un’altra. Il meccanismo di trasferimento varia: può essere un artefatto di handoff scritto, un riepilogo in memoria (compattazione o altro). È diverso dallo svuotamento, che non trasferisce nulla. Le ragioni variano: cambiare ruolo, passando da pianificatore a esecutore; avviare una sessione AFK; distribuire il lavoro tra sessioni parallele o liberare spazio nella finestra di contesto.

La sessione che riceve il trasferimento inizia senza contesto: il modello non conserva lo stato, quindi nulla della vecchia sessione è visibile a quella nuova. Occorre trasferire esplicitamente ciò che serve alla sessione successiva; tutto il resto va perduto. Il vincolo «nessun percorso di ritorno» determina che cosa trasferire: la nuova sessione non può chiedere alla vecchia che cosa intendesse, quindi il materiale trasferito deve essere autosufficiente.

Il fallimento più visibile di un handoff mal fatto è dover riaprire decisioni già risolte: la nuova sessione ci torna sopra perché il materiale trasferito registra che cosa si era deciso, ma non perché. Valuta un handoff in base a ciò che potrebbe fare una sessione priva di contesto usando quel materiale.

Uso:

«La sessione di pianificazione sta diventando pesante: continuo?»

«Fai un handoff. Scrivi le decisioni in un documento, svuota il contesto e avvia l’implementazione in una sessione nuova che lo legga.»

Una fonte nella sua forma originale: il codice, la trascrizione di una conversazione, il log grezzo, la risposta effettiva dell’API. Non il resoconto della cosa, ma la cosa stessa. È il corrispettivo della fonte secondaria.

Se vuoi sapere cosa fa la tua codebase, la fonte primaria è il codice. La documentazione, il diagramma dell’architettura e il README ne sono descrizioni: erano accurate quando sono stati scritti, ma da allora seguono ciascuno i propri tempi. Quando un agente afferma con sicurezza qualcosa di sbagliato sul tuo progetto, chiediti da quale fonte abbia ricavato l’informazione: un agente che ha letto un documento ne eredita l’obsolescenza; uno che ha letto il codice sta leggendo la verità attuale.

Il costo è ciò che impedisce alle fonti primarie di essere la scelta predefinita. Caricarne una nella finestra di contesto è costoso: il file intero, la trascrizione completa, ogni token conteggiato come input e in competizione per il budget di attenzione. In cambio ottieni completezza: nulla è stato filtrato in anticipo dal giudizio di qualcun altro su ciò che contava. Un riepilogo scritto il mese scorso non può contenere un dettaglio che solo oggi si rivela importante; la fonte primaria, invece, lo conserva.

Consulta la fonte primaria quando la precisione è importante: la firma esatta, l’errore effettivo, la riga che genera l’eccezione. Gran parte della gestione del contesto consiste nel decidere quando vale la pena pagare il costo della fonte primaria e quando basta una fonte secondaria.

Uso:

«L’agente dice che la logica dei nuovi tentativi applica un backoff esponenziale, ma lo vedo martellare l’endpoint.»

«L’ha letto nel documento di progettazione. Indirizzalo al modulo dei tentativi vero e proprio: quando il comportamento conta, lavora dalla fonte primaria.»

Il resoconto di una fonte primaria, a un passaggio di distanza: documentazione che descrive codice, un riepilogo che descrive una trascrizione, un rapporto che descrive risultati di ricerca. È più economico da caricare nella finestra di contesto rispetto alla fonte descritta, ma è intrinsecamente una rappresentazione con perdite: chi l’ha scritto ha deciso cosa fosse importante e ciò che ha omesso è invisibile a chi legge solo il riepilogo.

Gran parte dell’ingegneria del contesto consiste nel produrre fonti secondarie. La compattazione trasforma la cronologia della sessione in un riepilogo che avvia quella successiva. Un subagente usa il proprio contesto per una ricerca rumorosa e restituisce un breve rapporto. Un artefatto di handoff condensa le decisioni della sessione in un documento che verrà letto nella sessione successiva. I sistemi di memoria distillano ciò che una sessione ha appreso in appunti. Tutti effettuano lo stesso compromesso: fedeltà in cambio di spazio.

Le fonti secondarie falliscono in due modi. Sono incomplete: il riepilogo della compattazione che ha perso la decisione sullo schema, il rapporto che non menzionava il caso limite. E vanno fuori sincrono: la fonte primaria cambia e il resoconto non viene aggiornato, così i documenti descrivono l’architettura del trimestre scorso con la sicurezza di oggi. Quando un agente agisce sulla base di una fonte secondaria che ha fallito in uno dei due modi, lavora con sicurezza partendo da informazioni sbagliate; la soluzione è rimandarlo alla fonte primaria.

Nessuno di questi problemi rende le fonti secondarie un errore. La finestra di contesto è limitata e le fonti primarie sono costose; senza riepiloghi, rapporti e documenti di handoff non entrerebbe nulla di grande. La capacità consiste nel sapere quali dettagli possono sopravvivere alla perdita e quando occorre verificare una fonte primaria. Una fonte secondaria ben fatta include un puntatore al contesto che rimanda all’originale — il riepilogo che indica la trascrizione da cui proviene, il documento che nomina il file descritto — così, quando il resoconto non basta, il lettore può seguire il puntatore invece di affidarsi a ciò che è andato perso.

Uso:

«Il documento di handoff dice che l’autenticazione è pronta, ma la nuova sessione continua a trovare problemi nel rinnovo dei token.»

«Il documento è una fonte secondaria: l’ultima sessione ha annotato ciò che riteneva vero, non ciò che è vero. Fai eseguire alla nuova sessione i test di autenticazione e fidati della fonte primaria.»

Un documento usato come supporto per un handoff: una sessione lo scrive nell’ambiente perché un’altra sessione lo legga. Le specifiche, i ticket e i documenti di piano sono tutti artefatti di passaggio.

Perché scriverne uno: il model è stateless, quindi nulla di una sessione sopravvive al suo azzeramento. Decisioni, vincoli, piani a metà: scompaiono insieme al contesto che li conteneva. L’ambiente persiste. Scrivere le informazioni importanti in un file le sposta in un luogo da cui la sessione successiva può recuperarle.

L’artefatto è una fonte secondaria: il resoconto del lavoro svolto nella sessione, non il lavoro stesso. Questo lo rende abbastanza breve da fornire indicazioni a una sessione nuova, ma può anche trarla in inganno: registra ciò che la sessione autrice riteneva vero, mentre omissioni ed errori restano invisibili a chi legge. Quando un’affermazione è importante, la sessione successiva dovrebbe verificarla rispetto alla fonte primaria, cioè il codice e i test, invece di ereditarla.

Un buon artefatto è scritto per una sessione che parte senza alcun contesto. Percorsi concreti ai file invece di «il file di cui abbiamo parlato». Che cosa è stato deciso e perché, così la sessione successiva non deve ridiscutere tutto. Che cosa è fatto e che cosa resta da fare. È utile dire alla sessione autrice a chi è destinato l’artefatto: «scrivi un documento di passaggio per una nuova sessione che non sa nulla di questo lavoro».

L’alternativa è la compattazione, che riassume ciò che è in memoria. L’artefatto ha due vantaggi: resta su disco, dove puoi leggerlo e correggerlo prima che qualcuno vi faccia affidamento, e si può riutilizzare: la stessa specifica può fornire indicazioni a cinque sessioni parallele.

Uso:

«Come divido questo lavoro tra l’agent che pianifica e quello che implementa?»

«Fai scrivere all’agent pianificatore un artefatto di passaggio con percorsi dei file, decisioni e vincoli. La sessione dell’agent implementatore inizia con un puntatore all’artefatto e lo usa come brief.»

Un artefatto di passaggio che descrive un’attività articolata su più sessioni: che cosa si sta costruendo, non come ciascuna sessione svolge la propria parte. Si aggiorna man mano che il lavoro procede. È composto da ticket.

La specifica esiste perché le sessioni sono temporanee, mentre il lavoro importante non lo è. Qualsiasi attività che richieda più di una finestra di contesto ha bisogno di uno spazio al di fuori del contesto: un luogo nell’ambiente dell’agente che sopravviva all’azzeramento, che sia un file nel repository, una issue di GitHub o un issue tracker accessibile all’agent. La specifica è quel luogo: obiettivo, vincoli, decisioni prese finora ed elenco dei ticket con il loro stato. Ogni nuova sessione può leggerla e capire a che punto è il lavoro, senza ereditare il rumore accumulato dalla precedente.

Le specifiche seguono stili riconoscibili, perlopiù ereditati dal modo in cui i team già documentano il lavoro. Un documento dei requisiti di prodotto (PRD) privilegia il che cosa e il perché rivolti agli utenti: funzionalità, comportamento e criteri di accettazione. Un documento di progettazione o un RFC è più tecnico: approccio scelto, alternative scartate e compromessi. All’estremo più semplice, un `plan.md` con una lista di controllo dei ticket svolge lo stesso compito per una funzionalità che si estende su più sessioni. Lo stile conta meno della funzione: per l’agent, sono tutti la stessa cosa, ovvero la dichiarazione durevole d’intenti che legge all’inizio di ogni sessione.

Uso:

«Dovremmo fare tutto in una sola sessione?»

«No, mettilo per iscritto in una specifica: dividilo in ticket e svolgili ciascuno in una sessione separata. Cercare di fare tutto in un unico contesto ti farà entrare nella zona di confusione prima di arrivare a metà.»

Un artefatto di passaggio che definisce l’ambito di una sessione di lavoro. Può esistere da solo o essere collegato a una specifica come uno dei suoi elementi secondari. I ticket possono bloccare altri ticket dello stesso livello o esserne bloccati; l’ordine del lavoro emerge così dal grafo delle dipendenze, anziché da un piano lineare.

Il vincolo che lo definisce è la dimensione: una sessione. Un ticket dovrebbe poter essere completato prima che la sessione esca dalla zona di lucidità, e questo vincolo si può verificare. Se le sessioni dedicate ai ticket si degradano regolarmente prima che il lavoro sia finito, i ticket sono troppo grandi: dividili. Se ogni sessione passa quasi tutto il proprio contesto a prepararsi prima di svolgere cinque minuti di lavoro, i ticket sono troppo piccoli: uniscili.

Un buon ticket è scritto per chi non conosce il contesto. Obiettivo, criteri di accettazione e puntatori al contesto verso file e decisioni pertinenti: abbastanza informazioni perché la sessione possa iniziare senza dover ricostruire ciò che sapeva quella precedente.

Il grafo delle dipendenze è anche ciò che rende possibile il parallelismo. Ticket indipendenti, cioè le foglie del grafo, possono svolgersi ciascuno in una sessione separata e contemporaneamente agli altri. È un modo efficace per eseguire più agent in parallelo. In una software factory, contrassegnare un ticket come pronto è già di per sé il trigger che avvia la relativa sessione.

Uso:

«Da dove comincio con la specifica di migrazione?»

«Guarda il grafo dei ticket: la modifica dello schema blocca il backfill, e il backfill blocca il passaggio all’API. Scegli una foglia e avvia una sessione.»

Un handoff eseguito in memoria: la cronologia della sessione precedente viene riassunta e il riepilogo avvia una nuova sessione. È una perdita voluta: la trascrizione è una fonte primaria, il riepilogo una fonte secondaria; si sacrifica il dettaglio per guadagnare spazio. Può essere avviato manualmente dall’utente o automaticamente tramite autocompact.

Il meccanismo: la finestra di contesto è finita e una sessione lunga la riempie: nella cronologia restano ogni risultato di uno strumento, ogni file letto, ogni tentativo sbagliato. Quando diventa troppo pesante, l’harness chiede al model di riassumere la sessione, elimina la cronologia originale e avvia una nuova sessione con il riepilogo. Tutto ciò che non è entrato nel riepilogo scompare dal contesto. Alcuni harness attenuano la perdita conservando la vecchia trascrizione su disco e lasciando nel riepilogo un puntatore al contesto: la fonte secondaria rimanda alla primaria, quindi un dettaglio perso nel riepilogo si può recuperare rileggendo l’originale.

Il riepilogo è scritto dal model, quindi gli si può dare un prompt. «Preserva le decisioni sullo schema» rende l’artefatto generato più intenzionale. Anche il momento conta: compatta a un cambio di fase, dopo aver definito il piano, non nel mezzo dell’attività.

A differenza dell’azzeramento, che elimina tutto e riparte da zero, la compattazione cerca di trasferire gli elementi essenziali; l’azzeramento scommette che siano già stati annotati in un posto migliore.

Uso:

«Il contesto si sta appesantendo e devo ancora eseguire i test.»

«Compatta prima di iniziare: indica nel prompt del riepilogo ciò che deve sopravvivere, così la nuova sessione conserva le decisioni sullo schema e scarta l’esplorazione.»

Compattazione avviata automaticamente dall’harness quando la finestra di contesto sta per riempirsi.

L’harness controlla quanto è piena la finestra di contesto. Quando supera una soglia, spesso intorno all’80%, si ferma, chiede al modello di riassumere la sessione svolta fino a quel momento e avvia una sessione nuova con il riepilogo. Il lavoro prosegue come se non fosse successo nulla.

E invece è successo qualcosa. La compattazione comporta una perdita di informazioni, e la compattazione automatica interviene in un momento che non hai scelto. Puoi compattare manualmente a un confine tra le fasi, quando sai indicare al modello che cosa conservare. La compattazione automatica scatta a metà compito, appena si raggiunge la soglia: magari nel bel mezzo di un refactoring, e il riepilogo decide da solo quali tue decisioni vale la pena mantenere. Il sintomo tipico è che l’agente prosegue con sicurezza, ma ha dimenticato senza dirlo un vincolo stabilito un’ora prima; te ne accorgi solo quando il lavoro comincia a contraddirlo.

La difesa migliore è impedire che si attivi. Tieni d’occhio l’indicatore del contesto e compatta manualmente a un confine naturale, oppure scrivi le decisioni in un piano o in un artefatto di handoff su disco, dove nessun riepilogo può perderle. La maggior parte degli harness permette anche di personalizzare il margine: anticipare o posticipare la soglia oppure disattivare del tutto la compattazione automatica, così puoi regolare quanto spazio libero vuoi mantenere prima che scatti.

Uso:

«Non sembra ricordarsi che cosa avevamo deciso prima sullo schema.»

«La compattazione automatica è scattata tra i turni: le decisioni iniziali sono state riassunte e probabilmente abbiamo perso qualcosa. Ricarica il piano oppure la prossima volta compatta manualmente, così decidi tu che cosa conservare.»

Un sistema che cerca di rendere stateful un agent tra una sessione e l’altra. Durante una sessione salva informazioni nell’ambiente e le ricarica nel contesto all’inizio delle sessioni future, così l’agent mantiene continuità anche dopo che l’utente azzera la sessione.

Un sistema di memoria ha due metà. Il percorso di scrittura: durante la sessione, l’agent registra ciò che ha appreso — una preferenza che hai espresso, un fatto sul progetto — come file nell’ambiente. Il percorso di lettura: all’avvio della sessione, l’harness ricarica quei file, o un loro indice, nella finestra di contesto. Molti harness includono un proprio sistema di memoria — `/memory` di Claude Code è un esempio — ma puoi anche crearne uno: una directory di appunti e un’istruzione in AGENTS.md che ne richieda la consultazione.

Valgono gli stessi compromessi di qualsiasi contenuto caricato sempre. I ricordi si accumulano, quindi la maggior parte dei sistemi carica un indice di una riga e lascia i contenuti dietro puntatori al contesto, invece di inserirli per esteso. Inoltre, i ricordi sono fonti secondarie e quindi invecchiano: un fatto registrato a marzo viene caricato con la stessa sicurezza a giugno, quando il progetto è già cambiato. Un sistema di memoria va ripulito, proprio come AGENTS.md.

Uso:

«Devo continuare a ripetergli che uso Postgres, non MySQL.»

«Configura un sistema di memoria: al primo turno scrivi ciò che apprende nel filesystem, poi ricaricalo all’avvio della sessione. Il model è stateless; lo strato di memoria simula la continuità.»

Un file nell’ambiente che l’harness carica nella context window all’avvio della sessione: il brief permanente del progetto per l’agent. È una convenzione condivisa tra harness; alcuni hanno anche una propria variante (quella di Claude Code è CLAUDE.md).

Poiché viene caricato automaticamente, è un modo per evitare di ripetere le stesse cose tra una sessione e l’altra. Il model è stateless: una correzione data in una sessione non è più disponibile nella successiva e finisci per ripetere a ogni nuova sessione che il progetto usa pnpm, che i test si eseguono con un certo flag, che una directory è generata e non va toccata. Quando hai corretto l’agent due volte sulla stessa cosa, quella correzione è una possibile riga da aggiungere a AGENTS.md.

Il contenuto adatto è quello che l’agent non può dedurre dal codice: comandi di build e test, convenzioni non ovvie della codebase, vincoli rigidi («non modificare mai il client generato»). Deve essere breve e dichiarativo: un brief, non documentazione.

Il compromesso è che viene caricato sempre tutto. Le istruzioni si accumulano e molte non sono pertinenti a una determinata attività; un AGENTS.md lungo consuma token e si diluisce: più istruzioni ci sono nel contesto, meno affidabilmente il model ne segue ciascuna.

Evitare: usare AGENTS.md per contenuti da rivelare progressivamente: ogni informazione al suo interno costa token a ogni turno, in ogni sessione, serva o meno. Una guida di stile può stare dietro a una skill o a un context pointer; AGENTS.md va riservato alle righe valide ovunque.

Uso:

«Perché ogni sessione parte con 4k token già consumati?»

«Controlla AGENTS.md: qualcuno ci ha incollato l’intera guida di stile invece di metterla dietro a una skill.»

Caricare solo il contesto di cui l’agente ha bisogno in quel momento, usando puntatori al contesto per il resto. Il termine viene dal design delle interfacce, dove indica il mostrare agli utenti soltanto i controlli pertinenti al compito corrente e nascondere gli altri dietro un clic.

La tecnica esiste perché il contesto costa due volte. Ogni token caricato in anticipo viene conteggiato come token di input a ogni turno, e ogni token consuma budget di attenzione, che serva o meno all’agente. Un AGENTS.md pieno di tutta la guida di stile, del manuale operativo per il deployment e delle convenzioni del database rende l’agente peggiore in tutte queste attività: le istruzioni pertinenti al compito corrente vengono diluite da quelle che non lo sono. Il segnale rivelatore è un agente che ignora regole che sai essere nel suo contesto: ci sono, ma sono sepolte.

La divulgazione progressiva capovolge questo approccio. Mantieni ridotto il livello caricato sempre: una frase per argomento e un puntatore al luogo in cui si trovano i dettagli. L’agente legge la guida di stile quando scrive un componente, il manuale operativo quando esegue il deployment e nessuno dei due quando corregge un test. Le skill applicano questo modello nell’harness: una breve descrizione viene caricata a ogni sessione, mentre le istruzioni complete si caricano solo quando servono.

Uso:

«Dovrei riversare l’intera guida di stile in AGENTS.md?»

«No: divulgazione progressiva. Indica la guida di stile come una skill che l’agente carica quando deve davvero scrivere un componente. AGENTS.md comporta un costo in token a ogni turno.»

Un riferimento in un documento che rimanda a un altro, così che l’agent possa caricarlo nella context window soltanto quando il compito lo richiede. È l’unità di cui è composta la divulgazione progressiva.

Il motivo per usare un puntatore invece di includere il contenuto è il costo. Un puntatore occupa una riga nella finestra di contesto. Il documento a cui rimanda può contenere migliaia di token, ma quei token non costano nulla finché l’agent non segue il puntatore. Incolla un runbook di 2.000 token in AGENTS.md e ogni sessione lo paga; sostituiscilo con «procedura di deploy: vedi `internal/deploy.md`» e lo caricheranno solo le sessioni che eseguono deploy. L’agent segue il puntatore con una tool call quando il compito è pertinente.

Per funzionare, un puntatore ha bisogno di due elementi: un percorso stabile e una descrizione sufficiente perché l’agent capisca quando vale la pena seguirlo. Un percorso senza contesto è un puntatore che l’agent non ha motivo di seguire; «vedi `internal/deploy.md`» senza indicazioni sul contenuto verrà ignorato da una sessione a cui serviva. Scrivi la riga in modo che corrisponda a come si presentano i compiti: «release, deploy o rollback: leggi prima `internal/deploy.md`».

I puntatori sono ovunque, se ci fai caso: righe in AGENTS.md, descrizioni delle skill (l’harness carica la descrizione, mentre il contenuto resta dietro al puntatore), nomi di file nell’elenco di una directory, collegamenti tra documenti.

Un puntatore può anche collegare una fonte secondaria alla fonte primaria da cui deriva: per esempio, il riepilogo di compattazione che indica la trascrizione originale o il documento che indica il file sorgente descritto. In questo modo la perdita di informazioni della fonte secondaria è recuperabile: se il riepilogo non basta, l’agent segue il puntatore e legge l’originale invece di lavorare soltanto con ciò che il riepilogo ha conservato.

Evitare: «riferimento», troppo neutro e non comunica che seguirlo carica altro contesto. «Portale», troppo enfatico.

Uso:

«AGENTS.md sta diventando enorme.»

«La maggior parte dovrebbe contenere puntatori al contesto, non contenuti. Lascia inline le regole sempre valide; trasforma il runbook di deploy e la guida di stile in skill e lascia un puntatore al contesto.»

Una capacità insegnabile raccolta in un’unità: istruzioni e risorse per svolgere bene un compito, conservate nell’ambiente finché un puntatore al contesto non le carica nella context window per il compito in corso. È l’unità di divulgazione progressiva in un harness.

Le skill sono uno standard aperto, definito su agentskills.io, sviluppato inizialmente da Anthropic e poi adottato dalla maggior parte degli harness principali; una skill scritta una volta funziona quindi su tutti. Il formato è una cartella che contiene:

• Un file `SKILL.md`: metadati (almeno un nome e una descrizione) oltre alle istruzioni vere e proprie
• Facoltativamente, script che l’agent può eseguire
• Facoltativamente, modelli e materiale di riferimento indicati dalle istruzioni

Per impostazione predefinita, nel contesto si trovano soltanto nome e descrizione. Quando il compito dell’agent corrisponde, carica il resto. Fino a quel momento la skill occupa pochissimo spazio — una o due frasi di token, per quanto siano lunghe le istruzioni complete.

Questo distingue le skill da AGENTS.md, che viene caricato in ogni sessione indipendentemente dal compito. Una skill si legge quando serve un particolare tipo di lavoro — un rilascio, l’impalcatura di un nuovo servizio, una migrazione — e viene ignorata il resto del tempo.

Evitare: «tool»: uno strumento è ciò che l’agent chiama; una skill contiene istruzioni che l’agent legge.

Uso:

«Dove metto il runbook di deploy?»

«In una skill: l’agent la carica solo quando il compito riguarda il deploy. In AGENTS.md consumerebbe token a ogni turno per qualcosa che usiamo ogni settimana.»

Un agente avviato da un altro agente tramite una chiamata a uno strumento. Opera nella propria sessione, con la propria finestra di contesto, e restituisce un solo risultato dello strumento. È diverso da un handoff: il genitore si aspetta esplicitamente una risposta; un handoff non prevede un percorso di ritorno. Non può avviare altri subagenti: l’albero ha un solo livello. I subagenti servono a isolare il contesto, non a creare gerarchie.

Lo scopo è tenere fuori dal contesto del genitore il lavoro rumoroso. Una ricerca ampia o una lunga esplorazione dei file produce pagine di risultati degli strumenti, la maggior parte utili solo fino a quando non si trova la risposta. Se l’attività viene eseguita nel processo del genitore, tutto resta nel suo contesto per il resto della sessione. Se viene affidata a un subagente, il rumore riempie invece una finestra usa e getta: nel contesto del genitore arriva solo il resoconto finale. Il resoconto è una fonte secondaria: il genitore riceve il racconto del subagente su ciò che ha trovato, non i risultati grezzi; ciò che il resoconto omette resta quindi invisibile al genitore.

I subagenti possono anche lavorare in parallelo: il genitore può avviarne diversi contemporaneamente per attività indipendenti.

Uso:

«I risultati di grep stanno saturando il mio contesto.»

«Avvia un subagente per fare la ricerca: userà la propria finestra di contesto per assorbire il rumore e ti riferirà i due percorsi di file che ti servono davvero.»

Uno schema di lavoro in cui una o più persone collaborano con l’agent durante una sessione: esaminano, reindirizzano o partecipano in tempo reale. La persona è presente e coinvolta, non si limita ad autorizzare singole azioni.

Il contrasto è con il lavoro AFK, in cui l’agent opera senza supervisione e il risultato viene valutato in seguito. Il lavoro con intervento umano permette di individuare i problemi quando correggerli costa poco: vedi l’agent scegliere il file sbagliato, interpretare male un requisito o imboccare una strada senza uscita e lo reindirizzi con una frase, invece di scoprire venti minuti dopo che ha costruito con sicurezza il proprio lavoro su quell’errore. Gli agent non sanno riconoscere in modo affidabile quando hanno perso la strada; se lasciati soli, tendono ad andare avanti anziché fermarsi e chiedere.

Lo schema adatto dipende dal lavoro. Attività ben definite, a basso rischio e facili da verificare sono adatte ad AFK. Attività ambigue, irreversibili o difficili da valutare una volta concluse — una migrazione dello schema, una decisione progettuale delicata, qualsiasi intervento sulla produzione — richiedono di restare nel ciclo. La valutazione è essenzialmente: quanto costa una deviazione e quanto tardi la noteresti?

Alcune attività richiedono per natura la partecipazione continua, perché le tue reazioni sono parte dell’input. Il grilling funziona solo se sei lì a rispondere alle domande; la prototipazione richiede che tu reagisca all’artefatto.

Restare nel ciclo consuma la tua attenzione, che è una risorsa scarsa. Migliorare il lavoro con gli agent significa spostarne una parte maggiore fuori dal ciclo in sicurezza, usando piani, controlli automatizzati e revisione umana alla fine anziché una supervisione continua. Una software factory porta l’idea oltre avviando sessioni tramite trigger, così non devi nemmeno avviare il lavoro.

Uso:

«Lo faccio eseguire in AFK durante la notte?»

«No, è una migrazione dello schema: mantieni l’intervento umano nel ciclo. Voglio vedere ogni passaggio e guidare l’agent se sceglie la colonna sbagliata da usare per il backfill.»

Lontano dalla tastiera. Una modalità di lavoro in cui l’utente avvia una sessione e lascia che l’agente operi senza supervisione. È il moltiplicatore della produttività nella programmazione con l’AI: molte sessioni AFK possono procedere in parallelo mentre dormi, mangi o ti occupi di altro. Di solito, per farlo in sicurezza, servono una modalità dei permessi permissiva e il sandboxing.

Quando non ci sei, l’agente gestisce l’ambiguità in modo diverso. Se sei presente, una decisione ambigua emerge sotto forma di domanda e tu rispondi; quando ti allontani, l’agente sceglie un valore predefinito e prosegue, e ogni decisione successiva si basa su quella supposizione. Il tipico fallimento è tornare dopo ore e trovare un lavoro finito e realizzato con sicurezza, ma costruito su una scelta sbagliata fatta nei primi dieci minuti. Il lavoro non è approssimativo: è coerente, ma coerente con la cosa sbagliata.

Dato che non puoi intervenire durante l’esecuzione, fornisci indicazioni prima e dopo. Prima: risolvi in anticipo le ambiguità, per esempio con una sessione di grilling o una specifica scritta, così l’agente ha meno lacune da colmare da solo. Durante: i controlli automatizzati e la revisione automatizzata suppliscono all’attenzione che non stai dedicando, individuando rapidamente ciò che si può intercettare meccanicamente. Dopo: l’esecuzione deve produrre qualcosa che si possa esaminare, come una PR, non modifiche già unite. AFK non elimina la revisione umana: la rimanda tutta alla fine, perciò ciò che arriva a quel punto deve valere la pena di essere esaminato. Ecco anche perché l’AX è più importante nelle esecuzioni AFK: senza nessuno a supervisionare, l’ambiente è l’unico supporto a disposizione dell’agente.

Evitare: «agente in background»: mette al centro la macchina («in esecuzione in background») invece della modalità dell’utente («l’utente si è allontanato»). AFK nomina il fatto rilevante: l’utente non sta guardando.

Uso:

«Sto lavorando AFK: tre agenti in sandbox sul refactoring, domattina esaminerò le PR.»

«Ignorare i permessi?»

«Sì, filesystem in sola lettura, senza rete.»

Una verifica deterministica eseguita nell’ambiente: test, controlli dei tipi, lint, build, hook pre-commit. Esito positivo o negativo, senza giudizi. È il segnale da cui un agent può correggersi da solo, senza coinvolgere altre persone. Un test intermittente è una verifica difettosa, non l’assenza di una verifica: per definizione i controlli automatizzati sono deterministici.

L’autocorrezione funziona come un ciclo. L’agent apporta una modifica, esegue la verifica con una tool call e l’output dell’errore finisce nella sua context window: un errore di tipo con file e riga, un’asserzione non riuscita con i valori atteso ed effettivo. Questo basta all’agent per correggere il problema ed eseguire di nuovo la verifica, ripetendo il ciclo finché non passa, senza intervento umano. Il determinismo rende affidabile il ciclo: lo stesso codice dà sempre lo stesso esito, quindi un superamento ha valore. Una verifica intermittente compromette tutto: l’agent «corregge» codice che era corretto o riprova oltrepassando un errore reale.

Per questo le buone verifiche contribuiscono in larga misura all’AX di una codebase. Un agent in un repository con tipi rigorosi, una suite di test rapida e un linter individua da solo la maggior parte dei propri errori prima che tu li veda; un agent in un repository privo di tutto questo pubblica qualunque cosa produca. La differenza conta soprattutto nelle esecuzioni AFK, dove i controlli sono l’unica verifica in corso. Ma una verifica rileva soltanto ciò che asserisce: i controlli verdi significano che le proprietà asserite sono rispettate, non che il codice sia corretto. Le lacune che richiedono giudizio sono ciò a cui servono la revisione automatizzata e la revisione umana.

Evitare: «feedback loop» / «backpressure»: entrambi confondono verifiche e revisioni. Evitare: «test»: i test sono verifiche automatizzate, ma non tutte le verifiche automatizzate sono test.

Uso:

«L’agent continua a pubblicare codice difettoso nelle esecuzioni AFK.»

«Quali controlli automatizzati sono configurati nel sandbox?»

«Solo gli unit test.»

«Aggiungi typecheck e lint: l’agent potrà correggersi da solo prima ancora che la PR venga aperta.»

Un agente che esamina il lavoro di un altro agente, spesso con un modello o un prompt di sistema diverso. È non deterministico: formula un giudizio. Può essere eseguito ovunque — prima del merge su una PR, a posteriori sulla cronologia dei commit o durante una sessione come subagente. Un LLM usato come giudice nella CI è una revisione automatizzata, non un controllo automatizzato: la categoria dipende da ciò che l’asserzione fa, non da dove viene eseguita.

La separazione dall’agente che sta svolgendo il lavoro è ciò che la rende efficace. Chiedere all’agente che ha scritto il codice di esaminare il proprio lavoro serve a ben poco: la sessione che ha prodotto il bug contiene anche il ragionamento che lo ha generato, e l’agente rilegge le proprie conclusioni come conferme. Un revisore con una finestra di contesto nuova non ha quel legame: vede la differenza di codice come la vedrebbe un estraneo, condizione essenziale per una revisione. Un modello diverso o un prompt di sistema dedicato alla revisione affinano ulteriormente il risultato: punti ciechi diversi e un prompt circoscritto a ciò che interessa davvero — sicurezza, contratti API, prestazioni — invece di un generico «cerca problemi».

Si colloca tra gli altri livelli di revisione. I controlli automatizzati sono deterministici e intercettano ciò che si può verificare meccanicamente; la revisione umana è costosa e ha la scalabilità peggiore. La revisione automatizzata sta nel mezzo: intercetta problemi che richiedono giudizio — un nome di funzione fuorviante, un caso limite trascurato — a costo macchina. Poiché è non deterministica, può non rilevare qualcosa o segnalare falsi problemi; trattala come un filtro che alza il livello prima dell’esame umano, non come un gate che lo sostituisce.

Evitare: «revisione AI» o «revisione dell’agente»: sono espressioni troppo vaghe per distinguerla dall’agente che svolge il lavoro.

Uso:

«Le esecuzioni AFK stanno generando troppe PR scadenti.»

«Aggiungi una fase di revisione automatizzata prima del merge: modello diverso, prompt di sistema separato, concentrato sulle modifiche che riguardano sicurezza e contratti.»

L’utente legge il codice prodotto dall’agente e formula un giudizio. Leggere la differenza di codice o i file modificati conta; leggere la descrizione dell’agente non conta: raccontare il lavoro non equivale a esaminare l’artefatto. La descrizione è una fonte secondaria, scritta dalla parte sottoposta a revisione; la differenza di codice è la fonte primaria, e revisionare significa leggerla.

Gli agenti aumentano il volume di codice prodotto, quindi la revisione diventa il collo di bottiglia. Un approccio utile consiste nell’alternare diverse strategie di revisione. I controlli automatizzati intercettano gli errori meccanici, la revisione automatizzata individua quelli descrivibili e la revisione umana viene riservata a ciò che solo tu puoi giudicare: se la modifica è quella giusta, se l’approccio è adatto alla codebase, se quella cosa dovrebbe esistere.

La revisione costa anche meno se viene fatta prima. Leggere un piano prima di iniziare o una piccola differenza di codice durante il lavoro richiede pochi minuti; esaminare a fondo un branch completato dopo una sessione AFK richiede più tempo. Scegliere dove inserire il punto di revisione è una decisione human-in-the-loop, non un ripensamento.

Evitare: «revisione del codice» da sola: non chiarisce se si tratti di revisione umana o automatizzata.

Uso:

«Ho revisionato personalmente l’output della sessione AFK.»

«Hai letto la differenza di codice o soltanto il riepilogo?»

«La differenza. Il riepilogo diceva che aveva eliminato codice morto; poi è risultato che la funzione veniva chiamata da un file generato.»

Uno schema di lavoro in cui l’utente accetta il codice dell’agent senza revisione umana. La differenza è trattata come una scatola nera: conta il comportamento del programma, non il contenuto. Possono comunque essere eseguite una revisione automatizzata e delle verifiche automatizzate; il vibe coding non si esprime né sull’una né sulle altre.

Il termine è stato coniato da Andrej Karpathy, che lo introdusse all’inizio del 2025: «ti abbandoni completamente alle vibes» e «dimentichi persino che il codice esiste» — descrivi ciò che vuoi, accetti ciò che arriva e lo valuti eseguendolo.

Il vibe coding scambia l’ispezione del codice con la velocità. Nei lavori guidati da agent, leggere le differenze è di solito il passaggio più lento, quindi saltarlo elimina il principale collo di bottiglia. Per codice con conseguenze poco costose — prototipi, script usa e getta, strumenti interni — è un compromesso ragionevole. Il rischio cresce con la durata prevista del codice e con la gravità delle conseguenze.

Il costo arriva più tardi. Le modifiche scritte con il vibe coding si accumulano in una codebase che nessuno ha letto e si è verificato soltanto il comportamento; perciò tutto ciò che il comportamento non rivela — un segreto scritto nei log, un caso limite mancante o una gestione dei dati silenziosamente errata — viene pubblicato senza essere visto. La prima volta che qualcuno fa debug del sistema è anche la prima volta che qualcuno legge il codice. Senza revisione umana, qualunque verifica automatizzata rimasta — test, tipi, revisione automatizzata — è l’unico gate che il codice deve superare. Lo stesso approccio applicato a una codebase intera, o a una sua parte, le cui modifiche provengono da una software factory dà luogo a una dark factory.

Evitare: usare «vibe coding» come sinonimo di «programmazione di bassa qualità con l’IA»: il termine descrive il modo di procedere senza revisione, non la qualità del codice risultante.

Uso:

«Hai letto quello che ha cambiato nel flusso di autenticazione?»

«L’ho fatto con vibe coding: il login funziona ancora, è tutto ciò che ho verificato.»

«Leggi il diff prima di fare push: programmare a vibes sull’autenticazione è un modo per far finire segreti nei log.»

La comprensione condivisa di ciò che si sta costruendo, comune all’utente e all’agente, ma distinta da ogni artefatto. È un termine di Brooks (The Design of Design): la conversazione, gli artefatti di handoff e il codice sono tutti artefatti che cercano di catturare o raggiungere il concetto di progettazione, ma nessuno è quel concetto. La qualità del concetto di progettazione si percepisce dalla qualità della conversazione che l’ha costruito.

Il termine dà un nome alla causa di una frustrazione familiare: l’agente scrive esattamente ciò che gli hai chiesto e il risultato è comunque sbagliato. Di solito, non avevi ancora capito del tutto che cosa volevi. Il concetto di progettazione non era completo nella tua mente: il prompt descriveva gli aspetti su cui avevi riflettuto e taceva su quelli ancora da definire. L’agente ha colmato quei silenzi con le proprie supposizioni, perché non c’era nulla con cui allinearsi. Non si è verificato alcun malfunzionamento: non esisteva un concetto di progettazione condiviso, perché non ce n’era ancora uno completo da condividere.

Capisci che il concetto di progettazione è condiviso come faresti con un collega: l’altra persona comincia a rispondere alle domande che non hai ancora posto nel modo in cui lo faresti tu. Fino a quel momento, il lavoro è conversazione — il grilling ne è la forma intenzionale — e scrivere una specifica troppo presto si limita a fissare il disallineamento in un artefatto più durevole. Il concetto di progettazione cambia anche man mano che impari; gli artefatti restano indietro. Per questo una specifica fedele alla comprensione della settimana scorsa può comunque fuorviare la sessione di questa settimana.

Uso:

«Sta scrivendo esattamente ciò che gli ho chiesto e il risultato è comunque sbagliato.»

«Non avete ancora un concetto di progettazione condiviso: sta colmando le lacune con supposizioni. Continuate a parlarne finché annullamenti, rimborsi e adempimenti parziali non saranno chiari a entrambi, prima di lasciarlo scrivere una specifica.»

Una tecnica per sviluppare un concetto di progettazione con un agente: l’agente intervista l’utente in modo socratico, una decisione alla volta, proponendo per ciascuna una risposta consigliata. Rallenta la corsa verso un piano definitivo: non viene scritto alcun artefatto di handoff finché il concetto non si stabilizza.

La tecnica esiste perché gli agenti colmano in silenzio le lacune. Se gli chiedi di scrivere una specifica partendo da un prompt di due righe, non si ferma davanti alle decisioni che non hai preso: sceglie valori predefiniti e li inserisce. Il risultato sembra completo e le supposizioni sono indistinguibili dalle scelte, quindi le scopri tardi: durante la revisione o quando la funzionalità implementata gestisce un caso limite in un modo che non hai mai scelto. Il grilling capovolge questa dinamica: invece di indovinare, l’agente deve fare domande.

È una tecnica human-in-the-loop: le tue risposte sono l’input. Se non è possibile rispondere a una domanda a parole — perché dovresti vedere la cosa — passa alla prototipazione.

Uso:

«È passato direttamente alla stesura della specifica e ha sbagliato la logica di annullamento.»

«Prima sottoponilo a un grilling: deve chiederti come gestire annullamenti parziali, rimborsi e tempistiche prima di fissare tutto nel documento. Risolverlo parlando costa meno che correggere il codice.»

Far realizzare all’agente una versione rapida e approssimativa di qualcosa, quando la conversazione è troppo poco fedele e serve un artefatto concreto di cui parlare.

Il grilling risolve le decisioni di progettazione attraverso la conversazione. Parlare costa poco, ma offre pochi dettagli concreti: alcune domande non si possono risolvere a parole — che sensazione dà un’interazione, se la forma di un’API è ergonomica nel codice che la usa davvero, se il layout funziona con dati reali. Durante l’intervista si arriva a una domanda e la risposta sincera è «non lo so, dovrei vederlo». Da lì in poi la discussione gira a vuoto. Invece, chiedi all’agente di costruire la cosa, guardala e torna alla conversazione con una risposta.

Gli agenti riducono il costo della realizzazione, rendendo pratico questo approccio. Una versione grezza che prima avrebbe richiesto un giorno di lavoro per essere abbozzata ora si prepara in pochi minuti, quindi conviene farlo abitualmente. È una tecnica human-in-the-loop: il prototipo serve a raccogliere le tue reazioni.

Di solito non ci si ferma a un solo sguardo. Itera sul prototipo: reagisci, chiedi una modifica, reagisci di nuovo, così ogni passaggio risolve un’altra decisione sulla base dell’artefatto reale, con una fedeltà maggiore di quella consentita dalla conversazione.

Un prototipo non deve per forza essere tutto provvisorio. Puoi realizzare con qualità da produzione i componenti che stai valutando; una volta presa la decisione, il componente o l’API a cui hai reagito può passare nella codebase vera. Per questo il prototipo è un materiale essenziale a cui la specifica può fare riferimento.

Uso:

«Abbiamo passato mezz’ora a discutere se la procedura guidata debba stare in una pagina o in tre passaggi.»

«A parole non lo risolviamo: chiediamo all’agente di prototipare entrambe le versioni. Le proviamo e in cinque minuti lo sapremo.»

Esperienza dello sviluppatore — quanto una codebase e la sua toolchain rendono facile per le persone lavorare bene. Una buona DX offre feedback rapidi, messaggi d’errore chiari, documentazione che risponde alla domanda che hai davvero e una configurazione che funziona al primo tentativo. Il termine esisteva molto prima della programmazione con l’AI; in questo dizionario serve soprattutto come termine di confronto per AX.

La DX riguarda l’interazione tra la persona e la codebase, nient’altro. La differenza principale tra i due pubblici è che le persone conservano lo stato, mentre gli agenti non lo conservano (stateless). Una persona impara una volta come funziona la codebase e si porta dietro quelle conoscenze ogni giorno: ecco perché una DX scadente è sopportabile. Si aggira una CI lenta raggruppando i push, si colma la documentazione mancante chiedendo una volta su Slack, si affronta una struttura confusa ricordando dove si trovano le cose. Le soluzioni di ripiego si accumulano e il team finisce per essere produttivo in una codebase che gli ostacola il lavoro.

Gli agenti affrontano la stessa codebase senza poter accumulare quelle conoscenze. Non conservando lo stato tra le sessioni, ogni volta un agente reimpara tutto da capo: trae vantaggio da una suite di test veloce e da messaggi d’errore chiari, ma dimentica ciò che ha capito il giorno prima, a meno che non sia stato scritto nell’ambiente, che l’agente percepisce solo tramite i risultati degli strumenti. È questo divario che AX descrive: gli aspetti della DX che restano utili quando chi sviluppa è un agente, più esigenze che le persone non hanno, come mantenere libera la finestra di contesto.

La sovrapposizione fa sì che gli investimenti nella DX spesso migliorino anche l’AX senza costi aggiuntivi: tipi rigorosi, test veloci e una struttura prevedibile aiutano entrambi. La divergenza significa che non succede sempre: una splendida guida all’onboarding aiuta una persona per una settimana, ma non un agente, a meno che non sia raggiungibile da AGENTS.md.

Uso:

«La nostra DX è buona: i nuovi assunti diventano produttivi in una settimana.»

«Sono produttivi perché qualcuno li affianca durante quella settimana. L’agente non ha una settimana a disposizione: valuta l’AX separatamente.»

Esperienza dell’agente — quanto bene è configurato l’ambiente perché un agente possa lavorare efficacemente in una codebase. È il corrispettivo, dal punto di vista dell’agente, della DX. Quando lo stesso agente lavora bene in un repository e male in un altro — stesso modello, stesso harness — di solito la differenza è nell’AX. L’istinto è dare la colpa al modello o riscrivere il prompt; più spesso, la soluzione è nel repository.

Una buona AX ha tre dimensioni principali:

AX e DX si sovrappongono — controlli validi e un’architettura pulita aiutano entrambi i pubblici — ma divergono. Le persone tollerano conoscenze informali, CI lenta e «chiedi a Sarah del modulo di fatturazione»; gli agenti no. Gli agenti non traggono vantaggio dai suggerimenti dell’IDE o da dashboard curate: hanno bisogno che gli errori compaiano come testo nel risultato di uno strumento. Una codebase può avere una buona DX e una AX scarsa.

Evitare: usare AX come sinonimo di DX: i due pubblici richiedono investimenti diversi.

Uso:

«L’agente scrive ottimo codice nel repository API e codice pessimo nel frontend.»

«Il repository API ha tipi rigorosi e una suite di test veloce; il frontend non ha né gli uni né l’altra e carica sempre quaranta skill. È una lacuna di AX, non un problema del modello.»

Un sistema di lavoro in cui le sessioni degli agent sono avviate da trigger — la creazione di una issue, una pianificazione, un errore CI, la conclusione di un’altra sessione — invece che da una persona. In questo modo più lavoro procede AFK e l’attenzione umana si concentra sulle decisioni di human-in-the-loop rimaste.

Senza una factory, ogni sessione inizia perché qualcuno l’ha avviata. Anche un lavoro completamente AFK aspetta che una persona apra la sessione, la indirizzi al ticket e la metta in moto. I team vogliono pubblicare più di quanto ciò consenta. Una factory elimina l’intervento umano nell’avvio delle sessioni, ma non necessariamente in ogni altra fase.

Trigger comuni e sessioni che avviano:

Una factory non deve coprire tutto il processo software. Un solo cron job che esegue un tipo di sessione e apre una PR verificabile è già una factory. È utile iniziare in piccolo: un ciclo ristretto produce PR piccole e simili, la cui revisione mostra quanto sia affidabile prima di ampliarlo.

Le persone possono partecipare in qualsiasi punto della factory: scrivere ed etichettare le issue che avviano le sessioni, approvare un piano prima dell’implementazione, fare revisione umana prima del merge. Decidere quali di queste scelte restano umane è la principale questione di progettazione. Una codebase, o una sua parte, in cui nessuno rivede ciò che produce la factory è una dark factory.

Uso:

«Chi ha corretto tutte le violazioni di `no-floating-promises`?»

«La factory. Il cron job sceglie una regola di lint ogni notte e apre una PR. Io la rivedo al mattino.»

Una base di codice, o una sua parte, in cui una software factory scrive codice che nessun essere umano legge. Non c’è revisione umana. Le persone possono comunque scrivere le issue che avviano il lavoro, ma nessuno legge il codice prodotto. Il nome deriva dalle fabbriche «lights-out», che producono senza persone in fabbrica.

Una dark factory è vibe coding applicato a un’area di codice, non a una singola modifica. Quando fai vibe coding, scegli di non leggere una modifica che hai richiesto, ma sai che esiste. In una dark factory, il team fa questa scelta una sola volta per l’intera area. Da quel momento nessuno richiede o vede ogni singola modifica: le modifiche arrivano alla velocità con cui i trigger avviano nuovo lavoro.

Il problema emerge quando qualcosa si rompe. Non sai che cosa è cambiato perché nessuno ha letto le modifiche. Devi fare debug di codice che nessuno del team ha letto. La causa può trovarsi in una qualsiasi delle numerose modifiche, ciascuna delle quali ha superato i controlli.

Gli controlli automatizzati e le revisioni automatizzate sono gli unici gate. Se non trovano un problema, il problema entra nel codice.

Evitare: definire «dark» una base di codice soltanto perché la factory funziona senza essere sorvegliata. Se le sessioni degli agent sono AFK e una persona esamina le loro PR, si tratta di una software factory, non di una dark factory.

Uso:

«Chi ha cambiato la logica dei nuovi tentativi nel servizio di fatturazione? Nessuno del team se lo ricorda.»

«Il servizio di fatturazione è una dark factory. Gli agent uniscono tutte le modifiche che superano la CI. Nessuno ha letto quella modifica.»