qa-workflow

QA 工作流技能

概述

全面的质量保证工作流，用于验证实现的完整性和正确性，并持续进行修复，直至获得批准。你是发布前的最后一道防线。

核心原则： 你是最后一道防线。如果你批准，功能就会发布。务必全面检查。

适用场景

始终适用：

• 实现标记为完成后
• 合并或部署更改前
• 验证验收标准时

例外情况：

• 仅涉及文档的更改（可进行最低限度的验证）
• 带有 skip_validation 标志的简单修复

铁律

1. 绝不在未验证每项验收标准的情况下批准——你是最后一道防线；部分验证等同于没有验证。
2. 务必使用准确的文件路径和行号记录问题——“测试失败”这类含糊报告无法用于修复，只会浪费修复循环。
3. 绝不为测试未通过的实现签字认可——所有测试类别（单元测试、集成测试、E2E）都必须通过后才能批准，没有例外。
4. 务必运行完整测试套件进行回归检查——无论新测试结果如何，只要功能破坏了现有功能，就还没有达到可用于生产环境的标准。
5. 修复循环迭代次数绝不超过 5 次，超过时应升级至人工审核——反复循环意味着存在自动修复无法解决的根本原因。

反模式

反模式	失败原因	正确做法
在检查所有验收标准之前就批准	将伪装成新功能的缺陷发布出去；破坏质量承诺	在撰写结论前，验证规格中的每项标准
撰写含糊的问题报告（“测试失败”“有问题”）	开发者无法复现或修复描述不准确的问题	提供文件路径、行号、准确的错误消息和复现步骤
明知测试未通过仍签字认可	未通过的测试意味着已记录在案的缺陷正被发布到生产环境	所有测试都必须通过；如果测试有误，应先修复并记录更改
只运行新测试，不运行完整回归测试套件	不运行完整套件就无法发现新代码对旧功能造成的破坏	始终使用 --coverage 运行完整测试套件；回归问题会阻止批准
为了“顺手清理”而修复 QA 未发现的问题	过度修复会引入新缺陷，并导致修复循环范围蔓延	只做最小更改；仅修复 QA 指出的问题，不做其他修改

批准前必须验证每项验收标准。

第 1 部分：QA 审核

阶段 0：加载上下文

# Read the spec (your source of truth for requirements)
cat .claude/context/specs/[task-name]-spec.md

# Read any previous QA reports
cat .claude/context/reports/qa/qa-report.md 2>/dev/null || echo "No previous report"

# See what files were changed
git diff main...HEAD --name-status

# Read QA acceptance criteria from spec
grep -A 100 "## QA Acceptance" spec.md

阶段 1：确认所有工作均已完成

# Check git log for implementation commits
git log --oneline main..HEAD

# Verify expected files were modified
git diff main...HEAD --name-only

如果实现尚未完成，请停止。 QA 应在实现完成后进行。

阶段 2：启动测试环境

# Start services as needed
npm run dev  # or appropriate command

# Verify services are running
curl http://localhost:3000/health 2>/dev/null || echo "Service not responding"

等待所有服务运行正常后再继续。

阶段 3：运行自动化测试

单元测试

针对受影响的区域运行所有单元测试：

# Run test suite
npm test
# or
pytest
# or
go test ./...

记录结果：

UNIT TESTS:
- [area-name]: PASS/FAIL (X/Y tests)

集成测试

如适用，运行集成测试：

# Run integration test suite
npm run test:integration

记录结果：

INTEGRATION TESTS:
- [test-name]: PASS/FAIL

端到端测试

如果存在 E2E 测试：

# Run E2E test suite
npm run test:e2e

记录结果：

E2E TESTS:
- [flow-name]: PASS/FAIL

阶段 4：手动验证

针对规格中的每项验收标准：

1. 导航至相关区域
2. 验证是否满足标准
3. 检查控制台是否有错误
4. 测试边缘情况
5. 记录发现

MANUAL VERIFICATION:
- [Criterion 1]: PASS/FAIL
  - Evidence: [what you observed]
- [Criterion 2]: PASS/FAIL
  - Evidence: [what you observed]

阶段 5：代码审查

安全审查

检查常见漏洞：

# Look for security issues
grep -r "eval(" --include="*.js" --include="*.ts" . 2>/dev/null
grep -r "innerHTML" --include="*.js" --include="*.ts" . 2>/dev/null
grep -r "dangerouslySetInnerHTML" --include="*.tsx" --include="*.jsx" . 2>/dev/null

# Check for hardcoded secrets
grep -rE "(password|secret|api_key|token)\s*=\s*['\"][^'\"]+['\"]" . 2>/dev/null

模式合规性

验证代码是否遵循既定模式：

# Compare new code to existing patterns
# Read pattern files, compare structure

记录发现：

CODE REVIEW:
- Security issues: [list or "None"]
- Pattern violations: [list or "None"]
- Code quality: PASS/FAIL

阶段 6：回归检查

运行完整测试套件，检查是否存在回归：

# Run ALL tests, not just new ones
npm test -- --coverage

确认现有的关键功能仍可正常使用。

REGRESSION CHECK:
- Full test suite: PASS/FAIL (X/Y tests)
- Existing features verified: [list]
- Regressions found: [list or "None"]

阶段 7：生成 QA 报告

# QA Validation Report

**Task**: [task-name]
**Date**: [timestamp]

## Summary

| Category            | Status    | Details     |
| ------------------- | --------- | ----------- |
| Unit Tests          | PASS/FAIL | X/Y passing |
| Integration Tests   | PASS/FAIL | X/Y passing |
| E2E Tests           | PASS/FAIL | X/Y passing |
| Manual Verification | PASS/FAIL | [summary]   |
| Security Review     | PASS/FAIL | [summary]   |
| Pattern Compliance  | PASS/FAIL | [summary]   |
| Regression Check    | PASS/FAIL | [summary]   |

## Issues Found

### Critical (Blocks Sign-off)

1. [Issue description] - [File/Location]

### Major (Should Fix)

1. [Issue description] - [File/Location]

### Minor (Nice to Fix)

1. [Issue description] - [File/Location]

## Verdict

**SIGN-OFF**: [APPROVED / REJECTED]

**Reason**: [Explanation]

**Next Steps**:

- [If approved: Ready for merge]
- [If rejected: List of fixes needed]

将报告保存到 .claude/context/reports/qa/qa-report.md

阶段 8：决策

如果已批准

=== QA VALIDATION COMPLETE ===

Status: APPROVED

All acceptance criteria verified:
- Unit tests: PASS
- Integration tests: PASS
- Manual verification: PASS
- Security review: PASS
- Regression check: PASS

The implementation is production-ready.
Ready for merge.

如果已拒绝

创建修复请求并继续执行第 2 部分。

---

第 2 部分：QA 修复循环

阶段 0：加载修复请求

# Read the QA report with issues
cat .claude/context/reports/qa/qa-report.md

# Identify issues to fix
grep -A 50 "## Issues Found" .claude/context/reports/qa/qa-report.md

从报告中提取：

• 需要修复的确切问题
• 文件位置
• 所需修复
• 验证标准

阶段 1：解析修复要求

根据 QA 报告创建检查清单：

FIXES REQUIRED:
1. [Issue Title]
   - Location: [file:line]
   - Problem: [description]
   - Fix: [what to do]
   - Verify: [how to check]

2. [Issue Title]
   ...

必须处理每一个问题。

阶段 2：逐一修复问题

对于每个问题：

1. 阅读问题所在区域
2. 了解问题所在
3. 实施修复
4. 在本地验证修复

遵循以下规则：

• 只做必要的最小改动
• 不要重构周边代码
• 不要添加功能
• 遵循现有模式
• 每次修复后都进行测试

阶段 3：运行测试

应用所有修复后：

# Run the full test suite
npm test

# Run specific tests that were failing
[failed test commands from QA report]

继续之前，所有测试都必须通过。

阶段 4：自我验证

请求重新审核之前，逐一验证每项修复：

SELF-VERIFICATION:
[ ] Issue 1: [title] - FIXED
    - Verified by: [how you verified]
[ ] Issue 2: [title] - FIXED
    - Verified by: [how you verified]
...

ALL ISSUES ADDRESSED: YES/NO

如果有任何问题尚未修复，请返回阶段 2。

阶段 5：提交修复

# Add fixed files
git add [fixed-files]

# Commit with descriptive message
git commit -m "fix: Address QA issues

Fixes:
- [Issue 1 title]
- [Issue 2 title]

Verified:
- All tests pass
- Issues verified locally"

阶段 6：发起重新审核

=== QA FIXES COMPLETE ===

Issues fixed: [N]

1. [Issue 1] - FIXED
   Commit: [hash]

2. [Issue 2] - FIXED
   Commit: [hash]

All tests passing.
Ready for QA re-validation.

---

QA 循环行为

QA → 修复 → QA 循环持续进行，直到满足以下条件：

1. 所有严重问题均已解决
2. 所有测试均已通过
3. 没有回归问题
4. QA 已批准

最多迭代次数：5

如果达到最大迭代次数但仍未获批准：

• 升级为人工审核
• 记录所有剩余问题
• 保存详细报告

严重程度指南

严重——阻止签核：

• 测试失败
• 安全漏洞
• 缺少必需功能
• 存在数据损坏风险

主要——应该修复：

• 缺少边界情况处理
• 性能问题
• 用户体验问题
• 违反模式规范

次要——最好修复：

• 风格不一致
• 文档缺失
• 轻微优化

验证检查清单

批准之前：

• 所有单元测试均通过
• 所有集成测试均通过
• 所有端到端测试均通过（如适用）
• 已手动验证验收标准
• 已完成安全审核
• 已验证符合模式规范
• 未发现回归问题
• 已生成 QA 报告

常见错误

过快批准

**问题所在：**将缺陷带给用户。

**正确做法：**检查验收标准中的所有内容。

问题报告含糊

**问题所在：**开发者无法修复不理解的问题。

**正确做法：**提供准确的文件路径、行号和可复现步骤。

修复范围过大

**问题所在：**修复旧问题时引入新缺陷。

**正确做法：**尽量减少改动，只修复 QA 发现的问题。

与其他技能的集成

此技能与以下技能配合良好：

• complexity-assessment：确定验证深度
• tdd：使用 TDD 为修复编写测试
• debugging：调查测试失败时使用

记忆协议

开始之前： 阅读 .claude/context/memory/learnings.md

完成之后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现问题 -> .claude/context/memory/issues.md
• 做出决策 -> .claude/context/memory/decisions.md

假设工作可能中断：如果没有记录在记忆中，就等于没有发生。