Agentes UX para testing basado en personas

Agentes UX — revisión basada en personas usando el navegador

Un patrón para detectar problemas de UX que escapan a las pruebas unitarias y a la auto-revisión humana: define agentes de persona que controlan un navegador real mediante Playwright, recorren flujos desde la perspectiva de un usuario específico y reportan fricciones. Resultado real que demostró su utilidad: un agente detectó un bug de desincronización en un menú desplegable del workspace en la misma sesión en que se ejecutó por primera vez, antes de que nadie lo reportara.

Cuándo configurar esto

• El proyecto tiene un frontend web con múltiples tipos de usuarios distintos — nuevo graduado vs. profesional a mitad de carrera vs. jubilado, usuario gratuito vs. administrador empresarial, paciente vs. proveedor, etc. Las personas deben diferir lo suficiente para que los valores predeterminados, el vocabulario y las funciones disponibles se sientan realmente diferentes para cada una.
• La aplicación tiene suficiente superficie como para que recorrerla manualmente para cada persona en cada cambio no sea realista.
• El servidor de desarrollo se puede ejecutar localmente sin problemas de autenticación (o la autenticación tiene un bypass scripteable para pruebas).

Omitir esto para: APIs sin interfaz de usuario, CLI, herramientas internas de una sola persona.

Dónde viven los agentes

En el ámbito del proyecto, en .claude/agents/, no en la configuración global del usuario. Las personas incorporan conocimiento específico del proyecto (rangos numéricos, nombres de funciones, flujos) que no sería generalizable. Cada persona tiene su propio archivo .md con frontmatter:

---
name: <slug-de-persona>-ux
description: Pruebas UX de <app> desde la perspectiva de <descripción breve de la persona>. Controla un navegador real mediante Playwright, captura pantallas de cada pestaña y reporta puntos de fricción. Úsalo de forma proactiva después de cambios en la UI que afecten a <área>.
tools: Bash, Read, Write, Edit
---

Eres un agente de testing UX que interpreta el rol de <persona>.

## Tu persona
<5–10 líneas: edad, rol, nivel de conocimiento, objetivo en esta sesión, lo que NO sabría>

## Flujo de trabajo
1. Crea un espacio de trabajo nuevo mediante API (no contaminar datos reales).
2. Siembra datos de entrada mediante API para que coincidan con la persona.
3. Controla el navegador en /tmp/ux-<slug>.mjs con Playwright.
4. Captura pantalla de las pestañas relevantes para esta persona.
5. Lee cada captura y evalúa.
6. Escribe los hallazgos en plans/ux-reports/<slug>-<fecha>.md.
7. Limpia el espacio de trabajo de prueba.

También coloca un _shared-ux-protocol.md en el mismo directorio (el guión bajo inicial evita que se confunda con un agente). Ese archivo contiene expectativas del entorno, formato de salida, la rúbrica de "qué evaluar", etc. — los archivos por persona lo citan cuando es útil.

Infraestructura necesaria

• plans/ux-reports/ debe existir (crearlo durante la configuración para que los informes tengan dónde ir). Esto asume la convención de que plans/ en el repositorio contiene documentos de trabajo sobre tareas en curso, commiteados en git para que el razonamiento perdure más allá de la sesión de chat; los informes UX son uno de esos documentos. Si el proyecto no tiene un directorio plans/, créalo — o acuerda otra ubicación con el usuario y escríbela en cada archivo de persona, ya que los agentes tienen la ruta hardcodeada.
• Playwright funciona mediante npx playwright (los agentes pueden necesitar npx playwright install chromium una vez en una máquina nueva — inclúyelo en las instrucciones del agente).
• Debe existir una API para sembrar datos, O un flujo de UI determinista documentado. Sin uno de estos, el agente termina siendo demasiado frágil.

Reglas de diseño de personas

• La brecha de conocimiento es el valor — el agente del nuevo graduado encuentra jerga que el experimentado ni notaría; el jubilado encuentra las simplificaciones excesivas. Si dos personas dieran informes idénticos, fusiónalas.
• Indica un objetivo concreto por sesión, no un vago "explorar la aplicación". "¿Podré jubilarme algún día con este salario?" se puede probar. "Usar la app" no.
• Especifica lo que NO saben — "no sabe qué significa SWR / Coast FI / 72(t)" obliga al agente a marcar esos términos en lugar de pasarlos por alto.
• Los rangos numéricos importan — si la persona tiene $5K ahorrados, los valores predeterminados diseñados para ahorradores de $500K revelarán bugs en el escalado de ejes de gráficos, manejo de ceros, etc. que las personas promedio pasarían por alto.

Disciplina de salida (codificar en cada agente)

• Etiqueta cada hallazgo como [blocker] / [friction] / [polish].
• Una línea de sugerencia de corrección por problema.
• Termina con una sección "Top 3 correcciones para enviar a producción" para que el usuario reciba una lista de acciones priorizadas.
• Reporta solo lo que realmente se observó en las capturas de pantalla / respuestas de la API — sin quejas especulativas.

Cómo ejecutar un agente

Después de colocar los archivos .md, reinicia Claude Code — las definiciones de agentes se escanean al inicio de la sesión. Desde la nueva sesión: use el agente <persona>-ux para revisar la calculadora después de mis últimos cambios. Cada ejecución toma minutos (navegador real), así que no los actives en cada cambio — ejecútalos después de trabajo significativo en la UI.

Qué registrar para el usuario

Al configurar este patrón, anota en el CHANGELOG.md del proyecto o en un documento de plan bajo plans/:

• Que los agentes existen y dónde van los informes.
• El prerrequisito del servidor de desarrollo (para que un nuevo colaborador no intente ejecutar un agente contra un proyecto frío).
• Cualquier peculiaridad específica del proyecto sobre la siembra de datos que las personas usen.

Errores comunes

• No hagas que los agentes inicien el servidor de desarrollo. Suelen dejar procesos zombies. Haz que verifiquen curl -fsS http://localhost:<puerto> y se nieguen a continuar si no está activo — que lo inicie el usuario.
• No reutilices un espacio de trabajo / conjunto de datos real. Siempre crea y elimina un espacio de trabajo UX: <persona>. Los hallazgos contaminados por estado residual desperdician el tiempo de revisión del usuario.
• No conviertas la persona en un "usuario casual" genérico. De ahí viene el ruido. Cuanto más específica sea la persona, más útil será el informe.
• No ejecutes demasiados en paralelo — Playwright + servidor de desarrollo + Chromium por agente agotará la memoria RAM de una laptop rápidamente. Las ejecuciones en serie están bien.