// acordo
AGENTS.md
Como o Codex deve se comportar nesse repositório.
Para usuários do Codex CLI
O AGENTS.md diz ao Codex como trabalhar.
Não o que está lá.
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.
Plano Free: 3 repositórios, Até 50 mil linhas de repositório indexadas, sem cartão.
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.
// transporte
MCP
Como o Codex acessa ferramentas externas e contexto.
// codebase
Maguyva
O servidor MCP que retorna fatos fundamentados do repositório.
// quem paga
Workspaces, não assentos
Agentes não pagam assento. Ver preços
O AGENTS.md é um acordo de trabalho. Use-o.
Instruções persistentes pertencem ao AGENTS.md. É o lugar certo para:
- Comandos de build, test e lint que o Codex deve rodar.
- Guardrails do tipo “sempre faça X / nunca faça Y” restritos 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-and-pray 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
fatos do codebase
o que ele enxerga
- AGENTS.md como o Codex se comporta nesse repositório.
- MCP como o Codex acessa ferramentas e contexto. (especificação)
- Maguyva o que o Codex enxerga quando faz uma pergunta ao codebase. 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 algo para trabalhar a partir daí.
Três fluxos de trabalho
Específico para o Codex. Fundamentado no grafo de chamadas real, não no grep do Codex.
// workflow 01
Renomeie uma classe compartilhada, encontre cada dependente primeiro
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.
// workflow 02
Encontre a implementação real, não o stub de teste
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.
// workflow 03
Confira o raio de impacto antes de uma refatoração
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.
// step 01
Indexe um repositório em maguyva.ai
Escolha um que você conheça bem, para conseguir verificar as respostas.
// step 02
Adicione o Maguyva como servidor MCP na sua configuração do Codex
$ export MAGUYVA_API_KEY=mgv_xxxx $ codex mcp add maguyva --url https://maguyva.tools/mcp \ --bearer-token-env-var MAGUYVA_API_KEY # equivalent ~/.codex/config.toml [mcp_servers.maguyva] url = "https://maguyva.tools/mcp" bearer_token_env_var = "MAGUYVA_API_KEY"// step 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.