Codebase indexing e agenti che leggono i file

Un agente con accesso ai file può costruirsi il contesto leggendo la repo. Questo è più potente del copia-incolla, ma richiede metodo: deve sapere cosa cercare, in che ordine e quando fermarsi.

Perché questa lezione conta

Incollare file in chat ti obbliga a decidere tutto prima. Un agente può esplorare: lista directory, cerca simboli, legge file, controlla test, produce una mappa. Ma se gli dai un obiettivo troppo ampio, può leggere troppo, modificare troppo o perdersi.

Protocollo di esplorazione

Un buon prompt agentico può chiedere:

Prima di modificare file:
1. lista la struttura rilevante;
2. cerca riferimenti con `rg`;
3. leggi solo i file necessari;
4. produci una mappa breve;
5. dichiara quali file pensi di modificare.

Questo trasforma l’esplorazione in un artefatto revisionabile.

Cosa rendere facile per l’agente

La repo dovrebbe offrire:

• README aggiornato;
• comandi di build/test;
• struttura cartelle comprensibile;
• entry point chiari;
• file di regole;
• naming coerente;
• test vicini al codice.

Il miglior prompt non compensa una repo completamente opaca.

Confini

L’agente deve sapere:

• cosa può leggere;
• cosa può modificare;
• quali comandi può eseguire;
• quali operazioni richiedono conferma;
• quando fermarsi.

Esempio:

Puoi leggere tutta la repo.
Puoi modificare solo src/content/lezioni/prompt-engineering.
Non modificare configurazione, redirect o package.json.

Laboratorio guidato

Dai a un agente una repo che non conosce e chiedi solo onboarding:

Esplora il progetto senza modificare file.
Restituisci:
- scopo del progetto;
- stack;
- comandi;
- struttura cartelle;
- dove vivono i dati;
- rischi per modifiche future.

Poi valuta se la mappa è corretta.

Output atteso

Un protocollo di onboarding agente da applicare a ogni nuovo progetto.

Template:

Obiettivo esplorazione:
Comandi consentiti:
File da leggere prima:
Pattern da cercare:
Output atteso:
Stop condition:

Checklist di verifica

• l’agente esplora prima di modificare;
• usa ricerca testuale invece di letture casuali;
• produce una mappa prima del piano;
• dichiara file da toccare;
• rispetta confini di modifica.

Errori comuni

Chiedere “capisci la repo” senza output. Serve una mappa verificabile.

Permettere modifiche durante l’esplorazione. Prima si capisce, poi si cambia.

Non indicare comandi. L’agente può saltare build/test o usare strumenti non previsti.

Collegamenti

• Modulo: Contesto e memoria nel progetto — lezione 23 del corso.
• Lezione precedente: RAG per sviluppatori.
• Prossima lezione: MCP, tool servers e contesto strutturato.