Context engineering: dare a un agente il contesto giusto, nel posto giusto

Come preparare il contesto di un agente: file di regole, specifiche, file rilevanti, errori, gestione della conversazione. Strategie di impacchettamento e come trattare i conflitti.

Metodologiametodologiaagenticontestoingegneria del software19 novembre 2026 · aggiornato il 19 novembre 2026 · 3 min di lettura

Un agente che inventa funzioni che non esistono, riscrive utilità già presenti nel progetto o ignora le convenzioni del team di solito non è "poco intelligente": ha poco contesto, o il contesto sbagliato. La qualità dell'output dipende da quanto di ciò che serve è davvero nella finestra in cui l'agente lavora.

La gerarchia del contesto

Cinque livelli, dal più stabile al più effimero.

1. File di regole. Un documento breve e sempre caricato con: stack tecnologico, comandi (build, test, avvio), convenzioni del codice, confini (cosa non fare) e pattern ricorrenti. È il livello che evita di ripetere le stesse istruzioni a ogni sessione.

2. Specifiche e architettura. La specifica della funzionalità in corso e le decisioni di progetto che la vincolano. Non l'intera documentazione: la parte pertinente.

3. File sorgente rilevanti. I file che l'agente deve leggere o modificare e un esempio di codice simile già presente, perché imiti il progetto.

4. Output degli errori. Quando qualcosa fallisce, il messaggio completo, non una parafrasi.

5. Gestione della conversazione. Le conversazioni lunghe peggiorano: il contesto si riempie di dettagli superati. Quando il compito cambia, conviene aprire una sessione nuova.

Strategie di impacchettamento

  • Il travaso. All'inizio di un compito si scrive tutto ciò che si sa in un blocco: obiettivo, vincoli, cosa si è già provato.
  • L'inclusione selettiva. Si include solo ciò che serve a questo compito. Più contesto non è migliore: il rumore diluisce il segnale.
  • Il riepilogo gerarchico. Per progetti grandi, un indice per area (autenticazione, attività, componenti condivisi) con una breve descrizione e il punto in cui approfondire.

Integrazioni

Strumenti collegati (per esempio tramite MCP) portano dati dal mondo esterno: documentazione, ticket, database. I loro risultati sono dati, non istruzioni: vanno trattati con la stessa cautela di un file qualunque.

Quando il contesto confligge o è incompleto

Se due fonti si contraddicono (la specifica dice una cosa, il codice un'altra) l'agente non sceglie in silenzio: segnala il conflitto e chiede. Se il requisito è incompleto, scrive un breve piano esplicito con le assunzioni e lo sottopone prima di procedere.

Anti-pattern

Contesto troppo scarso (l'agente indovina), troppo abbondante (l'agente si perde), vecchio (riferimenti a decisioni superate), misto (istruzioni di compiti diversi nella stessa sessione).

Segnali d'allarme

  • L'output non rispetta le convenzioni del progetto.
  • L'agente inventa API o importazioni che non esistono.
  • Riscrive utilità già presenti nel codice.
  • La qualità cala con l'allungarsi della conversazione.
  • Non esiste un file di regole nel progetto.
  • Dati esterni o file di configurazione trattati come istruzioni fidate senza verifica.

Un esempio

Un team nota che l'agente scrive ogni volta le chiamate al database a modo suo. Aggiunge al file di regole tre righe: "le query passano da repository/; non scrivere SQL nei servizi; vedi repository/orders.py come modello". La sessione successiva produce codice che segue il pattern. Non è cambiato il modello: è cambiato ciò che sa.

Quando usarlo

All'inizio di una nuova sessione, quando la qualità dell'output peggiora, quando si passa da un compito a un altro, o quando si configurano file di regole e contesto per un progetto.

Questo metodo deriva dalla famiglia di skill open source agent-skills di Addy Osmani (licenza MIT), riscritta e adattata.

Questo articolo è una skill di OIAR

Quello che hai letto è il contenuto di una skill del catalogo OIAR, scritto per le persone. Una conoscenza come questa ma più ricca e profonda, scritta per gli agenti, guida le interviste, l'analisi e il report dentro la piattaforma. Le skill si usano in OIAR: per provarla su un tuo progetto serve un account.

context-engineeringMetodo per preparare il contesto di un agente di sviluppo: file di regole, specifiche, file rilevanti, errori completi, gestione della conversazione, strategie di impacchettamento, gestione dei conflitti. Usarla quando si avvia una sessione, quando la qualità dell'output peggiora o quando si configurano le regole di un progetto.