Tre mesi di lavoro reale con Claude Code su un progetto da zero — non un tutorial, non un caso di studio costruito per l’articolo. Lalit Maganti, engineer con anni di esperienza, ha usato Claude Code quotidianamente per costruire syntaqlite, un linter e verificatore per SQLite, dopo 8 anni in cui continuava a rimandare per via della complessità percepita. Quello che ha scritto sul blog di Simon Willison è la mappa più onesta che abbia letto su dove l’AI ti moltiplica e dove ti porta fuori strada.

La analizzo qui con l’aggiunta di contesto tecnico pratico per chi usa Claude Code su codebase reali.

Il problema che l’AI risolve davvero: la paralisi da overdesign

Chi sviluppa tool per uso proprio conosce bene il pattern: hai l’idea chiara, le competenze tecniche, ma non riesci a iniziare perché “prima devo decidere l’architettura giusta”. Questa paralisi può durare mesi o anni. Nel caso di Maganti, 8 anni.

L’AI rompe questo ciclo in modo brutalmente efficace. Non perché produca architetture migliori — ma perché ti dà qualcosa di concreto su cui lavorare in pochi minuti. Invece di decidere in astratto come strutturare un parser SQLite, ti ritrovi con 200 righe di codice funzionante che puoi modificare, rifiutare, o usare come punto di partenza.

La psicologia qui è importante: iterare su qualcosa di concreto è 10x più veloce che progettare nel vuoto. L’AI trasforma decisioni architetturali astratte in problemi di implementazione concreti — e questi ultimi hanno risposte oggettive che puoi verificare.

Dove questo si traduce in velocità misurabile con Claude Code:

• Prototipo iniziale: da 0 a “funziona sul caso base” in ore invece di giorni
• Boilerplate: test unitari, CI/CD, error handling standard — delegabili completamente
• Refactoring guidato: “questa funzione fa troppe cose, separala” — Claude Code legge il file, propone la divisione, esegue la modifica
• Debug assistito: incolla lo stack trace, Claude legge i file rilevanti, identifica la causa in decine di secondi invece di minuti

Il rischio reale: accettare decisioni architetturali mediocri

Maganti ha dovuto ricominciare da zero dopo il primo prototipo. Non per un bug. Per scelte strutturali sbagliate che l’AI aveva preso in automatico e lui aveva accettato perché sembravano ragionevoli.

Questa è la trappola più pericolosa del lavoro con AI su progetti non banali: il codice generato sembra professionale, è formattato bene, ha commenti sensati, passa i test. Ma l’architettura sottostante riflette pattern generici appresi dal training — non la soluzione ottimale per il tuo contesto specifico.

La distinzione che Maganti fa è precisa e utile: “L’implementazione ha una risposta giusta. Il design no.”

Quando chiedi a Claude Code di implementare una funzione specifica — “scrivi una funzione che parsa questo formato SQL” — produce codice valutabile oggettivamente: funziona o non funziona, è veloce o lento, gestisce gli edge case o no. Puoi testarlo, misurarlo, rifiutarlo con criteri chiari.

Quando chiedi “come struttura questo sistema?”, produce qualcosa che sembra ragionevole ma:

• Non conosce i tuoi vincoli di manutenzione futura
• Non sa come questo componente si integrerà con il resto del tuo sistema tra 6 mesi
• Tende verso pattern over-engineered (dependency injection, factory pattern, ecc.) perché sono sovrarappresentati nel training data
• Non ha skin in the game: non è lui che dovrà mantenere il codice

Come strutturare il lavoro per evitare il ricominciare da zero

La formula che emerge dall’esperienza di Maganti — e che coincide con quello che i team più efficaci stanno adottando — è una separazione netta di responsabilità:

Prima della sessione Claude Code: decidi tu la struttura

Prima di aprire Claude Code su un task non banale, scrivi le decisioni architetturali — anche solo in un file NOTES.md o in commenti nel codice. Esempio pratico:

# NOTES.md — decisioni architetturali
# Parser: approccio ricorsivo discendente (non parser combinators — troppo overhead)
# Storage: SQLite diretto, no ORM — la semplicità vale la mancanza di astrazione
# Error handling: Result type, no exceptions — consistenza con il resto del codebase
# Test: solo integration test su SQL reali, no mock — troppo fragile

Con questo contesto nel file, Claude Code incorpora queste decisioni quando generi codice nella stessa directory. Stai guidando il modello con le tue scelte, non lasciandolo libero di fare le proprie.

Durante la sessione: task atomici ben definiti

Claude Code lavora meglio con task specifici e misurabili. Confronta:

# Richiesta vaga (risultato mediocre)
"refactora il modulo parser"

# Richiesta specifica (risultato migliore)
"la funzione parse_create_table in parser.py ha 3 responsabilità separate: 
tokenizzazione, validazione della sintassi, e costruzione dell'AST. 
Separala in 3 funzioni mantenendo l'interfaccia pubblica invariata e 
aggiorna i test esistenti"

La specificità non è burocrazia — è il modo in cui comunichi il contesto che Claude Code non può derivare dal codice da solo.

Dopo la sessione: review delle decisioni strutturali

Prima di andare avanti, leggi il codice generato con l’occhio su: l’astrazione introdotta ha senso nel tuo contesto? Il naming riflette i concetti del tuo dominio? Se hai dubbi, è il momento di correggere — non dopo aver costruito altri 500 righe sopra.

Metriche di produttività: cosa aspettarsi realisticamente

I numeri che circolano sul “10x più veloce con AI” sono reali in alcuni contesti e completamente sbagliati in altri. Basandomi sull’esperienza di Maganti e su altri casi documentati:

Task	Speedup realistico	Note
Prototipo iniziale (da 0 a funzionante)	5-10x	Il caso più forte per l’AI
Implementazione con spec chiare	3-5x	Dipende dalla complessità
Refactoring con contesto buono	3-4x	Claude Code legge l’intera codebase
Debug con stack trace	2-5x	Molto variabile
Test unitari su codice esistente	5-8x	Ottimo caso d’uso
Decisioni architetturali	0x o negativo	Non delegare — costo del ricominciare da zero
Code review critica	1x	Utile per checklist, non per giudizio

Il numero aggregato per un progetto come syntaqlite — dove la struttura era già decisa e l’AI lavorava sull’implementazione — è circa 4-5x. Non 10x, non 1x. Quattro-cinque volte più veloce sulla parte di lavoro che può fare, su una fraction del lavoro totale che non può toccare.

Il setup che funziona per sviluppo con Claude Code

Alcune configurazioni pratiche che migliorano il risultato:

# Crea un CLAUDE.md nella root del progetto
# Claude Code lo legge automaticamente all'avvio di ogni sessione
cat > CLAUDE.md << 'EOF'
# Contesto progetto per Claude Code

## Architettura
- Parser: ricorsivo discendente in Python 3.12
- No ORM — SQLite diretto via sqlite3 stdlib
- Error handling: eccezioni tipizzate, no Result type

## Convenzioni
- Naming: snake_case ovunque, prefisso _ per privato
- Test: pytest, solo integration test su SQL reali (no mock)
- Import: assoluti sempre, no relative

## Non fare
- Non introdurre dipendenze esterne senza chiedere
- Non aggiungere type: ignore senza spiegazione
- Non cambiare interfacce pubbliche senza avvisare
EOF

Il file CLAUDE.md è il modo ufficiale per dare a Claude Code il contesto persistente del progetto. È l’equivalente del “sai già come lavoriamo” che daresti a un nuovo collaboratore.

La conclusione onesta

L’AI nello sviluppo software non è uno strumento che ti fa fare il lavoro di un developer senza essere un developer. È uno strumento che moltiplica la velocità di un developer su implementazione, boilerplate e task ripetitivi — riducendo il tempo che passa tra “ho un’idea” e “ho qualcosa che funziona”.

Il rischio non è che scriva codice sbagliato — il rischio è che tu smetta di pensare all’architettura perché c’è qualcosa che sembra pensarci per te. Non lo fa. Quella parte rimane completamente tua. E se la deleghi, prima o poi ricomincia da zero.

Fonte: Simon Willison (simonwillison.net) — “Eight years of wanting, three months of building with AI” di Lalit Maganti, aprile 2026