L’issue come unità di intento

Dalla serie

Obiettivo

Progettare un work item come contratto operativo verificabile che espliciti obiettivo, autorità, ambito, dipendenze, criteri di accettazione e risultato atteso per persone e agenti.

Come usarla in pratica

In un contesto agentico, l’unità di intento è il contenitore autorevole che rende un lavoro delegabile, eseguibile e verificabile. Una GitHub IssueGlossarioIssueUna lezione di Architecture Coffee rappresentata come canonical Issue Content e portata attraverso review e pubblicazione.Apri la voce completa può implementare questo concetto, ma non lo esaurisce: ciò che conta è che il work item non sia un semplice promemoria né un riassunto della chat. Quando apri o rivedi una issue, chiediti se un esecutore esterno alla conversazione può capire senza ambiguità quattro cose: qual è il risultato atteso, quali decisioni può prendere, cosa è fuori ambito e quale evidenza deve restituire. La regola utile è questa: il work item descrive il contratto operativo, non l’intera conoscenza del dominioGlossarioDominioLa parte del mondo reale, del business o dell’organizzazione che un sistema deve supportare.Apri la voce completa. Le fonti stabili restano nei documenti architetturali, negli ADRGlossarioADRUn record durevole di una decisione architetturale e del ragionamento che l’ha guidata.Apri la voce completa o nelle policy; la issue li cita e li orchestra. Se il contenuto dipende da informazioni private o dalla memoria della sessione, il contratto è fragile e un agente rischia di eseguire lavoro tecnicamente corretto ma non autorizzato. Per renderlo davvero eseguibile, esplicita sempre obiettivo, autorità, ambito, dipendenze, criteri di accettazione, vincoli sulle modifiche e condizioni di escalationGlossarioEscalationUna richiesta deliberata a un’autorità superiore o diversa per risolvere un rischio materiale o una decisione bloccata.Apri la voce completa. Così il work item diventa leggibile sia per una persona sia per un agente e, soprattutto, verificabile a fine lavoro.

I trade-off da dichiarare apertamente

Formalizzare il work item come contratto aumenta chiarezza e automazione, ma introduce anche costi di disciplina. Il vantaggio principale è la riduzione dell’ambiguità: meno passaggi verbali, meno interpretazioni locali, meno dipendenza da chi ha aperto il ticket. Un altro guadagno importante è la verificabilità: se i criteri di accettazione sono scritti bene, il team può controllare l’esito senza ricostruire la storia della conversazione. Il compromesso è che il work item richiede più qualità in ingresso. Bisogna distinguere tra ciò che è autorizzato e ciò che costituisce solo contesto, e questo richiede tempo e attenzione. Inoltre, un contratto troppo rigido può rallentare l’esplorazione quando l’incertezza è ancora alta. Per questo conviene usare un livello di dettaglio sufficiente a delegare in modo sicuro, ma non così esteso da trasformare la issue in un mini-capitolato ingestibile. In sintesi: più l’agente è chiamato a operare in autonomia, più il contratto deve essere esplicito; più il problema è esplorativo, più il work item deve dichiarare anche i confini dell’incertezza.

Esempio enterprise realistico

Pensa a una banca che vuole far analizzare a un agente le richieste di modifica per un servizio di onboarding clienti. Se la issue dice soltanto “aggiornare il flusso KYC”, l’agente può prendere decisioni scorrette: potrebbe toccare schermate non autorizzate, modificare controlli regolamentari o saltare l’approvazione della sicurezza. Con una issue ben costruita come unità di intento, il work item specifica invece quale processo va cambiato, quali sistemi sono coinvolti, quali policy non possono essere modificate, quali documenti di riferimento usare, quale evidenza fornire a fine esecuzione e quale soglia richiede l’escalation a un architetto o a un responsabile della conformità. A quel punto l’agente non deve indovinare l’intento: lo legge, opera entro i limiti assegnati e restituisce un esito verificabile. Questo approccio funziona bene anche per i team umani. In revisione architetturale, il work item diventa il punto unico per capire se il cambiamento è autorizzato, completo e tracciabile.

Per approfondire

Fonti autorevoli per approfondire lo sviluppo guidato dalle specifiche e la progettazione dell’ambiente operativo degli agenti. • Spec-driven development with AI — GitHub — https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/ • Harness engineering: leveraging Codex in an agent-first world — OpenAI — https://openai.com/index/harness-engineering/