La Complementarietà
Marco Aurelio, nel secondo secolo dopo Cristo, aveva già compreso una verità profonda: siamo creature fatte per la collaborazione. I piedi, le mani, i denti lavorano in armonia, ognuno con il suo ruolo specifico, ognuno indispensabile all'altro.
Mentre costruivo CodeIntel, ho collaborato con un assistente IA. Non come sostituto, ma come partner. Non come automa che esegue ordini, ma come collaboratore con competenze complementari alle mie.
Perché la rivoluzione dell'IA nello sviluppo software non sta nel sostituire il programmatore, ma nell'amplificarne le capacità.
Questo post esplora due dimensioni:
- Come ho usato l'IA per sviluppare CodeIntel.
- Come CodeIntel integra l'IA come capability del sistema.
Parte I: L'IA come Co-Sviluppatore
Cosa Fa Bene
Boilerplate e scaffolding. Un nuovo agente, una struttura di test, un README iniziale: pochi minuti invece di mezz'ora. Tempo risparmiato per concentrarmi sulla logica di business.
Test writing. Date una funzione complessa, l'IA genera 15 test che coprono edge case che non avrei pensato. La copertura migliora, l'effort cala. Resto io a giudicare quali test contino davvero — ma il primo passaggio meccanico viene fatto in fretta.
Documentazione dettagliata. Sintesi di sprint, retrospettive, lesson learned. L'IA ha accesso a commit history, daily notes, test results: produce documenti strutturati che poi io rivedo e correggo.
Debugging complesso. Una sessione di otto iterazioni su un problema CI: Claude ha proposto fix ragionevoli per sette dei problemi. L'ottavo — quello chiave, l'autenticazione mancante — l'ho trovato io. La collaborazione ha lavorato meglio dei due singolarmente.
Cosa NON Fa Bene
Decisioni architetturali ad alto livello. "Multi-tenant collections o database separati?" L'IA fornisce pro/contro generici, ma non può decidere senza contesto business profondo. La decisione resta umana.
Trade-off complessi. Caching Redis vs latenza maggiore? Dipende da budget infrastruttura, scala utenti prevista, capacità di manutenzione del team, priorità. L'IA analizza le opzioni; io scelgo.
Code smell sottili. L'IA trova funzioni troppo lunghe e duplicazioni. Non percepisce smell architetturali che emergono da conoscenza del dominio. "Questo agent sta facendo troppo" richiede intuizione che va oltre l'analisi sintattica.
Creatività disruptive. Eccellente ad applicare pattern noti, mediocre a inventarne di nuovi. Per innovazione architetturale serve pensiero umano.
La Divisione dei Ruoli
L'IA eccelle in compiti strutturati, l'umano in compiti creativi e strategici. La collaborazione massimizza il risultato — ma solo se il giudizio finale resta umano.
Parte II: L'IA dentro CodeIntel
CodeIntel non solo è stato sviluppato con l'IA: integra l'IA come capability core, attraverso il pattern RAG (Retrieval-Augmented Generation).
Il flusso è semplice:
Domanda utente
↓
Embedding della domanda
↓
Vector search → chunk di codice rilevanti
↓
Costruzione del contesto (top-k chunk + metadata)
↓
Prompt all'LLM con il contesto
↓
Risposta + citazioni
Perché RAG batte un LLM nudo
Senza RAG, alla domanda "come funziona l'autenticazione in questo codebase?" un LLM risponde con generalità su OAuth e JWT. Con RAG, recupera dal vector store il file JWTAuthenticator.ts reale e cita la classe, l'algoritmo, il TTL del refresh token. La differenza tra una risposta generica e una specifica è data dal contesto recuperato.
Embeddings e Privacy
Tutto gira locale, via Ollama. Il modello di embedding produce vettori; ChromaDB li indicizza. Niente lascia la macchina. Per chi lavora con codice proprietario, è una scelta non negoziabile.
Separazione Fatti / Sintesi
Un pattern che ripeto in molti agent: l'analisi produce fatti misurabili (dependency graph, complessità ciclomatica, smell rilevati). La generazione LLM riceve questi fatti come input e produce sintesi (raccomandazioni, spiegazioni, diagrammi).
I fatti sono testabili a unit test. La sintesi è "best effort", da rivedere sempre. Mescolare i due nello stesso step è la prima causa di allucinazioni che sembrano credibili.
Conclusione: Simbiosi, non Sostituzione
L'IA non sostituisce lo sviluppatore. Lo amplifica.
Come i piedi e le mani di Marco Aurelio, umano e IA hanno ruoli complementari:
- Umano: visione architetturale, trade-off business, creatività disruptive, intuizione di dominio, decisioni etiche.
- IA: velocità implementativa, coverage di edge case, documentazione dettagliata, pattern recognition, consistency enforcement.
Insieme producono software migliore, più velocemente, con più qualità. Le decisioni critiche — architettura, tech stack, trade-off — restano umane.
L'IA è il miglior collaboratore che abbia avuto. Ma è esattamente questo: un collaboratore, non un sostituto.
Nel prossimo post entriamo nei dettagli tecnici: AST, Tree-sitter, e come CodeIntel "comprende" il codice a livello semantico.