首次使用 QA 技能前建立项目质量上下文文件…

在项目根目录创建并填充 .agents/qa-project-context.md，记录技术栈、测试框架、CI/CD、环境、质量目标、风险区域、团队与约定，供所有 QA 技能读取。

适用场景

解决思路

1. 先检查 .agents/qa-project-context.md 是否已存在：若存在则读取并跳过所有已填写（无 [方括号] 占位符）的章节。
2. 扫描仓库中的配置文件（见代码库检测表）并展示检测到的值供用户确认，而不是盲目提问。
3. 按章节逐一提问，绝不要一次性问完所有问题，从 Product 章节开始。
4. Product 章节：询问产品名称与一句话描述、产品类型（SaaS、电商、媒体、移动应用、API 服务、内部工具）、生产/预发/开发环境 URL，以及 5–10 个最关键用户旅程（要具体可测，如“买家搜索商品、加入购物车、用 Stripe 结账、收到确认邮件”）。
5. Tech Stack 章节：分别记录前端框架与语言、后端框架/语言/API 风格（REST、GraphQL、tRPC、gRPC）、数据库、缓存层、ORM、托管、CDN、监控；仅在版本影响测试方式时固定版本（如 App Router vs Pages Router）；版本从 package.json 读取而非照抄示例。
6. Test Stack 章节：对 E2E、单元、API、视觉、性能测试分别记录框架名称+版本、配置位置、测试目录；若从配置文件检测到框架则直接填入不再询问；若零测试基础设施则写“None selected yet”并注明默认推荐 Playwright（E2E）与 Vitest（单元）。
7. CI/CD 章节：记录平台、测试运行时机（每次推送、仅 PR、每晚、手动）、分片/并行情况、什么会阻塞部署、保存哪些产物（截图、报告、覆盖率）。
8. Environments 章节：记录环境数量与 URL、预发与生产的接近程度（基础设施、数据形态、第三方集成）、开发环境用 mock 服务还是真实 API。
9. Quality Goals 章节：记录覆盖率目标、flake 容忍度、套件时长预算、已跟踪或想要跟踪的指标；若无目标则按成熟度建议现实目标（早期创业：业务逻辑 60% 单元覆盖、Top 5 关键流程 E2E、flake <2%、单元 <3 分钟、E2E <15 分钟；成长期：80%、所有关键路径、<2%、同上；企业级：90%+、全面+性能预算、<1%、同上），并写成具体数字。
10. Risk Areas 章节：询问哪些部分导致最多生产事故、哪些集成最不稳定（支付、邮件、第三方 API）、哪里变更频繁且覆盖低；用 Impact × Likelihood 评分，用表格记录 Area、Risk Level、Business Impact、Notes，至少 3–4 条，分为 Critical（高影响+高概率，优先测试）、Important（高影响+低概率）、Monitor（低影响+高概率）、Backlog（低影响+低概率）。
11. Team 章节：记录 QA 工程师人数与专长、开发与 QA 比例、方法论（Scrum、Kanban、Shape Up）、QA 何时介入（左移在规格阶段还是开发后）；根据 dev:QA 比例确定自动化归属模型（无 QA：开发负责所有测试；8:1+：开发写测试，QA 专注策略与关键路径；4:1：QA 负责 E2E，开发负责单元；<3:1：专职自动化工程师）。
12. Conventions 章节：记录测试文件命名模式、同目录还是分离、分支策略与 PR 要求、E2E 选择器策略（默认 data-testid，kebab-case，如 data-testid="invoice-create-button"；若用语义/ARIA 选择器则记录具体 token 与权衡）、测试数据策略（工厂、fixture、种子数据库、每测试 API）。
13. 若文件不存在：创建 .agents/ 目录，搭建章节结构，从 Product 开始运行发现问答，填写后写入文件。
14. 若文件存在但有占位符：读取并列出已完成与未完成章节，只询问未完成章节，更新时保留已完成章节不动。
15. 若文件存在且完整：总结当前上下文，询问有何变化（新工具、团队变动、目标调整），只更新差异部分。
16. 完成后：确认文件路径，运行验证命令，并根据上下文建议下一个技能（无 E2E → playwright-automation；无策略 → test-strategy；无单元测试 → unit-testing）。
17. 验证：运行 test -f .agents/qa-project-context.md && ! grep -q '\[.*\]' .agents/qa-project-context.md && echo "context complete: file exists, no placeholders"，退出码 0 表示文件存在且无占位符；再运行 grep -c '^## ' .agents/qa-project-context.md 确认至少 9 个章节标题。
18. Monorepo 处理：将每个前端应用列为独立的 Tech Stack 与 Test Stack 条目，共享 API/后端保持一条；按应用分片 E2E（apps/admin 的变更不应运行 apps/storefront 的 E2E），并在 CI/CD 中注明哪些路径过滤器控制哪个应用的套件；检测提示：turbo.json、pnpm-workspace.yaml、nx.json。

适用边界 · 注意事项

• 不要用于从零端到端启动一个全新项目的 QA——应使用 qa-start（它会把本技能作为第一步调用）。
• 不要在本技能中推荐工具（除零测试基础设施时默认推荐 Playwright + Vitest 这一唯一例外外）——工具选择属于 playwright-automation、unit-testing 等专门技能。
• 不要一次性抛出所有问题，也不要留下 [方括号] 占位符或编造信息（数据库、托管商等必须从配置文件检测后与用户确认）。