Mappa rapida: file, moduli, dipendenze, punto d’ingresso

Prima di leggere il codice, devi sapere dove sei. Una codebase senza mappa è una città senza segnaletica: cammini ovunque, capisci nulla. Costruirne una in 15 minuti è skill chiave del vibe coder. Vale per progetti tuoi che riprendi, per codice generato dall’AI, per repo di terzi che valuti.

Perché questa lezione conta

Saltare la mappa porta a giudicare frammenti senza contesto. Un componente che sembra fragile è perfettamente sensato in un’architettura che non hai capito. Una funzione che sembra duplicata è in realtà una ridefinizione voluta in altro contesto. Mappa = capacità di leggere codice in modo strutturale, non riga-per-riga.

Obiettivo operativo

Alla fine devi saper:

1. costruire mappa di una codebase sconosciuta in 15 minuti;
2. identificare punto d’ingresso, flussi principali, configurazioni;
3. distinguere file di prodotto da generato/asset/config.

Nucleo della lezione

1. Cosa cercare

Sei elementi prioritari, in ordine:

Punto d’ingresso: dove parte l’app. src/main.ts, app.tsx, index.js, cmd/server/main.go. Per app web: file di setup framework (next.config, astro.config). Per CLI: bin/, cmd/. Per libreria: package.json field main/exports.

Route/pagine principali: per app web, struttura pages/ o app/ o routes/. Mappa URL → file.

Componenti principali: ciò che ricorre nelle pagine. Layout, header, navigation. Spesso in components/ o src/ui/.

Servizi/logica: dove vivono regole di business. services/, lib/, core/, domain/, usecases/. Nome varia, posizione cerca.

Configurazione: .env*, config/, files con nome *config* (es. tailwind.config, next.config, vite.config). Definiscono comportamento globale.

Test: dove sono i test? Stessa cartella del codice (*.test.ts accanto)? Cartella separata (tests/, __tests__/)? Niente test? Quest’ultimo è informazione.

2. Manifest e lockfile

Due file dicono quasi tutto sul progetto:

Manifest (package.json, pyproject.toml, Cargo.toml, go.mod):

• nome, versione del progetto;
• script disponibili (npm run X): comandi che puoi eseguire;
• dipendenze (production vs dev);
• engines (versione di Node, Python, ecc.).

Cosa cercare: scripts.dev, scripts.build, scripts.test, scripts.lint. Sono le fasi tipiche.

Lockfile (package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb, Cargo.lock):

• versioni esatte di TUTTE le dipendenze (incl. transitive);
• garanzia di build riproducibili.

Mai modificare lockfile a mano. Genera con npm install/pnpm install/etc.

Lettura veloce di package.json:

• 5 linee per script principali;
• 10 dipendenze più rilevanti (TanStack Query, react, prisma, ecc.);
• ignora le 50 transitive.

3. Categorie di file

Una codebase contiene 4-5 categorie. Saperle distinguere accelera la lettura:

Codice di prodotto: src/, lib/, app/. Cosa fai eseguire all’utente. Lo leggi.

Test: tests/, __tests__/, *.test.*, *.spec.*. Lo leggi per capire cosa il codice DEVE fare.

Generato: dist/, build/, .next/, out/, coverage/. Output di build. Non leggere, non modificare. Spesso gitignored.

Asset: public/, assets/, static/. Immagini, font, file binari. Riferimenti, non logica.

Configurazione: file root (tsconfig.json, astro.config.mjs, eslintrc.json). Modifica con cautela.

Documentazione: README.md, docs/, AGENTS.md. Leggi per primo, scrive per ultimo.

Quando apri repo nuova: ignora generato + asset, vai dritto a manifest + entry point + 1-2 file di prodotto in directory principali.

Caso guidato

Apri una repo sconosciuta e trovi:

package.json
src/main.ts
src/App.tsx
src/components/
src/lib/api.ts
src/lib/auth.ts
src/routes/
tests/

Non partire da App.tsx solo perché sembra familiare. Costruisci la mappa:

1. package.json: script dev, build, test; dipendenze principali; framework.
2. src/main.ts: punto d’ingresso browser, monta App.
3. src/routes/: decide pagine o route.
4. src/lib/api.ts: confine verso server.
5. src/lib/auth.ts: identità/sessione, zona sensibile.
6. tests/: cosa è protetto da test e cosa no.

Scheda orientamento:

Framework: React + Vite.
Avvio: src/main.ts -> App.tsx -> routes.
Dati esterni: src/lib/api.ts.
Auth: src/lib/auth.ts, usata da routes/private.
Test presenti: unit su api, nessun test UI.
Rischi: token in auth.ts, error handling centralizzato in api.ts.
Comandi: npm run dev, npm test, npm run build.

Solo dopo questa mappa chiedi all’AI di modificare codice. Prompt migliore:

La repo è organizzata così: [scheda]. Il bug riguarda `src/lib/api.ts` e una route privata. Prima proponi quali file leggere, poi diagnosi. Non toccare auth senza spiegare perché.

Procedura pratica

Mappa rapida (15 minuti):

1. README (3 min): descrizione, comandi setup, struttura citata.
2. Struttura cartelle (tree -L 2 -I 'node_modules|dist|.next') (1 min): vista d’insieme.
3. Manifest (3 min): script, dipendenze rilevanti.
4. Punto d’ingresso (3 min): apri il file principale, segui import.
5. AGENTS.md/CLAUDE.md (2 min): convenzioni del progetto.
6. Una pagina/route + suo flusso (3 min): segui un caso reale dall’inizio alla fine.

A 15 minuti hai mappa minima. Non profonda, ma orientata. Sufficiente per task piccoli; punto di partenza per task grandi.

Laboratorio guidato

Prendi una repo open source piccola (es. una libreria utility, ~50 file). Costruisci mappa in 15 minuti.

Esempio target: validator.js (libreria validazione).

README: validation library, install npm i validator, esempi di uso.

Tree:

src/lib/        — moduli di validazione (isEmail, isURL, ecc.)
src/index.js    — entry point, esporta tutto
test/           — test per ogni modulo
package.json    — manifest, scripts: test, lint

Manifest: dipendenze runtime: nessuna. Dev: mocha, eslint. Script: test, lint.

Entry point: src/index.js re-esporta da src/lib/*.js.

Convenzioni: ogni file in lib/ è una funzione singola, naming isX/isY. Test in test/ con stesso nome.

Flusso esempio: validator.isEmail('foo@bar.com') → carica src/lib/isEmail.js → usa altri moduli (assertString, regex). Test in test/validators.test.js.

A 15 minuti: capisci come è fatta. Ora puoi modificare consapevolmente.

Output atteso

Una “scheda di orientamento” salvata o copiata in note del progetto:

PROGETTO: [nome]
PUNTO D'INGRESSO: [file:linea]
ROUTE/PAGINE: [pattern, posizione]
LOGICA PRINCIPALE: [cartelle]
TEST: [posizione, framework]
CONFIG: [file principali]
COMANDI:
  - dev: ...
  - build: ...
  - test: ...
DIPENDENZE PRINCIPALI: [5-10 librerie chiave]
CONVENZIONI: [da AGENTS.md / README]
DOMANDE APERTE: [cose ancora poco chiare]

Studio passo passo

Studia questa lezione in tre passaggi, senza correre subito al prompt o al codice.

1. Prima lettura: chiarisci l’obiettivo: orientarsi in una codebase generata o modificata prima di giudicare il singolo frammento di codice. Se non riesci a riscriverlo in una frase tua, rileggi il nucleo della lezione.
2. Seconda lettura: trasforma i contenuti in domande operative:

• Identificare entry point, route, componenti principali, servizi, configurazioni e test.
• Leggere manifest e lockfile per capire dipendenze reali, script disponibili e versioni coinvolte.
• Separare file di prodotto, file generati, asset, configurazione e documentazione.

3. Applicazione: svolgi il laboratorio: aprire una mini repo sconosciuta e costruire una mappa dei file in quindici minuti. L’output da ottenere è: una scheda di orientamento con punto d’ingresso, flussi principali e comandi da eseguire.

Prima di passare alla lezione successiva, controlla di avere un artefatto concreto: una tabella, un prompt, una checklist, un mini report, un diff commentato o una decisione scritta. Nel vibe coding la comprensione resta astratta finché non produce una traccia verificabile.

Checklist di verifica

• so costruire mappa di repo nuova in 15 min;
• so distinguere codice prodotto da generato da asset da config;
• conosco script principali del progetto e li ho eseguiti almeno una volta;
• la mia scheda di orientamento è scritta, non solo nella testa.

Errori comuni

Saltare la mappa. “Vado dritto al codice”. Decisioni infondate.

Leggere file generato come fosse prodotto. dist/main.js minificato non è leggibile. Non perdere tempo.

Ignorare manifest. Salti scripts e dipendenze, scrivi codice che usa libreria diversa da quella in package.json.

Dimenticare README. Spesso contiene istruzioni di setup che il modello non indovina.

Non eseguire l’app. Mappa teorica + niente esecuzione = comprensione parziale. Almeno una volta, fai partire l’app e naviga.

Mappa troppo dettagliata. 30 minuti per una mappa è troppo. 15 minuti basta. Approfondisci man mano che lavori.

Prompt di lavoro

Sto esplorando questa repo per la prima volta.

Output di `tree -L 2`:
[incolla]

Contenuto rilevante di package.json:
[scripts + dipendenze top-level]

README rilevante:
[primi 50 righe o sezione "Getting Started"]

Aiutami a costruire mappa di orientamento. Output richiesto:

1. Identifica punto d'ingresso probabile.
2. Identifica organizzazione moduli (route/pagine, componenti, logica).
3. Identifica come testare (framework, posizione test).
4. Identifica convenzioni implicite (naming, struttura).
5. Suggerisci primo file/flusso da seguire per capire il progetto.
6. Domande aperte che risolveresti aprendo file specifici.

Output: schema compatto, max 1 pagina. Niente teoria, solo orientamento operativo.

Esercizio finale

Per il tuo progetto principale: scrivi a memoria la scheda di orientamento. Poi confronta con realtà. Probabilmente scopri che alcune cose non ricordi precisamente o credi diversamente. Quel delta è l’occasione per scriverla davvero (in docs/orientamento.md) — diventa documentazione utile per te del futuro o per chi entra nel progetto.