Módulo 2.2 - Pipeline de agentes e knowledge graph

Cinco agentes em série passam estado por .understand-anything/intermediate/. O resultado final é o knowledge-graph.json, validado contra o schema do core.

Captura do dashboard mostrando o knowledge graph renderizado após o pipeline rodar — O resultado do pipeline aberto no dashboard: nós coloridos por camada, arestas representando dependências, sidebar com info do nó selecionado.

🔭 project-scanner: o agente que abre o trabalho

Tudo começa com o project-scanner. Ele faz três coisas que ninguém quer fazer manualmente: enumera arquivos respeitando .gitignore, detecta linguagens e frameworks pelo conjunto de extensões e arquivos-pista (pnpm-lock.yaml, requirements.txt, Cargo.toml), e pré-resolve o importMap com tree-sitter.

🎯 Por que pré-resolver importMap?

Sem isso, cada file-analyzer teria que parsear o arquivo de novo só pra responder "quem este arquivo importa?". Multiplicado por milhares de arquivos, vira hora de LLM.

Com o importMap pronto, o agente recebe o trabalho mastigado: aqui está seu arquivo, aqui estão os imports já resolvidos pra caminhos absolutos. Só pensa no que importa: o que esse código faz?

💡 Dica prática

No comando /understand src/frontend, o scanner recebe um escopo. Em monorepos gigantes, isso evita rodar análise no repo inteiro quando você só mexe numa parte. Use sempre que possível.

Glob + ignore

Respeita .gitignore

Language detect

Por extensão e pista

importMap

Pré-resolvido via tree-sitter

Scope

Subdiretório opcional

📂 file-analyzer: paralelismo é o segredo

O file-analyzer é o agente que mais aparece: rodam até 5 em paralelo, processando 20-30 arquivos por batch. Para cada arquivo, ele produz nós (function, class, file) e arestas (imports, calls, inheritance). É a fábrica.

Batch arrives

20-30 arquivos por batch

O scanner entrega um lote já com importMap. O agente lê os arquivos da batch em uma única chamada — economia de round-trip.

Extract + describe

Estrutura + semântica

Combina o output do tree-sitter (definições, calls) com a leitura LLM (resumo em inglês claro, tags, layer hint). Híbrido.

Write intermediate JSON

Persistência fora do contexto

O resultado vai pra .understand-anything/intermediate/<hash>.json. Não volta pro contexto da conversa — é disco.

Fingerprint check

Incremental updates

Antes de reanalisar, compara o hash do arquivo com o anterior. Igual = pula. Re-run incremental = só os arquivos que mudaram.

📊 Tuning de paralelismo

5 paralelos × 25 arquivos — sweet spot atual
Mais paralelos: rate-limit do provedor LLM bate antes do throughput melhorar
Batch maior: contexto longo demais degrada qualidade do summary
Batch menor: overhead de round-trip explode

5 paralelos

Default concurrency

20-30 / batch

Tamanho ótimo

Fingerprint

Skip incremental

Intermediate

Disco, fora do contexto

🏛️ architecture-analyzer: pintar as camadas

Quando o dashboard mostra o grafo colorido por camada arquitetural — API, Service, Data, UI, Utility — a etiqueta veio daqui. O agente lê todos os nós já produzidos e atribui uma camada por heurística + julgamento LLM.

✓ Sinais fortes (heurística)

✓Path com /api/, /routes/, /controllers/ → API
✓Suffix Service.ts, UseCase.ts → Service
✓/components/, .tsx, JSX → UI
✓/db/, /models/, Repository.ts → Data

✗ Quando heurística falha

✗Codebase sem convenção (pastas src/foo/, src/bar/)
✗Arquivo "utilitário" que na verdade orquestra negócio
✗Hybrid frameworks (Next.js: app/, pages/, lib/)

💡 Dica prática

Cada nó recebe um confidence score. No dashboard, nós com baixa confiança aparecem com borda tracejada. Bom indicador de onde a arquitetura está ambígua — vale revisar.

5 camadas

API, Service, Data, UI, Util

Heurística first

LLM como tie-breaker

Confidence

Visualizado no grafo

Fallback

"unclassified" se nada bate

🧭 tour-builder: ensinar, não só mostrar

O tour-builder transforma o grafo em uma sequência didática. Ordenação topológica + narrativa LLM = "comece pelo main.ts, depois config/, depois auth.ts...". É o diferencial: ferramentas burras só mostram. Esta ensina.

🎯 Anatomia de um tour

•id, title, persona — para quem é o tour
•stops[] — array ordenado de {nodeId, narration}
•order rationale — por que essa sequência
•estimated minutes — quanto tempo o tour leva

tours[] no JSON (exemplo)

{
  "id": "auth-flow",
  "title": "Como funciona o login",
  "persona": "junior-dev",
  "estimatedMinutes": 8,
  "stops": [
    { "nodeId": "f_routes_auth", "narration": "Entrada da requisição..." },
    { "nodeId": "f_authService", "narration": "Aqui validamos a senha..." },
    { "nodeId": "f_jwtIssue",    "narration": "E aqui emitimos o token..." }
  ]
}

Topological order

Dependência primeiro

Narrative

Voz LLM consistente

Persona-aware

Tour diferente por nível

Stops anchored

Referência a nodeId

🔍 graph-reviewer: a última linha de defesa

O graph-reviewer roda no fim. Função única: garantir que o grafo é internamente consistente. Aresta apontando pra nó que não existe? Tour com stop quebrado? Layer fora da taxonomy? Erro antes de persistir — o usuário não vai descobrir num banner vermelho no dashboard.

🚨 O que ele verifica

Referential integrity: toda aresta tem source/target válidos
Tour stops: todos os nodeId referenciados existem
Layer taxonomy: camadas dentro do conjunto permitido
Required fields: nenhum nó sem id, kind, label
Cycle warnings: ciclos detectados quando não deveriam existir

📊 Dois modos

Inline (default): só validações estruturais determinísticas — rápido, barato
Full LLM review (--review): agente lê o grafo e questiona "esse nó faz sentido?", "essa camada parece certa?" — caro, mas pega problemas semânticos

💡 Dica prática

Use --review antes de commitar um grafo pro time. Adiciona ~1 minuto, mas evita "o dashboard tá esquisito" virar issue.

Inline check

Estrutural, sempre

--review

LLM completo

Fail fast

Antes de persistir

Schema reuse

Mesmo do dashboard

💾 .understand-anything/: o disco onde tudo mora

Esse diretório (criado no projeto-alvo, não no Understand Anything) é onde o pipeline grava tudo. Saber o que commitar e o que ignorar faz diferença entre PR limpo e PR com 40 MB de JSON sem motivo.

Estrutura

.understand-anything/
├── knowledge-graph.json    # Output canônico — COMMITAR
├── domain-graph.json       # /understand-domain — COMMITAR
├── intermediate/           # Scratch dos agentes — IGNORAR
│   └── <hash>.json
├── diff-overlay.json       # Local, para /understand-diff — IGNORAR
└── tours.json              # Walkthroughs — COMMITAR

✓ Commitar

✓knowledge-graph.json — onboarding instantâneo pro time
✓tours.json — walkthroughs versionados
✓domain-graph.json — visão de negócio para PMs

✗ Ignorar (.gitignore)

✗.understand-anything/intermediate/
✗.understand-anything/diff-overlay.json

💡 Dica prática

Grafo > 10 MB? Use git-lfs: git lfs track ".understand-anything/*.json". Evita inflar o histórico do repo.

Canônico

knowledge-graph.json

Scratch

intermediate/ é local

Auto-update

Hook post-commit incremental

git-lfs

Para grafos grandes

📋 Resumo do Módulo

✓

Scanner abre o trabalho — enumera, detecta, pré-resolve importMap.

✓

File-analyzers em paralelo — 5×25, fingerprint pra incremental.

✓

Architecture-analyzer pinta camadas — heurística + LLM, com confidence.

✓

Tour-builder ensina — topological order, narrativa, persona.

✓

Graph-reviewer protege — inline sempre, --review antes de commitar.

✓

.understand-anything/ tem regras — commit grafo, ignore intermediate.

Próximo Módulo:

2.3 — O dashboard: React Flow, Zustand, sidebar e code viewer

← Módulo Anterior Próximo Módulo →