Il tuo repository non ha mai raccontato tutta la storia

Apri un repository sei mesi dopo il rilascio di una funzionalità e puoi ricostruire molto. Puoi ripercorrere l'architettura, ispezionare lo schema, leggere i test e vedere con precisione quali righe sono cambiate.

Quello che di solito non puoi ricostruire è la conversazione che ha reso necessarie quelle righe.

Il codice non ti dirà che una regola di validazione esiste perché un cliente invia export malformati. Non spiegherà che una strana policy di retry impedisce transazioni duplicate in un sistema downstream. Non mostrerà che l'interfaccia più pulita è stata scartata dopo un test di accessibilità, o che un confine di servizio riflette un vincolo contrattuale più che una preferenza ingegneristica.

Git è eccellente nel preservare la storia del codice. Preserva l'intento solo quando un team lo mette deliberatamente per iscritto e lo mantiene collegato all'implementazione.

Questo divario ha sempre fatto parte dell'ingegneria del software. Gli strumenti di coding basati su IA lo rendono più visibile. Un sistema può leggere ogni file in un repository, seguire ogni simbolo e generare una patch tecnicamente convincente continuando comunque a risolvere il problema sbagliato.

Il problema non è che il codice sia fuorviante. Il codice sta rispondendo a una domanda più ristretta.

Cinque livelli di verità ingegneristica

La maggior parte delle modifiche software davvero significative dipende da cinque diversi livelli di evidenza.

1. Intento — Quale risultato stanno chiedendo l'utente, il cliente o il business? Può trovarsi in una specifica, in un ticket, in una conversazione con il supporto o in appunti di riunione.
2. Vincoli — Che cosa non deve rompersi? Promesse di compatibilità, confini di sicurezza, normative, contratti, budget e scadenze spesso si trovano fuori dal repository.
3. Implementazione — Come funziona oggi il sistema? Codice, test, schemi, dipendenze e configurazione di deploy forniscono questo livello.
4. Evidenza di runtime — Che cosa sta succedendo nel sistema reale? Log, trace, metriche, dati di produzione e report sugli incidenti possono contraddire ipotesi che nel codice sembrano ragionevoli.
5. Storia delle decisioni — Perché è stato scelto l'approccio attuale? Pull request, discussioni di design, alternative scartate e incidenti precedenti contengono la risposta.

Il repository è più forte nel terzo livello. Contiene parti degli altri, ma raramente abbastanza da rappresentarli in modo completo.

Questo conta perché i fallimenti del software spesso emergono ai confini tra i livelli. L'implementazione corrisponde a una specifica superata. La correzione soddisfa il ticket ma viola un vincolo operativo. I test passano perché codificano le ipotesi di ieri. Il codice è internamente coerente mentre i dati di produzione seguono uno schema che nessuno ha documentato.

Una patch localmente corretta può comunque essere la modifica sbagliata.

A cosa il repository, da solo, non può rispondere

Considera un utente che modifica un documento e poi cerca la frase aggiornata, solo per vedere ancora la vecchia versione nei risultati. “Fate in modo che la ricerca si aggiorni immediatamente” sembra una richiesta chiara. Il repository rivela diversi possibili punti da cui iniziare, ma da solo non può definire quale sia la correzione giusta.

Il codice della ricerca può spiegare come vengono restituiti i risultati. Non può dirti se il vero difetto sia un ritardo di sincronizzazione, un’estrazione obsoleta, un’invalidazione della cache, la propagazione delle autorizzazioni o un’aspettativa che il prodotto non ha mai definito.

Questa distinzione diventa ancora più importante nei sistemi maturi. Un campo che sembra obsoleto può ancora supportare un client legacy. Un servizio che sembra duplicato può in realtà separare dati con requisiti di autorizzazione diversi. Un controllo apparentemente eccessivo può essere l’unica traccia a livello di codice di un incidente in produzione che il team attuale non ha mai visto.

Eliminare la complessità ha valore. Eliminare la storia mascherata da complessità è costoso.

Più contesto può comunque portare alla risposta sbagliata

La soluzione più ovvia è dare all’AI più materiale: l’intero repository, ogni ticket, ogni documento, ogni messaggio e ogni log.

Questo crea accesso, non comprensione.

Le fonti possono essere obsolete, contraddittorie, speculative o scritte per pubblici diversi. Un brainstorming non dovrebbe avere più peso di una specifica approvata. Un requisito di sei mesi fa non dovrebbe sovrascrivere silenziosamente una decisione di prodotto presa ieri. Un log di produzione dovrebbe essere collegato alla release, all’ambiente e al percorso di codice che lo hanno generato. Una richiesta di un cliente non dovrebbe essere trattata come un requisito universale senza verificarne l’ambito.

Un sistema di contesto serio, quindi, ha bisogno di più del semplice retrieval. Ha bisogno di un modo per ragionare su:

• Autorità: Quale fonte è autorizzata a definire il requisito?
• Attualità: Quale informazione è aggiornata, e che cosa è stato superato?
• Provenienza: Da dove proviene ogni affermazione, vincolo o conclusione?
• Relazioni: Quali issue, release, clienti, dataset e percorsi di codice appartengono allo stesso insieme?
• Autorizzazioni: Quali fonti possono essere usate per questo compito e mostrate a questa persona?

Il contesto non è un mucchio di token. È un grafo con tempo, autorità e confini.

Più contesto dovrebbe produrre più evidenze, non più fiducia senza evidenze.

La vera unità di lavoro è il cambiamento

Gli editor e gli strumenti di coding sono organizzati attorno ai file perché i file sono ciò che modifichiamo. I team di ingegneria sono organizzati attorno ai cambiamenti.

Un cambiamento inizia con una ragione. Diventa un requisito, tocca codice e dati, passa attraverso la review, arriva in produzione e genera nuove evidenze. Se queste fasi restano scollegate, ogni attività futura comincia con un altro giro di archeologia.

Un sistema di AI che lavora su software reale dovrebbe seguire quel ciclo di vita.

Prima dell’implementazione, dovrebbe identificare la richiesta, i vincoli rilevanti e qualsiasi fonte in conflitto. Dovrebbe sapere se sta correggendo un difetto, modificando un comportamento atteso o introducendo un nuovo contratto.

Durante l’implementazione, dovrebbe collegare ogni scelta significativa alle evidenze. Perché questo modulo? Perché questa strategia di migrazione? Perché preservare questo branch? La spiegazione dovrebbe sopravvivere oltre la chat che ha prodotto il codice.

Dopo l’implementazione, dovrebbe allegare alla modifica i risultati della verifica, le decisioni della review e i vincoli scoperti di recente. Altrimenti la persona successiva — o la sessione di AI successiva — dovrà riscoprirli.

Questa è la differenza tra uno strumento che può modificare un repository e un sistema che può partecipare al lavoro di ingegneria.

L’AI dovrebbe ridurre la ricostruzione, non eliminare il giudizio

Un contesto migliore viene talvolta presentato come una strada verso lo sviluppo software autonomo. Il valore immediato è meno spettacolare e più utile: ridurre il costo della ricostruzione della realtà prima di apportare una modifica.

L’AI può portare il requisito originale accanto al codice pertinente. Può far emergere l’incidente che spiega una salvaguardia insolita. Può collegare una metrica in peggioramento alla release che l’ha modificata. Può mostrare che due fonti autorevoli sono in disaccordo prima ancora che l’implementazione inizi.

Queste capacità non eliminano il giudizio ingegneristico. Lo rendono più informato.

Una persona deve comunque decidere quale compromesso sia accettabile, se un requisito sia completo e quanto rischio possa sostenere una release. Il sistema dovrebbe rendere visibili le evidenze e verificabile il ragionamento. Non dovrebbe nascondere l’incertezza dietro una patch ben rifinita.

Il criterio non è “sa generare codice?”

Il criterio è “sa spiegare perché questa è la modifica giusta in questo momento?”

Dalla consapevolezza del repository alla consapevolezza del lavoro

Gli assistenti di coding hanno iniziato a diventare utili comprendendo il file davanti allo sviluppatore. La consapevolezza del repository è stato il passo successivo più importante: trovare codice correlato, seguire i simboli e applicare modifiche in tutto il progetto.

Il passo successivo è la consapevolezza del lavoro che circonda il repository.

Questo significa collegare il codice alla specifica che lo ha richiesto, alla conversazione che lo ha chiarito, alle evidenze di produzione che lo hanno messo in discussione e alla decisione che dovrebbe essere ricordata in seguito. Significa anche escludere il contesto irrilevante, obsoleto o al di fuori delle autorizzazioni dell’utente.

Mentre costruiamo Dvina, questa è una delle idee a cui continuiamo a tornare. Il lavoro non avviene all’interno di un singolo file, di una singola applicazione o di una singola conversazione. Il significato vive nelle connessioni tra questi elementi e nel modo in cui tali connessioni cambiano nel tempo.

Il repository resta essenziale. È la fonte di verità eseguibile per il comportamento del sistema. Semplicemente, non è la fonte di verità completa per l’intento del prodotto, la realtà operativa o la memoria organizzativa.

L’intera storia cambia ciò che viene costruito

Con il solo codice, la domanda naturale è:

Quale modifica si adatta a questo sistema?

Con il contesto più ampio, la domanda diventa:

Quale modifica si adatta a questo sistema, a questo requisito, a questa storia e a questo momento?

Quella seconda domanda intercetta i vincoli prima che diventino regressioni. Offre ai revisori il ragionamento alla base dell'implementazione. Aiuta i nuovi membri del team a capire perché il sistema è fatto così. E assegna all'AI un ruolo fondato: non un oracolo dentro l'editor, ma un partecipante capace di mettere insieme le evidenze distribuite nel lavoro.

Il tuo repo non è mai stato tutta la storia.

L'opportunità è costruire sistemi capaci di leggere anche tutto il resto — e di mostrare come ci arrivano.