# Claude inizia ogni sessione alla cieca.

Canonical source: https://maguyva.ai/it/for-claude-code

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

`CLAUDE.md` dice a Claude come comportarsi. Non dice a Claude cosa c'è nel tuo repo. Maguyva indicizza il codebase e lo restituisce via MCP, così Claude modifica come se avesse già letto il codice.

> Usa CLAUDE.md per il comportamento. Usa Maguyva per i fatti aggiornati sul codebase.

## CLAUDE.md è una buona pratica. Usalo.

```text
> cat CLAUDE.md
# convenzioni del progetto, comandi, regole con ambito
```

Le istruzioni persistenti vanno in `CLAUDE.md`. È il posto giusto per:

- Comandi di build, test e lint che l'agente dovrebbe eseguire.
- Regole di stile di codifica e convenzioni di denominazione.
- Regole del tipo “fai sempre X / non fare mai Y” valide per una specifica directory.
- Riferimenti alla documentazione canonica e ai log delle decisioni.

La [documentazione sulla memoria](https://code.claude.com/docs/en/memory) di Anthropic descrive bene questo aspetto. Tienilo conciso. Delimitane l'ambito. Salvalo in un commit.

Ma `CLAUDE.md` non è mai stato pensato per essere una mappa del tuo codebase.

## Dove CLAUDE.md smette di bastare

Quattro modalità di fallimento che il solo markdown non può risolvere.

### // il file non è il codebase

Dire a Claude *come comportarsi* non gli dice *cosa esiste*. La prima modifica su un repo sconosciuto è un'ipotesi su percorsi dei file, nomi delle funzioni e punti di chiamata. CLAUDE.md non può elencare ogni simbolo, e non lo vorresti comunque.

### // i documenti invecchiano, il codice no

Un blocco di `CLAUDE.md` che descrive il tuo flusso di auth è corretto finché qualcuno non refactorizza l'auth. Ora il codice è la fonte di verità e i documenti sono sicuri di sé ma sbagliati. Claude legge quello sbagliato.

### // le dipendenze non stanno nel markdown

“Cosa si rompe se cambio questa funzione?” è una domanda a cui risponde un grafo. Un file di documentazione non può rispondere. Claude fa grep e prega, oppure ti chiede di incollare i file nella chat.

### // le finestre di contesto hanno un budget

Riempire CLAUDE.md finché Claude “ne sa abbastanza” consuma token che dovrebbero finanziare il ragionamento. Oltre pochi KB scambi la qualità della risposta con volume di contesto.

## Maguyva è il livello che CLAUDE.md non copre

Un server MCP remoto che dà a Claude Code:

- **Ricerca semantica, AST, a grafo e testuale**: sul tuo repo indicizzato, restituita con percorsi di file e numeri di riga.
- **Ricerche di dipendenze, tipi e punti di chiamata**: le domande a cui risponde un grafo e non un file di documentazione.
- **Risultati che tengono conto del branch**: così Claude vede la versione del codice che sta effettivamente modificando.
- **Prezzi per workspace**: non per utente. Indicizza 1 repo o 50; gli agenti non comportano costi per utente.

> CLAUDE.md dice a Claude *come comportarsi*.
> Maguyva dà a Claude *una mappa consultabile del codice*.

## Tre flussi di lavoro

Numerati, con molti blocchi di codice. Le domande che già fai a Claude, fondate su righe reali.

### 01. Trova l'implementazione reale, non lo stub di test

```text
Tu: "Come funziona il retry nel nostro client di pagamento?"

Senza Maguyva → Claude fa grep di retry, trova 14 risultati, ne sceglie uno (spesso un mock di test).
Con Maguyva    → Maguyva restituisce la definizione del simbolo, i punti di chiamata e il
                   file:line dell'implementazione reale, classificati.
```

### 02. Controlla il raggio d'impatto prima di refactorizzare

```text
Tu: "Cosa chiama normalizePhoneNumber?"

Maguyva restituisce: 7 punti di chiamata in 4 pacchetti, incluso uno in un servizio Python
che lo importa tramite lo stub gRPC. Claude propone la modifica con l'elenco di migrazione
inline, non dopo che la CI diventa rossa.
```

### 03. Verifica l'agente prima di accettare il diff

```text
Claude: "Ho modificato src/auth/session.ts:142 per correggere il refresh del token."

Chiedi a Maguyva: "Mostrami session.ts:130-160 e tutto ciò che importa session."

Maguyva restituisce lo snippet del file aggiornato + 3 moduli che lo importano. Il diff è ora fondato
su righe reali, non sul ricordo di Claude dal token #11.000.
```

## Configurazione in Claude Code

Tre passaggi. Piano Free: 3 repository, Fino a 50K righe di repository indicizzate, senza carta di credito.

### 01. Indicizza un repo su maguyva.ai

Scegline uno che conosci bene così puoi verificare le risposte. Il piano Free copre 3 repository, Fino a 50K righe di repository indicizzate.

### 02. Installa il plugin Maguyva in Claude Code

```text
/plugin marketplace add maguyva/agent-plugins
/plugin install maguyva@maguyva

# the plugin reads your key from the environment
export MAGUYVA_API_KEY=mgv_xxxx
```

### 03. Fai una domanda di cui conosci già la risposta

Inizia con un repo e una domanda verificabile, non con tutta la tua azienda. Se la risposta corrisponde a quello che diresti, sei a posto.

Le istruzioni complete si trovano nella [documentazione di Maguyva](https://maguyva.ai/it/docs).

## Indicizza un repo che già conosci.

Prova una domanda di cui puoi verificare la risposta. Ecco tutto l'onboarding.