# O AGENTS.md diz ao Codex como trabalhar. Não o que está lá. Canonical source: https://maguyva.ai/pt-br/for-codex 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 AGENTS.md define o acordo de trabalho. O MCP permite que o Codex acesse ferramentas. O Maguyva é o servidor MCP que dá ao Codex um mapa consultável do seu repositório, para que a primeira edição não seja um chute sobre a estrutura de arquivos. > O AGENTS.md é o acordo. O MCP é o canal. O Maguyva é o mapa. ## A stack em camadas Quatro ideias. Cada uma com uma função. ### AGENTS.md Como o Codex deve se comportar nesse repositório. ### MCP Como o Codex acessa ferramentas externas e contexto. ### Maguyva O servidor MCP que retorna fatos fundamentados do repositório. ### Por workspace, não por usuário Agentes não geram cobranças por usuário. [Ver preços](https://maguyva.ai/pt-br/pricing) ## O AGENTS.md é um acordo de trabalho. Use-o. Instruções persistentes pertencem ao [`AGENTS.md`](https://developers.openai.com/codex/guides/agents-md). É o lugar certo para: - Comandos de build, teste e lint que o Codex deve rodar. - Regras do tipo “sempre faça X / nunca faça Y” restritas a um diretório. - Convenções de nomenclatura e preferências de refatoração. - Referências para os registros de decisão canônicos e notas de arquitetura. Mantenha conciso. Delimite o escopo. Faça commit. Mas o `AGENTS.md` nunca foi feito para ser um índice consultável de cada símbolo, arquivo e call site do seu repositório. ## Onde o AGENTS.md sozinho vira estático em escala Quatro modos de falha, um por card. ### // acordos não são um índice Dizer ao Codex *como trabalhar* não diz a ele *o que existe*. A primeira edição num pacote desconhecido é um chute sobre caminhos de arquivo e nomes de função. O AGENTS.md não consegue listar cada símbolo, e você nem ia querer isso. ### // o doc se desatualiza em relação ao código Um bloco do AGENTS.md descrevendo a topologia da sua fila está certo até alguém introduzir um novo consumidor. Agora o código é a fonte da verdade e o doc está confiantemente desatualizado. O Codex lê o errado. ### // renomear é um problema de grafo “O que referencia essa classe?” não tem resposta num arquivo markdown. O Codex ou faz grep e torce para dar certo no monorepo inteiro ou pede para você colar os call sites no chat. ### // janelas de contexto não são de graça Encher o AGENTS.md até o Codex “saber o suficiente” consome tokens que deveriam pagar por raciocínio. Depois de alguns KB, você troca qualidade de resposta por volume de contexto estático. ## Como as três camadas se encaixam Usuários do Codex já pensam nesse formato. A página deveria deixar isso óbvio. - **AGENTS.md**: acordos (como o Codex se comporta) - **MCP**: o canal (como ele acessa) - **Maguyva**: informações da base de código (o que ele enxerga) - **AGENTS.md**: como o Codex se comporta nesse repositório. - **MCP**: como o Codex acessa ferramentas e contexto. [(especificação)](https://modelcontextprotocol.io/docs/getting-started/intro) - **Maguyva**: o que o Codex enxerga quando faz uma pergunta à base de código. Busca semântica, AST, de grafo e de texto retornada com caminhos de arquivo e números de linha. > O AGENTS.md diz ao Codex *como trabalhar*. > O Maguyva dá ao Codex *uma base para trabalhar*. ## Três fluxos de trabalho Específico para o Codex. Fundamentado no grafo de chamadas real, não no grep do Codex. ### 01. Renomeie uma classe compartilhada, encontre cada dependente primeiro ```text codex> renomear PaymentClient → BillingClient graph::callers(PaymentClient) 12 referências em 7 pacotes graph::importers(src/payments/client.ts) 9 importadores graph::extends(PaymentClient) 2 subclasses (RetryClient, MockClient) → O Codex propõe uma migração de 21 edições com a lista de arquivos inline. [exit 0] ``` O Codex pergunta ao Maguyva pelos dependentes *antes* de começar a editar. A lista de migração volta fundamentada no grafo real, não na lembrança do Codex. ### 02. Encontre a implementação real, não o stub de teste ```text codex> como o normalizePhoneNumber trata o E.164? semantic::query("normalize phone E.164") src/util/phone.ts:88 normalizePhoneNumber() ← impl real test/util/phone.spec.ts:14 jest.mock(...) ← stub [exit 0] ``` Nomes mentem. Mocks fazem sombra no código real. O Maguyva ranqueia a implementação real acima do mock de teste. ### 03. Confira o raio de impacto antes de uma refatoração ```text codex> o que chama QueueDispatcher.publish? graph::callers(QueueDispatcher.publish) 3 em src/billing/* 1 em src/audit/* 1 em src/notifications/* [exit 0] ``` Call-sites entre pacotes aparecem inline. O diff é fundamentado em importadores reais, não no grep do Codex. ## Configuração no Codex CLI 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 conseguir verificar as respostas. ### 02. Adicione o Maguyva como servidor MCP na sua configuração do Codex `~/.codex/config.toml` ```text export MAGUYVA_API_KEY=mgv_xxxx codex mcp add maguyva --url https://maguyva.tools/mcp --bearer-token-env-var MAGUYVA_API_KEY ``` ```toml [mcp_servers.maguyva] url = "https://maguyva.tools/mcp" bearer_token_env_var = "MAGUYVA_API_KEY" ``` ### 03. Faça uma pergunta cuja resposta você já saiba Não comece com a empresa inteira. Comece com um repositório e uma pergunta verificável. ## Indexe um repositório que você já conhece. Conecte o Codex via MCP. Faça uma pergunta cuja resposta você consiga verificar.