byratio/ux-agents

UX-Test-Agents – Persona-basierte Browser-gesteuerte Überprüfung

Ein Muster, um UX-Probleme zu finden, die Unit-Tests und menschlicher Selbst-Check entgehen: Definiere Persona-Agents, die einen echten Browser via Playwright steuern, Reisen aus der Perspektive eines bestimmten Benutzers durchlaufen und Reibungspunkte melden. Ein reales Ergebnis, das diesen Ansatz bewiesen hat: Ein Agent hat einen Dropdown-Desynchronisierungs-Bug im selben Session erkannt, in dem er zum ersten Mal lief, bevor jemand einen Fehlerbericht eingereicht hatte.

Wann einrichten

• Das Projekt hat ein Web-Frontend mit mehreren unterschiedlichen Benutzertypen – Neuling vs. Karrieremitte vs. Rentner, Free-Tier vs. Enterprise-Admin, Patient vs. Anbieter usw. Die Personas müssen sich genug unterscheiden, dass Standardeinstellungen / Vokabular / verfügbare Funktionen sich für jede tatsächlich anders anfühlen.
• Die App hat genug Oberfläche, dass ein manuelles Durchgehen für jede Persona bei jeder Änderung nicht realistisch ist.
• Der Dev-Server kann lokal ohne Authentifizierungs-Hürden gestartet werden (oder die Authentifizierung hat einen skriptbaren Workaround für Tests).

Überspringe dies für: APIs ohne UI, CLIs, Ein-Persona-Interne Tools.

Wo die Agents leben

Projektbezogen unter .claude/agents/, nicht in der globalen Konfiguration des Benutzers. Personas kodieren projektspezifisches Wissen (Zahlenbereiche, Feature-Namen, Reisen), das nicht verallgemeinerbar ist. Jede Persona ist eine eigene .md-Datei mit Frontmatter:

---
name: <persona-slug>-ux
description: Testet <App> aus der Perspektive einer <einzeilige Persona>. Steuert einen echten Browser via Playwright, macht Screenshots von jedem Tab und meldet Reibungspunkte. Proaktiv nach UI-Änderungen am <Bereich> einsetzen.
tools: Bash, Read, Write, Edit
---

Du bist ein UX-Test-Agent, der eine <Persona> rollenspielt.

## Deine Persona
<5–10 Zeilen: Alter, Rolle, Kenntnisstand, Ziel in dieser Session, was sie NICHT wissen würden>

## Arbeitsablauf
1. Erstelle einen frischen Workspace über die API (keine echten Daten verschmutzen).
2. Befülle Eingaben über die API, um die Persona abzubilden.
3. Steuere den Browser mit Playwright in /tmp/ux-<slug>.mjs.
4. Mache Screenshots der relevanten Tabs für diese Persona.
5. Lese jeden Screenshot und bewerte ihn.
6. Schreibe die Ergebnisse in plans/ux-reports/<slug>-<date>.md.
7. Räume den Test-Workspace auf.

Lege auch eine _shared-ux-protocol.md im gleichen Verzeichnis ab (der führende Unterstrich verhindert, dass sie fälschlich als Agent erkannt wird). Diese Datei enthält Umgebungserwartungen, Ausgabeformat, die Bewertungsmatrix („Was soll bewertet werden“) usw. – die persona-spezifischen Dateien referenzieren sie bei Bedarf.

Erforderliches Grundgerüst

• plans/ux-reports/ existiert (erstelle es während der Einrichtung, damit die Reports einen Zielort haben). Dies setzt die Konvention voraus, dass plans/ im Repository Arbeitsdokumente für laufende Arbeiten enthält, die in Git committed werden, damit die Überlegungen die Chat-Session überdauern; UX-Reports sind solche Dokumente. Wenn ein Projekt kein plans/-Verzeichnis hat, erstelle es – oder vereinbare einen anderen Ort mit dem Benutzer und schreibe ihn in jede Persona-Datei, da die Agents den Pfad fest codieren.
• Playwright funktioniert über npx playwright (Agents benötigen möglicherweise einmalig npx playwright install chromium auf einem frischen Rechner – binde dies in die Agent-Anweisungen ein).
• Eine API zum Befüllen von Daten muss existieren ODER ein deterministischer UI-Ablauf muss dokumentiert sein. Ohne eine dieser Voraussetzungen wird der Agent zu spröde.

Regeln für das Persona-Design

• Wissenslücke ist der Wert – der Neuling-Agent findet Fachjargon, den der Erfahrene nicht mit der Wimper zuckt; der Rentner-Agent findet die zu starken Vereinfachungen. Wenn zwei Personas identische Berichte liefern würden, fasse sie zusammen.
• Formuliere ein konkretes Ziel pro Session, kein vages „Erkunde die App“. „Kann ich mit diesem Gehalt jemals in Rente gehen?“ ist testbar. „Nutze die App“ ist es nicht.
• Gib an, was sie NICHT wissen – „weiß nicht, was SWR / Coast FI / 72(t) bedeutet“ zwingt den Agenten, diese Begriffe zu markieren, anstatt sie zu übergehen.
• Zahlenbereiche sind wichtig – wenn die Persona 5.000 € gespart hat, werden Standardeinstellungen, die für Sparer mit 500.000 € ausgelegt sind, Bugs in Diagrammachsen-Skalierung, Nullbehandlung usw. aufdecken, die durchschnittliche Personas übersehen würden.

Ausgabedisziplin (in jedem Agent codieren)

• Tagge jeden Fund mit [blocker] / [friction] / [polish].
• Ein einzeiliger Lösungsvorschlag pro Problem.
• Beende mit einem Abschnitt „Top 3 Korrekturen für den nächsten Release“, damit der Benutzer eine priorisierte Aktionsliste erhält.
• Berichte nur, was tatsächlich in Screenshots / API-Antworten beobachtet wurde – keine spekulativen Beschwerden.

Ausführen eines Agents

Nach dem Ablegen der .md-Dateien starte Claude Code neu – Agent-Definitionen werden zu Beginn der Session eingelesen. Ab der neuen Session: nutze den <persona>-ux-Agent, um den Rechner nach meinen letzten Änderungen zu überprüfen. Jeder Durchlauf dauert Minuten (echter Browser), also starte sie nicht bei jeder Änderung – führe sie nach sinnvollen UI-Arbeiten aus.

Was für den Benutzer dokumentieren

Wenn du dieses Muster einrichtest, notiere im CHANGELOG.md des Projekts oder einem Plan-Dokument unter plans/:

• Dass die Agents existieren und wo die Reports landen.
• Die Dev-Server-Voraussetzung (damit ein neuer Mitwirkender nicht versucht, einen Agent gegen ein kaltes Projekt zu starten).
• Alle projektspezifischen Daten-Befüllungs-Besonderheiten, auf die die Personas angewiesen sind.

Häufige Fallstricke

• Lass die Agents nicht den Dev-Server starten. Sie neigen dazu, Zombie-Prozesse zu hinterlassen. Lass sie prüfen, ob curl -fsS http://localhost:<port> antwortet, und verweigere die Fortsetzung, wenn der Server nicht läuft – der Benutzer startet ihn.
• Verwende keinen echten Workspace / Datensatz neu. Erstelle und lösche immer einen UX: <Persona> Workspace. Funde, die durch übrig gebliebene Zustände verunreinigt sind, verschwenden die Überprüfungszeit des Benutzers.
• Mach die Persona nicht zu einem generischen „Gelegenheitsnutzer“. Daher kommt das Rauschen. Je spezifischer die Persona, desto nützlicher der Bericht.
• Starte nicht zu viele parallel – Playwright + Dev-Server + Chromium pro Agent überlastet schnell den Arbeitsspeicher eines Laptops. Serielle Durchläufe sind in Ordnung.