qa-do

大多数 QA 场景都符合可识别的模式。此技能会根据你想做什么或遇到了什么问题的通俗描述，匹配相应模式，并按顺序选出接下来的 1–2 个技能。对于操作请求，执行这些技能的工作流；如果用户询问该选择哪个技能，则只提供建议。如果调用时带有参数，场景为 `$ARGUMENTS`；否则，根据当前任务和项目证据推断。

探索问题

先检查 .agents/qa-project-context.md。在提问前，检查项目清单、测试、当前更改、已配置的目标和可用工具。只有当缺少的目标或要求会影响所请求的工作时，才提问。

核心原则

1. 选择最精准的技能，而不是最相近的技能。 与宽泛技能模糊匹配，不如直接命中范围更窄的技能。“复现此 Bug”应选择 bug-reproduction，而不是更宽泛的 ai-bug-triage；“测试我们的 Stripe 结账流程”应选择 payment-testing，而不是通用的 api-testing。如有疑问，优先选择其触发短语明确提及请求中具体对象的技能。

2. 按顺序选择一个或两个技能，绝不堆叠。 最多输出两个技能。只有当第一个技能留下明显缺口时（诊断 → 测量、风险 → 检查清单），第二个技能才有必要。如果一个技能就能覆盖请求，请注明“直接”，并执行该技能。需要路由到三个技能意味着场景不明确，应先提出澄清问题。

3. 路由表是唯一依据，但可能过时。 此路由器特别容易出现偏差：每当 skills/ 中新增技能，路由表就可能缺少对应条目。每当新增或移除技能时，都要根据 skills/ 重新生成路由表和“技能类别”参考内容。如果请求没有对应条目，应回退到“快速参考”中最接近的类别，而不是强行匹配错误的技能。

使用方法

用一两句话描述你想做什么或遇到了什么问题即可。路由器会输出推荐的技能（按顺序列出 1–2 个），并为每个技能用一行说明其作用。例如：“我们的 E2E 测试在 CI 中总是失败，但在本地通过。” → test-reliability（诊断易受环境影响的测试和不稳定测试），然后是 ci-cd-integration（使流水线环境与本地行为一致）。

执行应用检查

完整代码仓库可用时，请使用仓库提供的限定范围运行器。将 <qa-skills> 解析为此检出目录，将 <project> 解析为应用，即使当前工作目录不同也一样。

node <qa-skills>/scripts/qa.mjs plan --project <project> --goal "<user goal>"
node <qa-skills>/scripts/qa.mjs run --project <project> --goal "<user goal>"

阅读计划中的主要技能和下一个相关技能，然后执行它们的工作流。运行器会查找可用的测试命令，并生成 report.html、result.json、日志和主机交接文件。计划不等于已执行测试。如果只安装了单个技能，则直接执行其操作步骤，并保留等效证据。

对于 URL 检查，使用具体目标和由应用提供的就绪选择器。运行已配置的检查，不要因为缺少可选集成而停止其他无关的本地工作。缺少浏览器、目标不可用、未发现测试或测试结果无法读取，都应标记为受阻或未完成。保留跳过的用例。

如果失败，应复现问题并保留其断言；只有当修复属于用户请求的范围时才进行修复。修改代码后再次执行。如果失败仍然存在，最多尝试两次，然后停止并报告确切的阻碍；不得削弱断言或无限重试。报告涵盖已执行的检查，不代表普遍正确性。配置和主机集成说明请参阅仓库的 docs/QA-RUNNER.md。

常见场景及其技能

场景	推荐技能	顺序
新项目，完全没有测试	qa-start（或 qa-project-context → test-strategy）	搭建完整的 QA 配置
为现有代码库引入 QA 工程师	qa-project-bootstrap	直接使用——30 天上手计划 + 架构审计
“测试在 CI 中总是失败”	test-reliability → ci-cd-integration	先解决可靠性，再处理流水线
“UI 重构/重新设计导致许多选择器失效”	selector-drift-recovery	直接使用——批量重新生成，而非逐个测试修复
“本次发布前应该测试什么？”	risk-based-testing → release-readiness	先评估风险，再使用检查清单
“我们需要 Playwright 测试”	playwright-automation	直接使用
“我们需要 Cypress 测试”	cypress-automation	直接使用
“让 Agent 探索应用并验证结果”	agentic-browser-testing	直接使用——由目标驱动，无需脚本
“根据这份 PRD/规格说明/用户故事编写测试”	ai-test-generation	直接使用
“复现这个描述模糊的问题 / 将这份报告转化为失败测试”	bug-reproduction	直接使用——经过验证的最小复现 + 回归测试
“审查我的测试 / 查找测试异味”	ai-qa-review	直接使用
“我们的测试套件运行缓慢且不稳定”	test-reliability → qa-metrics	先诊断，再衡量
“我们的测试套件臃肿 / 冗余测试太多”	test-suite-curation	直接使用——审计并基于证据精简
“管理 / 编写手动测试用例（TestRail、Xray、Zephyr、Qase）”	test-case-management	直接使用
“设置测试报告”	qa-dashboard → ci-cd-integration	先设计仪表板，再接入 CI
“测试我们的 API”	api-testing	直接使用
“编写单元测试 / 添加模拟对象 / 设置覆盖率阈值”	unit-testing	直接使用
“测试我们的数据库 / 迁移 / 数据完整性”	database-testing	直接使用
“设置消费者驱动的契约测试（Pact）”	contract-testing	直接使用
“我们的覆盖率缺口在哪里？”	coverage-analysis	直接使用
“开展有结构的探索式 / 基于测试章程的测试会话”	exploratory-testing	直接使用
“检查无障碍合规性”	accessibility-testing	直接使用
“测试我们的支付 / Stripe 结账 / 3DS / 订阅计费”	payment-testing	直接使用
“测试注册确认 / 密码重置 / OTP 邮件流程”	email-testing	直接使用
“验证分析 / GA4 / 像素 / dataLayer 事件是否正确触发”	analytics-tracking-testing	直接使用
“生产环境出现了问题，想弄清原因”	bug-reproduction → quality-postmortem	先复现，再复盘
“对一批 CI 失败进行分类 / 分诊”	ai-bug-triage	直接使用——批量聚类失败
“我们正在从 Selenium/Cypress 迁移”	test-migration	直接使用
“性能正在退化”	performance-testing → observability-driven-testing	先衡量，再追踪
“设置测试数据”	test-data-management	直接使用
“设置 / 容器化测试环境或预发布环境”	test-environments	直接使用
“将测试加入 CI”	ci-cd-integration	直接使用
“视觉变更导致测试失败”	visual-testing → test-reliability	先建立基线，再提升稳定性
“我们完全不了解质量现状”	qa-metrics → qa-dashboard	先定义 KPI，再展示指标
“第三方 API 在测试中不可靠”	service-virtualization	直接使用
“需要在多种浏览器上测试”	cross-browser-testing	直接使用
“需要在真实 iOS/Android 设备上测试（Appium/Detox/Maestro）”	mobile-testing	直接使用
“即将进行安全审计”	security-testing	直接使用
“测试彼此依赖，且随机顺序运行时会失败”	test-data-management → test-reliability	先解决数据隔离问题
“在发布期间安全地推出功能（标志、金丝雀发布）”	testing-in-production	直接使用
“安排发布后运行的探测 / SLA 检查”	synthetic-monitoring	直接使用
“我们的 QA 总是在开发完成后才发现问题，为时已晚”	shift-left-testing → test-planning	先改变流程，再制定计划
“我们正在构建 AI/LLM 功能，需要对其进行测试”	ai-system-testing	直接使用
“让这份测试报告听起来更自然 / 少点 AI 味”	qa-report-humanizer	直接使用
“确保符合 GDPR/EAA/AI Act”	compliance-testing	直接使用
“在预发布环境中运行混沌测试 / 故障注入”	chaos-engineering	直接使用

情况模糊时

如果某个描述同等适用于三个或更多技能，只需问一个澄清问题即可缩小范围。回答后，路由器会将范围缩减到 1-2 个技能。

• “你是在修复已损坏的内容，还是从头开始构建新的覆盖？”
• “这是流程问题（团队如何协作），还是工具问题（正在运行什么）？”
• “优先考虑交付速度，还是结果正确性的可信度？”
• “你是唯一的 QA，还是这项变更会影响整个团队？”

消除歧义的对比项（需要厘清的四种重叠，而非猜测）

• test-reliability 与 selector-drift-recovery — 单个不稳定测试在运行时得到修复 → test-reliability；计划中的 UI 重构导致许多选择器失效 → selector-drift-recovery。
• cross-browser-testing 与 mobile-testing — 浏览器／CSS 引擎 → cross-browser-testing； 真机、Appium/Detox/Maestro、手势／深层链接 → mobile-testing。
• ai-bug-triage 与 bug-reproduction — 对一批 CI 失败进行分类／去重 → ai-bug-triage；复现并理解某个具体缺陷 → bug-reproduction。
• qa-start 与 qa-project-bootstrap — 全新项目，尚未开展 QA → qa-start； 为 QA 工程师安排现有代码库的入职引导 → qa-project-bootstrap。

技能类别速查

每当技能发生变化时，请根据每个 skills/*/SKILL.md 的 category: 字段重新生成此表。

类别	技能
基础	qa-project-context, qa-start, qa-do
策略	test-strategy, test-planning, risk-based-testing, exploratory-testing
自动化	playwright-automation, cypress-automation, api-testing, unit-testing, mobile-testing, visual-testing, performance-testing, cross-browser-testing, database-testing, security-testing, selector-drift-recovery
专业领域	accessibility-testing, payment-testing, email-testing, analytics-tracking-testing
AI-QA	ai-test-generation, ai-bug-triage, bug-reproduction, test-reliability, ai-qa-review, agentic-browser-testing
基础设施	ci-cd-integration, test-environments, test-data-management, contract-testing, service-virtualization
指标	qa-metrics, qa-dashboard, coverage-analysis
流程	shift-left-testing, qa-project-bootstrap, release-readiness, quality-postmortem, compliance-testing, qa-report-humanizer, test-case-management, test-suite-curation
生产环境	testing-in-production, synthetic-monitoring, observability-driven-testing
知识	ai-system-testing, chaos-engineering, test-migration

反模式

• 存在精准技能时却路由到宽泛技能。“复现此缺陷” → 路由到 ai-bug-triage（批量分类），而非 bug-reproduction（单个已验证的复现）。修正方法：将请求中的确切产物与名称匹配的技能对应起来。
• **针对同一种情况叠加三个或更多技能。**这意味着存在歧义，而非考虑周全。修正方法：提出一个澄清问题，将范围缩减到 1-2 个技能。
• **盲信过时的表格。**如果最近新增的技能没有对应行，路由器就会悄悄将请求错误路由到能力较弱的相近技能。修正方法：根据 skills/ 重新生成表格（核心原则 3），并退而选择最接近的速查类别，而不是强行错误匹配。
• 接手本应交由同级命名技能处理的请求。“在新项目中设置 QA”对应 qa-start；“记录项目上下文”对应 qa-project-context。只有在万不得已时才使用 qa-do。

完成标准

• 明确指出接下来要用的 1-2 个技能，并说明理由与当前任务的关联。
• 对于行动请求，已执行相关检查，或记录了具体的阻碍因素。
• 报告指出目标、源代码版本、命令、结果和剩余差距。
• 能够区分已编写、已执行、失败、跳过、受阻和未运行的检查。

相关技能

• qa-start — 最容易与此技能混淆的同级技能。在全新项目中启动 QA 且尚未建立任何 QA 流程时，使用此技能（而不是 qa-do）；它会串联项目背景 → 策略 → 规划。
• qa-project-context — 使用大多数技能前，先记录项目设置；每项技能都会先检查这一点。请转到此技能，不要重复实现。
• test-strategy — 当需求是“我们需要一套 QA 策略”，而不是要处理某个具体问题时使用。