Context engineering: il lavoro prima del prompt

spinny:~/writing $ less context-engineering-agents.md

1 
2La parola del momento, nel piccolo mondo degli agenti AI, è context engineering.
3 
4Sembra 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.
5 
6Il dolore è questo: i modelli non falliscono solo perché "non ragionano". Spesso falliscono perché li mandiamo al lavoro con la stanza sbagliata.
7 
8Gli 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.
9 
10Il prompt è la frase che gli dici. Il contesto è il mondo che gli prepari intorno.
11 
12## Dal prompt engineering al context engineering
13 
14Il prompt engineering era spesso pensato come scrittura. Scegli le parole giuste, chiedi nel modo giusto, aggiungi esempi, specifica il formato.
15 
16Il context engineering è più vicino all'architettura.
17 
18Non si chiede solo "come formulo la richiesta?". Si chiede:
19 
20- quali informazioni servono davvero?
21- quali sono rumore?
22- cosa va recuperato al volo?
23- cosa deve restare in memoria?
24- quali tool vanno esposti?
25- quali istruzioni sono stabili e quali dipendono dal task?
26- come faccio capire all'agente cosa è autorevole?
27 
28È un cambio sottile ma enorme. Perché quando lavori con agenti, il contesto non è un blocco statico. Cambia a ogni step.
29 
30L'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.
31 
32Questa è ingegneria.
33 
34## Il contesto non è una discarica
35 
36I modelli con finestre di contesto grandi ci hanno fatto venire una tentazione: buttiamoci dentro tutto.
37 
38È comprensibile. Se ho un milione di token, perché dovrei scegliere?
39 
40Perché 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é.
41 
42Il contesto buono ha una gerarchia:
43 
441. istruzioni di sistema e policy;
452. obiettivo specifico;
463. stato corrente;
474. dati rilevanti;
485. vincoli;
496. strumenti disponibili;
507. traccia delle decisioni già prese.
51 
52Non 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.
53 
54Context engineering significa anche dare pesi, non solo dati.
55 
56## Memoria: ricordare meno, ricordare meglio
57 
58La memoria negli agenti è uno dei temi più scivolosi.
59 
60Da 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.
61 
62Una memoria utile dovrebbe avere almeno tre qualità:
63 
64- provenienza: da dove arriva questa informazione?
65- data: quando è stata vera?
66- scopo: per quale tipo di task va usata?
67 
68Senza queste tre cose, la memoria diventa superstizione.
69 
70Mi 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.
71 
72Un buon sistema deve rendere questa manutenzione normale. Non eroica.
73 
74## Retrieval e tool non sono la stessa cosa
75 
76Quando si parla di contesto, spesso si finisce subito su RAG. Embedding, vector database, chunking, reranking.
77 
78Tutto utile. Ma il retrieval è solo un modo per portare informazione al modello. Non è l'unico.
79 
80Un 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.
81 
82La parte interessante è decidere quale via usare e quando.
83 
84Se 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.
85 
86Il contesto non è un database. È un flusso di lavoro.
87 
88## L'agente bravo sa anche ignorare
89 
90Un segno di maturità, negli agenti, sarà la capacità di dire: questa informazione non mi serve.
91 
92Sembra 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.
93 
94Serve compressione. Serve sintesi intermedia. Serve stato strutturato.
95 
96Non "ecco tutto quello che è successo", ma:
97 
98- obiettivo ancora valido;
99- ipotesi corrente;
100- file già controllati;
101- decisioni prese;
102- rischi aperti;
103- prossima azione.
104 
105Questo rende l'agente meno teatrale e più utile. Non perché sembri più intelligente, ma perché lavora con una scrivania ordinata.
106 
107## Context engineering per team, non per prompt artist
108 
109Il motivo per cui questo tema mi interessa è che sposta la competenza dall'individuo al sistema.
110 
111Nel 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.
112 
113Un 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.
114 
115Questa è una notizia bella e un po' scomoda. Bella perché premia le buone pratiche. Scomoda perché non puoi risolvere tutto con un prompt furbo.
116 
117Gli agenti amplificano l'igiene del sistema che trovano.
118 
119## Come lo applicherei domani
120 
121Se dovessi introdurre context engineering in un progetto reale, partirei da cose piccole:
122 
123- un file di istruzioni di progetto breve e mantenuto;
124- esempi buoni di output atteso;
125- una lista dei tool disponibili e dei casi in cui usarli;
126- decisioni architetturali scritte in modo citabile;
127- issue con contesto minimo obbligatorio;
128- log e test facili da recuperare;
129- memoria persistente modificabile dagli umani.
130 
131Poi misurerei una cosa semplice: quante volte l'agente deve chiedere chiarimenti o parte nella direzione sbagliata?
132 
133Se succede spesso, non aggiungerei subito un modello più grande. Guarderei il contesto.
134 
135## La mia lettura
136 
137Context engineering è una parola un po' gonfia, sì. Ma il concetto è sano.
138 
139Ci 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.
140 
141La 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".
142 
143Meno magia. Più stanza pulita. Gli agenti ne hanno bisogno quanto noi.
144 
145## Fonti
146 
147- [LangChain Blog: The rise of context engineering](https://blog.langchain.com/the-rise-of-context-engineering/)
148- [Simon Willison: Context engineering](https://simonwillison.net/2025/Jun/27/context-engineering/)
149- [Model Context Protocol: Introduction](https://modelcontextprotocol.io/introduction)
150- [Anthropic: Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)
151- [OpenAI: New tools for building agents](https://openai.com/index/new-tools-for-building-agents/)
152

:Context engineering: il lavoro prima del promptlines 1-152 (END) — press q to close

2La parola del momento, nel piccolo mondo degli agenti AI, è context engineering.

4Sembra 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.

6Il dolore è questo: i modelli non falliscono solo perché "non ragionano". Spesso falliscono perché li mandiamo al lavoro con la stanza sbagliata.

8Gli 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.

10Il prompt è la frase che gli dici. Il contesto è il mondo che gli prepari intorno.

12## Dal prompt engineering al context engineering

14Il prompt engineering era spesso pensato come scrittura. Scegli le parole giuste, chiedi nel modo giusto, aggiungi esempi, specifica il formato.

16Il context engineering è più vicino all'architettura.

18Non si chiede solo "come formulo la richiesta?". Si chiede:

20- quali informazioni servono davvero?

21- quali sono rumore?

22- cosa va recuperato al volo?

23- cosa deve restare in memoria?

24- quali tool vanno esposti?

25- quali istruzioni sono stabili e quali dipendono dal task?

26- come faccio capire all'agente cosa è autorevole?

28È un cambio sottile ma enorme. Perché quando lavori con agenti, il contesto non è un blocco statico. Cambia a ogni step.

30L'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.

32Questa è ingegneria.

34## Il contesto non è una discarica

36I modelli con finestre di contesto grandi ci hanno fatto venire una tentazione: buttiamoci dentro tutto.

38È comprensibile. Se ho un milione di token, perché dovrei scegliere?

40Perché 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é.

42Il contesto buono ha una gerarchia:

441. istruzioni di sistema e policy;

452. obiettivo specifico;

463. stato corrente;

474. dati rilevanti;

485. vincoli;

496. strumenti disponibili;

507. traccia delle decisioni già prese.

52Non 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.

54Context engineering significa anche dare pesi, non solo dati.

56## Memoria: ricordare meno, ricordare meglio

58La memoria negli agenti è uno dei temi più scivolosi.

60Da 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.

62Una memoria utile dovrebbe avere almeno tre qualità:

64- provenienza: da dove arriva questa informazione?

65- data: quando è stata vera?

66- scopo: per quale tipo di task va usata?

68Senza queste tre cose, la memoria diventa superstizione.

70Mi 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.

72Un buon sistema deve rendere questa manutenzione normale. Non eroica.

74## Retrieval e tool non sono la stessa cosa

76Quando si parla di contesto, spesso si finisce subito su RAG. Embedding, vector database, chunking, reranking.

78Tutto utile. Ma il retrieval è solo un modo per portare informazione al modello. Non è l'unico.

80Un 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.

82La parte interessante è decidere quale via usare e quando.

84Se 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.

86Il contesto non è un database. È un flusso di lavoro.

88## L'agente bravo sa anche ignorare

90Un segno di maturità, negli agenti, sarà la capacità di dire: questa informazione non mi serve.

92Sembra 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.

94Serve compressione. Serve sintesi intermedia. Serve stato strutturato.

96Non "ecco tutto quello che è successo", ma:

98- obiettivo ancora valido;

99- ipotesi corrente;

100- file già controllati;

101- decisioni prese;

102- rischi aperti;

103- prossima azione.

104

105Questo rende l'agente meno teatrale e più utile. Non perché sembri più intelligente, ma perché lavora con una scrivania ordinata.

106

107## Context engineering per team, non per prompt artist

108

109Il motivo per cui questo tema mi interessa è che sposta la competenza dall'individuo al sistema.

110

111Nel 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.

112

113Un 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.

114

115Questa è una notizia bella e un po' scomoda. Bella perché premia le buone pratiche. Scomoda perché non puoi risolvere tutto con un prompt furbo.

116

117Gli agenti amplificano l'igiene del sistema che trovano.

118

119## Come lo applicherei domani

120

121Se dovessi introdurre context engineering in un progetto reale, partirei da cose piccole:

122

123- un file di istruzioni di progetto breve e mantenuto;

124- esempi buoni di output atteso;

125- una lista dei tool disponibili e dei casi in cui usarli;

126- decisioni architetturali scritte in modo citabile;

127- issue con contesto minimo obbligatorio;

128- log e test facili da recuperare;

129- memoria persistente modificabile dagli umani.

130

131Poi misurerei una cosa semplice: quante volte l'agente deve chiedere chiarimenti o parte nella direzione sbagliata?

132

133Se succede spesso, non aggiungerei subito un modello più grande. Guarderei il contesto.

134

135## La mia lettura

136

137Context engineering è una parola un po' gonfia, sì. Ma il concetto è sano.

138

139Ci 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.

140

141La 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".

142

143Meno magia. Più stanza pulita. Gli agenti ne hanno bisogno quanto noi.

144

145## Fonti

146

147- [LangChain Blog: The rise of context engineering](https://blog.langchain.com/the-rise-of-context-engineering/)

148- [Simon Willison: Context engineering](https://simonwillison.net/2025/Jun/27/context-engineering/)

149- [Model Context Protocol: Introduction](https://modelcontextprotocol.io/introduction)

150- [Anthropic: Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)

151- [OpenAI: New tools for building agents](https://openai.com/index/new-tools-for-building-agents/)

152