Primo scenario di debugging guidato

Dopo aver installato e configurato Claude Code, possiamo finalmente entrare nella parte più operativa del workflow agentico, ovvero il debugging guidato. In questa lezione vedremo come utilizzare Claude Code come supporto intelligente nell’analisi di errori, anomalie logiche e comportamenti inattesi all’interno di un’applicazione reale.

L’obiettivo non è semplicemente "far correggere il bug" all’agente AI, ma imparare a costruire un processo collaborativo nel quale noi sviluppatori manteniamo il controllo architetturale mentre l’agente accelera l’individuazione del problema e propone soluzioni motivate. Uno degli aspetti più interessanti del coding agentico è proprio la capacità di ridurre drasticamente il tempo necessario per comprendere il contesto di un errore.

Nei workflow tradizionali spesso passiamo minuti o ore a seguire stack trace, inserire log temporanei, riprodurre condizioni specifiche e controllare manualmente le dipendenze coinvolte. Claude Code introduce invece un approccio diverso, infatti, possiamo fornirgli il contesto del progetto, i file rilevanti e il comportamento osservato, lasciando che analizzi correlazioni e anomalie in modo molto più rapido rispetto a una revisione esclusivamente manuale.

Analizzare un errore runtime

Immaginiamo di lavorare su una semplice applicazione Node.js che espone un endpoint API per recuperare dati utente. A prima vista il codice sembra corretto, ma in produzione alcuni utenti ricevono un errore HTTP 500 in modo intermittente. Il nostro obiettivo sarà usare Claude Code per identificare il problema.

Consideriamo questo esempio:

app.get("/users/:id", async (req, res) => {
    const userId = req.params.id;
    const user = await db.users.findOne({
        where: {
            id: userId
        }
    });
    res.json({
        id: user.id,
        name: user.name,
        email: user.email
    });
});

Durante i test funziona quasi sempre, ma occasionalmente il server genera un errore simile a questo:

TypeError: Cannot read properties of null (reading 'id')

In un approccio tradizionale probabilmente inizieremmo a inserire console.log, verificare la presenza dell’utente nel database oppure controllare i parametri della richiesta. Con Claude Code possiamo invece descrivere direttamente il comportamento osservato chiedendo un’analisi del problema.

Un prompt efficace potrebbe essere:

Analizza questo endpoint Express. A volte genera un errore: "Cannot read properties of null (reading 'id')" Spiega il problema e proponi una correzione sicura.

Claude Code individuerà rapidamente il punto critico: il metodo findOne() può restituire null quando l’utente non esiste, ma il codice assume che l’oggetto user sia sempre valido. Il problema non è quindi sintattico, ma logico. Questo è uno dei casi in cui il debugging agentico offre il massimo vantaggio, perché l’agente riesce a ragionare sul flusso applicativo e sulle possibili condizioni runtime.

app.get("/users/:id", async (req, res) => {
    const userId = req.params.id;
    const user = await db.users.findOne({
        where: {
            id: userId
        }
    });
    if (!user) {
        return res.status(404).json({
            error: "Utente non trovato"
        });
    }
    res.json({
        id: user.id,
        name: user.name,
        email: user.email
    });
});

Notiamo un aspetto importante: Claude Code non si limita a eliminare l’errore tecnico, ma suggerisce anche una gestione applicativa più corretta tramite una risposta HTTP coerente. Questo tipo di supporto ci aiuta a migliorare la qualità del software, non soltanto a correggere un bug isolato.

Debugging di codice asincrono

Nel debugging reale, gli scenari sono spesso più complessi. Gli errori possono derivare da race condition, dipendenze asincrone, variabili condivise o stati inconsistenti. In questi casi la qualità del contesto fornito all’agente diventa fondamentale. Più informazioni diamo a Claude Code, più accurata sarà l’analisi.

Supponiamo ora di avere un problema legato all’asincronia. Consideriamo questo codice:

let cache = {};
async function getUserProfile(userId) {
    if (cache[userId]) {
        return cache[userId];
    }
    const profile = fetchProfileFromApi(userId);
    cache[userId] = profile;
    return profile;
}

Il comportamento osservato è anomalo: alcune parti dell’applicazione ricevono una Promise invece di un oggetto profilo completo. A livello superficiale il codice sembra corretto, ma Claude Code può aiutarci a identificare rapidamente il problema.

Se chiediamo:

Perché questa funzione restituisce talvolta una Promise invece del profilo utente?

l’agente evidenzierà che fetchProfileFromApi() è asincrona ma non viene attesa tramite await. Di conseguenza nella cache viene salvata direttamente la Promise pendente invece del valore risolto.

La versione corretta sarà:

let cache = {};
async function getUserProfile(userId) {
    if (cache[userId]) {
        return cache[userId];
    }
    const profile = await fetchProfileFromApi(userId);
    cache[userId] = profile;
    return profile;
}

Debugging e stack trace complessi

Un altro vantaggio importante riguarda la capacità di interpretare stack trace articolati. In molte applicazioni enterprise gli errori attraversano diversi layer architetturali: controller, service, repository, middleware e librerie esterne. Seguire manualmente il flusso può diventare lento e dispersivo.

Immaginiamo di ricevere un errore come questo:

UnhandledPromiseRejectionWarning:
Error: Connection timeout
    at DatabaseClient.connect
    at UserRepository.findById
    at UserService.loadProfile
    at ProfileController.getProfile

Possiamo chiedere a Claude Code:

Analizza questo stack trace e individua il punto più probabile del problema.

L’agente sarà in grado di dedurre che il timeout avviene nella connessione al database e che i layer superiori stanno semplicemente propagando l’errore. Inoltre potrebbe suggerire l’aggiunta di timeout configurabili, retry controllati oppure gestione esplicita delle eccezioni.

Ad esempio:

try {
    const user = await userRepository.findById(id);
    return user;
} catch (error) {
    logger.error("Errore database", error);
    throw new ServiceUnavailableError(
        "Database temporaneamente non disponibile"
    );
}

In questo caso Claude Code non solo ci aiuta a localizzare il problema, ma migliora anche la resilienza dell’applicazione.

Individuare regressioni durante un refactoring

Vediamo ora un caso più vicino alla realtà produttiva: un bug introdotto durante un refactoring.

Supponiamo di avere questa funzione originale:

function calculateDiscount(price, user) {
    if (user.isPremium) {
        return price * 0.8;
    }
    return price;
}

Durante un refactoring viene modificata così:

function calculateDiscount(price, user) {
    return user?.isPremium
        ? price * 0.8
        : null;
}

Dopo il deploy alcuni ordini iniziano a generare valori null nei calcoli finali. Claude Code può aiutarci a confrontare le due versioni individuando rapidamente la regressione logica.

Un prompt di debugging utile potrebbe essere:

Confronta queste due versioni della funzione e identifica eventuali regressioni.

L'agente noterà immediatamente che la versione originale restituiva sempre price per gli utenti non premium, mentre quella nuova restituisce null. Questo tipo di analisi comparativa è estremamente utile durante i refactoring, perché consente di intercettare modifiche comportamentali involontarie.

La versione corretta sarà:

function calculateDiscount(price, user) {
    return user?.isPremium
        ? price * 0.8
        : price;
}

Conclusioni

Possiamo quindi affermare che il debugging guidato con Claude Code non rappresenta soltanto un'accelerazione tecnica, ma un cambiamento metodologico nel modo in cui affrontiamo i problemi software. L'agente AI diventa uno strumento di analisi contestuale capace di individuare correlazioni, suggerire correzioni e supportare il ragionamento architetturale.

Il vero valore emerge però quando integriamo queste capacità all'interno di un processo disciplinato di sviluppo: osservazione del problema, raccolta del contesto, formulazione precisa della richiesta, validazione della soluzione e verifica regressiva. Claude Code accelera ogni fase, ma resta fondamentale la nostra capacità di interpretare il sistema nel suo insieme.

Nella prossima lezione approfondiremo il tema della correzione assistita e del refactoring sicuro, vedendo come utilizzare Claude Code per modificare codice esistente minimizzando il rischio di introdurre regressioni o vulnerabilità nascoste.