Perche i vostri agenti AI scrivono codice scadente (e cosa abbiamo fatto per risolverlo)

Sei mesi fa avete approvato le licenze per Copilot o Cursor. Il team era entusiasta. L'adozione sembrava forte. E poi le lamentele hanno cominciato ad affiorare nei vostri 1:1.

I cicli di review si sono allungati. I senior engineer, quelli che speravate di liberare per lavoro ad alto impatto, dicevano che l'AI li rallentava. PR piene di codice generato arrivavano con violazioni architetturali: boundary di servizio sbagliati, librerie interne deprecate, pattern di dipendenza che violavano le vostre policy di sicurezza. Il consiglio di amministrazione ha chiesto il ROI sull'investimento in AI e non avevate una risposta chiara. E quando avete guardato trasversalmente i team, ognuno usava l'AI in modo diverso, senza coerenza e senza standard condivisi.

Avete fatto la scelta giusta acquistando gli strumenti. Il gap e strutturale, non tecnologico.

Il problema non e il modello

Ecco la verita scomoda: l'agente AI non sta malfunzionando. Sta facendo esattamente cio per cui e stato costruito: generare codice plausibile in base a cio che riesce a vedere. Il problema e cio che non riesce a vedere.

Non riesce a vedere i vostri architectural decision record. Non sa che avete deprecato la libreria HTTP client interna otto mesi fa. Non ha idea che i servizi nel dominio pagamenti non possono chiamare direttamente i servizi nel dominio identita. Non sa cosa significhi "buon codice" nella vostra specifica organizzazione, perche nessuno l'ha scritto in una forma che possa utilizzare.

L'intuizione che ha cambiato il nostro approccio in FairMind era semplice: l'errore di un agente non e un fallimento del modello. E un segnale che il vostro ambiente manca di un vincolo. Il lavoro consiste nel codificare quel vincolo in modo che l'agente non possa ripetere lo stesso errore.

Controintuitivamente, si ottengono piu capacita dai propri agenti restringendo il loro ambiente, non allentandolo. Questo principio, confermato indipendentemente da professionisti di Stripe, OpenAI, Anthropic e LangChain, e alla base di cio che il settore chiama oggi harness engineering.

Cosa abbiamo effettivamente fatto

Non siamo arrivati al nostro workflow attuale leggendo un manuale. Lo abbiamo costruito attraverso un anno di fallimenti, dibattiti e correzioni incrementali, sviluppando la piattaforma FairMind con gli agenti AI al centro del processo di sviluppo.

Il collo di bottiglia della review

La prima crisi e stata la code review. Circa un anno fa, quando gli strumenti per agenti erano meno maturi, abbiamo raggiunto un muro: gli agenti producevano codice piu velocemente di quanto i nostri senior engineer riuscissero a revisionarlo. Invece del guadagno di produttivita che ci aspettavamo, avevamo creato un nuovo collo di bottiglia. Le persone piu esperte del team passavano il tempo a leggere codice generato dall'AI invece di progettare sistemi.

Ne abbiamo discusso a lungo. L'impulso iniziale era di irrigidire gli standard di review. Invece, siamo andati nella direzione opposta: abbiamo costruito un sistema di review assistito dagli agenti. Abbiamo creato strumenti che permettono agli agenti di eseguire il primo passaggio di code review, combinati con suite di test automatizzati mirati, progettati specificamente per i pattern che gli agenti tendono a sbagliare. Inizialmente era una soluzione improvvisata, piuttosto artigianale. Ha funzionato abbastanza bene da diventare una funzionalita core della piattaforma FairMind che ora offriamo ai clienti.

Il problema del contesto

Il secondo problema era la frammentazione del contesto. Gli agenti non avevano un modo strutturato per comprendere il nostro codebase, le nostre convenzioni o le nostre decisioni architetturali. Generavano codice plausibile nel vuoto.

Abbiamo costruito quello che chiamiamo il Project Context: un repository strutturato che contiene l'intero codebase (aggiornato automaticamente), la documentazione architetturale, i decision record e, aspetto cruciale, tutti gli artefatti che gli agenti stessi producono. Quando un agente fa una sessione di brainstorming, scrive documentazione o esegue un'analisi di impatto, quell'output viene automaticamente salvato nel Project Context. La knowledge base cresce a ogni interazione.

Il nostro workflow ora inizia ben prima che venga scritto qualsiasi codice. Io uso gli agenti di FairMind per creare epic e user story, facendo brainstorming direttamente sul codebase e conducendo ricerche web per informare le decisioni. Queste story vanno al CTO e al team di sviluppo, che collaborano, fanno domande di chiarimento (a me o agli agenti) e scompongono il lavoro in task, tutto all'interno di FairMind. Quando un agente inizia a scrivere codice, il contesto e completo e le ambiguita sono state risolte.

Development journal e gap analysis nella CI/CD

La terza innovazione e nata da un punto dolente specifico: quando gli agenti finivano un task di sviluppo, non avevamo un modo affidabile per verificare se l'output corrispondeva a quanto pianificato, se non leggendo ogni riga noi stessi.

La nostra soluzione e stata obbligare ogni agente a produrre un "development journal" durante l'esecuzione: un log strutturato delle attivita svolte, delle decisioni prese, dei file modificati e della motivazione di ogni scelta. Quando il codice viene pushato, un agente dedicato nella nostra pipeline CI/CD legge questi journal, li confronta con quanto pianificato in FairMind e produce una gap analysis. L'output e una tabella comparativa: cosa e allineato, cosa devia, cosa richiede rimedio e le linee di intervento proposte. Lo sviluppatore legge la PR, vede esattamente dove sono i gap e puo completare cio che serve.

Questo meccanismo ha trasformato il nostro quality assurance da una review manuale, time-intensive, in un processo strutturato e verificabile.

Il layer di osservabilita

A volte gli agenti sviluppano assunzioni errate che si propagano silenziosamente nel loro lavoro. Lo abbiamo scoperto quando un agente, durante un task di documentazione del codebase, ha deciso che una delle nostre librerie fosse legata allo sviluppo di videogiochi. Non lo era. La causa: l'agente non era riuscito ad accedere al codebase reale e, invece di fermarsi per segnalare il problema, aveva inferito lo scopo del progetto dal nome del repository e costruito un'intera analisi su una premessa falsa. Il fallimento non era nel modello. Era nell'ambiente: nulla obbligava l'agente a fermarsi quando non aveva accesso a informazioni critiche.

Abbiamo risposto con un guardrail che interrompe gli agenti quando non possono accedere al codebase e li obbliga a chiedere indicazioni. Abbiamo inoltre costruito uno stream di attivita osservabile per ogni sessione agente e un sistema di memoria modificabile. Gli utenti possono osservare cosa stanno facendo gli agenti in tempo reale, ispezionare le loro assunzioni di lavoro, correggere errori nella memoria dell'agente e riavviare l'esecuzione da un checkpoint specifico. Non si aspetta l'output finale per scoprire un problema. Si interviene dove il ragionamento va storto.

Il cambiamento culturale

Anche all'interno del nostro team, come pionieri di questo approccio, la transizione non e stata liscia. Abbiamo attraversato una migrazione significativa: dallo sviluppo IDE-centrico a workflow basati su agenti in terminale usando Claude Code e strumenti simili, con gli IDE come backup per analisi avanzate e verifiche puntuali. Gli sviluppatori che inizialmente dicevano "lo scrivo piu velocemente io" avevano ragione, in casi specifici. Il debugging complesso beneficia ancora dell'intuizione umana. Ma sullo sviluppo di nuove funzionalita, la differenza di produttivita e diventata innegabile, e il team si e adattato.

I risultati

Usando queste pratiche, il nostro team di sviluppo ora mantiene un throughput fino a 10 PR per sviluppatore a settimana. Sullo sviluppo di nuove funzionalita, il miglioramento di produttivita e di un ordine di grandezza rispetto al nostro baseline pre-agenti. Sul debugging complesso, il vantaggio e piu contenuto (20-30%), sebbene la fase di analisi dei log e identificazione dei problemi sia migliorata di 5-7x grazie ad agenti che analizzano i log delle applicazioni cloud in tempo reale e li incrociano con il codebase.

Due risultati contano piu della velocita: abbiamo eliminato completamente i merge conflict sui feature branch e ridotto significativamente gli incidenti in produzione. Entrambi sono conseguenze dirette dell'integrazione degli agenti nella nostra pipeline CI/CD e dell'uso sistematico da parte del team per ogni fase di verifica.

Questi numeri sono specifici del nostro contesto, del nostro codebase e delle dinamiche del nostro team. I moltiplicatori varieranno. Cio che si generalizza e l'approccio strutturale: investite nell'ambiente e la produttivita degli agenti seguira.

Come riferimento, i dati del settore raccontano una storia coerente. Stripe esegue il merge di oltre 1.000 PR generate da agenti a settimana. I principali laboratori di AI hanno documentato throughput sostenuti di piu PR per ingegnere al giorno. I contesti sono molto diversi, ma i pattern strutturali sono gli stessi.

Domande da fare al vostro team subito

Non serve un consulente per iniziare a diagnosticare dove vi trovate. Queste cinque domande faranno emergere i gap strutturali. Lo sappiamo perche sono le domande che abbiamo posto a noi stessi.

I vostri agenti AI riescono a trovare i vostri architectural decision record? Non se avete degli ADR. Se sono in una posizione e in un formato che un agente puo usare durante la sessione. Se la risposta e "sono da qualche parte su Confluence," i vostri agenti stanno operando senza quel contesto. Quando abbiamo costruito il nostro Project Context, il miglioramento piu grande e venuto dal rendere la documentazione esistente accessibile agli agenti, non dallo scrivere nuova documentazione.

Quanto velocemente la vostra CI da feedback a un agente? Se la risposta e "da dieci a quindici minuti," i vostri agenti stanno operando al buio. Il feedback che arriva dopo la sessione e privo di contesto. Puntate a meno di cinque minuti per i check rilevanti per gli agenti e a meno di trenta secondi per il lint. I nostri controlli shift-left hanno intercettato problemi che prima sarebbero emersi solo in produzione.

Avete confini documentati che gli agenti devono rispettare? Regole di ownership dei servizi, librerie deprecate, confini di sicurezza, vincoli di compliance. Sono codificati come regole di lint e check automatizzati, o sono in un wiki che gli agenti non possono leggere? Noi li abbiamo codificati come skill degli agenti e hook che vengono eseguiti prima del commit del codice. I vincoli sono strutturali, non consultativi.

Chi revisiona il codice generato dall'AI e cosa controlla? Se i senior engineer stanno revisionando il codice generato dall'AI nello stesso modo in cui revisionano codice scritto da umani, avete invertito la value proposition. Noi abbiamo risolto stratificando la review assistita dagli agenti con test automatizzati mirati, riservando poi la review umana alle decisioni architetturali e ai casi limite. Il collo di bottiglia della review e scomparso.

L'output degli agenti e tracciabile rispetto all'intento? Se una PR viene mergiata e qualcosa va storto, riuscite a risalire a cosa l'agente avrebbe dovuto fare, cosa ha effettivamente fatto e dove ha deviato? Senza un meccanismo come i nostri development journal e la gap analysis, lo sviluppo guidato dagli agenti e una scatola nera. La tracciabilita non e un nice-to-have: e cio che rende il processo affidabile.

Rendere tutto questo sistematico

Le cinque domande qui sopra vi mostreranno dove sono i gap. Colmarli e un tipo di lavoro diverso da quello che la maggior parte delle organizzazioni di ingegneria ha fatto finora. E progettazione dell'ambiente: architettura della documentazione, sistemi di vincoli, ingegneria dei feedback loop, definizione dei ruoli e definizione dei pattern organizzativi. Si colloca all'intersezione tra platform engineering, developer experience e design organizzativo.

FairMind ha costruito un framework di consulenza per questo tipo di lavoro, partendo dalla nostra pratica interna e ora arricchito attraverso gli ingaggi con i clienti. I nostri consulenti valutano le organizzazioni di ingegneria su 72 criteri e 7 dimensioni, coprendo l'intero ambiente: sistemi di contesto, vincoli architetturali, feedback loop CI/CD, pattern di workflow degli agenti, misurazione e struttura del team. L'assessment richiede da due a tre settimane e produce una roadmap prioritizzata basata su dove la vostra organizzazione si trova effettivamente.

Non e necessario lavorare con FairMind per fare progressi. Le domande qui sopra sono un punto di partenza concreto. Ma se volete comprendere con precisione la posizione della vostra organizzazione e ottenere un percorso strutturato per colmare i gap, e esattamente quello per cui l'assessment e progettato.

La conclusione

I senior engineer che dicono che l'AI li rallenta non hanno torto. In un ambiente non strutturato, gli agenti generano codice plausibile che viola regole invisibili, e la correzione di quel codice ricade sulle persone piu esperte nella stanza. Il problema non e l'AI. Il problema e che le regole sono invisibili.

Non abbiamo ottenuto i nostri risultati deployando modelli migliori. Li abbiamo ottenuti costruendo un ambiente dove le regole sono codificate, i vincoli sono strutturali, i feedback loop si chiudono in secondi e ogni sessione agente produce un record tracciabile di intento versus esecuzione. Gli agenti sono capaci. L'ambiente e la leva.

L'harness engineering e la disciplina di costruire quell'ambiente in modo deliberato. E il lavoro che converte l'adozione di strumenti AI in produttivita guidata dall'AI.

Se volete capire dove si trova la vostra organizzazione, contattateci: info@fairmind.ai

Per un'analisi approfondita della disciplina e del framework a sette dimensioni, leggete anche: Harness Engineering: la disciplina che determina se i vostri agenti AI vanno in produzione o si bloccano

Scoprite come FairMind puo aiutare la vostra organizzazione: Harness Engineering Assessment