update-validation-requirements git:20261006.f659408A

Immutable. This exact content never changes and is served at /api/v1/blob/ca248f88c9636115.

---
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. 无法通过已有测试（单元测试、集成测试、端到端测试）可靠验证，必须在真实设备、真实环境或真实交互中验证的场景。

**先排除已覆盖的场景**：同目录 `yymmdd-{name}.e2e.md`（`e2e-tester` 报告）里已经测过的场景、以及单元/集成测试已覆盖的场景，都不要重复列入用户验证表。用户验证只收自动化测试覆盖不到、必须由用户亲自确认的残余风险项；没有符合条件的项时不要凑数造表，直接在文档中写明无需额外用户验证。

## 表格格式（固定契约）

验证表要能被脚本检索，格式不要自由发挥：

- 位置固定：一级标题 `# {feature_or_issue_name} 用户验证`，验证表固定放在二级标题 `## 验证项` 下。
- 列固定 6 列且顺序不变：`#`、`验证步骤`、`预期结果`、`实际结果`、`状态`、`备注/证据`。
- 分隔行固定：`| --- | --- | --- | --- | --- | --- |`。
- 一行一个验证项，`#` 从 1 起顺序编号；新建时 `实际结果`、`备注/证据` 留空，`状态` 一律填 `待验证`。
- 单元格只写单行文本：不要合并单元格，不要在单元格里嵌表格、列表或换行。
- `状态` 只能取四个值之一：`待验证`、`通过`、`不通过`、`受阻`。

这样 `rg '\| 待验证 \|' -g '*.validation.md'` 之类的脚本才能稳定捞出尚未验证的条目。

## 文档骨架

```markdown
# {feature_or_issue_name} 用户验证

## 验证说明

- 验证对象：{本次需要用户确认的功能或问题}
- 环境/前置条件：{设备、系统、账号、数据或其他必要条件；无则写“无”}

## 验证项

| #   | 验证步骤             | 预期结果               | 实际结果 | 状态   | 备注/证据 |
| --- | --- | --- | --- | --- | --- |
| 1   | {清晰、可重复的步骤} | {可观察、可判断的结果} | {留空}   | 待验证 | {留空}    |

## 验证结论

{用户验证后填写总体结论；未完成时写“待验证”。}

## 待跟进

{记录不通过、受阻场景及补充信息；无则写“无”。}
```

## 更新已有文档时

- 保留用户已经填写的实际结果、状态、备注和证据；不要代替用户改动已填写的状态。
- 不覆盖或改写历史反馈；若实现变化使旧结果失效，新增验证项或明确标记需要重新验证。
- 删除验证项前确认其已不再适用，并保留仍有沟通价值的问题记录。