Blog do Maguyva

Contexto que viaja com você

Mon, 07 Sep 2026 00:00:00 GMT

O indexador do Cursor é excelente dentro do Cursor. Autocompletar, edição inline, chat e o agente naquela janela já se apoiam em um índice de projeto que o Cursor opera para o workspace aberto. Se o Cursor é a única superfície em que você escreve, e esse índice já encontra os arquivos certos, fique lá. Esse é o caso honesto de “fique onde está”, e com razão é a primeira frase desta página.

Este texto trata da outra metade de uma semana comum. O mesmo repositório também é aberto no Claude Code, consultado pelo Codex CLI, revisado em uma segunda máquina, ou consultado por um agente rodando em CI. A pergunta não é “qual indexador é melhor”. A pergunta é se o mapa em que o agente confia em uma janela é o mesmo em que confia na próxima.

O Maguyva é esse mapa que viaja com você. É uma camada de contexto de código MCP remota. O agente a consulta do mesmo jeito que consulta qualquer outra ferramenta MCP. Os resultados voltam como caminhos ranqueados com números de linha. O Cursor continua sendo o editor. O contexto é o que se move.

Para que serve o indexador do Cursor

A indexação embutida do Cursor existe para que chat, agente e busca dentro do editor possam recuperar código relevante em vez de depender só do que cabe na janela de contexto bruta do modelo. Esse é o design certo para uma IDE. O índice é nativo do Cursor. Não é um servidor MCP e não é acessível por nenhum outro cliente.

Como funciona, conforme descrito na documentação pública do Cursor e no relato do próprio Cursor no momento em que este texto foi escrito: o caminho de busca principal não é mais um índice de embeddings na nuvem. A equipe do Cursor declarou em seu fórum da comunidade que a busca semântica/baseada em embeddings dedicada está sendo desativada em favor de uma recuperação baseada em grep, porque os modelos atuais já buscam bem o suficiente em uma árvore viva por conta própria. No lugar dela está o Instant Grep, um índice de busca local construído a partir de n-gramas, listas invertidas e filtros de Bloom, mantido em uma tabela de consulta mapeada em memória, de modo que as consultas são resolvidas na própria máquina do desenvolvedor, e não em um servidor.

O índice em si vive dentro do próprio diretório .git/cursor/ do repositório, ancorado a um commit git específico; mudanças desde esse commit se sobrepõem em vez de disparar uma nova varredura, e o índice só se reconstrói quando o estado local se afastou bastante daquilo contra o que foi construído. Como fica dentro de .git, nunca é versionado nem enviado — apague a pasta, e o índice some. .gitignore é respeitado por construção, já que só conteúdo rastreado pelo git é elegível, e .cursorignore é aplicado no caminho de leitura. Não há mais etapa de embedding no lado do servidor nem banco de dados vetorial remoto nesse caminho. Documentações anteriores descreviam um design assistido pela nuvem — criptografia de blocos, sincronização por árvore de Merkle, reaproveitamento de índice entre colegas de equipe — e a própria equipe do Cursor já afirmou que esse design está sendo desativado, então este texto não o descreve mais como atual.

Um destaque dentro do editor é o subagente Explore do Cursor. Ele pode disparar várias buscas paralelas em sua própria janela de contexto, em um modelo mais rápido, e retornar só os achados relevantes, para que a conversa principal não fique inchada com resultados de busca. Isso é um ponto forte genuíno dentro do editor. Mantenha-o.

Workspaces multi-raiz são suportados: o contexto de cada pasta aberta fica disponível para o Agente. Alguns recursos dependentes de git, como worktrees, ficam desativados em configurações multi-raiz, e os Cloud Agents não suportam workspaces multi-raiz de jeito nenhum.

Nada disso é motivo para abandonar o Cursor. É uma descrição precisa de um mapa que é excelente onde vive.

O que “viajar com você” realmente significa

Um mapa viaja com você quando as mesmas perguntas retornam o mesmo tipo de resposta, com citações que você pode abrir, a partir de mais de um cliente.

No Cursor: “Onde parseConfig é definido, e quem o chama?”
No Claude Code, no mesmo repo: a mesma pergunta.
No Codex CLI, em uma máquina de revisão que nunca abriu a janela do Cursor: a mesma pergunta.
Em um agente de CI que fala MCP: a mesma pergunta, contra o mesmo snapshot hospedado.

Se cada superfície constrói seu próprio índice privado, você não tem um mapa. Você tem vários caches que divergem. O índice do editor pode estar atualizado para a árvore em disco. A sessão da CLI pode estar um dia atrasada. O job de CI pode estar olhando um checkout diferente. O agente vai continuar soando confiante mesmo assim.

O indexador do Cursor não deveria resolver isso. Como vive dentro do editor, o contexto que ele constrói é para aquele editor. Um leitor que também precisa de uma CLI, de um pipeline de CI ou de um editor diferente precisa de uma ferramenta separada para essas superfícies. Isso é um fato de escopo, não um defeito. O Maguyva é essa ferramenta separada.

Uma contagem de linguagens publicada para o indexador do Cursor não é informada nas notas que este rascunho pode usar. O Maguyva publica mais de 279 linguagens e tecnologias baseadas em texto. Os preços do Cursor também não são copiados aqui; veja a página de preços deles. O Maguyva cobra por workspace, não por assento, com planos publicados de $0, $19, $49 e $149, dependendo da pegada indexada e do tamanho do workspace.

Um mapa hospedado, todo cliente MCP

O Maguyva é um servidor MCP remoto. Você conecta o GitHub, escolhe os repositórios, e o pipeline na nuvem constrói símbolos, arestas do grafo e um mapa ranqueado. Você adiciona uma chave de API à configuração MCP do cliente que já usa. O Maguyva tem guias de configuração para 24 clientes MCP documentados — incluindo o Cursor — e pode se conectar a outros clientes compatíveis com MCP que suportem a configuração padrão.

A página de configuração do Cursor é o caminho específico do editor, se for onde você trabalha. O mesmo servidor atende Claude Code, VS Code, Windsurf, Codex CLI e o resto. Você não troca de editor. Você dá a cada agente a mesma superfície de ferramentas: 11 ferramentas MCP voltadas ao cliente em busca, símbolos, análise de dependências, recuperação de arquivos, contexto de repositório e workflows utilitários determinísticos. Recuperação semântica, estrutural, por grafo e de texto são fundidas em resultados ranqueados.

Esse é o benefício da portabilidade. As citações que você avaliou no Cursor de manhã têm a mesma forma das citações que o Codex CLI vai retornar à noite. Caminho do arquivo e número da linha. Abra-as. Se estiverem erradas, você vê. Se estiverem certas, a próxima edição tem um lugar para pousar. A afirmação aprovada é menos edições alucinadas, não a promessa de que toda edição está correta.

A atualidade é publicada. Snapshots têm carimbo de tempo, então o agente sabe qual versão da árvore está lendo. A cadência de reconstrução é diária no plano gratuito e a cada hora nos planos pagos. O limite honesto é o trabalho local não sincronizado: uma edição que só existe em uma árvore de trabalho ainda não está no mapa hospedado. Esse limite é o mesmo não importa de qual cliente você consulte, e esse é justamente o ponto. A deriva entre clientes deixa de ser um segundo limite escondido.

Os docs dão o loop de ativação que se aplica a todo cliente: indexar um repo que você já conhece, conectar o cliente, fazer uma pergunta que você consiga verificar. Faça isso uma vez no Cursor. Faça de novo a partir da CLI que você realmente usa em dias de revisão. Se as duas respostas citarem o mesmo handler, o mapa viajou.

Como os dois mapas convivem

Use os dois. Eles não são alternativas no sentido de uma página de comparação.

Mantenha o indexador do Cursor ativo para o projeto em disco. Deixe o Explore, o Instant Grep e o agente dentro do editor usá-lo. Esse loop é nativo e rápido.
Adicione o Maguyva como servidor MCP no Cursor para que a mesma sessão também possa consultar o mapa hospedado do workspace. O Cursor é um cliente Maguyva documentado. Você não está escolhendo um índice e apagando o outro.
Adicione o mesmo servidor Maguyva ao Claude Code, Codex CLI, ou qualquer outro cliente MCP que toque o repo. Uma única forma de chave de API. Um único workspace.
Se um agente de CI for compatível com MCP, aponte-o para o mesmo servidor. Ele vai ler o mesmo snapshot com carimbo de tempo que o notebook leu.

O índice do editor continua sendo a melhor ferramenta para “o que está em disco nesta janela, agora”. O mapa hospedado é a melhor ferramenta para “como este workspace se parece para todo agente que vai tocá-lo hoje”. Essas frases não competem.

As cotas de workspace são publicadas na página de preços: repos, linhas indexadas e usuários, cobrados por workspace. Agentes e humanos compartilham a mesma contagem de usuários. Comece grátis com um repo que você já sabe avaliar. Aumente o workspace só depois que as citações sobreviverem ao contato com a árvore.

O que esta página não afirma

Ela não afirma que o indexador do Cursor é fraco, incompleto, ou um motivo para trocar de editor. A primeira frase deste rascunho é o oposto.

Ela não afirma que o Maguyva substitui o Instant Grep ou o subagente Explore. Esses são recursos do Cursor. Eles ficam no Cursor.

Ela não inventa uma contagem de linguagens, um número de latência, nem uma economia de tokens para nenhum dos dois produtos. Números desconhecidos permanecem não publicados.

Ela não finge que trabalho local não enviado está no mapa hospedado. Snapshots com carimbo de tempo tornam esse limite visível. Eles não o removem.

O teste é comum. Indexe um repo que você já conhece. Faça uma pergunta que você consiga verificar, primeiro no Cursor, depois em um segundo cliente MCP. Contexto que viaja com você é a mesma citação nos dois lugares.

// same map, wherever you opened it.

Primeiro o mapa, depois a revisão

Mon, 07 Sep 2026 00:00:00 GMT

Dois trabalhos diferentes ficam de cada lado de um pull request. Antes de o agente escrever, ele precisa de um mapa da árvore que está prestes a mudar. Depois que o agente abre um PR, algo deveria ler essa mudança contra o resto do sistema e deixar comentários sobre os quais um humano possa agir.

Esses trabalhos parecem semelhantes de longe porque ambos envolvem “entender a base de código”. Não são o mesmo produto. Um responde “onde essa mudança deveria pousar?”. O outro responde “o que esse diff quebrou que um linter linha a linha vai perder?”. Misturá-los produz um primeiro rascunho pior e uma revisão mais barulhenta.

Este texto é um guia de fluxo de trabalho conjunto. O Maguyva é o mapa que o agente consulta primeiro. O Greptile é o agente de revisão que comenta o PR depois. A dupla é complementar por construção: o Maguyva não revisa pull requests, e o Greptile não substitui a camada de contexto que o agente usou para escrevê-los.

Por que essa divisão é útil

Um agente de código que parte de priors de treinamento mais alguns arquivos colados vai inventar um caminho plausível e editá-lo. Essa é a falha do arquivo errado, e é um problema de recuperação. O Maguyva é uma camada de contexto de código MCP remota: recuperação semântica, estrutural (AST), por grafo/dependência e de texto, fundida em resultados ranqueados, mais busca de símbolos e recuperação de arquivos. Respostas fundamentadas voltam como path/file.ext:line, então você consegue rejeitar um erro antes que um patch exista. A afirmação continua modesta: menos edições alucinadas. O modelo ainda pode adivinhar. O primeiro passo só deixa de ser um chute.

O Greptile é um agente de revisão de código com IA. Em suas próprias palavras, ele revisa automaticamente todo pull request com compreensão completa da base de código, e posiciona isso contra linters tradicionais que verificam arquivos isoladamente em vez do sistema inteiro. A configuração consiste em instalar o app do GitHub ou GitLab e selecionar repositórios. Não há índice local para você operar. A hospedagem é o Greptile Cloud (eles declaram conformidade SOC 2 Tipo II, com relatório disponível sob solicitação), com uma opção auto-hospedada oferecida para empresas.

O fluxo numerado deles é: conectar e construir um grafo de dependências de cada função, classe e dependência; a cada pull request, analisar a mudança usando esse grafo completo do repo e publicar achados como comentários de PR com correções sugeridas, em cerca de três minutos; cada comentário pode passar o problema para um agente de código que a equipe já usa. Eles também declaram ler comentários humanos anteriores em PRs ao longo do tempo para aprender os padrões de código de uma equipe e reduzir sugestões ruidosas. O sistema de aprendizado deles, segundo declaram, precisa de 2 a 3 semanas para se adaptar.

Isso é revisão, não redação. O ponto forte do Greptile é o contexto de grafo completo do repo sobre a mudança que já pousou em um PR, seguido de um loop fechado que envia o achado para Claude Code, Codex, Conductor, Cursor ou Devin. O ponto forte do Maguyva é o mapa ranqueado que o agente consultou antes de essa mudança ser escrita. Use os dois. Não peça a nenhum dos dois para fazer o trabalho do outro.

Uma integração de produto de primeira parte Maguyva–Greptile não é declarada. Você não precisa de uma. O Maguyva fala com o agente via MCP. O Greptile fala com o GitHub ou GitLab pelo app deles. Eles se encontram no pull request. Sem script de cola, sem cron que canalize uma ferramenta para a outra. A dupla dispensa bash porque cada produto já ocupa a superfície que lhe pertence.

O que isso não é

Isso não é uma demolição do Greptile. Não é uma página “troque de revisor”. O Greptile lançou no Hacker News em 5 de março de 2024 como empresa da Y Combinator W24, e aquele tópico é como muita gente conheceu o produto pela primeira vez. Se foi assim que você os encontrou, fique com eles. Esta página é a metade da frente que falta nesse loop: ancorar o agente para que o PR que o Greptile vê já esteja mirando nos arquivos certos.

Os materiais de marketing do Greptile lideram com afirmações de velocidade de revisão e captura de bugs. Trate-as como afirmações do próprio Greptile, não como números verificados independentemente. Este rascunho não as repete como fatos.

A cobertura de linguagens é o mesmo tipo de honestidade. O Greptile enquadra o suporte como cobertura de todas as linguagens de programação em vez de uma lista enumerada; um número preciso não é informado. O Maguyva publica mais de 279 linguagens e tecnologias baseadas em texto, com uma divisão técnica (AST apoiado em parser versus só texto) no site quando a pergunta é técnica. São produtos diferentes fazendo afirmações diferentes. Não os misture.

Os preços do Greptile não são informados nas notas que este rascunho pode usar. Planos pagos existem; veja a página de preços deles. O Maguyva cobra por workspace, não por assento. Os planos começam grátis. A página de preços lista os níveis publicados se você precisar dos números de workspace.

Fluxo de trabalho

Três etapas nomeadas. Execute-as nessa ordem. Não pule nenhuma na primeira vez que tentar a dupla.

1. Contexto do Maguyva

Indexe um repositório que você já conhece. Conecte o cliente MCP em que você já escreve — Claude Code, Cursor, Codex CLI, VS Code, Windsurf, ou outro cliente compatível com MCP. O Maguyva tem guias de configuração para 24 clientes MCP documentados e pode se conectar a outros clientes que suportem a configuração MCP padrão.

Faça uma pergunta que você consiga avaliar antes de qualquer um escrever uma linha. “Onde a expiração de sessão é tratada, e o que a chama?” é um primeiro movimento melhor que “conserta a autenticação”. Exija citações. Abra os resultados file.ext:line. Siga o símbolo. Confirme a dependência que você está prestes a tocar.

O Maguyva expõe 11 ferramentas MCP voltadas ao cliente em busca, símbolos, análise de dependências, recuperação de arquivos, contexto de repositório e workflows utilitários determinísticos. Quatro modos de recuperação são fundidos em resultados ranqueados; find_symbol é uma ferramenta separada quando você já conhece o nome. Os docs descrevem o caminho mais curto: começar grátis, indexar um repo que você já conhece, conectar o cliente, depois fazer uma pergunta que você consiga verificar.

Snapshots têm carimbo de tempo, então o agente consegue saber qual versão da árvore está lendo. O limite honesto é o trabalho local não sincronizado. Se a edição só existe em uma árvore de trabalho e não foi enviada, o mapa hospedado ainda não a contém. Arquivos de instrução (CLAUDE.md, AGENTS.md) continuam tendo seu lugar aqui, para convenções e o que não deve ser tocado. Não são um mapa vivo. Use-os para comportamento. Use o Maguyva para fatos.

Não deixe o agente abrir um PR antes que as citações sobrevivam ao contato com o repo. Essa barreira é todo o sentido desta etapa.

2. PR do agente

O mesmo agente agora escreve a mudança no cliente pelo qual você já paga. O Maguyva não é um editor nem um revisor. O agente continua produzindo o diff. Você continua abrindo o pull request no GitHub ou GitLab do jeito que já faz.

O que deveria ser diferente é o primeiro arquivo. O PR deveria nomear o handler que realmente implementa o comportamento, o chamador que vai quebrar, e o teste que vai falhar se a mudança estiver errada. Se a etapa 1 foi pulada, a etapa 3 vai gastar seus comentários em uma mudança que pousou no pacote errado. O Greptile ainda consegue encontrar problemas sistêmicos. Ele não deveria também ter que se recuperar de um caminho alucinado.

Mantenha o PR restrito. Um primeiro arquivo fundamentado não é licença para reescrever o módulo. A dupla complementar funciona quando o agente fez um trabalho com um mapa, e então pediu a um revisor que fizesse outro trabalho em um diff delimitado.

3. Revisão do Greptile

O Greptile já está conectado ao repositório pelo app do GitHub ou GitLab. No novo pull request, ele analisa a mudança usando o grafo completo do repo que construiu e publica achados como comentários com correções sugeridas. Os próprios materiais deles colocam essa passagem em cerca de três minutos.

Leia os comentários como você leria um colega de equipe cuidadoso: abra o local citado, decida se o achado é real, depois aja. Onde o Greptile oferece “Fix with your Agent”, ele envia o problema — caminhos de arquivo, números de linha, código sugerido — para Claude Code, Codex, Conductor, Cursor ou Devin. “Fix All” envia todos os problemas da revisão de uma vez. Eles também entregam um MCP do Greptile e um plugin do Claude Code para essa transferência. O Maguyva não está nessa lista nomeada de destinos; essa ausência não é um problema. O Maguyva já fez seu trabalho na etapa 1. O agente de código que escreveu o PR é quem deveria receber o payload de correção.

Espere ruído nas primeiras 2 a 3 semanas enquanto o sistema de aprendizado do Greptile se adapta aos comentários que sua equipe realmente deixa. Esse é o cronograma declarado deles, não um defeito na dupla. A revisão humana continua no loop. O Greptile é a primeira passagem automatizada, não o botão de merge.

Se um comentário do Greptile aponta para um arquivo que o agente nunca consultou na etapa 1, esse é um sinal útil. Ou o mapa perdeu um chamador, ou o agente pulou uma citação. Corrija o rascunho contra o comentário. Não desative o revisor.

Como manter o complemento honesto

Maguyva primeiro, sempre. Uma revisão de um PR de arquivo errado ainda é uma revisão do arquivo errado.
Greptile depois, sempre. Um rascunho bem citado ainda precisa de uma leitura do diff em escala de sistema inteiro.
Não peça ao Maguyva para postar comentários de PR. Ele não faz isso.
Não peça ao Greptile para ser a primeira camada de recuperação do agente enquanto ele ainda está escolhendo um caminho. Esse não é o trabalho para o qual o app deles no GitHub ou GitLab foi construído.
Não invente um pipeline bash que “sincroniza” os dois. O PR é a interface.
Verifique os dois lados de forma independente. Indexe um repo que você já conhece. Faça uma pergunta que você consiga verificar. Depois abra um PR pequeno e leia o que o Greptile realmente comenta.

O loop é comum assim que você o nomeia. Primeiro o mapa. Depois o PR do agente. Depois a revisão. Cada produto fica do lado do pull request em que é bom.

// map first. review second. in that order.

Dar a um agente de IA o contexto de um repositório grande sem indexador local

Fri, 14 Aug 2026 00:00:00 GMT

Um repositório grande não cabe em uma janela de contexto, e se você já apontou um indexador de notebook para um monorepo de verdade, sabe que ali também não cabe confortavelmente — a RAM dispara, o primeiro índice demora uma hora, e seu agente ainda começa a próxima sessão adivinhando quais arquivos importam.

A resposta usual é rodar um indexador ao lado do editor, e para um repo que cabe confortavelmente em uma única máquina, é uma boa resposta. Se o seu monorepo já indexa rápido no Cursor e esse é o único lugar onde você precisa do mapa, este texto não tem nada a acrescentar — pule-o.

Este texto trata do outro caso — quando um agente precisa de um mapa consultável de um repo grande, e você não quer rodar um indexador local para consegui-lo.

Quando um indexador local é a ferramenta errada

Um índice local assume que o código vive na máquina que o consulta, e na escala real de um monorepo essa suposição fica tensa até dentro de um único editor. O repo é simplesmente maior do que você quer manter aquecido em um notebook: você trabalha em um pacote enquanto o raio de impacto vive três diretórios adiante, e um primeiro índice a frio de uma árvore de dois milhões de linhas não é algo que você queira encarar duas vezes — nem na sua máquina, nem em um runner de CI que nunca clonou a árvore antes. Ou um colega de equipe deveria conseguir consultar o mesmo mapa que você, sem esperar a própria máquina se arrastar pelo mesmo índice.

Nada disso é motivo para jogar fora um bom indexador de editor. É motivo para também ter um mapa hospedado que qualquer um dos seus agentes possa consultar via MCP.

E o problema de escala vai além de “arquivos demais para colar”. Em uma árvore grande, a pergunta interessante quase nunca é “me mostra este arquivo” — é qual arquivo, qual símbolo, quais chamadores, quais testes. Um agente que começa listando src/ e lendo os três primeiros resultados vai alegremente perder o handler em apps/api e o cliente gerado em packages/sdk. O que você precisa é de recuperação construída a partir da árvore inteira, depois ranqueada, depois citada.

O que “contexto de um repo grande” realmente significa

Despejar arquivos no prompt não é contexto — é uma cópia menor e pior da árvore. O que seu agente realmente precisa é fazer perguntas e receber respostas citadas de volta: onde esse símbolo é definido e quem o chama, o que depende do módulo que estou prestes a mudar, qual arquivo de teste cobre esse comportamento, e como a árvore se parece agora, não no trimestre passado.

Essas respostas têm que vir de um índice construído a partir do seu repo, e não da memória do modelo sobre repos de outras pessoas, e o índice tem que viver em algum lugar diferente da janela de contexto do agente. Para esse problema, ele também deveria viver em algum lugar diferente do seu notebook.

Mais uma coisa que arquivos de instrução não podem fazer por você: CLAUDE.md e AGENTS.md são o lugar certo para convenções e comportamento, mas não são um mapa vivo, ranqueado e consultável de uma árvore de dois milhões de linhas. Use regras para comportamento; use inteligência de repositório para fatos.

Construir o mapa na nuvem, consultá-lo de qualquer cliente

O Maguyva é uma camada de contexto de código MCP remota. Você conecta o GitHub, escolhe seus repositórios, e vai embora enquanto pipelines na nuvem analisam a árvore, constroem os símbolos e as arestas do grafo, e mantêm um mapa ranqueado — sem indexador local, nunca.

Quando você envia código, arquivos alterados são analisados incrementalmente, e as camadas de grafo e ranqueamento se reconstroem em uma programação: diária no plano gratuito, a cada hora nos pagos. Cada snapshot tem carimbo de tempo, então seu agente consegue saber qual versão da árvore está lendo. O limite honesto aqui é o trabalho local não sincronizado — uma edição que só existe na sua árvore de trabalho, nunca enviada, ainda não está no mapa hospedado.

Aí você conecta o cliente que já usa adicionando uma chave de API à configuração MCP dele. Há guias de configuração para 24 clientes MCP documentados, e qualquer outro cliente compatível com MCP que suporte configuração padrão também pode se conectar. Se o Cursor é onde você mora, a página do Cursor percorre esse caminho; o mesmo servidor atende Claude Code, VS Code, Windsurf, Codex CLI e o resto.

Você não troca de editor. Você dá ao seu agente uma superfície de ferramentas — 11 ferramentas MCP em busca, símbolos, análise de dependências, recuperação de arquivos e contexto de repositório — com cobertura em mais de 279 linguagens e tecnologias baseadas em texto, o que importa mais do que se pensa em um monorepo que deixou de ser uma única linguagem há anos.

As respostas voltam fundamentadas, como caminhos de arquivo com números de linha. Recuperação semântica, estrutural, por grafo e de texto são fundidas em resultados ranqueados, de modo que uma pergunta como “o que depende de parseConfig” não te dá nem um despejo de grep nem um único trecho semântico, mas o punhado de lugares que realmente importam.

Um passo a passo concreto

Não comece indexando a empresa inteira. Aqui está o caminho que funciona:

Escolha um repositório que você já conhece bem — um pacote que você consiga avaliar à mão vale mais que a maior árvore que você tem.
Comece grátis: 3 repos, 50 mil linhas indexadas, todas as 11 ferramentas, sem cota mensal de consultas. Se seu repo representativo for maior que isso, a página de preços lista os níveis de workspace ($0, $19, $49, $149) por pegada indexada — não por número de assentos.
Conecte o GitHub e espere o primeiro índice terminar. Você não está compilando nada localmente.
Conecte o cliente MCP — algumas linhas de configuração. O Maguyva é um servidor MCP remoto, então não há plugins, nem extensões, nem um segundo editor para adotar.
Faça uma pergunta que você consiga verificar. “O que depende de parseConfig?” ou “Onde a expiração de sessão de login é tratada?” Depois abra os resultados citados file.ext:line e confira contra a árvore na sua frente.
Só depois que as citações sobreviverem a esse contato você deixa o agente editar.

Se o primeiro repo encaixar bem e sua árvore for grande, aumente o workspace para acompanhar suas linhas indexadas e a cadência de reconstrução. Humanos e agentes compartilham a mesma contagem de usuários — o Maguyva cobra por workspace, não por assento — então adicionar um terceiro agente ao loop não custa nada.

O teste de ativação é o mesmo que os docs recomendam para qualquer primeira execução: indexar um repo que você já conhece, fazer uma pergunta que você consiga verificar. Um repo grande não muda o teste; só torna um primeiro arquivo errado mais caro.

O que observar depois de conectado

Fique de olho em três coisas. Atualidade: planos pagos reconstroem a cada hora, os gratuitos diariamente, e trabalho local não enviado não estará no mapa — essa é a troca que você aceita. Escopo: indexe um conjunto representativo de repos, não cada fork arquivado; o nível gratuito é deliberadamente dimensionado para descobrir se as respostas valem a pena manter. E verificação: um mapa de repo grande que não consegue citar caminhos e números de linha é só um motor de adivinhação mais lento, então faça seu agente mostrar o lugar antes de entregar o patch.

Depois rode o mesmo teste que rodaria em um repo pequeno. Indexe um repo que você já conhece. Faça uma pergunta que você consiga verificar. Se o mapa for real, seu agente para de começar de uma árvore fria.

// no laptop got hot building this map.

Por que seu agente de código com IA alucina caminhos de arquivo

Fri, 14 Aug 2026 00:00:00 GMT

O sinal revelador não é um corpo de função errado. É uma edição confiante em um arquivo que não existe, ou em um arquivo que existe mas não é o que implementa o comportamento.

Você pediu uma correção de expiração de sessão. O agente abriu src/auth/session.ts. Esse caminho é plausível. Também está errado. O handler de verdade vive em apps/api/src/middleware/expiry.ts, renomeado há duas refatorações. O agente não mentiu para você. Ele completou uma string em formato de caminho a partir de priors de treinamento mais o que já estivesse na janela de contexto.

Esse é o padrão de falha comum em um repositório real. O modelo sabe escrever código. O erro está em escolher o lugar errado para escrevê-lo.

Por que agentes inventam caminhos

Um agente de código é um modelo de previsão do próximo token com ferramentas. Quando você diz “conserta a expiração de sessão”, ele precisa nomear um arquivo antes de conseguir ler ou aplicar um patch em qualquer coisa. Se ainda não tem um mapa fundamentado, ele constrói um caminho a partir de:

Convenções de nomenclatura que já viu em outros repositórios. src/auth/session.ts é um formato frequente.
Arquivos que já estão na conversa, que talvez sejam os que você colou semana passada, não os que importam agora.
Listagens de diretório que ele acabou executando, incompletas em uma árvore grande.
Arquivos de instrução. CLAUDE.md e AGENTS.md dizem ao agente como se comportar. Não são um índice vivo de símbolos, chamadores ou caminhos atuais.

Nenhuma dessas fontes é um mapa deste repo, hoje. O modelo preenche a lacuna do jeito que preenche qualquer lacuna: com uma continuação de alta probabilidade. Essa continuação muitas vezes parece um caminho real. Às vezes o arquivo existe e fica ao lado do certo. Às vezes existiu em uma branch que foi mesclada mês passado. Às vezes nunca existiu.

O grep não te salva aqui se o agente nunca busca a string certa. O agente chutou um caminho, depois leu o que aquele caminho retornou, depois editou. O primeiro passo errado foi o caminho, não o patch.

Ler arquivos também não é a mesma coisa que encontrar os certos. Claude Code, Cursor, Codex e ferramentas parecidas conseguem abrir o que você apontar para eles. A pergunta é se conseguem encontrar de forma confiável os arquivos certos, os símbolos importantes, as dependências, os testes e o raio de impacto antes de editar. Acesso a arquivo sem um mapa ainda começa com um chute.

A edição do arquivo errado é um problema de recuperação

Trate o caminho inventado como um erro de recuperação, não como uma falha de caráter.

Se o agente tivesse que retornar path/file.ext:line antes de ter permissão para editar, duas coisas aconteceriam. Primeiro, você conseguiria abrir a citação e rejeitar o trabalho em dez segundos. Segundo, o agente teria que consultar algo que realmente conhece a árvore.

Esse é o trabalho de uma camada de contexto de código. Busca semântica sozinha não é suficiente. Um trecho que “soa como expiração de sessão” ainda pode pousar em um pacote obsoleto. Você também precisa de texto exato quando conhece a string, busca de símbolos quando conhece o nome, busca estrutural quando conhece a forma, e um grafo de dependências quando precisa de chamadores e raio de impacto.

O Maguyva é essa camada para agentes de código compatíveis com MCP. Não é um editor. Claude Code, Cursor, Codex CLI, VS Code, Windsurf e outros clientes MCP continuam onde estão. O agente consulta um mapa ranqueado antes de tocar em uma linha.

A afirmação é modesta de propósito: menos edições alucinadas. O Maguyva não tira do modelo a capacidade de chutar. Ele muda o primeiro passo padrão de “inventar um caminho plausível” para “pedir locais ranqueados e citados”.

Como é uma resposta fundamentada

Uma resposta útil para “onde a expiração de sessão é tratada” não é um parágrafo. É uma lista curta de locais:

apps/api/src/middleware/expiry.ts:48 - o handler
apps/web/src/lib/auth-client.ts:112 - o chamador
apps/api/tests/expiry.test.ts:20 - o teste que vai falhar se a mudança estiver errada

Você pode abrir essas linhas. Se estiverem erradas, você para. Se estiverem certas, o agente pode editar. A verificação é o ponto, não um slogan.

O Maguyva expõe 11 ferramentas MCP voltadas ao cliente em busca, símbolos, análise de dependências, recuperação de arquivos, contexto de repositório e workflows utilitários determinísticos. Quatro modos de recuperação (semântico, estrutural, grafo/dependência e texto) são fundidos em resultados ranqueados; busca de símbolos é uma ferramenta MCP separada (find_symbol). Respostas fundamentadas voltam com caminhos de arquivo e números de linha, então você pode avaliá-las contra a árvore na sua frente.

Os docs descrevem o caminho mais curto: começar grátis, indexar um repo que você já conhece, conectar o cliente, depois fazer uma pergunta que você consiga verificar.

Um loop que muda a primeira edição

Você não precisa de uma nova religião de fluxo de trabalho. Precisa de um passo extra antes da primeira escrita.

Faça uma pergunta que você já consiga avaliar. “Que código trata login e expiração de sessão?” é melhor que “conserta a autenticação”.
Exija citações. Caminho de arquivo e número de linha, não um resumo de “o módulo de autenticação”.
Abra os arquivos citados. Siga o símbolo. Confirme a dependência que você está prestes a tocar.
Só então deixe o agente aplicar o patch.

Se o passo 2 não retorna nada útil, o agente não tem permissão para improvisar um caminho. Ele busca de novo, ou você aponta o caminho. Essa única barreira é o que produz menos edições alucinadas. O modelo é o mesmo modelo. O mapa é o que mudou.

Arquivos de instrução continuam importando. Mantenha-os. Use-os para convenções, regras de revisão e o que não deve ser tocado. Não peça a eles para serem o índice. Um CLAUDE.md que lista três diretórios importantes vai ficar desatualizado na semana seguinte a uma divisão de pacote. Um mapa consultável se atualiza quando o repo se atualiza.

Uma falha relacionada é o arquivo quase-certo: o agente abre auth.ts quando o comportamento vive em auth-client.ts, ou aplica patch em um arquivo gerado em vez da fonte, ou edita a cópia em packages/legacy porque o nome bateu. Citações não tornam esses erros impossíveis. Elas os tornam visíveis antes de o diff pousar.

O que um mapa não vai resolver para você

Seja realista sobre o que você está ganhando. Um mapa fundamentado não vai tornar toda edição correta — seu agente ainda pode escrever um patch ruim exatamente no arquivo certo. Se sua base de código se apoia em despacho dinâmico, reflexão ou monkey-patching, algumas buscas de símbolos vão voltar mais pobres do que você gostaria, porque é isso que a indireção em tempo de execução faz com qualquer índice estático. E se você está esperando uma porcentagem — “caminhos alucinados reduzidos em X%” — você não vai encontrar isso aqui, porque ninguém consegue medir essa cifra honestamente para o seu repo além de você mesmo.

O que você pode esperar é mais estreito e mais útil: o agente para de abrir suas edições com um caminho chutado. Esse primeiro passo fica fundamentado em um mapa real, e é daí que vêm as menos edições alucinadas. Tudo depois da citação — ler o diff, julgar o patch — continua sendo seu trabalho, do jeito que sempre foi.

O teste quase não custa nada: indexe um repo que você já conhece e faça uma pergunta que você consiga verificar. Comece com um caminho que já te queimou antes. Se as citações estiverem erradas, você vai ver na hora. Se estiverem certas, a próxima edição do seu agente tem um lugar melhor para pousar.

// it doesn't know the file. it knows how to find it.

Por Que Atualizamos a Busca de Código para o voyage-4-large

Tue, 09 Jun 2026 00:00:00 GMT

Os números de benchmark neste post refletem os rankings do RTEB no momento da publicação (junho de 2026). Rankings mudam; trate as classificações como um retrato de um momento, não um fato permanente.

A busca semântica só é tão boa quanto os embeddings por baixo dela.

Quando um agente pergunta ao Maguyva “onde tratamos retries”, ele não está fazendo grep pela palavra “retry”. Ele está pedindo o significado — o loop de backoff, o circuit breaker, a coisa que envolve uma chamada instável. Essa pergunta é respondida por um modelo vetorial que transforma código em um ponto no espaço e encontra os vizinhos. Escolha um modelo melhor e cada consulta semântica no produto fica silenciosamente mais precisa.

Então mudamos o nosso. A partir de junho de 2026, os embeddings de código do Maguyva rodam em voyage-4-large, substituindo voyage-code-3.

O Benchmark

Não tomamos essa decisão com base em achismo. O Retrieval Embedding Benchmark (RTEB) público ranqueia modelos de embedding em tarefas reais de retrieval, e no seu ranking de Código o voyage-4-large está em 1º lugar geral (90,86) — à frente do gemini-embedding-2-preview (90,26) e, notavelmente, à frente do modelo que já usávamos, o voyage-code-3 (89,73, 3º lugar).

É uma diferença absoluta pequena. Mas é uma diferença na direção certa, em um benchmark público, na tarefa exata com que nos importamos: recuperar código por significado.

O Trade-off Que Aceitamos: Quantização Binária

Aqui está a parte que a maioria dos posts de “atualizamos nosso modelo” deixa de fora.

O Maguyva não armazena vetores de precisão completa. Armazenamos embeddings quantizados em binário: cada vetor de 2048 dimensões colapsa em uma assinatura de 2048 bits — 256 bytes por vetor. Essas assinaturas são buscadas com distância de Hamming, indexadas e particionadas por tenant.

É um trade-off deliberado. A quantização binária abre mão de um pouco de precisão de retrieval em troca de um armazenamento drasticamente menor e matemática de distância rápida e barata, sem precisar operar um banco de dados vetorial separado. Para um produto que indexa repositórios inteiros por workspace, essa economia importa mais do que espremer a última fração de um ponto de benchmark.

O voyage-4-large se encaixa nesse design sem forçar uma migração da camada de armazenamento: ele produz saída de 2048 dimensões, igual ao voyage-code-3, então nossas colunas bit(2048) e o caminho de busca por Hamming não mudaram. O modelo melhorou; o schema ficou no lugar.

Código Foi Só o Começo

O Maguyva é uma ferramenta de inteligência de código. Mas também somos o cliente zero, e apontamos ele para outra coisa: o markdown que vive nos nossos repositórios ao lado do código. Registros de decisão de arquitetura, runbooks, contratos, documentos financeiros e de política — tudo isso versionado no Git, tudo isso por trás do mesmo servidor MCP, um índice semântico sobre os documentos, não apenas sobre o código-fonte.

É exatamente por isso que a amplitude do voyage-4-large importa. Na mesma família de rankings do RTEB, ele é 1º lugar em finanças, 1º lugar em saúde, e 1º lugar em retrieval de texto geral — à frente do Gemini Embedding do Google, do Embed v4 da Cohere, e do text-embedding-3-large da OpenAI. (A Voyage é cocriadora do RTEB, então lemos isso como um sinal público forte, mas não como um árbitro perfeitamente neutro — ainda assim, é comparado diretamente com todos os principais modelos comerciais, em conjuntos de dados privados de validação.) O mesmo índice que encontra a função certa para um agente encontra a cláusula certa em um contrato ou a linha certa em uma política — e nesses domínios, o voyage-4-large não é um meio-termo, é o líder.

Por Que Pagamos por Embeddings Premium

Existe uma forma mais barata de fazer busca, e boa parte dela é gratuita. A busca lexical — BM25 e afins — busca correspondências com palavras-chave, roda localmente e não custa nada. Modelos de embedding de código aberto como BGE, Nomic e embeddinggemma oferecem um retrieval semântico genuinamente decente, e você pode hospedá-los por conta própria pelo preço de uma GPU. O Maguyva também usa o lado gratuito: toda consulta funde busca textual, de AST, de grafo e semântica. Onde não economizamos é na camada semântica.

Pagamos por token por embeddings premium — voyage-4-large — em vez de hospedar um modelo gratuito por conta própria, por dois motivos. Primeiro, a busca por palavra-chave sozinha não consegue responder “onde tratamos retries” quando o código diz backoff e circuit breaker e nunca diz a palavra “retry” — captar o significado é a razão de ser do embedding, e nos domínios que atendemos, os modelos abertos ficam atrás dos premium: alguns pontos atrás em texto geral, e ainda mais atrás em nichos como código, contratos e finanças. Segundo, na nossa experiência, a qualidade do retrieval molda a resposta final mais do que o modelo do outro lado — um agente forte recebendo o contexto errado ainda responde errado, e nunca vê o documento que nunca lhe foi dado.

Então embeddings premium são uma conta por token que escala com cada repositório e documento que indexamos — e pagamos essa conta de propósito. Pelo resultado que os nossos usuários obtêm, a função certa ou a cláusula certa, achamos que esse trade-off vale a pena.

A Parte Honesta

A própria documentação da Voyage ainda rotula o voyage-code-3 como o modelo otimizado para código. Então por que mudar?

Porque lemos o benchmark público, não apenas a tabela de modelos do fornecedor, e o benchmark colocou o voyage-4-large no topo para retrieval de código. Essa foi uma decisão olhando para frente: pegar o modelo mais novo, geralmente mais forte, e validá-lo contra um ranking público nas tarefas que importam. Estamos confortáveis em fazer essa aposta porque a evidência é ampla — o voyage-4-large não vence só em código, ele também lidera em finanças, saúde e retrieval geral.

A Base Discreta

Toda ferramenta que expomos — busca semântica, coleta de contexto de tarefa, perguntas e respostas fundamentadas — desemboca no retrieval. Quando o retriever melhora, o agente do outro lado obtém evidências melhores, toma menos decisões equivocadas, e fundamenta suas respostas no código certo — ou na cláusula certa, ou na política certa. Um modelo de embedding mais preciso não é um recurso vistoso. É a base de todo o resto, e acabamos de aprimorá-la. Você não vai notar. Esse é o ponto.

Autoaperfeiçoamento Recursivo do Suporte a Linguagens: Aprimorando a Inteligência de Código em ~280 Linguagens

Tue, 26 May 2026 00:00:00 GMT

Os números neste post refletem o sistema no momento da publicação (maio de 2026). Consulte nossa página da equipe para números atualizados.

O Maguyva extrai símbolos, referências e um grafo de dependências a partir de código-fonte em aproximadamente 280 linguagens. Cada linguagem é um handler tree-sitter personalizado — queries, heurísticas, casos extremos — e cada handler pode estar sutilmente errado à sua própria maneira. Uma chamada de método emitida como uma leitura. Uma função atribuída ao escopo delimitador errado. Um relacionamento que simplesmente não existe.

Você não pode auditar isso manualmente. Nenhuma equipe consegue ler a saída de extração em 280 gramáticas e identificar as arestas ruins. Então a pergunta interessante não é “a nossa extração está correta” — é “como você descobre que ela está errada, nessa amplitude, sem um humano em cada loop”. Nossa resposta é o autoaperfeiçoamento recursivo do suporte a linguagens: um loop de qualidade guiado por agentes de linguagem, um LLM atuando como juiz, e uma regra que continuamos reaprendendo: verde não é o mesmo que correto.

Verde não é correto

Toda linguagem tem uma suíte de fixtures, e um controle de validação antes da publicação a pontua em cinco dimensões — acurácia, integridade estrutural, completude, qualidade e performance. Uma linguagem só fica VERDE quando, em suas fixtures, a precisão é ≥ 0,95, o recall é ≥ 0,99 e o F1 é ≥ 0,97, com pelo menos 20 arestas esperadas para confiança estatística. Abaixo disso, é AMARELA ou VERMELHA, e não vai para produção.

Esse controle é necessário, mas não suficiente. Fixtures validam contra fixtures que nós escrevemos. Elas codificam os casos que já pensamos. Um handler pode ser impecável em suas fixtures e ainda assim estropiar um padrão que só aparece em código real — um padrão idiomático de macros, um método com restrições de tipos genéricos, um recurso de linguagem para o qual ninguém escreveu uma fixture. VERDE significa que as fixtures passam. Não significa que um repositório real seja extraído de forma limpa. Então o loop precisa deixar as fixtures para trás e olhar para o mundo real.

O loop interno: verificação pontual, julgamento, correção, prova

O loop central roda uma linguagem por vez:

        ┌──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          │
  1. corpus run ── clone real-world repos, extract relationships   │
        │                                                          │
        ▼                                                          │
  2. spot-check 100 edges (seed 42, then seed 123 to cross-check)  │
        │                                                          │
        ▼                                                          │
  3. LLM judge classifies every sampled edge:                      │
        CORRECT · FALSE_POSITIVE · TYPE_ERROR ·                    │
        SCOPE_ERROR · METADATA_ERROR                               │
        │                                                          │
        ▼                                                          │
  4. fix ONE thing — handler .py, .scm query, or config           │
        │                                                          │
        ▼                                                          │
  5. re-validate — F1 + re-classify + manifest diff (no regressions)│
        │                                                          │
   better? ──no──► revert, try a different fix ────────────────────┤
        │ yes                                                       │
        ▼                                                           │
  6. promote the fix into fixtures (a permanent regression guard) ──┘

Alguns detalhes fazem isso funcionar em vez de ficar andando em círculos.

O juiz é o agente, não uma chamada de API. Quando dizemos “LLM como juiz”, queremos dizer que o próprio agente de linguagem lê cada aresta amostrada em comparação com o código-fonte real e a classifica com uma rubrica fixa de cinco categorias: essa aresta está correta, é um falso positivo, é o relacionamento certo com o tipo errado, está anexada ao escopo errado, ou carrega metadados errados? Essa rubrica é o jogo inteiro — “taxa de erro de 23%” não significa nada até você saber se são defeitos reais ou o juiz contando errado.

Corrija uma coisa, depois prove. Cada iteração muda exatamente um ativo editável, depois roda novamente contra um harness fixo e mantém a mudança apenas se o F1 melhorar e a reclassificação parecer melhor. Se não melhorar, ela é revertida. Nada de lote de edições especulativas, nada de “deveria estar melhor”. Uma mudança conquista o seu lugar ou desaparece. E quando uma correção se mantém, ela é promovida para a suíte de fixtures — para que o bug que ela corrigiu nunca possa voltar silenciosamente. Essa etapa de promoção é o que torna o loop recursivo, e não apenas repetitivo: cada passagem fortalece o oráculo usado como referência para a validação seguinte.

A lição que continuamos reaprendendo: as métricas superestimam

Eis a armadilha, e caímos direto nela. As métricas secundárias do corpus — com que frequência um alvo extraído não tem símbolo resolvível, quantos símbolos parecem “órfãos”, e assim por diante — superestimam problemas massivamente. Na maioria das vezes, são artefatos de paradigma, não bugs.

O exemplo mais claro: llvm certa vez mostrou uma taxa de 73% de “origem sem símbolo” e foi rotulado como catastrófico. Investigamos. A acurácia real era de 98,5%. Os “símbolos ausentes” eram quase todos referências externas legítimas — chamadas para a biblioteca padrão, para frameworks, para código que vive fora do repositório. A métrica estava medindo uma propriedade da linguagem, não um defeito no handler. Linguagens como Zig, COBOL e Odin mostram taxas de “órfãos” de 65–70% e estão inteiramente corretas; COBOL não tinha erros reais.

Se tivéssemos deixado esses números guiarem o trabalho, teríamos gastado semanas “corrigindo” handlers que já estavam certos e ignorando as linguagens com bugs reais e silenciosos. A conclusão é direta: as métricas agregadas são, na melhor das hipóteses, um sinal aproximado de triagem. O verdadeiro sinal de qualidade é a verificação pontual com classificação de arestas — olhar para arestas reais em repositórios reais e julgá-las uma a uma. Dados acima da intuição, mas só depois que você sabe quais dados estão dizendo a verdade.

O loop externo: uma frota, não uma maratona

Uma linguagem de cada vez levaria uma eternidade em 280 delas, então o loop interno é envolvido por um loop externo que roda muitas em paralelo.

   pick a wave of near-GREEN / high-error languages
        │
        ▼
   fan out 10–15 agents, each ISOLATED in its own git worktree,
   each grinding ONE language, committing to its own branch
        │
        ▼
   orchestrator integrates serially: file-scoped apply, then
   `manifest diff` — any cross-language regression blocks the batch
        │
        ▼
   gated push (reviewed and confirmed) ──► rotate to the next wave

Cada agente trabalha em um worktree descartável, para que não pisem uns nos outros. O orquestrador integra as correções deles uma de cada vez, cada uma condicionada a uma verificação de regressão de manifesto completo: uma mudança que ajuda a sua própria linguagem, mas silenciosamente quebra três outras, não é integrada. A integração passa por um controle de validação e é confirmada antes de qualquer coisa ser enviada — o controle de regressão decide o que é seguro, um humano ainda decide o que vai para produção. Depois o pool gira para o próximo conjunto de linguagens e tudo roda de novo.

O que ainda é imperfeito

O juiz pode errar, e o erro tem uma direção: um agente rodando com contexto insuficiente superestima. Em um lote, oito linguagens foram sinalizadas com 5–20% de erro; na inspeção, apenas uma dessas linguagens tinha um bug real — o resto eram erros do juiz por não captar a semântica própria da linguagem (uma linha de origem legitimamente emitindo várias arestas, vinculações de parâmetro modeladas como atribuições, linguagens com referência por identificador). É por isso que amostramos com duas seeds e fazemos verificação cruzada, e por que uma discordância entre o juiz e as fixtures é tratada como o sinal mais interessante, não como um veredito definitivo — às vezes a fixture é o que está errado.

Também somos honestos sobre a meta. O objetivo é zero erros reais, ponto final — mas “zero” é uma direção rumo à qual refinamos, linguagem por linguagem, não uma caixa que se marca. Sempre há outro repositório com outro padrão idiomático.

Conquistado, Não Afirmado

Tudo o que o Maguyva faz por um agente — encontrar um símbolo, rastrear uma dependência, responder a uma pergunta com código citado — depende de a extração por baixo estar certa. Em 280 linguagens, “certo” não pode ser afirmado; precisa ser continuamente conquistado contra código real. O loop é como conquistamos isso: um ciclo autônomo de verificação pontual e correção que trata as próprias métricas com suspeita, prova cada mudança e transforma cada correção em uma guarda contra a próxima regressão. Não é glamouroso. É o trabalho que nos permite dizer “damos suporte à sua linguagem” e cumprir essa promessa. Verde é fácil. Correto é conquistado.

Busca com Fusão Multimodal: Escolhendo o Retriever Certo Para Cada Consulta

Wed, 15 Apr 2026 00:00:00 GMT

Nota sobre o projeto histórico: este artigo de abril de 2026 descreve o projeto de roteamento daquela época, não o comportamento padrão atual. A correção de setembro abaixo trata apenas de uma afirmação sobre medição. Para conhecer o roteamento atual, as predefinições e os controles explícitos de modalidade, veja Como funciona.

Uma consulta de busca não é uma coisa só.

“onde parseConfig é definido” quer um símbolo exato — um local preciso, rápido. “como funciona a autenticação” quer significado — o conjunto espalhado de código relacionado que explica um conceito. “o que quebra se eu mudar esta função” quer o grafo de dependências. “encontre a string ECONNREFUSED” quer uma correspondência literal, nada sofisticado.

O grep é excelente para correspondências literais e útil para algumas caças a referências, mas não é um grafo de dependências e não entende significado. Embeddings cobrem o lado semântico, mas são a ferramenta errada para strings exatas e análise de impacto. A maioria das ferramentas de busca de código escolhe um único motor e faz toda consulta conviver com essa escolha. O Maguyva não escolhe. Ele descobre que tipo de pergunta você fez, e então combina quatro retrievers na proporção que essa pergunta merece.

Quatro modalidades

Internamente, existem quatro formas independentes de encontrar código:

semantic — busca vetorial sobre embeddings binários da Voyage; encontra código por significado.
text — correspondência de trigramas; encontra literais, strings de erro, identificadores exatos.
structural — queries de AST; encontra definições, assinaturas e construções da linguagem.
graph — o grafo de dependências; encontra chamadores, chamados e raio de impacto.

Cada um é forte em uma classe diferente de pergunta. O truque é decidir o quanto confiar em cada um para a consulta que está na sua frente.

Classificação de intenção

Antes de qualquer retrieval rodar, um classificador leve classifica a consulta em uma de seis intenções, com uma pontuação de confiança. É deliberadamente barato — heurísticas ordenadas, a primeira correspondência vence — porque roda no caminho crítico e adiciona apenas um ou dois milissegundos:

começa com def , class , func , import … → find_definition (confiança 0,95)
“who calls”, “usages of”, “references to” (quem chama, usos de, referências a) → find_references (0,90)
“impact”, “blast radius”, “what depends on” (impacto, raio de impacto, o que depende de) → impact_analysis (0,90)
uma "string" entre aspas ou um token de erro como traceback → exact_match (0,85–0,90)
um identificador CamelCase ou snake_case → find_definition (0,60–0,80)
“how”, “why”, “explain”, “architecture” (como, por que, explique, arquitetura) → understand_code (0,75)
nada corresponde → understand_code, baixa confiança (0,40)

Cada intenção carrega um perfil de peso entre as quatro modalidades. Estes são os números reais:

Intenção	semantic	text	structural (AST)	graph
find_definition	0,2	0,1	0,6	0,1
find_references	0,1	0,2	0,2	0,5
understand_code	0,5	0,2	0,2	0,1
find_similar	0,4	0,3	0,2	0,1
impact_analysis	0,1	0,1	0,1	0,7
exact_match	0,0	0,9	0,1	0,0

Então “onde parseConfig é definido” se apoia fortemente em AST (0,6). “como funciona a autenticação” se apoia em vetores semânticos (0,5). “o que depende disso” é quase todo graph (0,7). “encontre ECONNREFUSED” é quase todo trigrama (0,9), com o modelo de embedding completamente desligado — porque similaridade semântica é exatamente a ferramenta errada para uma string exata.

O caminho rápido, e o caminho fundido

Quando o classificador está confiante — pontuação ≥ 0,85 — e a consulta é normal, o Maguyva pula a fusão por completo e roteia direto para a única modalidade dominante. “onde X é definido” não precisa de quatro retrievers; precisa do índice de AST, agora. Esse caminho direto é reportado de volta como fusion_strategy: "direct".

Tudo que é ambíguo passa pela fusão. As quatro (ou três, no preset padrão) modalidades rodam em paralelo, cada uma retornando sua própria lista ranqueada, e nós as combinamos.

Reciprocal Rank Fusion Ponderada

Fundir retrievers heterogêneos é mais difícil do que parece: uma similaridade de cosseno de 0,82, uma pontuação de trigrama de 137 e uma centralidade de grafo de 0,004 não estão na mesma escala, então você não pode simplesmente somá-las. O Reciprocal Rank Fusion contorna o problema descartando as pontuações brutas e mantendo apenas o rank que cada motor atribuiu. A contribuição de um resultado vinda de uma modalidade é:

contribution = weight × 1 / (k + rank + 1)

onde rank é a posição dele na lista daquela modalidade e k é uma constante de suavização. As contribuições são somadas entre modalidades para qualquer resultado que mais de um motor encontrou — a concordância entre retrievers naturalmente sobe ao topo. Usamos k = 40 no preset padrão e 60 em thorough (quick roda apenas com semantic, então a fusão nunca entra em ação ali). O trabalho original de RRF chegou a k = 60 para retrieval de propósito geral; nosso padrão enfatiza um pouco mais as primeiras posições, dando mais peso aos resultados que aparecem bem classificados em várias modalidades — e não recomendamos ajustá-lo manualmente.

Além disso, os resultados carregam um boost de importância de grafo. Um hub — uma função em que todo o codebase se apoia — deve superar em ranking um nó-folha pouco conhecido mesmo com a mesma relevância textual, então multiplicamos cada contribuição por:

boost = min(1 + 0.3 × ln(1 + centrality), 1.5)

A centralidade vem das métricas pré-computadas de PageRank/grau do pipeline, e o boost é limitado a 1,5× para que uma função popular não consiga sepultar completamente uma obscura mais relevante. Por fim, rebaixamos resultados de caminhos de dependências externas, artefatos de build e conteúdo arquivado, e removemos duplicatas mantendo o melhor chunk por arquivo.

O que ainda é imperfeito

O classificador de intenção é uma pilha de regexes, não um modelo aprendido. Ele trata os formatos comuns de consulta com heurísticas, e uma consulta ambígua recorre a understand_code e a uma combinação com maior peso semântico. Uma versão anterior deste artigo descreveu como alcançada uma redução da taxa de consultas sem resultados de aproximadamente 15% para menos de 5%. Na verdade, a proposta de dezembro de 2025 apresentava uma estimativa inicial e uma meta; não foi fornecido um conjunto de consultas nem um registro de medição que sustentasse essa redução. Retiramos essa afirmação de melhoria alcançada; veja as evidências de origem e a correção (em inglês). Não substituímos o classificador por um modelo treinado porque a versão de baixo custo é rápida e boa o suficiente para a função de roteamento pretendida, e porque um classificador errado, mas confiante, é pior do que uma alternativa honesta. Os pesos em si são valores a priori escolhidos manualmente, não aprendidos a partir de dados de cliques que não coletamos.

Faça a Pergunta, Não a Ferramenta

Um agente não deveria precisar saber se deve recorrer ao grep, a embeddings ou ao call graph — ele deveria fazer a sua pergunta em termos simples e obter a resposta certa. A fusão multimodal é o que permite que find_symbol, busca semântica e análise de dependências fiquem por trás de uma única interface de consulta: o sistema lê o formato da pergunta e silenciosamente monta o retriever certo para ela. O modelo que pontua os embeddings importa, mas também importa saber quando não usá-los. Escolher a ferramenta certa para cada consulta é um tipo de qualidade em si, e é algo que preferimos assumir a empurrar para quem chama.

// you bring the question. it brings the tools.

Observabilidade de Agentes: Hooks, Alloy e Grafana

Tue, 24 Mar 2026 00:00:00 GMT

Sistemas de agentes falham de formas estranhas.

Às vezes o modelo é o problema. Às vezes a ferramenta é o problema. Às vezes o seu servidor MCP está bem, mas o agente escolheu o especialista errado, ou passou metade da sessão fazendo trabalho de shell que você não esperava, ou consumiu orçamento silenciosamente em um loop que parecia produtivo visto de fora.

Se você não consegue ver a diferença, não está realmente operando um sistema de agentes. Está apenas chutando.

Então construímos uma stack de observabilidade para o nosso próprio fluxo de trabalho: Claude Code, Codex, eventos de hook do Claude, eventos de notify do Codex, OpenTelemetry nativo, Grafana Alloy e Grafana Cloud do outro lado.

A parte interessante não é “fizemos um dashboard”. A parte interessante é que tivemos que dividir a telemetria em dois streams diferentes porque nenhum feed único nos dava o quadro completo.

O Problema: a Telemetria de Agentes É Fragmentada

Agentes de codificação modernos já emitem alguma telemetria. Isso ajuda, mas não é suficiente.

O OTEL nativo é bom em responder perguntas como:

Quantas requisições fizemos?
Quanto custou uma sessão?
Onde estão os spans e traces?
A latência teve um pico?

Ele é muito pior em responder perguntas como:

Em qual servidor MCP o agente se apoiou?
Essa falha foi em Bash, em uma ferramenta de arquivo nativa ou em uma chamada MCP?
Qual skill realmente ativou?
Que tipo de subagente foi despachado?
A sessão estava fazendo trabalho útil ou apenas se debatendo?

Essa segunda classe de pergunta vive mais perto dos hooks do que dos traces.

Mas o inverso também é verdadeiro: algumas das perguntas de performance mais importantes vivem mais perto dos traces do que dos hooks.

Se você quer saber onde a latência realmente se acumulou, quais spans estavam lentos, ou se a sessão queimou tempo em chamadas de modelo versus execução de ferramentas, você precisa de dados de trace tanto quanto de eventos semânticos.

A Arquitetura a Que Chegamos

Rodamos dois caminhos de telemetria lado a lado.

Claude Code
  native OTEL -> Alloy -> Grafana Cloud
  hooks        -> send_event.py -> Grafana Cloud Loki

Codex
  native OTEL -> Alloy -> Grafana Cloud
  notify hook -> codex_notify.py -> shared Loki schema

Essa divisão é deliberada.

Ela também é assimétrica. O Claude Code nos dá uma interface de hooks de ciclo de vida muito mais rica. O Codex nos dá OTEL nativo mais uma interface de notify, então normalizamos eventos de conclusão de turno menos detalhados no mesmo schema de log, em vez de fingir que os dois runtimes expõem os mesmos controles.

O OTEL nativo nos dá o stream de base: logs e traces do próprio runtime, mais métricas onde o runtime realmente as emite.

Eventos de hook e notify nos dão a camada semântica: coisas como PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated, e os metadados classificados com os quais realmente nos importamos ao depurar o comportamento dos agentes. O Claude Code contribui aqui com o stream de eventos mais rico. O Codex contribui com um stream normalizado menos detalhado, mas ainda útil.

Por Que os Hooks Existem

Nosso pipeline de hooks enriquece eventos antes de chegarem ao Loki.

Em vez de apenas dizer “uma ferramenta rodou”, classificamos o evento em campos como:

tool_type: builtin, mcp, skill, agent, bash
mcp_server: qual backend MCP tratou a chamada
bash_cli: a família do comando de shell
subagent_type: que tipo de especialista foi despachado
agent_tool: se a origem foi o Claude Code ou o Codex

Isso significa que podemos fazer perguntas que importam operacionalmente:

{service_name="claude-code-hooks"} | agent_tool="codex-cli"
{service_name="claude-code-hooks"} | tool_type="mcp"
{service_name="claude-code-hooks"} | json | bash_cli="git"

Esses não são campos de vaidade. Eles são a diferença entre “o agente pareceu lento” e “o agente passou os últimos dez minutos em operações de git pesadas em shell com alta taxa de falha de ferramentas”.

Um detalhe de implementação que parece mais estranho do que é: o stream compartilhado do Loki ainda usa service_name="claude-code-hooks" como label mesmo quando o evento vem do Codex. A divisão real entre runtimes acontece em agent_tool.

Por Que o Alloy Fica no Meio

O Grafana Alloy não é apenas um encaminhador nesta configuração. Ele é o ponto de aplicação de políticas.

Apontamos o stream de OTEL nativo do Claude Code e do Codex para um proxy Alloy local em localhost:4318, e então deixamos o Alloy limpar o payload antes de encaminhá-lo para o Grafana Cloud.

Isso importa porque a telemetria bruta de agentes está cheia de campos de alta cardinalidade que são úteis para análise, mas terríveis como labels indexados:

session_id
prompt_id
contagens de tokens
durações
blobs de parâmetros de ferramentas

Se você indexar tudo, você tem uma explosão de labels e um dia ruim.

Então o Alloy faz três coisas por nós:

Mantém indexado um conjunto muito pequeno de labels de baixa cardinalidade.
Move campos ruidosos, mas úteis, para metadados estruturados.
Descarta ruído puro por completo.

A ideia importante é simples: observe mais, indexe menos.

Por Que o Stream de Hooks Contorna o Alloy

O stream de hooks já vem formatado para o Loki.

No momento em que send_event.py envia um evento, já decidimos quais campos merecem tratamento de label e quais pertencem ao corpo JSON estruturado. Esse stream vai direto para o gateway OTLP do Grafana Cloud, em vez de passar novamente pelo Alloy.

Então o sistema tem uma divisão de trabalho clara:

O Alloy doma o stream bruto de OTEL nativo.
O enriquecimento de hooks torna os eventos semânticos consultáveis.

Isso mantém a arquitetura mais simples do que tentar forçar tudo por um único caminho.

O Que o Dashboard Realmente Mostra

A captura de tela abaixo é de um dos dashboards de observabilidade por trás do nosso fluxo de trabalho de agentes. Não é um benchmark, e os números são apenas um recorte de um momento específico. O ponto é o formato dos dados: feed de atividade, chamadas de ferramentas, falhas, prompts, e detalhamentos por agente, ferramentas nativas, uso de MCP, comandos de shell e skills.

A parte útil é que esse dashboard vive na mesma stack do Grafana que o restante da telemetria de agentes. Podemos filtrar por agente de origem e família de ferramenta, e olhar entre runtimes sem inventar uma história de observabilidade diferente para cada sistema.

Um dos dashboards ao vivo por trás do nosso fluxo de trabalho de agentes. Esta captura de tela é apenas um recorte de uma stack compartilhada do Grafana que também recebe telemetria dos nossos outros runtimes e sistemas de agentes. Clique na imagem para a versão em resolução completa.

Por Que os Traces Importam Mais do que Parecem à Primeira Vista

Logs nos dizem que categoria de trabalho aconteceu. Traces nos dizem como o trabalho se desenrolou ao longo do tempo.

Essa distinção importa em sistemas de agentes porque “lento” é grosseiro demais para ser útil.

Um trace pode nos dizer se a dor veio de:

latência do modelo
tempo de execução de ferramentas
retries repetidos
uma interação MCP especialmente cara
uma longa cauda de pequenas operações que pareciam inofensivas isoladamente

Na prática, usamos o stream de hooks e os traces do Tempo juntos.

Os logs de hook respondem: que tipo de coisa aconteceu?
Os traces respondem: para onde foi o tempo?

A combinação é o que transforma a observabilidade de um dashboard em uma explicação.

Onde o Codex se Encaixa

O Codex faz parte da mesma stack, mas não é idêntico ao Claude Code.

Para o Codex, conectamos duas peças:

OTEL nativo do Codex para o Alloy
Um webhook de notify para codex_notify.py, que mapeia conclusões de turno para o mesmo schema do Loki que usamos para eventos de hook

Isso nos dá um filtro unificado como agent_tool="codex-cli" dentro do mesmo stream de logs.

A ressalva honesta: o payload de notify do Codex hoje é menos detalhado do que o payload de hook do Claude Code, porque não é o mesmo tipo de interface de integração. Na nossa configuração atual, as conclusões de turno do Codex podem ser normalizadas para o schema compartilhado, mas a extração rica ferramenta por ferramenta ainda é melhor no stream de OTEL nativo do que na bridge de notify.

Isso não é motivo para evitar o post. É o ponto do post. Sistemas de observabilidade reais são montados a partir de sinais imperfeitos.

O Grafana Sobre MCP Muda o Jogo

A mudança maior é que o Grafana não é apenas um lugar que humanos visitam em um navegador.

Neste repositório, também expomos o Grafana via MCP. Isso significa que um agente pode consultar o Loki, o Prometheus e o Tempo diretamente, em vez de esperar que um humano inspecione manualmente os dashboards primeiro.

Isso transforma a observabilidade em uma entrada ativa do fluxo de trabalho.

Um agente pode perguntar:

Quais famílias de ferramentas falharam mais na última hora?
Qual servidor MCP dominou uma sessão?
As mudanças recentes reduziram as falhas de ferramentas ou apenas moveram o trabalho para caminhos mais pesados em shell com os mesmos erros?
Quais traces mostram a maior latência ou retries repetidos?

Quando você tem isso, está muito perto de um loop de autoaperfeiçoamento.

Do Dashboard ao Loop de Feedback

Esta é a parte que achamos mais interessante.

Assim que a stack de observabilidade se torna consultável a partir da camada de agentes, a telemetria deixa de ser uma tela passiva de relatórios e se torna um sinal de controle.

O loop funciona assim:

A atividade dos agentes emite traces, métricas e logs de hook enriquecidos.
O Grafana armazena a evidência no Loki, no Tempo e no Prometheus, onde existem métricas.
Os agentes consultam essa evidência através do Grafana MCP.
O sistema identifica mix ruim de ferramentas, skills frágeis, roteamento fraco ou fluxos de trabalho pesados em shell que continuam produzindo erros evitáveis.
Agentes ou operadores ajustam prompts, configurações de agente, descrições de skills, regras de roteamento ou acesso a ferramentas.
A próxima sessão produz um novo formato de telemetria, e o ciclo se repete.

É assim que você passa de “dashboard interessante” para “sistema de melhoria mensurável”.

O objetivo não é maximizar uma categoria de ferramenta. É chegar à combinação certa de CLI, ferramentas nativas, chamadas MCP e skills para o trabalho que está realmente sendo feito.

O Que Isso Nos Permite Responder

Assim que os dois runtimes chegam à mesma stack do Grafana, conseguimos responder perguntas operacionais muito mais rápido:

As falhas estão concentradas em uma família de ferramentas?
Fluxos de trabalho pesados em shell estão criando erros evitáveis onde deveria existir uma ferramenta de nível mais alto?
Quais servidores MCP estão carregando a maior parte do trabalho?
Estamos pagando por atividade de agente que não está produzindo progresso significativo?
Uma sessão apresenta problemas por causa do modelo, das ferramentas ou da camada de orquestração?

Isso é especialmente útil em fluxos de trabalho multiagente, em que “o agente estava ocupado” não diz quase nada.

Se um especialista continua sendo despachado e produzindo altas taxas de falha, isso é um problema de roteamento ou de moldagem de prompt.

Se um servidor MCP domina todas as chamadas, isso pode ser boa arquitetura ou um sinal de que todo o resto é peso morto.

Se as falhas de ferramentas disparam enquanto o custo permanece alto, você tem um problema operacional, não um problema de qualidade.

Se o trabalho de shell continua falhando de formas previsíveis e evitáveis onde deveria existir uma ferramenta de nível mais alto, isso é um sinal de produto.

Se uma skill ativa constantemente, mas não melhora os resultados, isso é um sinal de prompt ou de roteamento.

A Lição Real

A lição mais profunda aqui é que a observabilidade de agentes precisa tanto de telemetria de runtime quanto de telemetria de fluxo de trabalho.

A telemetria de runtime diz o que o sistema fez.

A telemetria de fluxo de trabalho diz o que o agente achava que estava fazendo.

Precisamos das duas.

Se você mantém apenas traces e contadores, perde a camada semântica. Se você mantém apenas eventos de hook, perde latência, spans e o panorama mais amplo do runtime.

E se você mantém os dois, mas nunca os realimenta na camada de agentes, você tem monitoramento, não adaptação.

A combinação é o que torna o sistema explicável o suficiente para operar e ajustável o suficiente para melhorar.

O Que Ainda É Imperfeito

Ainda há arestas a aparar.

Nem todo evento de hook inclui os dados de duração e de tokens que gostaríamos.
Algumas das melhores visões de tempo ainda vêm dos traces do Tempo, não dos logs de hook.
O Codex hoje é semanticamente menos rico do que o Claude Code no stream de eventos enriquecido.
A captura de tela do dashboard é uma tela de operações em tempo real, não uma peça de marketing polida.

Esse último ponto é intencional. Preferimos mostrar o painel de instrumentos real a fingir que sistemas de agentes se explicam magicamente.

Por Que Isso Importa Para o Maguyva

O Maguyva é sobre dar aos agentes uma inteligência de código melhor. Mas assim que os agentes realmente começam a fazer trabalho útil, um novo requisito aparece imediatamente: você precisa ver como eles estão se comportando.

Qualidade de busca, qualidade de roteamento, seleção de ferramentas e eficiência de contexto, tudo isso se torna um problema observável.

É por isso que achamos que vale a pena escrever sobre isso. A pilha de agentes do futuro não é só prompts e ferramentas. Ela reúne prompts, ferramentas e a camada de instrumentação que diz se tudo isso está funcionando.

Se você está construindo fluxos de trabalho de agentes sérios, observabilidade não é infraestrutura opcional. É parte do produto.

Minerando o Loop: Como Mudanças Se Tornam Memória Institucional

Tue, 03 Feb 2026 00:00:00 GMT

Os números neste post refletem o sistema no momento da publicação (fevereiro de 2026). Consulte nossa página da equipe para números atualizados.

Toda equipe de engenharia enfrenta o mesmo desafio: mudanças acontecem o tempo todo, mas o porquê por trás dessas mudanças desaparece. Seis meses depois, alguém pergunta “por que adotamos o DuckDB para os stages do pipeline?” e a resposta vive apenas na cabeça de quem tomou essa decisão — se essa pessoa ainda estiver por perto.

Construímos um fluxo de trabalho de mineração que fecha esse loop. As mudanças fluem através de commits do git, são processadas pelo nosso pipeline de mineração, tornam-se entradas estruturadas de changelog e registros de decisões arquiteturais, e depois realimentam nossos agentes de IA através de consultas de CLI. O resultado: memória institucional que tanto humanos quanto IA podem acessar.

O Problema: Decisões Evaporam

Considere um cenário típico. Um desenvolvedor faz um commit:

feat(canonical): add DuckDB runtime for pipeline stages

Esse commit representa uma escolha arquitetural significativa. A equipe avaliou opções, considerou trade-offs e chegou ao DuckDB por razões específicas. Mas todo esse contexto vive em:

Uma thread do Slack (provavelmente apagada)
A memória de alguém (definitivamente enfraquecendo)
Um comentário no código (talvez, se você tiver sorte)

Três meses depois, um novo membro da equipe pergunta: “devo usar DuckDB ou SQLite para esse novo stage?” Sem memória institucional, essa pessoa ou reinventa a roda ou faz escolhas inconsistentes.

O Loop: dos Commits ao Contexto

Nosso fluxo de trabalho de mineração transforma o histórico do git em conhecimento consultável:

Git Commits
    │
    ▼
┌─────────────────────┐
│  mine sync          │  ← Build index from git history
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  mine candidates    │  ← Surface commits for review
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Classification     │  ← Human or LLM assessment
│  (changelog or ADR) │
└─────────────────────┘
    │
    ├──────────────────────┐
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ Changelog   │    │ Decisions     │
│ Ledger      │    │ Registry      │
│ (JSONL)     │    │ (YAML files)  │
└─────────────┘    └───────────────┘
    │                      │
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ CHANGELOG.md│    │ orkestra CLI  │
│ per package │    │ queries       │
└─────────────┘    └───────────────┘
    │                      │
    └──────────────────────┘
              │
              ▼
      ┌───────────────┐
      │ AI Agents     │
      │ (via CLI)     │
      └───────────────┘

O insight central: tanto os changelogs quanto as decisões arquiteturais fluem do mesmo histórico do git, processado por um pipeline unificado. Isso garante que nada escape pelas frestas.

Como a Mineração Funciona

Etapa 1: Sincronizar o Índice

uv run orkestra mine sync

Esse comando varre o histórico do git e constrói um índice de todos os commits. Ele extrai sinais estruturados de cada commit:

Tipo segundo a convenção Conventional Commits (feat, fix, chore, docs)
Escopo (qual pacote ou área)
Marcadores de breaking change
Arquivos alterados e métricas de complexidade

Etapa 2: Verificar o Status de Cobertura

uv run orkestra mine status

É assim que o nosso status atual se parece:

Mining Status
=============

Decisions
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Extracted:       476
    Skipped:       15161

Changelog
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Released:       6799
    Skipped:        8838

15.637 commits processados. 476 se tornaram decisões arquiteturais. 6.799 se tornaram entradas de changelog. Todo commit classificado.

Etapa 3: Obter Candidatos para Revisão

uv run orkestra mine candidates --limit 50 --full

Isso traz à tona commits que ainda não foram processados, com contexto completo para classificação:

{
  "sha": "90571786d99166c0039ca2e80e4d9cd96184bd85",
  "date": "2026-01-26",
  "subject": "feat(canonical): add DuckDB runtime for pipeline stages",
  "signals": {
    "commit_type": "feat",
    "scope": "canonical",
    "breaking": false,
    "is_releasable_type": true,
    "domains_affected": ["pipeline", "data-architecture"]
  },
  "body": "Establishes DuckDB as canonical in-process analytical database...",
  "files_changed": ["packages/canonical/pipelines/stages/duckdb_runtime.py", "..."],
  "stats": {"files": 8, "insertions": 450, "deletions": 120}
}

Os sinais ajudam a guiar a classificação: is_releasable_type: true sugere que isso deveria aparecer no changelog. A grande contagem de inserções e os arquivos de infraestrutura sugerem que também pode ser uma decisão arquitetural.

Etapa 4: Classificar Commits

Dois caminhos se separam aqui: entradas de changelog e decisões arquiteturais.

Para entradas de changelog:

uv run orkestra mine classify abc123 --changelog added

Isso registra que o commit abc123 deve aparecer no changelog na categoria “Added”.

Para decisões arquiteturais:

Primeiro, obtenha um ID de decisão real:

uv run orkestra registry decisions new --domain pipeline --dry-run
# Returns: DEC-PL-143

Depois classifique com o ID da decisão:

uv run orkestra mine classify abc123 --decision DEC-PL-143

Isso vincula o commit a um registro de decisão que será criado ou atualizado.

Para processamento em lote (o que fazemos na prática):

# Generate classifications file with LLM assistance
uv run orkestra mine commit --input classifications.jsonl

O formato JSONL suporta ambos os domínios em uma única passagem:

{"sha":"abc123","domain":"changelog","action":"release","category":"added","summary":"Add DuckDB runtime for pipeline stages"}
{"sha":"abc123","domain":"decisions","action":"extract","decision_id":"DEC-PL-142"}
{"sha":"def456","domain":"changelog","action":"skip","reason":"Chore: dependency update"}

Etapa 5: Renderizar as Saídas

uv run orkestra registry changelog render --package <pkg>

Isso gera arquivos CHANGELOG.md por pacote a partir do ledger. Os changelogs são artefatos derivados — apague-os e eles se regeneram perfeitamente a partir do ledger de origem.

A Estrutura do Registro de Decisão

As decisões extraídas se tornam arquivos YAML com metadados ricos:

id: DEC-PL-142
title: Adopt DuckDB as Canonical Processing Runtime for Pipeline Stages
domain: pipeline
status: active
created: '2026-01-26'
summary: |
  Establishes DuckDB as the canonical in-process analytical database for pipeline
  stage transformations. Provides a shared runtime module that resolves settings
  from pipeline defaults with stage-level overrides.

context: |
  Pipeline stages performing data transformations each independently configured
  DuckDB connections. This led to inconsistent settings, duplicated configuration
  code, and no way to tune DuckDB globally for a pipeline run.

rationale:
  - DuckDB provides efficient in-process OLAP with zero configuration deployment
  - Centralized runtime module eliminates duplicated DuckDB setup across stages
  - Hierarchical settings enable global tuning with stage-level overrides
  - Memory limits and thread counts can be adjusted per-pipeline

impact:
  positive:
    - Consistent DuckDB configuration across all pipeline stages
    - Single point of control for memory/thread tuning
    - Reduced code duplication in conversion and export stages
  negative:
    - Adds dependency on shared runtime module
    - Stages must adopt new configuration pattern

source_commits:
  - sha: 90571786d99166c0039ca2e80e4d9cd96184bd85
    message: 'feat(canonical): add DuckDB runtime for pipeline stages'
    date: '2026-01-26'
    role: primary

files:
  - packages/canonical/pipelines/stages/duckdb_runtime.py
  - packages/canonical/pipelines/runner.py
  - packages/canonical/pipelines/stages/convert_hdx_admin_boundaries_to_geoparquet.py

related:
  - DEC-DA-014  # Data architecture decisions that influenced this

Toda decisão remete de volta aos seus commits de origem. Toda decisão especifica quais arquivos ela afeta. Os relacionamentos entre decisões são explícitos.

Integração com a CLI: Consultando a Memória Institucional

É aqui que o loop se fecha. Os agentes podem consultar decisões através da CLI:

# Search by topic
uv run orkestra registry decisions search --query "retry"

Retorna decisões sobre lógica de retry, tratamento de erros, padrões de recuperação.

# Get full details on a specific decision
uv run orkestra registry decisions info DEC-PL-142

Retorna o registro de decisão completo com contexto, justificativa e impacto.

# List recent decisions for context
uv run orkestra registry decisions list --limit 15

Mostra quais escolhas arquiteturais foram feitas recentemente.

Como os Agentes Usam Isso

As instruções de base do nosso orquestrador incluem:

**Essential CLI commands:**
- `orkestra registry decisions search "X"` — Find architectural decisions

Quando um agente recebe a tarefa de implementar algo relacionado ao DuckDB, ele pode primeiro checar:

uv run orkestra registry decisions search --query "DuckDB"

E descobrir a DEC-PL-142, aprendendo:

Por que escolhemos o DuckDB (context)
Como usá-lo corretamente (agent_guidance)
Quais arquivos examinar (files)
Quais decisões relacionadas existem (related)

O agente não reinventa a roda. Ele constrói sobre padrões já estabelecidos.

O Teste das Três Perguntas

Nem todo commit merece um registro de decisão. Usamos o Teste das Três Perguntas para filtrar:

Isso foi difícil de decidir? Exigiu análise significativa, avaliação de trade-offs ou debate?
É custoso de mudar? Reverter essa decisão exigiria retrabalho significativo?
Tem impacto em todo o sistema? Afeta múltiplos pacotes ou estabelece padrões que outros vão seguir?

Se um commit responde “sim” a pelo menos uma dessas perguntas, ele é candidato à extração de decisão. Nossa taxa típica: 1 a 4 decisões a cada 100 commits (cerca de 1–4%).

Para entradas de changelog, a barra é mais baixa: qualquer mudança visível ao usuário (funcionalidades, correções, melhorias) é registrada. Tarefas internas, atualizações de documentação e refatorações costumam ser ignoradas. Nossa taxa típica: 30 a 50 entradas de changelog a cada 100 commits.

Armazenamento de Dados: Ledgers Somente-Anexação

O sistema de mineração usa ledgers JSONL somente-anexação para operação multiagente sem conflitos:

packages/orchestration/ai_assets/reference/changelog/
├── commits_processed.jsonl  # Classification ledger (both domains)
├── release_notes.jsonl      # Changelog entries
└── commits_index.yaml       # Derived index (gitignored)

packages/orchestration/ai_assets/reference/decisions/
├── registry.yaml            # Decision index
└── records/
    ├── DEC-AD-001.yaml
    ├── DEC-AD-002.yaml
    └── ...

O formato JSONL com merge=union em .gitattributes significa que vários agentes podem classificar commits simultaneamente sem conflitos de merge. Cada linha é independente.

Controles de Validação

Antes de qualquer sessão de mineração, rodamos validação:

uv run orkestra mine validate --quick

Isso verifica:

Validade do formato do SHA
Conformidade do formato do ID de decisão
Ausência de entradas duplicadas para o mesmo SHA
Se as decisões referenciadas realmente existem

Após a classificação, validamos novamente antes de fazer commit das mudanças.

Por Que Isso Importa

O loop de feedback que construímos resolve vários problemas:

Para novos membros da equipe: em vez de perguntar “por que fizemos X?”, eles podem buscar no registro de decisões. O contexto é preservado.

Para agentes de IA: eles não operam no vácuo. Podem consultar conhecimento institucional antes de fazer recomendações. Quando solicitados a adicionar um novo stage de pipeline, podem descobrir o padrão do DuckDB e segui-lo.

Para consistência arquitetural: as decisões são explícitas e pesquisáveis. Quando alguém propõe uma abordagem que contradiz uma decisão existente, o sistema pode revelar o conflito.

Para a geração de changelog: as notas de release não são uma correria de última hora. São um subproduto da classificação contínua durante o desenvolvimento.

Para onboarding: novos agentes herdam o contexto completo do codebase. Eles não veem apenas o código — veem as decisões que o moldaram.

Estado Atual

Atualmente:

15.637 commits processados pelo pipeline
476 decisões arquiteturais extraídas e documentadas
6.799 entradas de changelog registradas
100% de cobertura em ambos os domínios

Todo commit desde que começamos foi classificado. A memória institucional está completa e é consultável.

Começando

Se você quer implementar algo parecido:

Comece com a convenção Conventional Commits. O pipeline de mineração funciona melhor quando os commits têm prefixos estruturados (feat:, fix:, chore:).
Defina os seus domínios. Usamos domínios como pipeline, agent-design, observability, data-modeling. Eles organizam as decisões por área.
Construa o hábito de classificação. A mineração funciona quando as equipes classificam commits regularmente. O processamento em lote com assistência de LLM ajuda a escalar.
Torne as decisões consultáveis. O valor se acumula quando os agentes podem buscar decisões via CLI. Estruture a sua saída para consumo por máquina.
Feche o loop. As decisões devem influenciar o trabalho futuro. Inclua referências a decisões nas instruções dos agentes e nas checklists de revisão de código.

O objetivo não é documentação perfeita. É tornar o porquê por trás das mudanças acessível tanto para humanos quanto para IA, hoje e daqui a seis meses. Quando as mudanças se tornam memória institucional, as equipes constroem sobre padrões estabelecidos em vez de reinventá-los.

O fluxo de trabalho de mineração é parte do nosso motor de orquestração, especificamente o módulo de motor de contexto no nosso pacote de orquestração.

Mineração de Skills: De 3.500 Candidatas a 466 Capacidades

Tue, 27 Jan 2026 00:00:00 GMT

Os números neste post refletem o sistema no momento da publicação (janeiro de 2026). Consulte nossa página da equipe para números atualizados.

O Problema das 3.500 Skills

Quando começamos a construir um sistema de orquestração de agentes, enfrentamos um desafio interessante: existem milhares de skills potenciais espalhadas pelo ecossistema de IA. Repositórios no GitHub, documentação de fornecedores, projetos de comunidade, padrões internos — skills existem em todo lugar. Mas quais realmente importam? Quais funcionam? E como você mantém uma biblioteca de skills coerente que os agentes conseguem realmente usar?

Nossa resposta: um loop sistemático de mineração e ingestão.

Os Números de Hoje

Pouco mais de três meses depois de a Anthropic lançar os Agent Skills em 16 de outubro de 2025, aqui está onde estávamos quando este post foi publicado, em 27 de janeiro de 2026:

Métrica	Quantidade
Candidatas identificadas	3.500+
Skills adotadas	466
Skills de fornecedores	373
Skills internas	93
Fornecedores ativos	25+
Tokens médios por skill	2.834
Ferramentas referenciadas	89
Tags únicas	635

Revisamos mais de 3.500 skills candidatas. Adotamos 466. Isso é uma taxa de adoção de 13% — e essa seletividade é proposital.

O Sistema de Camadas de Conhecimento

Nem todas as skills são criadas iguais. Nós as organizamos em cinco camadas de conhecimento (K0-K4), cada uma representando um escopo diferente de aplicabilidade:

K0: Fundamentos (Universal)

Skills que todo agente deveria ter. Elas representam capacidades de “bom pensador” que funcionam em qualquer lugar.

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

As skills K0 são portáteis para qualquer projeto, qualquer domínio, qualquer stack. Elas codificam padrões cognitivos universais.

K1: Identidades (Disciplina)

Skills de “bom engenheiro” ou “bom pesquisador” que se aplicam entre projetos dentro de uma disciplina.

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2: Domínios (Expertise no Assunto)

Skills de “bom especialista em banco de dados” ou “bom engenheiro de segurança” portáteis dentro de um campo.

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3: Stacks (Tecnologia)

Skills de “bom usuário do Supabase” ou “bom desenvolvedor Cloudflare” para stacks de tecnologia específicas.

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4: Projeto (Organização)

Skills específicas da nossa organização e dos nossos fluxos de trabalho.

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

O Loop de Mineração

Fase 1: Descoberta

As skills vêm de todo lugar:

Repositórios de fornecedores: AWS, Anthropic, Cloudflare, Supabase e colaboradores da comunidade publicam coleções de skills. Rastreamos mais de 25 raízes de fornecedores.

Projetos de comunidade: o GitHub está cheio de templates para Claude Code, padrões de agente e definições de fluxos de trabalho.

Padrões internos: à medida que a nossa equipe resolve problemas, padrões emergem. Eles são formalizados em skills.

Mineração de documentação: a documentação técnica frequentemente contém skills implícitas — procedimentos, checklists, árvores de decisão.

A descoberta é contínua. Usamos um backlog de skills para rastrear candidatas antes da avaliação formal.

Fase 2: Avaliação

Toda candidata passa pela mesma rubrica:

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

Os cinco critérios de produto precisam ser atendidos. É por isso que 87% das candidatas são rejeitadas.

Depois, toda candidata passa por uma revisão de confiança separada. Não tratamos um repositório oficial de fornecedor, um mantenedor de comunidade bem conhecido e um repositório aleatório do GitHub como fontes de verdade equivalentes.

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

Fornecedores confiáveis recebem uma revisão de proveniência mais leve, mas não um passe livre. Fontes não confiáveis ou desconhecidas recebem uma auditoria manual mais profunda, e não executamos scripts empacotados até que eles tenham sido lidos, delimitados em escopo e classificados como seguros.

Análise de lacunas: antes de adotar, buscamos no nosso registro:

uv run orkestra skills search "<capability>"

Se já temos, não precisamos dela. Se temos algo próximo, podemos mesclar em vez de adotar.

Pontuação de profundidade e padrões: também pontuamos o quão plenamente uma candidata usa o modelo agent-skill. Um único SKILL.md isolado ainda pode ser útil, mas skills mais profundas são mais valiosas quando separam instruções de referências, scripts e assets da forma que agentskills.io incentiva.

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

Estrelas no GitHub podem elevar um pouco a pontuação de credibilidade, mas nunca resgatam uma skill rasa ou insegura. Um repositório com muitas estrelas e um único SKILL.md vago com scripts opacos pontua abaixo de um repositório menor com uma descrição precisa, referências selecionadas em references/, e helpers atômicos que realmente aproveitam a capacidade completa do modelo de skill.

Análise estrutural: verificamos a qualidade da skill:

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

Se uma candidata inclui scripts, essa revisão fica mais rigorosa. Uma boa skill não é apenas útil; ela precisa ser legível, delimitada e segura para entregar a um agente. Só esse filtro de segurança já desqualifica uma fatia significativa de candidatas que, de outra forma, seriam interessantes.

Fase 3: Ingestão

Quando uma skill passa na avaliação, ela entra no registro. Mas skills nunca são adotadas sem alterações. Elas são modificadas para se encaixar no nosso sistema.

Modificações na adoção:

Normalização de metadados: toda skill recebe o nosso schema de frontmatter
Atribuição de camada K: as skills são colocadas na camada de conhecimento apropriada
Enriquecimento de tags: tags são adicionadas para descoberta
Declaração de ferramentas: as ferramentas permitidas são declaradas explicitamente
Alinhamento de seções: o conteúdo é reestruturado para corresponder ao nosso template

Um YAML de skill típico após a ingestão:

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

Fase 4: Atribuição de Escopo

As skills são atribuídas a escopos — categorias que determinam quais agentes carregam quais skills:

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

Os agentes declaram seus escopos, e as skills são atribuídas automaticamente:

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

Fase 5: Materialização

As skills não vivem como YAML em produção. Elas são renderizadas em arquivos SKILL.md que o Claude Code consegue carregar:

uv run orkestra sync

Esse comando:

Lê todas as definições YAML de skill
Renderiza-as através de templates Jinja
Escreve arquivos SKILL.md em .claude/skills/
Organiza por camada K (foundations/, identities/, domains/, stacks/, project/)

A estrutura de saída final:

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

O Padrão de Escopo Dormente

Um dos nossos padrões mais poderosos são as skills “adotadas mas não carregadas”. Chamamos isso de escopos dormentes.

Considere as skills de computação científica do repositório k-dense-scientific. Adotamos mais de 120 skills cobrindo bioinformática, química, computação quântica e informática clínica. Mas a maioria dos nossos agentes não precisa de docking molecular ou análise de expressão gênica.

Em vez de carregar todas as 120 skills em cada agente (inchando as janelas de contexto), nós:

Adotamos as skills com um escopo específico (por exemplo, bioinformatics)
Mantemos-nas dormentes — registradas, mas não carregadas
Habilitamos apenas quando um agente declara aquele escopo

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

Esse padrão nos permite ter 466 skills no registro, enquanto agentes típicos carregam apenas de 40 a 60 relevantes.

Tipos de Skill

As skills vêm em três padrões cognitivos:

Fluxo de trabalho

Passos procedurais ordenados: “1. Faça X, 2. Depois Y, 3. Por fim Z”

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

Disciplina

Barreiras comportamentais: “Sempre X”, “Nunca Y”, “Prefira Z”

type: discipline
# Examples: test-first-discipline, evidence-based-completion

Checklist

Critérios de verificação: “Confirme X”, “Verifique Y”, “Cheque Z”

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

Controles de Qualidade

Toda skill precisa passar por validação antes de ir para produção:

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

As descrições precisam ter de 50 a 400 caracteres com frases de acionamento (“Use quando…”, “Quando você precisar de…”) para que o Claude Code saiba quando sugeri-las.

Validamos continuamente:

uv run orkestra validate --show-warnings

O Ecossistema de Fornecedores

Nossas 373 skills de fornecedores vêm de:

Fornecedor	Skills	Domínio
AWS Agent	19	Serviços de nuvem
Anthropic	12	Geração de documentos
Cloudflare	8	Edge computing
Supabase	5	Banco de dados
k-dense	100+	Computação científica
silvainfm	4	Ciência de dados
Java Developer Kit	45+	Spring/Java
Vercel	1	Automação de navegador

Cada raiz de fornecedor é declarada em metadata.yaml:

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

Quando orkestra sync roda, as skills de fornecedores são vinculadas por links simbólicos em .claude/skills/vendor/ com o namespace do respectivo fornecedor.

O Que Aprendemos

Seletividade compensa. É tentador adotar tudo que parece útil. Mas cada skill custa tokens. Com uma média de 2.834 tokens por skill, o inchaço dói rápido. Nossa taxa de adoção de 13% mantém os agentes enxutos.

Estrutura viabiliza a descoberta. O sistema de camadas K não é só organização — é sobre portabilidade. Skills K0 podem ser reutilizadas em qualquer lugar. Skills K4 são intencionalmente específicas de projeto. Essa clareza ajuda tanto humanos quanto agentes a encontrar o que precisam.

Escopos dormentes escalam. Você pode adotar centenas de skills sem carregá-las todas. Escopos permitem construir um registro abrangente mantendo as janelas de contexto de cada agente gerenciáveis.

A modificação na adoção é essencial. Skills brutas de fornecedores raramente se encaixam no seu sistema. O processo de ingestão — adicionar metadados, atribuir camadas, enriquecer tags — faz skills externas funcionarem internamente.

A mineração é contínua. O número de 3.500 continua crescendo. Novos repositórios de fornecedores aparecem. Padrões de comunidade emergem. Fluxos de trabalho internos se solidificam. O loop nunca para.

O Que Vem a Seguir

Estamos trabalhando em várias melhorias:

Detecção automatizada de lacunas: alertar quando falhas comuns de agente poderiam ser resolvidas por uma skill ainda não adotada
Fluxos de trabalho de descontinuação de skills: processo formal para aposentar skills que foram substituídas ou não são usadas
Dependências entre skills: declaração explícita de pré-requisitos de skill
Analytics de uso: rastrear quais skills os agentes realmente invocam versus apenas carregam

O loop de mineração de skills é infraestrutura. Não é glamouroso. Mas é o que faz 41 agentes funcionarem de forma coerente com 466 capacidades, permanecendo dentro dos limites de contexto.

Essa é a história de como 3.500 se tornam 466. Não ignorando 3.000 — avaliando-as sistematicamente e adotando apenas o que funciona.

Quer ver o sistema de skills em ação? Confira uv run orkestra skills list para explorar o nosso registro atual.

Divulgação Progressiva: Janelas de CLI para Sistemas de Agentes

Tue, 20 Jan 2026 00:00:00 GMT

Os números neste post refletem o sistema no momento da publicação (janeiro de 2026). Consulte nossa página da equipe para números atualizados.

Sistemas de agentes são opacos por design. Eles tomam decisões, invocam ferramentas e coordenam trabalho entre dezenas de especialistas. Mas quando algo dá errado — ou quando você simplesmente quer entender o que está acontecendo — para onde você olha?

A resposta é a divulgação progressiva: uma interface em camadas que revela exatamente a complexidade que você precisa, exatamente quando você precisa dela.

O Problema da Opacidade

Um sistema moderno de orquestração de agentes pode ter:

40+ agentes especialistas, cada um com capacidades distintas
700+ skills abrangendo automação interna e integrações de fornecedores
470+ decisões arquiteturais moldando o comportamento
Dezenas de servidores de ferramentas MCP fornecendo capacidades externas

Essa complexidade é intencional. Os agentes precisam de acesso a contexto rico — conhecimento de domínio, inteligência de código, schemas de banco de dados — para tomar boas decisões. Mas essa mesma riqueza cria um problema de visibilidade.

Como você sabe qual agente trata de migrações de banco de dados? Quais decisões moldaram o comportamento de ranqueamento do sistema de busca? A quais ferramentas o conselheiro de arquitetura tem acesso?

Sem acesso estruturado, você fica lendo código-fonte ou torcendo para que a documentação esteja atualizada.

Divulgação Progressiva como Arquitetura

Divulgação progressiva não é apenas um padrão de UI. É um princípio arquitetural: organizar a informação em camadas, cada uma mais profunda que a anterior, para que os usuários possam parar no nível que responde à pergunta deles.

Para sistemas de agentes, isso se traduz em comandos de CLI em profundidades crescentes:

Nível	Comando	Pergunta Respondida
1	`orkestra system status`	Está tudo saudável?
2	`orkestra agents list`	Quais agentes existem?
3	`orkestra agents info <name>`	O que este agente faz?
4	`orkestra decisions search`	Por que funciona dessa forma?
5	Ferramentas MCP do Maguyva	Me mostre o código.

Cada nível responde a uma pergunta de acompanhamento natural. Raramente é preciso pular direto para o nível 5.

Nível 1: Saúde do Sistema

A primeira pergunta é sempre: está tudo funcionando?

$ orkestra system status

{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

Um comando. Quatro números. Suficiente para saber que o sistema está configurado e que os registros estão populados.

Se a contagem de agentes cai inesperadamente ou skills falham ao carregar, você vê isso aqui primeiro. Sem precisar mergulhar em logs.

Nível 2: Inventário de Agentes

Uma vez que você sabe que o sistema está saudável, a próxima pergunta é: o que está disponível?

$ orkestra agents list

Isso retorna dados estruturados — nomes de agentes, descrições, preferências de modelo, cobertura de domínio. A saída é JSON por padrão, o que facilita direcioná-la para jq para filtragem:

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

Quer agentes que lidam com trabalho de banco de dados? O comando de busca reduz o escopo:

$ orkestra agents search "database"

Isso varre nomes, descrições e capacidades. Você encontra o especialista certo sem ler 40 definições de agente.

Nível 3: Análise Detalhada do Agente

Encontrou um agente que parece relevante? O comando info revela tudo:

$ orkestra agents info architecture-advisor

A saída inclui:

Metadados: nome, categoria, preferência de modelo, descrição
Domínios: quais áreas de conhecimento este agente cobre
Identidade: traços de caráter (architect, strategist, knowledge-architect)
Guias de ferramenta: qual documentação de ferramenta é injetada no contexto
Ferramentas: a lista completa de ferramentas MCP disponíveis para esse agente

Aqui está uma amostra do que você vê:

{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

Isso diz exatamente o que o agente pode fazer. Sem precisar de código-fonte.

Nível 4: Arqueologia de Decisões

Os agentes se comportam de acordo com decisões documentadas. Quando você precisa entender por que algo funciona de determinada forma, o registro de decisões é a fonte da verdade.

$ orkestra decisions search "agent"

Isso retorna as decisões arquiteturais correspondentes:

{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

Cada decisão tem proveniência completa — quando foi tomada, por quê, quais trade-offs foram considerados, quais commits a implementaram:

$ orkestra decisions info DEC-SR-049

{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

Essa é documentação arquitetural que se mantém atualizada porque é minerada a partir de commits, não mantida manualmente.

Nível 5: Inteligência de Código Direta

Quando você precisa ver a implementação real — não metadados sobre ela — as ferramentas MCP do Maguyva fornecem acesso direto.

De dentro de uma sessão de agente:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Isso roteia automaticamente entre busca semântica, textual e de AST para encontrar o código relevante. Para símbolos específicos:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Para análise de dependências:

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

Essas não são apenas substitutas do grep. Elas levam o grafo em conta, são indexadas semanticamente, e integradas com a mesma inteligência de código que move os próprios agentes.

Busca Unificada Entre Registros

Às vezes você não sabe qual registro contém a resposta. A busca unificada abrange tudo:

$ orkestra search "database" --summary

{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

254 correspondências em cinco registros. O resumo diz onde aprofundar. Remova --summary para resultados detalhados, ou adicione --limit 5 para manter a saída gerenciável.

Por Que Isso Importa

A divulgação progressiva não é só sobre conveniência. Ela muda como você interage com sistemas complexos.

A depuração se torna mais simples. Quando um agente toma uma decisão inesperada, você não faz grep em logs. Você checa a quais ferramentas ele tem acesso (agents info), quais decisões moldam o seu comportamento (decisions search), e rastreia a implementação se necessário (intelligent_search).

O onboarding acelera. Novos membros da equipe não precisam ler o codebase inteiro. Eles começam com system status, exploram com agents list, e vão mais fundo apenas quando encontram algo que não entendem.

A documentação se mantém atualizada. Como a CLI lê dos mesmos registros que configuram os agentes, a saída sempre é precisa. Não há divergência entre o que a documentação diz e o que o sistema faz.

A CLI como Interface

Poderíamos ter construído um dashboard web. Poderíamos ter escrito documentação extensa. Em vez disso, construímos uma CLI que lê da fonte da verdade.

A CLI tem vantagens:

Composável: direcione a saída através de jq, integre com scripts
Automatizável: automatize verificações, gere relatórios
Rápida: sem carregamento de página, sem fluxos de autenticação
Precisa: lê a configuração real, não uma representação em cache

Para sistemas em que correção importa mais do que estética, a CLI vence.

Construindo a Sua Própria Divulgação Progressiva

Se você está construindo sistemas de agentes, considere como os usuários vão inspecioná-los:

Comece com verificações de saúde. Um comando que diz se as coisas estão funcionando.
Forneça visões de inventário. Liste o que existe antes de explicar o que faz.
Habilite consultas direcionadas. Busca vence navegação em escala.
Exponha a proveniência. Deixe os usuários rastrearem decisões até suas origens.
Conecte-se à inteligência de código. Mais cedo ou mais tarde, os usuários precisam ver a implementação.

Cada camada responde a uma pergunta de acompanhamento. Construa-as em ordem de frequência — a maioria dos usuários para na camada 2 ou 3. Apenas usuários avançados chegam à camada 5.

O objetivo não é expor tudo. É expor exatamente o que é necessário, exatamente quando é necessário. Essa é a divulgação progressiva aplicada à arquitetura de agentes.

Ground Truths: Ancorando Agentes de IA à Realidade

Tue, 13 Jan 2026 00:00:00 GMT

Os números neste post refletem o sistema no momento da publicação (janeiro de 2026). Consulte nossa página da equipe para números atualizados.

Agentes de IA são notavelmente capazes. Eles conseguem raciocinar, sintetizar e gerar. Mas têm uma fraqueza fundamental: eles inventam coisas. Não de forma maliciosa, mas com confiança. Um agente pode inventar parâmetros de API que não existem, referenciar configurações que nunca foram definidas, ou aplicar padrões dos seus dados de treinamento que contradizem a sua arquitetura real.

A mitigação padrão é “dar mais contexto ao agente”. Mas o contexto pode ser contraditório. A documentação se distancia da implementação. Comentários mentem. Até o próprio código pode enganar quando lido sem entender a intenção.

Precisávamos de algo mais explícito. Algo que não pudesse ser ignorado ou mal interpretado. Algo que ancorasse os agentes a uma realidade verificável.

Chamamos isso de Ground Truths: fatos de referência.

O que é um Ground Truth?

Um ground truth é uma declaração de fato explícita e versionada que os agentes devem respeitar. Não é documentação. Não é um comentário. É uma entidade de primeira classe no sistema, com:

Um identificador único (como GT-MAG-015 ou GT-MAG-036)
Um status de ciclo de vida (atual, provisório ou obsoleto)
Um escopo (de toda a plataforma, específico de pacote, ou restrito a um domínio)
Evidência (caminhos de arquivo, URLs ou referências que comprovam a declaração)
Orientação para o agente (instruções explícitas do que fazer/evitar)

Aqui está um exemplo da nossa plataforma de inteligência de código Maguyva:

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

Isso não é prosa. É um contrato. Quando um agente encontra esse ground truth, ele sabe:

O padrão é determinístico (resultados vazios, não chutes aproximados)
Existem parâmetros específicos (find_similar, exact_match) com comportamentos definidos
Existe evidência em arquivos específicos que podem ser verificados
A declaração foi verificada em uma data específica

A Anatomia de um Registro de Ground Truths

Ground truths vivem em registros YAML sob ai_assets/reference/ground_truths.yaml. Cada pacote ou domínio pode ter seu próprio registro. A estrutura é:

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

O registro inclui metadados sobre a própria coleção, configuração de renderização para geração de documentação, e as declarações em si. Cada declaração segue um schema rígido validado por modelos Pydantic:

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

Como os Agentes Acessam Ground Truths

Ground truths são expostos por múltiplos canais:

1. Documentação Renderizada

O comando orkestra sync transforma registros YAML em markdown legível:

uv run orkestra sync

Isso gera arquivos GROUND_TRUTHS.md que são incluídos no contexto do agente. A saída renderizada agrupa as declarações por status e categoria:

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. Busca via CLI

Agentes com acesso a shell podem buscar ground truths de forma programática:

uv run orkestra registry truths search "embedding"
uv run orkestra registry truths search --tag security
uv run orkestra registry truths list --status current

A função de busca pontua correspondências em vários campos com relevância ponderada:

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. Composição de Contexto

Quando agentes são renderizados a partir de definições YAML, o contexto deles pode referenciar registros de ground truths:

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

Isso garante que os ground truths relevantes sejam carregados antes de o agente começar a trabalhar.

Categorias de Ground Truths

Olhando para os nossos registros, os ground truths se agrupam em vários padrões:

Princípios do Produto

Restrições sobre o que o produto é e o que não é:

“O Maguyva é somente leitura em relação aos repositórios dos usuários; o único ativo não reconstruível é o cache pago de embeddings.” (GT-MAG-001)

Limites de Arquitetura

Onde as responsabilidades vivem e por quê:

“Os limites entre pipeline e Maguyva são intencionais: o pipeline é reutilizável, o Maguyva contém a lógica específica de código, e o CQRS separa as escritas das etapas do pipeline das leituras de servidor.” (GT-MAG-006)

Regras Antialucinação

Mandatos explícitos que mantêm os contratos de ferramentas determinísticos em vez de inferidos:

“A correspondência fuzzy de símbolos é opt-in via find_similar=true. O comportamento padrão retorna resultados vazios para símbolos inexistentes; exact_match=true força a correspondência estrita e desativa todos os fallbacks fuzzy.” (GT-MAG-015)

Controles de Qualidade

Padrões que precisam ser mantidos:

“Mudanças em infraestrutura compartilhada (post_filters.py, extratores de relacionamento, handlers compartilhados) DEVEM ser validadas contra TODAS as linguagens suportadas via geração de manifesto completo antes do commit. Uma validação de uma única linguagem é insuficiente para código compartilhado.” (GT-MAG-036)

Padrões de Código

Requisitos de implementação:

“Use asyncio.to_thread() para trabalho limitado por CPU em contextos assíncronos; o padrão obsoleto loop.run_in_executor() não deve ser usado em código novo.” (GT-MAG-018)

O Ciclo de Vida de um Ground Truth

Ground truths não são estáticos. Eles evoluem por um ciclo de vida definido:

Provisório

Uma verdade proposta em avaliação. A declaração é registrada, mas pode mudar:

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Atual

Uma verdade verificada que os agentes devem respeitar. A evidência foi validada:

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

Obsoleto

Uma verdade que não se aplica mais. Mantida para referência histórica, com um ponteiro para o que a substituiu:

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

Por Que Não Apenas Documentação?

A documentação serve a um propósito diferente. Ela explica. Ela ensina. Pode ser vaga, pode usar qualificadores como “geralmente” ou “tipicamente”.

Ground truths não podem ser vagos. São afirmações. Ou se aplicam, ou não se aplicam.

Considere a diferença:

Documentação: “A API geralmente retorna resultados vazios quando um símbolo não é encontrado, embora a correspondência fuzzy possa estar habilitada em algumas configurações.”

Ground Truth: “O comportamento padrão retorna resultados vazios para símbolos inexistentes; exact_match=true força a correspondência estrita e desativa todos os fallbacks fuzzy.”

A primeira é útil para humanos aprendendo o sistema. A segunda é acionável para agentes tomando decisões.

Orientação para o Agente: Fazer e Evitar

Alguns ground truths incluem orientação explícita para o agente:

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

Isso remove a ambiguidade. Um agente lendo isso sabe não apenas o que é verdade, mas quais ações essa verdade implica.

Verificação e Manutenção

Ground truths exigem manutenção. Rastreamos:

last_verified: quando alguém confirmou que a declaração ainda vale
evidence: arquivos que comprovam a declaração (pode-se verificar se existem)
source: de onde a verdade se originou (inspeção via CLI, revisão de arquitetura, aprendizado pós-incidente)

Um ground truth com datas de verificação desatualizadas ou links de evidência quebrados é um sinal para investigar. Ou a verdade ainda é válida e precisa de reverificação, ou a realidade mudou e a verdade precisa ser atualizada.

Exemplos Reais de Produção

Limite de Segurança

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

Esse ground truth previne uma classe de “melhorias de segurança” mal orientadas que quebrariam o produto.

Acurácia no Momento da Extração

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

Isso veio de uma experiência dolorosa. Agentes corrigiam pacotes de linguagem com falhas adicionando filtros apenas no validador, que faziam o harness de teste parecer mais verde, enquanto o extrator Maguyva ao vivo continuava emitindo as arestas erradas. A regra força as correções de volta para o caminho real: configuração YAML, queries ou handlers.

Filtragem em Múltiplos Níveis

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

Isso impede que agentes adicionem filtros no lugar errado, um erro comum que causou regressões de acurácia.

Integração com o Sistema de Orquestração

Ground truths são uma camada de um sistema de contexto mais amplo:

Decisões Arquiteturais (ADRs) - Registram por que escolhemos a abordagem A em vez da B
Ground Truths - Declaram o que está estabelecido como verdadeiro neste momento
Padrões de Domínio - Descrevem como fazer as coisas corretamente
Antipadrões - Descrevem o que evitar e por quê

Um agente trabalhando no sistema tem acesso aos quatro. Os ground truths fornecem a âncora factual, enquanto as decisões explicam a história, os padrões guiam a implementação, e os antipadrões alertam sobre armadilhas.

Medindo o Impacto

Desde que introduzimos os ground truths, observamos:

Menos ciclos de “corrigir a correção alucinada”
Tomada de decisão mais confiante pelos agentes quando os fatos estão claros
Revisões de PR melhores, porque as expectativas são explícitas
Tempo de onboarding reduzido para novos agentes (e humanos)

O investimento em manter os ground truths se paga em menos depuração e limites de sistema mais claros.

Começando

Para adicionar um ground truth ao seu sistema:

Crie um ground_truths.yaml no diretório ai_assets/reference/ do seu pacote
Defina metadados e configuração de renderização
Adicione declarações seguindo o schema
Rode uv run orkestra sync para gerar a documentação
Inclua o registro na composição de contexto do agente

Comece pelos fatos que causam mais confusão ou pelas restrições que são violadas com mais frequência. Esses são os seus ground truths de maior valor.

Conclusão

Agentes de IA vão alucinar. Essa é a natureza deles. Mas podemos criar ambientes em que a alucinação é restringida, em que certos fatos são inegociáveis, em que os agentes podem checar suas suposições contra uma realidade verificada.

Ground truths não são uma solução completa. Eles exigem manutenção. Podem ficar desatualizados. Adicionam sobrecarga ao processo de desenvolvimento.

Mas eles fornecem algo valioso: um vocabulário compartilhado de fatos em que tanto humanos quanto agentes podem confiar. Em um mundo em que os agentes participam cada vez mais do desenvolvimento de software, essa base compartilhada se torna essencial.

A alternativa é um ciclo infinito de agentes cometendo erros com confiança e humanos os corrigindo. Ground truths quebram esse ciclo tornando as correções explícitas e duradouras.

Seus agentes merecem saber o que é verdade. Diga a eles.

Orkestra: Orquestrando Agentes de IA em Escala

Tue, 06 Jan 2026 00:00:00 GMT

Os números neste post refletem o sistema no momento da publicação (janeiro de 2026). Consulte nossa página da equipe para números atualizados.

Quando começamos a construir com o Claude Code, esbarramos em um problema que toda equipe que usa assistentes de codificação com IA acaba enfrentando: um único agente não consegue fazer tudo bem.

Você pode instruir um agente a ser um especialista em banco de dados. Ou um auditor de segurança. Ou um engenheiro de frontend. Mas no momento em que você pede que ele seja os três ao mesmo tempo, a qualidade sofre. O contexto se dilui. As instruções entram em conflito. O agente se torna um generalista medíocre em tudo.

Então construímos o Orkestra.

O que é o Orkestra?

O Orkestra é um sistema de orquestração de agentes para o Claude Code e ferramentas de codificação com IA semelhantes. Ele coordena vários agentes especializados, cada um com expertise distinta, sob um único orquestrador que roteia o trabalho para o especialista certo.

Pense nele como uma agência de recrutamento para agentes de IA. O orquestrador recebe uma tarefa, identifica qual especialista deveria tratá-la, e delega com o contexto certo. Quando o trabalho termina, os resultados voltam ao orquestrador para síntese.

Os números contam a história:

Componente	Quantidade
Agentes especialistas	46
Skills reutilizáveis	466
Arquétipos de identidade	27
Mindsets	11
Estilos de comunicação	10
Domínios de conhecimento	21

O Sistema de Personagens: D&D para Agentes

O insight central por trás do Orkestra é que o comportamento do agente emerge de três primitivas combináveis:

Identidade define o que o agente é. Um arquiteto projeta estruturas de sistema. Um debugger rastreia falhas até a causa raiz. Um guardião garante a conformidade e faz cumprir os limites de segurança. Temos 27 arquétipos de identidade que podem ser combinados.

Mindset define como o agente pensa. Um mindset analítico fundamenta afirmações em evidências e quantifica incerteza. Um mindset cético questiona suposições e busca evidências que contrariem essas suposições. Um mindset exploratório abraça a ambiguidade e tenta múltiplas abordagens.

Estilo define como o agente se comunica. Um estilo técnico inclui valores exatos e referencia arquivos específicos. Um estilo conciso corta enrolação e começa pela resposta. Um estilo diplomático equilibra honestidade com tato.

Um agente combina essas primitivas:

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

Essa composição cria um agente que projeta sistemas (architect), conecta conhecimento entre domínios (knowledge-architect), define direção estratégica (strategist), pensa em evidências e dados (analytical), e se comunica sem enrolação (concise).

O poder está na explosão combinatória. 27 identidades vezes 11 mindsets vezes 10 estilos rendem quase 3.000 personalidades de agente possíveis. Mas você só define as combinações que importam para o seu trabalho.

Skills: Módulos de Capacidade Reutilizáveis

Skills são o conhecimento e os fluxos de trabalho que os agentes podem invocar. Elas seguem um sistema em camadas baseado em escopo:

Camada	Nome	Escopo	Exemplo
K0	Fundamentos	Metodologia universal	Disciplina test-first, conclusão baseada em evidências
K1	Identidades	Fluxos de trabalho baseados em papel	Padrões de interface de CLI, playbook de performance
K2	Domínios	Conhecimento específico de domínio	Padrões de migração de banco de dados, validação de autenticação
K3	Stacks	Específico de tecnologia	Deploy no Cloudflare, operações no Supabase
K4	Projeto	Apenas este codebase	Fluxos de trabalho e convenções específicos do projeto

As skills são carregadas sob demanda (lazy-loaded). Um agente vê os nomes e descrições das skills na inicialização, mas o conteúdo completo da skill só carrega quando acionado. Isso mantém o contexto enxuto, ao mesmo tempo em que torna centenas de skills descobríveis.

Cada skill inclui:

Condições de acionamento claras (“Use ao migrar schemas de banco de dados”)
Orientação passo a passo
Ferramentas permitidas para o fluxo de trabalho
Critérios de sucesso e caminhos de recuperação de falha

As 466 skills no nosso registro cobrem desde isolamento de worktree do git até fluxos de trabalho de pesquisa web e validação de saúde de deploy.

Por Que a Orquestração Importa

Arquiteturas de agente único esbarram em paredes rapidamente:

Diluição de contexto. Uma janela de contexto de 200 mil tokens parece grande até você carregar schemas de banco de dados, docs de API, fixtures de teste e conhecimento de domínio. Especialistas conseguem trabalhar com contexto direcionado.

Conflitos de instrução. Dizer a um agente para “ser minucioso mas rápido” e “verificar tudo mas não complicar além do necessário” cria tensão. Especialistas resolvem isso tendo escopo claro.

Profundidade de expertise. Um agente generalista sabe um pouco de tudo. Um agente especialista, composto com a identidade e as skills certas, conhece o seu domínio profundamente.

O Orkestra implementa orquestração plana: um orquestrador coordena vários especialistas. Especialistas não podem gerar subespecialistas. Isso evita a explosão de complexidade, ao mesmo tempo em que viabiliza trabalho paralelo.

O orquestrador tem acesso a 2,2 milhões de tokens de capacidade efetiva: a sua própria janela de 200 mil mais 10 subagentes concorrentes com 200 mil cada. Um trabalho que esgotaria um único agente roda confortavelmente em toda a frota.

O Pipeline de Renderização

As definições de agente vivem em YAML. O Claude Code lê Markdown. O Orkestra faz essa ponte com um pipeline de renderização determinístico:

YAML Registries → Jinja Templates → .claude/agents/*.md

Os operadores editam a fonte YAML. Rodam orkestra sync. O Markdown renderizado aparece em .claude/agents/. O Claude Code capta as mudanças.

Essa separação atende a públicos diferentes:

A fonte YAML inclui metadados de ciclo de vida, tags, regras de validação e notas de descontinuação para ferramentas
O Markdown renderizado inclui apenas o que o modelo precisa: descrição, ferramentas, skills e orientação comportamental

O pipeline compõe identidades, mindsets, estilos e skills em um único prompt coerente. Um agente architect-analytical-concise recebe um system prompt muito diferente de um agente debugger-skeptical-technical, mesmo que compartilhem algumas skills subjacentes.

Conhecimento de Domínio: O Padrão de Quatro Arquivos

Cada domínio de conhecimento segue uma estrutura consistente:

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

Essa estrutura serve ao carregamento de contexto do agente. Um agente trabalhando em autenticação carrega authentication/patterns.md para orientação e authentication/anti-patterns.md para evitar armadilhas conhecidas. Os arquivos têm tamanho pensado para carregamento eficiente de contexto: focados o suficiente para serem úteis, abrangentes o suficiente para serem autoritativos.

Mantemos 21 domínios de nível superior, incluindo analytics, autenticação, ciência de dados, infraestrutura, machine learning, performance, segurança e mais. Cada domínio pode ter subdomínios para granularidade mais fina.

Valores: O Sistema Operacional

Todos os agentes compartilham uma camada base de valores que define como eles operam:

Simplicidade primeiro. Use a solução mais simples que funcione. Adicione complexidade apenas quando justificado.

Corrija causas raiz. Nunca contorne falhas sem resolver suas causas. Se um pipeline falha, depure o pipeline. Se um teste falha, corrija o código ou o teste.

Baseado em evidências. Rotule afirmações como “verificado” (com benchmarks) ou “estimado” (com suposições). Padrão detectado não é o mesmo que problema confirmado.

Economia de contexto. Ferramentas MCP custam 0,1% do contexto. Leituras de arquivo custam 2% cada. Aplique expertise de domínio antes de explorar código.

Esses valores se propagam para cada especialista através do pipeline de renderização. Um agente não pode contorná-los por composição.

CLI: O Plano de Controle

O Orkestra vem com uma CLI para gerenciar o ecossistema de agentes:

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

A CLI é a fonte da verdade para quais agentes existem, quais skills eles têm, e se o sistema está saudável. Ela roda validação antes da sincronização para pegar problemas cedo.

Considerações Sobre Código Aberto

Construímos o Orkestra para resolver o nosso próprio problema: coordenar agentes de IA em escala para um codebase complexo. Os padrões que descobrimos não são específicos do nosso domínio.

O sistema de composição de personagem (identidade + mindset + estilo) se aplica a qualquer equipe que defina personalidades de agente.

O sistema de camadas de skill (K0-K4) fornece um modelo mental para organizar capacidades reutilizáveis por escopo.

O padrão de pipeline de renderização (fonte YAML + templates + artefatos gerados) separa responsabilidades entre ferramentas e consumo pelo modelo.

O modelo de orquestração plana (um coordenador, muitos especialistas) evita complexidade, ao mesmo tempo em que viabiliza paralelismo.

Se o Orkestra vai se tornar código aberto depende de se esses padrões têm valor para outras pessoas construindo com o Claude Code. Se você está esbarrando nas paredes que descrevemos, a arquitetura pode ajudar.

O Que Aprendemos

Construir o Orkestra nos ensinou que orquestração não é sobre tornar os agentes mais inteligentes. É sobre torná-los mais focados.

Um único agente com instruções perfeitas ainda fica sem contexto. Um único agente com todas as skills ainda fica confuso sobre qual aplicar. Um único agente tentando ser tudo produz resultados medíocres em tudo.

Quarenta especialistas, cada um excelente em seu domínio, coordenados por um orquestrador que sabe quando delegar: é assim que entregamos.

Os números importam menos do que a arquitetura. Você pode precisar de cinco agentes ou de cinquenta. O princípio permanece: composição acima de capacidade, especialização acima de generalização, coordenação acima de heroísmo individual.

O Orkestra move o ecossistema de agentes por trás do Maguyva, a nossa plataforma de inteligência de código. Quer saber mais? Entre em contato com a equipe.