# O AGENTS.md passa suas regras ao OpenCode. O Maguyva mostra o código a ele.

Canonical source: https://maguyva.ai/pt-br/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).

O OpenCode lê no AGENTS.md como trabalhar e chama servidores MCP para todo o resto. O Maguyva é um servidor MCP remoto que dá ao OpenCode um mapa consultável do seu repositório, com caminhos de arquivo e números de linha.

> Uma entrada remota em mcp. Nada roda localmente.

## O que você precisa saber sobre o OpenCode

Quatro fatos específicos do OpenCode.

### opencode.json

Adicione o servidor em `mcp` no `opencode.json` do seu projeto, ou em `~/.config/opencode/opencode.json` para todos os projetos.

### type: remote

O OpenCode se conecta via HTTP ao endpoint do Maguyva. Nada roda localmente e o Node.js não é necessário.

### Uma referência a variável de ambiente

O OpenCode substitui variáveis de ambiente na configuração, então o cabeçalho fica `Bearer {env:MAGUYVA_API_KEY}` e a chave fica fora do arquivo que você comita.

### Limite por agente

Cada servidor MCP adiciona definições de ferramentas ao contexto. O OpenCode pode desligar globalmente as ferramentas de um servidor com um glob como `"maguyva*": false` e religá-las só para os agentes que precisam.

## O AGENTS.md é um acordo de trabalho. Use-o.

```text
> /init
# varre o repositório e escreve o AGENTS.md
```

O OpenCode lê o `AGENTS.md` na raiz do projeto e o `~/.config/opencode/AGENTS.md` para regras pessoais. Sem um `AGENTS.md`, ele recorre ao `CLAUDE.md`. Use-o para:

- Comandos de build, teste e lint.
- Convenções e limites que o agente deve respeitar.
- Ponteiros para a documentação que importa.

Uma varredura no momento do `/init` é um resumo, não um índice. Ela não vai dizer ao OpenCode quem chama uma função adicionada ontem.

## Onde o AGENTS.md não dá conta

Três lacunas que o OpenCode preenche com grep e paciência.

### // um resumo não é um índice

O AGENTS.md pode citar os pacotes importantes. Ele não consegue listar cada símbolo e ponto de chamada, e nem deveria tentar.

### // grep acha strings, não chamadores

Uma correspondência de texto não distingue uma chamada real de um comentário, de um mock ou de um método com o mesmo nome em outra classe.

### // o arquivo fica defasado

O AGENTS.md está certo no dia em que é escrito. O código segue mudando; o arquivo muda quando alguém lembra de atualizar.

## O Maguyva como servidor MCP remoto no OpenCode

Uma entrada em mcp dá ao OpenCode:

- **11 ferramentas sobre o seu repositório indexado**: busca semântica, estrutural (AST), de grafo e de texto, além de busca de símbolos, dependentes e recuperação de arquivos.
- **Respostas com caminhos de arquivo e números de linha**: em mais de 285 linguagens.
- **As mesmas respostas para qualquer modelo**: O OpenCode funciona com muitos provedores de modelos. O Maguyva devolve o mesmo mapa, não importa qual modelo pergunte.

> O AGENTS.md diz ao OpenCode *como trabalhar*.
> O Maguyva dá ao OpenCode *algo com que trabalhar*.

## Dois fluxos de trabalho

Pergunte ao mapa no mesmo terminal.

### 01. Renomear um tipo compartilhado entre pacotes

```text
opencode> renomeie OrderStatus para FulfillmentStatus

dependency_search("OrderStatus", dependents)
  23 referências em 8 pacotes
structural_search(switch_statement, "OrderStatus")
  4 switches exaustivos

→ O OpenCode edita a lista completa, switches incluídos.
[exit 0]
```

Os switches exaustivos são justamente os que a busca de texto deixa passar e o compilador pega tarde.

### 02. Separar código de documentação

```text
opencode> onde FEATURE_BULK_EXPORT é lido?

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

→ Dois caminhos de código, um doc desatualizado.
[exit 0]
```

Correspondências exatas voltam com caminhos, então o OpenCode separa código de documentação antes de editar qualquer um dos dois.

## Configuração no OpenCode

Três passos. Plano Free: 3 repositórios, Até 50 mil linhas de repositório indexadas, sem cartão.

### 01. Indexe um repositório em maguyva.ai

Escolha um que você já conheça, para poder avaliar as respostas.

### 02. Adicione o Maguyva em mcp no opencode.json

`opencode.json`

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

### 03. Exporte sua chave e confira a conexão

Defina `MAGUYVA_API_KEY` no shell que inicia o OpenCode. `opencode mcp list` mostra cada servidor configurado; depois faça uma pergunta cuja resposta você já saiba.

A [documentação de MCP](https://opencode.ai/docs/mcp-servers/) do OpenCode cobre timeouts, OAuth e acesso a ferramentas por agente.

## Indexe um repositório que você já conhece.

Conecte o OpenCode via MCP e faça uma pergunta que você consiga conferir.