别再写“功能正常”：我给 Codex 的前端验收标准，会落实到这 5 类证据

上一篇我把前端需求中最容易遗漏的边界拆成了七类。

边界找出来以后，不能只停在讨论里。它们最终要进入验收标准，否则 Codex 写完代码后，我们仍然只能凭感觉判断“应该差不多了”。

我见过最常见的验收描述，大概是这些：

  • 功能正常。

  • 页面无报错。

  • 代码符合规范。

  • 接口调用正确。

  • 兼容各种情况。

  • 不影响原有功能。

这些话方向都对，但几乎不能执行。

“功能正常”到底要点哪些按钮？“接口正确”要看请求参数还是只看返回成功？“不影响原有功能”要回归哪些路径？“代码符合规范”由什么检查或差异证明？

如果标准不能转成具体动作，就很难区分“真正完成”和“看起来完成”。

所以我现在写给 Codex 的验收标准，会尽量落实成五类证据：

  1. 行为证据。

  2. 数据证据。

  3. 修改范围证据。

  4. 自动检查证据。

  5. 页面体验证据。

它们分别回答：用户操作对不对、数据流对不对、代码有没有越界、工具检查有没有通过、真实页面能不能交付。

验收标准要在写代码之前定义

很多团队习惯在功能做完后再想怎么测试。

AI 参与开发以后，这个顺序更容易出问题。

如果一开始没有定义完成标准，Codex 会自然地把“代码已经修改”当成主要交付物。它可能列出修改了哪些文件、实现了哪些方法，再补一句“建议运行测试”。

但我们真正需要的不是修改说明，而是完成证据。

提前写验收标准有三个作用。

第一，暴露需求里的歧义

例如：

重置用户列表的筛选条件。

一旦开始写验收步骤，就会发现必须回答：

  • 重置后是否立即请求？

  • 页码是否回到第一页？

  • 每页数量是否恢复默认？

  • 固定组织条件是否保留？

验收标准不是实现结束后的附属文档，它本身就在帮助我们补需求。

第二，约束实现范围

如果验收只要求修正当前列表的重置行为，就没有必要顺手重构公共分页组件。

验收标准越具体，越容易判断哪些修改与目标无关。

第三，让 Codex 知道什么时候应该停止

一个没有终点的任务，很容易不断增加“优化”。

当行为路径、请求数据、项目检查和页面验证都已经满足约定，任务就应该进入交付，而不是继续重命名、抽方法或统一代码风格。

OpenAI 当前的 Codex 迭代用例也强调，复杂任务开始前应先定义成功如何衡量，并结合可确定的检查和可直接审查的产物持续评估。对前端开发来说，这个思路不必只用于大型优化任务；一个普通页面需求也应该先明确通过条件。

第一类证据：用户行为是否得到正确结果

行为证据是最接近需求的一层。

我会用这个结构写：

前置状态 → 用户动作 → 可观察结果 → 保持不变的内容

例如：

前置状态：
- 当前在用户列表第 3 页
- 姓名筛选为“张”
- 状态筛选为“启用”
​
用户动作：
- 点击重置
​
可观察结果：
- 姓名和状态恢复默认值
- 页码变为 1
- 使用默认条件重新请求列表
​
保持不变：
- 每页数量不变
- 页面权限和列配置不变

这里“保持不变”很重要。

很多 AI 修改不是没有完成目标，而是在完成目标时顺便改变了其他行为。只写期望变化，无法约束副作用。

行为证据至少要覆盖三种路径：

正常路径

用户按预期顺序完成操作。

例如：

  • 输入条件后查询。

  • 打开弹窗并成功保存。

  • 删除记录后刷新列表。

异常路径

接口失败、校验失败、权限不足或数据已变化。

例如：

  • 保存失败后弹窗不关闭。

  • 用户输入仍然保留。

  • 保存按钮恢复可点。

  • 使用项目既有方式提示错误。

连续操作路径

多个动作组合后状态仍然一致。

例如：

  • 查询 → 翻页 → 重置。

  • 编辑 → 校验失败 → 关闭 → 新增。

  • 提交失败 → 修改内容 → 再次提交。

前端状态问题很少只出现在单次点击中。连续路径往往比单个按钮更有验收价值。

第二类证据：页面状态和请求数据是否一致

页面看起来正确，不代表发给接口的数据正确。

例如，搜索表单显示已重置，但请求对象仍然保留上一次的状态字段；时间范围显示本地日期，实际发送时边界多了一天；多选清空后发送空数组，而接口约定是不发送字段。

所以我会单独写数据证据。

数据证据通常包含：

  • 页面输入值。

  • 内部状态。

  • 请求参数。

  • 响应转换。

  • 最终渲染结果。

可以写成一张表：

场景 页面状态 请求参数 预期结果
有条件查询 状态为启用 status = enabled 只显示启用数据
空条件查询 状态为空 不发送 status 使用默认列表
时间范围 选择开始和结束日期 按接口约定转换边界 结果范围与选择一致
重置 条件恢复默认 参数不含旧条件，pageNum = 1 请求第一页默认数据

如果接口无法真实调用，也不能把数据证据写成“已通过”。

这时可以验证：

  • 类型定义。

  • 参数构造逻辑。

  • 单元测试或模拟请求。

  • 现有接口契约。

并把真实联调明确列为未验证。

验收的价值不在于所有格子都写“通过”，而在于已验证和未知之间没有混淆。

第三类证据：代码修改是否控制在任务范围内

前端任务验收经常只看功能，不看差异。

AI 生成的代码可能实现了目标，同时带来：

  • 无关文件格式化。

  • 新增重复工具方法。

  • 改写公共组件默认行为。

  • 修改接口字段含义。

  • 引入没有必要的依赖。

  • 删除尚未确认用途的代码。

这些问题在页面正常路径里未必能立刻发现。

所以修改范围本身也要验收。

我会要求交付时列出：

  1. 修改了哪些文件。

  2. 每个文件为什么必须修改。

  3. 是否存在与任务无关的差异。

  4. 是否改变公共 API、默认值或共享类型。

  5. 是否新增依赖、配置或全局样式。

  6. 是否发现问题但没有纳入本次修改。

例如：

## 修改范围验收
​
- 用户列表页面：修正重置时的状态恢复和查询顺序。
- 用户列表测试：覆盖查询、翻页、重置的连续路径。
- 用户接口模块：未修改。
- 公共分页组件：未修改。
- 无新增依赖，无全局样式变化，无无关格式化。

“改得少”不是目标，“每一处修改都能解释”才是。

一个任务可能合理地改动多个文件，只要它们共同完成一个明确行为；一处无关的公共重构，即使只有几行，也可能超出范围。

第四类证据：项目已有的自动检查是否通过

自动检查可以稳定发现一部分问题：

  • 类型错误。

  • 代码规范问题。

  • 单元逻辑回归。

  • 构建失败。

  • 测试用例不通过。

但我不会笼统写“运行相关检查”，而会要求先从项目配置中确认真实命令。

例如：

## 自动检查
​
- 类型检查：项目实际命令，结果为通过或列出失败项。
- Lint：项目实际命令，结果为通过或列出失败项。
- 相关测试：具体测试文件或范围，结果为通过或列出失败项。
- 构建：本任务风险需要时执行，并记录结果。

这里有四个细节。

不猜命令

不同项目的包管理器和脚本名称不同。先读 package.json，再执行项目真实提供的命令。

不把既有失败算成通过

如果检查本来就有错误，要区分：

  • 本次修改新增的错误。

  • 修改前已经存在的错误。

  • 当前环境无法判断的错误。

不能因为“不是我造成的”就把整项写成通过，也不能把所有历史问题都顺手修掉。

不用构建通过替代业务验收

构建成功证明代码能够进入构建流程，不证明查询、重置、权限和异常路径符合需求。

不只写“已检查”

交付说明要包含：

  • 执行了什么。

  • 结果是什么。

  • 没执行什么。

  • 为什么没执行。

没有结果的检查名称，不算证据。

第五类证据：真实页面是否可用

前端代码最终要在页面中运行。

只看差异、类型和测试，很难覆盖：

  • 弹窗是否被遮挡。

  • 长文本是否溢出。

  • 按钮在窄屏下是否还能操作。

  • Loading 是否卡住。

  • 焦点和校验提示是否正确。

  • 连续点击是否触发重复请求。

  • 空状态和错误状态是否符合预期。

页面证据要根据任务风险选择，不是每次都做全站回归。

我通常从五个维度检查：

维度 示例
功能 点击、输入、提交、关闭是否符合要求
状态 Loading、禁用、错误、空状态能否正确恢复
视觉 遮挡、溢出、错位、长内容和窄屏表现
交互 连续操作、键盘、焦点和重复点击
回归 与本次修改直接相关的原有路径是否保持

页面验证也要写成路径，而不是一句“手动测试通过”。

例如：

如果当前环境无法启动页面，应明确写“页面验证未执行”，不能根据代码推断“页面应该正常”。

怎样把模糊标准改成可验收标准

我会用三个动作改写。

动作一：把形容词换成可观察结果

模糊标准 可验收标准
交互友好 提交期间按钮不可重复点击，失败后恢复并保留输入
页面正常 指定路径可完成，控制台无本次新增错误
响应式良好 在约定宽度下无横向遮挡，核心操作可见
异常处理完善 指定失败场景下提示、数据和 Loading 状态符合约定
不影响原功能 列出需要保持的原有路径并逐项回归

动作二：为每条标准指定验证方式

一条标准应该能够归到一种证据：

  • 看页面。

  • 看请求。

  • 看状态。

  • 看代码差异。

  • 跑检查。

  • 跑测试。

如果不知道怎样验证，这条标准通常还不够具体。

动作三：写清通过、失败和未验证

验收结果不只有“通过”和“不通过”。

我会使用三种状态：

  • 通过：已经执行并得到符合标准的证据。

  • 失败：已经执行，结果不符合标准。

  • 未验证：当前没有环境、数据、权限或接口条件。

未验证不等于失败，但必须进入剩余风险。

真正危险的是把未验证写成“理论上没问题”。

一份可以直接复用的前端验收模板

# 前端任务验收标准
​
## 任务目标
​
- 本次要改变的用户行为：
- 必须保持不变的行为：
​
## 1. 行为证据
​
### 正常路径
​
1. 前置状态：
2. 用户动作：
3. 可观察结果：
4. 保持不变：
​
### 异常路径
​
1. 触发条件：
2. 提示方式：
3. 保留的状态：
4. 恢复的状态：
​
### 连续操作
​
1.
2.
3.
​
## 2. 数据证据
​
| 场景 | 页面状态 | 请求参数 | 响应处理 | 页面结果 |
| --- | --- | --- | --- | --- |
|  |  |  |  |  |
​
## 3. 修改范围证据
​
- 修改文件及原因：
- 明确未修改的公共能力：
- 公共 API、类型和默认值是否变化：
- 新增依赖或配置：
- 无关差异清理结果：
​
## 4. 自动检查证据
​
| 检查 | 实际命令或范围 | 结果 | 备注 |
| --- | --- | --- | --- |
| 类型检查 |  |  |  |
| Lint |  |  |  |
| 相关测试 |  |  |  |
| 构建 |  |  |  |
​
## 5. 页面体验证据
​
- 页面访问路径：
- 验证尺寸：
- 功能与状态：
- 视觉与交互：
- 相关原有路径回归：
​
## 验收结论
​
- 已通过：
- 未通过：
- 未验证：
- 剩余风险：

验收标准也要控制成本

不是每个任务都要把五类证据写到同样深。

我会根据风险调整。

任务 验收重点
修改文案 修改范围、页面展示
局部样式 页面视觉、相关尺寸、无关页面影响
列表查询 行为、请求参数、连续状态、页面路径
表单提交 校验、重复提交、失败恢复、数据和焦点
公共组件 调用方、兼容行为、自动检查、代表页面回归
多文件重构 行为基线、差异范围、测试和分步验证

验收不是项目越小越随意，而是证据要与风险相称。

一个三行的公共工具修改，可能比一百行的局部样式风险更高。判断验收深度时，应该看影响范围和失败代价，不看代码行数。

AI 可以执行验收，但不能替人定义“可以接受”

Codex 可以协助：

  • 从需求生成验证路径。

  • 根据代码补测试。

  • 执行项目检查。

  • 审查代码差异。

  • 在可用环境中操作页面并记录结果。

  • 汇总通过、失败和未验证项。

但“什么结果可以接受”仍然要由人决定。

例如请求失败后保留旧表格数据还是清空，两种行为都可能通过技术检查。只有结合业务场景，才能确定哪一种算完成。

所以验收不是把责任交给 AI，而是让人的判断变得明确，让 AI 有条件执行。

完成不是一句结论，而是一组证据

我现在不太在意 Codex 最后说“任务已完成”还是“修改已实现”。

我更在意它能不能回答：

  • 哪些用户路径已经走过。

  • 页面状态和请求数据是否一致。

  • 修改是否控制在任务范围内。

  • 哪些自动检查已经运行。

  • 页面哪些尺寸和异常路径已经验证。

  • 还有什么没有验证。

只要这些证据完整，“完成”自然成立。

如果这些证据缺失，再肯定的完成说明也只是结论。

到这里，Day 5 的两篇形成了完整链条：第一篇找出容易被 AI 忽略的需求边界，这一篇再把边界转成可执行、可观察、可判断的验收标准。

下一篇进入 Day 6：一次性生成和小步修改到底有什么差异。我会继续讨论为什么多文件任务不适合一口气改到底，以及怎样用计划和检查点控制实现过程。

本系列持续更新。后面会把今天的验收模板放进具体的前端任务拆解和多文件修改流程中。

参考资料

posted @ 2026-08-02 20:01  孙梦少爷  阅读(1)  评论(0)    收藏  举报