MÓDULO 1.1

🧭 O que é Understand Anything e qual problema resolve

A dor concreta — repositório gigante, contexto zero — e como um plugin que combina LLM com tree-sitter muda a forma de chegar perto de um codebase desconhecido.

6
Tópicos
50
Minutos
Básico
Nível
Teoria
Tipo

Conteúdo detalhado

1

😵 O dev novo no codebase de 200 mil linhas

Você acabou de entrar num time. O repositório tem 200 mil linhas, 14 serviços, 3 linguagens e zero arquiteto disponível para te explicar. Onde começar? A resposta tradicional — "leia o README e vá clicando" — não escala. O Understand Anything nasce para resolver exatamente esse momento.

🎯 A pergunta central

Se um dev sênior gasta 3 a 6 semanas só para "se localizar" num repositório novo, qual o custo agregado para o time? E para a empresa?

  • •Tempo de onboarding caro e diluído em interrupções no time existente.
  • •Decisões tomadas sem contexto — features duplicadas, regressões silenciosas.
  • •Tribal knowledge concentrado em poucas pessoas (bus factor baixo).

📊 Sinais do problema

  • ~6 semanas — tempo médio de onboarding em codebases grandes (Stack Overflow Dev Survey).
  • 40% do tempo de um dev sênior é gasto explicando contexto que já existe em algum lugar.
  • 1 a 3 perguntas/dia de júnior em Slack durante os primeiros meses — todas elas viáveis num grafo.

Onboarding

Tempo até o primeiro PR útil

Bus factor

Quantas pessoas sabem cada parte

Doc rot

README mente a partir do mês 3

Leitura passiva

Ler ≠ entender

2

📚 O que o time faz hoje (e onde quebra)

Antes de comprar a ideia da ferramenta, vale mapear o que já se faz. Cada técnica tem um lugar — e também um teto.

✓ O que funciona

  • ✓Pair com sênior — alta qualidade, baixa escala.
  • ✓ADRs bem escritas — explicam o "porquê", não só o "o quê".
  • ✓Tour repo guiado quando alguém tem tempo de gravar.
  • ✓IDE com "Find usages" — bom para navegação local.

✗ O que falha

  • ✗"Lê o README" — desatualizado a partir do mês 3.
  • ✗grep / ripgrep cego — sem entender semântica de chamada.
  • ✗"Pergunta no Slack" — interrompe o time, não acumula.
  • ✗Vídeos longos — ninguém revê.

💡 Insight

O denominador comum dos métodos que falham: nenhum deles persiste contexto estrutural. Cada nova pessoa redescobre tudo do zero. O Understand Anything inverte isso — o entendimento vira artefato versionável.

3

🔎 A proposta do Understand Anything

Em uma frase: um plugin open-source que vira qualquer codebase num grafo interativo navegável. Em duas frases: tree-sitter extrai a estrutura, LLMs descrevem em inglês, o dashboard mostra tudo junto.

🧬 A fórmula

tree-sitter (estrutura) + LLM (significado) + React Flow (UI) = grafo navegável
  • •Tree-sitter (WASM): parser determinístico, mesma saída sempre, sem alucinação.
  • •LLM: sumariza arquivos, descobre intenção, nomeia padrões.
  • •React Flow + Zustand: dashboard que aguenta milhares de nós.
Captura do dashboard do Understand Anything, com grafo do codebase à esquerda e sidebar de informações à direita.
Captura real do dashboard — grafo + sidebar Info, gerados a partir do knowledge-graph.json

🧩 O que não é

  • Não é "outro chatbot" — produz artefato visual persistente.
  • Não é IDE — não substitui VS Code; complementa.
  • Não é SaaS — roda local, codebase nunca sai da sua máquina.
  • Não é vendor-locked — slash commands portáveis entre Claude Code, Cursor, Copilot, Codex.
4

🧑‍💻 Cinco personas que mais sofrem

Não é só o júnior recém-contratado. Cinco perfis ganham com o grafo — e cada um usa o dashboard de um jeito diferente.

1

Dev novo no time

Persona: Learn

Roda /understand-onboard, segue o tour, faz primeiro PR em dias e não em semanas.

2

Reviewer de PR grande

Persona: Review

Roda /understand-diff para ver o raio de impacto antes de aprovar 40 arquivos.

3

PM tentando estimar

Persona: Plan

Olha o grafo de domínio para entender o quão acoplado o sistema está antes de prometer prazo.

4

Arquiteto em auditoria

Persona: Audit

Usa layer view para identificar violações arquiteturais (ex: UI chamando DB direto).

5

Suporte caçando bug

Persona: Debug

Busca semântica "onde processa pagamento?" e abre os nós relevantes para root-cause.

5

🆚 Tradicional vs Understand Anything

Comparação direta entre o jeito que o time faz hoje e o que muda quando o grafo vira parte do fluxo.

✗ Sem a ferramenta

  • ✗Abrir arquivo aleatório no IDE e tentar adivinhar.
  • ✗Pingar no Slack: "alguém sabe onde X acontece?"
  • ✗Code review baseado em "li o diff, parece ok".
  • ✗Documentação que ninguém mantém.

✓ Com Understand Anything

  • ✓Tour guiado por ordem de dependência.
  • ✓/understand-chat responde com nós e caminhos.
  • ✓/understand-diff mostra o raio de impacto.
  • ✓O grafo é regenerável — não envelhece como prosa.
Antes — arquivos soltos auth.ts db.ts api.ts utils ui.tsx log cli.ts test cfg 200k linhas · sem mapa · grep no escuro /understand Depois — knowledge graph api auth db ui log cli arestas explicam quem chama quem · navegação visual
Antes vs. depois: pasta caótica de arquivos vira grafo navegável com camadas e dependências explícitas.

💡 Princípio

"Documentação é prosa que envelhece; grafo é artefato que se regenera." O Understand Anything muda o tipo de coisa que você produz para entender o código.

6

🌐 Onde roda: agentes suportados

O Understand Anything é um Claude Code plugin — mas via auto-discovery os mesmos slash commands aparecem em Cursor, Copilot, Codex, Gemini CLI, OpenCode, Vibe CLI e similares. Você instala uma vez, usa em qualquer cliente.

📦 Como o agente descobre os comandos

# o cliente lê o plugin manifest
understand-anything-plugin/
├── .claude-plugin/plugin.json
├── .cursor-plugin/plugin.json
├── .copilot-plugin/plugin.json
└── skills/understand.md ← slash command

Cada cliente tem seu manifest. Quando algum não suporta auto-discovery, o README explica o fallback manual.

⚠️ Detalhe importante

O campo model: inherit foi removido dos agents porque era um keyword só do Claude Code — clientes como OpenCode tratavam como model id literal e quebravam com ProviderModelNotFoundError.

Hoje o model é omitido, e cada plataforma usa o default dela. Resultado: portabilidade real.

Auto-discovery

Plugin manifest por cliente

Fallback manual

Cursor às vezes precisa

Multi-cliente

Claude, Cursor, Copilot, Codex

Sem lock-in

Troca de agente sem perder grafo

✅ Resumo do Módulo

✓
Dor real — onboarding em codebases grandes custa semanas e tempo de sênior.
✓
Métodos tradicionais não escalam — README envelhece, Slack interrompe, grep é cego.
✓
A proposta — tree-sitter + LLM + dashboard = grafo persistente.
✓
Cinco personas — Learn, Review, Plan, Audit, Debug.
✓
Multi-cliente — Claude Code, Cursor, Copilot, Codex, sem vendor lock-in.

Próximo Módulo:

1.2 — O conceito de knowledge graph e o dashboard interativo

← Voltar para Trilha Próximo Módulo →