Preservation-first

Preservation-first è la regola predefinita quando si modifica software già esistente. Significa che l’agente deve comprendere ed estendere l’implementazione funzionante invece di sostituirla con quella che avrebbe scelto lavorando in isolamento.

Il principio protegge comportamento, architettura, conoscenza locale e lavoro del developer. Mantiene inoltre il task revisionabile, impedendo che miglioramenti estranei vengano mescolati con la modifica autorizzata.

Usare il vocabolario di implementazione già presente nel progetto

Prima di scrivere nuovo codice in un’area implementata, l’agente dovrebbe identificare come il codice vicino risolve già problemi comparabili. Gli elementi pertinenti possono comprendere:

funzioni, metodi e confini dei servizi esistenti;
utility condivise e moduli helper;
validazioni, guard e controlli dei permessi;
convenzioni di gestione degli errori e logging;
pattern di dependency injection, stato e accesso ai dati;
convenzioni di naming, tipizzazione e cartelle;
test, fixture e comandi di verifica esistenti;
interfacce pubbliche e comportamenti da cui dipende altro codice.

Il nuovo codice dovrebbe riusare o comporre questi elementi quando appropriato. L’obiettivo non è imitare la sola formattazione, ma far sì che la modifica si comporti come una parte coerente del software esistente.

La coerenza locale viene prima di una soluzione “migliore” non richiesta

Un modello AI può conoscere una API più recente, un’astrazione più moderna o un’architettura teoricamente più pulita. Questa conoscenza è utile quando il developer richiede una decisione architetturale o un refactoring. Non costituisce automaticamente un’autorizzazione a sostituire un approccio locale funzionante.

Per una normale modifica di feature o correzione di bug, l’agente segue il pattern di implementazione stabilito anche quando un altro approccio potrebbe essere considerato migliore in un progetto greenfield. Le differenze possono essere riportate come osservazioni, ma restano fuori dall’implementazione finché non vengono autorizzate esplicitamente.

Aggiungere ciò che serve senza riscrivere ciò che funziona

L’agente dovrebbe aggiungere o adattare in modo minimo le istruzioni, diramazioni, chiamate, tipizzazioni e verifiche necessarie per ottenere il comportamento richiesto.

Non deve, soltanto perché sta modificando quell’area:

unificare più funzioni funzionanti nell’astrazione che preferisce;
riscrivere un metodo per stile o brevità;
ottimizzare codice senza un requisito identificato;
rinominare simboli non pertinenti;
riorganizzare moduli o cartelle;
sostituire utility locali con nuovi helper generati;
modernizzare la sintassi in tutto il file circostante;
rimuovere guard o validazioni apparentemente ridondanti senza averne dimostrato la funzione.

Queste modifiche aumentano la superficie di review e possono distruggere vincoli incorporati nella storia del progetto.

Preservare le modifiche del developer e quelle di origine incerta

Le modifiche manuali del developer sono stato corrente del progetto, non rumore da sovrascrivere. Prima di modificare un file, l’agente deve rileggerlo e integrarsi con ciò che è ora presente.

Quando l’origine di una modifica esistente è incerta, la scelta sicura predefinita è preservarla. L’agente non dovrebbe ripristinare uno snapshot precedente, scartare un diff o ricostruire il file affidandosi alla memoria senza un’autorizzazione esplicita del developer per quell’azione distruttiva.

Preservare il comportamento, non il difetto da correggere

Preservation-first non richiede di conservare il bug che il task deve risolvere. La baseline da preservare comprende comportamento e vincoli esterni alla modifica autorizzata.

Una correzione può cambiare il ramo difettoso mantenendo validazioni, interfacce e comportamenti circostanti non pertinenti. Il Task Contract dovrebbe rendere esplicita la differenza comportamentale richiesta, evitando che “preservare” e “modificare” restino soggetti a interpretazione.

La modifica minima è architetturale, non numerica

Un’implementazione preservation-first non viene giudicata in base al minor numero possibile di righe modificate. A volte l’architettura esistente richiede interventi coordinati su API, servizio, interfaccia e test.

La superficie corretta è la più piccola superficie coerente che soddisfa il task preservando il comportamento estraneo. Forzare artificialmente la modifica in un solo file può essere incoerente quanto riscrivere troppo.

Il refactoring resta possibile

TCAF non vieta refactoring, modernizzazione o miglioramento architetturale. Li separa dal lavoro non correlato.

Un refactoring è appropriato quando:

costituisce l’obiettivo esplicito del task;
è necessario per rendere possibile il comportamento richiesto ed è documentato nel contratto;
viene proposto e approvato separatamente dopo il task corrente;
è necessario per risolvere un blocker che il developer accetta come amendment.

In ogni caso, la superficie più ampia diventa visibile e revisionabile invece di entrare come effetto collaterale opportunistico.

Anche il greenfield diventa preservation-first quando esiste una baseline

All’inizio un nuovo progetto presenta meno vincoli locali. Non appena vengono stabiliti architettura, convenzioni, utility e feature funzionanti, i task successivi dovrebbero trattarli come baseline corrente.

Questo impedisce a ogni nuova sessione AI di reinventare il progetto e permette alla codebase di sviluppare un linguaggio interno stabile.

Cosa dovrebbe riportare il Task Contract

Per le modifiche in aree implementate, il contratto dovrebbe rendere concreto il confine di preservazione. In base al task può identificare:

metodi o utility esistenti da riusare;
file o comportamenti che devono restare invariati;
validazioni e guard da mantenere;
modifiche del developer già presenti;
refactoring o cambi di dipendenza vietati;
differenza comportamentale esatta richiesta;
controlli che dimostrano il comportamento preservato e quello nuovo.

Il principio diventa così verificabile invece di restare una generica istruzione a “fare attenzione”.