Quando versionare un artefatto insieme al software

Tipo

Pratica

Un artifact trae particolare beneficio dal vivere vicino al codice quando cambia con la stessa cadenza della soluzione, quando deve essere sottoposto a review insieme all'implementazione, quando la storia delle modifiche è importante o quando può essere validato automaticamente. Contratti API ed eventi, schema dati, configurazioni architetturali dichiarative, decision record e diagrammi derivabili da fonti strutturate sono esempi frequenti. Al contrario, materiale di workshop, esplorazioni iniziali, mappe temporanee e rappresentazioni pensate principalmente per facilitare una conversazione possono avere più valore in strumenti collaborativi. Il punto non è stabilire un luogo unico, ma evitare duplicazioni di autorità. Se una stessa informazione esiste in repository, wiki e diagramma manuale, bisogna sapere quale fonte è autorevole e quali viste sono derivate. Un buon criterio è chiedere: questo artifact deve cambiare nello stesso momento del codice? Una modifica dovrebbe bloccare o accompagnare una pull request? Esiste una forma verificabile o generabile? Il suo pubblico principale lavora nel repository oppure fuori? La collaborazione visuale in tempo reale è parte essenziale del suo valore? La risposta può anche essere ibrida: una fonte strutturata e versionata può generare viste consumabili altrove. Architecture as Code è utile quando riduce drift e aumenta verificabilità; diventa un anti-pattern quando trasforma ogni conversazione architetturale in manutenzione di file senza migliorare chiarezza o controllo.