Come dare contesto a Claude Code: la logica di business, non solo le convenzioni

Che cosa vuol dire «contesto» per un agente di codice?

Tutto quello che il modello deve sapere del tuo sistema e che non può ricavare dal codice che ha davanti. Anthropic chiama questa disciplina context engineering. Birgitta Böckeler, che sul sito di Martin Fowler scrive di agenti di codice, ne cita la definizione più asciutta che circoli: «Il context engineering consiste nel curare ciò che il modello vede, così da ottenere un risultato migliore». Quando l'agente lavora su un prodotto vero, quel contesto si presenta su tre livelli.

Tutte le guide al CLAUDE.md parlano del primo livello. È sul secondo e sul terzo, però, che un errore dell'agente costa soldi, ed è lì che nessuno scanner guarda: un rimborso che accredita troppo è codice perfettamente valido.

Questa classe di falle la trattiamo in falle di logica di business nel codice generato dall'AI. Qui ci occupiamo di prevenirla alla fonte, cioè di fare in modo che l'agente conosca la regola mentre scrive.

Quali sono i limiti di CLAUDE.md, AGENTS.md e skill?

Ognuno è nato per un compito preciso, e quel compito lo svolge. Nessuno, però, è stato pensato per portare le regole di business di un'azienda fino al momento della modifica. Ecco dove si ferma ciascuno, detto con le parole di chi lo produce.

CLAUDE.md: letto una volta, seguito quando torna comodo

La documentazione di Anthropic non gira intorno alla questione. I file CLAUDE.md vengono caricati «all'inizio di ogni conversazione» e «Claude li tratta come contesto, non come configurazione imposta». La stessa pagina chiede di puntare a «meno di 200 righe per file CLAUDE.md», perché «i file più lunghi consumano più contesto e riducono il rispetto delle istruzioni». Duecento righe, quindi, per i comandi di build, le convenzioni e tutte le regole di business che hai.

C'è di più: «se due regole si contraddicono, Claude può sceglierne una arbitrariamente», e intanto nessuno confronta il file con il codice che dovrebbe descrivere. Gli effetti li raccontano gli utenti nell'issue tracker. La issue #2901, aperta a luglio 2025 e arrivata a 31 commenti, lo dice così: «Claude Code viola spesso istruzioni esplicite di progetto e dell'utente definite nei file CLAUDE.md». La issue #33603, tuttora aperta, porta questo titolo: «Regole rigide del CLAUDE.md e istruzioni di memoria persistente ignorate sistematicamente».

AGENTS.md: lo stesso file, condiviso da più agenti

AGENTS.md è il formato aperto che leggono Codex, Cursor, Copilot e altri, adottato da oltre 60.000 progetti open source. Il suo stesso sito ne riassume la natura: «AGENTS.md è semplicemente Markdown standard», «un README per gli agenti». Lo standard stabilisce dove si trova il file, non se qualcuno lo rispetta.

E l'unico test rigoroso fatto finora non è lusinghiero. A febbraio 2026 Thibaud Gloaguen, Martin Vechev e altri tre coautori hanno pubblicato Evaluating AGENTS.md: i file di contesto «in generale non migliorano il tasso di successo dei task, mentre aumentano il costo di inferenza in media di oltre il 20%». Le istruzioni che contengono venivano «seguite bene», e gli autori salvano i file quando servono a «specificare pratiche di codice non standard», mentre le panoramiche del repository «non servono».

A questo si sommano tre limiti pratici:

• Claude Code lo salta se trova un CLAUDE.md. Con entrambi i file nel repository, per impostazione predefinita Claude Code legge «solo i tuoi file CLAUDE.md». Un team che li mantiene tutti e due si ritrova l'AGENTS.md ignorato da Claude Code, mentre gli altri agenti lo leggono.
• Codex ci mette un tetto. Per impostazione predefinita, Codex smette di aggiungere file di istruzioni quando la loro dimensione complessiva raggiunge i 32 KiB.
• Copilot lo vuole breve. Il prompt che GitHub suggerisce per scrivere le istruzioni precisa che «non devono superare le 2 pagine» e che «non devono essere specifiche di un task». Ma una regola di business è specifica di un task per sua stessa natura.

Skill: caricate quando l'agente ci pensa

Una skill è una cartella di istruzioni e script che si carica soltanto quando viene usata. La documentazione di Anthropic sulle skill spiega come sceglie Claude: legge la descrizione della skill per «decidere quando applicare la skill». Una regola confezionata come skill, di conseguenza, si applica solo se l'agente riconosce il momento giusto.

La stessa documentazione elenca i modi in cui quel riconoscimento salta. La descrizione viene «troncata a 1.536 caratteri». Quando le skill installate sono tante, Claude Code «scarta alcune descrizioni per rientrare nel budget di caratteri dell'elenco, eliminando le parole chiave di cui Claude ha bisogno per abbinare la tua richiesta». E dopo che una sessione lunga è stata compattata, «le skill più vecchie possono sparire del tutto».

Per le procedure le skill sono eccellenti. Come veicolo per regole che devono valere ogni volta, invece, dipendono proprio dall'unica cosa da cui stai cercando di non dipendere. C'è poi un rischio a parte, perché una skill scritta da altri esegue codice nella tua sessione: ne parliamo in le skill di Claude Code sono sicure?.

Quello che nessuno dei tre fa

Tutti e tre danno per scontato che la parte difficile sia già stata fatta. Nessuno dei tre:

• trova le tue regole. Ognuno contiene solo ciò che qualcuno si è ricordato di mettere per iscritto.
• sa quale regola vale per questa modifica. Si caricano per sessione, per percorso o per descrizione, mai in base a quello che fa davvero il codice in corso di scrittura.
• si accorge quando una regola non corrisponde più al codice. Un valore superato resta nel file finché a qualcuno non capita di rileggerlo.
• controlla il risultato. Se la regola sia stata rispettata o no, è affare della code review.
• funziona allo stesso modo su tutti i tuoi agenti. Un team che usa cinque agenti mantiene cinque dialetti.

Perché l'agente perde la regola prima di scrivere?

Perché l'attenzione di un modello non è uniforme, e una regola letta all'inizio, quando finalmente serve, è ormai lontana dalla modifica. Il team di engineering di Anthropic lo dice senza mezzi termini: il contesto «va trattato come una risorsa finita, con rendimenti marginali decrescenti». E all'effetto dà un nome, context rot: «man mano che il numero di token nella finestra di contesto aumenta, la capacità del modello di richiamare con precisione le informazioni di quel contesto diminuisce».

Lavori indipendenti lo hanno misurato. Chroma ha testato 18 modelli nel suo rapporto Context Rot e ha trovato che «le prestazioni dei modelli peggiorano all'aumentare della lunghezza dell'input, spesso in modi sorprendenti e non uniformi». Già prima, lo studio Lost in the Middle aveva mostrato che le prestazioni «peggiorano in modo significativo quando i modelli devono accedere a informazioni rilevanti collocate a metà di contesti lunghi». E IFScale, che accumula istruzioni su istruzioni, ha rilevato che con 500 istruzioni simultanee «anche i migliori modelli di frontiera arrivano solo al 68% di accuratezza».

Sulla sicurezza, nessun trattamento di favore. Nel benchmark SusVibes, il 57% delle soluzioni prodotte da SWE-Agent con Claude Sonnet 4 era funzionalmente corretto, ma solo l'11,8% era sicuro, e «arricchire la richiesta di funzionalità con indicazioni sulle vulnerabilità» non ha cambiato le cose. Dire a un agente di fare attenzione non equivale a dargli le tue regole.

La nostra misura è partita dal caso più difficile, quello in cui l'agente ha già una sua risposta plausibile. Una sezione di regole realistica nel CLAUDE.md ha prodotto 7 dettagli di regola esatti su 55: esattamente quanti ne ha prodotti l'assenza di qualunque file. Il protocollo completo è in Claude Code segue il CLAUDE.md?.

A spiegarlo sono due forze. La prima è la diluizione: alla trentesima modifica il file è un frammento vecchio, sepolto sotto decine di migliaia di token di codice e di output. La seconda è l'abitudine: il codice che l'agente ha davanti gli mostra come si fanno le cose qui, e per giunta compila.

Ecco come si traduce su un singolo prompt. Il 27 settembre 2026 abbiamo chiesto a Claude Code, con il modello Haiku, di scrivere una funzione di rimborso in un repository vuoto: una volta senza nessuna regola, una volta con l'hook descritto più avanti, caricato con la nostra regola sui rimborsi. Un run per parte, quindi un'illustrazione e non una misura.

Le righe che la regola ha cambiato, nella seconda esecuzione:

if (amountCents > availableForRefund) {
  throw new RefundError("REFUND_EXCEEDS_CAPTURED");
}
order.refundedCents += amountCents;
await audit.log("refund.created", {
  orderId: order.id, amountCents, actorId,
});

Sono codice ragionevole tutte e due, ma solo una è il tuo codice. Il comportamento giusto con i dettagli sbagliati: è lo scarto che sfugge a chi fa la review e su cui si rompe chi integra la tua API.

CLAUDE.md, regole, skill, MCP o hook: chi porta che cosa?

Ogni meccanismo raggiunge il modello in un momento diverso, ed è il momento a stabilire a che cosa serve.

Quella che conta è la seconda colonna. Un file, una skill o un tool MCP dipendono tutti da qualcosa che è successo prima, oppure dalla scelta del modello di andare a guardare. Un hook no: lo lancia l'harness, che il modello ci pensi o meno.

Le regole legate a un percorso stanno a metà strada. La documentazione di Anthropic dice che «si attivano quando Claude legge file che corrispondono al pattern, non a ogni uso di un tool». Rispetto a un unico file grande è un progresso vero, ma la chiave resta il percorso, non l'operazione.

Le skill eseguono codice che arriva dal repository di qualcun altro: per il lato sicurezza, vedi le skill di Claude Code sono sicure?.

Come si consegna una regola nel momento della modifica?

Con un hook PreToolUse sui tool di scrittura, che cerca le regole relative al file in corso di scrittura e le restituisce come additionalContext. Servono tre file, e il primo registra l'hook in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/rules-at-edit.mjs\"" }
        ]
      }
    ]
  }
}

Poi ogni regola diventa un piccolo file in .claude/edit-rules/, con sulla prima riga i percorsi a cui si applica:

applies-to: src/billing/**, src/api/refunds/**
Refunds: never refund more than the captured amount.
Answer 422 with the code REFUND_EXCEEDS_CAPTURED, never a prose message.
Every refund writes an audit event: audit.log("refund.created", { orderId, amountCents, actorId }).

Infine l'hook vero e proprio, .claude/hooks/rules-at-edit.mjs, che richiede Node 22.5 o successivo per via di path.matchesGlob:

import { readFileSync, readdirSync } from "node:fs";
import path from "node:path";

const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
const input = JSON.parse(readFileSync(0, "utf8"));
const file = path.relative(root, input.tool_input?.file_path ?? "");
const dir = path.join(root, ".claude/edit-rules");

const rules = readdirSync(dir)
  .map((name) => readFileSync(path.join(dir, name), "utf8"))
  .filter((text) => {
    const globs = text.match(/^applies-to:\s*(.+)$/m)?.[1] ?? "";
    return globs.split(",").some((g) => path.matchesGlob(file, g.trim()));
  });

if (rules.length > 0) {
  // JSON, not plain text: on PreToolUse, Claude Code only reads additionalContext.
  process.stdout.write(JSON.stringify({
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      additionalContext: `Rules for ${file}:\n\n${rules.join("\n---\n")}`,
    },
  }));
}

È la configurazione che sta dietro la colonna di destra del confronto sui rimborsi, più in alto. Claude Code colloca il contesto degli hook «accanto al risultato del tool»: l'agente legge la regola insieme all'esito della sua scrittura su quel file, e corregge sul momento. Nel nostro run ha scritto la funzione, ha letto la regola e ha risposto «Ho aggiornato la funzione per», prima di elencare il codice di errore e l'evento di audit.

Gli altri agenti parlano ciascuno il proprio dialetto. Codex di OpenAI documenta la stessa forma su PreToolUse: «per aggiungere contesto visibile al modello senza bloccare, restituisci hookSpecificOutput.additionalContext». In Cursor il preToolUse può consentire, negare o riscrivere una chiamata, mentre l'hook postToolUse aggiunge additional_context «dopo il risultato del tool». Le istruzioni di repository di GitHub Copilot, infine, circoscrivono un file con un pattern applyTo, e l'AGENTS.md più vicino nell'albero ha la precedenza.

Fin dove arriva la versione fai da te?

Si ferma alle regole. L'hook sistema il momento, e conviene installarlo oggi stesso, ma lascia in piedi il resto dell'elenco visto sopra: le regole continuano a uscire dalla memoria di qualcuno e continuano a invecchiare, nessuno controlla se sono state rispettate, e ogni agente del team ha bisogno della sua versione. In più aggiunge un limite tutto suo, perché un percorso non è un'intenzione: un rimborso si può scrivere anche in utils.ts, e un glob non distingue un rimborso da una funzione di formattazione. Superate le dieci regole e il singolo agente, tenere in piedi tutto questo a mano diventa un lavoro a sé.

Com'è fatto il metodo completo?

Comincia là dove ogni file si ferma, cioè da zero regole scritte. È il metodo che CybeDefend applica con VibeDefend, dalla codebase fino al diff, pensato per un team di sviluppo e non per il portatile di una persona sola. Le regole stanno in un unico posto per progetto, l'agente di ogni sviluppatore riceve lo stesso insieme verificato, e ciascun passo esiste perché esiste uno dei limiti visti sopra.

Estrai le regole dal tuo codiceUna persona le verifica una per unaConsegnate alla modificaControllate alla fine

Passo 1: estrai le regole dal tuo codice

Le tue regole, il tuo codice le contiene già, scritte sotto forma di ripetizione. Una volta collegato e analizzato un repository, un estrattore ne legge il grafo del codice e va a caccia di cinque tipi di regolarità:

• Pattern di presenza: un campo o una chiamata che quasi ogni istanza porta con sé. Ogni entità ha un organizationId, ogni scrittura su orders chiama il logger di audit.
• Insiemi di valori: i nomi letterali che il tuo codice usa per stati, ruoli e codici di errore. È la tua nomenclatura, e un agente che si inventa un sesto stato d'ordine rompe tutti i consumatori degli altri cinque.
• Co-occorrenze: guardie e decorator che viaggiano sempre insieme, come un controllo di autenticazione e un rate limit.
• Chiamate obbligatorie prima delle operazioni sensibili: controlli dei permessi, filtro per tenant, rate limit, feature flag.
• Convenzioni a cui un modello dà un nome partendo da gruppi di codice simile, con l'elenco dei casi anomali.

Ogni proposta arriva con le sue prove, cioè dove è stato trovato il pattern e quante volte, e con un grado di confidenza. La parte più utile sono proprio i casi anomali. Un endpoint senza filtro per tenant, in una codebase dove altri quaranta ce l'hanno, o è un'eccezione voluta da qualcuno o è una falla che nessuno ha notato: è esattamente il punto in cui logica di business e sicurezza si incontrano.

Passo 2: fai verificare ogni regola a una persona

L'estrazione propone, non decide mai. Un pattern può essere un'abitudine e non una regola, e una regola è una policy: chi la scrive orienta ogni agente del team. Per questo i file di istruzioni sono una superficie d'attacco a pieno titolo.

In VibeDefend ogni proposta si accetta, si modifica o si scarta dalla dashboard, oppure dall'interno dell'agente quando si apre una sessione. Una regola suggerita dall'agente stesso viene rifiutata finché non l'hai confermata tu. Una volta alla settimana un controllo di deriva propone un aggiornamento quando il codice si allontana da una regola accettata, ed è così che le regole restano vere senza che qualcuno debba mantenere un file.

Passo 3: consegna la regola giusta alla modifica

È l'hook della sezione precedente, con una ricerca delle regole pertinenti al posto dei glob. Prima di ogni scrittura, il percorso del file e l'inizio del codice che sta per essere scritto partono come intento, e come contesto per quel file tornano indietro fino a cinque regole di business e cinque regole di sicurezza pertinenti a quella modifica. L'installer lo collega a Claude Code, Cursor, Codex, Windsurf e GitHub Copilot in VS Code, ognuno con i limiti del proprio sistema di hook.

Consegnare una regola informa l'agente, non lo costringe. Per ciò che non deve mai accadere c'è una guardia separata, che controlla ogni comando prima dell'esecuzione e può bloccarlo. La regola nel contesto è un suggerimento forte, il controllo vero è la guardia sull'azione, e preferiamo dire apertamente quale delle due è il controllo.

Passo 4: controlla il risultato in fondo alla catena

Tre controlli, dalla singola sessione fino all'architettura:

• A fine sessione, una revisione si pone una sola domanda: questo lavoro ha fatto emergere una regola duratura che non è scritta da nessuna parte? Ne propone al massimo una, spesso nessuna, e senza il tuo sì non registra niente.
• Prima del commit, il diff viene scansionato alla ricerca di vulnerabilità, configurazioni errate dell'infrastruttura e segreti, così l'agente li corregge nella stessa sessione.
• Sulla logica di business in sé, BLSA, la nostra Business Logic Security Analysis, legge tutta l'architettura segmento per segmento per trovare quello che nessun pattern può trovare: un rimborso che si può rieseguire, un tenant che può leggere i dati di un altro, dati personali che escono da un export, un'operazione non idempotente. BLSA è un filone di ricerca condotto con il CNRS e il laboratorio CRIStAL, già attivo con alcuni design partner ma non ancora disponibile per tutti. Vedi che cosa cerca nel fintech.

Messe una accanto all'altra, le due strade si distinguono meno per l'agente che per il team che gli sta intorno.

Che cosa cambia quando la regola arriva al momento della modifica?

La maggior parte delle regole smette di perdersi per strada. Il nostro studio controllato ha fatto passare 30 ticket di sviluppo attraverso tre agenti autonomi, su una sola codebase e con un solo modello. Nei 19 task della prima fase, l'agente senza regole e quello con un file di regole realistico hanno implementato alla lettera, ciascuno, 7 dettagli di regola su 55. L'agente che riceveva le regole al momento della modifica ne ha implementati 46 su 53.

13%

esatti senza nessuna regola (7 su 55)

13%

esatti con una sezione di regole realistica nel CLAUDE.md (7 su 55)

87%

esatti con la regola consegnata alla modifica (46 su 53)

Va detto che cosa misura e che cosa no. Misura la consegna alla modifica: le 49 regole le abbiamo scritte noi, non sono state estratte, quindi sulla qualità dell'estrazione per ora non dice nulla. Una sola codebase, un run per braccio e per task, con la valutazione affidata a revisori in cieco che sono modelli.

E contiene il suo stesso controesempio. In un task una regola è stata consegnata tredici volte e l'agente l'ha violata lo stesso, ed è per questo che la guardia esiste. Il protocollo e ogni singolo numero sono nello studio.

Da dove cominci questa settimana?

Da dieci regole, non da una piattaforma.

1. Elenca dieci regole che il tuo team ripete in code review, cioè i commenti che hai scritto più di due volte.
2. Smistale con una sola domanda: un ingegnere competente, appena arrivato nel team, potrebbe indovinarla? Se sì, va nel CLAUDE.md. Se no, deve raggiungere l'agente al momento della modifica.
3. Circoscrivi ciò che è legato a una directory con .claude/rules/ e un campo paths.
4. Aggiungi l'hook qui sopra per le regole arbitrarie, e verifica che restituisca JSON.
5. Tutto ciò che non deve mai accadere trasformalo in una regola di deny o in una guardia, non in una frase.
6. Mettilo alla prova dove cede: una funzionalità che tocca una regola, trenta turni dopo l'inizio di una sessione.

Quando l'elenco non ti sta più in testa, è arrivato il momento di estrarlo invece di scriverlo.

Domande frequenti

Come si dà a Claude Code il contesto della propria codebase?

Su tre livelli. Comandi di build, struttura e convenzioni vanno in un CLAUDE.md breve, che Claude legge all'inizio di ogni sessione. Le regole specifiche di una directory vanno in .claude/rules/ con un campo paths, così si caricano quando Claude legge un file corrispondente. Le regole di business e di sicurezza che il modello non può indovinare, come codici di errore, soglie e formati di audit, vanno consegnate nel momento della modifica, con un hook PreToolUse che restituisce additionalContext in JSON.

Che differenza c'è tra skill e hook in Claude Code?

Una skill la carica Claude, se lo decide; un hook lo esegue Claude Code, che Claude lo decida o no. La descrizione di una skill sta nel contesto e il suo corpo si carica quando tu o Claude la invocate: per questo funziona bene per le procedure. Un hook scatta su un evento, come l'avvio di una sessione, un prompt o la chiamata a un tool, ed è quindi il posto giusto per una regola che deve raggiungere l'agente ogni volta, o per bloccare un comando.

Regole o skill in Claude Code: quando usare cosa?

Le regole sono istruzioni, le skill sono procedure. I file in .claude/rules/ entrano nel contesto senza condizioni, oppure quando Claude legge un file che corrisponde al loro pattern paths. Una skill impacchetta una procedura in più passaggi, con eventuali script, e si carica solo quando viene usata. Usa le regole per ciò che deve essere sempre vero del codice, e le skill per il modo di portare a termine un compito.

Claude Code ha un sistema di regole?

Sì. I file Markdown in .claude/rules/ vengono caricati come istruzioni, anche nelle sottocartelle, un argomento per file. Una regola con un campo paths nel frontmatter si carica solo quando Claude legge un file che corrisponde a uno dei suoi pattern glob; senza quel campo, si carica in ogni sessione. Le regole personali in ~/.claude/rules/ valgono per tutti i progetti sulla tua macchina.

A che cosa servono gli hook di Claude Code?

A tutto ciò che deve succedere ogni volta, perché lì sono l'unico meccanismo affidabile. La documentazione di Anthropic dice che per bloccare un'azione «a prescindere da ciò che Claude decide» bisogna usare un hook PreToolUse, non un'istruzione. Gli hook possono anche aggiungere contesto in un momento preciso, per esempio le regole del file che si sta scrivendo, cosa che un file letto all'avvio della sessione non può fare.

Il mio hook PreToolUse gira, ma Claude ne ignora l'output: perché?

Perché il testo semplice stampato da un hook PreToolUse finisce nel log di debug, non al modello. Claude Code aggiunge al contesto lo stdout in testo semplice solo per UserPromptSubmit, UserPromptExpansion, SessionStart e PostModelSwitch. Restituisci invece un JSON, con hookSpecificOutput.hookEventName impostato a PreToolUse e il tuo testo in additionalContext. La differenza l'abbiamo verificata su Claude Code 2.1.282, il 27 settembre 2026.

Che cos'è il context engineering per gli agenti di codice?

È decidere quali informazioni entrano nella finestra di contesto del modello, e quando, perché possa svolgere bene il compito. Per un agente di codice conta meno scrivere un prompt più lungo e molto di più il tempismo: i fatti stabili all'avvio della sessione, le regole pertinenti nel momento della modifica, e nient'altro a contendersi l'attenzione. Il team di engineering di Anthropic usa il termine per l'intera disciplina.

Claude Code può scrivere il CLAUDE.md da solo?

Sì: /init analizza la tua codebase e scrive un primo CLAUDE.md con i comandi di build, le istruzioni per i test e le convenzioni che individua. Per il primo livello di contesto è un buon punto di partenza, ma estrarre le regole di business è un'altra cosa. Lo studio Evaluating AGENTS.md ha trovato che i file di contesto generati da un modello in generale non miglioravano il successo dei task. E un file generato arriva comunque una volta sola, all'avvio della sessione, e ha comunque bisogno di qualcuno che lo verifichi.

Claude Code legge il file AGENTS.md?

Sì, se non c'è un CLAUDE.md. Secondo la documentazione di Anthropic, Claude Code legge AGENTS.md come istruzioni del progetto quando nella directory di lavoro, o più in alto, non ci sono né CLAUDE.md né CLAUDE.local.md. Se invece ci sono entrambi i file, per impostazione predefinita legge soltanto i tuoi CLAUDE.md, a meno che il CLAUDE.md non importi AGENTS.md o che tu non cambi l'impostazione. In un caso come nell'altro il meccanismo è lo stesso, un file caricato all'avvio della sessione, con gli stessi limiti per le regole che servono trenta modifiche dopo.