verification-before-completion Skill 多维度简评

综合评分:9.0 / 10 ⭐⭐⭐⭐⭐ 类别:质量门禁 / 完成验证 仓库:obra/superpowers 维护者:Jesse Vincent / Prime Radiant 引用:Superpowers README · CSDN 详解 · 掘金原理解析

一、核心定位与价值

verification-before-completion 是 Superpowers 14 个 Skills 中最容易被忽视、但损失最大的一环。它解决一个普遍问题:AI(包括人)经常”凭感觉”宣称工作完成:

• “应该通过了” → 实际没通过
• “看起来正确” → 实际有 bug
• “大概没问题” → 实际有 regression

核心铁律:“EVIDENCE BEFORE ASSERTIONS”(证据先于断言) 正确模式:[运行命令] → [看到输出] → 才宣称成功 错误模式:"应该通过了"(未验证)

关键洞见:“修复了”和”证明修复了”之间隔着一个证据——verification-before-completion 强制跨过这个距离。

适用场景

• 完成任何代码改动后
• 提交 / 创建 PR 前
• 修复 bug 后
• 实现功能后
• 任何准备说”完成了”的时刻

不适用场景

• 探索性原型
• 闲聊 / 问答
• 文档撰写(用 doc-coauthoring)

二、核心原则:证据先于断言

2.1 错误 vs 正确模式

2.2 5 步验证清单

## Verification Report

### Tests
[Run test command]
[See: 34/34 pass, 87% coverage]
"All tests pass"

### Regression (TDD Red-Green)
Write failing test → Run (pass) → Revert fix → Run (MUST FAIL)
"Test correctly fails without fix"

### Build
[Run build]
[See: exit 0, no errors]
"Build passes"

### Lint
[Run eslint / ruff / golangci-lint]
[See: 0 issues]
"Lint clean"

### Requirements
Re-read plan → Create checklist → Verify each item
"All requirements met"

2.3 Red-Green-Refactor 回归验证

关键技巧——验证测试真的能捕获 bug:

1. 写新测试,验证修复
2. 运行测试 → 通过(因为 fix 已应用)
3. 暂时 revert 修复代码
4. 重新运行测试 → **必须失败**(MUST FAIL)
5. 重新应用修复
6. 测试再次通过

目的:确认测试是”真”的,不是”测试空过”。

三、9 大常见反模式

3.1 伪成功 #1:“应该通过了”

# ❌ WRONG
"我修改了 SQL 查询,加了个 JOIN,应该快了。"
# 用户运行 → 还是慢

# ✅ RIGHT
"我加了 EXPLAIN ANALYZE,跑完从 2000ms 降到 50ms。"

3.2 伪成功 #2:跳过测试

# ❌ WRONG
"我加了 user 字段到 schema,后端读这个字段。"
# 实际:没重启服务,字段没生效

3.3 伪成功 #3:改测试匹配代码

# ❌ WRONG (Move the Goalposts)
def test_user_login():
    response = login("user@test.com", "wrong_password")
    assert response.status_code == 200  # 改成期望的 200,因为密码错也"成功"

铁律:绝不改测试匹配坏代码。

3.4 伪成功 #4:本地好,生产坏

# ❌ WRONG
"本地测了,可以。"
# 实际:生产用了不同的 DATABASE_URL,连接失败

要求:在类生产环境验证。

3.5 伪成功 #5:忽视 stderr

# ❌ WRONG
$ ./build.sh
# exit 0,但输出里有 WARNING: deprecated API
# 工程师说"成功了"

3.6 伪成功 #6:跑一半的测试

# ❌ WRONG
pytest tests/test_user.py
# 只跑了 1 个文件,跳过 50 个
# 工程师说"测试都通过"

3.7 伪成功 #7:部分 PR 通过

# ❌ WRONG
"PR 合并了,3 个 review comment 已处理。"
# 实际:只解决了 1 个,其他没动

3.8 伪成功 #8:口头 commit

# ❌ WRONG
"代码改完了,一会儿 commit。"
# 实际:忘了 commit,丢失改动

3.9 伪成功 #9:截图作为验证

# ❌ WRONG
"我截图了,UI 看起来对。"
# 实际:截图只显示 hero section,没显示报错的下半屏

四、4 大验证门禁

4.1 测试门禁

# Python
pytest --tb=short --cov=src tests/
# 必须看到: passed=N failed=0

# JavaScript
npm test
pnpm test
# 必须看到: Tests: X passed, Y total

4.2 构建门禁

# TypeScript
pnpm build
# 必须看到: ✓ Compiled successfully

# Go
go build ./...
# 必须看到: (无输出 = 成功)

# Rust
cargo build --release
# 必须看到: Finished `release` profile

4.3 Lint 门禁

# ESLint
pnpm lint
# 必须看到: 0 errors, 0 warnings

# Ruff
ruff check .
# 必须看到: All checks passed!

# golangci-lint
golangci-lint run
# 必须看到: 0 issues

4.4 需求门禁

## 计划 → 实施 → 验证

## 计划阶段
- [ ] 需求 1
- [ ] 需求 2
- [ ] 需求 3

## 验证阶段(实施后)
- [ ] 跑完代码 → 需求 1 实现 ✓
- [ ] 跑完代码 → 需求 2 实现 ✓
- [ ] 跑完代码 → 需求 3 实现 ✓

五、与其他 Skill 配合

完整工作流:

[1] 实现代码
  ↓
[2] self-verification (本 Skill)
  ↓ 测试通过?Linter 干净?构建成功?需求覆盖?
[3] requesting-code-review (重要功能)
  ↓
[4] finishing-a-development-branch
  ↓
[5] 合并 / PR

六、5 条反合理化

七、5 条实战技巧

1. 永远复制粘贴真实输出:[See: 34/34 passed] 而不是 “应该”
2. CI 是终极 verification:本地过不代表 CI 过
3. Red-Green-Refactor 三步验证测试——关键反模式检测
4. 回归测试:fix 后跑全量,看是否破坏其他功能
5. 配置 .git/hooks/pre-push 自动跑测试再 push

八、Q&A

Q: 跟”测试覆盖率高”区别? A: verification 是”运行测试并看真实输出”,覆盖率是”测试覆盖的代码比例”。

Q: 必须订阅 Claude Code 吗? A: 工具本身不需要。Skill 是给 Claude 的指令。

Q: 跟 CI 关系? A: CI 是 verification 的自动化形式。本 Skill 是 Claude 自己执行 verification。

Q: 适用所有语言吗? A: 适用。命令不同,原则一致。

Q: 跟 systematic-debugging 区别? A: debugging 是”找根因 + 修”,verification 是”修后证明修了”。

Q: 中文支持? A: 完全支持。

Q: 学习曲线? A: 1 天理解,1 周变习惯,1 月成本能。

九、Prompt 模板

模板 1:完成功能

用 verification-before-completion 验证这个功能:
1. 运行测试套件(看到全过)
2. 运行 linter(看到 0 issue)
3. 运行 build(看到 exit 0)
4. 对照需求清单逐项 check
5. 输出 verification 报告

模板 2:修复 bug

用 verification-before-completion 验证 bug 修复:
1. 先重现 bug(确认能触发)
2. 应用修复
3. 重现步骤不再触发
4. 跑全量回归测试(确认没破坏其他)
5. 跑 linter + build
6. 写回归测试用例,确保未来不再发生

模板 3:创建 PR

用 verification-before-completion 验证 PR:
1. 跑所有测试
2. 跑 build
3. 跑 linter
4. 检查 diff 是否只包含相关改动
5. 检查是否有 console.log / debug 代码
6. 检查 commit message 规范

十、真实踩坑案例

案例 1:“我修好了”实际没修

场景:用户报”支付失败”,工程师改了 1 小时。 错误:“应该修好了。” 实际:用户复现,依然失败。 根因:工程师没复现原 bug,直接改了不同地方。 正确做法:先 reproduce → fix → verify fix → regression test。

案例 2:测试改了但代码没改

场景:CI 红了,工程师把测试断言改了让测试通过。 错误:“测试改完了,绿了。” 实际:bug 还在。 根因:Move the Goalposts 反模式。 正确做法:绝不改测试匹配坏代码,改代码让测试通过。

案例 3:本地过 CI 红

场景:本地 npm test 全过,推上去 CI 红了。 根因:本地用 Node 20,CI 用 Node 18。 正确做法:用 .nvmrc 固定版本,或 Docker 跑测试。

案例 4:覆盖率 80% 但漏关键路径

场景:覆盖率报告显示 85%。 实际:登录成功路径覆盖,但登录失败路径没测试。 根因:只测 happy path。 正确做法:boundary testing + mutation testing。

案例 5:性能”优化”实际更慢

场景:加了缓存”应该快了”。 实际:加了缓存层多一跳 RT 更高。 正确做法:先 benchmark → 改 → benchmark 对比。

案例 6:看日志没看 metrics

场景:部署后”看日志没报错”。 实际:慢查询 + 5xx 告警,日志里没有。 正确做法:同时看日志 + metrics + traces(可观测性三支柱)。

案例 7:截图作为”通过”证据

场景:前端 PR,作者截图”页面显示正常”。 实际:在某个屏幕尺寸下错位,截图用了完美分辨率。 正确做法:多设备 + 响应式测试 + Playwright 截图对比。

案例 8:本地是 SQLite,生产是 Postgres

场景:“本地跑过,没问题。” 实际:SQLite 兼容,Postgres 不兼容。 正确做法:用 Docker Compose 起生产相同数据库,或 e2e 环境。

案例 9:tag 推了,image 没 build

场景:打了 v1.0.0 tag,推了。 实际:CD pipeline 失败,image 没生成。 根因:tag 和 build 步骤分两个 workflow。 正确做法:git tag 后必须看 pipeline 成功。

案例 10:“我跑了”实际只跑了一个文件

场景:“测试通过了” 实际只跑了 test_user.py。 正确做法:看完整测试输出,跑全量 pytest / npm test。

十一、与其他工具对比

verification-before-completion 是这些工具背后的思维方法**——任何工具都替代不了”我要看到证据”的心态。**

十二、安装

# Claude Code
/plugin marketplace add obra/superpowers
/plugin install superpowers@claude-plugins-official

# 通用
npx skills add obra/superpowers --skill verification-before-completion

# Codex / Cursor / Copilot CLI 也支持
# 详见:https://github.com/obra/superpowers/blob/main/docs/environments.md

十三、真实战绩

来源:obra/superpowers 社区统计

十四、总结

核心价值:

• 强制”证据先于断言”
• 5 步验证清单
• Red-Green-Refactor 回归验证
• 反”伪成功”反模式

适用人群:

• 所有写代码的工程师
• Tech Lead(团队纪律)
• QA 工程师
• 任何准备说”完成”的人

投入产出比:⭐⭐⭐⭐⭐(5/5)—— 必装。

何时不要用:

• 纯聊天
• 探索性实验
• 一次性脚本(没验证也行)

参考链接:

• Superpowers 官方仓库
• Superpowers README
• CSDN: Superpowers Skills 完整探索
• 掘金: Superpowers 原理解析
• chongwenz.cn 常用命令与场景
• 配套:test-driven-development | systematic-debugging | using-superpowers