MÓDULO 1.3

⚙️ Fluxo de uso: do /understand ao dashboard

Como rodar o pipeline na prática, os cinco slash commands auxiliares e três casos reais (onboarding, code review e root-cause) onde o Understand Anything paga o próprio uso.

7
Tópicos
45
Minutos
Básico
Nível
Prático
Tipo

Conteúdo detalhado

1

🚀 /understand --full do zero

O ponto de entrada de tudo. Você roda uma linha, espera o pipeline rodar e ganha um grafo + dashboard. Sem configuração adicional.

⌨️ Comando

$ cd ~/projetos/meu-repo
$ claude
> /understand --full

A flag --full roda o pipeline completo (scan + analyze + architecture + tours). Sem ela, o comando faz só scan rápido — bom para projetos pequenos.

1

project-scanner

Lista arquivos, detecta linguagens

Varre o repo, ignora node_modules/build/etc e produz intermediate/scan.json.

2

file-analyzer

Tree-sitter + LLM por arquivo

Extrai símbolos via tree-sitter, sumariza com LLM. Resultados em intermediate/files.json.

3

architecture-analyzer

Layers + domain view

Agrupa nós em camadas (API/Service/Data/UI/Util) e extrai conceitos de domínio.

4

tour-builder + graph-reviewer

Tours guiados + validação

Monta tours por dependência, valida schema final e grava knowledge-graph.json.

5

Auto-trigger /understand-dashboard

Sobe a UI sozinho

O comando dispara o dashboard ao terminar. Intermediates são limpos.

/understand --full project- scanner lista arquivos file- analyzer tree-sitter + LLM architecture- analyzer layers + domínio tour- builder ordem de leitura graph- reviewer valida schema dashboard React Flow /file-content scan.json files.json architecture.json tours.json knowledge- graph.json intermediates gravados em .understand-anything/ — limpos no fim
Pipeline horizontal de /understand --full: cinco agents encadeados, cada um gravando seu intermediate, terminando no dashboard.

💡 Por que escrever em disco e não retornar contexto?

Os agents gravam em intermediate/ em vez de devolver tudo no chat. Assim, o pipeline sobrevive a múltiplas conversas e não polui a janela de contexto do LLM. Resultado: você consegue analisar repos que jamais caberiam num único prompt.

2

📊 /understand-dashboard

Sobe o dashboard React lendo o JSON que /understand deixou no disco. Você roda esse comando quando quer reabrir o dashboard sem regenerar o grafo.

> /understand-dashboard
→ Dev server up at http://localhost:5173
→ Token: ua-dev-7f3a... (auto)
→ Allowlist: 412 paths
Animação do dashboard rodando em localhost após /understand-dashboard: usuário navega pelo grafo estrutural e abre nós.
É isso que abre no navegador depois de /understand-dashboard — grafo estrutural ao vivo em localhost:5173.

✓ Quando usar

  • ✓Você fechou o dashboard e quer reabrir.
  • ✓Outro dev clonou o repo com o JSON versionado.
  • ✓Você quer compartilhar o link local com alguém na rede.

✗ Quando NÃO usar

  • ✗Código mudou bastante — rode /understand de novo.
  • ✗Erro de schema validation — apaga o JSON e regenera.
  • ✗Para deploy público — é dev server, não produção.
3

💬 /understand-chat, /understand-explain

Para quem prefere conversa a navegar no grafo. Dois comandos cobrem 90% dos casos textuais.

💬 /understand-chat

> /understand-chat
? onde o sistema valida o token JWT?
→ src/auth/login.ts:validateToken (chamada em 4 lugares)
→ src/middleware/auth.ts:authGuard (entry point principal)
→ Tour relacionado: "Auth flow" (5 nós)

Diferente de um chatbot genérico, a resposta cita nós reais do grafo — clique e cai no dashboard.

🧠 /understand-explain

> /understand-explain src/billing/charge.ts
→ Resumo: cobra cartão via Stripe, retorna invoice id.
→ Chamado por: src/api/checkout.ts, src/jobs/retry.ts
→ Depende de: src/billing/stripe-client.ts, src/db/invoices.ts
→ Risco de regressão: alto (fan-in = 7)

💡 Diferença vs "ChatGPT lê o arquivo"

O /understand-explain usa o grafo para incluir contexto estrutural: quem chama e quem é chamado. Resposta deixa de ser "esse arquivo faz X" e vira "esse arquivo faz X, é usado em Y, e mudar aqui afeta Z".

4

🌿 /understand-diff: impacto antes do merge

Code review honesto exige saber o que muda e o que é afetado. Ler 40 arquivos linha a linha não faz isso — o diff faz.

> /understand-diff main..feature/new-billing
→ Nós alterados: 12
→ Nós afetados (fan-in): 38
→ Camadas tocadas: Service, Data
→ Hot spots no caminho: charge.ts (fan-in 7), invoice.ts (fan-in 5)
→ Risco geral: ALTO

📊 O que olhar primeiro num PR

  • Nó alterado com fan-in alto — qualquer bug propaga muito.
  • Mudança cruza camadas (ex: UI mexendo em Data) — possível violação arquitetural.
  • Surgiu ciclo novo — refactor pendente, vai cobrar juros.
  • Aresta removida com fan-in > 0 — quebra esperando acontecer.
5

🎓 /understand-onboard: roteiro para dev novo

Em vez de "lê o README", o comando devolve uma sequência ordenada de arquivos para ler, com explicação curta de cada um.

> /understand-onboard --persona=backend
1. src/server.ts       # entry point HTTP
2. src/api/routes.ts   # mapa de endpoints
3. src/db/connection.ts # conexão Postgres
4. src/auth/login.ts   # fluxo de login (hot spot)
5. src/billing/charge.ts# cobrança Stripe (crítico)
...

Ordem por dependência

Topológica, não alfabética

Persona-adaptive

backend, frontend, fullstack

Checklist marcável

Acompanhe o progresso

Hot spots marcados

Leia com calma

6

🏥 Três casos reais

Para fechar a trilha, três histórias curtas de uso real — uma para cada persona principal.

A

Caso 1 — Dev novo no time, primeiro PR em 4 dias

Persona: Learn · Tempo: dia 1 a 4

Dia 1: roda /understand --full e /understand-onboard. Dia 2 a 3: segue a sequência, abre código no viewer. Dia 4: usa /understand-explain no módulo que ela vai mexer e abre o PR. Sênior só revisa, não precisa ensinar do zero.

B

Caso 2 — Review de PR de 40 arquivos em 20 minutos

Persona: Review · Tempo: 20 min

Reviewer roda /understand-diff main..feature/x. Vê que 3 nós alterados têm fan-in > 5 e que apareceu um ciclo. Foca a review nesses 3 arquivos + cobra refactor do ciclo. O resto é detalhe — aprovação em 20 min, com risco endereçado.

C

Caso 3 — Suporte caçando bug de produção

Persona: Debug · Tempo: MTTR cai 60%

Ticket: "pagamento dobrou para usuário X". Suporte abre /understand-chat: "onde processa pagamento e que jobs podem reentrar?". Resposta cita charge.ts e jobs/retry.ts. Layer view mostra que o retry chama charge sem idempotência. Bug encontrado em 15 min.

✓ Padrão dos três casos

  • ✓Pergunta clara antes de abrir código.
  • ✓Decisão baseada em estrutura (fan-in, layer, ciclo).
  • ✓Trabalho concentrado em poucos nós críticos.

✗ Anti-padrões

  • ✗"Abrir e ler" sem hipótese.
  • ✗Aprovar PR só porque o diff "parece pequeno".
  • ✗Caçar bug por grep aleatório.
7

🧰 Comando-cheatsheet

Tabela mental dos seis slash commands para colar na sua mesa enquanto a memória muscular não chega.

/understand           # escaneia + monta grafo + abre dashboard
/understand-dashboard  # só sobe a UI (sem rescanear)
/understand-chat      # pergunta livre, resposta cita nós
/understand-explain   # explica arquivo/função com contexto
/understand-diff      # impacto de uma branch / commit
/understand-onboard   # roteiro de leitura para dev novo

💡 Regra de bolso

Comece sempre por /understand. Sem grafo nenhum dos outros comandos faz sentido. Depois disso, mantenha o grafo regenerado a cada release — versione o JSON se o time é grande.

✅ Resumo do Módulo

✓
/understand --full — pipeline completo num comando, auto-abre o dashboard.
✓
/understand-dashboard — reabre a UI sem rescanear.
✓
/understand-chat — pergunta livre com resposta ancorada em nós.
✓
/understand-explain — explica trecho com contexto estrutural.
✓
/understand-diff — raio de impacto de PR antes do merge.
✓
/understand-onboard — sequência de leitura por dependência.
✓
Casos reais validam ROI — onboarding em dias, review em minutos, MTTR menor.

Próxima Trilha:

Trilha 2 — Pipeline & Agentes (por dentro do project-scanner, file-analyzer e companhia)

← Módulo Anterior Próxima Trilha →