Graphify para Claude Code: transforme seu repositório em um grafo consultável

Graphify Claude Code: transformando um repositório em um grafo consultável

Um repositório com 800,000 linhas de código pode conter a resposta a uma pergunta aparentemente simples em seis lugares diferentes: um módulo Terraform, uma migração de banco de dados, um cliente gerado, um documento OpenAPI, um manifesto de implantação e um runbook escrito há dois anos.

O Claude Code pode pesquisar e ler esses arquivos, mas o trabalho em escala de repositório costuma ser limitado pela rapidez com que o agente consegue descobrir as relações entre eles. Uma busca textual por customer_id encontra ocorrências. Ela não explica automaticamente que:

• customer_id é declarado em uma migração de banco de dados,
• exposto por um esquema de API,
• mapeado em um modelo ORM,
• copiado para o payload de um evento,
• consumido por um processo em segundo plano,
• e mencionado em um procedimento de reversão em produção.

O Graphify aborda esse problema convertendo o material do repositório em um grafo de conhecimento: entidades se tornam nós, referências e dependências se tornam arestas, e o Claude Code pode consultar essa estrutura como contexto adicional.

A ressalva importante é que um grafo não é uma segunda fonte de verdade mágica. Ele é uma interpretação indexada do seu repositório. Seu valor depende da cobertura dos analisadores, da disciplina de atualização, das permissões e de quão bem as relações resultantes respondem a questões reais de engenharia.

O que o Graphify acrescenta ao Claude Code

O Claude Code já oferece várias maneiras úteis de entender um projeto:

• Leitura direta de arquivos
• rg e outras buscas pelo shell
• Histórico e diferenças do Git
• Instruções do projeto em CLAUDE.md
• Skills para fluxos de trabalho repetíveis
• Servidores MCP para ferramentas e dados externos

O Graphify acrescenta um padrão de acesso diferente: recuperação orientada a relações.

Uma busca convencional pergunta:

Onde este símbolo aparece?

Uma consulta ao grafo pergunta:

Quais serviços dependem deste esquema, qual infraestrutura implanta esses serviços e quais documentos descrevem as consequências operacionais?

Essa distinção importa quando a tarefa atravessa os limites de responsabilidade das equipes ou envolve diferentes formatos de arquivo.

Um grafo típico pode conter nós como:

As arestas podem representar relações como:

• imports
• calls
• implements
• extends
• reads_from
• writes_to
• publishes
• consumes
• deploys
• configured_by
• documented_by
• owned_by
• depends_on

O vocabulário exato de nós e arestas depende dos indexadores e da configuração atuais do Graphify. Trate o esquema do grafo como uma parte inspecionável do produto, não como uma suposição. Antes de criar prompts em torno de uma relação como publishes, verifique se a versão instalada realmente a gera.

Instalação do Graphify para o Claude Code

O Graphify é um projeto ativo, portanto os comandos de instalação e os nomes dos executáveis podem mudar. Comece pelo repositório e use o comando de instalação documentado para a versão que você está adotando:

git clone https://github.com/Graphify-Labs/graphify.git
cd graphify

Se você estiver usando um pacote publicado, é preferível usar o comando do gerenciador de pacotes documentado pelo projeto a copiar uma postagem antiga de blog. Após a instalação, confirme três fatos antes de indexar um monorepo grande:

graphify --help
graphify version
graphify config --help

Os comandos acima ilustram as verificações a realizar; use o executável e os subcomandos disponibilizados pela versão instalada.

Uma primeira execução segura deve usar um pequeno repositório de teste:

mkdir -p /tmp/graphify-fixture
cd /tmp/graphify-fixture

git init
printf 'def charge(order):\n    return order.total\n' > billing.py
printf 'from billing import charge\n' > worker.py

graphify index .

A indexação inicial normalmente realiza alguma combinação de descoberta, análise, extração de relações e persistência do grafo. Em um repositório real, inspecione a configuração gerada e o local de armazenamento antes de adicioná-la à CI. Você precisa saber se o índice é:

• Local ou hospedado
• Incremental ou reconstruído integralmente
• Persistido em um banco de dados, em arquivos ou em um armazenamento embutido
• Seguro para execução simultânea com outro indexador
• Capaz de excluir segredos, artefatos de build e árvores de dependências de terceiros

Para uma integração com o Claude Code, o Graphify precisa ser disponibilizado por meio do mecanismo de integração compatível com o projeto, geralmente MCP. Um arquivo local .mcp.json poderia ser assim:

{
  "mcpServers": {
    "graphify": {
      "command": "graphify",
      "args": ["mcp", "--project", "."],
      "env": {
        "GRAPHIFY_INDEX": ".graphify/index"
      }
    }
  }
}

Não trate esse subcomando exato como universal. Confirme o ponto de entrada MCP com:

graphify mcp --help

Em seguida, valide o servidor a partir do Claude Code:

/mcp

Você deve ver o servidor Graphify e suas ferramentas disponíveis. Os nomes das ferramentas e a sintaxe das consultas são específicos de cada versão. A verificação útil é operacional: peça ao Claude Code para listar as ferramentas do grafo, executar uma consulta restrita e informar qual revisão do repositório foi indexada.

Um problema comum é iniciar o Claude Code no diretório errado. Os caminhos relativos do projeto em .mcp.json, os arquivos de exclusão e a configuração do Graphify são resolvidos de acordo com o diretório de trabalho do processo do servidor, que não é necessariamente o diretório que você tinha em mente.

As relações que importam na prática

O grafo é mais útil quando expõe relações que são trabalhosas de reconstruir a partir do texto.

Linhagem entre código e dados

Suponha que uma migração renomeie accounts.status para accounts.lifecycle_state. Uma busca textual pode identificar referências, mas um grafo pode organizar o conjunto de elementos afetados:

table accounts
  -> column lifecycle_state
  -> migration 2025_04_rename_status
  -> model Account
  -> repository AccountRepository
  -> API response AccountSummary
  -> dashboard query active_accounts

Isso oferece ao Claude Code um ponto de partida melhor para revisar uma migração. Ele pode inspecionar os arquivos reais depois que o grafo identificar os prováveis dependentes.

Topologia de serviços e infraestrutura

As relações de infraestrutura são especialmente valiosas em monorepos nos quais o código da aplicação e o código de implantação ficam juntos:

service payments-api
  -> container image payments-api
  -> Kubernetes deployment payments
  -> reads secret PAYMENTS_DATABASE_URL
  -> writes queue payment-events
  -> consumed by reconciliation-worker

Isso ajuda a responder perguntas como:

• Qual implantação precisa mudar se uma porta mudar?
• O que consome esta fila?
• Quais serviços compartilham este banco de dados?
• Qual configuração é específica de cada ambiente?
• Qual recurso Terraform cria a dependência?

O Graphify não consegue inferir perfeitamente o comportamento em tempo de execução a partir de arquivos estáticos. A descoberta dinâmica de serviços, a reflexão, a configuração gerada e a indireção por variáveis de ambiente podem deixar lacunas. Use os resultados de topologia como um mapa de impacto e, em seguida, verifique as arestas críticas na configuração de implantação e de execução.

Da documentação à implementação

A documentação costuma ficar desconectada da busca no código porque a relação é semântica, e não sintática. Um runbook pode se referir ao “processador de liquidação”, enquanto o repositório o chama de reconciliation-worker.

Se o Graphify vincular referências da documentação a entidades de código ou infraestrutura, o Claude Code poderá responder a perguntas operacionais com menos navegação manual:

"Where is the rollback procedure for the component that consumes payment-events?"

A resposta só é confiável se os nomes usados na documentação forem mapeados corretamente. Terminologia desatualizada cria arestas plausíveis, mas incorretas, o que é mais perigoso do que uma busca claramente sem resultados.

Graphify, Skills e MCP são camadas diferentes

O Graphify deve complementar os pontos de extensão existentes do Claude Code, em vez de substituí-los.

Uma arquitetura útil é:

1. O Graphify descobre entidades e dependências candidatas.
2. O Claude Code usa esses resultados para selecionar arquivos.
3. As ferramentas nativas de arquivos verificam a implementação atual.
4. Uma skill aplica o procedimento de revisão ou alteração da equipe.
5. Testes, linters e verificações de implantação fornecem as evidências finais.

Por exemplo, uma skill de revisão de migrações poderia ficar em .claude/skills/review-migration/SKILL.md:

# Review Database Migration

When reviewing a migration:

1. Identify renamed, removed, or changed columns.
2. Query Graphify for code, schema, event, and infrastructure dependents.
3. Read each high-confidence dependent from the working tree.
4. Check backward compatibility for deployed application versions.
5. Run the repository migration and contract tests.
6. Report uncertain graph relationships separately from verified findings.

A skill define o fluxo de trabalho. O Graphify fornece contexto sobre os relacionamentos. O MCP é o meio de transporte e a interface de acesso às ferramentas.

Essa separação é importante. Colocar todo o conhecimento do grafo em uma skill produziria instruções estáticas que ficariam desatualizadas rapidamente. Colocar todas as políticas de fluxo de trabalho no Graphify tornaria o indexador responsável por decisões que ele não pode tomar de forma confiável.

Gerenciamento do custo e da atualização do índice

A indexação tem um custo em processamento, disco, latência e complexidade operacional. O custo não se limita à primeira varredura. Repositórios grandes também exigem trabalho de atualização quando branches mudam, arquivos gerados são reconstruídos ou grafos de dependências são invalidados.

Comece pelas exclusões:

# .graphifyignore
.git/
node_modules/
vendor/
dist/
build/
coverage/
tmp/
*.min.js
*.map
.env
*.pem

A sintaxe pode diferir da de .gitignore, então confirme como o Graphify trata os arquivos de exclusão. Exclua explicitamente credenciais e exportações sensíveis, mesmo que já sejam ignoradas pelo Git. Uma ferramenta que indexa um arquivo pode expor seu conteúdo por meio de uma consulta.

Use uma política de indexação em etapas:

• Indexe o código-fonte da aplicação, os esquemas, a infraestrutura e a documentação mantida.
• Exclua os arquivos gerados, a menos que sejam o artefato de referência.
• Crie um índice completo em CI ou em uma tarefa agendada.
• Atualize o índice de uma branch de forma incremental quando houver suporte.
• Registre o commit de origem junto aos metadados do grafo.
• Reconstrua o índice após alterações no analisador ou na configuração.

A revisão de origem deve estar visível para o agente. Um formato de resposta como este é muito mais seguro do que uma lista sem qualificações:

{
  "query": "dependents of table accounts",
  "indexed_revision": "9f31a7c",
  "generated_at": "2025-05-14T10:22:11Z",
  "results": [
    {
      "entity": "AccountRepository",
      "relationship": "reads_from",
      "target": "accounts",
      "confidence": "high",
      "path": "src/accounts/repository.py"
    }
  ]
}

Quando o Claude Code está modificando uma árvore de trabalho após a última indexação, os resultados do grafo são contexto histórico. Os arquivos atuais prevalecem. Na prática, instruo o agente a incluir indexed_revision em seu raciocínio e a verificar novamente cada afirmação derivada do grafo em relação à árvore de trabalho.

Precisão, privacidade e limites de produção

Um grafo pode fazer informações incompletas parecerem confiáveis. Há vários modos de falha para os quais se preparar:

• Importações dinâmicas e reflexão passam despercebidas.
• Scripts de shell ocultam relacionamentos por trás da expansão de variáveis.
• Clientes gerados obscurecem o esquema de origem.
• Links da documentação usam aliases que o analisador não reconhece.
• Arquivos excluídos permanecem até que uma limpeza ou reconstrução seja executada.
• O índice de uma branch é consultado enquanto o agente trabalha em outra branch.
• Módulos de infraestrutura são interpretados sem valores específicos do ambiente.

Para fluxos de trabalho em produção, exponha o grau de confiança e a proveniência sempre que possível. Um relacionamento sem caminho de arquivo, revisão ou método de extração é difícil de auditar.

A privacidade exige a mesma atenção. Grafos de repositórios podem revelar:

• Nomes de serviços internos
• Modelos de dados de clientes e pagamentos
• Topologia de rede
• Segredos por meio de nomes de arquivos ou referências de configuração
• Dependências sensíveis a vulnerabilidades
• Documentação proprietária

Mantenha índices sensíveis localmente ou dentro do mesmo limite de confiança do repositório. Use uma configuração MCP com privilégios mínimos, exclua conteúdo que contenha segredos e evite enviar o conteúdo do grafo a um serviço hospedado, a menos que a organização tenha aprovado esse fluxo de dados. A capacidade do Claude Code de consultar um grafo não altera os requisitos de controle de acesso do repositório.

Popularidade também não é sinônimo de confiabilidade. Um projeto pode atrair muita atenção e ainda ter cobertura imatura do analisador, esquemas de grafo instáveis, garantias limitadas de atualização ou comportamento insuficiente diante de mudanças constantes na escala de um monorepo. Avalie-o com um conjunto de dados de teste extraído do seu próprio repositório:

• Ele identifica importações e dependências de serviços conhecidas?
• Ele remove relacionamentos excluídos?
• A indexação incremental converge para o mesmo resultado de uma reconstrução completa?
• Os usuários conseguem distinguir resultados desatualizados e de baixa confiança?
• O servidor MCP indica claramente a falha quando o índice está indisponível?
• As consultas são rápidas o suficiente para o trabalho interativo do agente?
• Você consegue reproduzir o índice em CI?

Não torne o Graphify um pré-requisito obrigatório para todas as ações do agente. É essencial ter um modo degradado que recorra à busca normal de arquivos.

Um padrão prático de adoção

Comece com um fluxo de trabalho em que descobrir relacionamentos seja custoso e os erros sejam visíveis, como alterações de API, migrações de banco de dados ou refatorações de infraestrutura.

Meça resultados úteis em vez do tamanho do grafo:

• Tempo para identificar componentes afetados
• Número de componentes dependentes não identificados na revisão
• Taxa de relacionamentos desatualizados ou incorretos
• Tempo de indexação após commits típicos
• Falhas de consulta e frequência de uso de alternativas
• Dados adicionais expostos ao modelo

Use Sonnet 4.6 para investigações amplas do repositório quando a profundidade do raciocínio for importante, Haiku 4.5 para classificação leve ou tarefas repetidas de consulta, e Fable 5, com contexto maior, quando o fluxo de trabalho do projeto com contexto de 1M realmente se beneficiar da inclusão de evidências extensas. A escolha do modelo não corrige um grafo ruim. Um modelo menor com relacionamentos precisos e atuais pode ser mais útil do que um modelo maior que recebe um despejo não filtrado do índice.

O padrão prático de prompt é explicitar a proveniência:

Use Graphify to identify likely dependents of the `accounts.lifecycle_state`
column. For every result, include its path, indexed revision, relationship,
and confidence. Then read the current files and discard relationships that
do not exist in the working tree. Do not treat graph results as proof.

Essa última frase não é mera formalidade. Ela impede que uma camada de contexto desatualizada se torne uma autoridade incontestada.

Recomendações Práticas

• O principal valor do Graphify é a recuperação de relacionamentos entre código, esquemas, infraestrutura e documentação.
• Instale a ferramenta com versão definida, inspecione seus comandos reais de CLI e MCP e teste-a com dados de teste antes de indexar um monorepo.
• Mantenha o Graphify responsável pelo contexto do repositório; use skills do Claude Code para procedimentos de engenharia repetíveis.
• Inclua a revisão do índice, a proveniência e o grau de confiança nas respostas do grafo.
• Exclua segredos, ruído gerado e conteúdo desnecessário de terceiros.
• Trate os resultados do grafo como pistas que devem ser verificadas em relação à árvore de trabalho atual.
• Teste a indexação incremental, o tratamento de exclusões, o isolamento de branches e a operação em modo degradado antes da adoção em produção.
• A popularidade pode justificar uma avaliação, mas somente a precisão específica para o repositório e o comportamento operacional justificam depender da ferramenta.