qa-project-context

此技能会生成其他所有 QA 技能都会读取的唯一文件。没有它，每项技能都会从头询问“使用什么框架？采用什么 CI？测试放在哪里？”，并给出泛泛的建议。它会在项目根目录生成 `.agents/qa-project-context.md`，记录产品、技术栈、测试栈、CI/CD、环境、质量目标、风险领域、团队和约定。将模板占位符替换为有证据支持的值或明确标注的未知项；无法获取答案，不代表可以凭空编造。

下游技能会使用特定章节：Risk Areas 为 risk-based-testing 和 test-strategy 提供依据；Conventions → Selectors 为 playwright-automation 和 test-reliability 提供依据；Quality Goals 为 qa-metrics 提供依据；Tech Stack 则为所有自动化技能提供依据。认真填写这些章节，库中的其他内容也会因此自动变得更精准。

发现问题

首先，检查 .agents/qa-project-context.md 是否已存在——如果存在，读取它并将现有章节作为背景信息。检查这些内容的来源，以及相关配置是否已更改。扫描代码仓库中的配置文件（参见 Codebase Detection），记录观察到的值及其来源，并且只询问会影响当前工作的缺失信息或冲突信息。 按章节逐一梳理剩余问题，绝不要一次性全部询问。

产品

• 产品叫什么？用一句话说明它的用途。
• 产品属于什么类型？（SaaS、电商、媒体、移动应用、API 服务、内部工具）——产品类型会影响哪些流程最重要。
• 生产、预发布和开发环境的 URL 是什么？
• 最关键的 5–10 个用户旅程是什么？（“如果这里出问题，我们凌晨 2 点就会收到告警。”）这份清单决定了其他所有技能的覆盖优先级。

技术栈

• 前端框架和语言是什么？后端框架、语言和 API 风格是什么（REST、GraphQL、tRPC、gRPC）？
• 使用什么数据库、缓存层和 ORM？托管、CDN 和监控方案是什么？
• 是否为单体仓库？如果是，请分别列出各个应用（参见 Monorepo note）——分片和检测方式会有所不同。

测试栈

• 目前有哪些端到端测试？使用什么框架，配置文件位于何处，测试目录在哪里？单元测试、API 测试、视觉测试和性能测试也采用同样的记录方式。
• 如果检测到测试框架，记录其名称、配置路径，以及从锁文件或已安装的软件包中解析出的版本。将 ^1.62.0 这类清单文件中的约束标记为版本范围，而不是已安装版本。存在配置文件并不能证明测试可以执行。
• 如果完全没有测试基础设施，也可以如实记录；填写“尚未选择”，并注明一个默认建议（参见 Core Principle 3）。

CI/CD

• 使用什么平台？测试何时运行（每次推送、仅 PR、每晚、手动）？是否采用分片或并行执行？
• 哪些条件会阻止部署？保存哪些产物（截图、报告、覆盖率数据）？

环境

• 有多少个环境？各自的 URL 是什么？预发布环境与生产环境有多接近（基础设施、数据形态、第三方集成）？
• 开发环境使用模拟服务还是真实 API？——环境一致性会影响测试可靠性。

质量目标

• 当前的覆盖率目标是什么？对不稳定测试的容忍度如何？测试套件的时长预算是多少？目前跟踪或希望跟踪哪些指标？
• 尚无目标？根据成熟度建议切合实际的目标（参见 Quality Goals 章节）。

风险领域

• 哪些部分导致的生产事故最多？哪些集成最不稳定（支付、电子邮件、第三方 API）？
• 哪些部分变更频繁但覆盖率较低？使用 Impact × Likelihood 为所有项目评分（参见 Risk Areas 章节）。

团队

• QA 工程师有多少人，各自专长是什么？开发人员与 QA 的比例是多少？采用什么方法论（Scrum、Kanban、Shape Up）？
• QA 何时介入（在规格阶段提前介入，还是开发后介入）？——这决定了自动化的所有权模式。

约定

• 测试文件的命名模式是什么？测试与代码放在一起还是分开存放？分支策略和 PR 要求是什么？
• 端到端测试采用什么选择器策略？测试数据采用什么策略（工厂、固定数据、预置数据库、每个测试调用一次 API）？

核心原则

1. 一个文件是整个库的唯一事实来源。 每项技能都应先读取 .agents/qa-project-context.md。将其中的信息重复写入其他文档必然会导致 内容偏差——请在此处记录技术栈、目标和风险，并让其他技能引用这些信息。

2. 记录真实状态，而非期望状态。 如果没有 E2E 测试，请写“尚未选择”， 而不是写成愿望。下游技能会根据实际情况进行处理：缺少测试框架会触发设置建议；虚构一个框架，则会让它们从一开始就建立在错误基础上。

3. 先检测，再询问；只有无从检测时才推荐默认选项。 先读取 package.json、锁文件和配置文件，并注明查到的内容。工具推荐 应由专门技能负责——唯一例外是项目完全没有测试基础设施，此时应在 Test Stack 中注明 Playwright（E2E）和 Vitest（单元测试）为默认选项，并交由 playwright-automation / unit-testing 处理。这是“不要推荐”规则的唯一例外；其他情况下只需记录。

4. 风险领域需要有依据。 risk-based-testing 和 test-strategy 会将其作为输入。 记录已知风险，并将拟议的风险或评分标注为假设。如果没有事件历史、可能性或业务影响方面的信息，请记录这一缺失。不要仅仅为了填满表格，就凭空编造三个风险或精确评分。

代码库检测

在询问技术栈之前，先扫描以下内容。注明检测到的值及其所在文件；找到测试配置时，记录测试框架，以及其版本和执行方式是否已知。

文件	表明
package.json	Node.js 项目——检查 dependencies 中的框架
next.config.*	Next.js
nuxt.config.*	Nuxt/Vue
angular.json	Angular
astro.config.*	Astro
react-router.config.ts	React Router 7 / Remix
requirements.txt / pyproject.toml	Python 项目
go.mod	Go 项目
playwright.config.*	已设置 Playwright → 填写 Test Stack 的 E2E
cypress.config.*	已设置 Cypress → 填写 Test Stack 的 E2E
vitest.config.* / jest.config.*	单元测试框架 → 填写 Test Stack 的 Unit
.github/workflows/	GitHub Actions CI
.gitlab-ci.yml	GitLab CI
Jenkinsfile	Jenkins
docker-compose.*	基于 Docker 的环境
wrangler.*	Cloudflare Workers
vercel.json	Vercel 托管
bun.lock / bun.lockb	Bun 运行时
pnpm-workspace.yaml / turbo.json / nx.json	单体仓库——按单体仓库说明处理
src-tauri/tauri.conf.json	Tauri 桌面应用
.claude/	项目使用 Claude Code 技能/Agent
.claude-plugin/plugin.json	项目发布 Claude Code 插件
AGENTS.md	Codex / 多 Agent 工作流约定

工作流：创建上下文文件

1. 检查是否已有上下文文件。 在项目根目录查找 .agents/qa-project-context.md。
2. 如果不存在： 如有需要，创建 .agents/，搭建各章节的结构，从 Product 开始提问 Discovery Questions，并在信息填写完毕后写入文件。
3. 如果存在占位内容： 读取文件，列出哪些章节已完成、哪些尚未填写；只询问未填写的章节，然后更新文件——已完成的章节保持不变。
4. 如果内容完整： 总结当前上下文，询问有哪些变化（新工具、团队变动、目标调整），并且只更新变更部分。
5. 完成后： 确认文件路径，执行 Verification（见下文），并根据上下文建议下一项技能（没有 E2E → playwright-automation；没有策略 → test-strategy；没有单元测试 → unit-testing）。

有关两个填写完整的文件（SaaS 和多站点出版商）以及单体仓库布局，请参见 references/examples.md。以下是一个简短示例片段：

## Test Stack
### E2E / Integration
- **Framework:** Playwright 1.60
- **Config Location:** playwright.config.ts
- **Test Directory:** tests/e2e/
### Unit / Component
- **Framework:** None selected yet — Vitest recommended (see unit-testing)

各部分填写指南

说明每个部分应包含哪些内容。空白模板位于 qaskills 仓库中的 .agents/qa-project-context.md。

产品。 关键用户流程必须具体且可测试：“买家搜索商品，将商品加入购物车，通过 Stripe 结账，并收到确认邮件”——而不是“用户使用应用”。每项测试技能都会依据此列表确定优先级。建议列出 5–10 项。

技术栈。 分别记录前端、后端、数据库和托管环境。只有在版本会改变测试方式时才注明版本（App Router 和 Pages Router 的差异就很大）。不要仅仅因为示例中写了某个版本就照抄——请从 package.json 中读取。

测试栈。 对每个工具，注明框架名称和版本、配置文件位置以及测试目录。尚未选择基础设施也没问题——写上“尚未选择”，并注明推荐的默认选项（原则 3）。

单体仓库。 将每个前端应用分别作为一项技术栈和测试栈条目列出；共享的 API/后端则作为一项列出。按应用拆分 E2E（修改 apps/admin 不应运行 apps/storefront 的 E2E），并在 CI/CD 中注明哪些路径过滤规则控制哪些应用的测试套件。识别提示：turbo.json / pnpm-workspace.yaml / nx.json。参见 references/examples.md。

CI/CD。 回答其他技能需要了解的问题：哪些情况会阻止部署、反馈速度如何，以及会保留哪些证据。

环境。 说明预发布环境与生产环境有哪些差异——预发布环境使用不同的数据库引擎，意味着即使测试通过，也仍可能在生产环境中失败。

质量目标。 只写具体且可衡量的目标。根据成熟度选择起始目标：

成熟度	单元测试覆盖率	E2E	不稳定率	测试套件时长
初创早期	业务逻辑覆盖率 60%	前 5 个关键流程	<2%	单元测试 <3 分钟，E2E <15 分钟
成长阶段	80%	所有关键路径	<2%	单元测试 <3 分钟，E2E <15 分钟
企业级	90%+	全面覆盖 + 性能预算	<1%	单元测试 <3 分钟，E2E <15 分钟

以数字形式写明目标：“使用 Istanbul 测得的行覆盖率为 80%”“滚动 30 天窗口内的不稳定率 <2%”“使用 4 个分片时，完整 E2E 测试耗时不到 15 分钟”。不要写“我们希望质量出色”。

风险区域。 使用表格，列为“区域”“风险等级”“业务影响”“备注”，并按影响 × 可能性评分：

• 严重（优先测试）： 高影响 + 高可能性（存在已知边界情况的支付流程）。
• 重要： 高影响 + 低可能性（身份验证——一旦出错后果严重，但很少变更）。
• 监控： 低影响 + 高可能性（通知格式——经常出错，但严重程度低）。
• 待办： 低影响 + 低可能性（管理设置——稳定且很少使用）。

至少列出 3 项，不要写模糊的内容（如“所有内容都会出错”）。

团队。 记录实际人数和开发人员与 QA 的比例——这会决定自动化的责任分工模式：

开发人员与 QA 的比例	责任分工模式
单人 / 无 QA（实际上比例无限大）	开发人员负责所有测试。不设手动回归测试套件；采用低门槛的自动化工具（Playwright + Vitest）和 CI 检查。QA“角色”= 策略 + 关键路径 E2E，由开发人员承担。
高（8:1+）	开发人员编写测试；QA 专注于策略、关键路径自动化和探索性测试。
均衡（4:1）	QA 负责 E2E，开发人员负责单元测试，集成测试由双方共同负责。
QA 占比较高（<3:1）	配备专职自动化工程师、全面的回归测试套件，并按计划开展探索性测试。

约定。 尤其要说明选择器策略——playwright-automation 和 test-reliability 会读取这些约定，以生成匹配的选择器。默认使用 data-testid 以确保稳定性（data-testid="invoice-create-button"，采用 kebab-case）。如果团队更倾向于使用语义化/ARIA 选择器来进行无障碍感知测试，请记录具体标记——role="button"、role="heading"、getByRole('link', { name: ... })——以及其中的权衡：ARIA 角色也能验证无障碍性，而且在标记变更时仍能保持稳定，但当文案或角色变更时，其稳定性不如 data-testid，因此应固定 name/level，确保选择器明确无歧义。

反模式

1. 一次性提出所有问题

一口气抛出 30 个问题会让人应接不暇，也只能得到浅显的回答。按章节逐一进行，先从 Product 开始。

2. 在最终文件中留下 [brackets]

如果用户确认没有框架，记录“尚未选择”。如果没有可用证据，记录“未知；未检查”或具体缺少的输入。这些状态并不相同。普通 Markdown 链接、任务复选框和带方括号的选择器都是有效内容；仅凭方括号无法判断它是不是模板占位符。

3. 编造信息

根据清单文件、锁文件和配置文件检测技术栈，并注明来源。不要猜测数据库、托管服务提供商、已安装版本、团队规模或商定的质量目标。

4. 跳过风险领域

即使缺少证据，也要保留此章节。将候选风险标记为提议，将未知分数标记为未知；不要把假设的事故当作项目历史来陈述。

5. 超出零基础设施默认方案推荐工具

此技能用于记录当前状态；工具选择属于 playwright-automation、unit-testing 和其他专用技能的职责。此处唯一的推荐是：完全没有测试基础设施时，采用 Playwright + Vitest 默认方案（原则 3）。

验证

阅读生成的文件，并将各章节与其来源逐一比较。使用 grep 搜索方括号会误判有效的 Markdown 链接和选择器；而统计九个任意标题则可能接受错误的章节。这两种方法都无法证明内容完整或事实准确。

检查下面列出的九个指定章节是否都出现在代码围栏之外，并且包含实质性内容或明确标注为未知。将模板字段与替换后的内容进行比较，同时保留合法的方括号语法。根据锁文件核对框架版本，区分当前状态与建议，并保留检测到的值的来源信息。报告尚未解决的缺口和下一步有用的操作；缺少可选细节并不意味着所有下游技能都无法继续。

完成条件

• .agents/qa-project-context.md 已存在，且其模板字段包含有证据支持的值或明确标注为未知。保留有效的 Markdown 链接和带方括号的选择器。
• 九个章节均已包含：Product、Tech Stack、Test Stack、CI/CD、Environments、Quality Goals、Risk Areas、Team、Conventions。
• Product 列出已知的具体用户流程；如果缺少流程证据，应明确指出。
• Test Stack 区分已配置的框架、清单文件中的版本范围、已解析的版本、观察到的执行情况，以及明确不存在或未知的工具。
• Risk Areas 区分有证据支持的风险与提议，并指出未知分数。
• Quality Goals 区分商定的数值目标与提议或未知的目标。
• Team 包含提供的人员数量和比例，否则明确说明这些信息未知。

相关技能

• qa-start — 从头到尾为全新的项目引导 QA，并将此技能作为第一步调用。尚无 QA 时使用 qa-start；要直接（重新）填充上下文时使用此技能。
• risk-based-testing — 将 Risk Areas 章节转化为按优先级排序的风险矩阵。当问题是“我们应该重点测试哪里？”时，在此技能之后运行。
• test-strategy — 使用 Risk Areas、Quality Goals 和 Team 制定跨多个季度的方向。
• qa-metrics — 跟踪此处定义的 Quality Goals；两者引用相同的目标。
• playwright-automation / unit-testing — 填写 Test Stack 章节后，设置 E2E / 单元测试框架；它们会读取 Conventions 中的选择器和命名策略。
• ci-cd-integration — 配置 CI/CD 章节中所述的流水线。

参考文件（位于 references/ 中）

• examples.md — 两份完整填写的上下文文件（SaaS 和多站点出版商），以及 monorepo 的 Tech/Test Stack 布局。