Cosa Imparerai

Questa guida copre la harness engineering dai principi fondamentali all'implementazione pratica. Capirai cos'è, perché OpenAI ha scommesso il suo più grande progetto interno su di essa, i pattern architetturali specifici che la fanno funzionare e come applicare questi principi ai tuoi workflow di AI agent — sia che tu stia usando Codex, Claude Code, OpenCode o qualsiasi altro sistema di agent.

Harness Engineering: La Guida Completa per lo Sviluppo di AI Agent nel 2026

Se il 2025 è stato l'anno in cui gli AI agent hanno dimostrato di poter scrivere codice, il 2026 è l'anno in cui abbiamo imparato che l'agent non è la parte difficile — la harness lo è.

Il team Codex di OpenAI ha pubblicato un post fondamentale sul blog nel February 2026 descrivendo come hanno costruito un'applicazione di produzione contenente circa 1.000.000 di linee di codice dove zero linee sono state scritte da mani umane. Il segreto non era un modello migliore o un prompt più intelligente. Era il sistema che hanno costruito intorno all'agent — la harness. Source

Questa guida analizza ogni principio, pattern e tecnica pratica di quell'esperimento e del più ampio movimento di harness engineering che ne è scaturito.

Parte 1: Cos'è la Harness Engineering?

La Definizione

La harness engineering è la disciplina di progettare l'intero ambiente — scaffolding, feedback loops, documentazione, vincoli architetturali e artefatti leggibili dalle macchine — che consente agli AI coding agents di svolgere un lavoro affidabile e di alta qualità su vasta scala con un minimo intervento umano.

Il termine "harness" (imbracatura) deriva dai finimenti dei cavalli: redini, sella, morso — il set completo di attrezzature per incanalare un animale potente ma imprevedibile nella giusta direzione. Un cavallo incontrollato è pericoloso. Un cavallo con la harness ha costruito civiltà. Lo stesso vale per gli AI agents. Source

Perché è Emersa Ora

Il passaggio dalla prompt engineering alla harness engineering riflette una maturazione del panorama dello sviluppo AI:

Source

L'intuizione chiave che ha guidato questa transizione: gli agent sono diventati abbastanza capaci che il collo di bottiglia si è spostato dalla qualità del modello alla qualità dell'ambiente. Un modello state-of-the-art che opera in una repository strutturata male produce risultati peggiori di un modello mediocre che opera in un ambiente con una buona harness.

Parte 2: L'Esperimento OpenAI Codex

La Scala

In un esperimento interno di 5 mesi, gli ingegneri di OpenAI hanno costruito e rilasciato un prodotto beta contenente circa 1.000.000 di linee di codice. La repository spazia dalla logica applicativa, infrastruttura, tooling, documentazione e utility interne per sviluppatori. Non c'era codice pre-esistente scritto da umani per ancorare il sistema. Source

Il Team

Il progetto è iniziato con solo 3 ingegneri che guidavano Codex. Nel periodo di 5 mesi, circa 1.500 pull requests sono state aperte e unite. Man mano che il team cresceva a 7 ingegneri, il throughput aumentava — un risultato controintuitivo che suggeriva che la harness stessa fosse il principale moltiplicatore di produttività, non l'abilità individuale.

OpenAI stima di aver costruito il sistema in circa 1/10 del tempo che sarebbe stato necessario per scrivere il codice a mano. Source

Lo Scaffold Iniziale

Il progetto è iniziato con Codex CLI che generava lo scaffold iniziale usando GPT-5, guidato da un piccolo set di template esistenti:

• Struttura della repository e convenzioni delle directory
• Configurazione CI/CD
• Formattazione del codice e regole di linting
• Setup del package manager
• Boilerplate del framework applicativo

Da questo seme, tutto il resto è cresciuto attraverso lo sviluppo guidato dagli agent.

Il Problema del Venerdì

All'inizio dell'esperimento, il team ha scoperto un problema critico: passavano ogni venerdì — il 20% del loro tempo di ingegneria — a pulire ciò che chiamavano "AI slop". Questo includeva pattern incoerenti, logica duplicata, variabili con nomi errati e deriva architetturale.

Questo non era scalabile. La soluzione è stata codificare i loro standard nella harness stessa in modo che gli agent producessero output più puliti fin dall'inizio, e costruire sistemi automatizzati di pulizia per la deriva residua.

Parte 3: I Cinque Principi Fondamentali

Principio 1: Repository-First Knowledge

Dal punto di vista dell'agent, tutto ciò a cui non può accedere in-context durante l'esecuzione effettivamente non esiste. La conoscenza che risiede in Google Docs, thread di chat, messaggi Slack o nelle teste delle persone è invisibile al sistema.

Ciò significa che tutta la conoscenza deve risiedere come artefatti versionati locali alla repository:

• Codice — l'artefatto primario
• Documentazione Markdown — decisioni architetturali, convenzioni, guide all'onboarding
• Schemas — contratti API, database schemas, definizioni di tipi
• Piani eseguibili — suddivisioni delle attività passo dopo passo che l'agent può seguire
• Configurazione — regole linter, CI pipelines, standard di formattazione

Il team ha imparato che doveva spingere sempre più contesto nella repo nel tempo. Ogni volta che un agent commetteva un errore perché mancava di contesto, la soluzione non era un prompt migliore — era aggiungere quel contesto alla repository. Source

Implementazione pratica:

# ARCHITECTURE.md (lives in repo root)

## Dependency Rules
- UI components may import from Service layer but never from Repo layer
- Service layer may not import from Runtime layer
- All cross-domain communication goes through typed event bus

## Naming Conventions
- React components: PascalCase, suffixed with purpose (UserListPage, UserCard)
- Services: camelCase, suffixed with Service (userService, authService)
- Types: PascalCase, prefixed with domain (UserProfile, OrderItem)

## Testing Requirements
- All Service functions require unit tests
- All API endpoints require integration tests
- Coverage threshold: 80% per package

Principio 2: Golden Principles

I Golden principles sono regole opinate e meccaniche codificate direttamente nella repository che mantengono la codebase leggibile e coerente per le future esecuzioni degli agent. Non sono linee guida aspirazionali — sono vincoli applicati.

Esempi dall'esperimento OpenAI:

1. Preferire pacchetti utility condivisi rispetto a helper scritti a mano — centralizza gli invarianti in modo che quando il comportamento deve cambiare, cambi in un unico posto
2. Non sondare i dati in stile YOLO — validare i confini o affidarsi a SDK tipizzati in modo che gli agent non possano accidentalmente costruire su forme di dati ipotizzate
3. Un concetto, un file — ogni file dovrebbe rappresentare un singolo concetto, rendendo più facile per gli agent trovare e modificare la posizione corretta
4. Esplicito invece di implicito — evitare comportamenti magici che richiederebbero a un agent una conoscenza tribale per essere compresi

Source

Questi principi non sono solo documentazione. Sono applicati da:

• Regole Linter — linter personalizzati (anch'essi generati da Codex) che segnalano le violazioni
• Test strutturali — test che convalidano la conformità architetturale
• CI gates — le pull requests che violano i golden principles vengono rifiutate automaticamente

Principio 3: Architettura a Livelli con Applicazione Meccanica

Ogni dominio di business nel progetto OpenAI è diviso in un set fisso di livelli con direzioni di dipendenza rigorosamente convalidate:

Types → Config → Repo → Service → Runtime → UI

Le dipendenze fluiscono in una sola direzione. Un componente UI può dipendere da Runtime e Service, ma un Service non può mai importare da UI. Un Repo può dipendere da Config e Types, ma mai da Service. Source

Questi vincoli sono applicati meccanicamente:

// structural-test.ts — enforces dependency boundaries
import { analyzeImports } from './tools/import-analyzer';

describe('Dependency Layer Enforcement', () => {
  it('Service layer must not import from Runtime', () => {
    const violations = analyzeImports({
      sourceLayer: 'service',
      forbiddenLayers: ['runtime', 'ui'],
    });
    expect(violations).toEqual([]);
  });

  it('Repo layer must not import from Service', () => {
    const violations = analyzeImports({
      sourceLayer: 'repo',
      forbiddenLayers: ['service', 'runtime', 'ui'],
    });
    expect(violations).toEqual([]);
  });
});

I test strutturali convalidano la conformità e prevengono violazioni della stratificazione modulare. Questa non è un suggerimento — è applicato dalla CI. Ogni pull request, sia essa creata da un umano o da un agent, deve superare questi test.

Principio 4: Garbage Collection Automatica

Anche con i golden principles e l'applicazione strutturale, il codice generato dagli agent devia nel tempo. Il team OpenAI ha risolto questo problema implementando una garbage collection automatica — attività in background ricorrenti che:

1. Scansionano le deviazioni dai golden principles in tutta la codebase
2. Aggiornano i gradi di qualità per ogni modulo in base ai punteggi di conformità
3. Aprono pull requests di refactoring mirate che correggono specifiche categorie di deriva

Questo ha sostituito la "pulizia del venerdì" manuale con un sistema che gira continuamente. Il garbage collector stesso è alimentato da agent Codex, creando un ciclo di auto-manutenzione. Source

# .github/workflows/garbage-collection.yml
name: Codebase Garbage Collection
on:
  schedule:
    - cron: '0 2 * * *'  # Run nightly at 2 AM

jobs:
  gc-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run golden principle scanner
        run: npx codex-gc scan --principles ./GOLDEN_PRINCIPLES.md
      - name: Generate refactoring PRs
        run: npx codex-gc fix --auto-pr --max-prs 5

Principio 5: Piani Eseguibili

Prima che gli agent scrivano codice, scrivono piani. Questi piani non sono note informali — sono documenti strutturati ed eseguibili che specificano:

• Obiettivo: Cosa realizza il compito
• File da modificare: Elenco esplicito dei file che l'agent toccherà
• Dipendenze: Altri compiti o moduli da cui dipende questo lavoro
• Criteri di accettazione: Come verificare che il lavoro sia completo
• Vincoli: Regole architetturali che non devono essere violate

# Plan: Add user notification preferences

## Objective
Allow users to configure which notification channels (email, SMS, push) they
receive alerts on, with per-category granularity.

## Files to Modify
- src/types/user.ts — Add NotificationPreferences type
- src/repo/userRepo.ts — Add getPreferences/setPreferences methods
- src/service/notificationService.ts — Filter notifications by preferences
- src/ui/pages/SettingsPage.tsx — Add preferences UI section

## Constraints
- Must follow Types → Repo → Service → UI dependency flow
- NotificationPreferences type must be shared, not duplicated
- All new methods require unit tests

## Acceptance Criteria
- [ ] User can toggle email/SMS/push per notification category
- [ ] Preferences persist across sessions
- [ ] Toggling a channel off stops notifications on that channel within 30s

I piani risiedono nella repository come file markdown, sono versionati e possono essere revisionati prima dell'esecuzione — offrendo agli umani un punto di controllo tra intenzione e implementazione.

Parte 4: Il Ciclo dell'Agent Codex

Capire come opera il ciclo dell'agent Codex all'interno di una harness è essenziale per una harness engineering efficace.

L'Architettura del Ciclo

OpenAI ha pubblicato un'analisi dettagliata del ciclo dell'agent Codex nel post di accompagnamento "Unrolling the Codex agent loop." Source Il ciclo segue questa sequenza:

Read Context → Plan → Execute → Validate → Commit (or Retry)

Ogni iterazione:

1. Read Context: L'agent legge i file rilevanti, la documentazione, gli schema e il piano del compito dalla repository
2. Plan: In base al contesto, l'agent determina quali modifiche apportare
3. Execute: L'agent scrive o modifica il codice
4. Validate: La harness esegue test, linter e controlli strutturali sulle modifiche
5. Commit or Retry: Se la validazione passa, l'agent esegue il commit. Se fallisce, l'agent legge l'output dell'errore e riprova.

Il ruolo della harness è rendere i passaggi 1 e 4 il più ricchi di informazioni possibile. Più contesto legge l'agent, migliore sarà il suo piano. Più specifico è il feedback di validazione, più velocemente convergerà verso una soluzione funzionante.

L'App Server Harness

Nel post "Unlocking the Codex harness: how we built the App Server," OpenAI descrive l'infrastruttura concreta che alimenta il ciclo dell'agent. Source L'App Server fornisce:

• Ambienti di esecuzione sandboxed per ogni compito dell'agent
• Accesso a strumenti pre-configurati (file system, terminal, browser)
• Iniezione automatica del contesto dagli artefatti della repository
• Feedback di validazione in streaming in modo che gli agent possano vedere i fallimenti dei test in tempo reale

Parte 5: Applicare la Harness Engineering al Tuo Team

Per Iniziare: La Minimum Viable Harness

Non è necessario replicare l'intera infrastruttura di OpenAI per beneficiare della harness engineering. Inizia con questi elementi fondamentali:

Step 1: Crea un ARCHITECTURE.md

Documenta le regole architetturali del tuo progetto in un formato leggibile dalle macchine nella root della tua repository. Includi:

• Confini dei moduli e dipendenze consentite
• Convenzioni di denominazione
• Regole di organizzazione dei file
• Requisiti di test

Questo singolo file migliora drasticamente la qualità dell'output dell'agent perché gli agent lo leggono prima di apportare modifiche.

Step 2: Aggiungi Test Strutturali

Scrivi test che convalidano le tue regole architetturali. Questi test non controllano la logica di business — controllano che il codice sia organizzato correttamente:

// No service file should import from a UI module
test('service layer isolation', () => {
  const serviceFiles = glob('src/services/**/*.ts');
  for (const file of serviceFiles) {
    const imports = extractImports(file);
    const uiImports = imports.filter(i => i.startsWith('../ui/'));
    expect(uiImports).toHaveLength(0);
  }
});

Step 3: Configura la Validazione CI

Assicurati che la tua pipeline CI esegua test strutturali, linter e controlli dei tipi su ogni pull request — comprese quelle create dagli agent. L'agent dovrebbe vedere lo stesso output di validazione che vedrebbe uno sviluppatore umano.

Step 4: Scrivi Piani di Lavoro Prima dell'Esecuzione dell'Agent

Prima di chiedere a un agent di implementare una funzionalità, scrivi un documento di piano strutturato che specifichi i file da modificare, i vincoli da seguire e i criteri di accettazione. Memorizza questi piani nella tua repository.

Step 5: Imposta la Pulizia Automatica

Implementa un job CI settimanale o notturno che scansiona la tua codebase alla ricerca di deviazioni dai tuoi standard documentati e crea PR di refactoring mirate.

Scegliere il Proprio Sistema di Agent

I principi della harness engineering si applicano indipendentemente dall'agent utilizzato:

La harness risiede nella tua repository, non nel tuo agent. Ciò significa che puoi cambiare agent senza perdere il tuo investimento nella harness.

Passare da un Agent a Molti

L'esperimento OpenAI ha dimostrato che la harness engineering consente l'esecuzione parallela degli agent. Poiché la harness applica i confini architetturali, più agent possono lavorare contemporaneamente su diverse parti della codebase senza creare conflitti.

Requisiti chiave per l'esecuzione parallela degli agent:

1. Chiara proprietà dei moduli — ogni agent lavora entro un confine definito
2. Interfacce tipizzate tra i moduli — gli agent possono programmare verso le interfacce senza conoscere i dettagli di implementazione
3. Prevenzione dei conflitti di merge — i compiti sono dimensionati per minimizzare la sovrapposizione dei file
4. Validazione centralizzata — tutti gli agent inviano alla stessa pipeline CI

Parte 6: Trappole Comuni e Anti-Pattern

Anti-Pattern 1: Trattare l'Agent come la Harness

L'agent non è la harness. La harness è l'ambiente in cui opera l'agent. Chiedere a un modello più intelligente di compensare una repository strutturata male è l'approccio sbagliato. Correggi l'ambiente, non il prompt.

Anti-Pattern 2: Documentazione nel Posto Sbagliato

Se le tue decisioni architetturali risiedono in Confluence, Notion o Google Docs, gli agent non possono vederle. La soluzione è semplice ma richiede disciplina: sposta tutta la documentazione rilevante per lo sviluppo nella repository.

Anti-Pattern 3: Pulizia Manuale Invece di Applicazione Automatica

Se stai passando molto tempo a pulire il codice generato dagli agent, hai bisogno di un'applicazione migliore delle regole, non di più sessioni di pulizia. Ogni attività di pulizia ricorrente dovrebbe diventare una regola linter, un test strutturale o un job di refactoring automatizzato.

Anti-Pattern 4: Eccesso di Vincoli

Una harness troppo rigida impedisce agli agent di trovare soluzioni creative. L'obiettivo è vincolare l'architettura, non l'implementazione. Indica agli agent quali moduli possono modificare e quali dipendenze sono consentite, ma lascia che decidano come implementare la logica all'interno di quei confini.

Anti-Pattern 5: Ignorare il Feedback degli Agent

Quando un agent fallisce ripetutamente in determinati compiti, il fallimento di solito indica una lacuna nella harness, non un limite dell'agent. Traccia i pattern di fallimento e usali per migliorare la tua documentazione, i test strutturali o i vincoli architetturali.

Parte 7: Il Futuro della Harness Engineering

La Prospettiva di Martin Fowler

Martin Fowler ha pubblicato un'analisi della harness engineering sul suo blog, notando che essa rappresenta un cambiamento fondamentale nel modo in cui operano i team software. La disciplina prende in prestito decenni di best practice dell'ingegneria del software — continuous integration, architecture decision records, dependency injection — ma le riutilizza per un mondo guidato dagli agent. Source

Il Framework HumanLayer

Il team di HumanLayer ha pubblicato un'analisi definendo la harness engineering un "problema di competenze" (skill issue) — sostenendo che la capacità di progettare harness efficaci diventerà il principale differenziatore tra i team di ingegneria ad alte prestazioni e quelli in difficoltà. Source

Cosa Significa per gli Sviluppatori

La harness engineering non sostituisce le competenze degli sviluppatori — le reindirizza. Invece di scrivere codice, gli ingegneri senior progettano i sistemi che consentono agli agent di scrivere bene il codice. Le competenze che contano si spostano dall'implementazione all'architettura, dalla programmazione al design del sistema, dalla scrittura di test alla progettazione di framework di test.

Per i team che costruiscono applicazioni, piattaforme come ZBuild stanno già incorporando i principi della harness engineering nei loro workflow di app builder. Invece di richiedere agli sviluppatori di progettare le proprie harness da zero, ZBuild fornisce pattern architetturali pre-configurati, gestione delle dipendenze e sistemi di validazione che guidano gli AI agent verso output di alta qualità — lasciando che gli sviluppatori si concentrino sulle decisioni di prodotto piuttosto che sull'infrastruttura.

I Tre Orizzonti

Guardando al futuro, è probabile che la harness engineering si evolva attraverso tre fasi:

1. Breve termine (2026): I team adottano documentazione repository-first, test strutturali e golden principles. Lo sviluppo assistito da agent diventa una pratica standard per i progetti con una buona harness.

2. Medio termine (2027): La generazione della harness stessa diventa guidata dagli agent. Gli agent analizzano le codebase esistenti e propongono configurazioni per la harness — regole linter, test strutturali, confini delle dipendenze — in base ai pattern che osservano.

3. Lungo termine (2028+): Le harness diventano adattive. Invece di regole statiche, si evolvono in base ai risultati del codice generato dagli agent, restringendo automaticamente i vincoli nelle aree in cui gli agent producono spesso errori e allentandoli dove hanno successo costante.

Parte 8: Checklist Pratica

Usa questa checklist per valutare la maturità della harness engineering del tuo team:

Fondamenta (Inizia qui)

• ARCHITECTURE.md esiste nella root della repository
• La formattazione del codice è automatizzata (Prettier, Black, gofmt)
• Il linting viene eseguito su ogni pull request
• Il controllo dei tipi è obbligatorio (TypeScript strict, mypy, ecc.)

Intermedio

• I test strutturali convalidano i confini delle dipendenze
• I golden principles sono documentati e applicabili meccanicamente
• I piani di lavoro vengono scritti prima dell'esecuzione dell'agent
• Le PR generate dagli agent passano attraverso la stessa CI delle PR umane

Avanzato

• La garbage collection automatica viene eseguita regolarmente
• Più agent possono lavorare in parallelo senza conflitti
• I pattern di fallimento degli agent vengono tracciati e usati per migliorare la harness
• La harness stessa è versionata e revisionata come il codice

Esperto

• Gli agent generano parti della harness (regole linter, test strutturali)
• I gradi di qualità vengono assegnati automaticamente a ogni modulo
• I miglioramenti della harness sono guidati dai dati basati sui tassi di successo degli agent
• Il team rilascia più codice per ingegnere a settimana rispetto a prima di adottare gli agent

Conclusione

La harness engineering non è una moda passeggera. È l'evoluzione naturale dell'ingegneria del software in un'era in cui gli AI agent sono abbastanza capaci di scrivere codice di produzione ma hanno bisogno di ambienti strutturati per farlo bene. L'esperimento da un milione di linee di OpenAI ha dimostrato il concetto su vasta scala, e i principi che hanno articolato — conoscenza repository-first, golden principles, architettura a livelli, garbage collection automatica e piani eseguibili — sono applicabili a team di qualsiasi dimensione.

I team che padroneggeranno la harness engineering nel 2026 rilasceranno più velocemente, manterranno una qualità del codice più elevata e scaleranno in modo più efficace rispetto a quelli che trattano gli AI agent come un semplice autocomplete avanzato. L'agent è il cavallo. La harness è ciò che lo rende utile.

Fonti

• Harness Engineering: Leveraging Codex in an Agent-First World — OpenAI
• Unlocking the Codex Harness: How We Built the App Server — OpenAI
• Unrolling the Codex Agent Loop — OpenAI
• OpenAI Introduces Harness Engineering — InfoQ
• Harness Engineering — Martin Fowler
• Skill Issue: Harness Engineering for Coding Agents — HumanLayer
• From Prompt Engineering to Harness Engineering — SoftmaxData
• How to Build an Agent Harness — Study Notes
• Harness Engineering — GTCode
• OpenAI Harness Engineering: Ship 1M Lines of Code — The Neuron
• How OpenAI Built 1M Lines of Code Using Only Agents — TonyLee
• Harness Engineering — The New Discipline — CodeNote