Claude Code per l'onboarding della codebase: prompt che mappano la tua app

Cosa stai cercando di imparare (e cosa può aspettare)

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:

• Quali sono i moduli principali?
• Quali sono i flussi chiave che gli utenti attivano?
• Dove sono le aree rischiose che possono rompere la produzione o causare bug?

Un onboarding "sufficiente" in 1–2 giorni non è "Posso spiegare ogni classe." È più vicino a questo:

• Sai nominare i 5–8 moduli che contano e cosa gestisce ognuno.
• Sai tracciare 2–3 flussi utente reali end-to-end (dall'interfaccia o dall'entry API al database e ritorno).
• Conosci i rischi principali (pagamenti, auth, scritture dati, job in background) e dove si trovano.
• Puoi fare una piccola modifica in sicurezza perché sai cosa testare e chi chiedere.

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.

Lavoro preparatorio: ottieni contesto senza bollire l'oceano

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:

• Conferma accesso alla repo, permessi richiesti e come eseguire i test.
• Raccogli note per la configurazione dell'ambiente (env var, seed, feature flag) e dove si guardano log e metriche.
• Identifica i file di verità attuali (README, note di architettura, ADR, runbook).
• Definisci cosa è in scope e cosa è esplicitamente fuori scope per questo pass di onboarding.
• Imposta regole di sicurezza: non incollare mai segreti, API key, token, dati clienti privati o log di produzione con dettagli sensibili.

Se qualcosa manca, catturalo come domanda per un collega. Non "aggirare" il contesto mancante con supposizioni.

La mappa mentale: cosa catturare mentre esplori

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:

• Moduli: scopo, punti di ingresso, dipendenze, owner
• Flussi chiave: trigger, passi, dati scritti, punti di fallimento
• Dati: tabelle o collezioni toccate, campi importanti, vincoli
• Rischi: categoria, impatto peggiore, come monitorare, come fare rollback
• Domande aperte: cosa non sai ancora, chi chiedere

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.

Prompt passo-passo per esplorare una codebase con Q&A

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:

• Percorsi file e nomi di funzione
• Assunzioni e ignoranze chiaramente indicate
• Dipendenze formulate come "Se cambio X, cosa si rompe?"
• Un piccolo compito di lettura che puoi fare in 10 minuti

Come catturare le risposte così restano utili

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.

Trovare rapidamente aree rischiose (senza leggere ogni file)

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:

• "Elenca ogni posto che applica permessi per [risorsa X]. Qual è la verifica finale?"
• "Mostrami il percorso completo per scrivere [tabella/entità X]: handler API -> service -> chiamata DB. Dove sono le validazioni?"
• "Quali integrazioni esterne esistono (pagamenti, email, webhooks, API di terze parti)? Dove sono impostati retry e timeout?"
• "Dove può essere eseguito lavoro due volte (code, goroutine, cron)? Cosa lo rende idempotente?"
• "Cosa può rompersi silenziosamente e come lo noteremmo (log, metriche, alert, dashboard)?"

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.

Esempio pratico: mappare un flusso utente reale

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.

Mappa il flusso dal browser al database

Inizia dall'UI e procedi avanti, un hop alla volta. Chiedi nomi di file specifici, funzioni e shape di request/response.

• "Trova la route o la pagina React per la schermata di login. Quale componente la renderizza e quale azione si attiva al submit?"
• "Dove viene fatta la chiamata client all'API (fetch/axios/etc.)? Quale path URL esatto, metodo, header e body invia?"
• "Nel lato Go, dove è registrato l'handler per quel path? Mostrami la configurazione del router e la funzione handler."
• "Dentro l'handler, dove avviene la validazione dell'input (frontend, backend, o entrambi)? Quali regole esistono e dove vengono formattati gli errori?"
• "Quale query DB viene eseguita per il login? Indica il repository/file SQL, elenca tabelle/colonne toccate e nota eventuali transazioni o lock."

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".

Conferma con una rapida esecuzione

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.

Trasforma la mappa mentale in un breve documento di onboarding

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.

Struttura semplice in 1–2 pagine

Mantieni il documento prevedibile così le persone trovano rapidamente le informazioni. Una buona struttura è:

• Scopo: cosa fa l'app, chi la usa e cosa significa "done"
• Sommario dell'architettura: servizi principali, datastore e come passano le richieste nel sistema
• Come eseguire: prerequisiti, il comando unico per avviare e il comando unico per eseguire i test
• Dove stanno le cose: le cartelle importanti, più i 5–10 file che sono punti di ingresso
• Flussi chiave e rischi: tracce brevi dei percorsi importanti, più cosa validare dopo le modifiche

Rendilo azionabile, non accademico

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:

• Aggiorna una copia/testo o una regola di validazione in una schermata ben contenuta
• Aggiungi un piccolo unit test intorno a un helper complicato che hai identificato
• Risolvi un bug a basso rischio con un repro chiaro e risultato atteso
• Aggiungi una guardia: miglior messaggio d'errore, controllo input o timeout
• Chiedi chi possiede i deploy di produzione e chi pingare per domande di dominio

Errori comuni e come evitarli

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.

Tieni visibili gli ignoti (così li risolvi)

Usa una semplice regola nelle tue note: ogni affermazione deve essere contrassegnata come una di queste.

• Confermato nel codice
• Confermato eseguendo l'app
• Assunzione (da verificare)
• Sconosciuto (manca contesto)

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.

Non trattare gli output come fatti

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.

Checklist rapida prima di dire "Sono onboarded"

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:

• Riesci a spiegare le cinque aree più importanti del codice e cosa possiede ciascuna (per esempio: UI, layer API, job in background, accesso ai dati, integrazioni)?
• Riesci a percorrere due journey utente di alto valore end-to-end e indicare il primo file o funzione che avvia ogni journey?
• Sai dove viene applicata l'autenticazione e dove sono definiti e controllati ruoli o permessi?
• Sai indicare le scritture DB più rischiose (denaro, permessi, cancellazioni, transizioni di stato) e descrivere come testeresti ciascuna modifica in sicurezza?
• Riesci a consegnare a un nuovo sviluppatore una nota di onboarding breve che può leggere in meno di 10 minuti e poi sapere da dove iniziare?

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.

Prossimi passi: mantieni aggiornata la mappa e facilita i passaggi

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à:

• Dopo ogni feature: aggiorna la lista moduli e i flussi principali che ha toccato
• Dopo ogni incidente: aggiungi trigger, impatto e il punto esatto della correzione
• Dopo ogni refactor rischioso: annota cosa è cambiato e cosa è rimasto compatibile
• Prima di un rilascio: ricontrolla le 3 aree più rischiose e i percorsi di test
• Una volta al mese: elimina note stale e conferma i proprietari per i moduli chiave

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:

• Cosa leggere prima (2–3 file o doc) e perché
• Cosa eseguire in locale (comandi, env var, seed data)
• Cosa verificare (un percorso felice e un caso di errore)
• Dove sono i punti critici (moduli rischiosi, test instabili, config ostiche)
• Chi contattare per cosa (owner per i flussi chiave)

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.