Skip to content

stribus/pygerengastos / .agents/skills/reversa-arquitetura-3d

reversa-arquitetura-3d

Verified

Cria visualizações 3D interativas de arquitetura de software usando Three.js, gerando HTML standalone com cenas navegáveis por câmera livre. Use esta skill sempre que o usuário pedir para visualizar arquitetura, módulos, dependências, camadas ou hierarquia de chamadas em 3D. Deve ser ativada quando o usuário mencionar termos como "code city", "cidade de código", "arquitetura 3D", "dependency graph 3D", "module map 3D", "layer stack 3D", "call graph 3D", "architecture tour", "tour pela arquitetura", "visualizar software em 3D", "Three.js" no contexto de software, ou pedir para explorar a estrutura de um sistema com câmera 3D. Funciona com JSON de módulos (nome, pasta, LOC, complexidade) e dependências (grafo orientado). Sempre gera HTML standalone completo. Quando rodada pelo Time Reversa Docs, usa Three.js servido localmente em assets/vendor/ (offline-first).

Arquitetura 3D

Cria visualizações 3D de arquitetura de software usando Three.js. Gera sempre HTML standalone (arquivo único, self-contained) com cena 3D interativa, controles de câmera (mouse, touch, teclado), sidebar de parâmetros e botão de exportar a viewport como PNG.

A skill cobre cinco modos visuais consagrados em visualização de software, cada um com referência dedicada em references/:

ModoQuando usarReferência
Code CityVisão geral de tamanho/complexidade de cada arquivo, padrão "cidade de código"references/CODE_CITY.md
Dependency Graph 3DGrafo de dependências com força repulsiva, nós em 3Dreferences/DEPENDENCY_GRAPH_3D.md
Layer StackCamadas arquiteturais (UI / Domain / Infra) empilhadas com setas de fluxoreferences/LAYER_STACK.md
Call Graph 3DÁrvore de chamadas explorável em profundidadereferences/CALL_GRAPH_3D.md
Architecture TourCâmera animada percorrendo a cena com overlay narrativoreferences/ARCH_TOUR.md

Padrões compartilhados de Three.js, lighting, controles e performance vivem em references/THREE_PATTERNS.md. Cenários de erro e tratamento em references/ERRORS.md.

Fluxo de Trabalho

1. Receber os dados

Os dados podem vir de:

  • JSON inline: usuário fornece modules.json (lista de módulos) e/ou deps.json (grafo de dependências).
  • Caminho de arquivo: usuário aponta para JSONs em .reversa/documentation/assets/data/ (gerados pelo agente /reversa-documentation).
  • Solicitado ao usuário: se a skill é invocada sem dados, perguntar caminho ou pedir colagem inline.

Schema esperado de modules.json:

[
  {
    "name": "src/auth/login.ts",
    "folder": "src/auth",
    "loc": 142,
    "complexity": 8,
    "type": "code"
  }
]

Schema esperado de deps.json (orientado):

{
  "nodes": [{ "id": "src/auth/login.ts" }, { "id": "src/auth/jwt.ts" }],
  "edges": [{ "from": "src/auth/login.ts", "to": "src/auth/jwt.ts", "weight": 1 }]
}

2. Escolher o modo

Se o usuário especificou o modo, usar aquele. Se não, sugerir 2 ou 3 opções com base nos dados:

Tipo de dadoModos recomendados
modules.json com LOC + complexidadeCode City (padrão), Layer Stack se houver pastas/camadas claras
deps.json com muitas arestasDependency Graph 3D, Code City colorindo hot path
Trace de execução ou call graphCall Graph 3D
Pedido explícito de apresentaçãoArchitecture Tour combinando duas das anteriores

Quando o número de nós ultrapassa 500, aplicar agrupamento por pasta automaticamente e avisar o usuário (registrar a decisão no rodapé do HTML gerado).

3. Gerar o código

Consultar references/THREE_PATTERNS.md para setup base (renderer, cena, câmera, iluminação, OrbitControls). Consultar a referência específica do modo escolhido para o algoritmo de layout e materiais.

Regras fundamentais:

  1. HTML standalone: arquivo único .html com tudo embutido (CSS, JS, dados inline em <script id="data">). Quando rodada pelo Time Reversa Docs, os dados vêm de window.RV_DATA.modules e window.RV_DATA.deps (carregados pelo assets/js/data.js que o Publisher gera) e o <script id="data"> fica vazio ou ausente. Páginas finais nunca fazem fetch() para arquivos locais (quebra via file://).
  2. Three.js local: usar <script src="assets/vendor/three.min.js"></script> apontando para o arquivo baixado pelo Publisher (versão pinada em agents/reversa-docs-publisher/references/vendor-pins.yaml, hoje three@0.147.0 IIFE). Em modo invocação isolada fora do time Docs, aceite CDN como fallback (https://unpkg.com/three@0.147.0/build/three.min.js), mas nunca misture versões.
  3. OrbitControls local: usar <script src="assets/vendor/OrbitControls.js"></script> (também IIFE, compatível com three@0.147). Não use examples/jsm/... enquanto a skill não migrar para importmap + ESM.
  4. Renderer: WebGLRenderer com antialiasing, pixelRatio do device.
  5. Iluminação: HemisphereLight + DirectionalLight com sombras suaves. Para Code City, AmbientLight extra para preencher.
  6. Câmera: PerspectiveCamera, posição inicial olhando o centro da cena de cima e levemente angulada. Distância derivada do tamanho da cena.
  7. Performance: usar InstancedMesh quando há mais de 200 elementos do mesmo tipo. Limite máximo de 5.000 prédios no Code City sem agrupamento.
  8. Responsividade: handler de resize redimensiona renderer e ajusta aspect ratio da câmera.
  9. Sidebar: lado direito, controles sliders/checkboxes/botões em layout vertical. Cada controle tem ID estável para localStorage.
  10. Exportar PNG: botão captura o canvas via renderer.domElement.toBlob().

4. Estrutura do HTML gerado

<!DOCTYPE html>
<html lang="pt-BR">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Arquitetura 3D | <!-- PROJECT_NAME --></title>
    <script src="assets/vendor/three.min.js"></script>
    <script src="assets/vendor/OrbitControls.js"></script>
    <script src="assets/js/data.js"></script>
    <style>
        body { margin: 0; overflow: hidden; font-family: system-ui, sans-serif; }
        #scene { position: fixed; inset: 0; }
        #sidebar { position: fixed; top: 0; right: 0; width: 280px; height: 100vh; padding: 16px; background: rgba(15,15,20,0.85); color: #eaeaea; overflow-y: auto; }
        #loader { position: fixed; inset: 0; display: flex; align-items: center; justify-content: center; font-size: 18px; background: #0a0a10; color: #eaeaea; }
        /* Estilo Reversa: variantes derivam de data-style do <body> via CSS externo do agente */
    </style>
</head>
<body data-style="exploratory">
    <div id="loader">Carregando cena 3D...</div>
    <canvas id="scene"></canvas>
    <aside id="sidebar">
        <h3>Controles</h3>
        <!-- SIDEBAR_CONTROLS -->
        <button id="reset">Reset</button>
        <button id="export-png">Exportar PNG</button>
    </aside>
    <script id="data" type="application/json"><!-- DATA_JSON --></script>
    <script>
        // OrbitControls IIFE expõe THREE.OrbitControls globalmente.
        // 1. Carregar dados de window.RV_DATA quando rodando no time Docs,
        //    ou do <script id="data"> em modo standalone.
        // 2. Configurar cena, câmera, renderer, iluminação
        // 3. Construir geometria conforme o modo (Code City, Dep Graph, etc)
        // 4. Conectar sidebar aos parâmetros da cena
        // 5. Loop de renderização e tratamento de eventos
    </script>
</body>
</html>

5. Salvar e entregar

O output é sempre HTML standalone. Salvar no caminho indicado pelo agente orquestrador (geralmente .reversa/documentation/arquitetura.html).

Quando invocada fora do contexto do /reversa-documentation, perguntar caminho de destino ou usar <modo>-<timestamp>.html no diretório atual.

Diretrizes de qualidade

  • Câmera intuitiva: posição inicial mostra a cena inteira; OrbitControls com damping para movimento suave.
  • Materiais coesos: paleta limitada (5 a 8 cores no máximo); cores carregadas indicam atributo (ex: vermelho para hot path, azul para módulos leves).
  • Labels legíveis: usar CSS2DRenderer ou sprites; labels só aparecem em hover ou zoom acima de um threshold para não poluir.
  • Loader visível: cena começa com overlay "Carregando cena 3D..." que some quando o requestAnimationFrame da primeira frame termina.
  • Fallback gracioso: se Three.js não carregar (sem internet), mostrar mensagem "Esta visualização requer carregar a biblioteca Three.js. Conecte-se à internet e recarregue."
  • Acessibilidade básica: navegação por teclado nos botões da sidebar; foco visível.
  • Idioma: comentários e textos visíveis em pt-br. Sem travessão.

Diretrizes de código

  • Modularidade: separar criação da cena, construção da geometria e gerenciamento de interação em funções com nomes claros.
  • Sem dependências além de Three.js e OrbitControls (locais em assets/vendor/): não importar GSAP, dat.GUI, ou qualquer outra lib sem necessidade clara.
  • Constantes nomeadas no topo: cores, sizes, thresholds em um bloco de configuração visível.
  • Dispose: ao trocar de modo ou regenerar, chamar geometry.dispose() e material.dispose() para evitar vazamento.
  • Performance check: antes de renderizar, contar nós; se > 5.000 sem instanced mesh, abortar e mostrar aviso.

Tratamento de erros

Consultar references/ERRORS.md para cenários comuns (CDN inacessível, JSON malformado, projeto vazio, WebGL não suportado, etc).

rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall