byratio/agents-ux

Agents de test UX — revue basée sur des personas avec navigateur réel

Un modèle pour détecter les problèmes UX qui échappent aux tests unitaires et à l'auto-revue humaine : définissez des agents persona qui pilotent un vrai navigateur via Playwright, parcourent les parcours du point de vue d'un utilisateur spécifique et signalent les points de friction. Résultat concret qui a prouvé l'utilité de cette approche : un agent a signalé un bug de désynchronisation d'un menu déroulant dans la même session où il a été exécuté pour la première fois, avant même que quiconque ne l'ait signalé.

Quand mettre cela en place

• Le projet a une interface web frontend avec plusieurs types d'utilisateurs distincts — nouveau diplômé vs cadre en milieu de carrière vs retraité, utilisateur gratuit vs administrateur entreprise, patient vs professionnel de santé, etc. Les personas doivent être suffisamment différents pour que les valeurs par défaut / le vocabulaire / les fonctionnalités disponibles semblent réellement différentes pour chacun.
• L'application a suffisamment de surface pour qu'il ne soit pas réaliste de la parcourir manuellement pour chaque persona à chaque changement.
• Le serveur de développement peut être exécuté localement sans contorsions d'authentification (ou l'authentification dispose d'un contournement scriptable pour les tests).

À éviter pour : les API sans interface utilisateur, les CLI, les outils internes à un seul persona.

Où vivent les agents

Au niveau du projet dans .claude/agents/, pas dans la configuration globale de l'utilisateur. Les personas intègrent des connaissances spécifiques au projet (plages numériques, noms de fonctionnalités, parcours) qui ne se généraliseraient pas. Chaque persona est son propre fichier .md avec un en-tête YAML :

---
name: <slug-du-persona>-ux
description: Teste UX de <app> du point de vue d'un <persona en une ligne>. Pilote un vrai navigateur via Playwright, capture chaque onglet et signale les points de friction. À utiliser de manière proactive après des modifications UI affectant <zone>.
outils: Bash, Read, Write, Edit
---

Vous êtes un agent de test UX jouant le rôle d'un <persona>.

## Votre persona
<5 à 10 lignes : âge, rôle, niveau de connaissance, objectif de cette session, ce qu'il ne saurait PAS>

## Workflow
1. Créez un nouvel espace de travail via API (ne polluez pas les données réelles).
2. Initialisez les entrées via API pour correspondre au persona.
3. Pilotez le navigateur dans /tmp/ux-<slug>.mjs avec Playwright.
4. Capturez les onglets pertinents pour ce persona.
5. Lisez chaque capture et évaluez.
6. Écrivez les résultats dans plans/ux-reports/<slug>-<date>.md.
7. Nettoyez l'espace de travail de test.

Déposez également un fichier _shared-ux-protocol.md dans le même répertoire (le trait de soulignement initial empêche qu'il soit confondu avec un agent). Ce fichier contient les attentes environnementales, le format de sortie, la grille d'évaluation « quoi évaluer », etc. — les fichiers par persona le citent lorsque c'est utile.

Infrastructure requise

• plans/ux-reports/ existe (créez-le lors de la configuration pour que les rapports aient un endroit où atterrir). Cela suppose la convention que plans/ dans le dépôt contient les documents de travail sur les tâches en cours, validés dans git pour que le raisonnement survive à la session de discussion ; les rapports UX sont l'un de ces documents. Si un projet n'a pas de répertoire plans/, créez-le — ou convenez d'un autre emplacement avec l'utilisateur et écrivez-le dans chaque fichier persona, car les agents codent en dur le chemin.
• Playwright fonctionne via npx playwright (les agents peuvent avoir besoin de npx playwright install chromium une fois sur une machine neuve — intégrez cela dans les instructions de l'agent).
• Une API pour l'amorçage des données doit exister, OU un parcours UI déterministe doit être documenté. Sans l'un d'eux, l'agent devient trop fragile.

Règles de conception des personas

• L'écart de connaissance fait la valeur — l'agent « nouveau diplômé » trouve le jargon que l'agent expérimenté ne remarquerait pas ; l'agent « retraité » trouve les simplifications excessives. Si deux personas donneraient des rapports identiques, fusionnez-les.
• Énoncez un objectif concret par session, pas un vague « explorez l'application ». « Puis-je prendre ma retraite un jour avec ce salaire ? » est testable. « Utilisez l'application » ne l'est pas.
• Spécifiez ce qu'ils NE savent PAS — « ne sait pas ce que signifient SWR / Coast FI / 72(t) » force l'agent à signaler ces termes plutôt que de les ignorer.
• Les plages numériques comptent — si le persona a 5 000 $ d'économies, les valeurs par défaut conçues pour les épargnants de 500 000 $ révéleront des bugs dans la mise à l'échelle des axes de graphiques, la gestion des zéros, etc. que les personas médians manqueraient.

Discipline de sortie (intégrez dans chaque agent)

• Étiquetez chaque constatation [bloqueur] / [friction] / [polissage].
• Une suggestion de correction en une ligne par problème.
• Terminez par une section « Top 3 des correctifs à livrer ensuite » afin que l'utilisateur obtienne une liste d'actions priorisées.
• Rapportez uniquement ce qui a été réellement observé dans les captures d'écran / réponses API — pas de plaintes spéculatives.

Exécution d'un agent

Après avoir déposé les fichiers .md, redémarrez Claude Code — les définitions d'agents sont scannées au début de la session. Depuis la nouvelle session : utilise l'agent <persona>-ux pour revoir la calculatrice après mes dernières modifications. Chaque exécution prend quelques minutes (vrai navigateur), donc ne les lancez pas à chaque changement — exécutez-les après un travail UI significatif.

Ce qu'il faut noter pour l'utilisateur

Lors de la mise en place de ce modèle, notez dans le fichier CHANGELOG.md du projet ou dans un document de plan sous plans/ :

• Que les agents existent et où vont les rapports.
• Le prérequis du serveur de développement (afin qu'un nouveau contributeur n'essaie pas d'exécuter un agent sur un projet froid).
• Toute particularité d'amorçage des données spécifique au projet dont les personas dépendent.

Pièges courants

• Ne laissez pas les agents démarrer le serveur de développement. Ils ont tendance à laisser des processus zombies. Faites-leur vérifier curl -fsS http://localhost:<port> et refusez de continuer s'il est arrêté — l'utilisateur le démarre.
• Ne réutilisez pas un espace de travail / jeu de données réel. Créez et supprimez toujours un espace de travail UX: <persona>. Des constatations polluées par un état résiduel gaspillent le temps de revue de l'utilisateur.
• Ne faites pas du persona un « utilisateur occasionnel » générique. C'est de là que vient le bruit. Plus le persona est spécifique, plus le rapport est utile.
• N'exécutez pas trop d'agents en parallèle — Playwright + serveur de développement + Chromium par agent épuisera rapidement la mémoire d'un ordinateur portable. Les exécutions en série sont préférables.