在现有代码库中给新 QA 工程师做入职或审计继承测试架构时…

适用于新 QA 加入既有团队/代码库、接手无文档测试套件或需要项目测试参考文档时，目标是在两周内把真实测试合并到 main 并在 CI 通过。

适用场景

解决思路

1. 开始前检查项目根目录的 `.agents/qa-project-context.md`；若存在，用它回答大部分发现问题和提供 onboarding 技术上下文；若不存在，把创建它作为第一个行动项。
2. 识别当前任务属于哪类：给现有团队 onboarding 新成员、审计继承的现有测试套件、或需要给所有写测试的人提供参考文档；onboarding 新成员跳到 First 30 Days Checklist 和 Mentorship Patterns；继承套件跳到 Test Architecture Audit；需要参考文档跳到 Framework Walkthrough Template；完整 onboarding 通常三者都做，快速健康检查只做审计。
3. 发现并确认被 onboarding 的人是 QA 工程师还是参与测试的开发者：QA 工程师需要测试策略上下文和代码库 orientation，开发者需要框架模式和约定，ramp-up 路径不同。
4. 发现并确认被 onboarding 的人对测试框架的经验水平：第一次用 Playwright/Cypress/pytest，还是有经验但新代码库，还是高级只需约定；据此决定 framework walkthrough 深度。
5. 发现并确认是 solo QA 还是加入现有 QA 团队：solo QA 需要从零建立约定，加入团队则学习现有模式并在既定规范内贡献。
6. 发现并确认项目是否已有测试框架；若有，评估健康度；若没有，框架选择是第一步，参见 `test-strategy` skill。
7. 发现并确认项目是否有 `.agents/qa-project-context.md`；若没有，创建它是高优先级 onboarding 任务，迫使新人记录所学并惠及全队。
8. 发现并确认本地环境搭建是否已文档化：新人是否能在第一天运行全栈并执行测试；若搭建超过 2 小时，先修复流程再 onboarding。
9. 发现并确认所有所需账号和权限已设置：repository 访问、CI dashboard、staging 环境、测试数据账号、bug tracker、沟通频道；缺少访问会浪费时间并造成挫败。
10. 以 time to first merged test 为成功指标：让新人尽快把真实测试合并到 main，不是教程练习或仅本地实验，而是运行在 CI 并验证真实产品行为的测试；目标前两周内。
11. 采用渐进复杂度：第一个测试做 smoke test 或 page-load 验证；第二个测试做 form interaction；第三个测试做 multi-step user flow；第三周开始为 sprint stories 写测试；不要在第一天扔进复杂多服务流程。
12. 记录 tribal knowledge：每当新人问文档未回答的问题，就把答案永久记录，优先写入 `.agents/qa-project-context.md`、framework walkthrough 文档或代码注释；新人最适合写这些文档，因为他们知道缺了什么。
13. 前 3 个测试先配对再独立：新人驱动，有经验成员导航；配对传递隐性知识，解释为什么这样做而不是只讲怎么做，并更快建立信心。
14. 让容易路径成为正确路径：确保 test utilities、fixtures、page objects、data factories 让推荐模式成为阻力最小路径；如果新人必须对抗框架才能遵循约定，就修复框架。
15. 根据 `team_maturity` 校准：startup 聚焦 days 1-10，先让一个测试框架运行并覆盖一条关键路径，跳过流程仪式直到有工作基线；growing 执行完整 30 天计划，包括框架选择、CI 集成、覆盖率基线、团队约定文档化；established 在 30 天计划外加审计现有套件反模式、提出工具升级、建立指标基线、安排 recurring quality reviews。
16. Week 1 Day 1-2 setup：克隆仓库并在本地构建。
17. Week 1 Day 1-2 setup：配置所有环境变量（`.env.local`、测试凭据）。
18. Week 1 Day 1-2 setup：本地运行应用（frontend + backend + database）。
19. Week 1 Day 1-2 setup：本地运行测试套件并通过，或记录已知失败。
20. Week 1 Day 1-2 setup：配置 IDE 推荐扩展（test runner plugin、linter、formatter）。
21. Week 1 Day 1-2 setup：授予访问权限：CI dashboard、staging 环境、bug tracker、团队频道。
22. Week 1 Day 3-4 orientation：阅读 `.agents/qa-project-context.md`，若不存在则创建。
23. Week 1 Day 3-4 orientation：与团队成员走查测试目录结构。
24. Week 1 Day 3-4 orientation：理解测试金字塔：unit、integration、E2E 数量。
25. Week 1 Day 3-4 orientation：审查 CI pipeline：PR 运行什么、nightly 运行什么、什么阻塞 merge。
26. Week 1 Day 3-4 orientation：识别 top 5 critical user flows，作为首批测试目标。
27. Week 1 Day 3-4 orientation：作为观察者参加一次 Three Amigos 或 sprint planning session。
28. Week 1 Day 3-4 orientation：与团队 AI 助手协作：识别团队使用哪些 coding agents（Claude Code、Codex、Cursor、Gemini CLI 等），上下文存放位置（`.agents/qa-project-context.md`、`CLAUDE.md`、`AGENTS.md`），哪些 prompts/skills 是 house style，哪些任务明确不委托给 AI；产出简短 AI assistants we use, what they are good at, what to never let them do 文档作为 Day 4 deliverable。
29. Week 1 Day 3-4 orientation：若团队通过 agent 自动化 Playwright，记录 agent-driven Playwright 现有独立 `@playwright/cli`（daemon architecture、`playwright-cli` 命令、token-efficient），区别于 framework walkthrough 记录的 `npx playwright test` runner。
30. Week 1 Day 5 first small win：在 debug/headed 模式运行单个测试并理解其作用。
31. Week 1 Day 5 first small win：修改现有测试的一个断言，验证它按预期失败，再还原。
32. Week 1 Day 5 first small win：阅读 3 个现有测试并注释每部分作用（setup、action、assertion）。
33. Week 2 first real test：识别简单低风险测试（页面加载、元素可见性、基础导航）。
34. Week 2 first real test：使用现有 page objects 和 fixtures 编写测试（与团队成员配对）。
35. Week 2 first real test：本地运行测试并确保稳定通过（连续 3 次）。
36. Week 2 first real test：开 PR，接收反馈并迭代。
37. Week 2 first real test：测试在 CI 通过。
38. Week 2 first real test：合并第一个测试。
39. Week 3 sprint contribution：在指导下接手 sprint story 的 QA 工作。
40. Week 3 sprint contribution：编写覆盖 story 验收标准的测试。
41. Week 3 sprint contribution：识别至少一个验收标准未覆盖的 edge case。
42. Week 3 sprint contribution：积极参与 Three Amigos 或 story refinement，提问。
43. Week 3 sprint contribution：用 `shift-left-testing` 的 PR review checklist 审查一个现有 PR 的测试质量。
44. Week 4 independence milestones：不配对编写并合并一个多步骤 E2E 测试。
45. Week 4 independence milestones：参与 bug triage 并阐明测试缺口。
46. Week 4 independence milestones：向 `.agents/qa-project-context.md` 贡献新学习。
47. Week 4 independence milestones：在 sprint review 或团队 standup 展示测试结果/发现。
48. Week 4 independence milestones：自评哪些测试模式舒服、哪些需要更多练习。
49. Test Architecture Audit：加入现有项目时，在写新测试前评估测试套件健康度；审计耗时 2-4 小时并产出当前状态清晰图景。
50. 按 `team_maturity` 确定审计范围：startup 跳过全面审计，确认一条路径被覆盖且一个框架可运行，把节省时间用于合并首个测试；growing 运行全部五维一次建立基线，推迟 recurring reviews；established 做完整五维审计加定期质量评审（如 monthly），并持续跟踪 findings doc。
51. 评估五维之一 Coverage and Distribution：按层测试数量、金字塔形状、代码覆盖率和趋势。
52. 评估五维之二 Reliability：flaky test rate、最 flaky 测试、quarantine 数量和年龄。
53. 评估五维之三 CI Health：全套件和每阶段耗时、并行度、通过率、重试率。
54. 评估五维之四 Technical Debt：skipped tests、`waitForTimeout`/`force: true` 使用、硬编码数据、无断言测试、废弃 API、陈旧 AI 生成测试、陈旧 feature flags。
55. 评估五维之五 Conventions：page objects、fixtures、factories、命名、共享 utilities、tagging。
56. 使用 `references/audit-worksheets.md` 中覆盖全部五维的 copy-and-fill worksheets。
57. Audit Output：产出 1-2 页文档总结发现，分类为 Strengths、Gaps、Risks、Quick Wins、Strategic Work。
58. Audit Output：Strengths 写现有套件做得好的地方，保留并学习。
59. Audit Output：Gaps 写缺失覆盖区域和测试不足的关键路径。
60. Audit Output：Risks 写 flaky tests、陈旧 quarantines、覆盖率下降。
61. Audit Output：Quick Wins 写 1-2 个 sprint 可完成的改进，如修复 flaky tests、补缺失 happy-path 覆盖。
62. Audit Output：Strategic Work 写需要持续投入的改进，如重构测试架构、添加 integration layer。
63. Framework Walkthrough：为项目创建该文档，作为任何写测试的人的主要参考；包含六部分。
64. Framework Walkthrough 第 1 部分 Architecture Overview：框架、语言、配置位置和带注释目录树。
65. Framework Walkthrough 第 2 部分 How to Run Tests：完整运行命令（all tests、single file、grep、headed、debug、UI mode、per-browser、report）。
66. Framework Walkthrough 第 3 部分 How to Write a New Test (Step by Step)：六步 location/reuse/write/run/PR 流程，加 Arrange-Act-Assert 测试模板。
67. Framework Walkthrough 第 4 部分 How to Debug Failures：本地 vs CI 失败 playbooks 和 common failure-pattern decoder。
68. Framework Walkthrough 第 5 部分 Common Patterns and Conventions：项目特定示例，包括 auth fixtures、data factories、assertion specificity、selector priority。
69. Framework Walkthrough 第 6 部分 Where to Find Help：关于 patterns、failures、product behavior、docs 的问题路由表。
70. 参考 `references/framework-walkthrough.md` 获取完整模板，包括所有 code blocks、directory trees、command lists 以复制和调整。
71. Codebase Orientation Guide：安排 60-90 分钟与新人走查。
72. Test Directory Structure Tour：走查实际目录树，解释为什么按 feature 而非按 type 组织测试、每个产品区域的 page objects 在哪、共享 utilities 在哪及作用、测试数据和 fixtures 在哪定义、CI 配置在哪。
73. Shared Utilities Inventory：列出并讲解 `fixtures/auth.fixture.ts` 提供认证会话 `{ adminPage, userPage }`。
74. Shared Utilities Inventory：列出并讲解 `helpers/factories.ts` 通过 API 创建测试数据 `createTestUser({ role: 'editor' })`。
75. Shared Utilities Inventory：列出并讲解 `helpers/api-client.ts` 直接 API 调用用于 setup/teardown `apiClient.delete('/users/' + id)`。
76. Shared Utilities Inventory：列出并讲解 `helpers/a11y.ts` 是 axe-core wrapper `checkAccessibility(page, testInfo)`。
77. Shared Utilities Inventory：列出并讲解 `helpers/assertions.ts` 自定义 matchers `toHaveToast('Saved')`。
78. Page Objects Walk-Through：展示现有 page objects 并解释 base page class 及其 contract（abstract `path`、`waitForReady`）。
79. Page Objects Walk-Through：解释 component objects 如何与 page objects 组合。
80. Page Objects Walk-Through：解释命名约定，文件名匹配 route，例如 `checkout.page.ts` 对应 `/checkout`。
81. Page Objects Walk-Through：解释如何添加新 page object，从最简单的现有对象 copy-modify。
82. CI Pipeline Walk-Through：打开 CI 配置并追踪 pipeline 触发条件（push、PR、schedule）。
83. CI Pipeline Walk-Through：追踪运行哪些阶段及顺序。
84. CI Pipeline Walk-Through：追踪测试 artifacts 去向（reports、traces、screenshots）。
85. CI Pipeline Walk-Through：演示如何查找和解释 CI 中的失败测试。
86. CI Pipeline Walk-Through：演示如何重新运行失败 job。
87. Mentorship Pattern：Pair on first 3 tests 的 Test 1 Navigator/Driver：有经验者解释方法并做关键决策，新人打字并在每步问为什么，目标理解工作流。
88. Mentorship Pattern：Pair on first 3 tests 的 Test 2 Co-pilots：双方平等贡献，新人做更多决策，有经验者补缺，目标建立信心。
89. Mentorship Pattern：Pair on first 3 tests 的 Test 3 Observer：新人完全驱动，有经验者观察，仅在被要求或方法会导致问题时给反馈，目标独立。
90. Mentorship Pattern：前 2 周 review 所有 PR：对新人每个 PR 做彻底、支持性 review，不只看 LGTM，具体反馈 pattern adherence、selector strategy、assertion quality、test isolation、naming；两周后降到标准 review 深度。
91. Mentorship Pattern：Testing Buddy System：指定 testing buddy，第一周每天 check in 问 What are you stuck on，随时可回答 ad-hoc 问题无需预约，所有 PR 给教育性评论解释 why，介绍团队规范和不成文规则。
92. Mentorship Pattern：Progressive Responsibility Ramp：Week 1-2 为现有、理解良好的功能写测试（smoke、basic flows）。
93. Mentorship Pattern：Progressive Responsibility Ramp：Week 3-4 为当前 sprint stories 写测试（可配对）。
94. Mentorship Pattern：Progressive Responsibility Ramp：Week 5-6 独立写测试并 review 他人 PR。
95. Mentorship Pattern：Progressive Responsibility Ramp：Week 7-8 贡献测试架构（新 fixtures、utilities、page objects）。
96. Mentorship Pattern：Progressive Responsibility Ramp：Month 3+ 领导某功能区域的测试计划，并指导下一个新人。
97. 避免 Sink or Swim Onboarding：不要只给 repository 访问和 README 就让新人自己摸索；用结构化 onboarding 加配对，在第一 sprint 回本。
98. 避免 Tutorial-Only Onboarding：不要把两周花在框架教程和玩具练习后再碰真实代码库；把教程限制在 1-2 小时并尽快进入真实测试。
99. 避免 No Documentation, All Tribal Knowledge：不要让每个问题的答案都是 ask Sarah；把约定写进 `.agents/qa-project-context.md` 和 framework walkthrough；重要到值得口头解释的事就重要到值得写下来。
100. 避免 Perfectionism Paralysis：不要期望新人第一个测试完美；第一个测试只需功能正确并遵循基本约定，质量通过每个 PR review cycle 提升；不要因风格细节或高级模式阻塞首个 PR。
101. 避免 Ignoring the Onboarding Experience：不要忽略被 onboarding 者的反馈；他们在第 2 周和第 4 周末各做 15 分钟反馈 session，并用反馈改进下一次 onboarding。
102. 避免 Copy-Paste Without Understanding：不要让新人复制现有测试、改 locators 和 URL 就结束；配对和 code review 聚焦每个模式背后的 why；如果新人不能解释 fixture 为什么这样结构，他们在上下文不同时会误用。
103. Verification：验证第一个合并测试稳定而非侥幸；先本地重复运行排除 flakiness，再确认 CI green：`npx playwright test <new-test> --repeat-each=3` 退出 0，且 PR 的 CI check 对同一测试 green。
104. Verification：验证 audit doc 完整而非 stub；打开 findings doc 确认五维（coverage/distribution、reliability、CI health、technical debt、conventions）填满，发现分类为 strengths / gaps / risks / quick wins / strategic work；startup 若 scope out 审计则记录该决定。
105. Verification：验证 context file 可解析且已填充；`.agents/qa-project-context.md` 存在并包含 framework、critical paths、team structure、risk areas，不是高层占位符。
106. Done When：至少一个工作测试合并到 repo、CI 通过、本地 `--repeat-each=3` 连续 3 次稳定通过，证明本地和 pipeline 端到端设置。
107. Done When：Test architecture audit doc 存在且五维填满并分类（strengths、gaps、risks、quick wins、strategic work），或对 startup `team_maturity` 明确记录 scope out 决定。
108. Done When：Week-1 Day-1/2 每个 setup item 有记录 owner 和 target date；blocking items 建 tracked tickets。
109. Done When：`.agents/qa-project-context.md` 存在并填充 framework、critical paths、team structure、risk areas，不是占位符。
110. Done When：测试框架选定并记录理由（评估 alternatives、写下决定），或继承现有框架时标 N/A。
111. 使用 references：阅读 `references/framework-walkthrough.md` 获取完整 framework walkthrough 模板。
112. 使用 references：阅读 `references/audit-worksheets.md` 获取测试架构审计的 copy-and-fill worksheets。
113. 相关技能：使用 `qa-project-context`，因为项目上下文文件是 onboarding 基础；不存在则创建，onboarding 中更新。
114. 相关技能：使用 `playwright-automation` 获取 Playwright 项目的框架特定模式、page object model、fixtures、CI 集成。
115. 相关技能：使用 `shift-left-testing` 向新人介绍团队 shift-left 实践：Three Amigos、PR review、Definition of Done。
116. 相关技能：使用 `test-strategy` 让新人理解整体测试策略以及测试为什么这样组织。
117. 相关技能：使用 `test-reliability` 让新人理解 flaky test patterns 和 quarantine 管理，避免创建不可靠测试。

适用边界 · 注意事项

• 不适用于从零开始的新项目 QA 搭建；这种情况应使用 `qa-start`。
• 如果只需要快速健康检查，不必执行完整 30 天入职计划，只做测试架构审计。
• 如果本地环境搭建超过 2 小时，先修复环境搭建流程，再按本技能入职。