Graft: encontre relações no código antes de abrir arquivos demais

ANÁLISE EDITORIAL

Ler um repositório grande do começo ao fim é caro, lento e ainda pode esconder a relação que realmente importa. O Graft cria um grafo local do código e ensina o agente a consultar esse mapa antes de abrir arquivos demais. A promessa prática é orientar busca, impacto e arquitetura com caminhos e linhas verificáveis. Isso não transforma o grafo em verdade absoluta nem substitui a leitura do trecho que será alterado.

O que esta Skill faz

A Skill muda a ordem de trabalho de um agente de código. Em vez de começar com uma busca ampla ou abrir arquivos inteiros, ela orienta a escolher uma consulta do Graft: ask para localizar e entender, grep para encontrar todas as ocorrências indexadas, skeleton para ver a superfície de um arquivo, callers para rastrear dependências e map para obter uma visão do repositório.

O grafo fica na pasta local graft/. Os nós em Markdown descrevem partes do projeto e apontam para intervalos arquivo:linha. Uma estrutura separada registra chamadas, referências, importações, extensões e outras ligações extraídas do código. A Skill também explica quando abandonar o grafo e abrir a fonte exata.

Para quem serve

Graft serve a desenvolvedores e revisores que trabalham em bases grandes, monorepos ou conjuntos de repositórios e precisam localizar o ponto certo antes de editar. Ele pode ajudar em onboarding técnico, investigação de um fluxo, preparação de refactor, busca de consumidores de uma função e avaliação do raio de impacto de uma mudança.

Não é uma escolha adequada quando o repositório é pequeno, a tarefa já nomeia poucas linhas ou a linguagem usada não está coberta pelos parsers instalados. Também não substitui testes, revisão de segurança, documentação oficial do projeto ou confirmação humana de uma decisão arquitetural.

Origem e curadoria

A pasta auditada é .claude/skills/graft no repositório do Graft. A curadoria fixou o commit f9e65396e638e517aecae0d731017f53084d70ed e comparou o SKILL.md original byte a byte.

O repositório aparece como trailhq/Graft na API, enquanto o package.json aponta a origem do pacote para a organização NanoNets. A página usa o commit como referência imutável, em vez de depender do nome que pode redirecionar. GitLab e Hugging Face foram pesquisados, mas não apresentaram outra origem canônica da mesma Skill.

Compatibilidade e pré-requisitos

O arquivo é compatível com agentes que carregam SKILL.md ou aceitam instruções de projeto equivalentes. Para executar os comandos, o manifesto do pacote exige Node.js 20 ou posterior e publica o binário graft por npm.

O commit declara parsers para TypeScript, Python, Go, Java, Kotlin, PHP, R e Swift, além da base tree-sitter. Isso descreve dependências do pacote, não uma garantia de que todo constructo de cada linguagem será ligado corretamente. Em repositórios sensíveis, use uma cópia de trabalho e compare os resultados com o código real antes de tomar decisões.

Instalação com revisão

O README oficial documenta instalação por npm. Para repetir a versão auditada, fixe 0.18.0 e evite @latest. O registro npm da versão 0.18.0 deve ser conferido antes da execução.

npm install -g @nanonets/graft@0.18.0
graft --version
graft init --dry-run

O primeiro comando consulta a rede, baixa dependências, grava fora do repositório e executa o postinstall do pacote. O terceiro não deve ser pulado: ele mostra os arquivos que o init pretende tocar antes de qualquer alteração. O download local do Bastidores é documental e não executa nada.

O postinstall e a telemetria

O script de pós-instalação registra um evento de instalação e entrega o envio a um processo separado quando a build publicada contém a chave de telemetria. O fluxo não bloqueia a instalação e ignora falhas de telemetria. Isso é uma ação de rede que merece ser conhecida antes de executar npm.

A política de telemetria diz que não envia código, caminhos, nomes de repositório, remotos, branches, símbolos, consultas, prompts, saída do agente, variáveis de ambiente ou mensagens de erro. Ela também informa que o hook pode ler localmente o fim do transcript para contar se a resposta mencionou a economia estimada, sem enviar o texto.

Como desativar antes de instalar

Se a política da equipe não permite telemetria, defina DO_NOT_TRACK=1 no ambiente antes do npm. Depois da instalação, o projeto também documenta graft telemetry disable, graft telemetry status e uma opção no seletor do init. Execuções reconhecidas como CI não enviam eventos.

Não trate a palavra “anônima” como autorização automática. Compare os campos descritos na política com as regras internas, verifique graft telemetry debug em um ambiente descartável e decida antes de indexar código proprietário.

Configure o escopo antes do primeiro pedido

Defina a raiz do repositório, os diretórios permitidos, as linguagens relevantes e se submódulos ou repositórios aninhados devem permanecer fora. O comportamento padrão exclui submódulos não inicializados e repositórios aninhados. Há opções específicas para incluí-los, e essa escolha amplia o conjunto de arquivos lidos.

Para múltiplos projetos, use --in <escopo> nas consultas depois de localizar o subprojeto correto. Evite indexar pastas com segredos, dumps, artefatos de clientes ou dependências vendorizadas só porque estão sob a mesma raiz.

Primeiro uso seguro

Comece em uma cópia do repositório, sem credenciais de produção e com telemetria decidida. Rode graft init --dry-run, examine a lista, depois use graft init --no-global --no-hooks --no-statusline se o objetivo inicial for testar somente arquivos locais e evitar integrações automáticas.

graft init --dry-run
graft init --no-global --no-hooks --no-statusline
graft map
graft check --json

Revise git status e git diff logo depois. O teste deve provar quais arquivos foram criados, se o índice cobre a linguagem e se uma consulta aponta para o trecho correto. Não comece com um refactor real.

O que o init pode alterar

O código de inicialização de hosts escreve instruções do agente, configurações MCP e, conforme as opções e o cliente, hooks locais ou globais. O caminho específico do Claude cria configuração, helpers, a Skill, registro MCP e pode construir o grafo se ele ainda não existir.

--no-global reduz escritas fora do projeto, mas não significa “nenhuma escrita”. --no-hooks, --no-statusline e --no-build tratam efeitos diferentes. Leia o plano completo do dry-run em vez de presumir que uma única opção cobre tudo.

Ask, grep e skeleton

graft ask "como a autenticação funciona" --source retorna resultados ranqueados e inclui um recorte curto do código. Use para perguntas conceituais ou quando o local ainda é desconhecido. Como é top N, a ausência de um item não prova que ele não existe.

graft grep "NomeDaFuncao" busca todas as ocorrências indexadas e agrupa por símbolo. graft skeleton arquivo.ts mostra assinaturas sem corpos. O primeiro serve para cobertura; o segundo, para conhecer a superfície antes de abrir uma implementação grande.

Callers e raio de impacto

graft callers Simbolo --depth 2 tenta mostrar quem depende do símbolo em dois saltos. --direction out inverte a pergunta e lista o que o símbolo usa. Para refactors amplos, a Skill sugere --depth all.

Essas ligações são extraídas por análise estrutural e podem perder usos dinâmicos, reflexão, geração de código, strings, templates ou chamadas fora das linguagens cobertas. Trate o grafo como índice de investigação. Antes de mudar uma assinatura, confirme os pontos relevantes com a busca e os testes do próprio repositório.

Map e repositórios múltiplos

graft map resume clusters de diretórios, hubs e pontos de alta conexão. Em uma pasta com vários repositórios, o Graft cria índices separados e uma visão federada no pai. Em um monorepo, tenta identificar subprojetos para equilibrar o ranqueamento.

Essa orientação pode acelerar o primeiro contato, mas não substitui decisões registradas em ADRs, políticas do repositório ou documentação de domínio. Se houver conflito entre o grafo e um arquivo oficial, investigue a divergência em vez de escolher silenciosamente a versão mais conveniente.

Modo profundo e chaves de modelo

O índice estrutural e as consultas principais são descritos como locais e sem chave. graft build --deep adiciona uma camada de resumos com modelo e pode exigir credencial do provedor escolhido. Essa etapa é opcional.

Antes do modo profundo, confirme qual provedor receberá conteúdo, quais arquivos entram no escopo, retenção, região e contrato. Não coloque chave em prompt, repositório, graft/, arquivo de configuração versionado ou screenshot. Para código confidencial, permaneça no modo estrutural até existir aprovação formal.

Limites e problemas conhecidos

O projeto é anterior à versão 1.0 e a política de segurança informa que correções são feitas na versão npm mais recente, sem manutenção separada das antigas. A API do GitHub não apresentou uma release publicada para o repositório na consulta; a versão foi confirmada no package.json e no npm.

A issue 80 permanece aberta e descreve quatro defeitos observados no init 0.9.1. A issue 79, sobre uma regra de .gitignore que podia esconder a própria Skill, está fechada como concluída. Esses registros não provam que toda observação antiga ainda afeta 0.18.0, mas justificam dry-run, diff e teste isolado.

Resultado esperado

Uma adoção correta termina com um diretório graft/ local, consultas que retornam arquivos e linhas plausíveis, um graft check coerente e uma lista conhecida de integrações instaladas. O operador deve saber quais arquivos são cache regenerável e quais configurações precisam ser versionadas.

O sucesso não é uma frase sobre “tokens economizados”. É conseguir localizar um fluxo ou consumidor real, conferir o trecho correspondente e repetir a consulta depois de uma mudança sem perder contexto relevante.

Permissões e riscos

Instalar por npm executa código e pode usar rede. O init grava arquivos de agente, MCP, hooks, statusline e cache. A indexação lê o repositório. O modo profundo pode enviar conteúdo a um provedor. A telemetria oficial envia eventos permitidos pela política quando não está desativada.

Use menor privilégio, versão fixada, diretório descartável e revisão do diff. Não indexe segredos. Não aceite uma referência arquivo:linha sem conferir quando a mudança for sensível. Remova integrações apenas com o comando documentado e depois examine o que permaneceu.

Erros comuns e como corrigir

• graft não encontrado: confirme Node.js 20+, instalação do pacote fixado e o PATH usado pelo agente ou MCP.
• Grafo ausente: rode graft build na raiz correta e examine erros de linguagem ou exclusão.
• Resultado fraco no ask: use uma pergunta mais específica ou troque para grep, skeleton ou callers.
• Caminho inexistente: atualize o grafo e confirme se a branch mudou antes de abrir o arquivo.
• Configuração alterada sem intenção: restaure pela ferramenta documentada, revise o diff e repita com dry-run e opções restritivas.
• Telemetria incompatível com a política: defina DO_NOT_TRACK=1 antes da instalação ou use o comando de desativação e confirme o status.

Quando não usar

Não use Graft para substituir testes, análise de dependências de pacote, scanner de vulnerabilidade, revisão de licença ou documentação de negócio. Evite quando a indexação amplia o acesso do agente além do necessário ou quando hooks e arquivos globais não podem ser auditados.

Para uma leitura humana e estruturada da base, a Acquire Codebase Knowledge segue outra abordagem. Para avaliar decisões de arquitetura, a Codebase Design também resolve um problema diferente. O Graft é uma camada de índice e navegação.

Versão, licença e pacote auditado

Esta curadoria usa Graft 0.18.0 no commit f9e65396e638e517aecae0d731017f53084d70ed. O repositório e o arquivo de licença indicam MIT. A consulta registrou 7.249 estrelas e 658 forks em 12/09/2026.

O ZIP local tem 5.971 bytes e três arquivos textuais: SKILL.md, LICENSE e ORIGEM.md. SHA-256: b87677bf2f936d087e519906fc6b28fc363eb5167d15be18a4a4491f1098f99b.

O que a revisão editorial confirmou

O SKILL.md e a licença correspondem byte a byte ao commit fixado. O pacote documental não contém o CLI, Node.js, npm, dependências, binários, scripts, hooks, MCP, cache graft/, código do leitor, chaves, telemetria, relatórios ou credenciais. A curadoria leu o postinstall e os caminhos de inicialização, mas não instalou nem executou Graft.

O pacote próprio serve para inspeção e importação manual das instruções. O uso funcional exige instalar o CLI oficial separadamente. Essa separação evita redistribuir executáveis e impede que o botão de download seja confundido com um instalador pronto.

Checklist antes de executar

• Fixe versão, commit, raiz do repositório e linguagens em escopo.
• Leia o SKILL.md, package.json, postinstall, TELEMETRY.md e SECURITY.md.
• Decida a telemetria antes do npm e confirme o status depois.
• Rode graft init --dry-run e revise toda escrita local ou global.
• Comece com --no-global --no-hooks --no-statusline em cópia descartável.
• Compare git status, git diff e os caminhos retornados pelo grafo.
• Aprove separadamente modo profundo, chaves, MCP, hooks e qualquer ação remota.

Fontes oficiais consultadas

• Repositório Graft no GitHub, visão geral, comandos e arquitetura declarada.
• SKILL.md no commit auditado, regras de consulta e limites.
• package.json no commit auditado, versão, Node.js, dependências e scripts.
• @nanonets/graft 0.18.0 no registro npm, versão publicada.
• postinstall oficial, evento de instalação e processo de envio.
• Política de telemetria, campos, exclusões e formas de desativação.
• Política de segurança, versões mantidas e reporte privado.
• Inicialização de hosts, arquivos, MCP e hooks.
• Inicialização do Claude, configuração, helpers, Skill e grafo.
• Node.js oficial, obtenção do runtime exigido.
• Issue 80, limitações históricas do init ainda em discussão.
• Issue 79, correção registrada para a regra de gitignore.