Come smettere di scrivere codice a mano e iniziare a progettare imbracature per le reti neurali

Recentemente mi sono ritrovato a provare una strana sensazione. Sei seduto in un editor, lanci un agente come Claude Code o Cursor, gli assegni un compito, e dieci minuti dopo stai cercando di districarti tra un casino di funzioni inventate e tipi rotti. Provando a dettare un prompt di sistema di cinque pagine di solito le cose peggiorano: il modello dimentica l'inizio dell'istruzione al terzo passaggio.

Si scopre che nella comunità ingegneristica attorno a OpenAI, Anthropic e Cursor, questo problema è già stato formalizzato in una disciplina separata. Si chiama Harness Engineering, che può essere tradotto come progettare imbracature o briglie per gli agenti.

Il repository deusyu/harness-engineering ha raccolto un'ampia base di conoscenza su questo argomento in un unico posto: analisi di concetti, traduzioni di decine di articoli in inglese da ingegneri come Martin Fowler, LangChain e i creatori di Bun, oltre a template pronti all'uso per implementare questo approccio nei propri progetti.

Da dove è venuta l'idea

Se nello sviluppo classico una persona scrive il codice e la macchina lo esegue, con l'arrivo degli agenti autonomi la catena cambia. Una persona formula vincoli e regole del gioco, la rete neurale scrive il codice, e l'ambiente esegue controlli e restituisce feedback all'agente.

Il punto è che l'ingegnere smette di essere l'autore di ogni riga. Il prodotto principale dell'ingegnere diventa un sistema di vincoli: file di configurazione AGENTS.md, linter personalizzati, test strutturali e gate rigorosi nella CI.

Il repository cita i dati di un esperimento reale condotto da uno dei team: in oltre 5 mesi, un team di 3-7 persone ha unito circa 15.000 pull request per un totale di quasi un milione di righe di codice, chiudendo in media 3,5 PR per persona al giorno. La maggior parte della generazione è avvenuta durante la notte in sessioni di sei ore.

Principi fondamentali dell'Harness Engineering

L'autore del repository scompone l'approccio in diversi concetti applicati.

Il repository come unica fonte di verità

Tutto ciò che non è all'interno di un repository git non esiste per l'agente. Le tue chiamate Zoom, le discussioni architetturali su Slack o le bozze su Google Docs non entrano nel contesto del modello.

Se hai deciso di modificare una firma API o hai concordato una struttura di cartelle, questo deve risiedere nel repository come file versionati. Qualsiasi specifica e piano di task vengono immediatamente committati su un branch.

Una mappa invece di un'enciclopedia

Un errore comune quando si imposta lo sviluppo agentico è creare un enorme file di sistema con tutte le istruzioni del progetto. I modelli si sovraccaricano di prompt troppo lunghi.

Invece, viene utilizzato un file AGENTS.md di circa 100 righe. Funziona come un sommario o mappa del terreno, indicando all'agente quali sottodirectory consultare per i dettagli in base al compito. Ogni sottodirectory contiene il proprio file AGENTS.md locale. Questo principio è chiamato disclosure progressiva del contesto.

Controllo meccanico invece di persuasione verbale

Le regole testuali nella documentazione diventano rapidamente obsolete, e gli agenti tendono a ignorarle o misinterpretarle. I linter e i test unitari non diventano obsoleti.

Invece di descrizioni dettagliate dello stile architetturale, vengono scritti linter personalizzati. La parte più interessante: i messaggi di errore in questi linter contengono immediatamente istruzioni chiare per risolvere il problema. L'agente esegue il controllo, rileva l'errore del linter, legge il testo del suggerimento e riscrive autonomamente la sezione di codice problematica.

Leggibilità del codice per gli agenti e gestione dell'entropia

Quando si scelgono le librerie, viene data priorità a tecnologie stabili, ben documentate e con comportamenti prevedibili. Se una libreria è troppo complessa o utilizza magia metaprogrammativa oscura, l'agente inciamperà costantemente. A volte è più semplice implementare un modulo interno semplice da zero piuttosto che far indovinare alla rete neurale il comportamento di un pacchetto esterno opaco.

Inoltre, gli agenti amano copiare i pattern errati se li trovano nel codebase esistente. Per prevenire il decadimento del repository, agenti di refactoring specializzati vengono eseguiti in background, il cui compito è ridotto a trovare deviazioni dagli standard e creare PR correttivi.

Repository autoreferenziale

Ciò che rende il progetto deusyu/harness-engineering interessante è che è costruito sui principi stessi che descrive.

All'interno del repository viene eseguito uno script scripts/check-consistency.sh rigoroso, attivato tramite pre-commit hooks e GitHub Actions. Lo script verifica tredici livelli di integrità:

• Verifica il numero esatto di articoli menzionati nei badge e nella documentazione
• Monitora che la struttura delle directory corrisponda all'albero dei file dichiarato
• Valida tutti i link e le tabelle
• Controlla gli audit delle immagini nelle traduzioni degli articoli affinché nessun diagramma degli originali venga perso

Il processo di aggiunta di nuovi materiali è automatizzato attraverso una skill Claude specializzata, dove gli agenti eseguono il parsing e la formattazione iniziale degli articoli, mentre un essere umano agisce solo come censore finale.

Per chi è questo progetto

Se scrivi progetti personali da solo o vuoi configurare un lavoro efficiente con Cursor, Claude Code, Aider o modelli locali nel tuo team, questo repository merita di essere salvato nei preferiti.

Non ci sono pulsanti magici o binari pronti all'uso qui. Questo è un manuale e una raccolta di esperienza ingegneristica, che spiega perché i tuoi prompt smettono di funzionare con la distanza e come configurare il repository affinché le reti neurali portino benefici invece di trasformare il codebase in una discarica.

Il modo più semplice per iniziare a imparare è con i file nella directory concepts/, poi guarda l'implementazione di AGENTS.md alla radice del progetto e prova ad adottare una struttura simile per i tuoi repository di lavoro.