qa-project-bootstrap

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<objective> A new QA engineer pointed at the README and left to "figure it out" burns two weeks learning bad habits by trial and error, and an unaudited inherited suite hides flaky tests and coverage gaps that only surface in production. This skill reduces time to first merged test and produces three concrete artifacts: a 30-day ramp plan, a five-dimension test architecture audit, and a framework walkthrough doc. Every section serves the same metric — a real test merged to main and green in CI, fast.

Before starting: Check for

.agents/qa-project-context.md

in the project root. If it exists, it answers most discovery questions and provides the technical context for onboarding. If it does not, creating it is the first action item. </objective>

<objective> 如果让新QA工程师对着README自行“摸索”，他们会在两周的试错中养成坏习惯；而未经审计的遗留测试套件会隐藏不稳定测试和覆盖缺口，这些问题只会在生产环境中暴露。本技能可缩短首次合并测试的时间，并生成三份具体成果：一份30天入门计划、一份五维度测试架构审计报告，以及一份框架讲解文档。每个环节都围绕同一个衡量标准——快速将真实测试合并到主分支并在CI中运行成功。

开始前准备： 检查项目根目录下是否存在

.agents/qa-project-context.md

。如果存在，它会回答大多数探索性问题，并为入职提供技术背景。如果不存在，创建该文件是首要任务。 </objective>

Quick Route

快速路径

This skill serves three distinct jobs. Identify yours, jump to the section, skip the rest.

Situation	Jump to	Output
Onboarding a new person to an existing team	First 30 Days Checklist → Mentorship Patterns	A 30-day ramp plan with owners and dates
Inherited an existing suite with no onboarding/docs	Test Architecture Audit (scope by `team_maturity` )	A 1-2 page findings doc, five dimensions
Need the reference doc for anyone writing tests	Framework Walkthrough Template	A project-specific walkthrough.md

A real onboarding usually needs all three; a quick health check needs only the audit.

本技能适用于三种不同场景。请确定你的场景，跳转到对应部分，跳过其余内容。

场景	跳转至	输出成果
为现有团队引入新成员	前30天检查清单 → 导师指导模式	包含负责人和日期的30天入门计划
接手无入职文档的遗留测试套件	测试架构审计（按 `team_maturity` 划分范围）	1-2页的发现文档，涵盖五个维度
需要供所有测试编写人员参考的文档	框架讲解模板	项目专属的walkthrough.md文档

真实的入职流程通常需要全部三项内容；快速健康检查仅需审计环节。

Discovery Questions

探索性问题

Who Is Being Onboarded?

入职人员信息

New QA engineer or developer contributing to tests? QA engineers need test strategy context and codebase orientation. Developers contributing tests need framework patterns and conventions. The ramp-up path differs significantly.
Experience level with the test framework? First time with Playwright/Cypress/pytest? Experienced but new to this codebase? Advanced and just needs conventions? This determines how much framework walkthrough to include.
Solo QA or joining an existing QA team? Solo QA needs to establish conventions from scratch. Joining a team means learning existing patterns and contributing within established norms.

是新QA工程师还是参与测试开发的开发人员？ QA工程师需要测试策略背景和代码库介绍。参与测试开发的开发人员需要了解框架模式和约定。两者的入门路径差异显著。
对测试框架的熟悉程度如何？ 首次接触Playwright/Cypress/pytest？有经验但不熟悉当前代码库？技术娴熟仅需了解约定？这决定了框架讲解的深度。
是独立QA还是加入现有QA团队？ 独立QA需要从零开始建立约定。加入现有团队则需要学习现有模式并在既定规范内贡献。

Project State

项目状态

Is there an existing test framework? If yes: how healthy is it? If no: framework selection is step one (see
```
test-strategy
```
skill).
Does the project have a
.agents/qa-project-context.md
? If not, creating one is a high-priority onboarding task -- it forces the new person to document what they learn, which benefits the entire team.
Is local environment setup documented? Can a new person run the full stack and execute tests within the first day? If setup takes more than 2 hours, the process needs fixing before onboarding.

是否已有测试框架？ 如果有：框架健康状况如何？如果没有：第一步是选择框架（请查看
```
test-strategy
```
技能）。
项目是否有
.agents/qa-project-context.md
文件？如果没有，创建该文件是入职的高优先级任务——它迫使新成员记录所学内容，惠及整个团队。
本地环境搭建是否有文档说明？ 新成员能否在第一天内运行完整栈并执行测试？如果搭建耗时超过2小时，需在入职前优化流程。

Access and Tooling

权限与工具

Are all required accounts and permissions set up? Repository access, CI dashboard, staging environment, test data accounts, bug tracker, communication channels. Missing access on day one wastes time and creates frustration.

是否已配置所有必需的账户和权限？ 代码库访问权限、CI仪表板、预发布环境、测试数据账户、缺陷跟踪工具、沟通渠道。第一天缺少权限会浪费时间并引发挫败感。

Core Principles

核心原则

1. Time to First Merged Test Is the Success Metric

1. 首次合并测试的时间是衡量入职成功的核心指标

The single most important measure of onboarding success is how quickly the new person gets a real test merged into the main branch. Not a tutorial exercise, not a local-only experiment -- a real test that runs in CI and validates real product behavior. Target: within the first two weeks.

衡量入职成功的唯一最重要标准是新成员将真实测试合并到主分支的速度。不是教程练习，不是仅本地运行的实验——而是能在CI中运行并验证真实产品行为的测试。目标：前两周内完成。

2. Progressive Complexity

2. 渐进式复杂度提升

Start simple, increase difficulty gradually. First test: a smoke test or page-load verification. Second test: a form interaction. Third test: a multi-step user flow. By week three, the new person is writing tests for sprint stories. Throwing someone into the deep end with a complex multi-service flow on day one creates anxiety and bad habits.

从简单开始，逐步增加难度。第一个测试：冒烟测试或页面加载验证。第二个测试：表单交互。第三个测试：多步骤用户流程。到第三周，新成员开始为迭代需求编写测试。第一天就让新人处理复杂的多服务流程会引发焦虑并养成坏习惯。

3. Document Tribal Knowledge

3. 记录隐性知识

Every time a new person asks a question that is not answered in documentation, that is tribal knowledge escaping. The onboarding process should capture these answers in permanent form -- ideally in

.agents/qa-project-context.md

, the framework walkthrough doc, or code comments. The new person is the best person to write this documentation because they know exactly what was missing.

每当新成员提出文档中未解答的问题，就意味着隐性知识正在流失。入职流程应将这些答案以永久形式记录下来——理想情况下存入

.agents/qa-project-context.md

、框架讲解文档或代码注释。新成员是编写这些文档的最佳人选，因为他们清楚知道缺失了什么。

4. Pair First, Solo Second

4. 先结对，后独立

The first 3 tests should be written in a pair -- the new person driving, an experienced team member navigating. Pairing transfers tacit knowledge (why we do things this way, not just how) and builds confidence faster than reading documentation alone.

前3个测试应通过结对方式完成——新成员操作，资深团队成员指导。结对能传递隐性知识（不仅是怎么做，还有为什么这么做），比单独阅读文档更快建立信心。

5. Make the Easy Path the Right Path

5. 让正确的路径成为最轻松的选择

If the correct way to write a test is harder than the wrong way, people will write tests the wrong way. Ensure that test utilities, fixtures, page objects, and data factories make the recommended patterns the path of least resistance. If a new person has to fight the framework to follow conventions, fix the framework.

Calibrate to your team maturity (set
team_maturity
in
.agents/qa-project-context.md
):
startup — Focus on days 1–10: get one test framework running and one critical path covered. Skip process ceremony until you have a working baseline.

growing — Full 30-day plan: framework selection, CI integration, coverage baseline, team conventions documented.

established — 30-day plan plus: audit existing suite for anti-patterns, propose tooling upgrades, establish metrics baseline, schedule recurring quality reviews.

如果编写正确测试的难度大于错误方式，人们会选择错误方式。确保测试工具、fixture、页面对象和数据工厂让推荐模式成为最省力的路径。如果新成员为遵循约定不得不与框架对抗，就需要优化框架。

根据团队成熟度调整（在
.agents/qa-project-context.md
中设置
team_maturity
）：
初创团队 — 聚焦第1-10天：运行一个测试框架并覆盖一条关键路径。在拥有可行基线前跳过流程仪式。

成长中团队 — 完整的30天计划：框架选择、CI集成、覆盖基线、团队约定文档化。

成熟团队 — 30天计划加上：审计现有套件中的反模式、提议工具升级、建立指标基线、安排定期质量评审。

First 30 Days Checklist

前30天检查清单

Week 1: Environment, Access, and Orientation

第1周：环境、权限与项目介绍

Day 1-2: Setup

Repository cloned and building locally
All environment variables configured (
```
.env.local
```
, test credentials)
Application running locally (frontend + backend + database)
Test suite runs locally and passes (or known failures are documented)
IDE configured with recommended extensions (test runner plugin, linter, formatter)
Access granted: CI dashboard, staging environment, bug tracker, team channels

Day 3-4: Orientation

Read
```
.agents/qa-project-context.md
```
(or create it if it does not exist)
Walk through the test directory structure with a team member
Understand the test pyramid: how many unit, integration, and E2E tests exist
Review the CI pipeline: what runs on PR, what runs nightly, what blocks merge
Identify the top 5 critical user flows (these will be the first testing targets)
Attend one Three Amigos or sprint planning session as an observer
Working with the team's AI assistants: Identify which coding agents the team uses (Claude Code, Codex, Cursor, Gemini CLI, etc.), where their context lives (
```
.agents/qa-project-context.md
```
,
```
CLAUDE.md
```
,
```
AGENTS.md
```
), which prompts/skills are house style, and which tasks the team explicitly does NOT delegate to AI. Produce a short "AI assistants we use, what they're good at, what to never let them do" doc as a Day 4 deliverable. If the team automates Playwright via an agent, note that agent-driven Playwright now has its own
```
@playwright/cli
```
(daemon architecture,
```
playwright-cli
```
commands, token-efficient) — distinct from the
```
npx playwright test
```
runner the framework walkthrough documents.

Day 5: First Small Win

Run a single test in debug/headed mode and understand what it does
Modify one assertion in an existing test, verify it fails as expected, revert
Read 3 existing tests and annotate what each section does (setup, action, assertion)

第1-2天：环境搭建

克隆代码库并在本地构建
配置所有环境变量（
```
.env.local
```
、测试凭证）
在本地运行应用（前端+后端+数据库）
在本地运行测试套件并通过（或记录已知失败项）
配置IDE并安装推荐扩展（测试运行器插件、代码检查器、格式化工具）
获取权限：CI仪表板、预发布环境、缺陷跟踪工具、团队沟通渠道

第3-4天：项目介绍

阅读
```
.agents/qa-project-context.md
```
（如果不存在则创建）
与团队成员一起浏览测试目录结构
理解测试金字塔：单元测试、集成测试和端到端测试的数量分布
查看CI流水线：PR触发的任务、夜间运行的任务、阻止合并的任务
确定前5个关键用户流程（这些将是首批测试目标）
作为观察者参加一次“三 amigos”会议或迭代规划会议
团队AI助手使用指南：确定团队使用的编码Agent（Claude Code、Codex、Cursor、Gemini CLI等），其上下文存储位置（
```
.agents/qa-project-context.md
```
、
```
CLAUDE.md
```
、
```
AGENTS.md
```
），团队通用的提示词/技能，以及团队明确不委托给AI的任务。在第4天交付一份简短文档：“我们使用的AI助手、擅长的工作、绝对不能让它们做的事”。如果团队通过Agent自动化Playwright，请注意Agent驱动的Playwright现在拥有独立的
```
@playwright/cli
```
（守护进程架构、
```
playwright-cli
```
命令、高效令牌）——与框架讲解文档中记录的
```
npx playwright test
```
运行器不同。

第5天：首次小胜利

在调试/有头模式下运行单个测试并理解其功能
修改现有测试中的一个断言，验证其按预期失败，然后还原
阅读3个现有测试并注释每个部分的作用（准备、操作、断言）

Week 2: First Real Test

第2周：编写首个真实测试

Week 3: Sprint Contribution

第3周：参与迭代工作

Pick up a sprint story's QA work (with mentorship)
Write tests covering the story's acceptance criteria
Identify at least one edge case not covered by acceptance criteria
Participate actively in Three Amigos or story refinement (ask questions)
Review one existing PR for test quality (using the PR review checklist from
```
shift-left-testing
```
)

接手一个迭代需求的QA工作（在导师指导下）
编写覆盖需求验收标准的测试
识别至少一个验收标准未覆盖的边缘场景
积极参与“三 amigos”会议或需求细化（提出问题）
使用
```
shift-left-testing
```
中的PR评审清单评审一个现有PR的测试质量

Week 4: Independence Milestones

第4周：独立里程碑

Write and merge a multi-step E2E test without pairing
Participate in bug triage and articulate testing gaps
Contribute to
```
.agents/qa-project-context.md
```
with new learnings
Present test results/findings at sprint review or team standup
Self-assess: which test patterns feel comfortable? Which need more practice?

无需结对即可编写并合并一个多步骤端到端测试
参与缺陷分类并阐述测试缺口
将新学习内容补充到
```
.agents/qa-project-context.md
```
中
在迭代评审或团队站会上展示测试结果/发现
自我评估：哪些测试模式已熟练掌握？哪些需要更多练习？

Test Architecture Audit

测试架构审计

When joining an existing project, assess the health of the test suite before writing new tests. This audit takes 2-4 hours and produces a clear picture of the current state.

Scope the audit by
team_maturity
(from

.agents/qa-project-context.md

) — a one-size-fits-all audit wastes a startup's time and underserves an established team:

startup — Skip the full audit. Confirm one path is covered and one framework runs; spend the saved hours getting a first test merged.
growing — Run all five dimensions once to establish a baseline; defer recurring reviews.
established — Full five-dimension audit plus recurring quality reviews on a schedule (e.g. monthly), with the findings doc tracked over time.

加入现有项目时，在编写新测试前评估测试套件的健康状况。本次审计耗时2-4小时，可清晰呈现当前状态。

根据
team_maturity
划分审计范围（来自

.agents/qa-project-context.md

）——一刀切的审计会浪费初创团队的时间，也无法满足成熟团队的需求：

初创团队 — 跳过完整审计。确认一条路径已覆盖且一个框架可运行；将节省的时间用于合并首个测试。
成长中团队 — 运行全部五个维度的审计以建立基线；暂不安排定期评审。
成熟团队 — 完整的五维度审计加上定期质量评审（例如每月一次），并跟踪发现文档的变化。

What to Assess

审计维度

Assess five dimensions, each with a fill-in worksheet:

Coverage and Distribution — test counts by layer, pyramid shape, code coverage and trend.
Reliability — flaky test rate, top flakiest tests, quarantine count and age.
CI Health — full suite and per-stage duration, parallelism, pass rate, retry rate.
Technical Debt — skipped tests,
```
waitForTimeout
```
/
```
force: true
```
usage, hardcoded data, assertionless tests, deprecated APIs, stale AI-generated tests, stale feature flags.
Conventions — page objects, fixtures, factories, naming, shared utilities, tagging.

See

references/audit-worksheets.md

for the copy-and-fill worksheets covering all five dimensions.

评估五个维度，每个维度都有可填写的工作表：

覆盖范围与分布 — 各层级测试数量、测试金字塔形状、代码覆盖率及趋势。
可靠性 — 不稳定测试率、最不稳定的测试、隔离测试数量及存在时长。
CI健康状况 — 完整套件及各阶段运行时长、并行度、通过率、重试率。
技术债务 — 跳过的测试、
```
waitForTimeout
```
/
```
force: true
```
的使用、硬编码数据、无断言测试、废弃API、过时AI生成测试、过时功能标志。
约定规范 — 页面对象、fixture、工厂、命名规则、共享工具、标签体系。

请查看

references/audit-worksheets.md

获取涵盖所有五个维度的可复制填写工作表。

Audit Output

审计输出

Produce a short document (1-2 pages) summarizing findings, categorized as:

Strengths: What the existing suite does well (preserve and learn from these)
Gaps: Missing coverage areas, undertested critical paths
Risks: Flaky tests, stale quarantines, declining coverage
Quick Wins: Improvements achievable in 1-2 sprints (fix flaky tests, add missing happy-path coverage)
Strategic Work: Improvements requiring sustained investment (refactor test architecture, add integration layer)

生成一份简短文档（1-2页）总结发现，分为以下类别：

优势：现有套件的优秀之处（保留并学习）
缺口：缺失的覆盖区域、测试不足的关键路径
风险：不稳定测试、过时隔离测试、覆盖率下降
快速改进项：1-2个迭代内可完成的改进（修复不稳定测试、补充缺失的正常路径覆盖）
战略性工作：需要持续投入的改进（重构测试架构、增加集成层）

Framework Walkthrough Template

框架讲解模板

Create this document for your project. It is the primary reference for anyone writing tests. It has six sections:

Architecture Overview — framework, language, config location, and the annotated directory tree.
How to Run Tests — the full set of run commands (all tests, single file, grep, headed, debug, UI mode, per-browser, report).
How to Write a New Test (Step by Step) — the six-step location/reuse/write/run/PR flow plus the Arrange-Act-Assert test template.
How to Debug Failures — local vs CI failure playbooks and common failure-pattern decoder.
Common Patterns and Conventions — project-specific examples for auth fixtures, data factories, assertion specificity, and selector priority.
Where to Find Help — the routing table for questions about patterns, failures, product behavior, and docs.

See

references/framework-walkthrough.md

for the full template with all code blocks, directory trees, and command lists to copy and adapt.

为你的项目创建此文档。它是所有测试编写人员的主要参考资料。包含六个部分：

架构概述 — 框架、语言、配置位置及带注释的目录树。
测试运行方法 — 完整的运行命令集（所有测试、单个文件、grep过滤、有头模式、调试、UI模式、按浏览器运行、报告）。
编写新测试的步骤 — 定位/复用/编写/运行/PR的六步流程，以及Arrange-Act-Assert测试模板。
故障调试方法 — 本地与CI故障排查指南及常见故障模式解析。
常见模式与约定 — 项目专属的示例，包括认证fixture、数据工厂、断言精准度、选择器优先级。
求助渠道 — 关于模式、故障、产品行为及文档问题的咨询路由表。

请查看

references/framework-walkthrough.md

获取完整模板，包含所有代码块、目录树和命令列表，可直接复制并适配。

Codebase Orientation Guide

代码库介绍指南

Walk through these areas with the new person in a 60-90 minute session.

在60-90分钟的会议中，带领新成员浏览以下内容。

Test Directory Structure Tour

测试目录结构讲解

Walk through the actual directory tree, explaining:

Why tests are organized this way (by feature, not by type)
Where to find page objects for each product area
Where shared utilities live and what they do
Where test data and fixtures are defined
Where CI configuration lives

浏览实际目录树，解释：

测试按功能而非类型组织的原因
各产品区域的页面对象位置
共享工具的位置及功能
测试数据和fixture的定义位置
CI配置的位置

Shared Utilities Inventory

共享工具清单

Utility	Location	Purpose	Example
Auth fixture	`fixtures/auth.fixture.ts`	Provides authenticated sessions	`{ adminPage, userPage }`
Data factory	`helpers/factories.ts`	Creates test data via API	`createTestUser({ role: 'editor' })`
API client	`helpers/api-client.ts`	Direct API calls for setup/teardown	`apiClient.delete('/users/' + id)`
Accessibility helper	`helpers/a11y.ts`	axe-core wrapper	`checkAccessibility(page, testInfo)`
Assertions	`helpers/assertions.ts`	Custom matchers	`toHaveToast('Saved')`

工具	位置	用途	示例
认证fixture	`fixtures/auth.fixture.ts`	提供已认证会话	`{ adminPage, userPage }`
数据工厂	`helpers/factories.ts`	通过API创建测试数据	`createTestUser({ role: 'editor' })`
API客户端	`helpers/api-client.ts`	用于准备/清理的直接API调用	`apiClient.delete('/users/' + id)`
无障碍助手	`helpers/a11y.ts`	axe-core封装工具	`checkAccessibility(page, testInfo)`
断言工具	`helpers/assertions.ts`	自定义匹配器	`toHaveToast('Saved')`

Page Objects Walk-Through

页面对象讲解

Show the existing page objects and explain:

Base page class and its contract (abstract
```
path
```
,
```
waitForReady
```
)
How component objects compose with page objects
Naming conventions (file name matches route:
```
checkout.page.ts
```
for
```
/checkout
```
)
How to add a new page object (copy-modify pattern from the simplest existing one)

展示现有页面对象并解释：

基础页类及其契约（抽象
```
path
```
、
```
waitForReady
```
）
组件对象如何与页面对象组合
命名约定（文件名与路由匹配：
```
checkout.page.ts
```
对应
```
/checkout
```
）
如何添加新页面对象（复制修改最简单的现有对象）

CI Pipeline Walk-Through

CI流水线讲解

Open the CI configuration and trace through:

What triggers the pipeline (push, PR, schedule)
What stages run and in what order
Where test artifacts go (reports, traces, screenshots)
How to find and interpret a failed test in CI
How to re-run a failed job

打开CI配置并梳理：

触发流水线的条件（推送、PR、定时任务）
运行的阶段及顺序
测试产物的存储位置（报告、跟踪记录、截图）
如何在CI中查找并解读失败测试
如何重新运行失败任务

Mentorship Patterns

导师指导模式

Pair on First 3 Tests

前3个测试结对完成

The experienced team member sits with the new person for their first three tests:

Test 1: Navigator/Driver. Experienced person explains the approach and makes key decisions. New person types and asks "why?" at each step. Goal: understand the workflow.
Test 2: Co-pilots. Both contribute equally. New person makes more decisions, experienced person fills gaps. Goal: build confidence.
Test 3: Observer. New person drives entirely. Experienced person observes and gives feedback only when asked or when the approach would cause problems. Goal: independence.

资深团队成员与新成员一起完成前3个测试：

测试1：指导者/操作者。资深成员解释方法并做出关键决策。新成员操作并在每个步骤询问“为什么”。目标：理解工作流程。
测试2：协作模式。双方平等贡献。新成员做出更多决策，资深成员填补空白。目标：建立信心。
测试3：观察者模式。新成员独立操作。资深成员仅在被询问或方法可能引发问题时提供反馈。目标：培养独立性。

Review All PRs for First 2 Weeks

前两周评审所有PR

Every PR from the new person gets a thorough, supportive review for the first two weeks. Not just "LGTM" -- specific feedback on:

Pattern adherence (are they using page objects correctly?)
Selector strategy (are they using stable locators?)
Assertion quality (are assertions specific enough?)
Test isolation (any shared state risks?)
Naming (does the test name describe behavior?)

After two weeks, reduce to standard review depth.

前两周内，新成员的每个PR都需得到全面且支持性的评审。不只是“LGTM”——需提供具体反馈：

模式遵循情况（是否正确使用页面对象？）
选择器策略（是否使用稳定定位器？）
断言质量（断言是否足够精准？）
测试隔离性（是否存在共享状态风险？）
命名规范（测试名称是否描述行为？）

两周后，降低至标准评审深度。

Testing Buddy System

测试伙伴制度

Assign a testing buddy -- a specific person the new team member can ask any question without hesitation. The buddy:

Checks in daily for the first week ("What are you stuck on?")
Is available for ad-hoc questions without scheduling
Reviews all PRs with educational comments (explain the "why")
Introduces the new person to team norms and unwritten rules

为新成员分配一位测试伙伴——新成员可随时向该人员提问，无需顾虑。伙伴需：

第一周每日跟进（“你遇到了什么问题？”）
随时可用，无需预约即可解答临时问题
带着教育性评论评审所有PR（解释“为什么”）
向新成员介绍团队规范和不成文规则

Progressive Responsibility Ramp

渐进式责任提升

Week 1-2:  Write tests for existing, well-understood features (smoke, basic flows)
Week 3-4:  Write tests for current sprint stories (with pairing available)
Week 5-6:  Write tests independently, review others' PRs
Week 7-8:  Contribute to test architecture (new fixtures, utilities, page objects)
Month 3+:  Lead test planning for a feature area, mentor the next new person

第1-2周：  为已充分理解的现有功能编写测试（冒烟测试、基础流程）
第3-4周：  为当前迭代需求编写测试（可请求结对支持）
第5-6周：  独立编写测试，评审他人PR
第7-8周：  参与测试架构建设（新fixture、工具、页面对象）
第3个月及以后：  牵头某功能区域的测试规划，指导下一位新成员

Anti-Patterns

反模式

Sink or Swim Onboarding

放任自流的入职方式

Giving a new person repository access, pointing them at the README, and expecting them to figure it out. This produces weeks of wasted time, bad habits learned from trial and error, and early attrition. Structured onboarding with pairing pays for itself in the first sprint.

给新成员代码库访问权限，指向README后就让他们自行摸索。这会导致数周时间浪费、试错中养成坏习惯，以及早期人员流失。结构化的入职流程加结对指导能在第一个迭代内收回成本。

Tutorial-Only Onboarding

仅教程式入职

Spending two weeks on framework tutorials and toy exercises before touching the real codebase. Tutorials teach syntax; they do not teach project conventions, domain knowledge, or team workflow. Minimize tutorials (1-2 hours max) and move to real tests quickly.

花两周时间学习框架教程和玩具练习，之后才接触真实代码库。教程仅教授语法；无法教授项目约定、领域知识或团队工作流程。尽量减少教程（最多1-2小时），尽快转向真实测试。

No Documentation, All Tribal Knowledge

无文档，全靠隐性知识

When the answer to every question is "ask Sarah," the team has a bus factor of one and onboarding depends entirely on Sarah's availability. Document conventions in

.agents/qa-project-context.md

and the framework walkthrough. If something is important enough to explain verbally, it is important enough to write down.

每个问题的答案都是“问Sarah”，团队的关键人员风险为1，入职完全依赖Sarah的可用性。将约定记录在

.agents/qa-project-context.md

和框架讲解文档中。如果某件事重要到需要口头解释，就重要到需要写下来。

Perfectionism Paralysis

完美主义瘫痪

Expecting the new person's first test to be perfect. The first test should be functional and following basic conventions. Code quality improves with each PR review cycle. Blocking a first PR on style nits or advanced patterns destroys confidence and delays the first win.

期望新成员的第一个测试完美无缺。第一个测试只需功能正常并遵循基本约定即可。代码质量会在每次PR评审中逐步提升。因风格细节或高级模式阻塞首个PR会打击信心并延迟首次胜利。

Ignoring the Onboarding Experience

忽视入职体验反馈

Not soliciting feedback from the person being onboarded. They experienced the process firsthand and know exactly what was missing, confusing, or wasted time. Conduct a 15-minute feedback session at the end of week 2 and week 4. Use their feedback to improve onboarding for the next person.

不征求入职人员的反馈。他们亲身体验了流程，清楚知道哪些内容缺失、令人困惑或浪费时间。在第2周和第4周结束时进行15分钟的反馈会话。利用他们的反馈优化下一位成员的入职流程。

Copy-Paste Without Understanding

复制粘贴却不理解

The new person copies an existing test, changes the locators and URL, and calls it done. The test works but they do not understand why. Pairing and code review should focus on the "why" behind each pattern. If someone cannot explain why a fixture is structured a certain way, they will misuse it when the context differs.

新成员复制现有测试，修改定位器和URL后就完成了。测试能运行但他们不理解原因。结对和代码评审应聚焦每个模式背后的“为什么”。如果有人无法解释fixture的结构原因，在不同场景下就会误用它。

Verification

验证环节

Prove the artifacts hold before declaring onboarding complete. Cheapest check first.

The first merged test is stable, not lucky. Run it repeated to rule out flakiness, then confirm CI is green.
- ```
npx playwright test <new-test> --repeat-each=3
```
  exits 0 (3 consecutive passes locally)
- The PR's CI check is green on the same test
The audit doc is complete, not a stub. Open the findings doc and confirm all five dimensions (coverage/distribution, reliability, CI health, technical debt, conventions) are filled, and findings are categorized into strengths / gaps / risks / quick wins / strategic work. A startup that scoped out the audit (see
```
team_maturity
```
) records that decision instead.
The context file parses and is populated.
```
.agents/qa-project-context.md
```
exists and carries framework, critical paths, team structure, and risk areas — not a high-level placeholder.

在宣布入职完成前，先验证成果是否有效。先进行成本最低的检查。

首个合并测试稳定可靠，而非侥幸通过。 重复运行以排除不稳定性，然后确认CI运行成功。
- ```
npx playwright test <new-test> --repeat-each=3
```
  返回0（本地连续3次通过）
- PR的CI检查中该测试运行成功
审计文档完整，而非空架子。 打开发现文档，确认所有五个维度（覆盖范围/分布、可靠性、CI健康状况、技术债务、约定规范）已填写，且发现内容已分类为优势/缺口/风险/快速改进项/战略性工作。对于初创团队（
```
team_maturity
```
），需记录跳过审计的决策。
上下文文件可解析且内容完整。
```
.agents/qa-project-context.md
```
存在，且包含框架、关键路径、团队结构和风险区域——而非空泛的占位符。

Done When

完成标志

At least one working test merged to the repo, passing in CI, and stable across 3 local repeats (
```
--repeat-each=3
```
exits 0) — proves the local and pipeline setup end-to-end.
Test architecture audit doc exists with all five dimensions filled and findings categorized (strengths, gaps, risks, quick wins, strategic work) — or, for a startup
```
team_maturity
```
, the doc records the explicit decision to scope it out.
Every Week-1 Day-1/2 setup item has a recorded owner and a target date; blocking items are filed as tracked tickets.
```
.agents/qa-project-context.md
```
exists and is populated with framework, critical paths, team structure, and risk areas (not a placeholder).
Test framework selected with rationale recorded (evaluated alternatives, decision written down) — or marked N/A when inheriting an existing framework.

至少一个可运行的测试合并到代码库，在CI中通过，且本地连续3次运行稳定（
```
--repeat-each=3
```
返回0）——证明本地和流水线端到端搭建完成。
测试架构审计文档存在，所有五个维度已填写且发现内容已分类（优势、缺口、风险、快速改进项、战略性工作）；对于初创团队（
```
team_maturity
```
），文档需记录明确跳过审计的决策。
第1周第1-2天的所有搭建项都已记录负责人和目标日期；阻塞项已提交为跟踪工单。
```
.agents/qa-project-context.md
```
存在且内容完整，包含框架、关键路径、团队结构和风险区域（非占位符）。
已选择测试框架并记录决策依据（评估备选方案、书面记录决策）；如果是接手现有框架则标记为N/A。

Reference Files (in

references/

)

参考文件（位于

references/

目录）

framework-walkthrough.md — The full framework walkthrough template: architecture overview, run commands, new-test step-by-step and template, debug playbooks, conventions, and help routing.
audit-worksheets.md — Copy-and-fill worksheets for the test architecture audit (coverage, reliability, CI health, technical debt, conventions).

framework-walkthrough.md — 完整的框架讲解模板：架构概述、运行命令、编写新测试的步骤及模板、故障排查指南、约定规范、求助路由。
audit-worksheets.md — 测试架构审计的可复制填写工作表（覆盖范围、可靠性、CI健康状况、技术债务、约定规范）。