Back to Details

user-acceptance

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Running User Acceptance Walkthroughs

执行用户验收走查

Overview

概述

Acceptance at delivery time should be experiential, not just a test summary. Primary goal: help the human directly see and feel what changed before merge. If work is not user-facing, run and show executable proof with user-impact translation. For user-facing work, run a live end-to-end demo using the appropriate automation tool for the platform. Then give the user instructions for running it themselves.
交付阶段的验收应当是体验式的，而非仅提供测试总结。 核心目标：帮助相关人员在merge前直观看到、感知到变更内容。 如果工作内容不面向用户，需要运行并展示可执行的证明，同时说明对用户的影响。 对于面向用户的工作，使用平台对应的自动化工具运行实时端到端演示，然后为用户提供自行运行的操作指引。

When to Use

适用场景

  • End of PR/ticket prompts: "UAT", "verify", "walk me through", "show what changed", "can we merge?"
  • Sign-off requests where confidence requires direct observation, not only CI output
  • Mixed work (UI + backend/infrastructure) that needs both walkthrough and proof
Do not use for mid-implementation debugging or code-quality review without acceptance intent.
  • PR/ticket收尾阶段的提示语："UAT"、"verify"、"walk me through"、"show what changed"、"can we merge?"
  • 需要直接观察而非仅靠CI输出结果来确认的签署请求
  • 同时包含UI+后端/基础设施、需要同时走查和证明的混合工作
请勿用于开发中途调试，或是没有验收意图的代码质量评审场景。

Decision Flow

决策流程

dot
digraph uat_flow {
  "End-of-ticket or PR acceptance?" [shape=diamond];
  "Any user-facing behavior changed?" [shape=diamond];
  "Detect platform" [shape=diamond];
  "Can agent execute proof locally?" [shape=diamond];
  "Run web/Electron demo" [shape=box];
  "Run iOS/macOS demo" [shape=box];
  "Run CLI/API demo" [shape=box];
  "Provide reproducible proof plan + user run steps" [shape=box];

  "End-of-ticket or PR acceptance?" -> "Any user-facing behavior changed?" [label="yes"];
  "Any user-facing behavior changed?" -> "Detect platform" [label="yes"];
  "Any user-facing behavior changed?" -> "Can agent execute proof locally?" [label="no"];
  "Detect platform" -> "Run web/Electron demo" [label="web or Electron"];
  "Detect platform" -> "Run iOS/macOS demo" [label="iOS/macOS native"];
  "Detect platform" -> "Run CLI/API demo" [label="CLI/API/backend"];
  "Can agent execute proof locally?" -> "Run CLI/API demo" [label="yes"];
  "Can agent execute proof locally?" -> "Provide reproducible proof plan + user run steps" [label="no"];
}
dot
digraph uat_flow {
  "End-of-ticket or PR acceptance?" [shape=diamond];
  "Any user-facing behavior changed?" [shape=diamond];
  "Detect platform" [shape=diamond];
  "Can agent execute proof locally?" [shape=diamond];
  "Run web/Electron demo" [shape=box];
  "Run iOS/macOS demo" [shape=box];
  "Run CLI/API demo" [shape=box];
  "Provide reproducible proof plan + user run steps" [shape=box];

  "End-of-ticket or PR acceptance?" -> "Any user-facing behavior changed?" [label="yes"];
  "Any user-facing behavior changed?" -> "Detect platform" [label="yes"];
  "Any user-facing behavior changed?" -> "Can agent execute proof locally?" [label="no"];
  "Detect platform" -> "Run web/Electron demo" [label="web or Electron"];
  "Detect platform" -> "Run iOS/macOS demo" [label="iOS/macOS native"];
  "Detect platform" -> "Run CLI/API demo" [label="CLI/API/backend"];
  "Can agent execute proof locally?" -> "Run CLI/API demo" [label="yes"];
  "Can agent execute proof locally?" -> "Provide reproducible proof plan + user run steps" [label="no"];
}

Step-by-Step Workflow

分步工作流

1. Identify scope, mode, and platform

1. 确定范围、模式和平台

  • Confirm what behavior is being accepted.
  • Declare 
    Mode
    : 
    user-facing
    , 
    non-user-facing
    , or 
    mixed
    .
  • For user-facing work, detect 
    Platform
    to select the right demo tool:
SignalPlatformPlaybook
Xcode project, 
.xcodeproj
, 
.swift
files, iOS simulator		iOS/macOS native
./references/ios-demo-playbook.md
Web app, 
package.json
with dev server, browser-based UI		Web
./references/web-demo-playbook.md
Electron app, 
electron
in dependencies		Electron
./references/web-demo-playbook.md
(Electron section)
CLI tool, API endpoint, backend service, infrastructureCLI/API
./references/cli-api-demo-playbook.md
If the platform is ambiguous, ask the user.
  • 确认需要验收的功能范围。
  • 声明
    模式
    ：
    user-facing
    （面向用户）、
    non-user-facing
    （非面向用户）或
    mixed
    （混合）。
  • 面向用户的工作需要检测
    平台
    以选择正确的演示工具：
识别信号平台操作手册
Xcode项目、
.xcodeproj
、
.swift
文件、iOS模拟器		iOS/macOS native
./references/ios-demo-playbook.md
Web应用、含开发服务器配置的
package.json
、浏览器端UI		Web
./references/web-demo-playbook.md
Electron应用、依赖中包含
electron
Electron
./references/web-demo-playbook.md
(Electron章节)
CLI工具、API端点、后端服务、基础设施CLI/API
./references/cli-api-demo-playbook.md
如果平台无法明确判断，请询问用户。

2. Define acceptance slices

2. 定义验收分片

Break validation into small slices (2-5), each with clear pass/fail criteria.
How to derive slices:
  • Start from the ticket's acceptance criteria if they exist
  • Otherwise, map each user-visible behavior change to a slice
  • For non-user-facing work, map each functional change to a demonstrable proof
  • Each slice should be independently verifiable — avoid slices that only pass if run in sequence
将验证拆分为2-5个小的分片，每个分片都有明确的通过/失败标准。
分片拆分方法：
  • 如果ticket有验收标准，优先基于验收标准拆分
  • 否则将每个用户可见的行为变更对应为一个分片
  • 非面向用户的工作，将每个功能变更对应为一个可演示的证明项
  • 每个分片应当可以独立验证——避免只有按顺序运行才能通过的分片

3. Execute validation

3. 执行验证

Follow the appropriate playbook:
  • User-facing (web/Electron): 
    ./references/web-demo-playbook.md
  • User-facing (iOS/macOS): 
    ./references/ios-demo-playbook.md
  • Non-user-facing or CLI/API: 
    ./references/cli-api-demo-playbook.md
  • Mixed: run user-facing demo first, then technical proof tied to the same outcome.
遵循对应的操作手册：
  • 面向用户（web/Electron）： 
    ./references/web-demo-playbook.md
  • 面向用户（iOS/macOS）： 
    ./references/ios-demo-playbook.md
  • 非面向用户或CLI/API： 
    ./references/cli-api-demo-playbook.md
  • 混合模式： 先运行面向用户的演示，再提供对应结果的技术证明。

4. Capture evidence

4. 留存证据

  • Save screenshots/video for user-facing slices.
  • Save exact commands and key output lines for technical slices.
  • 面向用户的分片保存截图/视频。
  • 技术分片保存执行的准确命令和关键输出行。

5. Report results to the user

5. 向用户反馈结果

  • Start with overview and scope bullets.
  • List each slice with explicit 
    Pass
    /
    Fail
    .
  • Provide instructions to the user for running the same validation themselves.
  • End with 
    Recommendation
    : 
    GO
    , 
    GO with follow-ups
    , or 
    NO-GO
    .
  • 开头先提供概述和范围要点。
  • 列出每个分片的明确
    Pass
    /
    Fail
    结果。
  • 为用户提供自行执行相同验证的操作指引。
  • 结尾给出
    建议
    ：
    GO
    （可合并）、
    GO with follow-ups
    （可合并但需后续跟进）或
    NO-GO
    （不可合并）。

6. Update ticket (required on success)

6. 更新ticket（成功时必填）

If recommendation is 
GO
or 
GO with follow-ups
, post a ticket comment in the project system of record (check CLAUDE.md or project config; common systems: Linear, Jira, GitHub Issues) with:
  1. UAT verdict (
    GO
    / 
    GO with follow-ups
    )
  2. Scope validated (2-5 bullets)
  3. Mode and platform used
  4. Slice-by-slice pass/fail summary
  5. Evidence links or file paths (screenshots, videos, logs)
  6. Commands run (for non-user-facing or mixed technical slices)
  7. Any follow-ups or residual risks
If no ticket is known, ask for the ticket ID before closing UAT. Do not mark acceptance complete until this ticket update is posted.
如果建议为
GO
或
GO with follow-ups
，请在项目对应的工单系统中发布ticket评论（可查看CLAUDE.md或项目配置，常见系统：Linear、Jira、GitHub Issues），评论需包含：
  1. UAT结论（
    GO
    / 
    GO with follow-ups
    ）
  2. 验证的范围（2-5个要点）
  3. 使用的模式和平台
  4. 分片级别的通过/失败汇总
  5. 证据链接或文件路径（截图、视频、日志）
  6. 执行的命令（非面向用户或混合模式的技术分片）
  7. 后续待办事项或剩余风险
如果无法找到对应ticket，请在关闭UAT前询问用户ticket ID。在ticket更新完成前，请勿标记验收已完成。

Quick Reference

快速参考

ModeFirst stepEvidence requiredDone when
user-facingRun platform-appropriate demo (slice 1)Demo trace + screenshots/video + observed UIUser confirms pass/fail for all scenarios
non-user-facingRun proof command(s)Command output + impact translationReproducible evidence reviewed
mixedUser-facing demo first, then technical proofBoth demo evidence and technical proofBoth layers accepted
模式第一步所需证据完成标准
user-facing运行适配平台的演示（分片1）演示记录 + 截图/视频 + 观测到的UI用户确认所有场景的通过/失败结果
non-user-facing运行证明命令命令输出 + 影响说明可复现的证据已通过审核
mixed先做面向用户的演示，再提供技术证明演示证据和技术证明都需提供两层变更都已通过验收

Common Mistakes

常见错误

  • Dumping a static checklist with no interaction
  • Reporting only test counts with no demonstration
  • Skipping a live demo for user-facing changes
  • Skipping non-UI demo because there is no frontend change
  • Declaring merge readiness before collecting explicit pass/fail signals
  • Using the wrong demo tool for the platform (e.g., agent-browser for an iOS app)
  • 只提供静态检查清单，没有交互内容
  • 只上报测试数量，没有演示内容
  • 面向用户的变更跳过实时演示
  • 因为没有前端变更就跳过非UI演示
  • 未收集明确的通过/失败信号就声明可合并
  • 对平台使用错误的演示工具（例如对iOS应用使用agent-browser）

Rationalization Table

合理化对照表

ExcuseReality
"No UI changes, so UAT is just unit tests."Non-user-facing work still needs demonstrable proof and user-impact explanation.
"We are in a rush, give a fast merge checklist."Time pressure increases need for clear GO/NO-GO evidence.
"I already summarized everything; that is enough."Summaries do not replace user experience or executable demonstration.
"User can test later after merge."Acceptance belongs before merge unless explicitly deferred by user.
"Tests pass, so it works."Tests prove code correctness. Acceptance proves the right thing was built.
借口实际情况
"没有UI变更，所以UAT只要跑单元测试就行。"非面向用户的工作仍然需要可演示的证明以及对用户影响的说明。
"我们赶时间，给个快速合并的检查清单就行。"时间压力越大，越需要清晰的通过/不通过证据。
"我已经总结了所有内容，足够了。"总结不能替代用户体验或是可执行的演示。
"用户可以在合并后再测试。"验收应当在合并前完成，除非用户明确要求延后。
"测试都通过了，所以功能没问题。"测试证明代码是正确的，验收证明我们建了正确的功能。

Red Flags - Stop and Correct

危险信号 - 请立即停止并修正

  • You are about to send only a summary/checklist.
  • You cannot point to any observed behavior or executed proof.
  • You are treating CI green status as equivalent to acceptance.
  • You are asking for merge without an explicit acceptance signal.
  • You skipped platform detection and defaulted to the wrong demo tool.
  • 你正准备只发送总结/检查清单。
  • 你拿不出任何观测到的行为或是已执行的证明。
  • 你把CI的绿色状态等同于验收通过。
  • 你没有拿到明确的验收信号就申请合并。
  • 你跳过了平台检测，默认使用了错误的演示工具。