Per gli utenti di Claude Code

Claude inizia ogni sessione alla cieca.

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.

Inizia gratis Leggi la configurazione per Claude Code

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

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

CLAUDE.md è una buona pratica. Usalo.

> 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” con ambito su una directory.
Riferimenti alla documentazione canonica e ai log delle decisioni.

La documentazione sulla memoria di Anthropic descrive bene questo aspetto. Tienilo conciso. Delimitane l'ambito. Fanne 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 di grafo. Non può avere risposta da un file di documentazione. 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 consapevoli del branch così Claude vede la versione del codice che sta effettivamente modificando.
Prezzi per workspace non per postazione. Indicizza 1 repo o 50; gli agenti non pagano postazioni.

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.

// workflow 01

Trova l'implementazione reale, non lo stub di test

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.

// workflow 02

Controlla il raggio d'impatto prima di refactorizzare

Tu: "Cosa chiama normalizePhoneNumber?"

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

// workflow 03

Verifica l'agente prima di accettare il diff

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 live + 3 importatori. 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.

// step 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.

// step 02

Installa il plugin Maguyva in Claude Code

/plugin marketplace add maguyva/claude-code-plugin
/plugin install maguyva@maguyva

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

// step 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.