Superpowers 教程 9：verification-before-completion（验证与分支收尾）

教程概述

系列目录：Superpowers 教程系列索引

本教程涵盖 Superpowers 的两个"收尾"技能：verification-before-completion 确保工作真正完成，finishing-a-development-branch 指导如何整合开发成果。

你将学到

✅ verification-before-completion 的验证策略
✅ 用证据而非断言证明成功
✅ finishing-a-development-branch 的决策流程
✅ 合并/PR/清理的选择标准
✅ 完整开发周期闭环

verification-before-completion 技能

为什么需要验证？

断言式完成的问题

flowchart LR
    A[完成工作] --> B["声称完成了"]
    B --> C["真的吗？"]
    C --> D[没有证据]
    D --> E[信任问题]
    E --> F[需要重新检查]
    
    style B fill:#ffcccc
    style D fill:#ffcccc
    style E fill:#ffcccc

证据式完成的优势

flowchart LR
    A[完成工作] --> B[运行验证命令]
    B --> C[收集输出证据]
    C --> D[展示证据]
    D --> E[信任建立]
    E --> F[顺利合并]
    
    style B fill:#e8f5e9
    style C fill:#e8f5e9
    style D fill:#e8f5e9

触发时机

verification-before-completion 在以下场景自动触发：

声称任务完成前 - 准备报告完成时
提交代码前 - 准备 commit/push 前
创建 PR 前 - 准备请求合并前
修复 Bug 后 - 准备关闭 issue 前

核心原则

verification:
  principles:
    - "证据优于断言"
    - "可重复验证"
    - "自动化优先"
    - "完整覆盖验收标准"
  
  anti_patterns:
    - "我相信应该没问题"
    - "我手动测试过了"
    - "看起来是对的"
    - "应该没问题吧"

验证策略

策略 1: 测试验证

# ❌ 断言
"测试都通过了"

# ✅ 证据
$ pytest tests/ -v --tb=short
===================== test session starts =====================
collected 47 items

tests/test_tag_model.py::test_tag_creation PASSED
tests/test_tag_model.py::test_slug_generation PASSED
tests/test_tag_api.py::test_get_tags_list PASSED
...
===================== 47 passed in 12.34s =====================

测试通过率：100% (47/47)

策略 2: 功能验证

# ❌ 断言
"功能正常工作"

# ✅ 证据
$ curl -X GET http://localhost:8000/api/tags | jq
[
  {
    "id": 1,
    "name": "Python",
    "slug": "python",
    "created_at": "2026-02-28T10:00:00Z"
  },
  {
    "id": 2,
    "name": "AI",
    "slug": "ai",
    "created_at": "2026-02-28T10:05:00Z"
  }
]

API 响应正常，返回 2 个标签

策略 3: 质量验证

# ❌ 断言
"代码质量良好"

# ✅ 证据
$ npm run lint

> lint
> eslint src/ --max-warnings=0

✖ 0 problems (0 errors, 0 warnings)

$ npm run typecheck

> typecheck
> tsc --noEmit

No type errors found.

Lint: ✅ 0 问题
TypeScript: ✅ 无错误

策略 4: 性能验证

# ❌ 断言
"性能很好"

# ✅ 证据
$ ab -n 1000 -c 10 http://localhost:8000/api/tags/

Benchmarking localhost (be patient).....done
Server Software:        uvicorn
Server Hostname:        localhost
Server Port:            8000

Document Path:          /api/tags/
Document Length:        1024 bytes

Concurrency Level:      10
Time taken for tests:   1.234 seconds
Complete requests:      1000
Failed requests:        0
Requests per second:    810.37 [#/sec] (mean)
Time per request:       12.340 [ms] (mean)
Time per request:       1.234 [ms] (mean, across all concurrent requests)

性能指标:
- RPS: 810.37
- 平均延迟：12.34ms
- 失败请求：0

验证清单

## 完成前验证清单

**任务**: 标签系统实现

### 功能验证
- [ ] 所有单元测试通过
  ```bash
  $ pytest tests/unit/ -v
  45 passed

所有集成测试通过

$ pytest tests/integration/ -v
12 passed

API 端点手动测试

$ curl http://localhost:8000/api/tags
[{"id":1,"name":"Python"}]

代码质量

Lint 检查通过
```
$ npm run lint
0 problems
```
类型检查通过
```
$ tsc --noEmit
No errors
```

代码格式化

$ prettier --check src/
All files formatted correctly

性能验证

响应时间 < 100ms

$ ab -n 100 http://localhost:8000/api/tags
Time per request: 23.45ms

无内存泄漏

$ memory_profiler
Memory usage stable at 128MB

安全验证

无 SQL 注入风险

$ sqlmap --test
No vulnerabilities found

输入验证完整

$ pytest tests/security/
All security tests passed

文档验证

README 已更新
API 文档已生成
变更日志已更新

验证结论: ✅ 所有检查通过，可以提交


### 验证失败处理

```markdown
## 验证失败示例

**验证项目**: 性能测试

**期望**: 响应时间 < 100ms

**实际**:
```bash
$ ab -n 1000 http://localhost:8000/api/tags
Time per request: 234ms

分析:

性能不达标 (234ms > 100ms)
原因：数据库查询未使用索引

修复计划:

添加 tags 表索引
优化 N+1 查询
重新验证

状态: ⏸️ 阻塞，修复后重新验证


## finishing-a-development-branch 技能

### 触发时机

finishing-a-development-branch 在以下场景**自动触发**：

1. **所有任务完成** - 实现计划全部完成
2. **准备整合** - 需要合并到主分支
3. **worktree 清理** - 需要决定如何处理 worktree

### 决策流程

```mermaid
flowchart TD
    A[所有任务完成] --> B[finishing-a-development-branch]
    B --> C{验证通过？}
    C -->|否 | D[修复问题]
    D --> C
    C -->|是 | E{如何整合？}
    
    E -->|直接合并 | F[merge to main]
    E -->|需要审查 | G[创建 PR]
    E -->|实验功能 | H[保留分支]
    E -->|废弃功能 | I[清理删除]
    
    F --> J[清理 worktree]
    G --> J
    H --> K[保留 worktree]
    I --> L[删除 worktree]
    
    style B fill:#e1f5ff
    style F fill:#e8f5e9
    style G fill:#e8f5e9
    style J fill:#fff3e0
    style L fill:#ffebee

整合选项详解

选项 1: 直接合并到 main

适用场景:

个人项目
已充分审查
紧急修复
团队信任度高

操作流程:

# 1. 确保在最新的主分支
git checkout main
git pull origin main

# 2. 合并功能分支
git merge feature/tag-system --no-ff

# 3. 编写有意义的合并信息
git merge feature/tag-system --no-ff -m "
feat: 实现标签系统

功能:
- 标签 CRUD 操作
- 文章 - 标签关联
- 标签过滤查询

技术:
- 使用多对多关系
- 添加完整测试覆盖
- 符合 REST API 规范

Closes: #123
"

# 4. 推送
git push origin main

# 5. 清理 worktree
git worktree remove ../theme-stack-blog-feature-tag
git branch -d feature/tag-system

选项 2: 创建 Pull Request

适用场景:

团队项目
需要正式审查
重要功能
需要 CI/CD 验证

操作流程:

# 1. 推送到远程
git push origin feature/tag-system

# 2. 创建 PR (GitHub CLI)
gh pr create \
  --title "feat: 实现标签系统" \
  --body "
## 概述
实现完整的标签系统，支持文章的标签分类和过滤。

## 变更
- 新增 Tag 模型和迁移
- 实现标签 API 端点
- 添加前端标签组件
- 完整测试覆盖

## 测试
- [x] 单元测试 (57 个)
- [x] 集成测试 (12 个)
- [x] 手动测试通过

## 截图
![标签列表](screenshot1.png)
![标签选择器](screenshot2.png)

## 相关 Issue
Fixes #123
" \
  --label "feature" \
  --reviewer teammate1,teammate2

# 3. 等待审查和 CI

# 4. 合并后清理
git branch -d feature/tag-system
git worktree remove ../theme-stack-blog-feature-tag

选项 3: 保留分支继续测试

适用场景:

实验性功能
需要更多验证
依赖其他未完成功能
长期特性分支

操作流程:

# 保持现状，继续开发

# 定期同步主分支
git checkout main
git pull origin main
git checkout feature/tag-system
git rebase main

# 在 worktree 中继续测试
cd ../theme-stack-blog-feature-tag
# 继续开发和测试

选项 4: 清理删除

适用场景:

功能被否决
技术方案不可行
需求变更
实验失败

操作流程:

# 1. 记录经验教训（重要！）
cat >> .project/learnings.md << EOF

## 标签系统尝试 - 已废弃

日期：2026-02-28
原因：
- 性能无法达标（查询太慢）
- 团队决定使用第三方服务

经验:
- 早期进行性能验证
- 考虑现成解决方案

相关代码位置:
- Git 分支：feature/tag-system (已删除)
- 设计文档：.project/designs/tag-system.md
EOF

# 2. 删除分支
git branch -D feature/tag-system

# 3. 清理 worktree
git worktree remove ../theme-stack-blog-feature-tag

# 4. 清理远程分支（如果已推送）
git push origin --delete feature/tag-system

清理检查清单

## 分支清理清单

### 合并前检查
- [ ] 所有测试通过
- [ ] 代码审查通过
- [ ] 无合并冲突
- [ ] 文档已更新

### 合并操作
- [ ] 选择正确的合并策略
- [ ] 编写清晰的合并信息
- [ ] 关联相关 Issue

### 合并后清理
- [ ] 删除本地分支
- [ ] 删除远程分支
- [ ] 清理 worktree
- [ ] 更新项目状态

### 后续行动
- [ ] 部署到测试环境
- [ ] 通知相关人员
- [ ] 监控关键指标
- [ ] 准备回滚方案

完整开发周期示例

从开始到结束的完整流程

flowchart TD
    Start[需求提出] --> B1[brainstorming]
    B1 --> B2[设计文档]
    B2 --> B3[writing-plans]
    B3 --> B4[实现计划]
    B4 --> B5[using-git-worktrees]
    B5 --> B6[创建 worktree]
    B6 --> B7[subagent-driven-development]
    
    B7 --> T1[任务 1 完成]
    B7 --> T2[任务 2 完成]
    B7 --> T3[任务 N 完成]
    
    T1 --> R1[requesting-code-review]
    T2 --> R2[requesting-code-review]
    T3 --> R3[requesting-code-review]
    
    R1 --> V1[verification]
    R2 --> V2[verification]
    R3 --> V3[verification]
    
    V1 --> F[finishing-a-branch]
    V2 --> F
    V3 --> F
    
    F --> Merge{合并决策}
    Merge -->|PR| PR[创建 PR]
    Merge -->|直接 | Direct[直接合并]
    
    PR --> Clean[清理]
    Direct --> Clean
    
    Clean --> End[完成]
    
    style B1 fill:#e1f5ff
    style B3 fill:#e1f5ff
    style B5 fill:#e8f5e9
    style B7 fill:#fff3e0
    style F fill:#f3e5f5

时间线示例

Day 1 - 设计与规划
09:00 - brainstorming 启动
10:30 - 设计文档完成
11:00 - writing-plans 启动
12:00 - 实现计划完成

Day 1-2 - 开发
13:00 - using-git-worktrees 创建环境
13:30 - subagent-driven-development 启动
14:00 - 任务 1-3 完成 + 审查
16:00 - 任务 4-6 完成 + 审查
Day 2 10:00 - 所有任务完成

Day 2 - 验证与整合
10:30 - verification-before-completion
11:00 - 修复验证发现的问题
12:00 - 重新验证通过
14:00 - finishing-a-development-branch
14:30 - 创建 PR
15:00 - 代码审查
16:00 - 审查意见修复
17:00 - PR 合并
17:30 - 清理 worktree

总耗时：约 1.5 天

最佳实践

1. 验证自动化

# .github/workflows/verification.yml
name: Verification

on: [push, pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Run tests
        run: pytest tests/ -v
      
      - name: Run lint
        run: npm run lint
      
      - name: Type check
        run: tsc --noEmit
      
      - name: Performance test
        run: pytest tests/performance/ -v
      
      - name: Security scan
        run: bandit -r src/

2. 验证报告模板

## 验证报告

**功能**: 标签系统
**日期**: 2026-02-28
**验证者**: AI Assistant

### 测试摘要

Tests: 57 passed, 0 failed Coverage: 92.3% Build: ✅ Success


### 关键指标
| 指标 | 期望 | 实际 | 状态 |
|-----|------|------|------|
| 响应时间 | <100ms | 23ms | ✅ |
| 错误率 | <0.1% | 0% | ✅ |
| 覆盖率 | >85% | 92.3% | ✅ |

### 手动验证
- [x] 标签创建功能
- [x] 标签列表显示
- [x] 标签过滤查询
- [x] 错误处理

**结论**: ✅ 验证通过，可以合并

3. 合并策略选择

# 根据项目类型选择
merge_strategy:
  # 个人项目 - 直接合并
  personal:
    strategy: merge
    require_review: false
  
  # 小团队 - 简化 PR
  small_team:
    strategy: pr
    require_review: true
    reviewers: 1
  
  # 大团队 - 正式 PR
  enterprise:
    strategy: pr
    require_review: true
    reviewers: 2
    require_ci: true
    require_security_scan: true

小结

这两个技能确保开发工作有始有终：

verification-before-completion - 用证据说话
finishing-a-development-branch - 正确的整合决策

关键要点

✅ 验证优于断言
✅ 自动化验证优先
✅ 根据场景选择整合策略
✅ 清理是必要步骤

验证清单速查

□ 测试通过（有输出证据）
□ Lint 通过（有输出证据）
□ 类型检查通过（有输出证据）
□ 性能达标（有基准测试）
□ 安全检查通过（有扫描报告）
□ 文档已更新（有 diff）

系列导航：

← 上一篇：教程 8：subagent-driven-development 与并行任务
→ 下一篇：教程 10：writing-skills - 创建你自己的技能
返回：教程系列索引

Superpowers 教程 9：verification-before-completion（验证与分支收尾）

verification-before-completion 让“我做完了”变成可复现的证据链：测试、日志、对比、验收标准；finishing-a-development-branch 则把分支收尾（合并/PR/清理/发布）标准化。本文给出一套可复用的验证清单与收尾流程。

教程概述

你将学到

verification-before-completion 技能

为什么需要验证？

断言式完成的问题

证据式完成的优势

触发时机

核心原则

验证策略

策略 1: 测试验证

策略 2: 功能验证

策略 3: 质量验证

策略 4: 性能验证

验证清单

代码质量

性能验证

安全验证

文档验证

整合选项详解

选项 1: 直接合并到 main

选项 2: 创建 Pull Request

选项 3: 保留分支继续测试

选项 4: 清理删除

清理检查清单

完整开发周期示例

从开始到结束的完整流程

时间线示例

最佳实践

1. 验证自动化

2. 验证报告模板

3. 合并策略选择

小结

关键要点

验证清单速查

参考资源

教程概述

你将学到

verification-before-completion 技能

为什么需要验证？

断言式完成的问题

证据式完成的优势

触发时机

核心原则

验证策略

策略 1: 测试验证

策略 2: 功能验证

策略 3: 质量验证

策略 4: 性能验证

验证清单

代码质量

性能验证

安全验证

文档验证

整合选项详解

选项 1: 直接合并到 main

选项 2: 创建 Pull Request

选项 3: 保留分支继续测试

选项 4: 清理删除

清理检查清单

完整开发周期示例

从开始到结束的完整流程

时间线示例

最佳实践

1. 验证自动化

2. 验证报告模板

3. 合并策略选择

小结

关键要点

验证清单速查

参考资源

🍪 Cookie 使用通知

Cookie 偏好设置

必要 Cookie

分析 Cookie

广告 Cookie