Configurare un CLAUDE.md non è harness engineering. Ecco com’è fatto l’altro 95%.

Configurare un file CLAUDE.md non è harness engineering. È il primo 5%.

Su X vedo sempre lo stesso schema: qualcuno scrive un ottimo CLAUDE.md, aggiunge qualche server MCP, magari un hook o due, e lo chiama “harness engineering”. Sia chiaro: è un buon inizio. Ma se avete lavorato solo sul repository di un singolo sviluppatore, non avete ancora visto cosa richiede davvero l’harness engineering.

Ho passato gli ultimi due anni a costruire harness per clienti enterprise europei. Codebase da oltre due milioni di righe. Sistemi legacy che nessuno vuole toccare. Requisiti di compliance da far girare la testa. E posso dirvelo: il salto tra configurare un agente di coding e progettare un harness enterprise non è incrementale. È un’altra disciplina.

La conversazione è ferma allo strato dello sviluppatore

Il dibattito attuale sull’harness engineering si concentra quasi solo sulla configurazione a livello di sviluppatore: file di istruzioni per l’agente, tuning dei prompt, selezione dei tool, pattern di sub-agenti. Sono tecniche vere e utili. OpenAI ci ha scritto sopra. Martin Fowler le ha dato un nome. Mitchell Hashimoto le pratica ogni giorno.

Ma c’è un problema: tutto questo presuppone uno sviluppatore, un repository, una sessione dell’agente. In azienda non funziona così.

In enterprise avete più team che condividono la stessa codebase. Avete decisioni architetturali prese dieci anni fa che nessuno ha documentato. Avete responsabili della compliance che pretendono un audit trail di ogni riga generata da un agente. Avete pipeline di CI che impiegano 40 minuti, non 4 secondi.

L’harness per questo ambiente non somiglia per niente a un CLAUDE.md scritto bene.

Il context engineering è un pilastro, non l’edificio

Sta emergendo una lettura che tratta l’harness engineering come un sottoinsieme del context engineering: dai all’agente il contesto giusto, e il resto viene da sé. Credo che sia il ragionamento inverso, almeno in ambito enterprise.

Il context engineering è determinante. In FairMind abbiamo costruito quello che chiamiamo Project Context: in sostanza un gemello digitale della codebase aziendale. Dà ai nostri agenti una conoscenza strutturata e aggiornata di architettura, dipendenze, convenzioni e decisioni del team. Non un file markdown piatto, ma un knowledge graph vivo che evolve insieme al codice.

Ma il contesto da solo non rende gli agenti affidabili in produzione. Servono almeno altri tre pilastri.

I vincoli architetturali sono limiti meccanici a ciò che l’agente può fare. Non “per favore non modificare il modulo di autenticazione” scritto in un prompt. Veri layer di dipendenze che lo rendono impossibile. Regole di lint che rifiutano il codice non conforme prima che arrivi in review. Gate di CI che intercettano automaticamente le violazioni architetturali. In azienda non potete contare sul fatto che il modello segua le istruzioni nel 98% dei casi. Vi serve che il 2% di fallimento venga intercettato meccanicamente.

I feedback loop sono cicli di verifica automatica. Non “lancia la test suite quando l’agente si ferma”: quella è la versione base. I feedback loop enterprise comprendono test di integrazione cross-service, controlli di regressione sulle performance, scansioni di sicurezza e telemetria che vi dice se il codice dell’agente funziona davvero in staging, molto prima che si avvicini alla produzione.

La garbage collection è quella di cui non parla nessuno. Il codice generato dall’AI accumula debito tecnico più in fretta del codice scritto dalle persone, perché gli agenti ottimizzano per il completamento del task, non per la manutenibilità nel tempo. Qualcuno deve ripulire gli import morti, le astrazioni ridondanti, i file di test che verificano i dettagli implementativi invece del comportamento. Nel progetto personale di uno sviluppatore lo fate a mano. In azienda vi servono sistemi automatici, altrimenti la codebase si degrada nel giro di settimane.

Context engineering, vincoli architetturali, feedback loop, garbage collection. Quattro pilastri. Toglietene uno e l’harness cede sotto la pressione della scala enterprise.

L’harness vero non è un agente. È un sistema orchestrato.

L’idea di usare i sub-agenti come “firewall di contesto” sta prendendo piede nella comunità degli sviluppatori. Isolare ogni task nella sua finestra di contesto, tenere pulita la sessione principale, restituire solo risultati condensati. Pattern intelligente.

Ma c’è una differenza tra lanciare a mano dei sub-agenti da Claude Code e mettere in campo agenti specializzati lungo l’intero ciclo di vita del software, orchestrati da un harness che ne governa le interazioni e mantiene la coerenza sul progetto.

In FairMind non abbiamo un agente che fa tutto. Ne abbiamo cinque, ciascuno progettato per una fase distinta dell’SDLC:

Nova si occupa del brainstorming di business, crea le epiche e organizza la roadmap di prodotto. Prima che esista una sola riga di codice, Nova traduce l’intento di business in piani di sviluppo strutturati.

Sage trasforma quei piani in user story, sia di business sia tecniche. Fa da ponte tra quello che vuole il team di prodotto e quello che il team di ingegneria deve costruire.

Echo prende le user story di Sage e crea i task di sviluppo analizzando il codice esistente in ogni repository dentro il Project Context. Non tira a indovinare su cosa vada cambiato. Lo sa, perché ha il quadro completo della codebase.

Atlas è l’architetto. Brainstorming tecnico, analisi di impatto sulle change request, supporto al debugging distribuito, generazione di documentazione. Quando arriva una richiesta di modifica, Atlas sa dirvi quali servizi sono coinvolti prima che qualcuno apra un file.

Tess genera i piani di test direttamente dalle user story, così la copertura viene progettata insieme alla feature, non appiccicata dopo.

Questi agenti non lavorano isolati. Condividono il Project Context. Sanno cosa hanno fatto gli altri. Quando Echo crea i task, conosce già i vincoli architetturali di Atlas. Quando Tess genera i piani di test, conosce già i criteri di accettazione di Sage.

Questa non è configurazione. È platform engineering per agenti AI. E l’harness che la orchestra è il prodotto.

Rilasciamo anche in open source una suite di agenti per Claude Code (Atlas, Echo, Tess, Shield, Debug Inspector) che porta alcuni di questi pattern ai singoli sviluppatori. Ma l’orchestrazione a livello di piattaforma: è lì che vive l’harness engineering enterprise.

Harness enterprise significa vincoli enterprise

Ecco una cosa che non entra quasi mai nella conversazione sull’harness engineering: la governance.

In Europa, mettere in produzione agenti AI che generano codice richiede un trattamento dei dati conforme al GDPR. Richiede audit trail. Richiede la capacità di spiegare, a posteriori, perché l’agente ha preso una certa decisione. Non “perché l’ha detto il modello”. Tracciabilità reale, dal requisito all’implementazione.

L’AI Act sta spingendo ancora oltre. E controintuitivamente, è un vantaggio. La regolamentazione vi costringe a costruire harness migliori. Quando dovete dimostrare che il vostro agente ha operato entro confini definiti, quei confini li progettate bene fin dall’inizio. L’harness non è opzionale. È un obbligo di legge.

Con l’architettura di FairMind potete tracciare una linea che va dall’epica di Nova, alla user story di Sage, al task di Echo, all’analisi di impatto di Atlas, al piano di test di Tess. Ogni decisione è documentata. Ogni azione degli agenti è loggata. Non è una funzionalità aggiunta per la compliance. È la conseguenza naturale di aver costruito un harness fatto bene.

Per questo credo che l’Europa produrrà alcuni degli harness più solidi al mondo. Non nonostante la regolamentazione, ma grazie a quella.

Il 95% è dove sta il vantaggio competitivo

Configurare un CLAUDE.md lo sanno fare tutti. Gli strumenti migliorano ogni mese. Presto ogni sviluppatore avrà un setup dignitoso.

Ma costruire un harness che regge un team di ingegneria da 200 persone, su 15 microservizi, con obblighi normativi, garbage collection automatica e cinque agenti specializzati orchestrati che condividono un Project Context vivo: quello è il 95%.

Quello è harness engineering.

E in questo momento lo stanno costruendo in pochissimi. Noi sì.

Per l’architettura tecnica dietro Project Context, trovate tutto sul blog di FairMind.

Configuring a CLAUDE.md file is not harness engineering. It’s the first 5% of it.

I keep seeing the same pattern on X: someone writes a great CLAUDE.md, adds a few MCP servers, maybe a hook or two, and calls it “harness engineering.” And look, that’s a solid start. But if you’ve only worked with a single developer’s repo, you haven’t seen what harness engineering actually demands.

I’ve spent the last two years building harnesses for European enterprise clients. Codebases with 2M+ lines. Legacy systems nobody wants to touch. Compliance requirements that make your head spin. And I can tell you: the gap between configuring a coding agent and engineering an enterprise harness is not incremental. It’s a different discipline.

The conversation right now is stuck at the developer layer

The current discourse around harness engineering focuses almost entirely on developer-level configuration: agent files, prompt tuning, tool selection, sub-agent patterns. These are real and useful techniques. OpenAI wrote about it. Martin Fowler named it. Mitchell Hashimoto practices it daily.

But here’s the problem: all of this assumes one developer, one repo, one agent session. Enterprise doesn’t work like that.

In enterprise, you’re dealing with multiple teams sharing the same codebase. You’re dealing with architectural decisions made ten years ago that nobody documented. You’re dealing with compliance officers who need an audit trail of every line an agent generates. You’re dealing with CI pipelines that take 40 minutes, not 4 seconds.

The harness for this environment looks nothing like a well-crafted CLAUDE.md.

Context engineering is one pillar, not the whole building

There’s a framing emerging that treats harness engineering as a subset of context engineering: give the agent the right context, and the rest follows. I think this gets it backwards, at least for enterprise.

Context engineering is critical. At FairMind, we built what we call Project Context: essentially a digital twin of the enterprise codebase. It gives our agents structured, up-to-date knowledge about architecture, dependencies, conventions, and team decisions. Not a flat markdown file, but a living knowledge graph that evolves with the codebase.

But context alone doesn’t make agents reliable in production. You need at least three more pillars.

Architectural constraints are mechanical limits on what the agent can do. Not “please don’t modify the auth module” in a prompt. Actual dependency layers that make it impossible. Linting rules that reject non-compliant code before it reaches review. CI gates that catch architectural violations automatically. In enterprise, you can’t rely on the model following instructions 98% of the time. You need the 2% failure case to be caught mechanically.

Feedback loops are automated verification cycles. Not “run the test suite when the agent stops.” That’s the basic version. Enterprise feedback loops include cross-service integration tests, performance regression checks, security scans, and telemetry that tells you whether the agent’s code actually works in staging before it gets anywhere near production.

Garbage collection is the one nobody talks about. AI-generated code accumulates technical debt faster than human-written code because agents optimize for task completion, not long-term maintainability. Someone has to clean up the dead imports, the redundant abstractions, the test files that test implementation details instead of behavior. In a developer’s personal project, you do this manually. In enterprise, you need automated systems for it, or your codebase degrades within weeks.

Context engineering, architectural constraints, feedback loops, garbage collection. Four pillars. Remove any one and the harness collapses under enterprise-scale pressure.

The real harness isn’t one agent. It’s an orchestrated system.

The idea of using sub-agents as “context firewalls” is gaining traction in the developer community. Isolate each task into its own context window, keep the parent session clean, return only condensed results. Smart pattern.

But there’s a difference between manually spawning sub-agents from Claude Code and deploying specialized agents across the entire software development lifecycle, orchestrated by a harness that manages their interactions and maintains coherency across the project.

At FairMind, we don’t have one agent that does everything. We have five, each designed for a distinct phase of the SDLC:

Nova handles business brainstorming, creates epics, and organizes the product roadmap. Before a single line of code exists, Nova translates business intent into structured development plans.

Sage turns those plans into user stories, both business-facing and technical. It bridges the gap between what the product team wants and what the engineering team needs to build.

Echo takes Sage’s user stories and creates development tasks by analyzing the existing code across every repository inside the Project Context. It doesn’t guess what needs to change. It knows, because it has the full picture of the codebase.

Atlas is the architect. Technical brainstorming, impact analysis on change requests, support for distributed debugging, documentation generation. When a change request arrives, Atlas can tell you which services are affected before anyone opens a file.

Tess generates test plans directly from user stories, ensuring coverage is designed alongside the feature, not bolted on afterward.

These agents don’t just run in isolation. They share the Project Context. They understand what the other agents have done. When Echo creates tasks, it already knows Atlas’s architectural constraints. When Tess generates test plans, it already knows Sage’s acceptance criteria.

This isn’t configuration. This is platform engineering for AI agents. And the harness that orchestrates it is the product.

We also open-source a suite of agents for Claude Code (Atlas, Echo, Tess, Shield, Debug Inspector) that bring some of these patterns to individual developers. But the platform-level orchestration: that’s where enterprise harness engineering lives.

Enterprise harness means enterprise constraints

Here’s what almost never comes up in the harness engineering conversation: governance.

In Europe, deploying AI agents that generate production code requires GDPR-compliant data handling. It requires audit trails. It requires the ability to explain, after the fact, why the agent made a specific decision. Not “because the model said so.” Actual traceability from requirement to implementation.

The AI Act is pushing this further. And counterintuitively, this is an advantage. Regulation forces you to build better harnesses. When you must prove that your agent operated within defined boundaries, you design those boundaries properly from the start. The harness isn’t optional. It’s legally required.

With FairMind’s architecture, you can trace a line from Nova’s epic, through Sage’s user story, to Echo’s task, to Atlas’s impact analysis, to Tess’s test plan. Every decision is documented. Every agent action is logged. That’s not a feature we added for compliance. It’s a natural consequence of building a proper harness.

This is why I believe Europe will produce some of the most robust harness engineering in the world. Not despite regulation, but because of it.

The 95% is where the moat lives

Anyone can configure a CLAUDE.md. The tooling is getting better every month. Soon, every developer will have a decent agent setup.

But building a harness that works for a 200-person engineering team, across 15 microservices, with regulatory compliance, automated garbage collection, and five orchestrated specialized agents sharing a living Project Context: that’s the 95%.

That’s harness engineering.

And right now, very few people are building it. We are.

For the technical architecture behind Project Context, see the FairMind blog.

Configurare un CLAUDE.md non è harness engineering. Ecco com’è fatto l’altro 95%. Configuring a CLAUDE.md Is Not Harness Engineering. Here’s What the Other 95% Looks Like.