Context engineering, memoria e pianificazione
Più contesto non significa automaticamente più qualità. Questo modulo insegna a selezionare ciò che cambia una decisione, a mantenere istruzioni di progetto concise e a verificare ciò che sopravvive tra sessioni.
Cosa affronti, passo dopo passo
Quattro fonti pratiche del contesto
Quando lavori con un agente, il contesto non è un unico mucchio di informazioni. È l'insieme di ciò che l'agente può usare per decidere il prossimo passo. Separarne i tipi ti aiuta a capire cosa fornire, cosa verificare e cosa invece lasciare fuori.
Qui usiamo quattro fonti pratiche, non un elenco completo di tutto ciò che può entrare nel contesto: la richiesta corrente, i file e gli output osservati, le istruzioni persistenti e la memoria. `CLAUDE.md` contiene regole scritte da te; l’auto memory contiene appunti che Claude conserva fra sessioni. Confonderli produce regole temporanee che diventano permanenti o ricordi vecchi trattati come fatti attuali.
Ogni elemento dovrebbe rispondere a una domanda: serve per decidere adesso? Rimarrà vero la prossima settimana? Può essere verificato nel repository? Contiene dati che non dovrebbero essere condivisi?
Devi mostrare EUR o USD accanto al totale. Il repository contiene un modello Invoice, una funzione di formattazione e una vecchia nota che parla soltanto di euro.
- Scrivi la richiesta corrente in una frase verificabile: «mostra la valuta salvata nella fattura, senza cambiare gli importi esistenti».
- Apri modello, migrazioni, formattatore e test: scopri che il campo currency esiste già e che USD è già ammesso dal database.
- Leggi le istruzioni stabili: per il denaro il progetto richiede Intl.NumberFormat e vieta conversioni implicite. Tratta la vecchia nota sull'euro come memoria da verificare, non come verità.
- Costruisci il contesto finale con quei file, il vincolo sul formato e due fatture di prova; escludi dump clienti e chiavi del servizio pagamenti.
Risultato: L'agente può fare una modifica piccola e coerente: usa il campo già disponibile, rispetta la convenzione del progetto e non assume che tutte le fatture siano in euro.
Istruzioni di progetto che aiutano davvero
Le istruzioni di progetto sono un piccolo manuale operativo per chi interviene sul codice. Non devono raccontare tutta la storia del prodotto: devono evitare gli errori che una semplice lettura dei file non rende evidenti.
Un buon file di istruzioni indica comandi affidabili, confini architetturali, convenzioni non ovvie e Definition of Done. Evita biografie del progetto, opinioni duplicate e informazioni già facili da leggere dai file.
Scrivi regole positive e verificabili: «esegui pytest -q» è più operativo di «fai attenzione ai test». Ricorda però che `CLAUDE.md` guida il modello, non è un firewall: una regola che deve scattare sempre va resa tecnica con permessi, hook o test. Aggiungi eccezioni soltanto quando esiste un motivo reale e rimuovi una regola quando non è più vera.
Nel sito, alcune persone modificano direttamente `messages.generated.json`; alla build successiva il generatore sovrascrive tutto e la traduzione scompare.
- Conferma dai file di build che `messages.generated.json` è davvero generato e individua `locales/source.it.json` come fonte modificabile.
- Aggiungi un'istruzione positiva: modifica soltanto il file sorgente, poi esegui `npm run i18n:build`; non limitarti a scrivere «non toccare i file sbagliati».
- Indica la prova: `git diff` deve mostrare sia la sorgente sia il file generato, e `npm run i18n:check` deve terminare senza chiavi mancanti.
- Prova l'istruzione con una nuova etichetta e fai leggere il testo a una persona che non conosce il generatore; se deve chiedere quale file aprire, la regola è ancora incompleta.
Risultato: La prossima modifica segue un percorso ripetibile e lascia una prova. Il file di istruzioni contiene una convenzione non ovvia, non una copia della documentazione generale.
Compattare senza perdere il contratto
Compattare significa trasformare una lunga conversazione in un handoff breve. L'obiettivo non è ricordare ogni frase: è conservare il contratto operativo necessario per riprendere senza reinterpretare il lavoro.
Quando una conversazione cresce, una sintesi riduce il volume ma può eliminare dettagli. Prima della compattazione identifica decisioni, vincoli, file modificati, prove ottenute e lavoro residuo. Dopo, controlla che questi elementi siano ancora espliciti.
Una nuova sessione dovrebbe poter riprendere dal repository e da un breve handoff, non da una fiducia cieca nella memoria. Dopo `/compact`, Claude Code rilegge il `CLAUDE.md` alla radice; istruzioni annidate e regole legate a un percorso tornano quando riapri i file pertinenti. Lo stato dei file resta comunque la fonte primaria per ciò che è effettivamente cambiato.
Hai isolato un doppio addebito quando l'utente preme due volte «Paga». La sessione è lunga e devi interrompere prima della verifica completa.
- Registra il contratto: una sola richiesta di pagamento per ordine, nessun cambiamento al flusso di rimborso e nessun log con dati della carta.
- Annota la decisione: usare una chiave di idempotenza derivata dall'ordine; segnala che il tentativo di disabilitare soltanto il pulsante è stato scartato perché non copre richieste duplicate dalla rete.
- Elenca i file realmente modificati e la prova disponibile: il nuovo test falliva prima della patch ed è verde dopo; il test end-to-end non è ancora stato eseguito.
- Alla ripresa confronta handoff, `git status` e diff, poi esegui il controllo mancante in un ambiente di prova prima di dichiarare concluso il lavoro.
Risultato: La nuova sessione parte dal rischio ancora aperto, non ricostruisce tutta la discussione e non confonde un test unitario riuscito con una verifica completa del pagamento.
Piano prima dell’esecuzione
Non ogni lavoro merita un piano enorme. Cambiare un’etichetta può richiedere tre righe; cambiare dati letti da due versioni dell’app richiede fasi compatibili e una via di ritorno. Un piano utile rende visibile proprio questa differenza prima che inizi la parte costosa.
La pianificazione è utile quando la modifica attraversa più confini, esistono alternative reali o il costo di un errore è alto. Il piano deve nominare file, dipendenze, verifiche e decisioni aperte; non deve simulare certezza su dettagli non ancora ispezionati.
Per un cambio locale e reversibile può bastare un piano di tre righe. La profondità del ragionamento va proporzionata al rischio: spendere molto tempo su un cambio ovvio è inefficiente quanto improvvisare una migrazione complessa.
- Definisci risultato, confini e rischio del cambiamento.
- Individua file, istruzioni e fonti che possono cambiare la decisione.
- Scrivi passi piccoli con dipendenze e decisioni ancora aperte.
- Associa a ogni passo una prova osservabile.
- Approva l’esecuzione soltanto quando il piano è verificabile.
Vuoi sostituire `customer_name` con `first_name` e `last_name`, ma la vecchia app mobile resterà attiva durante il rilascio.
- Mappa lettori e scrittori della colonna e segna l'incognita principale: per alcuni clienti esiste soltanto un nome aziendale, quindi la divisione automatica non è affidabile.
- Pianifica una fase compatibile: aggiungi le nuove colonne nullable, continua a leggere il vecchio campo e fai scrivere entrambi i formati alla nuova API.
- Prepara un backfill ripetibile su una copia dei dati, conta record ambigui e definisci un arresto sicuro se il numero supera la soglia concordata.
- Rimuovi la vecchia colonna soltanto dopo metriche stabili, adozione della nuova app e prova di rollback; associa a ogni fase query di controllo e test di compatibilità.
Risultato: Il cambiamento diventa una sequenza reversibile. I casi ambigui non vengono inventati e la vecchia app continua a funzionare durante la transizione.
Istruzioni stabili in CLAUDE.md
Il progetto ha un comando test e un confine dati importante.
# Comandi
- Test: pytest -q
# Vincoli
- Non cambiare il formato dei task senza una migrazione approvata.
# Definition of done
- Test e lint verdi; riassumere diff e rischi residui.