ux-audit

UX 审计

像真实用户一样操作正在运行的 Web 应用。审计以交互为先——输入、点击、发送、观察、截图。静态 DOM 扫描无法得出结论。

判定状态

审计结束时，判定结果必须且只能是以下之一：

• 通过 — 严重问题 = 0，High 问题 = 0，所有硬性门槛均通过，交互清单完整。
• 有条件通过 — 严重问题 = 0，High 问题 = 0，所有硬性门槛均通过，但存在 Medium/Low 问题。
• 不通过 — 至少发现一个严重或 High 问题，或者有硬性门槛未通过。
• 未完成 — 交互清单缺少必填项、未执行某个阶段，或者审计元检查触发（清单时间戳间隔集中在 < 0.5s、截图少于路由数的 2 倍、控制台读取次数少于路由数，或穷尽式审计的第 3 阶段耗时 < 1m）。即使所有观察结果看起来正常，也不得将结果升级为通过。

如果工作中没有完整的交互清单，唯一合法的判定结果就是未完成。“看起来没问题”不等于通过。如果通过判定的时间记录不合理，该结果将被驳回——Agent 必须通过真实交互重新执行审计。

硬性门槛

以下情况会导致审计自动不通过，不得降低严重程度。

门槛	阈值	违规时的严重程度
操作过程中的控制台错误	> 0	Critical
操作过程中的控制台警告	> 0	High
网络 5xx	> 0	Critical
已认证页面上的网络 403 / 404	> 0	High
任意已测试视口 / 面板组合出现布局崩溃	> 0	High
任意已审计页面存在 axe-core Critical 违规	> 0	Critical
任意已审计页面存在 axe-core Serious 违规	> 0	High
代表性路由上的 LCP（务实预算）	> 4.0s	High
代表性路由上的 CLS	> 0.25	High
代表性路由上的 INP	> 500ms	High
缺少必填的交互清单条目	n/a	未完成
清单条目间的中位间隔 < 0.5s	n/a	未完成（实际上并未交互）

控制台警告的严重程度最低为 High。5xx 会自动判定为 Critical。不存在“Medium 控制台错误”这一类别——此技能中没有此类别。

axe-core 阈值按页面执行（任一单页的违规数 > 1 即判定失败）。性能阈值只在一个代表性路由上执行（逐页执行过于苛刻）；务实预算远高于故障水平，但远低于严格的 CWV 标准。完整阈值及其依据见 references/performance-budget.md。完整的无障碍配置及严重程度映射见 references/a11y-automation.md。

已知噪声的允许列表

部分应用存在已知的控制台 / 网络噪声类别，但这些并非 Bug（Sentry 信息日志、浏览器扩展提示、认证检查探测中预期出现的 401）。执行第 3 阶段前，请先读取审计配置文件并应用其中的允许列表。路径回退顺序：.jez/audit-config.yml → audit-config.yml → .audit/config.yml。允许列表中的条目仍保留在交互清单中，但不会计入问题。判定结果块同时显示原始数量和允许列表数量：Console warnings: 3 (1 allowlisted, 2 reportable)。

未提供配置时，所有控制台错误 / 警告都视为问题。格式、语义和界面覆盖规则见 references/audit-config.md。

阶段（按顺序）

1. 预检 — Persona 锁定、浏览器工具、URL、视口、能力测试
2. 探索 — 站点地图、线程清单、元素清单
3. 走查 — 交互清单、线程、元素穷尽检查、多窗格压力测试、首次使用者视角、实时交互冒烟测试
4. 润色 — 视觉润色检查、组件完善检查清单
5. 压力测试 — 场景测试组（11 个场景）+ 扩展压力测试方案
6. 结论 — 结论状态、硬性门槛评分卡、完善路线图、附带复现步骤的发现
7. 修复并验证 — 修复发现的问题、重新走查受影响的部分、更新报告

如需进行 30 秒的部署前检查，请使用本文件底部的 dogfood 演练——这是一条项目级规则，而非技能调用。

阶段 1 — 预检

共五道关卡。任何一项未通过都应停止。

1. Persona 锁定

审计首先需要一个 Persona。没有锁定的 Persona，发现的问题就会泛化成“看起来不错”。

按以下顺序确定 Persona：

1. 参数 — 如果用户提供了 Persona（“以一位繁忙的保险经纪人的视角进行 UX 审计”）
2. 项目 Persona — 读取现有的 Persona 文件（回退顺序：.jez/audit-personas/<slug>.md → docs/personas/<slug>.md → personas/<slug>.md → .audit/personas/<slug>.md）。采用第一个匹配项。
3. 询问一次 — “谁在使用这个应用？他们想完成什么任务？”

记录：角色、技术熟练度、时间压力、情绪状态、设备场景。一个好的 Persona 能预判他们会漏掉什么（“在接电话间隙工作的接待员不会滚动到首屏以下”）。

将选定的 Persona 写在审计报告顶部，以此锁定。每条发现都必须能从该 Persona 的角度进行论证。如果你发现自己在想 “开发人员会知道……”，就停下来。你的 Persona 并不知道。

还要始终对每项多页面功能进行首次使用者视角检查（必做，见阶段 3），即使明确指定的 Persona 并非首次使用者。这是 AI / 内部工具最容易忽视的问题。

Persona 库和编写规范见 references/persona-lock.md。

2. 浏览器工具

目标	工具	原因
已验证身份的应用	Chrome MCP	使用你实际登录的 Chrome 会话——OAuth、Cookie、RBAC 均可直接使用
公共网站	Playwright MCP	无需登录
两者均不可用	停止	请用户连接 Chrome MCP 或安装 Playwright

对于已验证身份的应用，不要悄悄改用全新的 Playwright 会话——如果无法登录，审计就毫无价值。如果 Chrome MCP 未连接，请停止并说明：“打开 Chrome，点击 Claude 扩展中的 Connect，然后重新运行。”

命令见 references/browser-tools.md。

3. URL

优先使用已部署的实时版本——这样才能获得真实的身份验证、延迟、CDN 和 CORS。查找方式：读取项目的 CLAUDE.md / README，寻找“URL” → 检查技术栈配置（wrangler.jsonc、vite.config.ts、next.config.js、config/database.yml、manage.py、.env 中的 APP_URL、wp-config.php）→ lsof -i :PORT（常见端口：Vite 为 5173，Next/Rails 为 3000，Django/Laravel 为 8000，Wrangler 为 8787，Astro 为 4321）→ 询问。特定技术栈的指南见 references/project-adaptation.md。只有在用户要求或功能尚未部署时才使用本地版本。

4. 视口

开始时将窗口固定为 1440×900。阶段 3 的多窗格压力测试将测试 375 / 768 / 1024 / 1280 / 1440 / 1920。不要超过 2000px——否则会破坏测试框架。

5. 能力测试

开始任何走查之前，先验证工具可用——每项调用一次：

• 截取一张屏幕截图
• 读取一次控制台
• 清点一次网络请求
• 查询一次元素选择器

如果任一项失败，请停止并修复连接，然后再开始审计。无法查看控制台输出的审计毫无价值。

阶段 2 — 探索

Sitemap 爬取

在审查任何页面之前，先建立完整的页面清单。

1. 路由器配置 — 查看应用的路由定义（React Router、TanStack Router、Next.js app dir）
2. 导航爬取 — 点击浏览侧边栏／菜单中的每个区块和子区块
3. 深层链接 — CLAUDE.md、文档或先前审计报告中的 URL

每个路由占一行，并注明用途：/app/clients — 客户端列表、搜索、新增。

任务线程清单

找出构成用户日常工作内容的 3–5 个真实任务。这些任务是审计的主线。

查找方式：询问用户、阅读 CLAUDE.md／README，或根据顶层导航推断。示例：保险经纪 → 续保、创建客户、处理今天的待办事项。项目管理 → 早间分流、更新任务、向客户发送摘要。空间／聊天应用 → 创建空间、发送消息、打开线程。

元素清单

到达每个路由时，列出所有交互元素。按需建立清单——遍历过程中逐页建立，而非预先一次性列出所有元素。这决定了覆盖率指标：“已测试 /app/clients 上的 31 个元素中的 29 个。”

第 3 阶段 — 演练（审计本身）

交互清单（必需）

每次演练都必须生成一份清单。没有清单，结论即为“不完整”。

INTERACTION MANIFEST — /dashboard/spaces/marketing-pod
  Persona: SME owner, time-pressed, low tech comfort
  [✓] 14:32:01 Typed "@assistant test" into message input (textarea[placeholder*="message"])
  [✓] 14:32:03 Picked @assistant from autocomplete (li[data-mention-id="assistant"])
  [✓] 14:32:05 Clicked Send (button[aria-label="Send"])
  [✓] 14:32:06 Verified input cleared within 1000ms (textarea.value === "")
  [✓] 14:32:08 Verified message appeared in transcript ([data-message-id] count +1)
  [✓] 14:32:12 Opened thread on the message ([data-thread-trigger])
  [✓] 14:32:13 Verified main column width ≥ 200px after thread open (getBoundingClientRect().width)
  [✓] Console read after each step (0 warnings, 0 errors)
  [✓] Screenshot before + after each step
  [✓] Network requests inventoried (0 5xx, 0 403/404 on auth pages)

每个复选框都需要一次工具调用（点击、截图或读取控制台），并记录时间戳和选择器。没有完整清单，Agent 不能出具“通过”报告。

每个受审页面的必需条目：

• ≥ 1 个输入框中输入内容（真实文本，而非仅点击）
• ≥ 1 个主要操作已触发（发送／保存／提交／创建／发布——按实际情况选择）
• ≥ 1 个模态框或详情窗格已打开
• ≥ 1 次主要操作后的控制台读取
• ≥ 1 张主要操作前的截图，且至少 1 张主要操作后的截图
• 验证操作后的预期状态（输入框已清空、出现成功提示、路由已变更、列表已更新）

完整模板和回放流程见 references/interaction-manifest.md。

任务线程遍历

针对每个任务线程：

1. 从应用入口开始 — 不要从线程中途开始。真实用户会进入 / 或 /dashboard。
2. 以用户角色进行操作 — 如果他们会略读，就略读。如果他们会误读标签，就按误读的方式操作。记录犹豫之处。
3. 为每次状态变化截图 — 默认 → 悬停／聚焦 → 激活 → 点击后 → 加载后 → 确认。截图序列是证据。
4. 跟踪操作成本 — 点击次数、决策点、死路、意外中断后的恢复（第 3 步关闭标签页，第 4 步返回——状态是否保留？）
5. 在每个任务线程结束时，将截图交给子 Agent 审查。

每个任务线程结束时，以用户角色回答：任务是否明确结束？我还会回来吗？有什么办法能让这件事变得容易一倍？

参见 references/walkthrough-checklist.md 和 references/workflow-comprehension.md。

元素穷尽检查

对于每个路由，逐项检查清单中的元素。跳过任务线程遍历中已经操作过的元素。详情见 references/walkthrough-checklist.md。

对于每个列表／表格，如果数据量允许，都要在 0／1／100／1000+ 条数据时进行测试。

多窗格压力测试（适用于具有可折叠 UI 的应用，必须执行）

窗格组合会暴露最严重的布局问题——2026-04-29 出现的 spaces 垂直文本 bug，只有在 1024-1280px 且三个窗格全部打开时才会显现。对于具有侧边栏／成员／线程／抽屉／底部弹层的应用，运行以下矩阵：1920 / 1440 / 1280（高风险 bug） / 1024（灾难性 bug） / 768 / 375 × 全部打开、双窗格、单窗格、默认状态。对于每种组合：滚动最长的内容、截取屏幕截图，并运行布局检测 JS，检查溢出／裁切／竖排文本堆叠。完整矩阵、JS 代码片段和自动化流程见 references/multi-pane-stress.md。

首次使用者视角（必需）

除了固定的人设外，每个多页面功能都必须通过首次使用者检查。这是为了发现内部／AI 工具中最严重的用户体验问题：由设计者亲手打造的功能对他们来说很好用，但首次进入同一界面的新用户却完全不知道各个控件是什么意思。

采用首次登录此应用、没有任何背景信息、无法查看源代码、也没有内部文档可参考的人的视角。对每个界面都问问：

问题	能发现的问题
不读代码或文档，我能完成任务吗？	表单中隐藏的技术知识要求
字段标签是否通俗易懂，而非内部术语？	agentClass、slug、webhook_id 等泄漏到界面中
下拉菜单／选择器是否说明每个选项的作用，而不只是显示 ID？	snake_case 枚举值、原始类名、不透明的 slug
默认值是否合理，让我可以保留默认值继续操作？	必填字段没有默认值、必须手动输入 ID
需要输入内容时，是否能找到有效值列表？	本应使用组合框，却使用了自由文本输入框
如果我会因为不明白某项设置而说“点跳过”，那就是用户体验问题。	将可选但令人困惑的设置作为主要输入项展示

发现问题时，即使界面在技术上能正常工作，也要记录一条问题。常见的修复方式：将文本输入框替换为选择器、显示元数据、自动推导值、将内部 ID 收到“高级”选项下、添加行内说明。

如果一位首次使用该功能的新用户无需私下求助就能完成任务，界面才算通过这项检查。

实时交互冒烟测试

阅读代码可以确认按钮存在且有 onClick，但无法验证点击后是否真的产生了可观察的效果。对每个页面上的每个交互控件：

1. 点击控件。 指针移到控件上，控件高亮，点击成功触发。
2. 观察 Network 标签页。 是否发送了请求？URL 是否正确？方法和请求体是否正确？
3. 观察 DOM。 是否有可见变化——新增元素、移除元素、状态转换？
4. 如果（2）或（3）没有任何变化，那就是一个问题。

已知的无提示失败控件（工具调用卡片上的“批准／拒绝”、因弹出窗口被拦截而失败的对话框内 OAuth、异步验证表单、乐观 UI 删除、分页差一位、TanStack Query 缓存过期的筛选标签、缺少 Message-ID 的“回复／转发”）：完整的无提示失败清单和 SDK 契约检查（@ai-sdk/react、better-auth、TanStack Query、React Router v7、Radix Dialog、zodResolver）请参阅 references/live-interaction-smoke.md。

往返工作流完整性（必需）

由测试电池（Phase 5）中的场景 10 覆盖。在 Phase 3 演练中也要运行该场景——遍历线程时遇到的每个 A→B→A 流程，都必须先进行往返检查，再继续操作。完整流程请参阅 references/round-trip-workflows.md。

响应式检查

在每种宽度下运行布局检测 JS（溢出、裁切、文字不可见）。记录布局转换点。结合上文的多窗格压力测试，实现全面覆盖。

审计过程中身份验证过期

如果在之前已通过身份验证的路由上，导航或 API 调用返回 401/403，则会话已失效。不要悄悄重新进行身份验证——之后的每项观察都会受到影响。停止操作，记录导致问题的步骤（会话无提示过期本身就是一条问题），并以判定结果 Incomplete 结束。完整流程和问题判定标准请参阅 references/auth-expired-handling.md。

阶段 4 — 润色

视觉细节打磨

逐页微调，涵盖十类常见的 AI 痕迹：视觉居中、嵌套圆角规则、偏离尺度的间距、氛围感灰色、边框粗细不一致、阴影方向、动画时长偏离规范、悬停状态变化幅度校准、下划线／大写字母间距，以及对称布局与编辑式节奏之间的取舍。

此外，还要对按钮、徽章、输入框、下拉菜单、卡片、标签页、头像和 Toast 逐个组件进行视觉检查。

完整流程包含 DevTools 工作流、严重程度指南和用于校准的参考应用，详见 references/visual-polish.md。

组件完善检查清单

组件级的细致检查能发现页面级审查遗漏的问题。分为六类，每项都包含具体的「是／否」检查，并要求提供证明材料：

1. 按钮与触发器 —— 状态清晰度、意图匹配、微文案、加载状态、层级
2. 输入框与表单 —— 持续显示的标签、格式掩码、行内验证、错误清晰度、默认值设置
3. 导航与层级 —— 我在哪？点击深度、搜索逻辑、粘性页眉
4. 视觉一致性 —— 图标一致性、空状态、边框圆角、对比度
5. 移动设备与触控 —— 可点击区域（≥ 48×48）、键盘优化、滑动手势
6. 性能与反馈 —— 骨架屏、成功 Toast，仅在高风险操作时显示确认模态框

此外，每个主要组件都要检查六种视觉状态（默认、骨架屏、空状态、部分内容、错误、禁用）—— 空白页面上显示骨架屏不算骨架屏。

报告中的每个复选项都要注明证明材料（截图、控制台行、DOM 选择器、代码引用）。没有证明材料 = 不计入。

完整检查清单见 references/perfection-checklist.md。

自动化无障碍检查（axe-core，必做）

纯键盘手动检查（场景 5）能发现焦点陷阱和 Tab 顺序问题，但会漏掉约 80% 的结构性无障碍问题（标题跳级、悬停／焦点状态对比度不足、缺少 aria-label、角色不匹配）。axe-core 可在每页 <1 秒内覆盖这 80% 的问题。

对每个审查页面：

1. 通过 CDN 注入 axe-core（一个 script 标签）。
2. 页面稳定后运行 axe.run()。
3. 将违规项映射到审查发现（axe 的 critical → 审查中的 Critical，axe 的 serious → 审查中的 High，依此类推）。
4. 严格门槛：任一页面存在 > 0 项 axe Critical 或 > 0 项 axe Serious = 审查不通过。

对 16 条路由进行审查，运行时间总计约为 16 秒。可通过项目的 audit-config 将构建器模式参考页面（Components、Style guide）加入允许列表（路径回退链见 references/audit-config.md）。完整代码片段、严重程度映射和发现项格式见 references/a11y-automation.md。

性能预算（务实标准，必做）

在一个具有代表性的路由上运行一次 Performance API 采集（即真实用户最常访问的页面，通常是仪表盘或主要工作区）。务实阈值（LCP < 4.0s、CLS < 0.25、INP < 500ms）远高于故障水平，也低于 Google CWV 的「良好」等级。CWV 严格标准适用于落地页和营销团队；对于真实用户长时间使用的应用内部页面，务实标准才是合适的门槛。

将结果加入结论区块。任何阈值超标都必须判定为不通过。使用 Chrome DevTools Performance 跟踪进行诊断（大型主视觉、字体加载延迟、点击处理程序过重、水合开销）。完整测量代码片段、限流规格和常见问题见 references/performance-budget.md。

阶段 5 — 压力测试

场景测试套件（11 个场景）

始终覆盖全部 11 个场景。它们能发现逐屏测试遗漏的问题。完整测试方案见 references/scenario-tests.md。

1. 初次接触 — 在毫无先验知识的情况下摸清应用，为每个线程编写一份 2 分钟即可读完的简明指南。
2. 工作流中断 — 开始一项任务，关闭标签页、刷新页面，或在填写表单时离开。状态能否保留？
3. 误操作恢复 — 故意点错。需要点击几次才能恢复？
4. 回访用户 — 重复体验某个线程。速度更快吗？有快捷方式吗？能否看出自上次访问以来发生了哪些变化？
5. 仅用键盘 — 每个线程都只用键盘操作。焦点可见，Tab 顺序合理，按 Escape 可关闭。
6. 海量数据 — 填充 500 条以上记录。列表是否采用虚拟滚动，搜索结果是否正确，筛选条件是否能缩小范围？
7. 破坏性操作信心测试 — 每项删除、发送、发布、付款、分享操作都要明确征求同意，文案具体，并提供撤销功能。
8. 第二位用户（角色） — 使用受限角色（查看者而非编辑者，客户而非员工）。检查只读视图和权限错误。
9. 生命周期阶段 — 同一角色分别处于用户 #1（创始人）、#2（首位受邀者，状态尚不完整）、#N（后续加入者，工作区已有内容）时进行测试。每种情况呈现的现实都不同。
10. 往返工作流完整性 — 测试每个 A→B→A 流程：在 B 完成状态变更，返回时确认 A 已反映新状态，无需重新加载。返回入口应易于发现。页眉徽章应更新。这是导致“项目返回后就空了”问题的最大单一来源。
11. 数据时间跨度 — 准备 Day 0 / 1 / 7 / 30 的数据种子。带有时间跨度的数据能发现仅按数量填充数据时遗漏的问题：时间分隔线、按最近时间排序、cron 触发的副作用、通知徽章溢出、带历史记录的搜索性能、图表分桶。只有在不存在按时间分布的数据时才能跳过。

扩展压力测试方案

除了场景测试，还要运行 references/stress-test-recipes.md 中所有相关方案：

压力测试	能发现的问题
空内容／饱和内容／长内容	AI 在开发期间很少遇到的边界布局
竞态条件（双击、快速输入后失焦、慢速网络）	乐观 UI 错误、防抖失效
慢速网络（3G 限速）	加载状态、骨架屏节奏、超时体验
减少动态效果（prefers-reduced-motion: reduce）	忽略用户偏好的动画
i18n（较长的德语、RTL 阿拉伯语、CJK 字符宽度）	对文本长度的布局假设
离线模式	重试／队列／未保存状态体验
打印样式表	遗漏的媒体查询
高对比度模式	强制颜色媒体查询处理
真实场景风格数据测试套件（任何接受表单的应用都必须测试）	会静默剔除字符的校验（撇号、变音符号、RTL）；截断长度但不发出警告；未转义 SQL/XSS 探针字符串；不兼容的文件上传（.heic、8000×8000 PNG、50MB PDF）。AI 构建的 UI 中，开发数据以外的情况尤其容易出问题。

阶段 6 — 结论

结论区块（报告顶部必填）

═══════════════════════════════════════════════════════════
VERDICT: [Pass / Conditional Pass / Fail / Incomplete]

Persona: [locked persona slug]
Surfaces audited: N / M routes
Interaction Manifest: complete / incomplete (X of Y required entries)

Hard Gates: console errors [N], warnings [N], network 5xx [N], 403/404 auth [N], layout-collapse [N], axe Critical [N], axe Serious [N]   (all must be 0; allowlisted counts shown in parens)
Performance (on /[route]): LCP [N]s / CLS [N] / INP [N]ms — thresholds 4.0s / 0.25 / 500ms

Findings:
  Critical: [count]    High: [count]    Medium: [count]    Low: [count]

Self-critique pass (sub-agent): Drafted: [N]  Kept: [N]  Generic: [N]  Duplicate: [N]

Time per phase: Phase 3 [N]m / Total [N]m   (Phase 3 ≥ 5m for exhaustive)
Manifest plausibility: [N] entries (≥ 6/route), median gap [N]s (< 0.5s = Incomplete), [N] screenshots (≥ 2/route)

TOP 5 (ranked by impact × ease, senior-designer pick):
  1-5. [F-id] Title — one-sentence reason this edges out the others
═══════════════════════════════════════════════════════════

Top 5、自我审查环节，以及收尾段落（置于阶段 7 之后）均为必填项。缺少任何一项，结论均为 Incomplete。完整规范、格式和反模式见 references/audit-output-discipline.md。

自我审查环节（发布前必做）

完成发现问题的草稿后，派出一个全新的子 Agent，提供草稿列表并给出以下提示词：

“阅读这些审计发现。为每项标记 KEEP / GENERIC / DUPLICATE。KEEP = 针对这个应用、这个角色和这个界面的具体问题。GENERIC = 适用于任何 Web 应用。DUPLICATE = 与另一项发现根因相同。发布前删除 GENERIC 和 DUPLICATE 项。”

全新的子 Agent 更合适，因为原始起草者会倾向于维护自己的产出。在当前上下文中进行自我审查，往往会为问题辩护，而不是删减。记录审查结果：Drafted: 23 Kept: 14 Generic: 5 Duplicate: 4。

审计审计流程触发条件（不可妥协，自动转为不完整）

信号	表明
第 3 阶段耗时 < 1m / 穷尽式审计的清单首尾时间跨度 < 5m	演练被跳过或仓促完成
清单条目之间的中位间隔 < 0.5s	条目是批量生成的，没有真实交互
截图数量少于路由数的 2 倍 / 控制台读取次数少于路由数	页面并未经过实际检查
前 5 项缺失或用占位内容填充	审计纪律被破坏（见 audit-output-discipline.md）
未记录自我批评环节	未清除填充内容
发现项使用“建议修复”/“考虑 X”/“改进 Y”	补丁形同填充内容，无法提交
[✓] 通过项缺少一句话证明 + 佐证材料	凭感觉通过
缺少“握在手中的实物”段落	未进行整体判断

发现项格式（每项发现都必须遵循）

每项发现都必须包含：ID（严重程度字母 + 数字）、层级（架构 / 交互 / 视觉 / 反馈 / 愉悦感）、严重程度、涉及界面（路由 + 视口 + 面板）、用户画像、复现步骤（编号步骤）、实际情况、预期情况、证据（截图路径 + 控制台 / 网络捕获）、疑似位置（file:line）、最小可行补丁（具体且可提交——不能写“建议修复”/“考虑 X”）。缺少复现步骤 + 证据 + 疑似位置的发现项将被拒绝。填充式补丁（“改进 X”“考虑 Y”“让 Z 更好”）会在自我批评环节被判为不完整。示例及五层层级见 references/report-template.md 和 references/perfection-checklist.md。纪律规则见 references/audit-output-discipline.md。

握在手中的实物（强制结尾段落）

每次审计都必须以一个段落结束，不使用模板，并回答：如果这个应用是一个实体物品，我会想把它握在手里吗？ 这是唯一一个以感受为重点的部分——清单无法呈现的整体判断。格式和示例见 references/audit-output-discipline.md。

完美路线图（必需）

将发现项分组为：

• 快速见效（24-48h）——微文案、悬停状态、对比度修复、单行 CSS 调整
• 结构性改进（1-2 weeks）——基础组件替换、路由重组、多面板重构
• 高级润色（发布后）——微动画、骨架屏变体、个性化空状态

完整报告结构见 references/report-template.md。

第 7 阶段——修复并验证

报告完成后，提供以下循环：

“发现 N 个严重问题和 M 个高优先级问题。现在修复并重新验证吗？”

如果是：

1. 按文件 / 区域对发现项分组
2. 逐项修补
3. 仅重新走查受影响的部分（而非整个应用）——包括最初暴露该缺陷的交互，并重新截图
4. 更新报告：标记为 ✓ fixed、✗ still present 或 ⚠ new issue found
5. 以“本次会话中已修复”摘要收尾

在一次会话中完成闭环，无需等到明天再审计。

与 ux-extract 和 brains-trust 交叉参考

如果存在模式库（回退顺序：.jez/artifacts/ux-extracts/<ref>.md → docs/ux-extracts/<ref>.md → audits/extracts/<ref>.md），请在开始前阅读，并以此作为发现项的标准。

给出结论后，可选择运行 dev-tools:brains-trust 进行第二意见审查（每 4-6 周一次）。合并发现项时，按 (reproduction-steps, suspected-location) 去重——第二个模型发现的同一缺陷应合并为一项并附上两条确认，而不是拆成两项。添加一行 Confirmed by:。不要逐字附加第二份报告，否则会产生噪声并夸大严重程度。

30 秒 Dogfood 演练（项目级规则）

审计工作量很大。对于每次变更的部署前检查，建议在 CLAUDE.md 中添加一条项目规则：

宣布任何 UI 变更“完成”之前，先进行 30 秒 Dogfood 演练：

1. 打开受影响的页面
2. 在任意输入框中输入内容
3. 点击主要操作
4. 观察后续状态 2 秒
5. 打开相关视图（线程、模态框、详情）
6. 查看控制台 如果任何一步出现意外行为，这项变更就还没完成。

六个步骤，约 30 秒。能发现立即显现的行为问题。每周再配合一次完整的 ux-audit。

Playwright 杀手级流程测试

审计可以发现当前存在的问题。测试可以防止回归。建议为杀手级流程编写 10-15 个 Playwright 测试——入门示例见 references/playwright-killer-flows.md（发送后输入框会清空、挂载时没有控制台警告、打开线程后消息列宽度 ≥ 200px、@-mention 恰好生成一个标签等）。通过 CI 在每次部署时运行。

自主性

• 直接执行：导航、截图、阅读页面、注入布局检测 JS、使用虚构测试数据提交表单、编写报告文件、派遣截图审查子 Agent。
• 先询问：破坏性操作（删除、发送、发布、付款）。进行破坏性置信度测试时，在运行该场景前询问一次。
• 停止并确认：任何会向外部人员发送邮件或通知的操作。

执行规范

1. 在主会话中执行审计，不要交给子 Agent。 跨交互状态保存在持续观察的会话中。新的子 Agent 一开始没有上下文，也会遗漏二阶发现。
2. 直接使用浏览器工具。 在主会话中使用 Chrome MCP 或 Playwright MCP。不要把截图交给一个全新的 Agent 发表意见。
3. 不断尝试不同变体，直到没有新发现。 每轮之后，换一个角度继续测试（不同的角色、工作流、输入量或起始点）。只有完整一轮没有产生新发现时才停止。

对于预计运行时间超过 30 分钟的审计，请在主会话旁设置每 15 分钟一次的 /loop 检查点——它会记录发现、帮助会话保持上下文，并提供自然的终止信号。参见 references/long-running-check-in-pattern.md。

参考文件

时间	阅读
跨技能输出规范（Top 5、自我批评、最小补丁、proof-PASS、hold-this）	references/audit-output-discipline.md
项目适配——非默认技术栈（NextAuth/Lucia/Devise/Django 身份验证、Prisma/TypeORM/ActiveRecord 种子数据、WordPress/Rails/Django URL 发现、按应用类型划分的角色库）	references/project-adaptation.md
角色库 + 写作协议 + 角色过载模式	references/persona-lock.md
审计过程中身份验证过期——协议 + 无头测试身份验证恢复	references/auth-expired-handling.md
数据调味时间跨度（第 0/1/7/30 天）+ 项目种子脚本架构	references/data-seasoning.md
审计配置允许列表格式 + 语义 + 界面覆盖项	references/audit-config.md
交互清单模板 + 重放协议	references/interaction-manifest.md
多窗格压力测试矩阵 + 自动化片段	references/multi-pane-stress.md
各屏幕评估问题、布局检测 JS	references/walkthrough-checklist.md
导航指引、心智模型、页面间连贯性	references/workflow-comprehension.md
11 种场景的完整协议	references/scenario-tests.md
扩展压力测试方案（竞态、慢速网络、减少动态效果、i18n）	references/stress-test-recipes.md
组件级完善度检查清单（6 个类别 + 6 种状态）	references/perfection-checklist.md
AI 特征目录、视觉居中、设计令牌规范	references/visual-polish.md
静默失败控制 + SDK 合约检查	references/live-interaction-smoke.md
Playwright 关键流程测试起始模板	references/playwright-killer-flows.md
报告格式、结论区块、严重程度分级、复现步骤格式	references/report-template.md
浏览器工具命令和视口说明	references/browser-tools.md
往返工作流完整性（A→B→A 模式）	references/round-trip-workflows.md
自动化无障碍检查（注入 axe-core + 严重程度映射）	references/a11y-automation.md
实用性能预算（通过 Performance API 测量 LCP/CLS/INP）	references/performance-budget.md
通过 15 分钟 /loop 监督长时间运行的审计	references/long-running-check-in-pattern.md

提示

• 每次犹豫都值得记录为发现。 如果你停下来思考该点哪里，这就是值得报告的摩擦。
• 尽情使用吸管工具。 这是发现氛围灰色、偏离设计令牌的颜色和设计系统漂移最快的方法。
• 覆盖率就是算术。 已测试项 ÷ 已盘点项。在报告中公布这个比率。
• 使用子 Agent 审查截图，并逐步记录发现。 不要在一个循环中既操作浏览器，又分析 200 张截图。报告文件比你的上下文更省资源。