Ingegneria del contesto per gli agenti di codifica

L'ingegneria del contesto consiste nel decidere cosa vede un agente di codifica prima che agisca. È la leva più importante a tua disposizione per garantire la qualità dell'output, poiché la validità di un modello dipende strettamente dall'input fornito.

In Jira, il contesto di cui un agente ha bisogno fa già parte del ticket. Nel ticket sono presenti l'obiettivo e i criteri di accettazione, mentre il Teamwork Graph lo collega al codice, alle decisioni e alla documentazione correlata, in modo che l'agente possa agire in base a un intento reale anziché a un prompt vuoto. Quel contesto rimane condiviso all'interno del team invece che in file locali salvati su un unico computer.

Questa guida illustra che cos'è l'ingegneria del contesto, perché la finestra di contesto rappresenta il vero limite per gli agenti di codifica e come progettare il contesto in Jira in modo che gli agenti ottengano ciò di cui hanno bisogno senza che tu debba fornirglielo manualmente in ogni prompt. In pratica, il tutto si riduce a una manciata di azioni che puoi eseguire nel ticket su stai già lavorando:

• Dai all'agente l'obiettivo, non solo un prompt. Scrivi il ticket di Jira come specifica, con criteri di accettazione in base ai quali viene valutato l'agente.

• Lascia che il grafico fornisca il contesto necessario. Usando il ticket come punto di partenza per il prompt, il Teamwork Graph lo espande inserendo la documentazione, le decisioni e il contesto correlato al task.

• Mantieni gli standard condivisi e aggiornati. Le convenzioni risiedono in Confluence e attingono alla stessa fonte per ogni agente e membro del team.

• Fornisci a tutti gli agenti lo stesso livello di contesto. Lo stesso contesto organizzativo si adatta a ogni agente di codifica, come Claude Code, Cursor, Codex, GitHub Copilot, il Jira Coding Agent e altri ancora.

Che cos'è l'ingegneria del contesto?

L'ingegneria del contesto è la pratica di decidere deliberatamente quali informazioni vede un modello in ogni fase, in modo che un agente di codifica abbia ciò che gli serve per svolgere correttamente il lavoro. Queste informazioni vanno ben oltre il semplice prompt: comprendono la base di codice, i tuoi standard, le dipendenze, la cronologia git, le definizioni degli strumenti, gli obiettivi e i criteri di accettazione. Il nuovo lavoro consiste nel selezionare con cura l'insieme di dati più adatto per ogni attività.

Nell'ingegneria del prompt selezioni le informazioni e le inserisci in un'unica istruzione. Nell'ingegneria del contesto, il sistema fornisce all'agente ciò di cui ha bisogno in un task articolato in più fasi: cosa viene inserito, cosa viene recuperato, cosa viene incluso nel riepilogo e cosa viene tralasciato, in modo che l'agente possa trovare il resto delle informazioni su richiesta.

È importante notare che un contesto più ampio non è necessariamente un contesto migliore:

• Il contesto ad alto segnale è l'informazione che aiuta nello svolgimento del task

• Il contesto a basso segnale è il contenuto obsoleto, fuori tema o duplicato che il modello deve comunque leggere

Quando una finestra di contesto si riempie di token a basso segnale, le risposte diventano più lente e meno accurate, anche se il modello non è cambiato. Questo peggioramento viene chiamato deterioramento del contesto, ossia il graduale declino dell'output man mano che la finestra di contesto si riempie di token obsoleti, a basso segnale o contraddittori. Per una buona ingegneria del contesto occorre tanto rimuovere il contesto obsoleto quanto aggiungere quello giusto.

Perché la finestra di contesto è il vincolo per gli agenti di codifica?

Un modello di codifica può ragionare solo su ciò che rientra nella finestra di contesto, che è piccola rispetto alla base di codice, alla documentazione e alla cronologia del tuo team. Anche un agente competente continua a distribuire codice errato o non sicuro quando le tue convenzioni, la tua architettura o la decisione alla base di un task non riescono a entrate nella finestra.

Quando si lascia all'agente il compito di raccogliere il contesto, si ripresentano ciclicamente determinati errori:

• L'agente si discosta dal contesto in un task lungo perché la decisione presa inizialmente viene estromessa dalla finestra di contesto man mano che nuovi token con un segnale più debole si accumulano.

• Recupera troppi dati, inserisce nella finestra molti più contenuti di quanti ne utilizzi e spende il budget di token per informazioni superflue.

• Non vede mai uno standard che non gli hai imposto, e poi rilascia codice che infrange uno schema che viene seguito dal resto del team.

• Funziona bene da solo, ma non ha idea di cosa stia facendo il resto del team, o un altro agente, nella stessa area.

Al contrario, rendere il contesto corretto facilmente accessibile permette all'agente di mostrare autonomamente ciò di cui ha bisogno man mano che procede, in modo che i tuoi prompt possano mantenere un approccio più generale, senza che tu debba esplicitare manualmente ogni convenzione e decisione.

Come progetti il contesto per gli agenti di codifica in Jira?

In Jira, il contesto è definito dal ticket stesso: l'intento risiede nel ticket, le conoscenze necessarie sono collegate tramite il Teamwork Graph, mentre gli standard e le decisioni consolidati vengono importati da Confluence e Loom, in modo che ogni agente e membro del team attinga alla stessa fonte. Jira va oltre i file locali salvati su un unico computer includendo gli obiettivi, le decisioni e le conversazioni in corso, nonché la cronologia di tutto il tuo lavoro. Mantiene tutte queste informazioni condivise, in modo che il contesto in cui un agente opera sia strutturato, aggiornato e coerente per l'intero team.

L'ingegneria del contesto si basa su tre principi:

1. Selezionare le informazioni giuste

2. Occorre mantenerlo strutturato

3. Deve essere reso persistente

1. Selezione e recupero: scrivi il ticket come specifica

La selezione consiste nello scegliere la porzione più piccola di contesto ad alto segnale per un task, mentre il recupero consiste nell'estrarre le informazioni corrette su richiesta, anziché riversare tutto nella finestra iniziale. In Jira, entrambi i processi iniziano dal ticket.

• Come funziona in Jira: inserisci l'obiettivo nella descrizione e i criteri di accettazione in una checklist per fornire all'agente l'intento e i parametri in base di valutazione in una struttura comprensibile. Quindi, assegna il ticket a un agente connesso. Il processo inizia dal ticket e dal contesto collegato, non dall'intera base di codice. Confrontarsi con l'agente per affinare le specifiche fa parte del lavoro: legge rapidamente grandi quantità di codice e aiuta a individuare le lacune prima di iniziare.

• Presto disponibile: Jira Planner trasforma le idee in piani pronti all'uso per agenti e ticket con il contesto già allegato. Mettiti in lista di attesa.

2. Contesto condiviso: collega il lavoro, non incollarlo

La struttura e il formato sono fondamentali: modella il contesto in modo che un agente possa orientarsi al suo interno e mantienilo collegato anziché copiarlo e incollarlo. Teamwork Graph è ciò che rende disponibile il contesto necessario senza la necessità di assemblarlo manualmente ogni volta.

• Come funziona in Jira: collega il ticket agli altri ticket correlati, al codice e alle pagine di Confluence che contengono le specifiche, l'RFC o il registro delle decisioni. L'agente eredita il contesto relativo al task e non solo il testo del ticket. Anche una panoramica di Loom conta: una registrazione della riproduzione del bug o della motivazione alla base di una progettazione permette di aggiungere la trascrizione e il riepilogo al grafico. In questo modo, una spiegazione che avresti fornito a un collega del team diventa parte del contesto che un agente è in grado di leggere. Ciò permette di recuperare le "informazioni corrette" dal tuo lavoro effettivo, anziché dover creare e gestire un archivio vettoriale separato.

3. Persistenza: mantieni gli standard e le decisioni quando si influenzano a vicenda

Con persistenza o memoria si intende la capacità di mantenere disponibili nel corso del tempo informazioni durature tra una sessione e l'altra, in modo che l'agente non debba ripartire da zero ogni volta. Le tre categorie da considerare sono: ciò che l'agente conserva durante l'esecuzione di un task, ciò che deve mantenere tra un task e l'altro e ciò che può cercare quando necessario.

• Come funziona in Jira: convenzioni, decisioni sull'architettura e modelli preferiti si trovano nello spazio Confluence condiviso. Qui tutto il team e tutti gli agenti attingono alla stessa fonte tramite il grafico, anziché a una copia sul computer di una persona che nessun altro può vedere. Man mano che il ticket avanza nel sistema, il grafico si arricchisce, così che l'agente successivo abbia più elementi a cui attingere. Il contesto si accumula man mano che i ticket vengono completati, senza che lo sviluppatore debba fare passaggi manuali aggiuntivi.

Due elementi sono fondamentali per garantire la collaborazione all'interno di un team: un livello di contesto unico utilizzabile da ogni agente e una governance che ne assicuri l'affidabilità e l'autorizzazione.

Un livello di contesto per ogni agente

Il contesto che progetti ha valore solo se ogni strumento può sfruttarlo. Insegnare di nuovo i tuoi standard a ogni agente è il modo più rapido per far sì che il contesto torni a deteriorarsi.

• Come funziona in Jira: fornisci a ogni agente di codifica lo stesso contesto organizzativo tramite due percorsi. La CLI Teamwork Graph offre al tuo agente l'accesso diretto a quel contesto e ai relativi strumenti dal terminale. Configuralo una volta e il tuo agente potrà interrogare il grafico mentre elabora. Il server Atlassian Rovo MCP svolge lo stesso lavoro per i client MCP come Claude, Cursor, Codex e GitHub Copilot. Teamwork Graph è ciò che rende possibile l'operazione in entrambi i casi: ticket, decisioni, documentazione e codice sono collegati in un unico livello interrogabile. Puoi progettare il contesto una sola volta e usarlo con qualsiasi modello esegua il lavoro.

Governance: mantieni il contesto affidabile e consentito

Il contesto è utile solo se è aggiornato e l'agente è autorizzato a visualizzarlo. La governance mantiene affidabile il livello condiviso mentre un numero crescente di agenti lo utilizza.

• Come funziona in Jira: gli agenti ereditano le stesse autorizzazioni che il tuo team utilizza già come base, quindi un agente vede ciò che può vedere l'utente e nulla di più, mentre il suo ambito può essere ulteriormente limitato con regole specifiche per l'agente. Per capire come si integrano l'accesso, l'approvazione e l'audit, consulta Protezioni e sicurezza dell'ingegneria agentica in Jira.

In che modo Jira si integra con il resto dello stack del contesto?

Oggi, la maggior parte del contesto di un agente di codifica risiede su un'unica macchina: il repository aperto, alcuni file locali e tutto ciò che lo sviluppatore ha digitato nel prompt. Funziona in autonomia, ma è disperso, dipende dalla singola persona e dimentica. Jira e Teamwork Graph riuniscono il contesto rilevante in un unico livello condiviso, aggiornato e gestibile, da cui possono attingere l'intero team e i suoi agenti.

Niente di tutto questo sostituisce l'agente di codifica, l'IDE o la configurazione locale, che continuano a occuparsi dei dettagli per ogni repository e del codice vero e proprio. Jira è il livello condiviso superiore, quindi il contesto da cui tutti i ticket partono è strutturato, aggiornato e uguale per tutto il tuo team.

Come fornire al tuo primo agente un contesto reale in Jira

Il context engineering consiste, in ultima analisi, nel fornire a un agente gli strumenti e le informazioni per trovare da solo ciò di cui ha bisogno. Jira e Teamwork Graph sono il livello di contesto condiviso a cui accede tramite MCP o CLI, quindi il lavoro consiste nel mantenere quel livello accurato e connesso.

Inizia con un ticket ben definito per vedere la differenza tra un agente che va per tentativi e uno che agisce in base a un intento preciso.

1. Fornisci all'agente un parametro di riferimento in base al quale essere valutato. Scegli un task circoscritto, a basso rischio e facile da annullare, ad esempio un refactoring autonomo o una piccola correzione di bug, e scrivi l'obiettivo nella descrizione includendo i criteri di accettazione in una checklist.

2. Lascia che l'agente erediti il contesto invece di incollarlo. Collega il ticket al suo codice facendo riferimento all'Identificatore del ticket nel branch, nel commit o nella richiesta pull e collega il documento o la decisione che lo motiva. In questo modo, l'agente rileva il contesto collegato al task, non solo il testo del ticket.

3. Fai riferimento a uno standard condiviso. Collega la convenzione che deve seguire a una pagina Confluence, così l'agente e il collega del team che seguiranno utilizzeranno la stessa fonte.

4. Assegnalo a un agente. L'agente inizia dal ticket e dal contesto collegato, un punto di partenza più mirato rispetto all'intera base di codice o a un prompt vuoto.

5. Fai una revisione della richiesta in base ai criteri che l'hanno generata. Controlla la richiesta pull rispetto ai criteri di accettazione che hai scritto nel ticket, in modo che l'output venga valutato rispetto allo standard originale che hai assegnato all'agente.

6. Fai in modo che l'agente chiuda il cerchio. Chiedigli di aggiornare il ticket alla fine con un riepilogo della sessione, le decisioni chiave e i compromessi, nonché la richiesta pull collegata, in modo che il collega del team o l'agente che seguirà possa riprendere da dove si era interrotto tramite Teamwork Graph.

Esegui alcuni ticket in questo modo e il grafico si completa man mano: ogni agente lascia un riepilogo, le decisioni fondamentali e la richiesta pull collegata nel ticket, così chi viene dopo parte da un quadro più completo rispetto alla situazione precedente. È il context engineering che si amplifica, invece di azzerarsi a ogni esecuzione.

Domande frequenti sul context engineering

Qual è la differenza tra prompt engineering e context engineering?

Il prompt engineering è la disciplina in cui vengono selezionate manualmente le informazioni pertinenti per un singolo prompt. Il context engineering è la disciplina che consiste nell'implementare un sistema che fornisce informazioni a un agente in un task articolato in più passaggi, inclusi il recupero, la struttura, la memoria e l'obiettivo stesso, in modo da far emergere i dettagli su richiesta, quando necessario.

In che modo gli agenti di codifica IA ottengono il contesto da Jira?

Gli agenti traggono il contesto dal ticket, dalla relativa descrizione e dai criteri di accettazione, nonché da Teamwork Graph, che collega ticket, documentazione e codice correlati in modo che l'agente agisca in base all'intento reale, non a un prompt vuoto.

Perché gli agenti di codifica producono codice errato anche a fronte di un buon prompt?

Raramente un prompt include le tue convenzioni, l'architettura o la decisione alla base di un task. La maggior parte degli errori dell'agente è dovuta a errori di contesto, non del modello: un contesto migliore risolve più problemi rispetto a una formulazione migliore.

Mi serve comunque il context engineering se il mio agente legge già il mio repository?

Sì. Un repository indica a un agente qual è il codice, ma non perché è stato creato in quel modo, quali standard seguire o cos'altro sta succedendo all'interno del team. Il context engineering fornisce il resto.

Che cos'è il deterioramento del contesto?

Il deterioramento del contesto è il degrado graduale dell'output di un agente man mano che la sua finestra di contesto si riempie di token obsoleti, poco significativi o contraddittori. Le risposte diventano più lente e meno accurate anche se il modello non è cambiato.