git:20260726.6db2d65 to git:20261006.f659408
22 added, 9 removed. Audit A to A.
---
name: update-validation-requirements
description: 创建或更新需求、问题的用户验证要求文档。当实施内容需要用户验收，尤其需要真实设备、真实环境或真实交互验证时使用。
user-invocable: true
---
# update-validation-requirements
创建或更新用户验证要求文档：
- 需求：`{project_root}/docs/features/yymmdd-{feature_name}/yymmdd-{feature_name}.validation.md`
- 问题：`{project_root}/docs/issues/yymmdd-{issue_name}/yymmdd-{issue_name}.validation.md`
验证文档是 Agent 与用户沟通验证结果的共享表格。只记录：
1. 最重要、最能证明功能或修复是否成立的核心场景。
- 2. 无法通过已有单元测试、集成测试可靠验证，必须在真实设备、真实环境或真实交互中验证的场景。
+ 2. 无法通过已有测试（单元测试、集成测试、端到端测试）可靠验证，必须在真实设备、真实环境或真实交互中验证的场景。
- 格式参考：
+ **先排除已覆盖的场景**：同目录 `yymmdd-{name}.e2e.md`（`e2e-tester` 报告）里已经测过的场景、以及单元/集成测试已覆盖的场景，都不要重复列入用户验证表。用户验证只收自动化测试覆盖不到、必须由用户亲自确认的残余风险项；没有符合条件的项时不要凑数造表，直接在文档中写明无需额外用户验证。
+ ## 表格格式（固定契约）
+
+ 验证表要能被脚本检索，格式不要自由发挥：
+
+ - 位置固定：一级标题 `# {feature_or_issue_name} 用户验证`，验证表固定放在二级标题 `## 验证项` 下。
+ - 列固定 6 列且顺序不变：`#`、`验证步骤`、`预期结果`、`实际结果`、`状态`、`备注/证据`。
+ - 分隔行固定：`| --- | --- | --- | --- | --- | --- |`。
+ - 一行一个验证项，`#` 从 1 起顺序编号；新建时 `实际结果`、`备注/证据` 留空，`状态` 一律填 `待验证`。
+ - 单元格只写单行文本：不要合并单元格，不要在单元格里嵌表格、列表或换行。
+ - `状态` 只能取四个值之一：`待验证`、`通过`、`不通过`、`受阻`。
+
+ 这样 `rg '\| 待验证 \|' -g '*.validation.md'` 之类的脚本才能稳定捞出尚未验证的条目。
+
+ ## 文档骨架
+
```markdown
# {feature_or_issue_name} 用户验证
## 验证说明
- 验证对象：{本次需要用户确认的功能或问题}
- 环境/前置条件：{设备、系统、账号、数据或其他必要条件；无则写“无”}
## 验证项
- | 验证步骤 | 预期结果 | 实际结果 | 状态 | 备注/证据 |
- | -------------------- | ---------------------- | -------- | ------ | --------- |
- | {清晰、可重复的步骤} | {可观察、可判断的结果} | {留空} | 待验证 | {留空} |
-
- 状态使用：`待验证`、`通过`、`不通过`、`受阻`。
+ | # | 验证步骤 | 预期结果 | 实际结果 | 状态 | 备注/证据 |
+ | --- | --- | --- | --- | --- | --- |
+ | 1 | {清晰、可重复的步骤} | {可观察、可判断的结果} | {留空} | 待验证 | {留空} |
## 验证结论
{用户验证后填写总体结论；未完成时写“待验证”。}
## 待跟进
{记录不通过、受阻场景及补充信息；无则写“无”。}
```
- 更新已有文档时：
+ ## 更新已有文档时
- - 保留用户已经填写的实际结果、状态、备注和证据。
+ - 保留用户已经填写的实际结果、状态、备注和证据；不要代替用户改动已填写的状态。
- 不覆盖或改写历史反馈；若实现变化使旧结果失效，新增验证项或明确标记需要重新验证。
- 删除验证项前确认其已不再适用，并保留仍有沟通价值的问题记录。