Quando l'IA sembra funzionare — Gustavo Teixeira Cuco

La maggior parte dei fallimenti dell'IA è evidente. Il modello inventa un fatto. Interpreta male un prompt. Produce qualcosa di chiaramente sbagliato. Lo si nota, lo si corregge, si va avanti.

Il fallimento che voglio descrivere è diverso. L'IA ha consegnato file. Ha riempito cartelle. Sembrava produttiva. Ed era completamente sbagliata — non perché ha mentito, ma perché ha agito prima di capire.

Il contesto che tutti danno per caricato

A gennaio 2026 ho costruito un template di governance per tutti i miei repository tecnici — un insieme strutturato di istruzioni, regole di base e bozze di documentazione che ogni nuovo repository dovrebbe ereditare. Il template vive nel proprio repository GitHub. Ogni file ha uno scopo. Il SYSTEM_PROMPT.md spiega la struttura completa. Il CLAUDE.md definisce la politica di caricamento del contesto: quali documenti leggere, in quale ordine, per quale tipo di attività.

La settimana scorsa ho chiesto a Claude Code di applicare quel template a un nuovo repository.

Non ha letto il template. È andato dritto a creare file.

Il risultato sembrava corretto — struttura delle cartelle, file di documentazione, convenzioni di denominazione. Ma aveva saltato quattro documenti che il SYSTEM_PROMPT.md richiedeva esplicitamente esistessero, anche solo come bozze. Aveva deciso, sulla base della memoria di sessione di un progetto precedente, quali documenti "si applicavano" a questo. Aveva sostituito la lettura delle istruzioni con il riconoscimento di pattern.

La sessione è terminata. Sono andato avanti. Ho scoperto il problema solo quando sono tornato e ho messo in discussione un file specifico che mancava.

Cosa si è davvero rotto

Il fallimento ha un'anatomia precisa:

L'IA non ha letto le istruzioni prima di agire. Quando ho detto "applica il template", il primo passo corretto era aprire il SYSTEM_PROMPT.md e il CLAUDE.md del repository del template. Ha saltato questo passo e ha agito in base a ciò che ricordava da sessioni precedenti.
Ha assunto che la conoscenza pregressa fosse aggiornata. I template cambiano. Le regole evolvono. Ciò che il modello ricordava da una sessione di tre settimane prima non corrispondeva a ciò che il documento diceva oggi. Ricordare un pattern non è la stessa cosa che leggere uno stato.
Ha preso decisioni di ambito senza chiedere. Ha concluso che alcuni documenti non si applicavano a questo repository. Era un giudizio che non aveva l'autorità di esprimere — le istruzioni dicevano esplicitamente che tutti i documenti dovevano esistere, anche se contrassegnati come N/A.
Il risultato era abbastanza plausibile da superare una revisione rapida. Questa è la parte critica. Un repository con dei file sembra un repository configurato. L'assenza di quattro documenti bozza è invisibile finché non si legge la specifica.

Lo schema si generalizza

Non è un fallimento specifico di Claude. È una modalità di fallimento intrinseca al modo in cui gli assistenti IA operano nei flussi di lavoro agentici.

Quando si dà a un'IA un'istruzione di alto livello — "applica questo template", "configura questa integrazione", "migra questa configurazione" — agirà sul contesto più disponibile: ciò che può inferire dallo stato attuale dei file, ciò che ricorda dall'inizio della sessione, ciò con cui l'istruzione corrisponde per pattern derivato dall'addestramento. Leggere la documentazione autorevole è un atto deliberato e sequenziale. Non avviene automaticamente a meno che non venga integrato nel flusso di lavoro.

Il divario tra "l'IA ha capito lo spirito del compito" e "l'IA ha letto la specifica autorevole" è dove vivono gli errori silenziosi.

In termini di prodotto: il tuo assistente IA sta ottimizzando per il completamento del compito, non per la correttezza rispetto alla specifica. Non sono la stessa cosa.

Cosa ho cambiato

Due interventi, entrambi strutturali:

Primo: Ho aggiunto una regola alla memoria persistente — prima di applicare qualsiasi template o pattern esterno, leggere prima i file di istruzioni di quel repository. Sempre. Non come suggerimento, ma come primo passo obbligatorio.

Secondo: Sto costruendo una skill /read-context — un controllo preliminare che viene eseguito prima di qualsiasi attività di applicazione del template. Legge il SYSTEM_PROMPT.md, il CLAUDE.md e il documento delle regole di base, poi riassume ciò che ha trovato prima di procedere. L'IA non può saltare questo passo perché è il primo passo.

La correzione più profonda consiste nel rendere il comportamento corretto il percorso di minor resistenza. Se il flusso di lavoro richiede di leggere prima di agire, la modalità di fallimento richiede sforzo per riprodursi.

Cosa significa questo se stai costruendo con l'IA

L'assunzione che "l'IA sa cosa intendo" è comoda e di solito innocua. Finché non lo è più.

I casi in cui si rompe sono proprio quelli in cui la posta in gioco è più alta: integrare un nuovo repository in una struttura di governance, migrare una configurazione critica, applicare un template di conformità. Compiti in cui un risultato sbagliato ma plausibile è più pericoloso di un errore evidente.

La soluzione non è un prompt migliore sul momento. È costruire flussi di lavoro in cui l'IA è costretta a leggere la fonte autorevole prima di agire — senza affidarsi alla memoria, senza inferire dal contesto, senza fare corrispondenza di pattern da sessioni precedenti.

La correttezza rispetto alla specifica è una proprietà del flusso di lavoro, non del modello.

Qual è il tuo meccanismo di forzatura?

Se stai integrando l'IA in flussi di lavoro tecnici con posta in gioco reale, quale meccanismo la costringe a leggere la specifica prima di agire — invece di assumere che sappia già?

Fonti

Anthropic, Claude system prompts and persistent memory behaviour — claude.ai/docs, 2025
Andrew Ng, Agentic AI Design Patterns — deeplearning.ai, 2024
Personal incident log — gtc-portfolio governance template, March 2026