Il contratto di lavorazione per un agente di coding: cosa scrivere prima di dargli un compito

Un contratto di lavorazione per un agente di coding è il documento che sta davanti al compito: dice cosa va ottenuto, da quale codice si parte, cosa l'agente può toccare e come si deciderà che ha finito. Il rapporto di Bain sul software agentico, uscito il 29 settembre 2026, arriva a una conclusione vicina da un'altra strada: dopo tre anni in cui il limite era il modello, sostiene, il limite è l'architettura attorno al modello. Qui prendo il pezzo più concreto di quel rapporto, la specifica, e lo trasformo in un modello da provare lunedì mattina su un compito vero.

Cosa dice il rapporto Bain e con quali dati

Il documento si intitola The Missing Architecture for Agentic Software Development, fa parte del Technology Report 2026 di Bain & Company ed è firmato da quattro partner (Purna Doddapaneni, Chris McLaughlin, Stanley Liu e Bill Radzevych). I dati vengono dal Bain Tech and Engineering Survey di aprile 2026, rivolto a 293 dirigenti tecnologici senior.

Secondo il rapporto, gli intervistati si aspettano entro uno o due anni un miglioramento del 148% nella velocità del ciclo di rilascio e del 95% nella produttività degli sviluppatori, mentre i guadagni di oggi stanno fra il 20% e il 27% sulle metriche chiave (valori mediani). Gli sviluppatori completano circa il 21% di attività in più, ma il tempo di revisione sale di circa il 91%. Per Bain il collo di bottiglia si è spostato dalla scrittura alla revisione e alla governance.

L'architettura che propone ha tre parti: conoscenza leggibile dalle macchine, un controllo di qualità deterministico prima della revisione umana, e un ciclo di sviluppo trattato come un prodotto da migliorare. Il passaggio che interessa qui è l'esempio di Stripe: gli agenti chiamati "minions" hanno ciascuno una specifica con obiettivo, ambito, contesto rilevante, metodo di verifica e vincoli, e il rapporto parla di 1.300 pull request scritte da agenti e unite ogni settimana, tutte sottoposte alla stessa revisione umana delle altre. La frase da ricordare è una sola: "The specification, not the model, is the leverage."

Cosa il rapporto non dimostra

Il campione è fatto di dirigenti che rispondono a un sondaggio. Le aspettative del 148% e del 95% sono opinioni su un futuro, e i guadagni del 20-27% sono dichiarati, non misurati sul codice: la pagina non spiega quali siano le "metriche chiave". I casi di Stripe, Amazon e Craft Docs sono riportati senza fonte né metodo, quindi sono racconti di Bain, non dati verificabili.

Il caso di Craft Docs merita una lettura attenta. Un team di venti ingegneri passa, scrive il rapporto, da 15-20 issue a settimana a più di 100. È una metrica di volume, e il rapporto non dice quante di quelle issue siano state riaperte. Vale la regola che ho scritto parlando di metriche di delivery con agenti AI: una metrica che non può peggiorare quando l'agente produce di più non misura la consegna.

Bain è una società di consulenza, e la pagina elenca fra i servizi correlati "AI, Insights, and Solutions" e "Product Development". Il rapporto non dichiara un interesse specifico nel risultato che misura, ma chi vende consulenza sull'architettura ha un motivo per concludere che manca un'architettura. Dunque la tesi "la specifica è la leva" non è dimostrata da una comparazione, è una lettura di Bain dell'esempio di Stripe. Resta un'ipotesi ragionevole, e si può provare sul proprio lavoro con poco.

I sette campi di un contratto di lavorazione

L'elenco di Stripe ha cinque voci. Per un team che lavora su repository con una storia ne servono due in più che il rapporto, in quel passaggio, non nomina: lo stato di partenza e il budget. Ecco i sette campi, ciascuno con la ragione per cui c'è.

Il primo è lo stato di partenza: l'hash del commit da cui l'agente parte. Senza, la revisione confronta il lavoro con un ramo che nel frattempo si è mosso, e nessuno sa dire dopo un mese cosa l'agente avesse davanti. Il secondo è la richiesta, in una frase che descrive un risultato e non un procedimento. Il terzo sono i criteri di accettazione: affermazioni che una macchina o una persona possono controllare con sì o no, come "tutti gli endpoint dell'elenco rispondono con il nuovo schema" e non "il codice è pulito".

Il quarto è il contesto autorizzato: i file, i documenti e i ticket che l'agente può usare, scritti come elenco. Il quinto sono gli strumenti permessi, con il comando consentito e non solo lo strumento: ne parlo in agent harness, dove il punto è proprio la granularità dei permessi. Il sesto è il budget: tempo massimo, numero di tentativi, e una regola di arresto che dice cosa fare quando si esaurisce. Il settimo è la verifica, cioè chi esegue i controlli e chi ha scritto le prove.

Un esempio ipotetico, scritto per un compito di migrazione a una nuova versione di un'API interna:

stato_di_partenza: "a3f9c21 su main"
richiesta: "Migrare i client dell'elenco ordini alla v2 dell'API pagamenti"
criteri_di_accettazione:
  - "nessuna chiamata alla v1 resta nei moduli elencati"
  - "la suite di integrazione scritta da Giulia passa senza modifiche"
contesto_autorizzato: ["docs/api-v2.md", "src/ordini/**", "ticket PAG-214"]
strumenti_permessi: ["lettura repository", "esecuzione test locali"]
budget: "tre tentativi, due ore; allo scadere si consegna lo stato e si ferma"
verifica: "test scritti da chi non esegue; revisione umana prima del merge"

Un contratto così non garantisce che il lavoro riesca. Garantisce che, se non riesce, si capisce dove: nel criterio mancante, nel contesto sbagliato o nel budget troppo stretto, e non in una conversazione che nessuno può più rileggere.

Un esempio da questo blog, e un metodo

Gli articoli di questo blog li scrive una routine guidata da istruzioni versionate nel repository, e quella routine ha un contratto: parte dall'ultimo origin/main, ha criteri di accettazione scritti in uno script di controllo versionato, ha regole sulle fonti e un limite di un articolo per esecuzione. Lo script che la giudica non è scritto dalla routine che esegue. Non dice se i fatti sono veri, controlla solo forma, link e divieti, e per questo la procedura aggiunge a mano la lettura delle fonti. È un esempio piccolo, e mostra il limite: un criterio automatico copre quello che si sa misurare, il resto resta a una persona.

Sul fronte dei metodi, DETENT, il metodo che sto costruendo, parte dalla stessa idea. Il sito dichiara che l'unità di lavoro non è il prompt ma il contratto, con stato di partenza, richiesta, criteri di accettazione, contesto autorizzato, budget, strumenti permessi e verifica indipendente, e che chi esegue non scrive le prove che lo giudicano. Non porto qui risultati su clienti reali perché non ce ne sono da raccontare. La pagina sul metodo è l'industrializzazione della produzione di software.

Cosa fare lunedì mattina

Prendete le ultime cinque pull request scritte da un agente e scrivete, dopo il fatto, il contratto che avrebbero dovuto avere. Per ciascuna annotate quali dei sette campi riuscite a compilare con quello che esisteva prima del lavoro. Quelli che restano vuoti sono i candidati a spiegare perché la modifica è tornata indietro, ed è un'ipotesi che potete confrontare con il tasso di rientro del vostro repository.

Poi una regola mia, che non viene dal rapporto e non è un dato: un compito con più di due campi vuoti non va all'agente. Si scrivono prima i campi mancanti, e se i criteri di accettazione non si riesce a scriverli in forma controllabile, il compito non è pronto. È lo stesso principio di chi controlla il codice scritto dall'intelligenza artificiale: il controllo conta quando le condizioni sono scritte prima, non dopo.

Il rapporto di Bain mette la leva nella specifica e non nel modello. Prima di spendere altro budget sul modello, vale la pena capire quanto della vostra specifica oggi esiste solo nella testa di chi scrive il prompt.