Claude Code per l'onboarding della codebase: usa prompt Q&A per mappare moduli, flussi chiave e rischi, poi trasforma le note in un breve documento di onboarding.
Leggere file a caso è lento perché la maggior parte delle codebase non è organizzata come una storia. Apri una cartella, vedi dieci nomi che sembrano importanti, clicchi uno e finisci in helper, config e casi limite. Dopo un'ora hai tanti dettagli ma non riesci ancora a spiegare come funziona l'app.
Un obiettivo migliore per Claude Code durante l'onboarding è costruire una semplice mappa mentale. Quella mappa dovrebbe rispondere a tre domande:
Un onboarding "sufficiente" in 1–2 giorni non è "Posso spiegare ogni classe." È più vicino a questo:
Alcune cose possono aspettare. Refactor profondi, capire perfettamente ogni astrazione e leggere vecchio codice che nessuno tocca raramente ti danno il massimo valore subito.
Pensa all'onboarding come a costruire una mappa, non a memorizzare le strade. I tuoi prompt dovrebbero riportarti sempre a: “Dove sono nel sistema, cosa succede dopo e cosa potrebbe andare storto qui?” Una volta che hai quello, i dettagli diventano più facili da imparare al bisogno.
Prima di iniziare a fare domande, raccogli le basi che normalmente ti servono il primo giorno. Claude Code funziona meglio quando può reagire a file reali, config reali e comportamenti che puoi riprodurre.
Inizia con accesso e un'esecuzione funzionante. Assicurati di poter clonare la repo, installare le dipendenze e avviare l'app (o almeno una piccola porzione) in locale. Se la configurazione locale è difficile, ottieni accesso a un ambiente di staging e a dove vivono i log, così puoi verificare cosa fa davvero il codice.
Poi trova i documenti "sorgente di verità". Cerchi ciò che il team aggiorna davvero quando le cose cambiano: un README, una breve nota di architettura, una cartella ADR, un runbook o una nota di deployment. Anche se sono disordinati, danno nomi a moduli e flussi, il che rende la Q&A molto più precisa.
Decidi lo scope presto. Molte repo contengono più app, servizi e pacchetti condivisi. Scegli confini come "solo l'API e il worker di billing" o "solo la web app e il suo flusso di auth." Uno scope chiaro evita deviazioni infinite.
Annota le assunzioni che non vuoi che l'assistente indovini. Sembra poca cosa, ma previene modelli mentali sbagliati che fanno perdere ore dopo.
Ecco una semplice checklist preparatoria:
Se qualcosa manca, catturalo come domanda per un collega. Non "aggirare" il contesto mancante con supposizioni.
Una mappa mentale è un piccolo insieme di note che risponde: quali sono le parti principali di questa app, come comunicano tra loro e dove può andare storto. Fatto bene, l'onboarding diventa meno navigazione tra file e più costruzione di un'immagine riutilizzabile.
Inizia definendo i tuoi output. Vuoi una lista di moduli pratica, non perfetta. Per ogni modulo, cattura cosa fa, chi lo possiede (team o persona se lo sai) e le sue dipendenze chiave (altri moduli, servizi, database, API esterne). Nota anche i punti di ingresso principali: rotte UI, endpoint API, job in background e task schedulati.
Poi scegli alcuni percorsi utente che contano. Tre-cinque sono sufficienti. Scegli flussi che toccano denaro, permessi o modifiche di dati. Esempi: signup e verifica email, creare un piano a pagamento o un acquisto, un'azione admin che cambia l'accesso di un utente e un flusso critico di uso quotidiano di cui la maggior parte degli utenti dipende.
Decidi come etichetterai il rischio prima di iniziare a raccogliere note. Mantieni le categorie semplici così da poterle scorrere velocemente. Un set utile è sicurezza, integrità dei dati, uptime e costo. Quando segnali qualcosa come rischioso, aggiungi una frase che spiega perché, più cosa proverebbe che è sicuro (un test, un log, un controllo di permessi).
Usa un formato coerente così puoi trasformare le note in un documento di onboarding senza riscrivere tutto:
Esempio: se Checkout chiama Billing che scrive su payments e invoices, etichettalo come integrità dei dati e costo. Poi nota dove avvengono i retry e cosa impedisce il doppio addebito.
Quando entri in una nuova repo vuoi un'orientazione veloce, non una comprensione perfetta. Questi prompt ti aiutano a costruire una mappa mentale in passi piccoli e sicuri.
Inizia dando all'assistente l'albero della repo (o un sottoinsieme incollato) e chiedi un tour. Mantieni ogni round focalizzato, poi concludi con una domanda che ti dica cosa leggere dopo.
1) Repo tour
"Here is the top-level folder list: <paste>. Explain what each folder likely contains and which ones matter for core product behavior."
2) Entry points
"Find the app entry points and boot process. What files start the app, set up routing, configure DI/env, and start background jobs? Name the exact files and what they do."
3) Module index
"Create a module index: module name, purpose, key files, and important external dependencies. Keep it to the modules that affect user-facing behavior."
4) Data model hints
"Based on migrations/models, list the key tables/entities, critical fields, and relationships. Call out fields that look security-sensitive or used for billing/permissions."
5) Flow trace
"Trace this flow end-to-end: <flow>. Where does the request/event start, where does it end, and what does it call in between? List the main functions/files in order."
6) Next inspection
"What should I inspect next and why? Give me 3 options: fastest clarity, riskiest area, and best long-term payoff."
Un esempio concreto: se stai mappando "l'utente si registra e crea il suo primo progetto", chiedi per l'handler della route API, la validazione, la scrittura su DB e qualsiasi job asincrono che invia email o provisiona risorse. Poi riesegui il flow trace per "l'utente elimina progetto" per individuare gap di cleanup.
Per mantenere le risposte azionabili, chiedi artefatti specifici, non solo riassunti:
La più grande vittoria nell'onboarding è trasformare Q&A sparsi in note che un altro sviluppatore può riusare. Se le note hanno senso solo per te, rifarai la stessa scavata dopo.
Una struttura semplice batte pagine lunghe. Dopo ogni sessione di esplorazione, salva le risposte in cinque piccoli artefatti (un file o un doc va bene): una tabella moduli, un glossario, i flussi chiave, gli ignoti e un registro dei rischi.
Ecco un template compatto che puoi incollare nelle tue note e compilare man mano:
Module table
- Module:
Owns:
Touches:
Entry points:
Glossary
- Term:
Meaning:
Code name(s):
Key flow (name)
1.
2.
3.
Unknowns
- Question:
Best person to ask:
Where to look next:
Risk register
- Risk:
Location:
Why it matters:
How to verify:
Mantieni i flussi chiave volutamente brevi. Esempio: 1) l'utente effettua il login, 2) il backend crea una sessione, 3) il client carica la dashboard, 4) l'API recupera i dati, 5) l'UI rende e gestisce gli errori. Se non riesci a tenere un flusso in cinque passi, dividilo (login vs caricamento dashboard).
Quando usi Claude Code, aggiungi una riga a ogni risposta: "Come testerei questo?" Quella singola riga trasforma note passive in una checklist che puoi eseguire dopo, specialmente quando ignoti e rischi si sovrappongono.
Se stai costruendo in una piattaforma vibe-coding come Koder.ai, questo tipo di presa di appunti ti aiuta anche a vedere dove le modifiche generate potrebbero avere effetti collaterali. I moduli con molti touchpoint tendono a essere calamite per i cambiamenti.
Il rischio in una codebase raramente è casuale. Si concentra dove l'app decide chi sei, cambia dati, parla con altri sistemi o esegue lavoro in background. Puoi trovare la maggior parte con domande mirate e poche ricerche focalizzate.
Inizia dall'identità. Chiedi dove avviene l'autenticazione (login, sessione, token) e dove vivono le decisioni di autorizzazione (controlli di ruolo, feature flag, regole di ownership). Una trappola comune è avere controlli sparsi tra UI, handler API e query DB senza una singola fonte di verità.
Poi mappa i percorsi di scrittura. Trova endpoint o funzioni che creano, aggiornano o eliminano record, più le migrazioni che rimodellano i dati nel tempo. Includi anche i job in background. Molti bug misteriosi vengono da worker asincroni che scrivono valori inaspettati molto dopo che una richiesta è finita.
Prompt che emergono rischio velocemente:
Poi controlla configurazione e gestione dei segreti. Cerca variabili d'ambiente, file di config runtime e fallback di default. I default sono utili, ma rischiosi quando nascondono misconfigurazioni (per esempio usare una chiave dev in produzione perché manca un valore).
Un esempio rapido: in un backend Go con PostgreSQL potresti trovare un job "invia email" che riprova in caso di fallimento. Se riprova senza una idempotency key, gli utenti possono ricevere email duplicate. Se i fallimenti loggano solo un warning e non esiste un alert, fallisce silenziosamente. È un'area ad alto rischio da documentare e testare presto.
Usa un flusso reale per costruire il tuo primo thread end-to-end nel sistema. Il login è un buon punto di partenza perché tocca routing, validazione, sessioni o token e letture dal database.
Scenario: un'app React chiama una API Go, e l'API legge e scrive su PostgreSQL. Il tuo obiettivo non è capire ogni file. È rispondere: "Quando un utente clicca Login, quale codice viene eseguito dopo, quali dati si muovono e cosa può rompersi?" Così l'onboarding resta concreto.
Inizia dall'UI e procedi avanti, un hop alla volta. Chiedi nomi di file specifici, funzioni e shape di request/response.
Dopo ogni risposta scrivi una riga nella tua mappa mentale: "Componente UI -> endpoint API -> handler -> service -> query DB -> response." Includi i nomi, non solo "una funzione".
Una volta che hai il percorso, verificane l'esecuzione con un test veloce. Stai controllando che la strada mappata sia quella che l'app usa realmente.
Guarda le richieste di rete negli strumenti dev del browser (path, status code, body della risposta). Aggiungi o abilita log sul server intorno a handler e chiamata DB (request ID se disponibile). Interroga PostgreSQL per cambiamenti attesi (per il login, magari last_login_at, sessioni o righe di audit). Forza un fallimento (password sbagliata, campo mancante) e annota dove viene creato il messaggio di errore e dove viene mostrato. Registra risposte attese per successo e fallimento (status code e campi chiave), così il prossimo sviluppatore può fare un sanity check rapido.
Questo singolo flusso spesso espone confini di ownership: cosa si aspetta la UI, cosa applica l'API e dove gli errori scompaiono o vengono doppiamente gestiti.
Una volta che hai una mappa mentale decente, fissala in una nota di 1–2 pagine. Lo scopo non è essere completa. È aiutare il prossimo sviluppatore a rispondere: che cos'è questa app, dove guardo prima e cosa è più probabile che si rompa?
Se usi Claude Code, considera il documento come l'output della tua Q&A: chiaro, concreto e facile da scorrere.
Mantieni il documento prevedibile così le persone trovano rapidamente le informazioni. Una buona struttura è:
Per "Dove stanno le cose" includi puntatori tipo "Auth inizia in X, logica sessione in Y, rotte UI in Z." Evita di scaricare tutto l'albero. Scegli solo ciò che la gente toccherà.
Per "Flussi chiave" scrivi 4–7 passi per flusso: trigger, controller o handler, modulo core, chiamata al DB e effetto esterno (email inviata, stato aggiornato, job in coda). Aggiungi nomi di file a ogni passo.
Per "Aree rischiose" nomina la modalità di fallimento e il controllo di sicurezza più veloce (un test specifico, una smoke run o un log da monitorare).
Concludi con una piccola lista di primi task così qualcuno può contribuire in sicurezza:
Il modo più veloce per sprecare un assistente è chiedere "una spiegazione completa di tutta la repo." Ottieni un riassunto lungo che suona sicuro ma resta vago. Invece, scegli una porzione piccola che conta (un modulo più un flusso utente), poi espandi.
Un secondo errore comune è non specificare quali viaggi contano. Se non dici "checkout", "login" o "modifica admin", le risposte virano nel generico. Inizia ogni sessione con un obiettivo concreto: "Aiutami a capire il flusso di signup end to end, incluse validazioni, stati di errore e dove sono memorizzati i dati."
Un'altra trappola è lasciare che l'assistente indovini. Quando qualcosa non è chiaro, obbligalo a segnalarlo come incertezza. Chiedigli di separare quello che può provare dal codice da quello che inferisce.
Usa una semplice regola nelle tue note: ogni affermazione deve essere contrassegnata come una di queste.
Le note inoltre si disfano quando sono raccolte senza struttura. Una pila di snippet di chat è difficile da trasformare in una mappa mentale. Mantieni un template coerente: moduli coinvolti, punto di ingresso, funzioni e file chiave, dati toccati, effetti collaterali, percorsi di errore e test da eseguire.
Anche con Claude Code, considera l'output come una bozza. Verifica i flussi chiave eseguendo l'app, specialmente le parti che possono rompere la produzione: auth, pagamenti, permessi, job in background e migrazioni.
Un esempio pratico: se l'assistente dice "il reset della password invia un'email tramite X", confermalo attivando un reset in ambiente dev e controllando i log o la sandbox email. Quel controllo di realtà ti evita di fare onboarding su una storia non vera.
Non serve memorizzare la repo. Serve avere abbastanza fiducia per fare una modifica sicura, debuggare un problema reale e spiegare il sistema al prossimo.
Prima di dichiararti onboarded, assicurati di poter rispondere a queste senza indovinare:
Se ti manca una voce, fai un piccolo pass focalizzato invece di una ricerca ampia. Scegli un flusso, seguilo fino al confine del database, poi fermati e scrivi quello che hai imparato. Quando qualcosa è poco chiaro, trasformalo in una domanda, non in un paragrafo. "Dove viene creato il ruolo X?" è più utile di "l'auth è confusa."
Un buon test finale: immagina di dover aggiungere una piccola feature dietro una flag. Se sai nominare i file che toccheresti, i test che eseguirai e i modi in cui potrebbe fallare, sei abbastanza onboarded per contribuire responsabilmente.
Una mappa mentale è utile solo finché corrisponde alla realtà. Trattala come un artefatto vivo, non come un compito da una tantum. Il modo più semplice per mantenerla onesta è aggiornarla subito dopo cambiamenti che impattano il comportamento.
Una routine leggera batte grandi riscritture. Collega gli aggiornamenti al lavoro che fai già:
Tieni il documento di onboarding vicino al codice e versionalo con la stessa disciplina della codebase. Piccole diff vengono lette. Grandi riscritture spesso vengono saltate.
Quando i deploy sono rischiosi, scrivi cosa aiuterebbe il prossimo a recuperare velocemente: cosa è cambiato, cosa monitorare e come fare rollback. Se la tua piattaforma supporta snapshot e rollback, aggiungi il nome dello snapshot, il motivo e cosa significa "buono" dopo la correzione.
Se costruisci con Koder.ai (Koder.ai), la modalità planning può aiutarti a redigere una mappa dei moduli coerente e una nota di onboarding dalle tue Q&A, e l'export del codice sorgente dà ai reviewer un modo pulito per convalidare il risultato.
Infine, definisci una checklist di handoff che il prossimo sviluppatore possa seguire senza indovinare:
Fatto bene, Claude Code per l'onboarding della codebase diventa un'abitudine: ogni modifica lascia dietro di sé una mappa più chiara per il prossimo.
Punta a una mappa mentale utile, non a una comprensione totale.
Un buon risultato in 1–2 giorni è:
Forniscigli elementi concreti così può puntare al codice reale invece di indovinare:
Scegli un pezzo ristretto con confini chiari.
Un buon scope di default è:
Scrivi cosa è esplicitamente fuori scope (altri servizi, moduli legacy, feature poco usate) così l'assistente non si distrae.
Inizia dai trigger noti e cammina in avanti:
Chiedi percorsi di file e nomi di funzione in ordine, e finisci con: “Come testerei questo velocemente?”
Cerca dove il sistema prende decisioni o cambia stato:
Usa un semplice sistema di etichette e aggiungi un passo di verifica.
Esempio di formato:
Obbliga l'assistente a separare evidenza da inferenza.
Chiedigli di etichettare ogni affermazione come una di queste:
Quando qualcosa è sconosciuto, trasformalo in una domanda per un collega (“Dove è definito il ruolo X?”) invece di riempire il vuoto con un'ipotesi.
Tieni un unico file leggero con cinque sezioni:
Fai un rapido controllo reale:
Questo valida che hai mappato il percorso che l'app .
Usa le funzionalità della piattaforma per ridurre il rischio e mantenere le review semplici.
Impostazioni pratiche:
Poi chiedi: “Cosa si rompe in modo silenzioso e come lo noteremmo?”
Mantienilo breve così lo aggiornerai mentre impari.
Aggiungi una riga a ogni flow: “Come testerei questo?” così diventa una checklist.
Questo è particolarmente utile per attività di onboarding come “aggiungi un guardrail”, “rafforza la validazione” o “migliora un path di errore”.