UX 测试代理——基于角色的浏览器驱动审查
一种捕捉单元测试和人工自审查难以发现的 UX 问题的模式：定义角色代理，通过 Playwright 驱动真实浏览器，从特定用户的角度遍历旅程，并报告摩擦点。实际效果证明其有用：一个代理在首次运行的同一会话中就标记了一个工作区下拉菜单状态不同步的 bug，而在此之前无人提交过该问题。
何时设置此功能
- 项目拥有一个面向多种不同用户类型的 Web 前端——新毕业生 vs. 中生代 vs. 退休人员、免费版 vs. 企业管理员、患者 vs. 提供者等。这些角色之间需要存在足够差异，使得默认设置、术语和可用功能对每个角色来说感受明显不同。
- 应用的覆盖面足够大，以至于每次变更时手动为每个角色走查不现实。
- 开发服务器可以在无需复杂身份验证（或身份验证有可编程的测试绕过方式）的情况下本地运行。
以下情况跳过此模式：无 UI 的 API、CLI 工具、单一角色的内部工具。
代理的存放位置
项目级别存放在 .claude/agents/ 目录下，而非用户的全局配置中。角色嵌入了项目特定的知识（数值范围、功能名称、旅程），这些知识无法通用化。每个角色都是一个独立的 .md 文件，包含前置元数据：
---
name: <角色简称>-ux
description: 从 <一行角色描述> 的角度对 <应用> 进行 UX 测试。通过 Playwright 驱动真实浏览器，截取每个标签页的截图，并报告摩擦点。在影响 <区域> 的 UI 变更后主动使用。
tools: Bash, Read, Write, Edit
---
你是一个扮演 <角色> 的 UX 测试代理。
## 你的角色
<5–10 行：年龄、角色、知识水平、本次会话的目标、他们**不会**知道的内容>
## 工作流程
1. 通过 API 创建一个全新的工作区（不要污染真实数据）。
2. 通过 API 播种与角色匹配的输入数据。
3. 使用 Playwright 在 /tmp/ux-<简称>.mjs 中驱动浏览器。
4. 截取与该角色相关的标签页截图。
5. 读取每个截图并进行评估。
6. 将发现写入 plans/ux-reports/<简称>-<日期>.md。
7. 清理测试工作区。
同时，在同一目录下放置一个 _shared-ux-protocol.md 文件（前导下划线可防止其被误认为是代理）。该文件包含环境期望、输出格式、“评估标准”等内容——每个角色的文件在需要时引用它。
必需的基础设施
plans/ux-reports/目录必须存在（在设置过程中创建，以便报告有地方存放）。这遵循约定，即仓库中的plans/目录存放关于进行中工作的工作文档，并提交到 git，使得推理过程在对话会话结束后依然存在；UX 报告就是这类文档之一。如果项目没有plans/目录，则创建它——或者与用户商定另一个位置并写入每个角色文件中，因为代理会硬编码该路径。- Playwright 通过
npx playwright工作（代理可能需要在一台新机器上执行一次npx playwright install chromium——将该步骤嵌入到代理的指令中）。 - 必须存在一个用于播种数据的 API，或者必须记录一个确定性的 UI 流程。如果没有这些，代理会变得过于脆弱。
角色设计规则
- 知识差距是价值所在——新毕业生代理会发现经验丰富的代理忽视的行话；退休人员会发现过度简化的问题。如果两个角色会给出相同的报告，则合并它们。
- 为每次会话设定一个具体目标，而不是模糊的“探索应用”。“我退休后能否靠这笔薪水生活？”是可测试的。“使用应用”则不可测试。
- 明确说明他们不知道的内容——“不知道 SWR / Coast FI / 72(t) 是什么意思”会迫使代理标记这些术语，而不是一带而过。
- 数值范围很重要——如果角色只存了 5000 美元，而为存了 50 万美元的人设计的默认值会暴露图表轴缩放、零值处理等方面的 bug，而这些是普通角色可能忽略的。
输出规范（在每个代理中编码）
- 每个发现标记为
[blocker]（阻塞）/[friction]（摩擦）/[polish]（打磨）。 - 每个问题附上一行建议修复方案。
- 以“下一版应修复的前 3 个问题”部分结尾，使用户获得一个优先行动列表。
- 仅报告在截图 / API 响应中实际观察到的内容——不进行推测性抱怨。
运行代理
放置 .md 文件后，重新启动 Claude Code——代理定义在会话启动时扫描。从新会话中：使用 <角色简称>-ux 代理在我最新更改后审查计算器。每次运行需要几分钟（真实浏览器），因此不要在每次变更时都运行——在完成有意义的 UI 工作后运行。
需要为用户跟踪的内容
在设置此模式时，在项目的 CHANGELOG.md 或 plans/ 下的计划文档中注明：
- 代理存在以及报告存放的位置。
- 开发服务器前提条件（以便新贡献者不会尝试对冷启动的项目运行代理）。
- 角色依赖的任何项目特定的数据播种特殊之处。
常见陷阱
- 不要让代理启动开发服务器。 它们往往会留下僵尸进程。让它们检查
curl -fsS http://localhost:<端口>，如果服务未运行则拒绝继续——由用户手动启动。 - 不要重用真实的工作区/数据集。 始终创建并删除一个
UX: <角色>工作区。受残留状态污染的发现在浪费用户的审查时间。 - 不要让角色成为通用的“普通用户”。 那是噪音的来源。角色越具体，报告越有用。
- 不要同时运行太多代理——Playwright + 开发服务器 + 每个代理一个 Chromium 实例会很快导致笔记本电脑内存不足。串行运行即可。