Vale a pena mapear o projeto com o Graphify ou deixar o Claude Code buscar sozinho?

Fala aí, beleza? Apareceu uma skill que promete entregar seu projeto inteiro mastigado pro agente antes dele abrir o primeiro arquivo, e a dúvida vem na hora: pra que mapear, se o Claude Code já vasculha o repositório sozinho?

É uma tensão legítima

De um lado, o agente que busca por demanda e nunca fica com índice velho

Do outro, um grafo de conhecimento pronto, que responde sem reler meio repositório

A resposta honesta é: depende do tamanho do projeto e de quantas vezes você pergunta sobre a mesma base. Bora comparar as duas abordagens com o que dá pra verificar hoje sobre o Graphify, a skill /graphify publicada em 3 de abril de 2026, criada por Safi Shamsi e mantida na organização Graphify-Labs

O que o Graphify faz com o seu projeto

A ideia é simples de enunciar: ele pega código, docs, schemas SQL, configs e PDFs, e ainda alcança papers, imagens e transcrições no passo semântico, transformando tudo num grafo de conhecimento consultável

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

O PORQUÊ vem antes do como: em vez do agente descobrir a estrutura do zero em toda pergunta, ele consulta um mapa que já sabe quem chama quem

O build roda em dois passos, e essa separação é a parte importante:

• Passo 1, AST determinístico: extrai classes, funções, imports, call graph e docstrings direto do código, sem LLM nenhum no meio
• Passo 2, extração semântica: aí sim entram subagentes do Claude por cima do material que não é estrutura de código, ou seja docs, papers, imagens e transcrições

A saída vai toda pra pasta graphify-out/, com graph.html (o grafo interativo), GRAPH_REPORT.md, graph.json (o grafo persistido) e uma pasta cache/ com cache SHA256, que serve pra pular arquivo que não mudou

Dois detalhes que eu achei mto massa: cada aresta do grafo vem rotulada como EXTRACTED (explícita no código-fonte) ou INFERRED (resolvida pelo próprio Graphify), então dá pra separar o que foi lido do que foi deduzido

E o agrupamento de nós em comunidades usa o algoritmo Leiden, por densidade de arestas, sem embeddings e sem banco vetorial

Sem vector store, se liga nisso: não é mais um RAG com índice semântico pra você babá

Estado do projeto hoje: open source sob Apache 2.0 (migrou da MIT), versão v0.9.47 publicada em 19 de agosto de 2026, e a skill é multiplataforma, roda em Claude Code, Cursor, Codex e Gemini CLI

Um registro pra evitar telefone sem fio: Andrej Karpathy inspirou o conceito de wiki/grafo de conhecimento gerado por LLM, mas ele NÃO é autor nem mantenedor do Graphify

Como o Claude Code encontra as coisas sem mapa nenhum

Agora o outro lado da moeda

O Claude Code roda localmente no terminal e fala direto com as APIs do modelo, sem servidor de backend próprio e sem índice remoto do seu código

Ou seja: não existe uma cópia do seu repositório indexada em lugar nenhum esperando pra ficar desatualizada

Ele usa busca agêntica pra entender estrutura e dependências do projeto, sem você precisar selecionar manualmente os arquivos de contexto

E como é que ele acha as coisas? A própria Anthropic descreve isso como um modelo híbrido: primitivas como glob e grep deixam o agente navegar e buscar arquivos just-in-time, justamente pra fugir do problema clássico do índice defasado

É o oposto filosófico do grafo prévio: nada é preparado, tudo é descoberto na hora

Tem ainda a peça que segura o contexto: subagentes podem ser configurados com ferramentas como Read, Grep e Glob, rodam numa janela de contexto isolada e devolvem só o relevante pro orquestrador

É assim que o agente paraleliza busca e não entope a janela principal com arquivo cru

Graphify x busca agêntica do Claude Code: comparação lado a lado

O 71,5x sai do BENCHMARKS.md do repositório, medido num corpus misto (repositórios do Karpathy + papers + imagens)

Não é o seu projeto, beleza? É um número oficial com corpus específico, e vale como indicação de ordem de grandeza, não como promessa

Quando o mapa evita voltas e quando ele é só uma etapa a mais

O critério prático é um só: repetição de consulta sobre a mesma base é o que paga o preparo

Se você vai perguntar uma vez, o preparo é imposto puro

Compensa mapear:

• Monorepo grande que você consulta várias vezes por dia
• Onboarding em código herdado, aquele projeto que ninguém sabe direito quem chama quem
• Base que mistura código com documentação, papers e PDFs, porque o passo semântico alcança material que grep não lê bem
• Time que quer compartilhar o mesmo grafo, já que o servidor MCP também roda em Streamable HTTP além do stdio padrão

Não compensa:

• Projeto pequeno, onde o agente lê o repositório inteiro sem suar
• Tarefa pontual de um arquivo só
• Código em reescrita diária, aí o rebuild vira pedágio
• Quem não quer manter graphify update, watch ou hook rodando

Esse último ponto é o que mais pega

Grafo é infraestrutura, e infraestrutura pede manutenção. Se você já curte deixar o agente rodando tarefas sozinho, encaixar um rebuild no fluxo é natural. Se não, é mais uma coisa pra lembrar

Como instalar o Graphify e gerar o primeiro grafo

Passo a passo curto, só com o que dá pra conferir na fonte oficial

1. Instale o CLI. A forma recomendada é via uv:

uv tool install graphifyy

Alternativas, se você não usa uv:

pipx install graphifyy
# ou
pip install graphifyy

Tome cuidado! O erro comum deste passo é o nome: o pacote oficial no PyPI é graphifyy, com dois y, e o comando do CLI continua sendo graphify. Outros pacotes com nome graphify* no PyPI não são afiliados ao projeto

2. Registre a skill no assistente:

graphify install

Pra gravar no repositório atual em vez do perfil do usuário, usa a flag --project:

graphify install --project

No Claude Code, isso escreve em .claude/skills/graphify/SKILL.md mais um diretório references/ carregado sob demanda, caminho que o Claude Code já varre sozinho. Existe também a forma por plataforma, graphify claude install --project

O erro comum deste passo é pular ele e sair digitando /graphify no assistente: sem o install, a skill não existe ali

3. Rode a skill dentro do assistente e confira a saída:

/graphify

Depois abre a pasta graphify-out/ e olha o graph.html e o GRAPH_REPORT.md. Se você não configurou API key, o build sai só com AST, determinístico e sem consumir créditos

4. Mantenha o grafo vivo:

graphify update   # re-escaneia só o que mudou
graphify watch    # reconstrói ao salvar
graphify hook install  # reconstrói após cada commit

O erro comum deste passo é achar que o grafo se atualiza sozinho. Não se atualiza, e é exatamente daí que vem a próxima seção

Os limites conhecidos antes de você adotar

Aqui não tem hype, tem issue aberta no repositório

A issue #1116 relata que o graphify update vaza nós obsoletos: um símbolo removido de um arquivo que ainda existe não é podado e sobrevive a todo rebuild incremental, até você fazer um rebuild completo

A issue #874 relata que o servidor MCP faz cache do graph.json na inicialização e não recarrega automaticamente depois de um graphify update

O impacto prático das duas junta é o mesmo, e é chatinho: o mapa pode te responder com estrutura que já não existe mais no código

E aí você debate com o agente sobre uma função que você mesmo apagou semana passada, haha

Outro ponto de confusão: o repositório graphify-mcp-tools (do CristianoCiuti) está marcado como DEPRECATED e foi sucedido pelo projeto reponova. Ele NÃO é o servidor MCP oficial do Graphify. O MCP oficial acompanha o CLI e lê o graphify-out/graph.json gerado pelo comando

Vale a pena? O veredito

Minha leitura, sem fingir bancada de teste: o Graphify é complemento, não substituto da busca agêntica

Ele não desliga o glob e o grep, ele evita que o agente precise deles o tempo todo pra remontar a mesma estrutura

Use o mapa se a base é grande, relativamente estável e recebe consulta repetida. O argumento mais forte aqui nem é o benchmark: é que o build estrutural, só com AST e sem API key, não consome crédito nenhum. O preparo barato muda a conta

Deixe o Claude Code buscar sozinho se o projeto é pequeno, se o código está volátil ou se é tarefa única. Nesses cenários o grafo é etapa a mais sem retorno, e o agente resolve dentro do fluxo do primeiro projeto ao deploy sem ferramenta extra

Duas ressalvas honestas pra fechar: o 71,5x é benchmark oficial do repositório em corpus misto, não medida do seu monorepo

E as issues de poda e de hot-reload pedem que você agende rebuild completo de vez em quando, não só incremental

Conclusão

O jeito mais barato de decidir isso não é lendo post nenhum (nem esse aqui, haha)

Rode o build sem API key num repositório real seu, que é a parte determinística e sem custo de crédito

Abre o graph.html, lê o GRAPH_REPORT.md, e faz a MESMA pergunta pro Claude Code sem o mapa

Compara as duas respostas e vê se o grafo te poupou volta de verdade ou só te deu um desenho bonito

Evidência do seu projeto > promessa de ferramenta, sempre

E vale reavaliar daqui a um tempo: a v0.9.47 ainda é pré-1.0, então esse jogo pode mudar rápido…

até o próximo post! 😀