Seu codebase tem problemas que você não consegue ver — como um knowledge graph revela o que grep não mostra

Desenvolvedores gastam 70% do tempo lendo código, não escrevendo. E a maior parte desse tempo é gasto procurando coisas. Não procurando uma função específica — isso o grep resolve em 2 segundos. O problema é procurar o que você nem sabe que existe: dependências ocultas, código morto que parece vivo, módulos acoplados que ninguém percebeu, workflows inteiros que nada referencia.

A gente construiu um knowledge graph do nosso codebase e, na primeira query, descobriu 229 artefatos órfãos, 2 workflows completamente desconectados do sistema, e que mudar um único agente impacta 31 outros artefatos em cadeia. Tudo isso era invisível — por anos.

O que grep encontra vs. o que grep nunca vai encontrar

Grep é uma ferramenta de presença. Você procura “parseConfig” e ele te mostra os 5 arquivos que mencionam essa string. Perfeito.

Mas grep não responde nenhuma dessas perguntas:

• O que acontece se eu mudar parseConfig? — Grep acha os 5 callers diretos. Mas esses 5 chamam outros 23 módulos que dependem transitivamente. O blast radius real é 28, não 5.
• Quais funções existem mas ninguém chama? — Grep acha presença. Órfãos são definidos pela ausência de referência. Você precisaria checar cada função contra todas as outras — combinação explosiva.
• Quantos módulos dependem desse aqui? — Quando você lê auth.js, você vê os imports dele (o que ele consome). Mas não vê quem importa ele (quem depende dele). O fan-in é invisível no arquivo individual.
• Tem dependência circular? — A→B→C→A. Cada arquivo mostra um edge. O ciclo só aparece quando você monta o grafo completo.

Um estudo da Microsoft Research (Nagappan et al., ICSE 2006) mostrou que métricas baseadas em grafo de dependência preveem 73% dos defeitos pós-mudança. Desenvolvedores que checavam só callers diretos (a abordagem grep) perdiam 60% das quebras que aconteciam em dependentes transitivos.

Ou seja: grep te dá uma foto. O grafo te dá o mapa.

A camada invisível que ninguém vê

Todo codebase tem 3 camadas de entendimento:

1. Micro (legível) — Funções individuais, classes, arquivos. Você abre e lê.
2. Macro (documentada) — Arquitetura do sistema, diagramas, READMEs.
3. Meso (invisível) — As conexões reais entre os arquivos. Quem chama quem, quem depende de quem, o que quebra se eu mexer aqui.

A camada meso é distribuída: cada arquivo contém um pedaço (seus imports), mas a foto completa exige agregar todos eles. É cognitivamente impossível manter isso na cabeça com centenas de arquivos.

Fowler e Whitehead documentam um caso no livro Building Evolutionary Architectures que ilustra perfeitamente:

“Projetamos o grafo de dependências na parede. O CTO disse: ‘Essa não é nossa arquitetura.’ Dissemos: ‘Essa É sua arquitetura.’ O sistema que eles achavam ter 8 módulos era, na prática, 2 mega-clusters com um gargalo roteando 67% do tráfego.”

Eles liam o código há 5 anos e não sabiam disso. Porque é impossível ver sem o grafo.

O que fizemos: dois grafos, um codebase

A gente trabalha com o AIOS — um sistema de orquestração de agentes IA para desenvolvimento full stack. Tem agentes (@dev, @qa, @architect), tasks (qa-gate, dev-develop-story), workflows (story-development-cycle, epic-orchestration), squads de especialistas, e minds (clones cognitivos de thought leaders como Alex Hormozi, Paul Graham, Seth Godin).

O problema: toda vez que o Claude Code precisava entender a relação entre esses artefatos, ele relia os arquivos. 12 agentes × 5.000 tokens cada = 60.000 tokens queimados só pra responder “o que o @dev faz?”.

Então construímos dois knowledge graphs complementares:

1. code-review-graph — Para código

O code-review-graph (fork do projeto original do tirth8205) usa Tree-sitter pra parsear código-fonte em AST e construir um grafo SQLite com funções, classes, imports e chamadas.

Resultado médio: 8.2x menos tokens por operação de review. Num monorepo com 27.000 arquivos, o grafo filtra pra ~15 arquivos relevantes.

No nosso fork, contribuímos com o PR #95 que adiciona 10 subcomandos CLI e parsing de CommonJS require().

2. aios-graph — Para artefatos não-código

Mas código é só metade da história. Nosso sistema tem 206 tasks, 14 workflows, 13 agentes, 93 squads e 115 minds — tudo definido em YAML e Markdown, fora do escopo do code-review-graph.

Então construímos o aios-graph: um knowledge graph local (Python + SQLite + PyYAML) que parseia esses artefatos e mapeia relações como DEPENDS_ON_TASK, ASSIGNED_TO, MIND_IN_SQUAD, DELEGATES_TO.

Nenhum outro tool no mercado faz isso. O Augment Code, codebase-memory-mcp, GitHub Stack Graphs — todos focam em entidades de código. Grafar agentes, tasks e workflows é uma categoria nova.

aios-graph query agent dev          # O que o @dev faz?
aios-graph impact agent:dev         # Blast radius se mudar o @dev
aios-graph who-uses qa-gate         # Quem depende do qa-gate?
aios-graph mind-search --tier S     # Minds prontas pra produção
aios-graph dead                     # Artefatos que ninguém referencia

200 tokens por query. Antes eram 60.000.

O que descobrimos no primeiro dia

Rodamos aios-graph build e as queries revelaram coisas que nenhum grep jamais mostraria:

229 artefatos órfãos

48 tasks (23.5% do total) existiam no repositório mas nenhum agente as declarava nas dependências. Eram tasks de orquestração, segurança e build que funcionavam na prática — mas o sistema não sabia que elas existiam.

Isso é importante porque se alguém deletasse uma delas achando que era “código morto”, quebraria workflows que dependiam implicitamente.

Me segue no Instagram @murilloimparavel — lá eu mostro os bastidores de como uso IA no dia a dia, sem filtro.

Blast radius de 31 para o @dev

O agente @dev (nosso implementador principal) tem 43 dependências e 24 dependentes. Mudar a interface dele — um comando, um formato de input — impacta 31 artefatos em 2 níveis de profundidade: 8 workflows, 6 rules, 10 agentes, 7 workflows indiretos.

Sem o grafo, alguém editaria o @dev achando que é “só um arquivo”. Na real, é o nó mais acoplado de todo o sistema.

2 workflows fantasma

epic-orchestration e development-cycle existiam como arquivos YAML completos, bem escritos, com fases e agentes definidos. Mas o grafo mostrou 0 edges — nada os referenciava, nada os conectava ao resto do sistema. Eram workflows que alguém criou, commitou, e esqueceu de plugar.

Descobrimos que o parser não entendia o formato YAML deles (usavam phases como dict em vez de sequence como lista). Corrigimos o parser e de repente: 12 novas edges apareceram. Os workflows voltaram à vida.

98.3% das minds sem frameworks extraídos

Das 115 minds (clones cognitivos de thought leaders), apenas 2 tinham frameworks operacionais extraídos (Gary Vaynerchuk e Pedro Sobral). As outras 113 eram bibliotecas brutas — o agente precisava reler todo o material fonte toda vez pra derivar princípios.

Isso é como ter um livro de receitas com 115 livros mas só 2 com o índice pronto. Os outros, você tem que ler inteiro pra achar o que precisa.

Duplicatas invisíveis

squads/copy/ e squads/copy-squad/ tinham agentes idênticos byte a byte. Sem o grafo, seriam 2 squads aparentemente diferentes (nomes diferentes, diretórios diferentes). A comparação de edges CONTAINS_AGENT revelou que eram a mesma coisa.

A economia de tokens — calculadora de padeiro

Segundo o paper Codebase-Memory, um graph query retorna resultado em ~200 tokens. Ler os mesmos arquivos manualmente custa 8.000-60.000 tokens.

Vamos fazer a conta com a calculadora de padeiro:

Com Claude Opus 4.6 a $9/1M input tokens, uma sessão pesada de exploração que consome 500K tokens custa $4.50. Com graph queries, a mesma sessão custa $0.45. Em um mês com 50 sessões, são $225 vs $22.50. $200 economizados por mês só mudando de grep pra graph.

E isso sem contar o benefício qualitativo: o modelo performa melhor com menos contexto. Factory.ai mostrou que contexto irrelevante degrada a performance — não é só mais caro, faz o modelo parecer pior.

Por que CLI e não MCP

Vamos delirar aqui um pouco. O ecossistema inteiro está empurrando MCP (Model Context Protocol) como a forma de conectar AI agents a ferramentas. A gente construiu o aios-graph inicialmente com MCP server (FastMCP). Depois deletamos.

Os dados são claros:

O aios-graph faz queries stateless contra SQLite. Não tem connection pooling, não tem streaming, não tem comunicação bidirecional — os únicos cenários onde MCP agrega valor real. Pra tudo mais, um CLI com --json resolve.

O Nx deletou a maioria dos seus MCP tools pela mesma razão. O CTO da Perplexity abandonou MCP internamente. A tendência é clara: CLI pra ferramentas de desenvolvimento, MCP só pra integrações externas que precisam de auth.

Como construir o seu

O aios-graph foi construído em ~2 horas com esta arquitetura:

aios_graph/
  graph.py    — SQLite store (WAL mode, parameterized queries)
  parser.py   — 7 parsers (agent, task, workflow, squad, mind, rule, framework)
  tools.py    — Core functions (stateless queries)
  cli.py      — Entry point com --json global flag

Dependências: pyyaml. Só isso.

O pipeline é simples:

1. Descobrir — rglob nos diretórios de artefatos
2. Parsear — Extrair YAML blocks de markdown, carregar YAML puro
3. Indexar — Upsert nodes + edges no SQLite com SHA-256 pra change detection
4. Consultar — BFS pra impact, in-degree=0 pra órfãos, LIKE pra search

Build completo: 420 nós, 993 edges, <15 segundos. Update incremental: <2 segundos.

O código é open source. O fork do code-review-graph está no meu GitHub com o PR #95 que adiciona CLI-first expansion. O aios-graph está no mvp-system.

O futuro: todo workspace de AI deveria ter um grafo

A pesquisa acadêmica está convergindo pra isso. Em 2024-2026, foram publicados pelo menos 7 papers sobre grafos + AI agents:

• CodeXGraph (NAACL 2025) — agentes LLM escrevem queries Cypher contra grafos de código
• GraphCodeAgent — +43.8% pass rate com GPT-4o usando dual graph
• Codebase-Memory — 83% da qualidade com 10x menos tokens
• Augment Code — +70% quality improvement com graph context

O padrão que está emergindo:

A gente está no L3 com investimento de $0 em infra. Zero servidor, zero embedding model, zero API key. SQLite + Tree-sitter + PyYAML.

Se esse conteúdo fez sentido pra você, compartilha com alguém que precisa ouvir isso. E se quiser trocar uma ideia sobre knowledge graphs, AI agents, ou como orquestrar isso tudo, me chama no Instagram.

FAQ

O que é um knowledge graph de codebase?

É um banco de dados de grafos (nós + arestas) que mapeia entidades do seu código (funções, classes, módulos) e as relações entre elas (quem chama quem, quem importa quem, quem testa quem). Diferente de um index de busca, ele permite queries de relacionamento: “o que quebra se eu mudar X?” ou “quais funções ninguém usa?”.

Preciso de Neo4j ou algum banco de grafos pra isso?

Não. O code-review-graph e o aios-graph usam SQLite puro. Duas tabelas (nodes e edges) com indexes são suficientes pra a maioria dos casos. Neo4j faz sentido se você precisa de queries Cypher complexas ou escala de milhões de nós. Pra um codebase típico (<100K arquivos), SQLite resolve.

Quanto código morto o meu codebase provavelmente tem?

Segundo a FlagShark, repositórios típicos têm 10-30% de código morto. Codebases enterprise com 5+ anos chegam a 20-35%. Pós-aquisição, pode bater 50%. Uma empresa SaaS descobriu que ~50% do código era não utilizado.

MCP ou CLI pra servir o grafo pro AI agent?

CLI com --json. Os benchmarks mostram que MCP custa 32x mais tokens e tem 72% de reliability vs 100% do CLI. MCP faz sentido pra database connections (connection pooling), browser automation (estado persistente) e OAuth delegation. Pra queries stateless contra SQLite, CLI é estritamente superior.

Isso funciona só pra código ou pra outros artefatos também?

Funciona pra qualquer coisa que tenha relações estruturadas. O aios-graph parseia YAML e Markdown — agentes, tasks, workflows, squads, minds. O mesmo padrão serve pra Terraform modules, Kubernetes manifests, GitHub Actions workflows, ou qualquer configuração declarativa que referencia outras configurações.