Il problema
Siamo onesti: non vogliamo più leggere il codice. Non vogliamo verificare tutto ciò che fanno gli agenti, né tenere a mente ogni dettaglio tecnico del progetto.
Ma se nessuno controlla gli agenti, trasformeranno qualsiasi progetto in un caos immantenibile che né un umano né un agente riuscirà a districare. È solo questione di tempo.
L'idea
HUMAN-INTENT.md è un file nella radice del tuo repository. Contiene la tua intenzione: l'architettura del progetto, le regole di sviluppo e le decisioni di prodotto.
Non è la documentazione del codice. È la legge a cui il codice deve obbedire.
Le regole
-
Lo scrivi tu — e solo tu
Gli agenti non modificano mai questo file. Ogni riga è una decisione presa da un umano.
-
Le sue istruzioni sono legge per l'agente
Ciò che dice HUMAN-INTENT.md prevale su tutto il resto. Se il codice contraddice il file, è il codice a sbagliare.
-
Definisce architettura, regole e prodotto
Intenzione, non ricette. L'agente conosce già tutti i pattern; il tuo compito è fissare cosa deve valere — e perché.
Perché funziona
Impossibile stare dietro agli agenti: c'è più codice di quanto chiunque sia disposto a leggere. Controllare ogni riga è senza speranza. Controllare l'intenzione no.
HUMAN-INTENT.md porta il controllo un livello più in alto: sorvegli un file con le tue decisioni invece di migliaia di righe di codice. Finché il file è legge, il progetto segue la tua intenzione — anche se nessuno legge il codice.
Come iniziare
- Crea HUMAN-INTENT.md nella radice del tuo repository.
- Annota le decisioni che hai già preso: architettura, regole di sviluppo, prodotto.
- Di' al tuo agente di leggere il file e trattarlo come legge — richiamalo da AGENTS.md o CLAUDE.md.
- Ogni volta che prendi una nuova decisione, aggiungila al file. Non lasciare mai che un agente ci scriva.
- Fai la review di questo file, non del codice.