Graphify ou CLAUDE.md: qual explica melhor a arquitetura do projeto para o agente?

Fala aí, beleza? Você pede uma mudança simples, e o agente jura que a regra de autenticação mora num arquivo que ela não mora mais

Não é burrice do modelo, é amostragem: ele abre alguns arquivos, encontra um padrão parecido e generaliza o resto do projeto a partir dali

E aí existem duas respostas possíveis pra esse problema

A primeira é escrever o contexto à mão, no CLAUDE.md, e confiar que o texto continua verdadeiro

A segunda é gerar o mapa a partir do código, com o Graphify, e deixar o agente consultar esse mapa quando precisar

Bora ver em que situação cada uma ganha, e por que na prática elas costumam conviver em vez de brigar 🙂

O que o CLAUDE.md resolve (e onde ele para)

O CLAUDE.md é um arquivo markdown com instruções persistentes que o Claude lê no início de toda sessão

É o lugar de escrever o que não está escrito em lugar nenhum do repositório: convenção do time, comando de build, o que é proibido mexer, o jeito que vocês nomeiam as coisas

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

O /init conduz a criação do CLAUDE.md do projeto, então você não precisa começar de uma folha em branco

E a documentação de memória do Claude Code é bem direta no critério de qualidade: quanto mais específicas e concisas as instruções, mais consistentemente o Claude as segue

Ou seja, arquivo gigante não é sinônimo de arquivo bom

Os níveis somam, eles não se substituem:

Existe o CLAUDE.md do projeto (./CLAUDE.md) e o do usuário (~/.claude/CLAUDE.md)

Se os dois existem, o agente enxerga os dois, eles são aditivos

Tem ainda o CLAUDE.md de política gerenciada, da organização, que não pode ser excluído

E dá pra quebrar o arquivo em pedaços usando import, com a sintaxe @path/to/import, em caminho relativo ou absoluto

# CLAUDE.md

Convenções do time e comandos do projeto

@docs/arquitetura.md
@docs/estilo-de-codigo.md

Isso ajuda bastante quando o contexto do projeto cresce e você quer manter cada assunto no seu arquivo

E a auto memory?

Boa pergunta, porque ela é fácil de confundir com o CLAUDE.md que você escreve

Além do arquivo que a pessoa mantém, o Claude Code tem a auto memory, em que o próprio Claude salva notas entre sessões: comandos de build, notas de arquitetura, preferências de estilo

Ela vem ligada por padrão, e o interruptor fica no comando /memory, que grava autoMemoryEnabled nas configurações do usuário

Esse mecanismo de não repetir o mesmo briefing toda vez é o mesmo problema que aparece em outra ferramenta da casa, quando você tenta não explicar o projeto toda vez numa conversa nova

Onde ele para:

Aqui vem a parte honesta

O CLAUDE.md é texto escrito por gente

Ele registra a intenção muito bem, e não prova absolutamente nada sobre o que existe no repositório hoje

Se alguém renomeou um módulo na sexta e não atualizou o arquivo, o agente vai começar a sessão lendo uma descrição desatualizada com toda a confiança do mundo

Documentação escrita à mão envelhece na velocidade do código, e o código é rápido

O que o Graphify faz diferente: mapa gerado a partir do código

O Graphify ataca o mesmo problema pelo outro lado: em vez de você descrever a arquitetura, ele extrai a arquitetura do que está lá

Ele é mantido no repositório Graphify-Labs/graphify (o caminho antigo safishamsi/graphify aponta pro mesmo projeto), foi criado por Safi Shamsi e está licenciado sob Apache License 2.0, depois de um relicenciamento a partir do MIT na linha v0.9.28

O texto MIT original continua no arquivo LICENSE-MIT, referenciado no NOTICE

A versão mais recente publicada é a v0.9.47, de 19/08/2026

Um detalhe de crédito que anda circulando torto por aí: o projeto é apenas INSPIRADO numa ideia publicada por Andrej Karpathy, a de compilar documentos num wiki estruturado em vez de fazer RAG a cada pergunta

Não é um projeto do Karpathy, a autoria é do Safi Shamsi / Graphify Labs

Como ele lê o código:

A extração de código é feita localmente, com parsing de AST via tree-sitter, de forma determinística

Sem chamada a modelo e sem vector store

Se você conhece um linter ou um compilador, a analogia é essa: a ferramenta entende a estrutura da linguagem e monta as ligações a partir dela, não a partir de um palpite estatístico

Consequência prática boa: um corpus só de código não exige chave de API nenhuma

Agora, se o seu corpus tem material não textual ou não código (PDFs, imagens, diagramas), aí o graphify extract usa um backend de LLM configurado por variável de ambiente (GEMINI_API_KEY, MOONSHOT_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY) ou uma instância local do Ollama

O que ele te entrega:

Os artefatos do grafo vão pra pasta graphify-out/ do projeto

• graphify-out/graph.json, o grafo legível por máquina
• graphify-out/GRAPH_REPORT.md, o relatório de arquitetura
• graphify-out/graph.html, o grafo interativo

Repara que são três formatos pra três públicos: a máquina consome o JSON, o agente e você leem o relatório, e o HTML é pra olhar mesmo, com o dedo na tela

Como o agente consulta:

A CLI tem três comandos de consulta

graphify query "como o login chega no banco?"
graphify path
graphify explain

O query recebe uma pergunta em linguagem natural, percorre o grafo e imprime o subgrafo com citações no formato arquivo:linha

O path acha o caminho mais curto entre dois nós

O explain explica um nó e a vizinhança dele

Os três aceitam as flags --dfs, --budget e --graph (que aponta pro grafo, com padrão em graphify-out/graph.json)

E tem também um servidor MCP com 10 ferramentas pro agente consultar o grafo sozinho, entre elas query_graph, get_node, get_neighbors, shortest_path, list_prs, get_pr_impact e triage_prs

A instalação, sem pegadinha:

Aqui mora uma armadilha de nome que já derrubou muita gente

O pacote no PyPI se chama graphifyy, com dois ‘y’, e o comando que ele instala se chama graphify, com um ‘y’ só

A instalação recomendada é via uv tool install

uv tool install graphifyy
graphify install

O graphify install registra a skill /graphify nos assistentes de código detectados na máquina

Se você quer isso valendo só no repositório atual, em vez do perfil do usuário, existe a flag --project

graphify install --project

Tome cuidado na hora de instalar: se você digitar uv tool install graphify, com um ‘y’, não é o pacote certo

E se liga nisso, que é o ponto que amarra o post inteiro: a integração com o Claude Code escreve uma seção própria chamada graphify (um heading de nível 2) no CLAUDE.md de nível de projeto e um hook PreToolUse em .claude/settings.json, que lembra o agente de consultar o grafo antes de sair buscando arquivo

Ou seja, a própria ferramenta não pede pra você abandonar o CLAUDE.md

Ela se instala DENTRO dele

Veja a arquitetura sendo desenhada na prática

Pra sentir o formato desse tipo de saída, este vídeo do canal mostra uma skill que gera o desenho da arquitetura a partir do código do projeto

Vale a ressalva pra não embaralhar as coisas: no caso do Graphify, quem monta o grafo do código é o parsing de AST, não um modelo

Graphify x CLAUDE.md: comparação lado a lado

Quando cada um ganha: 4 cenários de decisão

1. Projeto pequeno e estável, com convenção de time

CLAUDE.md basta, e sobra

Se o repositório cabe na cabeça de uma pessoa, o agente não se perde procurando arquivo, ele se perde é no seu padrão de código

Aqui o ganho está em ser específico e conciso, exatamente como a doc recomenda, e não em gerar mapa nenhum

2. Repositório grande, onde o agente gasta metade do tempo caçando arquivo

Esse é o cenário do grafo

Quando o agente precisa descobrir quem chama quem antes de escrever uma linha, o query com citação arquivo:linha e o hook PreToolUse mudam o jogo, porque ele consulta a estrutura em vez de sair varrendo o projeto

E em base grande a decisão costuma vir acompanhada de outra, a de como dividir o trabalho: vale pensar se é subagente por tarefa ou lotes antes de jogar tudo numa sessão só

3. Onboarding numa base herdada, sem documentação nenhuma

Sabe aquele projeto que ninguém entende e cujo autor saiu da empresa? 😛

Não adianta pedir pra alguém escrever o CLAUDE.md, porque ninguém sabe o que escrever

Aqui o GRAPH_REPORT.md e o graph.html funcionam como ponto de partida: você lê o relatório, abre o grafo interativo e SÓ DEPOIS escreve o CLAUDE.md, agora com base em algo

4. Regra de negócio e proibição que não estão no código

"não mexa nessa pasta", "esse serviço é legado e vai morrer", "toda migração precisa passar por revisão"

Nada disso está no AST

Grafo nenhum infere intenção, ele lê ligação

Então esse cenário é do CLAUDE.md, e sempre vai ser

O veredito: não é escolha, é divisão de trabalho

A comparação Graphify vs CLAUDE.md fica muito mais simples quando você aceita que as perguntas são diferentes

O CLAUDE.md responde "como eu quero que você trabalhe aqui"

O Graphify responde "como este código está ligado hoje"

Um é intenção, o outro é estado atual

E a prova mais forte disso não é opinião minha, é o comportamento da própria integração: ela escreve uma seção chamada graphify (heading de nível 2) no CLAUDE.md do projeto e um hook em .claude/settings.json

O mapa entra pelo arquivo de instruções, não no lugar dele

Agora, a parte que raramente aparece em post de ferramenta nova: pra quem o Graphify provavelmente é exagero?

Pra repositório pequeno, com poucos módulos, que você já conhece de cor

Nesse caso você vai instalar pacote, gerar graphify-out/ e manter mais uma coisa, pra resolver um problema que você não tem

Conclusão

O próximo passo aqui é pequeno e não custa nada

Abra o CLAUDE.md do seu projeto e leia com olhar de editor, cortando o que é genérico e deixando o que é específico do seu time, porque a recomendação oficial é justamente essa: específico e conciso

Se o seu repositório é dos grandes, aí sim vale gerar o grafo e testar UMA pergunta de arquitetura com o graphify query, daquelas que o agente costuma errar

Se a resposta vier com as citações arquivo:linha certas, você já sabe o que fazer

Se não vier, você economizou a adoção 😀

Continue por aqui no Hora de Codar que semana que vem tem mais ferramenta nova pra destroçarmos por completo

até o próximo post!