Come ho fatto smettere l'IA di allucinare sul nostro codebase
Gli strumenti di coding basati su IA falliscono nei veri progetti di produzione. Funzionano bene con il codice nuovo. Si sfaldano con il codice vecchio che ha una cronologia.
Il nostro progetto fintech ha tre anni di storia. Ha due frontend in React, un pannello di amministrazione e un backend in FastAPI. Il database è complesso, con molte tabelle e join pesanti.
Abbiamo provato a usare l'IA per muoverci più velocemente. Non ha funzionato.
Ho chiesto all'IA di creare una tabella contatti. Ha creato nuove colonne per nomi ed email. Non si è resa conto che le avevamo già nella nostra tabella utenti. Ha duplicato i dati invece di usare una foreign key.
L'IA non era stupida. Non aveva contesto. Ha preso una decisione con informazioni incomplete.
Ho smesso di chiedere come ottenere codice migliore. Ho iniziato a chiedere quale contesto l'IA avesse bisogno per prendere buone decisioni.
Abbiamo costruito un workflow strutturato. L'IA è valida solo quanto il contesto che le fornisci. Abbiamo reso quel contesto esplicito.
Ecco la nostra configurazione:
- ADR Directory: Abbiamo creato una cartella per gli Architecture Decision Records. Questi file spiegano perché prendiamo determinate scelte. Un file dice all'IA di controllare le tabelle esistenti prima di crearne di nuove. Vieta la duplicazione dei dati utente.
- context.md: Questo file spiega i nostri termini specifici. Dice all'IA come le nostre parole uniche si relazionano tra loro.
- plot.md: Fornisce una mappa ad alto livello del progetto e di come i vari pezzi si collegano.
- Test Obbligatori: Ogni nuova rotta API richiede dei casi di test.
Questo ha cambiato tutto. Una volta, l'IA ha modificato una funzione utility condivisa. La modifica ha rotto altre otto parti del sistema. La suite di test l'ha individuata immediatamente. L'IA ha visto il fallimento e ha corretto il proprio errore creando una versione che gestiva sia i vecchi che i nuovi requisiti.
Senza i test, quel bug sarebbe arrivato in produzione.
Tratta l'IA come un nuovo sviluppatore. Non incolpi un nuovo assunto perché non conosce il tuo codebase. Fornisci documentazione e onboarding. Abbiamo fatto lo stesso per l'IA.
La nostra struttura:
- docs/context.md: Termini e connessioni del progetto.
- docs/plot.md: Mappa ad alto livello del codebase.
- docs/adr/: Regole specifiche come la creazione di tabelle e la struttura delle API.
Tre regole per il tuo team:
- Sii specifico negli ADR. Usa istruzioni chiare invece di consigli vaghi.
- Rendi la documentazione autorevole. Di' all'IA che queste regole hanno la priorità.
- Trasforma gli errori in regole. Ogni volta che l'IA fallisce, scrivi un nuovo ADR.
Questo sistema non rende l'IA perfetta. La rende prevedibile. Vogliamo un codebase in cui l'IA sia coerente, così il team può muoversi più velocemente.