Context engineering: il lavoro prima del prompt
· 6 min read · Filippo Spinella · AI, Agents, Prompting, Developer Tools
La parola del momento, nel piccolo mondo degli agenti AI, è context engineering.
Sembra l'ennesima etichetta inventata per vendere una cosa che già facevamo. In parte lo è. Però, come spesso succede, l'etichetta prende piede perché dà un nome a un dolore reale.
Il dolore è questo: i modelli non falliscono solo perché "non ragionano". Spesso falliscono perché li mandiamo al lavoro con la stanza sbagliata.
Gli diamo istruzioni vecchie. Gli nascondiamo i file importanti. Gli passiamo documenti troppo lunghi e non diciamo cosa conta. Gli facciamo vedere log senza priorità. Gli diamo dieci tool senza spiegare quando usarli. Poi ci stupiamo se l'agente si muove come una persona svegliata in un appartamento sconosciuto.
Il prompt è la frase che gli dici. Il contesto è il mondo che gli prepari intorno.
Dal prompt engineering al context engineering
Il prompt engineering era spesso pensato come scrittura. Scegli le parole giuste, chiedi nel modo giusto, aggiungi esempi, specifica il formato.
Il context engineering è più vicino all'architettura.
Non si chiede solo "come formulo la richiesta?". Si chiede:
- quali informazioni servono davvero?
- quali sono rumore?
- cosa va recuperato al volo?
- cosa deve restare in memoria?
- quali tool vanno esposti?
- quali istruzioni sono stabili e quali dipendono dal task?
- come faccio capire all'agente cosa è autorevole?
È un cambio sottile ma enorme. Perché quando lavori con agenti, il contesto non è un blocco statico. Cambia a ogni step.
L'agente apre un file, impara qualcosa, lancia un test, riceve un errore, aggiorna il piano, chiama un tool, scopre una dipendenza. A ogni giro deve decidere cosa portarsi dietro e cosa lasciare fuori.
Questa è ingegneria.
Il contesto non è una discarica
I modelli con finestre di contesto grandi ci hanno fatto venire una tentazione: buttiamoci dentro tutto.
È comprensibile. Se ho un milione di token, perché dovrei scegliere?
Perché anche quando puoi mettere tutto, non significa che tutto aiuti. Anzi, il rumore ha un costo. Costa token, costa attenzione, costa latenza, costa qualità. Un modello può perdersi in dettagli irrilevanti esattamente come noi quando apriamo venti tab e non ricordiamo più perché.
Il contesto buono ha una gerarchia:
- istruzioni di sistema e policy;
- obiettivo specifico;
- stato corrente;
- dati rilevanti;
- vincoli;
- strumenti disponibili;
- traccia delle decisioni già prese.
Non serve trattare tutto allo stesso livello. Un comando dell'utente vale più di una nota vecchia. Un test fallito ora vale più di una preferenza estetica di tre mesi fa. Una policy di sicurezza vale più di una scorciatoia produttiva.
Context engineering significa anche dare pesi, non solo dati.
Memoria: ricordare meno, ricordare meglio
La memoria negli agenti è uno dei temi più scivolosi.
Da utente, vuoi che l'agente ti conosca. Vuoi che ricordi il tono, il progetto, le convenzioni, le cose già decise. Da ingegnere, sai che ogni memoria persistente è anche un rischio: può essere sbagliata, vecchia, troppo personale, troppo generica, non verificabile.
Una memoria utile dovrebbe avere almeno tre qualità:
- provenienza: da dove arriva questa informazione?
- data: quando è stata vera?
- scopo: per quale tipo di task va usata?
Senza queste tre cose, la memoria diventa superstizione.
Mi piace pensare alla memoria agentica come a un quaderno di lavoro, non come a una mente magica. Ci sono appunti temporanei, decisioni confermate, preferenze di stile, vincoli tecnici, link a fonti. Alcune cose scadono. Alcune vanno riscritte. Alcune vanno eliminate perché l'agente le ha inferite male.
Un buon sistema deve rendere questa manutenzione normale. Non eroica.
Retrieval e tool non sono la stessa cosa
Quando si parla di contesto, spesso si finisce subito su RAG. Embedding, vector database, chunking, reranking.
Tutto utile. Ma il retrieval è solo un modo per portare informazione al modello. Non è l'unico.
Un agente può ottenere contesto leggendo file, interrogando un'API, chiamando un MCP server, aprendo un browser, eseguendo test, cercando in Slack, guardando una dashboard, chiedendo all'umano.
La parte interessante è decidere quale via usare e quando.
Se l'agente deve rispondere a una domanda storica, forse basta retrieval. Se deve correggere un bug, deve leggere codice reale. Se deve capire perché un deploy fallisce, deve guardare log freschi. Se deve scrivere a un cliente, deve recuperare tono, cronologia e stato del ticket. Se deve agire su produzione, deve chiedere permesso.
Il contesto non è un database. È un flusso di lavoro.
L'agente bravo sa anche ignorare
Un segno di maturità, negli agenti, sarà la capacità di dire: questa informazione non mi serve.
Sembra una banalità, ma è difficilissima. Molti sistemi agentici accumulano. Ogni tool call aggiunge testo. Ogni errore resta nel buffer. Ogni file letto si somma alla pila. Alla fine il modello ha una cronologia lunghissima e nessuna mappa.
Serve compressione. Serve sintesi intermedia. Serve stato strutturato.
Non "ecco tutto quello che è successo", ma:
- obiettivo ancora valido;
- ipotesi corrente;
- file già controllati;
- decisioni prese;
- rischi aperti;
- prossima azione.
Questo rende l'agente meno teatrale e più utile. Non perché sembri più intelligente, ma perché lavora con una scrivania ordinata.
Context engineering per team, non per prompt artist
Il motivo per cui questo tema mi interessa è che sposta la competenza dall'individuo al sistema.
Nel prompt engineering, spesso vince chi sa parlare meglio al modello. Nel context engineering, vince il team che organizza meglio il proprio lavoro: documentazione, convenzioni, issue, log, test, ownership, naming, fonti.
Un repository pulito diventa contesto migliore. Una issue scritta bene diventa carburante migliore. Un runbook aggiornato fa risparmiare token e ansia. Un changelog chiaro riduce allucinazioni.
Questa è una notizia bella e un po' scomoda. Bella perché premia le buone pratiche. Scomoda perché non puoi risolvere tutto con un prompt furbo.
Gli agenti amplificano l'igiene del sistema che trovano.
Come lo applicherei domani
Se dovessi introdurre context engineering in un progetto reale, partirei da cose piccole:
- un file di istruzioni di progetto breve e mantenuto;
- esempi buoni di output atteso;
- una lista dei tool disponibili e dei casi in cui usarli;
- decisioni architetturali scritte in modo citabile;
- issue con contesto minimo obbligatorio;
- log e test facili da recuperare;
- memoria persistente modificabile dagli umani.
Poi misurerei una cosa semplice: quante volte l'agente deve chiedere chiarimenti o parte nella direzione sbagliata?
Se succede spesso, non aggiungerei subito un modello più grande. Guarderei il contesto.
La mia lettura
Context engineering è una parola un po' gonfia, sì. Ma il concetto è sano.
Ci ricorda che l'intelligenza di un agente non sta solo nel modello. Sta nell'ambiente che gli prepariamo: cosa vede, cosa ricorda, cosa può fare, cosa gli è vietato fare, quali fonti riconosce come vere.
La parte umana è questa: preparare bene il contesto è una forma di cura. È dire all'agente, ma anche al team, "non voglio che tu indovini, voglio che tu abbia ciò che serve".
Meno magia. Più stanza pulita. Gli agenti ne hanno bisogno quanto noi.