Il repository è il contratto 📜
C’è un momento in ogni progetto in cui qualcuno (di solito il più stanco della squadra) scrive un file di testo con dentro le regole del gioco. Lo chiama AGENTS.md, lo commita, e spera che tutti — umani e macchine — lo rispettino.
Non è un file di configurazione tecnica. Non è un README aggiornato male. È qualcosa di più sottile e più potente: è il contratto sociale del repository. Quel patto non scritto (anzi, scritto eccome) che dice come lavoriamo, cosa non si tocca, e cosa ci aspettiamo gli uni dagli altri.
E quando “gli altri” includono un agente AI, il contratto diventa ancora più importante. Perché un agente che non conosce le regole non è pericoloso: è imprevedibile. E l’imprevedibilità, in un progetto software, si traduce in bug, tech debt, e meeting dove tutti si guardano in faccia chiedendosi “chi ha fatto questo?”.
Il contratto che non sai di avere 🧾
Ogni squadra ha un suo modo di fare le cose. Alcune regole sono documentate, altre vivono solo nelle menti dei senior che “sono lì da sempre”. Il problema è che un agente AI non può leggere il pensiero. Non sa che il modulo legacy/auth è sacro e non va toccato dopo le 17 di venerdì. Non sa che i commit devono seguire Conventional Commits. Non sa che i test vanno eseguiti prima di ogni PR.
L’AGENTS.md non è un manuale: è un set di vincoli operativi che l’agente applica senza bisogno di istruzioni ripetute.
Senza un contratto chiaro, l’agente opera per analogia. E le analogie, come sappiamo, sono il modo più elegante per fare Errori Elegantissimi™.
Il bello è che il contratto è già lì, anche senza un file dedicato. Solo che in quel caso è implicito, fragile, e vive nella testa di una sola persona. Quando quella persona è in ferie, il contratto evapora. Con un AGENTS.md, il patto diventa oggettivo: non dipende da chi è in squadra oggi, ma da cosa il progetto richiede sempre.
Conoscenza condivisa, non documentazione morta 🧠
La differenza tra un AGENTS.md ben scritto e un wiki dimenticato è sottile ma sostanziale. Il wiki dice “queste sono le nostre best practice”. Il contratto dice “queste sono le regole che applichi ora, senza discussioni”.
Non è documentazione passiva. È conoscenza attiva: qualcosa che l’agente legge, interpreta e usa per prendere decisioni. È come passare al nuovo assunto un foglio con le regole della casa, non un librone da leggere “quando hai tempo”.
La differenza sta nell’atteggiamento. Il wiki è consultivo: “puoi guardarla se vuoi”. Il contratto è operativo: “questo è il modo in cui lavori”. E quando il “tu” è un agente che processa migliaia di token al minuto, la distinzione tra consultivo e operativo si traduce nella differenza tra output coerente e rumore plausibile.
E qui entra il collegamento con un tema che abbiamo già esplorato: mantenere un contesto agentico ricco non è solo una questione di prompt ben scritti. È una questione di struttura del repository. Il contesto deve essere lì, nei file, versionato, revisionabile, vivo.
La gerarchia del patto 🏗️
Un singolo AGENTS.md nella root funziona per progetti semplici. Ma quando il progetto cresce, il contratto deve adattarsi.
La soluzione è la gerarchia: un file root con le regole generali, e file specifici nelle subdirectory che gestiscono le eccezioni. Come una costituzione con delle leggi locali. Il principio è lo stesso che si applica alla configurazione del repository: il contesto si stratifica, e ogni livello aggiunge precisione senza duplicare.
Un monorepo senza gerarchia di contesto è come un paese senza tribunali locali: tutto finisce al parlamento, e il parlamento è sempre in backlog.
In un monorepo, questa gerarchia diventa essenziale. Ogni package ha le sue regole, ma condivide un nucleo di vincoli. Senza gerarchia, o duplichi ovunque (e poi devi mantenerli tutti), o lasci buchi (e l’agente indovina).
La cosa elegante è che la gerarchia rispecchia già il modo in cui pensiamo al codice: moduli, package, livelli di astrazione. Il contratto segue la stessa logica. Non è un extra: è la traduzione documentale dell’architettura.
Il contratto come memoria collettiva 🧬
Qui il discorso si fa filosofico, ma non per partito preso.
Quando un team definisce il proprio AGENTS.md, sta facendo qualcosa di più profondo di “scrivere delle regole”. Sta esternalizzare la memoria collettiva. Le decisioni passate, i compromessi accettati, le trappole evitate — tutto viene compresso in un file che può essere letto da chiunque, umano o macchina.
È lo stesso meccanismo che sta alla base della mente collettiva e dello stato intraducibile: quando la conoscenza vive solo nelle teste dei singoli, è fragile. Quando viene esternalizzata, diventa robusta. Ma anche quando viene compressa, qualcosa si perde.
Un AGENTS.md non può catturare tutto. Non può dire “questa funzione è scritta così perché Marco aveva fretta il 14 marzo”. Ma può dire “questo modulo ha test deboli, procedi con cautela”. È una compressione con perdita, ma è meglio di niente.
E qui sta il paradosso bello: più il contratto è preciso, meno è “umano”. Ma più è vago, meno è utile. Trovare il punto giusto — abbastanza specifico da essere applicabile, abbastanza flessibile da sopravvivere ai cambiamenti — è un’arte. Un’arte che, per fortuna, si può versionare.
Quando il contratto si rompe 💥
Un contratto non serve a nulla se non ha conseguenze. E un AGENTS.md senza enforcement è solo un file di testo con delle buone intenzioni.
Le conseguenze, nel mondo degli agenti, sono diverse:
- L’agente ignora le regole e genera output incoerente
- Il team perde fiducia nel processo e torna a fare tutto a mano
- Il repository accumula tech debt perché nessuno applica i vincoli
E c’è un effetto collaterale sottile: quando il contratto viene ignorato troppo spesso, il team smette di crederci. Diventa quel file che “c’è ma non guarda nessuno”. E un contratto che nessuno rispetta è peggio di nessun contratto, perché insegna al team che le regole sono opzionali.
La soluzione non è “più regole”. È regole chiare, verificabili e maintainate. Ogni volta che l’agente fa qualcosa che non avresti voluto, aggiorni il contratto. Ogni volta che una regola non serve più, la elimini. Il file vive e respira con il progetto.
Il futuro: contratti vivi 🌱
Stiamo andando verso un mondo in cui il repository non è solo un contenitore di codice, ma un sistema cognitivo condiviso. Il codice è il “cosa”, il AGENTS.md è il “come” e il “perché”.
Questo cambia il modo in cui pensiamo alla documentazione. Non più come un’appendice noiosa, ma come una componente architetturale. Non più “da scrivere quando si ha tempo”, ma “da mantenere come si mantiene il codice”.
E cambia anche il modo in cui pensiamo ai team. Un buon contratto non è solo un vantaggio tecnico: è un vantaggio culturale. Costringe il team a esplicitare ciò che dà per scontato. A chiedersi: “le nostre regole sono scritte da qualche parte, o vivono solo nella nostra testa?”.
La risposta, nella maggior parte dei casi, è scomoda. Ma almeno ora c’è un posto dove scriverla.
Ed è esattamente qui che il contratto si trasforma da vincolo a risorsa: non è più qualcosa che ti dice cosa non puoi fare, ma qualcosa che ti ricorda perché lo fai in un certo modo.
Il repository è il contratto. Il contratto è la conoscenza. La conoscenza è il potere — ma solo se è condivisa e viva.
E forse, alla fine, questa è la lezione più importante: un buon contratto non è quello che tutti firmano, ma quello che tutti rispettano. Anche quando nessuno guarda. Specialmente quando è una macchina a doverlo rispettare.