bughunt

¿Qué hace bughunt?

Las pruebas unitarias y la mayoría de las pruebas de interfaz de usuario verifican las rutas de código en las que pensaron sus autores, a menudo a través de hooks de prueba que evitan los clics y las teclas reales. Las personas no usan una aplicación de esa manera. Hacen clic donde el hook no llega, presionan Deshacer después de todo, trabajan en una ventana estrecha, pierden la red a mitad de camino y abren el archivo extraño que un colega envió. La mayoría de los bugs que encuentran ya estaban allí, y nadie los estaba buscando.

Esta habilidad busca. Maneja la aplicación real con entrada real, un área a la vez, y registra cada bug confirmado dos veces: como una prueba fallida que permanece en el repositorio, para que el bug no pueda regresar sin ser notado, y como una entrada en la lista de bugs del repositorio, para que alguien lo corrija. Una cacería no arregla el código del producto. Encuentra, prueba y escribe.

Modos

• Cazar (el predeterminado): elige un área, cázala, registra los hallazgos, actualiza la rotación. Un área por ejecución mantiene la cacería lo suficientemente profunda como para encontrar bugs reales.
• Configurar: el repositorio no tiene forma de manejar la aplicación de extremo a extremo, o carece de los límites en references/boundaries.md. Construye el carril de recorrido más pequeño que pueda ejecutar una característica en cada superficie (references/walkthroughs.md), luego caza.
• Barrer: ejecuta cada recorrido existente e informa qué es nuevo, qué cambió y qué se corrigió desde la última ejecución. Una barrida encuentra regresiones, no nuevos tipos de bugs; combínala con cacerías.
• Reglas: agrega una de las reglas en references/invariants.md al carril, para que se ejecute en cada paso de cada recorrido. Una sola regla (por ejemplo, "Deshacer restaura el estado anterior exacto") puede sacar a la luz una docena de bugs en características que nadie pensaría en scriptear.

1. Aprende primero las reglas básicas

Lee los archivos de instrucciones del repositorio (CLAUDE.md, AGENTS.md, CONTRIBUTING, cualquier regla o nota de traspaso), el README de lo que sea que ejecute la aplicación, y las pruebas de extremo a extremo existentes. Averigua:

• Cómo iniciar cada superficie que tiene la aplicación: servidor de desarrollo, compilación de escritorio, simulador móvil. Una superficie es un host (web, escritorio, móvil) con una apariencia (claro, oscuro, alto contraste) a un tamaño (ancho, estrecho, teléfono).
• Dónde se rastrean los bugs (un archivo de bugs, una lista de tareas pendientes, un rastreador de incidencias) y el formato que usan las entradas allí. Escribe en ese formato.
• Lo que una prueba nunca debe tocar: cuentas reales, archivos de usuarios reales, datos de producción, correo electrónico real, pagos, el portapapeles del usuario, la impresora y el navegador, la copia instalada de la aplicación. Lee references/boundaries.md y pon en práctica cada límite que aplique antes de manejar cualquier cosa. Esta es la parte de una cacería que puede hacer daño real, así que viene primero.
• Si el repositorio prohíbe cualquier otra cosa (hacer push, acceso a la red, servicios de pago, iniciar agentes). Esas reglas tienen prioridad sobre esta habilidad.

Pregunta solo cuando la respuesta cambie lo que puedes tocar. De lo contrario, elige y escribe la suposición en el informe de cacería.

2. Elige el área y enumera lo que hace

Usa el área que la persona nombró. De lo contrario, lee bughunt/areas.md (crearlo desde templates/areas.md en la primera ejecución) y elige, en este orden: un área nunca cazada, luego una cambiada desde su última cacería (git log en sus rutas), luego la más desactualizada. Un área es un conjunto de características que una persona usa juntas: el editor de documentos, el explorador de archivos, inicio de sesión y cuentas, configuración, compartir, pagos.

Enumera las características del área desde lo que tenga el repositorio: un registro de características, los menús y la lista de comandos, rutas, las páginas de ayuda, los puntos de entrada del código. Cada característica recibe al menos una pasada en cada superficie.

3. Cazar

Para cada característica, primero haz lo que una persona hace con ella, de principio a fin, en archivos sintéticos realistas. Luego revisa references/checklist.md. Es una lista de movimientos de usuario hostil que rompen aplicaciones una y otra vez: Deshacer después de cada paso, solo teclado, ventana estrecha, modo oscuro, sin conexión a mitad de camino, el archivo más grande y el más roto, un viaje de ida y vuelta a través de otro formato, la misma cosa en dos pestañas, un fallo a propósito.

Maneja la aplicación con eventos de entrada reales (clics, pulsaciones de teclas, arrastres, escritura) al ritmo de una persona. Un script actúa más rápido que una persona, así que dale a un clic un breve momento antes de la siguiente acción, y deja medio segundo entre dos cambios que esperes deshacer por separado. De lo contrario, archivarás artefactos de temporización como bugs.

Observa cada paso en busca de:

• el resultado incorrecto, o un resultado correcto que no persiste (desaparece después de recargar, guardar, Deshacer o cambiar de pestaña)
• trabajo perdido: ediciones, configuración, selección, posición de desplazamiento
• Deshacer que retrocede demasiado, demasiado poco, o nada
• un comando que no hace nada, funciona solo desde uno de sus puntos de entrada, o no está deshabilitado cuando no puede ejecutarse
• texto de error sin procesar: trazas de pila, códigos de error, rutas internas
• errores de consola, fallos, ventanas en blanco, cuelgues
• texto que es demasiado tenue, recortado, superpuesto o roto en medio de una palabra (las comprobaciones de captura de pantalla en references/invariants.md detectan la mayor parte de esto por sí solas)
• el mismo paso comportándose de manera diferente en otra superficie

Escribe cada candidato cuando lo veas, con la superficie, el paso y lo que esperabas. Luego continúa; confirma al final de la característica.

4. Confirma antes de archivar

Una cacería solo es tan buena como sus hallazgos son verdaderos. Para cada candidato:

1. Reprodúcelo dos veces desde un estado limpio, al ritmo de una persona, manualmente o con un script mínimo. Si no se reproduce, descártalo o archívalo como "No verificado:" con lo que viste y dónde.
2. Descarta la prueba. Temporización (ver arriba), un selector que coincidió con el elemento incorrecto, los stubs propios de la prueba, una ventana que no estaba enfocada, el puntero descansando sobre algo con un estado de hover. Un hallazgo que va y viene con dónde descansa el puntero es real pero necesita una posición de puntero fija en su prueba.
3. Encuentra la causa cuando sea barato. Lee el código en el lugar probable y nombra el archivo y la función. No te detengas mucho aquí; el que lo arregle lo hará.
4. Verifica el rastreador. Si una entrada ya lo cubre, agrega la nueva superficie o detalle a esa entrada en lugar de una nueva.
5. Agrupa por causa. Varios síntomas a menudo comparten una causa (una sola combinación de teclas faltante puede romper Deshacer en cinco editores en un host). Dilo, para que la corrección ocurra una vez.

5. Registra cada bug confirmado

• Primero una prueba fallida. Agrega un paso al recorrido de la característica (o un nuevo recorrido) cuya expectativa establezca lo que debería suceder. Ejecútalo y verifica que falla, y falla por la razón del bug, no por otra cosa. Pasará una vez que el bug esté corregido. Nunca debilites una expectativa existente o una comprobación de captura de pantalla para hacer que una ejecución pase. Si una comprobación es incorrecta, di por qué en el informe y déjala para una persona.
• Luego la entrada de bug, al final de la lista de bugs del repositorio, en su formato, usando templates/bug-entry.md: el síntoma en palabras de un usuario, lo que sucede contra lo que debería, los números medidos, dónde en el código, qué prueba lo protege, y en qué superficies se muestra.
• Sin cambios en el código del producto en una cacería, a menos que la persona haya solicitado correcciones. Corregir sobre la marcha oculta el hallazgo y mezcla dos tipos de revisión.
• Confirma las nuevas pruebas y las entradas de bug si las reglas del repositorio lo permiten, preparando los archivos por nombre. No hagas push a menos que la persona lo haya dicho.

6. Informa y rota

Escribe el informe de cacería desde templates/hunt-report.md: el área, las superficies, cada hallazgo con su prueba y entrada, los candidatos que descartaste y por qué, lo que no pudiste probar, y los grupos de corrección sugeridos por causa. Actualiza la fila del área en bughunt/areas.md (fecha, commit, hallazgos).

Termina diciéndole a la persona, en lenguaje sencillo: cuántos bugs fueron confirmados, los tres peores, los grupos de corrección y la siguiente área que la rotación elegiría.

Sigue encontrándolos

Una cacería terminada deja pruebas que atrapan los mismos bugs cuando regresan. Los bugs nuevos necesitan una nueva búsqueda:

• Caza de nuevo en rotación. Vuelve a cazar un área después de cambios grandes en ella.
• Convierte un bug que sigue apareciendo en nuevos lugares en una regla (references/invariants.md) para que cada paso lo verifique.
• Cada bug que una persona informa se convierte en un paso de recorrido antes de que se corrija.
• Ejecuta todo el carril antes de cada lanzamiento y, si el repositorio permite un programador, cada noche. Informa solo fallos nuevos y cambiados, para que un bug conocido no entierre uno nuevo.

Cuando el trabajo es grande

Si puedes dividir el trabajo entre modelos o sesiones, caza con tu modelo más fuerte y confirma con uno diferente en una sesión nueva. La segunda pasada vuelve a ejecutar cada prueba fallida desde un estado limpio y lee cada entrada en frío. Eso atrapa el falso positivo seguro que una sola pasada tiende a conservar.