# AGENTS.md dice a OpenCode le tue regole. Maguyva gli mostra il codice.

Canonical source: https://maguyva.ai/it/for-opencode

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).

OpenCode legge in AGENTS.md come lavorare e chiama i server MCP per tutto il resto. Maguyva è un server MCP remoto che dà a OpenCode una mappa interrogabile del tuo repo, con percorsi file e numeri di riga.

> Una voce remota sotto mcp. In locale non gira nulla.

## Cosa sapere su OpenCode

Quattro fatti specifici di OpenCode.

### opencode.json

Aggiungi il server sotto `mcp` nell’`opencode.json` del progetto, oppure in `~/.config/opencode/opencode.json` per tutti i progetti.

### type: remote

OpenCode si collega via HTTP all’endpoint di Maguyva. In locale non gira nulla e Node.js non serve.

### Un riferimento a variabile d’ambiente

OpenCode sostituisce le variabili d’ambiente nella sua configurazione, quindi l’header diventa `Bearer {env:MAGUYVA_API_KEY}` e la chiave resta fuori dal file che committi.

### Limitalo per agente

Ogni server MCP aggiunge definizioni di strumenti al contesto. OpenCode può disattivare globalmente gli strumenti di un server con un glob come `"maguyva*": false` e riattivarli solo per gli agenti che ne hanno bisogno.

## AGENTS.md è un accordo di lavoro. Usalo.

```text
> /init
# analizza il repo e scrive AGENTS.md
```

OpenCode legge `AGENTS.md` nella root del progetto e `~/.config/opencode/AGENTS.md` per le regole personali. Senza un `AGENTS.md`, ripiega su `CLAUDE.md`. Usalo per:

- Comandi di build, test e lint.
- Convenzioni e confini che l’agente deve rispettare.
- Rimandi alla documentazione che conta.

Un’analisi al momento di `/init` è un riassunto, non un indice. Non dirà a OpenCode chi chiama una funzione aggiunta ieri.

## Dove AGENTS.md non basta

Tre lacune che OpenCode colma con grep e pazienza.

### // un riassunto non è un indice

AGENTS.md può nominare i pacchetti importanti. Non può elencare ogni simbolo e punto di chiamata, e non dovrebbe provarci.

### // grep trova stringhe, non chiamanti

Una corrispondenza testuale non distingue una chiamata reale da un commento, un mock o un metodo omonimo di un’altra classe.

### // il file va alla deriva

AGENTS.md è corretto il giorno in cui viene scritto. Il codice continua a muoversi; il file cambia quando qualcuno si ricorda di aggiornarlo.

## Maguyva come server MCP remoto in OpenCode

Una voce sotto mcp dà a OpenCode:

- **11 strumenti sul tuo repo indicizzato**: ricerca semantica, strutturale (AST), a grafo e testuale, più ricerca dei simboli, dipendenti e recupero file.
- **Risposte con percorsi file e numeri di riga**: su oltre 285 linguaggi.
- **Le stesse risposte per ogni modello**: OpenCode funziona con molti fornitori di modelli. Maguyva restituisce la stessa mappa qualunque sia il modello che chiede.

> AGENTS.md dice a OpenCode *come lavorare*.
> Maguyva dà a OpenCode *qualcosa su cui lavorare*.

## Due flussi di lavoro

Interroga la mappa dallo stesso terminale.

### 01. Rinominare un tipo condiviso tra pacchetti

```text
opencode> rinomina OrderStatus in FulfillmentStatus

dependency_search("OrderStatus", dependents)
  23 riferimenti in 8 pacchetti
structural_search(switch_statement, "OrderStatus")
  4 switch esaustivi

→ OpenCode modifica l’elenco completo, switch inclusi.
[exit 0]
```

Gli switch esaustivi sono proprio quelli che una ricerca testuale manca e che il compilatore scopre tardi.

### 02. Distinguere il codice dalla documentazione

```text
opencode> dove viene letto FEATURE_BULK_EXPORT?

text_pattern_search("FEATURE_BULK_EXPORT")
  src/config/flags.ts:17
  src/export/bulk.ts:5
  docs/flags.md:40   ← solo docs

→ Due percorsi di codice, un documento obsoleto.
[exit 0]
```

Le corrispondenze esatte tornano con i percorsi, così OpenCode distingue il codice dalla documentazione prima di modificare l’uno o l’altra.

## Configurazione in OpenCode

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 già conosci, così puoi valutare le risposte.

### 02. Aggiungi Maguyva sotto mcp in opencode.json

`opencode.json`

```json
{
  "mcp": {
    "maguyva": {
      "type": "remote",
      "url": "https://maguyva.tools/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MAGUYVA_API_KEY}"
      }
    }
  }
}
```

### 03. Esporta la chiave e controlla la connessione

Imposta `MAGUYVA_API_KEY` nella shell che avvia OpenCode. `opencode mcp list` mostra ogni server configurato; poi fai una domanda di cui conosci già la risposta.

La [documentazione MCP](https://opencode.ai/docs/mcp-servers/) di OpenCode copre timeout, OAuth e accesso agli strumenti per agente.

## Indicizza un repo che già conosci.

Collega OpenCode via MCP, poi fai una domanda che puoi verificare.