vue-debug-guides

Visão geral da skill vue-debug-guides

Para que serve a skill vue-debug-guides

vue-debug-guides é uma skill de troubleshooting para Vue 3 focada em diagnosticar bugs em runtime, warnings, falhas no carregamento assíncrono, comportamentos inesperados de reatividade e problemas de SSR ou hydration mismatch. Ela é mais útil quando você já tem um comportamento quebrado ou confuso e precisa de um caminho de depuração mais direcionado do que um prompt genérico como “me ajuda a debugar Vue”.

Quem deve usar vue-debug-guides

O melhor perfil de uso são desenvolvedores trabalhando em apps Vue 3 reais com sintomas como re-renders inesperados, refs que não atualizam, handlers de evento duplicados, falhas em async components, erros de carregamento de rota ou problemas de timing no DOM. Também é especialmente útil para equipes que querem orientação específica por tipo de problema, em vez de tutoriais amplos sobre o framework.

O trabalho real que ela resolve

O objetivo aqui não é aprender Vue do zero. É pegar um bug report vago, reduzir o problema até chegar na armadilha específica do Vue que provavelmente está causando o erro, e então aplicar o padrão de correção certo com menos tentativas frustradas. O valor de vue-debug-guides está em ligar sintomas comuns a gotchas concretos e exemplos de correção.

O que diferencia isso de um prompt comum

Um prompt comum costuma gerar conselhos amplos de debugging. A vue-debug-guides skill funciona melhor quando o problema provavelmente depende da semântica do Vue: regras de reatividade, restrições de computed, comportamento de async components, Suspense, keep-alive, fallthrough attrs, event modifiers, nextTick ou limitações de script setup. O repositório é organizado exatamente em torno desses modos de falha, então as respostas tendem a ser mais específicas e mais acionáveis.

Principais motivos para adotar

O motivo mais forte para instalar vue-debug-guides é a cobertura de edge cases de alto atrito que são fáceis de diagnosticar errado olhando só para os sintomas do app. O conjunto de referências inclui temas práticos como tratamento de erro em async components, por que defineAsyncComponent não deve ser usado em rotas do Vue Router, por que Suspense pode suprimir as opções de loading e erro de async components, e por que refs de componente podem quebrar após a reativação com keep-alive.

O que ela não substitui

Essa skill não substitui fundamentos de Vue, ferramentas de profiling da aplicação nem a documentação do framework. Se o que você precisa é orientação de arquitetura, convenções de estilo ou “boas práticas” mais amplas, o próprio repositório aponta vue-best-practices como opção mais adequada. Use vue-debug-guides for Debugging quando você já tiver uma falha, warning ou comportamento não óbvio para explicar e corrigir.

Como usar a skill vue-debug-guides

Contexto de instalação de vue-debug-guides

Instale a partir do repositório vuejs-ai/skills no ambiente com suporte a skills que você já usa. Um padrão comum é:

npx skills add vuejs-ai/skills --skill vue-debug-guides

As evidências do repositório não mostram um comando de instalação embutido dentro de SKILL.md, então quem usa o diretório deve tratar essa skill como conteúdo-first: instale no ambiente do seu agente e depois invoque com uma tarefa concreta de debugging em Vue.

Comece pelos arquivos certos

Leia primeiro skills/vue-debug-guides/SKILL.md para entender o mapa entre sintomas e referências. Depois abra os arquivos específicos em reference/ que mais se aproximam do seu problema. Boas leituras iniciais incluem:

• reference/async-component-error-handling.md
• reference/async-component-suspense-control.md
• reference/async-component-vue-router.md
• reference/cleanup-side-effects.md
• reference/component-ref-requires-defineexpose.md
• reference/dom-update-timing-nexttick.md
• reference/computed-no-side-effects.md
• reference/attrs-event-listener-merging.md

Este repositório é fortemente baseado em referências, então a adoção fica mais fácil se você tratá-lo como uma árvore de decisão, não como um guia linear único.

Relacione seu bug ao sintoma mais próximo

O melhor uso de vue-debug-guides começa pela formulação do sintoma. Em vez de pedir “debuga meu componente”, descreva a falha observável:

• “Ref atualiza no script, mas o template continua desatualizado”
• “Async route component nunca mostra meu loading UI”
• “Hydration warning aparece só no primeiro carregamento”
• “Click handler dispara duas vezes em um botão encapsulado”
• “Método no ref de componente filho vira undefined depois de trocar de aba”

Essa abordagem orientada por sintoma ajuda a skill a apontar para o gotcha relevante, em vez de devolver conselhos genéricos sobre Vue.

Que entrada a skill precisa para funcionar bem

Forneça contexto suficiente para um diagnóstico específico de Vue:

• versão do Vue e peças principais do ecossistema: Vue Router, Pinia, SSR/Nuxt, Vite
• se o problema acontece só no client, só em SSR ou só na hydration
• código mínimo do componente ou da rota
• texto exato do warning ou erro
• comportamento esperado vs comportamento real
• se Suspense, keep-alive, async components ou script setup estão envolvidos

Sem esses detalhes, a skill ainda pode sugerir causas prováveis, mas a qualidade da resposta cai porque muitos bugs em Vue compartilham sintomas parecidos.

Transforme um pedido vago em um prompt forte

Prompt fraco:

Use vue-debug-guides to debug why my Vue component is broken.

Prompt melhor:

Use vue-debug-guides to diagnose a Vue 3 issue. In a route component loaded with Vue Router, I wrapped the page in defineAsyncComponent and added loadingComponent, but the loading state never appears and navigation feels inconsistent. We use Vue Router 4 and Vite. Explain the likely mistake, show the correct route lazy-loading pattern, and tell me when Suspense would change the behavior again.

Por que isso funciona: inclui o sintoma, a API suspeita, o ecossistema e o formato de resposta desejado.

Fluxo prático de uso de vue-debug-guides

1. Descreva o sintoma em uma frase.
2. Cole a menor amostra de código que ainda reproduza o problema.
3. Peça ao agente para identificar qual regra específica do Vue provavelmente está sendo violada.
4. Peça uma versão corrigida, não cinco alternativas.
5. Se necessário, peça um checklist curto para validar a correção no DevTools ou no console do navegador.

Isso mantém a skill focada em diagnóstico e correção, sem desviar para refatorações genéricas.

Caminhos de referência de alto valor neste repositório

Vários arquivos de referência cobrem problemas que costumam consumir muito tempo de debugging:

• async-component-vue-router.md: erros em lazy loading de rotas
• async-component-suspense-control.md: por que loadingComponent e errorComponent parecem ser ignorados
• async-component-keepalive-ref-issue.md: refs que somem após reativação
• attrs-event-listener-merging.md: comportamento de clique duplicado por listeners em fallthrough
• computed-no-side-effects.md: mutações escondidas dentro de getters de computed
• dom-update-timing-nexttick.md: leituras do DOM acontecendo antes de o Vue aplicar os updates

Se o seu bug estiver próximo de um desses limites, fazer a instalação de vue-debug-guides provavelmente vale a pena, porque prompts genéricos costumam deixar passar esses detalhes.

Dicas que melhoram de forma concreta a qualidade das respostas

Peça ao agente para fazer estas três coisas, nesta ordem:

1. Nomear a regra ou gotcha provável do Vue.
2. Apontar a linha de código ou o padrão exato que dispara o problema.
3. Produzir a menor correção segura possível.

Essa estrutura evita respostas longas e especulativas e faz a skill se comportar mais como uma assistente de debugging do que como uma tutora.

Quando usar isto em vez de ajuda geral de Vue

Use o modo vue-debug-guides guide quando o bug provavelmente depende do comportamento do framework, e não da sua lógica de negócio. Se o seu problema é “a API retorna dados errados”, essa skill não é a ferramenta principal. Se o problema é “watcher dispara de forma inesperada”, “ref está undefined”, “transition está lenta” ou “o carregamento do componente de rota está se comportando de forma estranha”, o alinhamento é muito melhor.

FAQ da skill vue-debug-guides

vue-debug-guides é bom para iniciantes?

Sim, se a pessoa iniciante já tiver um bug concreto. As referências são práticas e guiadas por exemplos. Mas não é o melhor primeiro recurso para aprender conceitos de Vue do zero, porque o material é organizado em torno de casos de falha, e não em uma sequência didática.

Que tipos de bug vue-debug-guides cobre melhor?

vue-debug-guides é mais forte em debugging de runtime no Vue 3: edge cases de reatividade, uso incorreto de computed, comportamento de watchers, falhas em async components, timing de update no DOM, merge de eventos e attrs, e interações de ciclo de vida de componentes como keep-alive ou Suspense.

Ela ajuda com problemas de SSR e hydration?

Sim. A descrição da skill inclui explicitamente bugs de SSR e hydration. Isso importa porque falhas de hydration geralmente exigem raciocínio específico de Vue, e não apenas debugging frontend genérico. Ainda assim, você deve fornecer o texto exato do warning e deixar claro se o mismatch acontece só em produção ou apenas no primeiro render.

Em que isso difere de um prompting comum?

No prompting comum, é frequente receber respostas do tipo “verifique seu estado”. A vue-debug-guides skill entrega mais valor quando a resposta depende de gotchas conhecidos do Vue, como regras de unwrapping de template refs no topo, updates em batch no mesmo tick ou padrões de carregamento de route components que diferem de async components comuns.

Devo usar para problemas com Vue Router?

Sim, se o problema do router cruza com carregamento de componentes, transitions ou timing de renderização. Uma das referências mais úteis explica que route components devem usar imports dinâmicos diretamente, em vez de defineAsyncComponent, o que é uma fonte comum de confusão.

Quando vue-debug-guides não é uma boa escolha?

Ela não é uma boa escolha para design systems, arquitetura de aplicação, modelagem de estado ou erros genéricos de JavaScript sem relação com a semântica do Vue. Também não é a melhor ferramenta quando você precisa mais de padrões de código do que de orientação de debugging.

Como melhorar o uso da skill vue-debug-guides

Dê ao vue-debug-guides um sintoma reproduzível

A forma mais rápida de melhorar os resultados é fornecer uma reprodução mínima. Inclua o menor componente, configuração de rota ou composable que ainda mostre o problema. Isso ajuda a skill a relacionar seu caso com uma referência existente, em vez de tentar adivinhar em cima de uma base de código grande.

Nomeie os recursos do Vue envolvidos

Mencione se o seu código usa:

• script setup
• defineAsyncComponent
• Suspense
• keep-alive
• Vue Router
• SSR ou hydration
• composables, watchers ou valores computed

Esses detalhes reduzem drasticamente o espaço de busca e muitas vezes apontam direto para um guia correspondente.

Inclua warnings exatos, não paráfrases

Uma paráfrase como “o Vue fala alguma coisa sobre hydration” é muito menos útil do que a mensagem exata do console. A skill foi construída em torno de classes específicas de erro, então o texto bruto do warning melhora a qualidade da correspondência e reduz correções incorretas.

Peça diagnóstico antes de pedir refatoração

Um modo comum de errar é pedir um rewrite cedo demais. Melhor prompt:

Use vue-debug-guides to identify the likely Vue rule being broken here, explain why this symptom happens, and then show the smallest fix.

Essa sequência tende a gerar respostas mais limpas do que começar pedindo uma refatoração completa.

Compare o comportamento esperado com o real

Não cole só o código. Informe:

• o que você esperava
• o que realmente aconteceu
• se isso é consistente ou intermitente
• se mudou depois de adicionar um recurso do Vue como Suspense ou keep-alive

Essas comparações ajudam a skill a distinguir entre um bug de lógica e um bug de interação com o framework.

Faça uma segunda rodada depois da primeira resposta

Se a primeira resposta estiver perto do ideal, mas ainda insuficiente, faça um follow-up mais específico:

• “Now assume this component is inside <Suspense>.”
• “Now account for SSR hydration.”
• “Now explain why the event fires twice.”
• “Now show how to verify the fix with Vue DevTools.”

Essa é a melhor forma de extrair mais valor de vue-debug-guides for Debugging sem abrir demais o escopo da solicitação.

Fique atento aos modos de falha mais comuns

Os resultados pioram quando você:

• cola código demais sem relação com o problema
• omite a mensagem de erro
• não informa se routing ou SSR estão envolvidos
• pede “todas as causas possíveis”
• mistura debugging, refatoração e arquitetura no mesmo pedido

Mantenha a tarefa estreita. Essa skill funciona melhor quando a pergunta é diagnóstica e baseada em evidências.

Use a pasta reference como fonte de aprofundamento

Depois que o agente identificar uma causa provável, abra o arquivo markdown referenciado e compare seu código com os padrões “bad” e “good” do arquivo. Neste repositório, os arquivos em reference/ são a camada de profundidade real. O melhor fluxo com vue-debug-guides guide costuma ser: identificar o tópico provável, ler um arquivo correspondente, aplicar a correção e depois voltar com um segundo prompt, se necessário.