从规格、PRD、用户故事、代码 diff、bug 报告或…

用 AI 从规格、PRD、用户故事、代码 diff、bug 报告或 OpenAPI 生成新测试代码时，按分阶段流水线产出可审查、可追溯的测试。

适用场景

解决思路

1. 开始前检查项目根目录 `.agents/qa-project-context.md`；若存在则读取并使用其中的技术栈、测试框架、命名约定、选择器策略和已知风险区域，并跳过 Discovery 中已回答的问题。
2. 根据输入源确定 Step 1 的提取重点：PRD/feature spec 提取实体、业务规则、验收标准、NFR、声明的假设，并警惕从「seamless」「fast」等词推断出的隐含需求。
3. 若输入是 user story + AC：将每个 AC 转为至少 1 个 happy path 和至少 1 个 negative 场景；警惕一行 AC 隐藏多个行为。
4. 若输入是 code diff（`git diff main...HEAD`）：提取新增/变更代码路径、修改的条件、移除的行为；限定回归范围到变更路径，而不是整个模块。
5. 若输入是 bug report：提取复现步骤、期望 vs 实际、环境；编写断言*期望*行为的测试，使其现在失败、修复后通过。
6. 若输入是 OpenAPI / GraphQL SDL：提取端点、模式、必填字段、枚举、认证；为每个端点考虑验证、认证失败和边缘情况，而不只是 200 响应。
7. 若项目使用 Playwright，按 Discovery Q2 选择 agent integration mode：Playwright CLI + agents、Playwright MCP 或都不用。
8. 澄清输入源是什么，以决定 Step 1 提取重点；若输入是 LLM/AI 功能 spec，停止并在 `ai-system-testing` 生成 eval 数据集，而不是 Playwright specs。
9. 澄清目标测试框架：E2E 用 Playwright（优先）或 Cypress；Unit 用 Jest、Vitest、pytest；API 用 Playwright `APIRequestContext`、Supertest、requests。
10. 若选 Playwright CLI + agents（Claude Code / Codex / Cursor 推荐）：运行 `npx playwright init-agents --loop=claude`，将 planner/generator/healer agents 脚手架到 `.claude/agents/` 作为 markdown；它们是交互式开发工具，产出标准 Playwright 测试，在 CI 中不变运行；token 高效，在 agent 循环内运行。
11. 若选 Playwright MCP：运行 `npx @playwright/mcp@latest`；开销更高，适合 agent 必须在长会话中交互式驱动实时浏览器。
12. 若两者都不用：手写测试，把 AI 当 scratch-pad 助手。
13. 收集项目上下文：现有测试模式、Page Objects/helpers、数据工厂/fixtures、CI 约束（超时、并行）；上下文越多，清理越少。
14. 确定审查工作流：完整流水线 → 人工审查 → 合并（默认）；仅场景 → 人工写代码；或代码 → 人工迭代精炼。
15. 收集领域知识：受监管行业（医疗、金融）合规、领域不变量（钱不能为负、预约不能重叠）、过去事件中的已知风险区域。
16. 遵循 Core Principle：Pipeline before code——在确定测试什么、为什么、如何验证之前，绝不生成测试代码。
17. 把结构化中间产物当作产品：假设文档、覆盖率矩阵、oracle 定义比测试代码本身更有价值，因为可审查、可追溯、可复用。
18. 分离 what 和 how：场景生成（测试什么）与 oracle 设计（如何验证）是不同认知任务，不要混合，否则场景会偏向容易断言的，断言变成事后附加。
19. AI 生成初稿，人工审查和精炼；未经人工审查绝不发布 AI 生成的测试。
20. 上下文就是一切：向 LLM 提供约定、现有模式、选择器策略、数据设置，以减少清理。
21. 质量优先于数量：每个测试都有维护成本，关注关键路径、复杂逻辑和已知风险区域，而不是测试数量。
22. 强制按顺序执行七步流水线：Step 1 Extract → Step 2 Analyze → Step 3 Map → Step 4 Generate → Step 5 Design → Step 6 Code → Step 7 Review。
23. Step 1：把输入解析成结构化元素：实体（角色/状态/属性）、编号业务规则、显式需求 `[REQ-N]`、隐式需求 `[IMP-N]`；每个隐式需求都标记供人工确认。
24. Step 2：做风险分析，生成风险表 `Risk | Likelihood | Impact | Source Requirement`（例如库存递减竞态、邮件延迟 > 30s）。
25. Step 2：列出必须始终成立的不变量，例如 `stock >= 0`、`order total = sum(items) + tax + shipping`、`user sees only their own orders`。
26. Step 2：明确捕获歧义并交给人工回答，例如「免运费是在折扣码之前还是之后应用？」；不要默默选一个。
27. Step 2：从风险推导边缘情况，例如两个用户购买最后一件、支付成功但邮件服务宕机。
28. Step 3：构建覆盖率矩阵，将每个需求映射到场景，包含类别、优先级、oracle 类型；这是防止缺口和重复的最重要产物。
29. Step 3 后验证：每个需求至少 1 个 happy path 和 1 个 negative 场景；每个不变量有直接测试；每个 Step 2 风险都有场景；没有两行测试同一事物。
30. Step 4：为每个矩阵行编写完整 Given/When/Then 场景，并明确测试数据需求，例如 `Given: user with 99 items in cart (max 100); When: adds one more; Then: count = 100`。
31. Step 4：系统覆盖类别：Happy path、Boundary（使用 `references/prompt-patterns.md` 中的 BOUNDARIES 框架）、Negative、Security、Accessibility、State transition、Concurrency。
32. Step 5：有意将断言和 oracle 设计与 Step 4 场景生成分开；场景描述行为，oracle 描述如何验证。
33. Step 5：为每个场景定义跨类别的 oracle：UI state（可见文本/元素状态）、Data（通过 API/DB 持久化状态）、Negative（什么不应发生）、Side effect（异步/外部结果）。
34. Step 5：遵循 oracle 质量规则：断言业务结果而非实现细节；使用最具体断言（如 `toHaveText('$29.99')`，不是 `toBeTruthy()`）；包含否定断言；验证数据完整性而不只是 UI；断言可访问性（焦点管理、live-region 公告）。
35. Step 6：仅在 Steps 1-5 产出并审查制品后生成测试代码；代码是场景 + oracle 到框架语法的机械翻译。
36. Step 6：在代码中包含追溯注释，链接回需求和场景，例如 `Scenario: SC-XXX`、`Requirement: REQ-XX`。
37. Step 6：遵循代码生成规则：匹配项目约定（来自 `qa-project-context.md`）；复用现有 Page Objects、fixtures 和数据工厂；遵循项目选择器策略；将 setup/teardown 放入 fixtures 而不是内联。
38. Step 7：执行强制人工审查（不可选），审查本流水线刚生成的测试；若审计预先存在且非刚生成的套件，改用 `ai-qa-review`。
39. Step 7：对每个生成测试运行检查清单：可追溯到需求；测试行为而非实现；抽象层级正确；命名和可读性表达行为；测试隔离/无共享状态；真实测试数据；有意义的断言；匹配项目约定；无 flakiness 风险；包含边缘情况；假设已验证。
40. Step 7：为每个测试记录审查结果：KEEP（原样合并）、MODIFY（修复后合并）、REJECT（错误需求、错误抽象、幻觉 API）、DEFER（因歧义阻塞）。
41. 遵守硬性护栏：禁止在有覆盖率之前写代码；若跳过到代码，STOP 并回到 Steps 1-3。
42. 遵守硬性护栏：断言结果而非实现，例如用 `expect(screen.getByRole('progressbar')).toBeVisible()`，不是 `expect(component.state.isLoading).toBe(true)`；用 `expect(page.getByTestId('cart-badge')).toHaveText('1')`，不是 `expect(store.dispatch).toHaveBeenCalledWith(...)`。
43. 遵守硬性护栏：始终先场景（Step 4）后 oracle（Step 5）；Scenario = WHAT happens，oracle = HOW to verify。
44. 始终产出中间产物——假设文档、未覆盖歧义、oracle 候选、追溯链——即使采用缩写形式。
45. 检测并标记幻觉 API：端点、选择器、方法、导入不存在于代码库；在人工审查前机械验证。
46. 检测并标记重复场景：相同行为、琐碎不同数据；合并或参数化。
47. 检测并标记低价值断言：`expect(response).toBeTruthy()`、`expect(page).toHaveURL(/.*/)`。
48. 检测并标记缺失否定用例：如果每个场景都是 happy path，覆盖率矩阵不完整。
49. 检测并标记不真实测试数据：`test@test.com`、`John Doe`、`password123`；使用多样、合理数据在 `example.com`。
50. 按难度路由模型：Step 1 机械提取和 Step 3 覆盖率矩阵记录用便宜模型，Haiku 4.5 或 Sonnet 4.6 足够。
51. Step 5 oracle 设计和 Step 6 对幻觉敏感的代码生成升级到 Opus 4.8；只在真正难推理（微妙不变量、受监管领域逻辑）时用 Fable 5。
52. 不要每步都用最强模型（浪费），也不要在 Step 6 用最便宜模型（会产生伪造 API）。
53. Verification 第 1 步：解析导入/类型。TypeScript 运行 `npx tsc --noEmit`；Python 运行 `python -m pyflakes <files>` 或 `ruff check`；伪造导入和错误签名会失败。
54. Verification 第 2 步：grep 生成的 selectors/endpoints 对代码库，确认每个 `getByTestId('...')` id 和 API path 实际存在；使用示例 grep 命令，任何 `MISSING` 行都是幻觉。
55. Verification 第 3 步：运行套件一次；引用不存在路由/选择器的测试会快速失败；在人工审查前隔离这些，而不是审查死代码。
56. 任何 `MISSING` 行或 `tsc` 错误必须在人工花时间审查前修复。
57. 避免反模式：不要跳过到代码；不要断言实现而非行为；不要混合场景和断言；不要在提示中没有项目上下文；不要过度生成；不要不理解就复制粘贴；不要未经审查就发布；不要忽略反馈循环。
58. 当 AI 测试抓到真实 bug 时，记录有效的 prompt patterns；当出现 false-positive 时，记录出错原因，建立项目特定有效库。
59. Done When：确保七个制品存在——requirements document、risk & invariants、coverage matrix、scenario set、oracle definitions、test code、review notes（每个测试有 KEEP/MODIFY/REJECT/DEFER 决定）。
60. Done When：覆盖率矩阵在任何测试代码文件写入前产生并审查。
61. Done When：验证通过——`tsc --noEmit`（或语言等价）退出 0，selector/endpoint grep 报告零 `MISSING` 行。
62. Done When：每个生成测试都有记录的人工审查决定；没有 KEEP 未记录。
63. Done When：套件 CI 任务退出 0（绿色）。
64. Done When：记录可复现性元数据——精确模型 ID（例如 `claude-opus-4-8`、`claude-sonnet-4-6`、`claude-haiku-4-5-20251001`）、输入源哈希、任何 skill/CLI/MCP server 版本。

适用边界 · 注意事项

• 不要在需要测试产品中的 AI/LLM 功能时使用；应使用 `ai-system-testing` 生成 eval 数据集。
• 不要在审计预先存在且不是本流水线刚生成的测试套件时使用；应使用 `ai-qa-review`。
• 若输入是 LLM/AI 功能 spec，应停止并改用 `ai-system-testing`，而不是 Playwright specs。