Comprendere una codebase esistente 🔍

Prima di toccare una riga di codice, devi capire cosa c’è già. Un agente di coding è eccellente in questo: può leggere l’intero repository e restituirti una mappa in pochi minuti. Ma solo se gli chiedi le domande giuste e gli dai il contesto giusto. Altrimenti ottieni un riassunto generico che avresti potuto leggere su Wikipedia.

Un agente che comprende una codebase non è un agente che ha letto tutto: è un agente che ha letto le cose giuste nel modo giusto.

Quando usare l’agente per questo caso 🎯

• Onboarding su progetto nuovo: sei entrato in un team e devi capire la struttura, lo stack, i pattern in uso.
• Audit architetturale: devi valutare la qualità di un progetto prima di un refactoring o di un’assunzione.
• Esplorazione mirata: “dove viene gestita l’autenticazione?”, “quali servizi chiamano questo endpoint?”.
• Generazione della prima bozza AGENTS.md: documentare stack, comandi e convenzioni in un file vivente.

Quando NON usare l’agente ⛔

• Il progetto è un monolite di 500k righe senza struttura chiara — prima fai un’archaeology manuale, poi delega.
• Devi modificare il codice — questo caso d’uso è in sola lettura. Se devi intervenire, passa a integrare funzionalità.
• Il contesto è sensibile (dati personali, segreti, credenziali) — assicurati che il modello non processi dati che non dovrebbe vedere.

Prompt di apertura 📝

Usa questo template come punto di partenza e adattalo al tuo caso:

“Analizza il repository [percorso]. Obiettivo: [comprensione architetturale / onboarding / audit]. Output atteso: [mappa dei moduli, flussi di chiamata, rischi, punti caldi]. NON modificare alcun file.”

Esempi concreti:

• “Analizza la directory src/auth/. Obiettivo: capire come funziona il flusso di login. Output atteso: diagramma Mermaid del flusso, dipendenze esterne, eventuali criticità.”
• “Fai un audit del progetto nella cartella corrente. Obiettivo: valutare la qualità architetturale. Output atteso: punti deboli, violazioni dei pattern, suggerimenti di miglioramento.”

Setup del contesto 🔧

Per ottenere risultati utili, prepara il terreno:

1. Indica le directory rilevanti — non lasciare che l’agente scorra l’intero monorepo. Se ti interessa il modulo payment/, parti da lì.
2. Assicurati che AGENTS.md sia presente — se non lo è, chiedi all’agente di generarne una bozza come primo task (vedi configurare il repository).
3. Specificare il livello di dettaglio — vuoi una panoramica ad alto livello o un’analisi approfondita di un modulo specifico?

Ciclo di lavoro 💡

Applica il ciclo pianifica→esegui→valida anche in sola lettura:

1. Pianifica: definisci cosa vuoi capire (architettura? flusso? dipendenze?).
2. Esplora: l’agente legge i file rilevanti e genera un’analisi strutturata.
3. Valida: verifica che le affermazioni dell’agente siano corrette. Controlla i file citati, confronta con il codice reale.

La validazione è cruciale: un agente può inventare relazioni tra moduli che non esistono. Sempre verificare sul codice reale.

    flowchart TD
    A[Avvia sessione] --> B[Scan iniziale: glob + grep]
    B --> C{Repo complesso?}
    C --> No --> D[Carica AGENTS.md + file rilevanti]
    C --> Sì --> E[Scoped exploration: modulo target]
    E --> F[Indicizzazione AST: Tree-sitter / ast-grep]
    F --> G[Mappa dipendenze e interfacce]
    G --> D
    D --> H[Valida con test / compilazione]
    H --> I[Output: mappa strutturata]
  

Indicizzazione e persistent indexing 🔎

Per repository ampi, il consumo di token diventa un problema reale: ogni file caricato nella finestra di contesto costa in input e degrada la qualità dell’analisi. La soluzione è l’indicizzazione persistente: una mappa della codebase che sopravvive alle sessioni e riduce il bisogno di rileggere tutto da zero.

Meccanismi di indicizzazione

Tree-sitter (versione WASM) è il punto di partenza ideale: parsa il codice in blocchi atomici di 50-1000 caratteri mantenendo la struttura sintattica. Aider RepoMap combina Tree-sitter + Ctags + PageRank per prioritizzare i simboli più importanti. ast-grep fa pattern matching strutturato direttamente sull’AST.

AGENTS.md: regola d’oro

Lo studio ETH Zurich / LogicStar.ai (Feb 2026, 138 task su SWE-bench Lite) ha dimostrato che:

• AGENTS.md generato da LLM: -3% success rate, +20% inference cost, +14-22% reasoning tokens
• AGENTS.md scritto dal developer: +4% success rate
• Dynamic Adaptive Context (ACE): +10.6% success rate

La regola è semplice: il root AGENTS.md deve essere meno di 50 righe. I dettagli vanno scoperti progressivamente, non caricati tutti all’avvio.

Full-repo vs scoped exploration 🔀

La regola pratica: se il repo ha più di 10k righe o è un monorepo, scoped exploration è sempre preferibile. L’agente non ha bisogno di visibilità totale: ha bisogno di percorsi rapidi verso la struttura che conta.

Anti-pattern nell’esplorazione 🚫

• Feed di dozzine di file senza scoping → context decay e recall degradato del modello.
• Accettare i claim dell’agente senza verificare → hallucination: l’agente inventa relazioni tra moduli che non esistono.
• Aggiunta incrementale di regole a AGENTS.md senza revisione periodica → “ball-of-mud” bloat che rende il file inutile.
• “Scoperta ripetuta” in ogni sessione per progetti grandi → usa l’indicizzazione persistente invece di rileggere tutto da zero.

Criteri di accettazione ✅

• Nessuna modifica ai file del progetto (sola lettura).
• Output strutturato: diagramma Mermaid o mappa dei moduli con legenda.
• Ogni affermazione cita il file e la riga di riferimento.
• La prima bozza di AGENTS.md è stata generata e validata manualmente.

Approfondimenti 📚

• Configurare il repository — come creare un AGENTS.md efficace.
• Gestire il contesto come una risorsa — tecniche di context hygiene per esplorazioni mirate.
• Blog: Context engineering — il fondamento teorico della gestione del contesto.