kvngnsn/bughunt

O que bughunt faz?

Testes unitários e a maioria dos testes de UI verificam os caminhos de código que seus autores imaginaram, muitas vezes através de hooks de teste que pulam cliques e teclas reais. As pessoas não usam um aplicativo assim. Elas clicam onde o hook não alcança, pressionam Desfazer depois de tudo, trabalham em uma janela estreita, perdem a rede no meio do caminho e abrem o arquivo estranho que um colega enviou. A maioria dos bugs que encontram já estava lá, e ninguém estava olhando.

Esta skill olha. Ela dirige o aplicativo real com entrada real, uma área de cada vez, e registra cada bug confirmado duas vezes: como um teste com falha que fica no repositório, para que o bug não possa voltar despercebido, e como uma entrada na lista de bugs do repositório, para que alguém o corrija. Uma caçada não corrige o código do produto. Ela encontra, prova e registra.

Modos

• Caçar (o padrão): escolha uma área, caçe-a, registre as descobertas, atualize a rotação. Uma área por execução mantém a caçada profunda o suficiente para encontrar bugs reais.
• Configurar: o repositório não tem como dirigir o aplicativo de ponta a ponta, ou não possui os limites em references/boundaries.md. Construa o menor caminho de passagem que possa executar um recurso em cada superfície (references/walkthroughs.md), depois caçe.
• Varredura: execute todos os caminhos de passagem existentes e relate o que é novo, o que mudou e o que foi corrigido desde a última execução. Uma varredura encontra regressões, não novos tipos de bugs; combine-a com caçadas.
• Regras: adicione uma das regras em references/invariants.md ao caminho, para que seja executada em cada passo de cada caminho de passagem. Uma única regra (por exemplo "Desfazer restaura o estado anterior exato") pode revelar uma dúzia de bugs em recursos que ninguém pensaria em programar.

1. Aprenda as regras básicas primeiro

Leia os arquivos de instrução do repositório (CLAUDE.md, AGENTS.md, CONTRIBUTING, quaisquer regras ou notas de entrega), o README do que executa o aplicativo e os testes de ponta a ponta existentes. Descubra:

• Como iniciar cada superfície que o aplicativo tem: servidor de desenvolvimento, build desktop, simulador mobile. Uma superfície é um host (web, desktop, mobile) em uma aparência (claro, escuro, alto contraste) em um tamanho (largo, estreito, telefone).
• Onde os bugs são rastreados (um arquivo de bugs, uma lista de tarefas, um rastreador de problemas) e o formato das entradas usadas lá. Escreva nesse formato.
• O que um teste nunca deve tocar: contas reais, arquivos de usuário reais, dados de produção, e-mail real, pagamentos, a área de transferência do usuário, impressora e navegador, a cópia instalada do aplicativo. Leia references/boundaries.md e coloque todo limite aplicável em prática antes de dirigir qualquer coisa. Esta é a parte de uma caçada que pode causar danos reais, então vem primeiro.
• Se o repositório proíbe qualquer outra coisa (push, acesso de rede, serviços pagos, iniciar agentes). Essas regras prevalecem sobre esta skill.

Pergunte apenas quando a resposta mudar o que você pode tocar. Caso contrário, escolha e escreva a suposição no relatório da caçada.

2. Escolha a área e liste o que ela faz

Use a área que a pessoa nomeou. Caso contrário, leia bughunt/areas.md (crie-o a partir de templates/areas.md na primeira execução) e escolha, nesta ordem: uma área nunca caçada, depois uma alterada desde sua última caçada (git log em seus caminhos), depois a mais antiga. Uma área é um conjunto de recursos que uma pessoa usa junto: o editor de documentos, o navegador de arquivos, login e contas, configurações, compartilhamento, pagamentos.

Liste os recursos da área a partir do que o repositório tem: um registro de recursos, os menus e a lista de comandos, rotas, as páginas de ajuda, os pontos de entrada do código. Cada recurso recebe pelo menos uma passagem em cada superfície.

3. Caçe

Para cada recurso, primeiro faça o que uma pessoa faz com ele, do início ao fim, em arquivos sintéticos realistas. Depois, trabalhe com references/checklist.md. É uma lista de movimentos de usuário hostil que quebram aplicativos repetidamente: Desfazer após cada passo, apenas teclado, janela estreita, modo escuro, offline no meio, o maior e o mais quebrado arquivo, uma ida e volta através de outro formato, a mesma coisa em duas abas, uma falha de propósito.

Dirija o aplicativo com eventos de entrada reais (cliques, pressionamentos de tecla, arrastos, digitação) no ritmo de uma pessoa. Um script age mais rápido que uma pessoa, então dê a um clique uma pequena pausa antes da próxima ação e deixe meio segundo entre duas alterações que você espera desfazer separadamente. Caso contrário, você registrará artefatos de tempo como bugs.

Observe cada passo em busca de:

• o resultado errado, ou um resultado certo que não persiste (desaparece após recarregar, salvar, Desfazer ou trocar de abas)
• trabalho perdido: edições, configurações, seleção, posição de rolagem
• Desfazer que retira demais, de menos, ou nada
• um comando que não faz nada, funciona apenas a partir de um de seus pontos de entrada, ou não está desabilitado quando não pode ser executado
• texto de erro bruto: stack traces, códigos de erro, caminhos internos
• erros de console, travamentos, janelas em branco, congelamentos
• texto muito fraco, cortado, sobreposto ou quebrado no meio da palavra (as verificações de captura de tela em references/invariants.md pegam a maior parte disso sozinhas)
• o mesmo passo se comportando de forma diferente em outra superfície

Escreva cada candidato quando o vir, com a superfície, o passo e o que você esperava. Então continue; confirme ao final do recurso.

4. Confirme antes de registrar

Uma caçada é tão boa quanto suas descobertas são verdadeiras. Para cada candidato:

1. Reproduza-o duas vezes a partir de um estado limpo, no ritmo de uma pessoa, manualmente ou com um script mínimo. Se não reproduzir, descarte-o ou registre-o como "Não verificado:" com o que você viu e onde.
2. Descarte o teste. Tempo (veja acima), um seletor que combinou com o elemento errado, os próprios stubs do teste, uma janela que não estava focada, o ponteiro repousando em algo com um estado de hover. Uma descoberta que vai e vem com onde o ponteiro repousa é real, mas precisa de uma posição de ponteiro fixa em seu teste.
3. Encontre a causa quando for barato. Leia o código no local provável e nomeie o arquivo e a função. Não gaste muito tempo aqui; quem corrigirá gastará.
4. Verifique o rastreador. Se uma entrada já cobrir isso, adicione a nova superfície ou detalhe a essa entrada em vez de criar uma nova.
5. Agrupe por causa. Vários sintomas frequentemente compartilham uma causa (uma ligação de tecla ausente pode quebrar Desfazer em cinco editores em um host). Diga isso, para que a correção aconteça uma vez.

5. Registre cada bug confirmado

• Um teste com falha primeiro. Adicione um passo ao caminho de passagem do recurso (ou um novo caminho de passagem) cuja expectativa declare o que deve acontecer. Execute-o e verifique se ele falha, e falha pelo motivo do bug, não por outra coisa. Ele passa assim que o bug for corrigido. Nunca enfraqueça uma expectativa existente ou verificação de captura de tela para fazer uma execução passar. Se uma verificação estiver errada, diga por que no relatório e deixe para uma pessoa.
• Depois a entrada do bug, no final da lista de bugs do repositório, em seu formato, usando templates/bug-entry.md: o sintoma nas palavras de um usuário, o que acontece contra o que deveria, os números medidos, onde no código, qual teste o protege e em quais superfícies ele aparece.
• Nenhuma alteração no código do produto em uma caçada, a menos que a pessoa tenha pedido correções. Corrigir enquanto avança esconde a descoberta e mistura dois tipos de revisão.
• Confirme os novos testes e as entradas de bug se as regras do repositório permitirem, organizando os arquivos por nome. Não faça push a menos que a pessoa tenha dito para.

6. Relate e rode

Escreva o relatório da caçada a partir de templates/hunt-report.md: a área, as superfícies, cada descoberta com seu teste e entrada, os candidatos que você descartou e por quê, o que você não pôde testar e grupos de correção sugeridos por causa. Atualize a linha da área em bughunt/areas.md (data, commit, descobertas).

Termine dizendo à pessoa, em linguagem simples: quantos bugs foram confirmados, os três piores, os grupos de correção e a próxima área que a rotação escolheria.

Continue encontrando eles

Uma caçada concluída deixa testes que pegam os mesmos bugs voltando. Novos bugs precisam de novos olhares:

• Caçe novamente em rotação. Recaçe uma área após grandes alterações nela.
• Transforme um bug que continua aparecendo em novos lugares em uma regra (references/invariants.md) para que cada passo o verifique.
• Todo bug que uma pessoa relatar se torna um passo de caminho de passagem antes de ser corrigido.
• Execute todo o caminho antes de cada lançamento e, se o repositório permitir um agendador, todas as noites. Relate apenas falhas novas e alteradas, para que um bug conhecido não esconda um novo.

Quando o trabalho é grande

Se você puder dividir o trabalho entre modelos ou sessões, caçe com seu modelo mais forte e confirme com um diferente em uma sessão nova. A segunda passagem reexecuta cada teste com falha a partir de um estado limpo e lê cada entrada a frio. Isso pega o falso positivo confiante que uma única passagem tende a manter.