Back to Details

qa-workflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

QA Workflow Skill

QA工作流技能

Overview

概述

Comprehensive quality assurance workflow that validates implementation completeness and correctness, then iterates through fix cycles until approval. You are the last line of defense before shipping.
Core principle: You are the last line of defense. If you approve, the feature ships. Be thorough.
这是一套全面的质量保障工作流，用于验证实现的完整性和正确性，随后迭代执行修复循环直到通过审批。你是发布前的最后一道防线。
核心原则： 你是最后一道防线，只要你审批通过，功能就会发布。请务必做到全面详尽。

When to Use

适用场景

Always:
  • After implementation is marked complete
  • Before merging or deploying changes
  • When validating acceptance criteria
Exceptions:
  • Documentation-only changes (may use minimal validation)
  • Trivial fixes with skip_validation flag
必须使用：
  • 实现被标记为完成后
  • 合并或部署变更前
  • 验证验收标准时
例外情况：
  • 仅涉及文档的变更（可采用极简验证）
  • 带有skip_validation标记的 trivial 修复

Iron Laws

铁律

  1. NEVER approve without verifying every acceptance criterion — you are the last line of defense; partial verification equals no verification.
  2. ALWAYS document issues with exact file paths and line numbers — vague reports like "the tests fail" are unfixable and waste the fix loop cycle.
  3. NEVER sign off on implementation with failing tests — all test categories (unit, integration, E2E) must pass before approval, no exceptions.
  4. ALWAYS run the full test suite for regression check — a feature that breaks existing functionality is not production-ready regardless of new test results.
  5. NEVER exceed 5 fix loop iterations without escalating to human review — repeated loops signal a root cause that automated fixes cannot resolve.
  1. 绝对不要在未验证每一项验收标准的情况下审批——你是最后一道防线，部分验证等于没有验证。
  2. 必须记录问题的精确文件路径和行号——类似“测试失败”这种模糊的报告无法修复，会浪费修复循环的时间。
  3. 绝对不要在测试未通过的情况下签字确认——所有测试类型（单元、集成、E2E）必须全部通过才能审批，没有例外。
  4. 必须运行完整测试套件做回归检查——无论新功能测试结果如何，破坏现有功能的实现都不符合生产发布要求。
  5. 绝对不要在没有升级到人工审核的情况下执行超过5次修复循环——重复循环说明存在自动化修复无法解决的根本问题。

Anti-Patterns

反模式

Anti-PatternWhy It FailsCorrect Approach
Approving before checking all acceptance criteriaShips bugs disguised as features; breaks the quality contractVerify every criterion in the spec before writing the verdict
Writing vague issue reports ("tests fail", "broken")Developer cannot reproduce or fix what is not precisely describedInclude file path, line number, exact error message, and reproduction steps
Signing off with known failing testsFailing tests are documented bugs being shipped to productionAll tests must pass; if tests are wrong, fix them first and document the change
Only running new tests, not the full regression suiteNew code breaking old functionality is invisible without full suiteAlways run full suite with 
--coverage
; regressions block approval
Fixing more than QA found to "clean things up"Over-fixing introduces new bugs and scope creep into the fix loopApply minimal changes; fix only what QA identified, nothing more
Every acceptance criterion must be verified before approval.
反模式失效原因正确做法
未检查所有验收标准就审批把伪装成功能的Bug发布出去，破坏质量承诺在给出结论前验证需求规范中的每一项标准
编写模糊的问题报告（“测试失败”、“功能损坏”）开发者无法复现或修复没有被精确描述的问题包含文件路径、行号、精确错误信息和复现步骤
已知测试未通过仍签字确认未通过的测试就是被记录的Bug，会被发布到生产环境所有测试必须通过；如果测试本身有问题，先修复测试并记录变更
只运行新测试，不运行完整回归套件不运行完整套件就无法发现破坏旧功能的新代码始终使用
--coverage
参数运行完整套件；回归问题会阻断审批
超出QA发现的问题范围做“代码清理”过度修复会引入新Bug，也会导致修复循环出现范围蔓延采用最小变更，仅修复QA识别出的问题，不要多做改动
审批前必须验证每一项验收标准。

Part 1: QA Review

第一部分：QA评审

Phase 0: Load Context

阶段0：加载上下文

bash
undefined
bash
undefined

Read the spec (your source of truth for requirements)

读取需求规范（你的需求唯一真值来源）

cat .claude/context/specs/[task-name]-spec.md
cat .claude/context/specs/[task-name]-spec.md

Read any previous QA reports

读取所有历史QA报告

cat .claude/context/reports/qa/qa-report.md 2>/dev/null || echo "No previous report"
cat .claude/context/reports/qa/qa-report.md 2>/dev/null || echo "无历史报告"

See what files were changed

查看变更的文件列表

git diff main...HEAD --name-status
git diff main...HEAD --name-status

Read QA acceptance criteria from spec

从需求规范中读取QA验收标准

grep -A 100 "## QA Acceptance" spec.md
undefined
grep -A 100 "## QA Acceptance" spec.md
undefined

Phase 1: Verify All Work Completed

阶段1：验证所有工作已完成

bash
undefined
bash
undefined

Check git log for implementation commits

检查git log中的实现提交

git log --oneline main..HEAD
git log --oneline main..HEAD

Verify expected files were modified

验证预期文件已被修改

git diff main...HEAD --name-only

**STOP if implementation is not complete.** QA runs after implementation.
git diff main...HEAD --name-only

**如果实现未完成请停止。** QA流程在实现完成后运行。

Phase 2: Start Test Environment

阶段2：启动测试环境

bash
undefined
bash
undefined

Start services as needed

按需启动服务

npm run dev # or appropriate command
npm run dev # 或对应命令

Verify services are running

验证服务正常运行

curl http://localhost:3000/health 2>/dev/null || echo "Service not responding"

Wait for all services to be healthy before proceeding.
curl http://localhost:3000/health 2>/dev/null || echo "服务无响应"

等待所有服务健康状态正常后再继续。

Phase 3: Run Automated Tests

阶段3：运行自动化测试

Unit Tests

单元测试

Run all unit tests for affected areas:
bash
undefined
运行受影响区域的所有单元测试：
bash
undefined

Run test suite

运行测试套件

npm test
npm test

or

或

pytest
pytest

or

或

go test ./...

**Document results:**
UNIT TESTS:
undefined
go test ./...

**记录结果：**
单元测试:
undefined

Integration Tests

集成测试

Run integration tests if applicable:
bash
undefined
如果有集成测试则运行：
bash
undefined

Run integration test suite

运行集成测试套件

npm run test:integration

**Document results:**
INTEGRATION TESTS:
undefined
npm run test:integration

**记录结果：**
集成测试:
undefined

End-to-End Tests

E2E测试

If E2E tests exist:
bash
undefined
如果存在E2E测试：
bash
undefined

Run E2E test suite

运行E2E测试套件

npm run test:e2e

**Document results:**
E2E TESTS:
undefined
npm run test:e2e

**记录结果：**
E2E测试:
undefined

Phase 4: Manual Verification

阶段4：人工验证

For each acceptance criterion in the spec:
  1. Navigate to the relevant area
  2. Verify the criterion is met
  3. Check for console errors
  4. Test edge cases
  5. Document findings
MANUAL VERIFICATION:
- [Criterion 1]: PASS/FAIL
  - Evidence: [what you observed]
- [Criterion 2]: PASS/FAIL
  - Evidence: [what you observed]
针对需求规范中的每一项验收标准：
  1. 导航到相关功能区域
  2. 验证标准已满足
  3. 检查控制台错误
  4. 测试边界场景
  5. 记录发现的问题
人工验证:
- [标准1]: 通过/失败
  - 证据: [观察到的现象]
- [标准2]: 通过/失败
  - 证据: [观察到的现象]

Phase 5: Code Review

阶段5：代码评审

Security Review

安全评审

Check for common vulnerabilities:
bash
undefined
检查常见漏洞：
bash
undefined

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
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
undefined
grep -rE "(password|secret|api_key|token)\s*=\s*['"][^'"]+['"]" . 2>/dev/null
undefined

Pattern Compliance

规范合规性

Verify code follows established patterns:
bash
undefined
验证代码符合已建立的编码模式：
bash
undefined

Compare new code to existing patterns

对比新代码和现有模式

Read pattern files, compare structure

读取模式文件，对比结构


**Document findings:**
CODE REVIEW:
  • Security issues: [list or "None"]
  • Pattern violations: [list or "None"]
  • Code quality: PASS/FAIL
undefined

**记录发现：**
代码评审:
  • 安全问题: [列表或“无”]
  • 规范违反: [列表或“无”]
  • 代码质量: 通过/失败
undefined

Phase 6: Regression Check

阶段6：回归检查

Run full test suite to catch regressions:
bash
undefined
运行完整测试套件捕捉回归问题：
bash
undefined

Run ALL tests, not just new ones

运行所有测试，而非仅新增测试

npm test -- --coverage

Verify key existing functionality still works.
REGRESSION CHECK:
  • Full test suite: PASS/FAIL (X/Y tests)
  • Existing features verified: [list]
  • Regressions found: [list or "None"]
undefined
npm test -- --coverage

验证核心现有功能仍正常运行。
回归检查:
  • 完整测试套件: 通过/失败 (X/Y 测试用例)
  • 已验证的现有功能: [列表]
  • 发现的回归问题: [列表或“无”]
undefined

Phase 7: Generate QA Report

阶段7：生成QA报告

markdown
undefined
markdown
undefined

QA Validation Report

QA验证报告

Task: [task-name] Date: [timestamp]
任务: [任务名称] 日期: [时间戳]

Summary

概览

CategoryStatusDetails
Unit TestsPASS/FAILX/Y passing
Integration TestsPASS/FAILX/Y passing
E2E TestsPASS/FAILX/Y passing
Manual VerificationPASS/FAIL[summary]
Security ReviewPASS/FAIL[summary]
Pattern CompliancePASS/FAIL[summary]
Regression CheckPASS/FAIL[summary]
分类状态详情
单元测试通过/失败X/Y 已通过
集成测试通过/失败X/Y 已通过
E2E测试通过/失败X/Y 已通过
人工验证通过/失败[摘要]
安全评审通过/失败[摘要]
规范合规性通过/失败[摘要]
回归检查通过/失败[摘要]

Issues Found

发现的问题

Critical (Blocks Sign-off)

严重（阻断审批）

  1. [Issue description] - [File/Location]
  1. [问题描述] - [文件/位置]

Major (Should Fix)

重要（应当修复）

  1. [Issue description] - [File/Location]
  1. [问题描述] - [文件/位置]

Minor (Nice to Fix)

次要（建议修复）

  1. [Issue description] - [File/Location]
  1. [问题描述] - [文件/位置]

Verdict

结论

SIGN-OFF: [APPROVED / REJECTED]
Reason: [Explanation]
Next Steps:
  • [If approved: Ready for merge]
  • [If rejected: List of fixes needed]

Save report to `.claude/context/reports/qa/qa-report.md`
审批结果: [通过 / 驳回]
原因: [说明]
下一步:
  • [如果通过: 可合并]
  • [如果驳回: 所需修复列表]

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

Phase 8: Decision

阶段8：决策

If APPROVED

如果通过

=== 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.
=== QA验证完成 ===

状态: 已通过

所有验收标准已验证:
- 单元测试: 通过
- 集成测试: 通过
- 人工验证: 通过
- 安全评审: 通过
- 回归检查: 通过

该实现已符合生产发布要求。
可合并。

If REJECTED

如果驳回

Create fix request and proceed to Part 2.
创建修复请求，进入第二部分。

Part 2: QA Fix Loop

第二部分：QA修复循环

Phase 0: Load Fix Request

阶段0：加载修复请求

bash
undefined
bash
undefined

Read the QA report with issues

读取包含问题的QA报告

cat .claude/context/reports/qa/qa-report.md
cat .claude/context/reports/qa/qa-report.md

Identify issues to fix

识别需要修复的问题

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

Extract from report:

- Exact issues to fix
- File locations
- Required fixes
- Verification criteria
grep -A 50 "## Issues Found" .claude/context/reports/qa/qa-report.md

从报告中提取：

- 需修复的精确问题
- 文件位置
- 要求的修复方案
- 验证标准

Phase 1: Parse Fix Requirements

阶段1：解析修复需求

Create a checklist from the QA report:
FIXES REQUIRED:
1. [Issue Title]
   - Location: [file:line]
   - Problem: [description]
   - Fix: [what to do]
   - Verify: [how to check]

2. [Issue Title]
   ...
You must address EVERY issue.
根据QA报告创建检查清单：
需修复项:
1. [问题标题]
   - 位置: [文件:行号]
   - 问题: [描述]
   - 修复方案: [操作说明]
   - 验证方式: [检查方法]

2. [问题标题]
   ...
你必须处理所有问题。

Phase 2: Fix Issues One by One

阶段2：逐个修复问题

For each issue:
  1. Read the problem area
  2. Understand what's wrong
  3. Implement the fix
  4. Verify the fix locally
Follow these rules:
  • Make the MINIMAL change needed
  • Don't refactor surrounding code
  • Don't add features
  • Match existing patterns
  • Test after each fix
针对每个问题：
  1. 阅读问题所在区域代码
  2. 理解问题根源
  3. 实现修复
  4. 本地验证修复效果
遵循以下规则：
  • 仅做所需的最小变更
  • 不要重构周边代码
  • 不要新增功能
  • 匹配现有编码模式
  • 每个修复后都要测试

Phase 3: Run Tests

阶段3：运行测试

After all fixes are applied:
bash
undefined
所有修复完成后：
bash
undefined

Run the full test suite

运行完整测试套件

npm test
npm test

Run specific tests that were failing

运行QA报告中失败的特定测试

[failed test commands from QA report]

**All tests must pass before proceeding.**
[QA报告中失败的测试命令]

**继续下一步前必须所有测试通过。**

Phase 4: Self-Verification

阶段4：自验证

Before requesting re-review, verify each fix:
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
If any issue is not fixed, go back to Phase 2.
请求重新评审前，验证每个修复：
自验证:
[ ] 问题1: [标题] - 已修复
    - 验证方式: [验证操作]
[ ] 问题2: [标题] - 已修复
    - 验证方式: [验证操作]
...

所有问题已处理: 是/否
如果有任何问题未修复，回到阶段2。

Phase 5: Commit Fixes

阶段5：提交修复

bash
undefined
bash
undefined

Add fixed files

添加修复的文件

git 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"
undefined
git commit -m "fix: 解决QA问题
修复项:
  • [问题1标题]
  • [问题2标题]
验证:
  • 所有测试通过
  • 问题已本地验证"
undefined

Phase 6: Signal for Re-Review

阶段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修复完成 ===

已修复问题数: [N]

1. [问题1] - 已修复
   提交哈希: [hash]

2. [问题2] - 已修复
   提交哈希: [hash]

所有测试已通过。
可重新进行QA验证。

QA Loop Behavior

QA循环规则

The QA → Fix → QA loop continues until:
  1. All critical issues resolved
  2. All tests pass
  3. No regressions
  4. QA approves
Maximum iterations: 5
If max iterations reached without approval:
  • Escalate to human review
  • Document all remaining issues
  • Save detailed report
QA → 修复 → QA 循环会持续执行直到满足以下条件：
  1. 所有严重问题已解决
  2. 所有测试通过
  3. 无回归问题
  4. QA审批通过
最大迭代次数：5次
如果达到最大迭代次数仍未通过审批：
  • 升级到人工审核
  • 记录所有剩余问题
  • 保存详细报告

Severity Guidelines

严重程度指南

CRITICAL - Blocks sign-off:
  • Failing tests
  • Security vulnerabilities
  • Missing required functionality
  • Data corruption risks
MAJOR - Should fix:
  • Missing edge case handling
  • Performance issues
  • UX problems
  • Pattern violations
MINOR - Nice to fix:
  • Style inconsistencies
  • Documentation gaps
  • Minor optimizations
严重 - 阻断审批：
  • 测试失败
  • 安全漏洞
  • 缺失必填功能
  • 数据损坏风险
重要 - 应当修复：
  • 缺失边界场景处理
  • 性能问题
  • UX问题
  • 规范违反
次要 - 建议修复：
  • 风格不一致
  • 文档缺失
  • 次要优化

Verification Checklist

验证清单

Before approving:
  • All unit tests pass
  • All integration tests pass
  • All E2E tests pass (if applicable)
  • Manual verification of acceptance criteria
  • Security review complete
  • Pattern compliance verified
  • No regressions found
  • QA report generated
审批前确认：
  • 所有单元测试通过
  • 所有集成测试通过
  • 所有E2E测试通过（如有）
  • 人工验证所有验收标准
  • 安全评审完成
  • 规范合规性已验证
  • 未发现回归问题
  • 已生成QA报告

Common Mistakes

常见错误

Approving Too Quickly

审批过快

Why it's wrong: Shipping bugs to users.
Do this instead: Check EVERYTHING in the acceptance criteria.
错误原因： 把Bug发布给用户。
正确做法： 检查验收标准中的每一项内容。

Vague Issue Reports

问题报告模糊

Why it's wrong: Developer can't fix what they don't understand.
Do this instead: Exact file paths, line numbers, reproducible steps.
错误原因： 开发者无法修复他们不理解的问题。
正确做法： 提供精确的文件路径、行号、可复现步骤。

Fixing Too Much

修复范围过大

Why it's wrong: Introducing new bugs while fixing old ones.
Do this instead: Minimal changes. Fix only what QA found.
错误原因： 修复旧问题的同时引入新Bug。
正确做法： 最小变更，仅修复QA发现的问题。

Integration with Other Skills

与其他技能的集成

This skill works well with:
  • complexity-assessment: Determines validation depth
  • tdd: Use TDD to write tests for fixes
  • debugging: Use when investigating test failures
该技能适用于以下场景：
  • 复杂度评估：决定验证深度
  • TDD：使用TDD为修复编写测试
  • 调试：调查测试失败时使用

Memory Protocol

存储协议

Before starting: Read 
.claude/context/memory/learnings.md
After completing:
  • New pattern -> 
    .claude/context/memory/learnings.md
  • Issue found -> 
    .claude/context/memory/issues.md
  • Decision made -> 
    .claude/context/memory/decisions.md
ASSUME INTERRUPTION: If it's not in memory, it didn't happen.
开始前： 读取 
.claude/context/memory/learnings.md
完成后：
  • 新模式 -> 
    .claude/context/memory/learnings.md
  • 发现的问题 -> 
    .claude/context/memory/issues.md
  • 做出的决策 -> 
    .claude/context/memory/decisions.md
假设存在中断：如果未存入存储，等于事件未发生。