L’harness engineering sembra semplice sulla carta. Ecco cosa ci hanno insegnato due anni in produzione. Harness Engineering Looks Simple on Paper. Here’s What 2 Years in Production Taught Us.

Sulla teoria ormai sono tutti d’accordo. OpenAI l’ha pubblicata. Martin Fowler le ha dato un nome. Anthropic l’ha validata con 16 agenti in parallelo che costruivano un compilatore C.

La teoria dell’harness engineering sta convergendo in fretta. La pratica è un’altra storia.

Ho passato gli ultimi due anni a costruire harness per agenti AI su codebase enterprise. Prima per noi (FairMind è costruita dai suoi stessi agenti), poi per clienti con milioni di righe di codice legacy, requisiti di compliance e team da 50 a 200 sviluppatori. Quello che ho imparato è che la distanza tra “abbiamo capito l’harness engineering” e “i nostri agenti sono produttivi in produzione” è enorme, e quasi del tutto non documentata.

Questo è il mio tentativo di documentarla.

Prima lezione: i vostri agenti falliranno in modi imprevedibili

Quando abbiamo iniziato a costruire FairMind con gli agenti al centro del flusso di sviluppo, i fallimenti non sono stati quelli che ci aspettavamo. Ci aspettavamo codice sbagliato. Abbiamo ottenuto qualcosa di peggio: codice plausibile che violava regole invisibili.

Un agente che importa una libreria deprecata non è rotto. Sta facendo esattamente ciò per cui è progettato: colmare i vuoti con inferenze plausibili. La libreria esiste, funziona, compare in tutta la codebase. L’agente non ha modo di sapere che è stata deprecata otto mesi fa, perché nessuno ha scritto quella decisione in un formato che l’agente potesse leggere.

È il primo schema in cui inciampa ogni organizzazione. Non fallimenti del modello. Fallimenti di contesto. E l’istinto è sempre quello sbagliato: i team danno la colpa al modello e iniziano a valutare alternative, quando dovrebbero guardare cosa manca nell’ambiente.

Abbiamo imparato a trattare ogni errore dell’agente come un segnale diagnostico. La domanda non è mai stata “perché l’agente ha fatto questo?” ma “quale vincolo manca nell’ambiente, tanto da aver permesso che accadesse?”

Seconda lezione: la velocità del feedback cambia tutto

Quasi tutte le pipeline CI/CD sono state progettate per sviluppatori umani che pubblicano codice qualche volta al giorno. Gli agenti lo fanno di continuo. Una pipeline da 15 minuti, che sembrava veloce per un flusso umano, diventa una zona morta per un agente: quando il feedback arriva, l’agente ha già perso il contesto di quello che stava facendo.

Abbiamo ricostruito i nostri feedback loop attorno a un principio semplice: qualsiasi segnale che impiega più della memoria di lavoro dell’agente è inutile. Lint sotto i 5 secondi. Controlli architetturali sotto i 30. La suite di CI completa sotto i 5 minuti per i controlli che riguardano l’agente.

Stripe è arrivata alla stessa conclusione in modo indipendente: lint sotto i 5 secondi con correzione automatica, eseguito prima che un essere umano veda l’output. L’intuizione è strutturale. Il feedback rapido non è un optional. È infrastruttura. Senza, state chiedendo agli agenti di scrivere codice bendati.

È qui che si blocca la maggior parte delle aziende. La loro CI è stata costruita per un’altra epoca. Adattarla alla velocità di feedback che serve agli agenti è lavoro di ingegneria vero, non configurazione.

Terza lezione: agli agenti servono guardrail, non linee guida

È stato il cambiamento più controintuitivo per il nostro team. Gli ingegneri apprezzano la flessibilità. Negli ambienti agent-first, la flessibilità è il nemico.

Quando abbiamo lasciato gli agenti senza vincoli, hanno prodotto codice che superava i controlli di base ma violava regole architetturali che esistevano solo nella testa delle persone. La soluzione non erano prompt migliori. Erano vincoli strutturali: linter custom che impongono i confini tra servizi, gestione delle dipendenze che blocca le librerie non approvate, controlli architetturali che partono automaticamente prima di qualsiasi review umana.

Il principio è semplice ma difficile da interiorizzare: dagli agenti ottenete più capacità restringendo il loro ambiente, non allargandolo. Ogni vincolo strutturale che abbiamo aggiunto ha aumentato la produttività degli agenti, non l’ha ridotta.

Lo abbiamo integrato in FairMind sotto forma di agenti e skill specializzati che operano dentro gli strumenti di sviluppo: un agente di cybersecurity, un agente di code review e una serie di hook che impongono la conformità di processo prima ancora che il codice venga committato. Non sono linee guida facoltative. Sono vincoli strutturali che rendono le violazioni impossibili, non semplicemente rilevabili.

Quarta lezione: l’osservabilità non è opzionale

C’è una cosa di cui non ho visto discutere abbastanza nella letteratura che sta nascendo sull’harness engineering: gli agenti sviluppano assunzioni sbagliate che si propagano in silenzio.

Un esempio concreto, capitato a noi. Durante un lavoro di documentazione di una codebase, uno dei nostri agenti ha stabilito che una certa libreria riguardasse lo sviluppo di videogiochi. Non era così. La causa profonda è istruttiva: l’agente non era riuscito ad accedere alla codebase vera e, invece di fermarsi e segnalare il problema, ha dedotto lo scopo del progetto dal nome del repository e ha costruito un’intera analisi su una premessa falsa.

La reazione naturale è “ma che razza di agente sbaglia così?“. La lezione vera, però, è che l’agente ha fatto esattamente ciò per cui è progettato: riempire i vuoti di contesto con inferenze plausibili. Il fallimento era nell’ambiente, non nel modello.

Abbiamo risposto con due interventi. Primo, un guardrail che ferma gli agenti quando non riescono ad accedere alla codebase e li obbliga a chiedere indicazioni. Secondo, uno stream di attività osservabile e un sistema di memoria editabile: le persone possono ispezionare le assunzioni dell’agente in tempo reale, correggere gli errori e far ripartire l’esecuzione da un checkpoint preciso. Non aspettate l’output finale per scoprire il problema. Intervenite nel punto in cui il ragionamento devia.

Quinta lezione: l’organigramma conta più dello stack tecnologico

È la lezione che nessuno vuole sentirsi dire.

Abbiamo attraversato una migrazione interna importante: dallo sviluppo centrato sull’IDE a flussi di lavoro con agenti da terminale. Gli sviluppatori che all’inizio dicevano “lo scrivo prima io” avevano ragione, in casi specifici. Il debugging complesso continua a beneficiare dell’intuizione umana. Ma sullo sviluppo di nuove funzionalità la differenza di produttività è diventata innegabile, e il team si è adattato.

La parte difficile non è stata la tecnologia. È stata ridefinire cosa significa “bravo sviluppatore”. Negli ambienti agent-first il ruolo dello sviluppatore si sposta dallo scrivere codice al progettare ambienti, istruire agenti e valutare output. È un insieme di competenze radicalmente diverso. Le organizzazioni che non definiscono che aspetto ha la competenza in questo nuovo modello non riescono ad assumere, promuovere o formare.

Abbiamo codificato tutto questo in un framework: 7 dimensioni, 72 criteri, dall’architettura ai guardrail fino alla cultura e all’adozione. Non perché i framework abbiano valore di per sé, ma perché senza una valutazione strutturata le organizzazioni ottimizzano una dimensione ignorando le altre sei, quelle che poi determinano se gli agenti funzionano davvero in produzione.

Cosa direi a un CTO che parte oggi

Non partite dal throughput. Partite dalla verifica. Prima di ottimizzare il volume di output degli agenti vi servono misure di riferimento sul tasso di difetti e sulla qualità in produzione del codice generato. Senza quelle, i numeri sul throughput sono impressionanti ma incompleti.

Non aspettate il greenfield. Il valore vero dell’harness engineering è nel brownfield: codebase esistenti, sistemi legacy, requisiti di compliance reali. Partite da un sottosistema ben coperto da test e sviluppate lì i vostri pattern di harness, prima di estenderli.

E soprattutto: investite nell’ambiente, non nel modello. Abbiamo raggiunto 10 PR per sviluppatore a settimana, zero conflitti di merge e una riduzione significativa degli incidenti in produzione. Non mettendo in campo modelli migliori. Costruendo un harness migliore attorno agli stessi modelli che usano tutti.

La disciplina è giovane. Le decisioni no.

Approfondimento sul framework e sulla metodologia: fairmind.ai/it/blog/harness-engineering-research. Per i responsabili tecnici che stanno valutando la maturità della propria organizzazione sugli agenti: fairmind.ai/it/harness-engineering.

Everyone agrees on the theory now. OpenAI published it. Martin Fowler named it. Anthropic validated it with 16 parallel agents building a C compiler.

The theory of harness engineering is converging fast. The practice is a different story.

I’ve spent the last two years building AI agent harnesses for enterprise codebases. First for ourselves (FairMind is built by its own agents), then for clients with millions of lines of legacy code, compliance requirements, and teams of 50 to 200 developers. What I’ve learned is that the gap between “we understand harness engineering” and “our agents are productive in production” is enormous, and almost entirely undocumented.

This is my attempt to document it.

The first lesson: your agents will fail in ways you can’t predict

When we started building FairMind with agents at the center of our development workflow, the failures weren’t what we expected. We expected bad code. We got something worse: plausible code that violated invisible rules.

An agent that imports a deprecated library isn’t broken. It’s doing what it’s designed to do: filling gaps with plausible inference. The library exists, it works, it appears throughout the codebase. The agent has no way to know it was deprecated eight months ago because nobody wrote that decision in a format the agent could read.

This is the first pattern every organization hits. Not model failures. Context failures. And the instinct is always wrong: teams blame the model and start evaluating alternatives, when they should be looking at what’s missing from the environment.

We learned to treat every agent error as a diagnostic signal. The question was never “why did the agent do this?” but “what constraint is missing from the environment that allowed this to happen?”

The second lesson: speed of feedback changes everything

Most CI/CD pipelines were designed for human developers who push code a few times a day. Agents push code continuously. A 15-minute pipeline that felt fast for human workflows becomes a dead zone for agents: by the time feedback arrives, the agent has lost the context of what it was doing.

We rebuilt our feedback loops around a simple principle: any signal that takes longer than the agent’s working memory is useless. Lint in under 5 seconds. Architectural checks in under 30. The full CI suite in under 5 minutes for agent-relevant checks.

Stripe reached the same conclusion independently: sub-5-second lint with auto-fix that runs before any human sees the output. The insight is structural. Fast feedback isn’t a nice-to-have. It’s infrastructure. Without it, you’re asking agents to code blindfolded.

This is where most enterprises stall. Their CI was built for a different era. Retrofitting it for agent-speed feedback is real engineering work, not configuration.

The third lesson: agents need guardrails, not guidelines

This was the most counterintuitive shift for our team. Engineers value flexibility. In agent-first environments, flexibility is the enemy.

When we left agents unconstrained, they produced code that passed basic checks but violated architectural rules that existed only in people’s heads. The fix wasn’t better prompts. It was structural constraints: custom linters that enforce service boundaries, dependency management that blocks unapproved libraries, architectural checks that run automatically before any human review.

The principle is simple but hard to internalize: you get more capability from agents by narrowing their environment, not expanding it. Every structural constraint we added increased agent productivity, not decreased it.

We built this into FairMind as specialized agents and skills that operate within development tools: a cybersecurity agent, a code review agent, and a set of hooks that enforce process compliance before code is even committed. These aren’t optional guidelines. They’re structural constraints that make violations impossible rather than merely detectable.

The fourth lesson: observability is not optional

Here’s something I haven’t seen discussed enough in the emerging harness engineering literature: agents develop wrong assumptions that propagate silently.

A concrete example from our own experience. During a codebase documentation task, one of our agents decided a particular library was related to game development. It wasn’t. The root cause was instructive: the agent failed to access the actual codebase and, instead of stopping to flag the problem, inferred the project’s purpose from the repository name and built an entire analysis on a false premise.

The natural reaction is “what kind of agent gets it that wrong?” But the real lesson is that the agent did exactly what it’s designed to do: fill context gaps with plausible inference. The failure was in the environment, not the model.

We responded with two changes. First, a guardrail that halts agents when they can’t access the codebase and forces them to ask for guidance. Second, an observable activity stream and editable memory system: users can inspect agent assumptions in real time, correct errors, and restart execution from a specific checkpoint. You don’t wait for the final output to discover a problem. You intervene where the reasoning goes wrong.

The fifth lesson: the org chart matters more than the tech stack

This is the lesson nobody wants to hear.

We went through a significant internal migration: from IDE-centric development to terminal-based agent workflows. Developers who initially said “I can write it faster myself” were right, in specific cases. Complex debugging still benefits from human intuition. But on new feature development, the productivity difference became undeniable, and the team adapted.

The harder part wasn’t the tooling. It was redefining what “good developer” means. In agent-first environments, the developer’s role shifts from writing code to designing environments, briefing agents, and evaluating outputs. That’s a fundamentally different skill set. Organizations that don’t define what competence looks like in this new model can’t hire, promote, or train for it.

We codified this into a framework: 7 dimensions, 72 criteria, covering everything from architecture and guardrails to culture and adoption. Not because frameworks are inherently valuable, but because without a structured assessment, organizations optimize one dimension while ignoring the six others that determine whether agents actually work in production.

What I’d tell a CTO starting today

Don’t start with throughput. Start with verification. Before optimizing for agent output volume, you need baseline measurements of defect rates and production quality for agent-generated code. Without that, throughput numbers are impressive but incomplete.

Don’t wait for greenfield. The real value of harness engineering is in brownfield: existing codebases, legacy systems, real compliance requirements. Start with a well-tested subsystem and develop your harness patterns there before extending.

And above all: invest in the environment, not the model. We achieved 10 PRs per developer per week, zero merge conflicts, and significantly fewer production incidents. Not by deploying better models. By building a better harness around the same models everyone else uses.

The discipline is young. The decisions are not.

Deep dive on the framework and methodology: fairmind.ai/en/blog/harness-engineering-research. For engineering leaders evaluating agent readiness: fairmind.ai/en/harness-engineering.