Maturità del codice
Il tuo agente di codifica IA è valido quanto il harness del tuo codebase. L'IA amplifica qualsiasi struttura già esistente: un codebase disciplinato produce più velocemente, uno indisciplinato produce codice confidentemente sbagliato più velocemente. Il harness (Fowler: Agent = Model + Harness) è ciò che questa pagina ti aiuta a misurare.
Una diagnostica a nove dimensioni con un rubric di punteggio da 1 a 5 per dimensione. Tre sono bloccanti: punteggi bassi compromettono fondamentalmente il lavoro degli agenti e non possono essere compensati da punteggi alti altrove. Le altre sei sono vincolanti. Valuta qualsiasi repo con un comando tramite la skill Claude Code open source gratuita.
I cinque livelli di maturità
Ogni livello è definito dal meccanismo di feedback che aggiunge. Non si possono saltare i livelli; ciò che sblocca il livello successivo è sempre un altro ciclo di feedback, non un altro strumento.
| Livello | Nome | Cosa è presente | Cosa possono fare gli agenti |
|---|---|---|---|
| 0 | Opaco | Nessun tipo imposto. Copertura di test scarsa o assente. CI assente o inaffidabile. Documentazione obsoleta. Confini dei moduli poco chiari. | Suggerimenti isolati per funzione singola. Qualsiasi cosa oltre produce codice allucinato senza segnale correttivo. |
| 1 | Strumentato | Tipi imposti a tempo di compilazione. Esistono alcuni test. CI restituisce pass/fail in pochi minuti. | Generazione di funzioni singole con fiducia di base. Refactoring a portata ristretta. Il segnale è debole ma presente. |
| 2 | Validato | Copertura significativa sui percorsi di codice che cambiano. CI sotto 30 min (sotto 5 min è meglio). Almeno un percorso di integrazione end-to-end. | Refactoring multi-file entro ambito delimitato. Correzioni di bug validate da test esistenti. Livello minimo per il Grado 3 (sviluppo diretto). |
| 3 | Leggibile | Confini dei moduli chiari. Denominazione coerente. Architettura documentata. Contratti comportamentali dichiarati ai confini delle interfacce. | Lavoro cross-modulo con risultati prevedibili. Gli agenti possono ragionare sul codebase senza walkthrough. |
| 4 | Specificato | L'intento catturato in specifiche, non solo nel codice. Il nuovo lavoro è spec-first. Le decisioni storiche documentate. | Generazione autonoma di feature da specifica (Grado 4). L'umano specifica; l'agente costruisce e testa. |
| 5 | Governato da scenari | Scenari end-to-end coprono i percorsi critici. Metriche di soddisfazione sostituiscono il pass/fail binario. Osservabilità completa. | Produzione autonoma completa (Grado 5). Il modello operativo del Lab diventa sostenibile. |
Fowler chiama le proprietà strutturali del Livello 3+ ambient affordances: proprietà che rendono un codebase leggibile a un agente senza istruzioni aggiuntive. La loro assenza costringe l'agente a inventare struttura.
L'AI Codebase Maturity Model, validato su un progetto reale al 91% di copertura e cicli bug-to-fix sotto i 30 minuti, ha dichiarato il risultato sottostante senza mezzi termini: "L'intelligenza di un sistema di sviluppo guidato dall'IA non risiede nel modello IA stesso, ma nell'infrastruttura di istruzioni, test, metriche e cicli di feedback che lo circondano."
La regola del soffitto
La pratica ingegneristica (i Gradi 0–5 del framework) riguarda come lavora il team. La maturità del codice (Livelli 0–5) riguarda cosa supporta il codice. Sono collegati:
Il livello di maturità di un codebase è il soffitto sul Grado ingegneristico che può operare in modo affidabile su di esso.
Un team al Grado 5 che spinge agenti in un codebase di Livello 2 otterrà gli stessi errori di un team al Grado 2, solo più velocemente. I cicli di feedback che mantengono onesto il Grado 5 non esistono. Questo è il modo più comune di fallire nell'adozione dell'IA brownfield: i team vedono demo del Grado 5 su repository greenfield e assumono che il modello funzionante si trasferisca. Non lo farà finché il harness non è costruito.
La Griglia di maturità del codice (Codebase Readiness Grid)
Nove dimensioni. Ognuna risponde a una domanda. Punteggio da 1 a 5 per ciascuna. Il punteggio più basso è il soffitto sul livello di maturità al quale puoi operare in modo affidabile; la tua dimensione più debole è dove gli agenti falliranno per primi.
La Griglia di maturità del codice (Codebase Readiness Grid), come skill Claude Code. Esegue su qualsiasi repo, raccoglie segnali per dimensione, produce uno scorecard con una raccomandazione del Percorso verso il Livello 5. Open source, licenza MIT.
| # | Dimensione | Tipo | Domanda a cui risponde | Rubric di punteggio (1–5) |
|---|---|---|---|---|
| 1 | Copertura dei test e latenza del feedback | bloccante | Esiste una copertura significativa sui percorsi di codice che cambiano più spesso? Quanto è veloce la CI? | 1 = nessun test o test morti. 2 = bassa copertura, CI lenta. 3 = copertura significativa sui percorsi caldi, CI sotto 30 min. 4 = soglia imposta, CI sotto 5 min, i fallimenti si localizzano. 5 = scenari comportamentali coprono i percorsi critici, CI veloce e verde come gate di deploy. |
| 2 | Rigidità dei tipi | bloccante | I tipi sono imposti a tempo di compilazione? any è raro o pervasivo? | 1 = non tipizzato o tipi disattivati. 2 = tipi opzionali, any ovunque. 3 = tipi imposti, alcune vie di fuga. 4 = strict mode attivo, any raro e giustificato. 5 = strict mode in CI, zero any, contratti ad ogni confine. |
| 3 | Dimensione dei file e leggibilità del contesto | vincolante | Un agente può ragionare su un file senza caricare il resto del sistema? | 1 = file dio (2000+ righe), responsabilità miste. 2 = molti file con 1000+ righe, aggrovigliati. 3 = la maggior parte dei file sotto 500 righe, alcuni outlier. 4 = la maggior parte sotto 300 righe, outlier rari e giustificati. 5 = ogni file dimensionato per una responsabilità. |
| 4 | Chiarezza dei confini dei moduli | vincolante | Un nuovo ingegnere (o agente) può descrivere il grafico dei moduli dopo 30 minuti? I confini sono imposti? | 1 = nessuna struttura modulare. 2 = struttura sulla carta, violata in pratica. 3 = moduli ad alto livello chiari, perdite occasionali. 4 = confini imposti, contratti stabili. 5 = il grafico dei moduli è una mappa navigabile; architettura documentata e aggiornata. |
| 5 | Direttezza delle API | bloccante | La chiamata HTTP/RPC è visibile al punto di chiamata, o nascosta dietro livelli wrapper? | 1 = accesso tramite astrazioni opache (Factory, dispatch dinamico, ORM con query invisibili). 2 = astrazione significativa, tracciabile con sforzo. 3 = mix di dirette e astratte. 4 = principalmente chiamate dirette con risposte tipizzate. 5 = i punti di chiamata mostrano cosa sta accadendo; nessuna operazione di rete o database nascosta. |
| 6 | Intento documentato | vincolante | Il perché è documentato separatamente dal come? Le decisioni architetturali sono registrate? | 1 = nessun documento di intento; il codice è l'unica verità. 2 = documentazione sparsa, spesso obsoleta. 3 = README dei moduli, alcuni ADR. 4 = log ADR aggiornato, moduli critici documentati, CLAUDE.md / AGENTS.md in posizione. 5 = ogni decisione non banale ha una specifica o un ADR; il contesto storico è preservato. |
| 7 | Osservabilità | vincolante | Riesci a capire cosa ha fatto il sistema per una data richiesta? I fallimenti producono casi di test riproducibili? | 1 = nessun log strutturato, nessuna traccia, nessuna metrica, nessun tracciamento degli errori. 2 = alcuni log, nessun tracing. 3 = log strutturati e metriche di base; tracciamento degli errori in posizione. 4 = telemetria completa con accesso a query. 5 = produzione completamente osservabile; gli errori producono casi di test riproducibili. |
| 8 | Semplicità di sviluppo e deploy | vincolante | Puoi configurare lo sviluppo con un comando? Fare il deploy con uno (o automaticamente)? | 1 = la configurazione dello sviluppo richiede giorni o conoscenza tribale; deploy manuali e fragili. 2 = scriptato ma fragile; i deploy richiedono passaggi da manuale. 3 = comandi documentati, deploy affidabile. 4 = configurazione con un comando; deploy con un comando (o automatico). 5 = sviluppo, CI, produzione architetturalmente identici. |
| 9 | Aggiornamento di dipendenze e runtime | vincolante | Il runtime è supportato? I framework sono entro 1–2 major da quello attuale? Ci sono librerie abbandonate? | 1 = runtime EOL, framework 2+ major indietro, librerie abbandonate, paradigmi misti. 2 = runtime aggiornato ma molte dipendenze 1+ major indietro. 3 = runtime aggiornato, la maggior parte delle dipendenze entro 1 major, pattern legacy occasionale documentato. 4 = paradigmi moderni coerenti. 5 = igiene aggressiva delle dipendenze; le convenzioni corrispondono agli standard attuali della community. |
Note sulle dimensioni meno intuitive. D1: la CI lenta è il deficit brownfield più comune: una suite di test a 72 ore non è un sensore, è un report. D3: i file piccoli non sono una preferenza di stile, sono una disciplina di context window; gli agenti che hanno bisogno di tre file per capire una funzione allucinano le parti mancanti. D5: le astrazioni opache non nascondono solo i dettagli, producono codice confidentemente sbagliato quando l'agente indovina cosa fa UserFactory.resolve(). D6: il codice si documenta da solo; l'intento no. Questo è il deficit più difficile da rimediare rapidamente. D9: gli agenti sono addestrati sulle versioni correnti delle librerie e i loro idiomi; un codebase che usa pattern di 2–3 anni fa riceve codice che contraddice le proprie convenzioni.
Come funziona il punteggio
Quattro regole governano come leggere lo scorecard. Si compongono: tutte e quattro si applicano simultaneamente.
1. Il soffitto è il punteggio più basso. La tua dimensione più debole imposta il livello di maturità. Un codebase con otto 5 e un 1 è al Livello 0, non al Livello 4. Gli agenti falliscono all'anello più debole.
2. Tre dimensioni sono bloccanti; sei sono vincolanti.
- Bloccanti (D1, D2, D5): punteggi bassi compromettono fondamentalmente il lavoro degli agenti. Senza test, gli agenti sono ciechi. Senza tipi, allucinano forme. Con API opache, producono codice confidentemente sbagliato. Non possono essere compensate da punteggi alti altrove.
- Vincolanti (D3, D4, D6, D7, D8, D9): punteggi bassi degradano la qualità, ma gli agenti possono ancora produrre valore. Più revisione umana per modifica, più pulizia, più attrito.
Quando due dimensioni sono a pari punteggio basso, aumenta prima quella bloccante. La regola del soffitto si applica comunque; questa classificazione affina solo la priorità di rimedio.
3. Credito per differimento: un differimento intenzionale e documentato ottiene un punteggio di un livello superiore rispetto allo stesso gap non documentato. Se l'osservabilità non è configurata, ma la specifica del progetto la differisce a una fase GA-Ready con data e criteri, punteggiala 2 invece di 1. Il differimento è una decisione; un gap distratto non lo è. Le affermazioni verbali non si qualificano: il differimento deve essere nel repo.
4. Non riassumere mai lo scorecard con una media. Lo scorecard è un vettore, non uno scalare. Due codebase con media 3.0 possono essere in situazioni radicalmente diverse: uno con D1 a 1 è cieco; uno con D7 a 1 è immaturo operativamente ma utilizzabile. Le medie nascondono questa distinzione.
Lo scorecard è uno snapshot. Eseguilo ogni trimestre: i codebase si muovono in entrambe le direzioni.
Come appare un codebase di Livello 5
Un riferimento concreto, generalizzato da pattern osservati. Un codebase che ottiene 5 in tutte le nove dimensioni tende a condividere queste caratteristiche:
- Spec-first per il lavoro non banale. Contratti API verificati, scenari di accettazione definiti, decisioni documentate prima del codice.
- Tipizzazione rigida imposta a tempo di compilazione. Zero
any. Le violazioni dei tipi fanno fallire la CI. - File piccoli e focalizzati. La maggior parte sotto qualche centinaio di righe. I file più grandi sono outlier intenzionali, non accumuli accidentali.
- Accesso diretto a API e dati. I punti di chiamata mostrano cosa viene chiamato. Nessuna factory opaca, nessun dispatcher generico.
- Dipendenze minime. Pochi pacchetti, ognuno giustificato.
- Convenzioni esplicite. Struttura dei file e denominazione documentate. Header
ABOUTME:su ogni file.AGENTS.mdoCLAUDE.mdcon le regole dell'agente. - Nessuna conoscenza implicita. Il codebase è leggibile perché dice cosa intende, non perché il team lo ricorda.
- Test come contratti. Mock semplici, asserzioni comportamentali, nomi leggibili.
- Build con un comando, deploy con un comando. Nessuna lotta con l'infrastruttura per spedire.
- Dipendenze aggiornate, runtime supportato. Nessun runtime EOL, nessuna libreria abbandonata.
Non sono preferenze di stile. Sono le proprietà strutturali che permettono agli agenti di produrre lavoro affidabile, e sono le stesse proprietà che rendono gli umani produttivi. Le due cose non sono separate.
Strategia di costruzione del harness
Quando la maturità è inferiore a dove il team deve lavorare, sequenzia l'investimento in quest'ordine. Saltare le fasi produce velocità senza fiducia.
Il harness ha due parti: sensori (test, CI, osservabilità) verificano l'output degli agenti; guide (tipi, convenzioni, documenti architetturali, intento documentato) specificano cosa produrre. I codebase brownfield tipicamente hanno le guide ma mancano dei sensori: è la configurazione che produce codice confidentemente sbagliato.
Fase 1: installare prima i sensori veloci. Test utili e CI veloce (latenza di feedback sotto 30 minuti è il gate). Senza sensori, ogni modifica a valle è un'ipotesi e non puoi verificare che il lavoro successivo sul harness stia producendo risultati.
Fase 2: rendere il codice leggibile. Denominazione coerente, tipi imposti, confini dei moduli chiari, preoccupazioni trasversali centralizzate, eliminazione dei percorsi morti. La leggibilità è ciò che permette agli agenti di lavorare attraverso i moduli senza allucinare struttura.
Fase 3: catturare l'intento. Documentare le decisioni architetturali. Dichiarare contratti comportamentali ai confini delle interfacce. Per i moduli più critici, estrarre la specifica implicita: le migliaia di decisioni accumulate nel corso di anni di patch. Gli agenti possono documentare cosa fa il sistema; distinguere il comportamento intenzionale dall'incidente storico rimane umano. Vedi la sequenza brownfield del Lab IA per la versione disciplinata.
Fase 4: governare con scenari. Convertire l'intento in scenari end-to-end. Gli scenari sono più difficili da aggirare per gli agenti rispetto ai test unitari. La modalità di lavoro del Grado 5 diventa praticabile a questo punto.
Pattern di Paul Duvall's AI Development Patterns che si adattano a questa sequenza: Readiness Assessment (Foundation), Observable Development, Guided Refactoring.
Cosa fare quando il punteggio è basso
Si applicano quattro modalità, trattate in dettaglio nella Strategia brownfield: risanare in loco, migrazione strangler-fig, ricostruzione completa o isolare e aggirare. La modalità giusta dipende dalla solidità architettonica del codebase, dalla disponibilità di seami e dal valore residuo per il business, non dalla capacità del team o dalle priorità strategiche, che sono al di fuori di questa valutazione.
Specchio: maturità e affidabilità
L'Ingegneria dell'affidabilità affronta l'output dell'IA come input ai sistemi. La maturità del codice affronta l'inverso: il codebase come input agli agenti IA. Stessa incertezza, riflessa.
Correlati
- Strategia brownfield: le quattro modalità per i codebase a bassa maturità
- Lab IA: la modalità di lavoro del Grado 5 che un codebase di Livello 5 supporta
- Ingegneria dell'affidabilità: il problema speculare
- Standard di esecuzione IA e Guida alle specifiche: ingegneria delle specifiche
Fonti
- Mahiou et al. (2026). "AI Codebase Maturity Model (ACMM)." arXiv. arxiv.org/abs/2604.09388
- Fowler, M. (2026). "Harness Engineering for Coding Agent Users." martinfowler.com
- Duvall, P. (2026). "AI Development Patterns." github.com/PaulDuvall/ai-development-patterns
- Google Cloud (2025). "DORA 2025 State of AI-assisted Software Development." dora.dev
- "A Maturity Model for AI-Native Development." (2025). Transcode. blog.transcode.be
- "The State of Generative AI in Software Development." (2026). arXiv. arxiv.org/abs/2603.16975
← Torna alla home · Strategia brownfield · Lab IA · Ingegneria dell'affidabilità · Glossario