Il tuo CLAUDE.md sta peggiorando le cose

Il mio file di istruzioni globale è arrivato a 117 righe. Non l'ho scritto in un pomeriggio: è cresciuto per accumulo, una riga alla volta, e ogni riga è lì perché una volta l'agente ha fatto qualcosa che non doveva. Ha chiuso dicendo "dovrebbe funzionare" senza aver eseguito niente? Riga nuova: done means verified. Ha dato per buono un path senza controllarlo? Riga nuova: se un check costa un comando, eseguilo.

È il modo naturale di lavorare con questi strumenti. Vedi un comportamento sbagliato, scrivi la regola che lo impedisce. Il file cresce, e la sensazione è di stare stringendo il controllo.

Poi vai a leggere la documentazione di prompting che Anthropic ha pubblicato per Opus 5, e trovi scritto che una parte di quelle righe adesso ti fa danno.

La frase che nessuno sta citando

Il modello è uscito il 24 luglio, a 5 dollari per milione di token in input e 25 in output. Di quel rilascio si è parlato ovunque: benchmark, contesto lungo, i confronti di rito. La guida al prompting sulla piattaforma contiene però un paragrafo che non ha fatto il giro, e che vale più dei benchmark:

"Claude Opus 5 verifies its own work without being told to. If your prompt contains explicit verification instructions ('include a final verification step for any non-trivial task,' 'use a subagent to verify'), remove them: instructions like these cause over-verification on Claude Opus 5, and removing them reduces wasted tokens with no loss in quality."

Rimuovile. Non "riformulale", non "spostale": rimuovile. E poco più sotto, sull'autocorrezione:

"Claude Opus 5 catches and fixes its own mistakes well without prompting. Avoid instructing re-checks it already performs ('double-check your answer,' 're-verify before responding'); like verification instructions, these compound with the model's own behavior and add cost without improving results."

Il verbo chiave è compound. Le istruzioni non si sommano al comportamento nativo: lo moltiplicano. Chiedere di ricontrollare a un modello che già ricontrolla non produce un lavoro doppiamente accurato, produce un lavoro doppiamente pagato. La documentazione estende la stessa logica all'impalcatura dell'harness: "the same applies to legacy harness scaffolding that adds separate verification steps".

Chi ha passato l'ultimo anno a costruirsi un file di regole ha ottime probabilità di avere almeno una di quelle righe. Io ne avevo una.

Non tutte le righe che dicono "verifica" sono la stessa riga

Qui serve una distinzione che i docs non fanno esplicitamente, ma che cambia tutto quando vai a potare. Ho preso il mio file e l'ho passato riga per riga, e il risultato è meno drastico di quanto la citazione lasci pensare.

Le regole di reporting restano. "Done means verified. Never close with 'should work'. Show what you ran and what came back, not a claim." Questa riga non ordina al modello di rifare il lavoro: gli dice cosa può dichiarare. Non genera lavoro aggiuntivo, genera onestà nel resoconto. Nessun costo, e serve.

Le regole di verifica sul mondo esterno restano. "Se un check costa un comando, eseguilo — path, nomi, chiavi di config, versioni, cosa dice davvero una fonte." Anche questa non è auto-verifica: è andare a guardare un fatto invece di ricordarselo. È l'antidoto alle allucinazioni, non un doppione del comportamento nativo. I docs non la toccano.

Le regole di re-check meccanico vanno via. Nel mio file ce n'era una sola: "rileggi un artefatto dopo averlo modificato, prima di modificarlo di nuovo". Sembra prudenza. In realtà è una tool call a ogni giro che non compra niente. E c'è di peggio: contraddice direttamente l'ambiente. Il system prompt di Claude Code contiene già l'istruzione opposta, "Do NOT re-read a file you just edited to verify — Edit/Write would have errored if the change failed". Avevo scritto una regola che diceva all'agente di fare esattamente ciò che l'harness gli dice di non fare.

Il criterio che ne ho ricavato, e che puoi applicare stasera al tuo file: una riga che dice al modello cosa dichiarare va tenuta; una che gli dice di rifare qualcosa che già fa va cancellata. In mezzo, le verifiche su fatti esterni: quelle restano, perché non sono ridondanza, sono ancoraggio.

E qui arriva la parte scomoda

Se il discorso finisse così, la conclusione sarebbe comoda: i modelli migliorano, i prompt si accorciano, tutti contenti. Solo che la stessa settimana ho aperto la guida al prompting di GPT-5.2, e per i contesti ad alto rischio (legale, finanziario, compliance) la raccomandazione è di far ri-scansionare al modello la risposta in cerca di assunzioni non dichiarate e affermazioni non fondate, ammorbidendo poi il linguaggio troppo netto.

Cioè: un passo di verifica esplicito. Esattamente quello che Anthropic ti dice di togliere.

Non è una contraddizione da risolvere, ed è inutile chiedersi chi abbia ragione: hanno ragione entrambi sul proprio modello. Anthropic descrive un modello che verifica di suo e che quindi va lasciato lavorare; OpenAI descrive un contesto in cui il costo di un errore non dichiarato è talmente alto che un giro in più si paga da sé. Sono due tarature diverse, su due comportamenti nativi diversi.

La conseguenza pratica però è netta, e nessuno la sta dicendo: il file unico di istruzioni che serve tutti gli agenti ha smesso di funzionare. Se sullo stesso repository giri Claude Code e Codex, e sono sempre di più quelli che lo fanno, non puoi più avere un solo testo di regole condiviso, perché le due piattaforme ora chiedono cose opposte sullo stesso punto. Una vuole meno impalcatura, l'altra ne vuole di più in certi domini.

Non è un problema di formato. CLAUDE.md, AGENTS.md, GEMINI.md: la moltiplicazione dei nomi è sempre sembrata una guerra di standard noiosa. Il punto vero è emerso adesso, ed è che i contenuti stanno divergendo, non i nomi dei file. Un file per agente non è più duplicazione da evitare: sta diventando la cosa corretta da fare.

Le righe da cancellare stasera

Operativamente, se usi Claude Code su Opus 5, questo è quello che i docs dicono di togliere:

ogni istruzione che chiede un passo di verifica finale su task non banali;
ogni istruzione che chiede di delegare la verifica a un subagent;
ogni "ricontrolla la risposta", "ri-verifica prima di rispondere", "rileggi dopo aver scritto";
l'impalcatura dell'harness che aggiunge passi di verifica separati.

E questo è quello che invece manca nei file scritti per i modelli precedenti, perché risponde a comportamenti nuovi:

Un tetto sulla delega. Opus 5 apre subagent più prontamente dei modelli precedenti. Su lavoro grande e realmente indipendente è un guadagno; su task piccoli moltiplica costo e tempo, ed è esattamente il meccanismo che porta a conti da migliaia di dollari per una sessione. I limiti deterministici esistono e sono CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS, più max_budget_usd nell'SDK. Richiedono Claude Code 2.1.217 o superiore: se hai un SDK pinnato a una versione precedente, aggiornalo prima di puntarlo su Opus 5.

Una calibrazione della lunghezza. I file che il modello scrive su disco (report, documenti, riassunti) escono più lunghi che sui modelli precedenti. Se il tuo flusso produce documentazione, senza un vincolo esplicito ti ritrovi piani da trecento righe che ne dicevano novanta.

Un vincolo di scope. I docs lo dicono senza giri di parole: "Claude Opus 5 can also expand the scope of a task, adding steps that weren't requested". Molti file di regole contengono già la difesa dal problema opposto, quello di non tagliare il lavoro richiesto, perché è il comportamento che ci aveva infastidito per due anni. Ora serve anche l'altra metà.

Una nota sull'effort, che è la leva di costo più sottovalutata: low e medium vanno usati liberamente ovunque la qualità regga, tenendo xhigh per il lavoro agentico duro. E soprattutto, controintuitivo ma scritto nei docs: thinking attivo a effort basso rende meglio di thinking disattivato a costo simile. Se hai portato i default di effort da un modello precedente, rifà una passata sulle tue valutazioni invece di fidarti.

Il punto generale, che è più grande del file

C'è una ragione per cui questa storia sembra strana, ed è che ribalta il riflesso che abbiamo tutti: davanti a un modello nuovo, aggiungiamo istruzioni. Non ne togliamo mai. Cancellare una riga sembra rinunciare a un controllo, e nessuno ha voglia di scoprire nel modo peggiore quale riga teneva insieme la baracca.

Solo che il controllo non sta più lì. Quando il modello verifica da sé, si autocorregge da sé e decide da sé quando delegare, il file di istruzioni statiche smette di essere il punto in cui governi il comportamento. Diventa il posto dove accumuli attriti residui, e ogni riga che descrive un comportamento ormai nativo è, nel migliore dei casi, token sprecati a ogni singola sessione.

È lo stesso identico movimento che Wiener descriveva nel 1948 e che questo blog ha già raccontato salendo un gradino alla volta: dal prompt al contesto, dal contesto all'harness. Ogni volta il controllo si sposta di un livello verso l'esterno, e ogni volta il livello precedente va alleggerito, non irrobustito. C'è un gradino ulteriore, arrivato quest'estate, e merita un pezzo suo.

Nel frattempo la cosa da fare è piccola e concreta. Apri il tuo file di istruzioni, cerca le righe che ordinano di verificare, e per ciascuna chiediti se sta dicendo al modello cosa dichiarare o cosa rifare. Le prime restano. Le seconde le stai pagando due volte.

Il mio file è passato da 117 righe a 120: una tolta, due aggiunte. Non è la potatura drastica che la citazione di Anthropic lascerebbe immaginare, ed è il motivo per cui vale la pena farla a mano invece di cancellare a manate. Ma quella riga in meno era la sola che stesse attivamente litigando con l'ambiente in cui gira.

Aggiungere è facile. Il lavoro vero, adesso, è sapere cosa togliere.

Fonti: