Claude Code per le indagini sulle prestazioni: un flusso di lavoro misurato

Perché il lavoro sulle prestazioni fallisce senza misurazione

I bug delle prestazioni invitano a fare supposizioni. Qualcuno nota che una pagina sembra lenta o che un'API va in timeout, e la mossa più rapida è "pulire" il codice, aggiungere cache o riscrivere un ciclo. Il problema è che "sembra lento" non è una metrica, e "più pulito" non è sempre uguale a più veloce.

Senza misurazione i team sprecano ore cambiando la cosa sbagliata. Il percorso critico potrebbe essere nel database, nella rete o in una singola allocazione inattesa, mentre il team lucida codice che incide poco sull'esecuzione. Peggio: una modifica che sembra intelligente può peggiorare le prestazioni: logging aggiuntivo in un ciclo stretto, una cache che aumenta la pressione di memoria, o lavoro parallelo che genera contesa sui lock.

L'indovinare rischia anche di rompere comportamenti. Quando cambi codice per velocizzarlo potresti alterare i risultati, la gestione degli errori, l'ordine o i retry. Se non ricontrolli correttezza e velocità insieme, puoi "vincere" un benchmark mentre passi in produzione un bug.

Tratta le prestazioni come un esperimento, non come un dibattito. Il loop è semplice e ripetibile:

• Scegli una metrica che rappresenti il problema (latenza, throughput, CPU, memoria, tempo DB).
• Cattura una baseline nelle stesse condizioni.
• Cambia una cosa piccola.
• Misura di nuovo e confronta.

Molte vittorie sono modeste: togliere l'8% dalla p95, ridurre la memoria di picco di 50 MB, o eliminare una query al database. Questi miglioramenti contano, ma solo se sono misurati, verificati e ripetibili.

Il flusso: misura, ipotizza, cambia, rimisura

Funziona meglio come loop, non come una richiesta una tantum di "rendilo più veloce". Il loop ti mantiene onesto perché ogni azione si ricollega a una prova e a un numero che puoi osservare.

Sequenza chiara:

• Misura: scegli una metrica e registra una baseline.
• Ipotizza: spiega cosa pensi sia lento e perché.
• Cambia: fai la minima modifica possibile che metta alla prova l'ipotesi.
• Rimisura: esegui la stessa misura e confronta.

Ogni passo ti protegge da un diverso tipo di autoinganno. Misurare prima ti evita di "riparare" qualcosa che non era il vero problema. Un'ipotesi scritta ti impedisce di cambiare cinque cose insieme e poi indovinare quale abbia inciso. Le modifiche minime riducono il rischio di rompere comportamenti o introdurre nuovi colli di bottiglia. Rimisurare cattura i falsi positivi (per esempio un run più veloce causato da cache calda) ed espone regressioni.

"Finito" non è una sensazione. È un risultato: la metrica obiettivo si è mossa nella direzione giusta e la modifica non ha causato regressioni evidenti (errori, più memoria, peggior p95 o endpoint più lenti).

Sapere quando fermarsi fa parte del flusso. Smetti quando i guadagni si appiattiscono, quando la metrica è già sufficientemente buona per gli utenti, o quando l'idea successiva richiede grandi refactor per un piccolo vantaggio. Il lavoro sulle prestazioni ha sempre costi opportunità; il loop ti aiuta a spendere tempo dove rende davvero.

Scegli la metrica e fissa una baseline

Se misuri cinque cose insieme non saprai cosa è migliorato. Scegli una metrica primaria per questa indagine e tratta il resto come segnali di supporto. Per molti problemi user-facing la metrica è la latenza. Per lavoro batch può essere throughput, tempo CPU, uso memoria o anche costo cloud per esecuzione.

Sii specifico sullo scenario. "L'API è lenta" è troppo vago. "POST /checkout con un carrello tipico di 3 articoli" è misurabile. Mantieni gli input stabili così i numeri hanno senso.

Annota la baseline e i dettagli dell'ambiente prima di toccare il codice: dimensione del dataset, tipo di macchina, modalità di build, feature flag, concorrenza e warmup. Questa baseline è il tuo ancora. Senza di essa ogni cambiamento può sembrare progresso.

Per la latenza affidati alle percentili, non solo a una media. p50 mostra l'esperienza tipica, mentre p95 e p99 espongono la coda dolorosa di cui gli utenti si lamentano. Una modifica che migliora p50 ma peggiora p99 può comunque dare una sensazione di lentezza.

Decidi in anticipo cosa significa "significativo" così non ti accontenti del rumore:

• Latenza: almeno 10% di miglioramento sulla p95 (o una soglia fissa come 50 ms)
• Throughput: almeno 5% in più di richieste al secondo allo stesso tasso di errori
• CPU o memoria: riduzione sufficiente ad evitare autoscaling o crash
• Costo: calo misurabile per esecuzione o per 1.000 richieste

Una volta stabilite queste regole, puoi testare idee senza spostare gli obiettivi.

Raccogli evidenze con profiling e metriche semplici

Inizia con il segnale più semplice di cui ti puoi fidare. Un singolo timing intorno a una richiesta può dirti se hai un problema reale e quanto è grosso; conserva il profiling profondo per quando devi spiegare perché è lento.

Buone evidenze provengono spesso da una combinazione di fonti:

• Log dell'app (durata richiesta, tasso di errori, endpoint più lenti)
• APM traces (dove si spende il tempo tra servizi)
• Output del profiler o flame graph (funzioni calde e call stack)
• Statistiche del DB (query lente, lock wait, hit rate della cache)
• Metriche infrastrutturali (CPU, memoria, rete, riavvii di container)

Usa metriche semplici quando la domanda è "è più lento e di quanto?" Usa il profiling quando la domanda è "dove va il tempo?" Se la p95 è raddoppiata dopo un deploy, parte da timing e log per confermare la regressione e circoscriverla. Se i timing mostrano che la maggior parte del ritardo è nel codice dell'app (non nel DB), allora un profiler CPU o un flame graph possono indicare la funzione esatta che è cresciuta.

Mantieni le misure sicure. Raccogli ciò che ti serve per fare debug delle prestazioni, non contenuti utente. Preferisci aggregati (durate, conteggi, dimensioni) ai payload raw e oscurare identificatori per default.

Il rumore è reale: prendi più campioni e annota gli outlier. Esegui la stessa richiesta 10–30 volte e registra mediana e p95 invece di usare una singola esecuzione migliore.

Scrivi la ricetta di test esatta così puoi ripeterla dopo le modifiche: ambiente, dataset, endpoint, dimensione del body, livello di concorrenza e come hai catturato i risultati.

Trasforma le evidenze in un'ipotesi chiara

Parti da un sintomo che puoi nominare: "la p95 sale da 220 ms a 900 ms durante i picchi", "la CPU è al 95% su due core" o "la memoria cresce di 200 MB all'ora". Sintomi vaghi come "sembra lento" portano a cambi casuali.

Poi traduci ciò che hai misurato in un'area sospetta. Un flame graph potrebbe mostrare molto tempo in JSON encoding, una trace potrebbe mostrare un percorso di chiamate lento, o le statistiche DB potrebbero mostrare una query che domina il tempo totale. Scegli l'area più piccola che spiega la maggior parte del costo: una funzione, una singola query SQL o una chiamata esterna.

Una buona ipotesi è una frase, testabile e legata a una previsione. Stai chiedendo di testare un'idea, non di far magicamente tutto più veloce.

Un template semplice per l'ipotesi

Usa questo formato:

• A causa di (evidenza), (sospetto) sta causando (sintomo).
• Se cambiamo (comportamento specifico), allora (metrica) dovrebbe migliorare di (stima approssimativa).
• Sapremo che ha funzionato se (risultato della rimisurazione).

Esempio: "Perché il profilo mostra il 38% della CPU in SerializeResponse, allocare un nuovo buffer per richiesta sta causando picchi CPU. Se riusiamo un buffer, la p95 dovrebbe scendere di circa 10–20% e la CPU di ~15% sotto lo stesso carico."

Mantieniti onesto nominando alternative prima di toccare il codice. Forse la parte lenta è un dipendente upstream, contesa sui lock, un cambiamento nel miss rate della cache o un rollout che ha aumentato la dimensione del payload.

Scrivi 2–3 spiegazioni alternative, poi scegli quella supportata meglio dalle evidenze. Se la tua modifica non muove la metrica, hai già l'ipotesi successiva pronta.

Come usare Claude Code senza scivolare nell'indovinare

Claude è più utile nel lavoro sulle prestazioni quando lo tratti come un analista attento, non come un oracolo. Mantieni ogni suggerimento ancorato a ciò che hai misurato e assicurati che ogni passo possa essere confutato.

Dagli input reali, non una descrizione vaga. Incolla piccole evidenze mirate: un sommario di profiling, alcune righe di log attorno alla richiesta lenta, un piano di query e il percorso di codice specifico. Includi i numeri "prima" (p95, tempo CPU, tempo DB) così sappia la tua baseline.

Chiedigli di spiegare cosa i dati suggeriscono e cosa non supportano. Poi forza spiegazioni concorrenti. Un prompt utile finisce con: "Dammi 2–3 ipotesi e per ciascuna dimmi cosa la falsificherebbe." Questo evita di fissarsi sulla prima storia plausibile.

Prima di cambiare qualcosa, chiedi il più piccolo esperimento che possa validare l'ipotesi principale. Fallo rapido e reversibile: aggiungi un timer attorno a una funzione, abilita una flag del profiler, o esegui una query DB con EXPLAIN.

Se vuoi una struttura compatta per l'output, chiedi:

• Cosa indicano le evidenze (e con quale confidenza)
• 2–3 ipotesi con un test di falsificazione
• La minima modifica di codice/config per testare la prima
• Esattamente quale metrica rimisurare e la direzione attesa

Se non riesce a nominare una metrica, una posizione e un risultato atteso, sei tornato a indovinare.

Fai modifiche minime e reversibili

Dopo avere evidenza e un'ipotesi, resisti alla tentazione di "pulire tutto". Il lavoro sulle prestazioni è più affidabile quando la modifica è piccola e facilmente annullabile.

Cambia una cosa alla volta. Se modifichi una query, aggiungi caching e refattorizzi un ciclo nello stesso commit, non saprai cosa ha aiutato (o danneggiato). Le modifiche a variabile singola rendono la misura successiva significativa.

Prima di toccare il codice, annota cosa ti aspetti in numeri. Esempio: "la p95 dovrebbe scendere da 420 ms a sotto 300 ms, e il tempo DB dovrebbe calare di ~100 ms." Se il risultato manca l'obiettivo, impari rapidamente che l'ipotesi era debole o incompleta.

Mantieni le modifiche reversibili:

• Preferisci un diff piccolo che si possa revertare chiaramente.
• Metti la modifica dietro a una flag così la puoi spegnere.
• Evita refactor di passaggio che cambiano nomi, formattazione e logica insieme.
• Mantieni lo scope stretto: un endpoint, un percorso caldo, una chiamata costosa.
• Aggiungi una breve nota nel commit con le metriche before/after attese.

"Minimo" non significa "banale." Significa concentrato: cache un risultato di funzione costosa, rimuovi un'allocazione ripetuta in un ciclo stretto o evita lavoro per richieste che non ne hanno bisogno.

Aggiungi un timing leggero attorno al collo di bottiglia sospettato così puoi vedere cosa è cambiato. Un singolo timestamp prima e dopo una chiamata (loggato o catturato come metrica) può confermare se la tua modifica ha colpito la parte lenta o ha solo spostato il tempo altrove.

Rimisura e decidi cosa fare dopo

Dopo una modifica, riesegui esattamente lo stesso scenario usato per la baseline: stessi input, ambiente e forma di carico. Se il test dipende da cache o warm-up, rendilo esplicito (per esempio: "prima esecuzione cold, successive 5 warm"). Altrimenti troverai miglioramenti che erano solo fortuna.

Confronta i risultati usando la stessa metrica e le stesse percentili. Le medie possono nascondere i problemi, quindi tieni d'occhio p95 e p99, oltre a throughput e tempo CPU. Esegui sufficienti ripetizioni per vedere se i numeri si stabilizzano.

Prima di festeggiare, controlla le regressioni che non si vedono in un numero principale:

• Correttezza: le risposte coincidono ancora con l'output atteso.
• Tasso di errore: timeouts, 5xx, retry.
• Memoria: picco più alto o crescita costante tra le esecuzioni.
• Latenza di coda: p99 peggiora anche se p50 migliora.
• Costo in risorse: CPU o carico DB è salito.

Poi decidi basandoti sulle evidenze, non sulla speranza. Se il miglioramento è reale e non hai introdotto regressioni, mantieni la modifica. Se i risultati sono misti o rumorosi, revert e formula una nuova ipotesi, oppure isola ulteriormente la modifica.

Se lavori su una piattaforma come Koder.ai, prendere uno snapshot prima di sperimentare può rendere il rollback un singolo passo, facilitando test di idee più audaci in sicurezza.

Infine, annota ciò che hai imparato: la baseline, la modifica, i nuovi numeri e la conclusione. Questo breve record evita che il giro successivo ripeta gli stessi vicoli ciechi.

Errori comuni che fanno perdere tempo

Il lavoro sulle prestazioni di solito devia quando perdi il filo tra ciò che hai misurato e ciò che hai cambiato. Mantieni una catena pulita di evidenze così puoi dire con fiducia cosa ha migliorato o peggiorato le cose.

I soliti colpevoli:

• Sistemare il bersaglio sbagliato: festeggi una mediana più veloce (p50) mentre la latenza di coda (p95/p99) resta alta.
• Cambiare troppe cose insieme: refactor, caching e tweak alle query in un unico commit significa che non sai cosa ha aiutato.
• Credere a una singola esecuzione rumorosa: un benchmark locale che oscilla del 20% tra esecuzioni non è prova.
• Trattare un singolo profilo come verità assoluta: un flame graph punta il parsing JSON, ma le richieste si accumulano durante rallentamenti DB.
• Confrontare mele con arance: dataset diversi, feature flag, hardware o concorrenza differenti e poi trarre conclusioni.

Un piccolo esempio: un endpoint sembra lento, quindi ottimizzi il serializer perché è caldo in un profilo. Poi ritesti con un dataset più piccolo e sembra più veloce. In produzione la p99 peggiora perché il database è ancora il collo di bottiglia e la tua modifica ha aumentato la dimensione del payload.

Se usi Claude Code per proporre fix, tienilo corto: chiedi 1–2 modifiche minime che corrispondano alle evidenze raccolte e insisti su un piano di re-misurazione prima di accettare una patch.

Una checklist rapida prima di dichiarare “più veloce”

Le affermazioni di velocità si sfaldano quando il test è vago. Prima di festeggiare, assicurati di poter spiegare cosa hai misurato, come lo hai misurato e cosa hai cambiato.

Inizia nominando una metrica e scrivendo la baseline. Includi i dettagli che cambiano i numeri: tipo macchina, carico CPU, dimensione del dataset, modalità build (debug vs release), feature flag, stato della cache e concorrenza. Se non riesci a ricreare l'assetup domani, non hai una baseline.

Checklist:

• Metrica e baseline registrate con note sull'ambiente (hardware, config, dati, cache fredda/calda).
• I passi del test sono scritti e ripetibili.
• Hai un'ipotesi con una previsione (es. "Se rimuoviamo le query N+1, la p95 dovrebbe scendere di ~30% ").
• Hai fatto un'unica modifica piccola e reversibile e documentato esattamente cosa si è mosso (file, funzione, query, setting).
• Hai rimisurato con campioni multipli e confrontato "come con come" (stessi input, stesso carico).

Dopo che i numeri sono migliori, fai una veloce verifica di regressione. Controlla correttezza (stessi output), tasso di errori e timeouts. Osserva effetti collaterali come più memoria, picchi CPU, avvio più lento o maggiore carico DB. Una modifica che migliora la p95 ma raddoppia la memoria potrebbe essere un trade sbagliato.

Esempio: investigare passo passo un endpoint API lento

Un team segnala che GET /orders va bene in dev ma rallenta in staging con carichi moderati. Gli utenti si lamentano di timeouts, ma la latenza media sembra "abbastanza OK", che è una trappola classica.

Prima, fissa una baseline. Con un load test stabile (stesso dataset, stessa concorrenza e durata) registri:

• p95 latency: 1.8s (obiettivo < 600ms)
• CPU API: ~70% con picchi occasionali
• DB: una query impiega 900–1100ms, e il tempo totale query per richiesta è ~1.3s

Raccogli evidenze. Una trace rapida mostra che l'endpoint esegue una query principale per gli ordini, poi itera e recupera gli item correlati per ordine. Noti anche che la risposta JSON è grande, ma il tempo DB domina.

Trasforma questo in una lista di ipotesi testabili:

• Una query lenta ha bisogno di un indice.
• Query N+1 stanno moltiplicando il tempo DB.
• La serializzazione è lenta a causa del payload enorme.
• Contesa sui lock blocca le letture durante le scritture.

Chiedi una modifica minima che corrisponda all'evidenza più forte: rimuovere una chiamata N+1 fetchando gli item in una singola query con chiave sugli order ID (o aggiungere l'indice mancante se il piano di esecuzione mostra una scansione completa). Mantienila reversibile e in un commit focalizzato.

Rimisura con lo stesso load test. Risultati:

• p95 latency: 1.8s -> 720ms
• Tempo DB totale: ~1.3s -> ~420ms
• CPU: leggermente più bassa, ma ancora con picchi

Decisione: deploya la fix (vittoria chiara), poi avvia un secondo ciclo focalizzato sul gap residuo e sui picchi di CPU, dato che il DB non è più il principale limite.

Prossimi passi: rendi il flusso routine

Il modo più veloce per migliorare nelle indagini sulle prestazioni è trattare ogni run come un piccolo esperimento ripetibile. Quando il processo è consistente, i risultati diventano più affidabili da confrontare e condividere.

Un template di una pagina aiuta:

• Metrica + come è misurata (tool, comando, dataset)
• Baseline (numeri, ambiente, quando catturata)
• Ipotesi (una frase, testabile)
• Modifica (diff piccolo, cosa è stato toccato)
• Risultato (prima/dopo, e decisione)

Decidi dove vivono queste note così non scompaiono. Un posto condiviso conta più dello strumento perfetto: una cartella nel repo accanto al servizio, un doc di team o note nel ticket. L'importante è la reperibilità. Qualcuno deve poter trovare "p95 spike dopo cambio cache" mesi dopo.

Rendi gli esperimenti sicuri un'abitudine. Usa snapshot e rollback facili così puoi provare un'idea senza paura. Se costruisci con Koder.ai, Planning Mode può essere un posto comodo per delineare il piano di misura, definire l'ipotesi e tenere la modifica scoping prima di generare un diff mirato e rimisurare.

Stabilisci una cadenza. Non aspettare gli incidenti. Aggiungi piccoli controlli di performance dopo cambi come query nuove, endpoint nuovi, payload più grandi o aggiornamenti di dipendenze. Un check di baseline di 10 minuti ora può risparmiarti una giornata di indovinare dopo.