# O Claude começa toda sessão às cegas.

Canonical source: https://maguyva.ai/pt-br/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` diz ao Claude como se comportar. Não diz ao Claude o que tem no seu repositório. O Maguyva indexa a base de código e disponibiliza esse contexto via MCP, para que o Claude edite como se já tivesse lido o código.

> Use o CLAUDE.md para comportamento. Use o Maguyva para informações atuais da base de código.

## O CLAUDE.md é uma boa prática. Use-o.

```text
> cat CLAUDE.md
# project conventions, commands, scoped rules
```

Instruções persistentes pertencem ao `CLAUDE.md`. É o lugar certo para:

- Comandos de build, teste e lint que o agente deve rodar.
- Regras de estilo de código e convenções de nomenclatura.
- Regras do tipo “sempre faça X / nunca faça Y” restritas a um diretório.
- Referências para os docs canônicos e registros de decisão.

A [documentação de memória](https://code.claude.com/docs/en/memory) da Anthropic descreve isso bem. Mantenha conciso. Delimite o escopo. Faça commit.

Mas o `CLAUDE.md` nunca foi pensado para ser um mapa da sua base de código.

## Onde o CLAUDE.md para de ser suficiente

Quatro modos de falha que markdown sozinho não resolve.

### // o arquivo não é a base de código

Dizer ao Claude *como se comportar* não diz a ele *o que existe*. A primeira edição num repositório desconhecido é um chute sobre caminhos de arquivo, nomes de função e call sites. O CLAUDE.md não consegue listar cada símbolo, e você nem ia querer isso.

### // docs desatualizam, código não

Um bloco do `CLAUDE.md` descrevendo o seu fluxo de auth está certo até alguém refatorar a auth. Agora o código é a fonte da verdade e os docs estão confiantemente errados. O Claude lê o errado.

### // dependências não estão no markdown

“O que quebra se eu mudar essa função?” é uma pergunta de grafo. Não pode ser respondida por um arquivo de doc. O Claude ou faz grep e torce para dar certo ou pede para você colar arquivos no chat.

### // janelas de contexto têm um orçamento

Encher o CLAUDE.md até o Claude “saber o suficiente” consome tokens que deveriam pagar por raciocínio. Depois de alguns KB, você troca qualidade de resposta por volume de contexto.

## O Maguyva é a camada que o CLAUDE.md não cobre

Um servidor MCP remoto que dá ao Claude Code:

- **Busca semântica, AST, de grafo e de texto**: no seu repositório indexado, retornada com caminhos de arquivo e números de linha.
- **Consultas de dependência, tipo e call-site**: as perguntas que um grafo responde e um arquivo de doc não consegue.
- **Resultados que levam a branch em conta**: para que o Claude enxergue a versão do código que ele está realmente editando.
- **Preço por workspace**: não por usuário. Indexe 1 repositório ou 50; agentes não geram cobranças por usuário.

> O CLAUDE.md diz ao Claude *como se comportar*.
> O Maguyva dá ao Claude *um mapa consultável do código*.

## Três fluxos de trabalho

Numerados, cheios de blocos de código. As perguntas que você já faz ao Claude, fundamentadas em linhas reais.

### 01. Encontre a implementação real, não o stub de teste

```text
Você: "Como funciona a nova tentativa no nosso cliente de pagamentos?"

Sem o Maguyva → o Claude faz grep de retry, encontra 14 resultados, escolhe um (geralmente um mock de teste).
Com o Maguyva    → o Maguyva retorna a definição do símbolo, os call-sites, e o
                   file:line da implementação real, ranqueados.
```

### 02. Confira o raio de impacto antes de refatorar

```text
Você: "O que chama normalizePhoneNumber?"

O Maguyva retorna: 7 call-sites em 4 pacotes, incluindo um num serviço Python
que o importa via stub gRPC. O Claude propõe a mudança com a lista de
migração inline, não depois que o CI fica vermelho.
```

### 03. Verifique o agente antes de aceitar o diff

```text
Claude: "Editei src/auth/session.ts:142 para corrigir o refresh do token."

Pergunte ao Maguyva: "Me mostra session.ts:130-160 e tudo que importa session."

O Maguyva retorna o trecho atual do arquivo + 3 importadores. O diff agora está fundamentado
em linhas reais, não na lembrança do Claude lá do token #11.000.
```

## Configuração no Claude Code

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ê conheça bem para poder verificar as respostas. O Plano Free cobre 3 repositórios, Até 50 mil linhas de repositório indexadas.

### 02. Instale o plugin do Maguyva no 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. Faça uma pergunta cuja resposta você já saiba

Comece com um repositório e uma pergunta verificável, não a empresa inteira. Se a resposta bater com o que você diria, está pronto.

As instruções completas ficam nos [docs do Maguyva](https://maguyva.ai/pt-br/docs).

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

Teste uma pergunta cuja resposta você consiga verificar. É todo o onboarding.