In breve: e se il vero sorgente del software non fosse più il codice, ma l’intenzione che lo descrive? Un repository fatto solo di AGENTS.md, VISION.md e ADR potrebbe rigenerare lo stesso software in stack diversi — a patto di scrivere bene anche i freni.
C’è stato un momento, abbastanza preciso, in cui mi sono accorto che stava cambiando qualcosa nel mio modo di aprire un repository.
Stavo entrando in un progetto e la prima cosa che cercavo non era index.php. Nemmeno main.ts.
Cercavo AGENTS.md.
All’inizio c’era il solito README.md.
Il file che scrivi perché va scritto. Per ricordarti come si avvia il progetto, che versione usa, dove stanno le cose, quali comandi lanciare senza doverli ricostruire ogni volta. Poi sono arrivati i file per Copilot, tipo copilot-instructions.md.
Poi AGENTS.md.
Da lì, per qualche motivo, tutto ha iniziato a diventare maiuscolo.
- PLAN.md
- ARCHITECTURE.md
- BACKLOG.md
- CHANGELOG.md
- VISION.md
Quando il repository smette di essere solo codice
Di solito pensiamo a un repository come al contenitore del software.
Scarichi il repo, dentro c’è il programma. Il codice è il centro. Il resto gli gira intorno: documentazione, note, appunti, changelog, decisioni sparse.
Con gli agenti questa gerarchia si muove.
Quei file che prima stavano ai margini cominciano a pesare più del previsto. Non servono solo a spiegare il progetto a una persona. Servono a orientare qualcuno, o qualcosa, che può modificare il codice.
Gli dicono: questo progetto deve comportarsi così. Queste scelte vanno evitate. Questi confini vanno rispettati. Questo è lo stile. Queste verifiche vanno fatte prima di dire che il lavoro è chiuso.
Il software come compilazione dell’intenzione
Da qui nasce una possibilità strana, e per me parecchio interessante: un repository composto quasi solo da questi file.
Lo scarichi.
Dentro non trovi il programma.
Trovi il modo per rifarlo.
Ogni generazione potrebbe essere diversa. Lo stesso seed potrebbe produrre una versione in React, una in Vue, una in PHP semplice con Bootstrap e jQuery.
Eppure, se il seed è scritto bene, il risultato dovrebbe restare riconoscibile.
- Stessi comportamenti
- Stessi vincoli
- Stessa idea di utente
- Stessa definizione di “finito”
Il codice resta fondamentale. Però diventa una delle forme possibili. Una specie di compilazione.
Stai compilando intenzioni in software.
Dove questa idea diventa utile
Io sto pensando a cose molto normali: gestionali custom, dashboard, tool interni, piccoli SaaS, configuratori, pannelli per clienti, siti con logiche particolari.
Su un modulo PrestaShop o un plugin WordPress sarei più prudente. Una cosa che deve vivere dentro un ecosistema fatto di update, hook, convenzioni precise e dipendenze ha bisogno di restare strutturalmente stabile.
Su un gestionale custom, invece, cambia tutto.
Il patrimonio vero sta nella descrizione precisa di quella cosa.
Intent Source, Project Seed o Agentic Blueprint?
| Nome | Idea |
|---|---|
| Intent Source | Il sorgente del software diventa l’intenzione. |
| Project Seed | Scarichi un seme e lo fai crescere. |
| Agentic Blueprint | Più operativo, quasi da marketplace. |
Repository di intenzioni.
Il rischio grosso
Un seed scritto male è un prompt lungo travestito da progetto.
Questa cosa regge solo se contiene anche i freni.
- Scenari
- Casi di accettazione
- Checklist
- Test
- ADR
Il cuore del seed non è AGENTS.md.
Il cuore sta nell’insieme tra VISION.md, ARCHITECTURE.md, ADR e test di accettazione.
Memoria esterna
Questi file stanno già nascendo ovunque, senza un disegno comune.
Prima il README. Poi le istruzioni per Copilot. Poi AGENTS. Poi i plan. Poi i changelog.
Secondo me qui sta nascendo una superficie nuova del software.
Non è documentazione nel senso vecchio. È contesto persistente.
Il problema reale
In questi progetti il problema non è solo scrivere codice.
Il problema è ricordarsi perché quel codice è fatto così.
- Perché quella tabella ha quel campo
- Perché un utente vede una cosa e un altro no
- Perché quel filtro serve davvero
Se queste cose non le scrivi, dopo un po’ diventano archeologia.
Una sorgente dell’intenzione
Potremmo iniziare a trattare certi software come oggetti rigenerabili a partire da una descrizione robusta, controllata, versionata.
- Abbastanza precisa da produrre codice
- Abbastanza chiara da correggerlo
- Abbastanza stabile da sopravvivere allo stack del momento
Una sorgente dell’intenzione.
Forse, però, il centro di gravità si sta spostando un po’. Anche solo di qualche centimetro.
Dal concetto alla manutenzione
Qui ho parlato di repository come sorgente dell’intenzione. Ma esiste una domanda successiva: cosa succede quando quel contesto inizia a degradarsi? Ho approfondito questo passaggio nell’articolo Repo Forge.