O Coração do AI Harness: Um Grafo de Conhecimento da IA, pela IA, para a IA (Parte 2)

Oi, eu sou Ryan, CTO da airCloset.

Isenção de responsabilidade: "cortex" e "cortex-product-graph" mencionados neste artigo são nomes de código internos para uma plataforma de IA desenvolvida internamente na airCloset. Eles não estão relacionados a serviços comerciais existentes, como Snowflake Cortex ou Palo Alto Networks Cortex.

No Parte 1 (Introdução da Série), escrevi sobre como IA lida com revisões de PR e resposta a incidentes em cima de uma plataforma que chamamos de cortex. No centro desse ciclo está o Product Graph (nome de implementação: cortex-product-graph, ou cpg) — um grafo de conhecimento unificado de código, documentos, esquemas de DB e definições de infraestrutura, consultável através de busca semântica.

Na Parte 1, descrevi o cpg em um nível alto: "todo o cortex está indexado em um único grafo." Este post se aprofunda — como foi construído, por que chegamos a esse design e o que realmente mudou uma vez que foi implementado.

Índice da Série

Comece com Uma Cena

"Eu quero mudar a lógica de cálculo por trás do KPI 'taxa de bugs' no painel. Onde está, e o que pode quebrar?" — imagine que essa pergunta surge antes de você tocar em qualquer código.

Quando você pergunta isso diretamente a uma IA, sem nome de função e sem caminho de arquivo fornecido, ela acessa o cpg com uma busca semântica e puxa os nós relevantes de uma só vez. O que vem de volta não são apenas funções — inclui tabelas BigQuery e endpoints de API junto com o código. E no final da resposta, há um bloco de "candidatos a próxima ação (Runbook)" que diz à IA para re-investigar começando pela tabela BQ com mais leituras e gravações fluindo através dela.

A resposta final se parece com isso:

• Local de cálculo: calculateRatePer100pt / calculateBugCount — ambas funções puras sem efeitos colaterais de I/O; seguras para mudar em isolamento
• Escritores (upstream): syncKpiMetrics / writeKpiMetrics / backfillKpiMetrics todas escrevem na tabela kpi_bug_rate_per_100pt; esses são os verdadeiros trabalhos de agregação em lote
• Leitores (downstream): BigQueryKpiRepository.getSummaryByDate lê via BigQuery → /kpi/bugs API → página do painel KPI
• Documentos relacionados: docs/generator/kpi.md define a taxa de bugs; atualizar o código sem atualizar os documentos os deixaria desatualizados

"Atualize os documentos juntos e agende o deploy quando o lote de agregação não estiver em execução" — essa é uma decisão que você pode tomar com confiança.

Eu pessoalmente sei de tudo isso — eu escrevi. Mas esse é exatamente o problema: qualquer outra pessoa que quisesse tocar nisso tinha que me encontrar. Três meses atrás, "descobrir onde algo está e o que quebraria" significava me encontrar. Agora, essa mesma investigação é feita por membros do PMO (não engenheiros) usando cpg por conta própria. grep não os levou até lá; a documentação não os levou até lá. Uma pergunta em linguagem natural fez isso.

O que torna isso possível é o cpg — um grafo onde você pode seguir "o que você quer fazer" em linguagem simples até os nós relevantes em uma ou duas etapas, mesmo quando você não sabe o nome da função. A estrutura do Runbook — onde o valor de retorno da ferramenta contém a próxima chamada de ferramenta a ser feita — é o que permite que a IA re-selecione seu ponto de partida e aprofunde-se sozinha.

Esse é o cenário. Agora deixe-me explicar como foi construído.

O Que a Análise Estática Sozinha Não Conseguiu Fazer

o cortex tem um sistema separado que analisa graficamente a base de código de produção usando análise estática (escreverei sobre isso em seu próprio post — apenas tocando aqui). Ele analisa código JS/TS com análise AST em nossos repositórios de produção voltados para o público, extraindo automaticamente gráficos de chamadas de função, endpoints de API, padrões de acesso a DB e relacionamentos de pub/sub de eventos.

Isso funciona bem para o que faz, e ainda o usamos ativamente nos repositórios de produção. Mas quando tentamos aplicar a mesma abordagem ao cortex em si, não conseguimos chegar onde queríamos.

Três lacunas específicas:

1. Sem contexto — nós existem, mas não carregam nenhum significado. "Para que serve esta API?" "Por que esta coluna existe?" não está no grafo. Pergunte "onde está o código que calcula a taxa de KPI de bugs?" e você vai errar a menos que o nome da função aconteça de parecer com isso.
2. Sem ponto de entrada — você já precisa saber o caminho do arquivo ou o nome da função antes que a busca possa começar. "Deixe-me ir encontrá-lo" não funciona.
3. Explosão após 1–2 etapas — começando de qualquer nó, nós relacionados se multiplicam exponencialmente dentro de algumas etapas, superando em muito o que uma IA pode processar em uma janela de contexto. Os resultados de rastreamento se tornam longos demais para usar.

O resumo: mecanicamente preciso, mas sem peso semântico. Para ser genuinamente útil para a IA, você precisa de uma camada a mais: "o que importa e por que as coisas estão conectadas."

Enquanto Isso, o Grafo DB Estava Funcionando

Na mesma época, uma abordagem diferente — o DB Graph MCP que construímos — estava funcionando exatamente como pretendido.

O DB Graph é um servidor MCP com acesso a 15 esquemas e 991 tabelas dentro do cortex, suportando busca semântica sobre tabelas e colunas com descrições geradas por IA. Uma consulta em linguagem natural como "tabelas relacionadas à confirmação de processamento de retorno" encontraria nós semanticamente conectados mesmo quando o nome da tabela não contém essas palavras.

Depois de pensar sobre por que isso funcionou, a resposta se tornou clara: o DB Graph tem uma descrição de contexto de negócios anexada a cada nó, e essa descrição é o que alimenta as incorporações. Esse peso semântico é o que "encontrar por significado" realmente funciona.

O grafo de código de análise estática não tinha nada disso. Relações de tipo e gráficos de chamadas existem — mas "por que esta função existe" nunca foi escrito em lugar nenhum.

A Hipótese — Trazer a Essência do Grafo DB para o Grafo de Código

A hipótese era simples:

"Uma descrição de contexto de negócios em cada nó, carregada em incorporações" — se isso é o núcleo do porquê o DB Graph funciona, então fazer o mesmo para o código