title: 'Engenharia de Contexto Determinística: Medindo o Impacto do context-graph-engine em Agentes de Código' date: '2026-10-22' tags: ['context-graph-engine', 'Go', 'Clojure', 'AI Factory', 'Benchmarks', 'LLM', 'Architecture'] summary: 'Como um indexador sintático determinístico em Go (sem LLM e sem embeddings) reduziu em 82% o custo, 97% as chamadas de ferramentas e 97% o tempo de parede de um agente de código em um repositório Clojure real — e o que as execuções que falharam nos ensinaram sobre contaminação de benchmarks.'
Série AI Factory & Engenharia de Agentes — Parte 3 de 6
Nos dois primeiros artigos desta série, percorremos a infraestrutura soberana da AI Factory sobre FreeBSD Jails, vLLM e Slurm e o plano de execução do small-router (nosso gateway de inferência em Go com contratos em EDN/Malli).
Uma vez que o small-router passou a registrar a telemetria exata de cada turno de agente (tokens de entrada, prompt cache, chamadas de ferramentas, latência e custo em dólares), uma verdade incômoda saltou aos olhos nos logs: um agente de código chamado para trabalhar num repositório não-familiar gasta a maior parte do seu orçamento apenas descobrindo o que o repositório é.
Ele lista diretórios, dispara dezenas de glob e grep, abre arquivos irrelevantes, relê o mesmo arquivo duas ou três vezes e ainda invoca sub-agentes para resumir o que acabou de ler. Pior: essa exploração é redescoberta do zero — e paga de novo — a cada nova sessão.
A resposta padrão da indústria para isso costuma ser "coloque um banco vetorial com embeddings do código". Eu segui o caminho oposto: construí o context-graph-engine (repo-index) usando exclusivamente a biblioteca padrão do Go — sem LLM, sem embeddings e sem rede — para extrair fatos determinísticos com proveniência exata e empacotar envelopes de contexto com prefixo estável. E, em seguida, medi cientificamente o antes e o depois (BEFORE vs. AFTER).
🧱 As Quatro Camadas (e Por Que Elas Nunca Devem Se Misturar)
O erro mais comum em ferramentas de contexto para IA é misturar observação com heurística. Quando um indexador tenta "adivinhar" o que é importante durante a varredura, você perde a capacidade de auditar por que um arquivo entrou ou ficou de fora do prompt.
No context-graph-engine, o pipeline é dividido em quatro camadas estritamente separadas:
Repositório Git (Clojure / Go)
│
▼ 1. scan ──▶ O que existe? (Fatos puros + proveniência de arquivo/linha)
facts.json
│
▼ 2. graph ──▶ Como as partes se relacionam? (Arestas de require/import/deps)
graph.json
│
▼ 3. navigate ──▶ O que esta tarefa específica precisa? (Política declarativa, sem LLM)
subgraph
│
▼ 4. pack ──▶ O que cabe no orçamento e em qual ordem? (Envelope com prefixo estável)
envelope.txt ──▶ Entregue ao Agente de Código
| Camada | Pergunta que Responde | Onde Pode Errar |
|---|---|---|
1. Index (scan + graph) |
O que existe no repositório? | Em nada — é observação sintática pura com proveniência (arquivo, linha, regra). |
2. Navigation (navigate) |
O que é relevante para esta tarefa? | Na política declarada (que vive num perfil .json sobrescritível, nunca hardcoded no indexador). |
3. Pack (pack) |
O que cabe fisicamente na janela? | No orçamento de tokens (budget-soft / budget-hard) e na ordenação. |
| 4. Agent | O que fazer com o código? | Na execução da tarefa de engenharia em si. |
Manter essas camadas separadas é o coração da ferramenta: uma convenção de nomenclatura como *.core é política de navegação, não fato. Todo nó selecionado pelo navegador carrega a regra exata que o selecionou e a aresta pela qual ele chegou até ali, com o arquivo e a linha de origem.
🔍 O Que o Motor Extrai (Go + Clojure Nativo, Zero Dependências)
Sem subir uma JVM, sem chamar clj-kondo externo e sem depender de bibliotecas de terceiros, o binário possui analisadores sintáticos próprios em Go (internal/edn e internal/languages) capazes de inspecionar repositórios mistos de Clojure e Go (incluindo a si mesmo via self-hosting com make context):
- Clojure (
internal/edn+ analisador sintático): Extrains,:require,:as(aliases),:refer,def/defn/defmacropúblicos e reader conditionals (#?(:clj ... :cljs ...)), além de dependências e aliases dodeps.edn. - Go: Resolve o caminho de pacote a partir do
go.modmais próximo, extraiimports e declarações exportadas de topo. - Comandos Operacionais & CI: Mapeia tarefas do
mise.toml,Makefile,package.json, aliases do Clojure e passosrun:de workflows de CI. - Escopo e Fronteiras de Segurança (
internal/scope): Classifica cada caminho comorepository,external,generated,cacheouignored. Árvores excluídas (como.cpcache,node_modulesoutarget) não são descartadas em silêncio: viram fatos auditáveis com a regra que as excluiu.
Cinco Garantias Inegociáveis
- Determinismo Byte-a-Byte: O mesmo estado de repositório produz artefatos (
facts.json,graph.json,manifest.json) idênticos byte a byte. Zero timestamps variáveis, zero caminhos absolutos, zero IDs aleatórios — tudo ordenado lexicograficamente e testado escaneando cada fixture duas vezes e comparando os bytes. - Fronteira de Segurança Inviolável: Qualquer arquivo classificado como sensível (
.env,*.key,**/secrets/**) jamais é aberto em nenhuma camada — nem mesmo se o operador pedir explicitamente ao packer para materializá-lo. Ele viaja no grafo apenas como metadado (content_read: false), e credenciais em URLs de remotes Git são expurgadas na leitura. - Verificabilidade Criptográfica (
verify): O manifesto amarra o índice ao estado exato da árvore (commit, flagdirty, tree fingerprint e digests SHA-256 por artefato). O comandorepo-index verifyretornaINDEX_INVALID(código 3) se um artefato foi adulterado eSTALE_INDEX(código 4) se o código-fonte avançou. - Proteção Tripla Contra Escrita de Agentes (
protect): Fatos gerados, perfis de política e baselines de benchmark são protegidos contra edição acidental por agentes em três camadas independentes: permissões de sistema de arquivos (0444nos artefatos e0555no diretório — poisrenameeunlinkdependem da permissão do diretório, não do arquivo), um hookPreToolUseque barra a ferramenta comWRITE_DENIED protected_artifact(código 5) e regras de deny do projeto.
📊 O Experimento Científico: BEFORE vs. AFTER
Em vez de confiar na intuição de que "o agente pareceu mais rápido", congelei um protocolo experimental rigoroso usando um serviço real de produção em Clojure (112 arquivos-fonte, 1,17 MB), o mesmo modelo (qwen3.7-plus) e exatamente o mesmo prompt pedindo um inventário completo de arquitetura, dependências, fluxos de trabalho, metadados de segurança, candidatos a Polylith e riscos — sem permissão de escrita.
O Diagnóstico do BEFORE (Sem Índice de Contexto)
Quando o agente foi solto no repositório "a frio", a telemetria do small-router revelou dois ralos financeiros e de latência distintos:
- Explosão de Descoberta: Do turno #1 para o turno #2, o consumo saltou de
731para40.369tokens de entrada. Ao longo da sessão, o agente disparou 184 chamadas de ferramentas:108leituras de arquivos (read_file) sobre79arquivos distintos — relendo 29 arquivos mais de uma vez — além de39list_directory,17glob,10grep_searche4sub-agentes. - Instabilidade de Prefixo (Prompt Cache Abandonment): Embora a taxa média de cache parecesse saudável (
70,9%), apenas 5 requisições onde o prefixo do prompt mudou custaram 41% de todos os tokens não-cacheados da sessão inteira (incluindo uma única chamada no turno #38 que re-faturou66.760tokens a preço cheio).
O Resultado Comparado (BEFORE vs. AFTER com Envelope Determinístico)
No AFTER, mudamos exatamente uma variável: entregamos ao agente o envelope pré-computado pelo repo-index para o perfil architecture (com prefixo estável, contendo o mapa estrutural do repositório e os 22 arquivos nucleares materializados com suas razões de seleção).
| Métrica Auditada | BEFORE (Descoberta a Frio) |
AFTER (repo-index Envelope) |
Impacto Real (Δ) |
|---|---|---|---|
| Requisições ao LLM (Turnos) | 39 | 3 | −92% |
| Tokens de Entrada Totais | 1.220.009 | 171.976 | −86% |
| Tokens de Entrada Não-Cacheados | 354.729 | 103.368 | −71% |
| Tokens de Saída | 50.735 | 5.028 | −90% |
| Chamadas de Ferramentas (Total) | 184 | 5 | −97% |
read_file (Leituras de Arquivo) |
108 (29 releituras) | 0 | −100% |
list_directory / grep / shell / sub-agent |
39 / 10 / 6 / 4 | 0 / 0 / 0 / 0 | −100% |
glob (Verificação Pontual) |
17 | 5 | −71% |
| Custo Total da Tarefa (USD) | $0,2893 | $0,0510 | −82% |
| Tempo de Parede (Wall Clock) | 1.194 s (~20 min) | 36 s | −97% |
Olhe para a linha do read_file: caiu de 108 leituras para zero.
O agente no AFTER não precisou abrir nenhum arquivo para reconstruir mentalmente o repositório. Suas únicas 5 chamadas de ferramenta foram globs cirúrgicos para confirmar se diretórios opcionais existiam (test/**/*.clj, docs/adr/*.md). E todas as 14 áreas técnicas cobertas pelo BEFORE (Jetty, Datomic, Kafka, Qdrant, Slurm, interceptors, segurança, deploy, etc.) foram cobertas no relatório final do AFTER com 100% das afirmações ancoradas nos 22 arquivos do envelope.
🧪 O Que as 4 Tentativas que Falharam Antes do Benchmark Limpo Ensinaram
Em engenharia séria, os erros de medição durante a construção do experimento costumam ensinar mais do que o gráfico final. Antes de chegar à execução limpa do AFTER, quatro baterias preliminares foram invalidadas — e cada uma revelou uma armadilha clássica de quem avalia agentes de IA:
- Um pacote de contexto não é dado inerte — o modelo obedece ao que lê dentro dos arquivos:
Um dos 22 arquivos materializados dentro do envelope de arquitetura era o
AGENTS.mddo próprio repositório, que continha uma instrução antiga dizendo ao agente: "Antes de explorar, leiacontext/*.md". Mesmo com o prompt do envelope dizendo que tudo já estava ali, o modelo obedeceu à instrução que estava escrita dentro do arquivoAGENTS.mdmaterializado em três execuções seguidas! Lição: texto materializado no contexto é instrução ativa para um LLM; ou você demarca claramente as fronteiras de dados, ou alinha as instruções internas do repositório com o seu runtime. - Uma resposta anterior esquecida na árvore invalida qualquer benchmark:
Numa das rodadas, uma execução anterior havia deixado uma pasta com 95 KB de relatórios gerados no disco. O agente no
AFTERachou a pasta, leu os 7 documentos prontos e produziu um relatório brilhante — mas estava apenas parafraseando a resposta pronta, enquanto oBEFOREhavia lido o código-fonte real. A comparação era assimétrica e cientificamente nula. Respostas anteriores precisam ser movidas para fora da árvore física antes de medir, não apenas "proibidas por prompt". - Arquivos ignorados pelo Git não são estado do repositório:
Um servidor
nREPLdo Clojure reescrevendo.nrepl-portou o cache de um linter invalidavam o tree fingerprint do índice em poucos minutos, porque o cálculo de integridade inicial caminhava por todos os arquivos do diretório. Corrigimos a camadaverifypara que arquivos ignorados pelo Git continuem registrados como fatos, mas nunca decidam se o índice do código-fonte ficou obsoleto (STALE_INDEX). - É muito fácil conseguir "−80% de custo" fazendo o agente trabalhar menos:
Uma comparação ingênua contra uma sessão que havia abortado cedo mostrava
−80%de custo e−97%de chamadas de ferramentas — números verdadeiros na aritmética e completamente inúteis na realidade. Por isso, o nossobench_report.pyagora audita automaticamente se a execução produziu uma fração desproporcional do output ou teve turnos insuficientes antes de declarar vitória.
🏁 Conclusão: Menos Adivinhação, Mais Engenharia
O ganho de 20 minutos para 36 segundos e a queda de 82% no custo por tarefa concluída não vieram de trocar para um modelo maior, nem de mágica de prompt engineering. Vieram de aplicar um princípio clássico de ciência da computação aos agentes de IA: não recalcule de forma probabilística, a cada requisição, aquilo que pode ser extraído de forma determinística uma única vez.
Hoje, esse mesmo padrão de envelopes gerados pelo context-graph-engine já alimenta nossos fluxos de trabalho no TechSentry, no ark-streams e na nossa máquina de desenvolvimento.
🔜 No Próximo Artigo da Série...
Saindo dos bastidores da AI Factory e olhando para a superfície pública: na Parte 4 desta série, vou abrir o código da experiência interativa que você está vendo neste próprio portfólio — como escrevi os shaders GLSL de ray-marching relativístico do buraco negro Sagittarius A*, a viagem interestelar de 26.670 anos-luz até a visualização realista da Terra sincronizada em tempo real com os fusos horários (UTC), e como embuti a Rohana (nosso motor conversacional em Clojure + Pathom 3 + Turbovec) para atender visitantes ao vivo 24/7.