Issue 10044 · agentic-sdlc
L’issue come unità di intento
Quando il work item diventa il contratto operativo che persone e agenti possono eseguire e verificare
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.
practice
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 Issue 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 dominio. Le fonti stabili restano nei documenti architetturali, negli ADR 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 escalation. Così il work item diventa leggibile sia per una persona sia per un agente e, soprattutto, verificabile a fine lavoro.
trade-offs
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.
enterprise-example
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.
references
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/
Da ricordare
Per delegare lavoro a persone e agenti senza perdere controllo, tratta il work item come implementazione di una unità di intento verificabile: obiettivo chiaro, autorità esplicita, ambito limitato, evidenza richiesta e fonti stabili al posto della memoria implicita.
Per la prossima riunione
Prendendo una issue reale del tuo backlog, quale informazione manca oggi per renderla eseguibile e verificabile anche da chi non ha partecipato alle conversazioni precedenti?
Una domanda per te