UX 測試代理工具 — 以人物角色為基礎的瀏覽器驅動審查
一種用來捕捉單元測試和人為自我審查無法發現的 UX 問題的模式：定義人物角色代理工具，透過 Playwright 實際驅動瀏覽器，從特定使用者的視角走訪使用者旅程，並回報摩擦點。真實案例證明此模式的價值：一個代理工具在首次執行的同一個工作階段中，就標記出一個工作區下拉選單的同步錯誤，而在此之前沒有人回報過這個問題。
何時設定此模式
- 專案有一個網頁前端，且具有多個不同使用者類型 — 新畢業生 vs. 職涯中期 vs. 退休人士、免費方案 vs. 企業管理員、病患 vs. 醫療提供者等。這些人物角色需要有足夠的差異，讓預設值、詞彙和可用功能對每個角色來說感覺都不一樣。
- 應用程式的涵蓋範圍夠大，以至於每次都為每個人物角色手動走訪流程並不實際。
- 開發伺服器可以在本機執行，無需複雜的驗證流程（或者驗證有可用於測試的可腳本化繞過方式）。
以下情況不適用：僅有 API 而無 UI 的專案、命令列工具、單一人物角色的內部工具。
代理工具存放位置
放在專案範圍內的 .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 萬美元的使用者設計的預設值，將會曝露圖表軸線縮放、零值處理等方面的錯誤，而一般的人物角色則會忽略這些問題。
輸出規範（編碼到每個代理工具中）
- 為每個發現項目加上標籤
[blocker]/[friction]/[polish]。 - 每個問題附上一行建議的修復方式。
- 結尾處加上「下一版要出貨的前三大修復項目」章節，讓使用者獲得優先處理的行動清單。
- 只回報在截圖 / API 回應中實際觀察到的內容 — 不要推測性的抱怨。
執行代理工具
在放置好 .md 檔案後，重新啟動 Claude Code — 代理工具的定義是在工作階段開始時掃描的。在新的工作階段中：使用 <人物角色縮寫>-ux 代理工具來檢視我最新變更後的計算機。每次執行需要幾分鐘（實際瀏覽器），所以不要在每次變更時都執行 — 在有意義的 UI 工作完成後再執行。
需要為使用者追蹤的事項
在設定此模式時，請在專案的 CHANGELOG.md 或 plans/ 下的計畫文件中註明：
- 代理工具已存在，以及報告存放的位置。
- 開發伺服器的前提條件（這樣新貢獻者才不會嘗試在一個尚未啟動的專案上執行代理工具）。
- 任何人物角色依賴的專案特定資料播種細節。
常見陷阱
- 不要讓代理工具啟動開發伺服器。 它們往往會留下殭屍程序。讓它們檢查
curl -fsS http://localhost:<埠號>，如果伺服器未啟動就拒絕繼續執行 — 由使用者來啟動它。 - 不要重複使用真實的工作區 / 資料集。 始終建立並刪除一個
UX: <人物角色>工作區。被殘留狀態污染的發現項目會浪費使用者的審查時間。 - 不要將人物角色設定為通用的「一般使用者」。 雜訊就是從這裡來的。人物角色越具體，報告就越有用。
- 不要同時執行太多個 — 每個代理工具的 Playwright + 開發伺服器 + Chromium 很快就會讓筆記型電腦記憶體不足。序列執行就可以了。