Graphify e ADRs: como comentários NOTE: e WHY: viram nós ligados ao código?

Fala aí, beleza? Todo mundo já abriu um arquivo, viu um if esquisito com um # HACK: em cima e pensou: por que raios isso está assim?

O comentário continua ali, quietinho

O racional completo, esse foi embora junto com a pessoa que saiu do time

É exatamente essa dor que o Graphify ataca por um ângulo diferente: ele é uma skill /graphify que transforma teu repositório num grafo de conhecimento consultável, e nesse grafo os comentários de racional (NOTE:, IMPORTANT:, HACK:, WHY:) e as citações de ADR e RFC deixam de ser texto solto e viram NÓS ligados ao código que eles explicam

Bora entender como isso funciona?

O que é o Graphify e quem está por trás

A descrição oficial do projeto é bem direta: transformar qualquer codebase, com seus docs, schemas SQL, configs e PDFs, num grafo de conhecimento consultável

Formação Recomendada

Formação Claude Code

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

• 116 aulas
• 4 projetos
• 9h 23min

Conhecer formação

E a parte que mais me chama atenção: parsing AST local e determinístico, cada aresta explicada, sem vector store

Ou seja, não é mais um "joga tudo num embedding e reza"

A skill roda em Claude Code, Cursor, Codex e Gemini CLI, então tu não precisa trocar de assistente pra usar

O repositório oficial vive na organização Graphify-Labs, em github.com/Graphify-Labs/graphify (o caminho antigo safishamsi/graphify redireciona pra lá, então não estranha se tu clicar num link velho e cair no novo)

Quem toca o barco é o Safi Shamsi, CEO e fundador da Graphify Labs, organização que mantém o projeto

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

Quais marcadores e referências viram nós de racional

Aqui está o coração do post

O Graphify extrai comentários de racional e docstrings como material de "porquê", ligado ao código que eles explicam

Os marcadores reconhecidos em comentários inline são:

• NOTE:
• IMPORTANT:
• HACK:
• WHY:

Além disso, entram docstrings e racional de projeto vindo de documentos

E tem o segundo pedaço, o das decisões formais: em JS/TS, comentários contendo NOTE:, HACK: ou o padrão ADR-NNNN passaram a ser extraídos como nós de tipo rationale e doc_ref, ligando código e decisões de projeto

Essa extração específica de JS/TS entrou via PR #1599, aberta em 1 de julho de 2026, e consta no changelog

E por que um ADR citado no comentário vira nó?

Porque o grafo não cobre só código

O enum canônico de tipos de arquivo inclui document, concept, rationale e paper

É isso que permite a mágica: o ADR ou a RFC que explica a escolha existe como nó no mesmo grafo, e o comentário no código vira a ponte até ele

Se tu conhece um índice de banco de dados, a analogia é boa o suficiente: em vez de varrer o histórico inteiro atrás do porquê, tu tem um caminho direto até ele

Como o grafo liga a decisão ao código: a aresta rationale_for

"Grafo" pode soar abstrato, então vamos concretizar

Os nós são conceitos: classes, funções, decisões de projeto, seções de paper, diagramas

As arestas são as relações entre eles, e o projeto lista calls, imports, rationale_for e semantically_similar_to

Sacou o pulo do gato? rationale_for é uma aresta de primeira classe, no mesmo nível de calls e imports

O "por que isso existe" tem o mesmo status estrutural que o "quem chama quem"

E como saber se o grafo está chutando?

Essa é a pergunta certa, e o projeto responde ela por design

Toda aresta do grafo é marcada como EXTRACTED, INFERRED ou AMBIGUOUS, com score de confiança

O que sai da passada AST entra como EXTRACTED com confiança 1.0

O motivo é simples: o token está literalmente no arquivo, não teve adivinhação no meio

E essa passada sobre arquivos de código é determinística, sem chamada de LLM: o tree-sitter extrai classes, funções, imports, grafo de chamadas, docstrings e os comentários de racional

Como instalar o Graphify e construir o grafo

Passo a passo curto, só com o que dá pra confirmar na documentação oficial

1. Instale via uv, que é o caminho recomendado:

uv tool install graphifyy

2. Se tu não usa uv, as alternativas são pipx ou pip:

pipx install graphifyy
# ou
pip install graphifyy

O erro comum deste passo é o nome: o pacote no PyPI é graphifyy, com dois "y", enquanto o comando instalado é graphify, com um só

Tome cuidado aí, porque digitar pip install graphify não é o mesmo que o pacote publicado

3. Rode a instalação da skill no teu assistente:

graphify install

Sem argumento, o alvo padrão é o Claude Code

4. Chame a skill dentro do assistente de código pra construir, reconstruir ou consultar o grafo:

/graphify

5. Não conte com escopo de projeto ainda

O erro comum deste passo é tentar algo como graphify install --project achando que existe: isso hoje é apenas um pedido de recurso em aberto, a issue #817 ("Feature Request: Project-scoped skill installation")

Então a instalação que tu faz é a que existe hoje, e ponto

Quando essa documentação viva ajuda no dia a dia

Não é toda hora que tu precisa de grafo

Mas tem situação em que recuperar o porquê vale MUITO mais do que ler o diff:

• Entrar em código legado: em vez de caçar histórico commit a commit atrás do contexto, tu consulta o racional que já está ligado àquela função
• Revisar um HACK: antes de refatorar: aquele comentário estranho vira nó, e o nó aponta pro código que ele justifica, então tu decide sabendo o que estava em jogo
• Entender qual ADR sustenta uma escolha de arquitetura: em JS/TS, a citação ADR-NNNN no comentário vira nó doc_ref, e o documento existe como nó no mesmo grafo
• Cruzar código com o paper ou o diagrama que o explica: como o grafo cobre documentos, papers e diagramas, a ligação vive no mesmo lugar

Esse último caso é o típico projeto que implementa algo vindo de um artigo

Quem gosta desse fluxo de destrinchar documento pra entender uma decisão provavelmente já brinca com prompts de NotebookLM para estudar, a diferença aqui é que o racional fica amarrado ao código, não numa conversa à parte

Repara que eu não estou prometendo ganho de X vezes em nada 🙂

O que dá pra afirmar é o comportamento: o porquê vira nó consultável, com aresta explícita até o código

Veja também: do plano ao app com Claude Code

Pra quem quer pegar o ritmo de trabalhar com assistente de código antes de sair montando grafo, este vídeo do canal mostra um projeto completo, saindo do plano até o app funcionando

É um bom aquecimento pro contexto de organizar decisão e documento antes de escrever código, assunto que também aparece no post sobre transcrever reuniões no NotebookLM

Limites e cuidados de quem for adotar agora

Agora a parte honesta, que é a que interessa na hora de decidir

Os nós de racional já passaram por correções registradas no changelog do projeto:

• Rótulos deixaram de carregar caracteres \r em arquivos CRLF no Windows e WSL (clássico problema de fim de linha, quem programa no Windows conhece bem)
• Nós de racional passaram a ser excluídos da busca por nome na resolução de chamadas entre arquivos, o que preserva a direção das arestas calls e rationale_for na exportação JSON

E a versão v0.9.47 trouxe uma correção que muda o comportamento em caso de timeout: em vez de derrubar o chunk inteiro do arquivo, ele passa a bissectar o chunk

Traduzindo: divide pra tentar salvar a parte que dá pra processar, em vez de perder tudo

O que ainda pesa na decisão são duas coisas

Primeira: a extração de racional e de referências a ADR/RFC em JS/TS é recente, entrou via PR #1599, aberta em julho de 2026

Segunda: o escopo por projeto continua sendo pedido em aberto, na issue #817, então quem já esperava separar skill por repositório vai ter que esperar

Nada disso é impeditivo, mas é o tipo de coisa que eu prefiro saber ANTES de apontar a ferramenta pro monorepo da empresa inteira, né?

Conclusão

A ideia central é essa: quando o "por que decidimos assim" vira nó ligado ao código, ele para de depender da memória de quem estava na reunião

O Graphify faz isso com peças bem definidas: docstrings e comentários com NOTE:, IMPORTANT:, HACK: e WHY: entram como material de racional, o padrão ADR-NNNN em JS/TS vira nó doc_ref, e a aresta rationale_for amarra a decisão ao código, com marcação de confiança em cada ligação

Próximo passo prático, sem drama: instala via uv, roda graphify install, chama /graphify num repositório pequeno e observa quais comentários viraram nós de racional

Depois que tu vir o formato do resultado com os teus próprios olhos, aí sim escala pro projeto principal

até o próximo post! 😀