qakit

qakit

将 AI Agent 刚实现的功能转化为一份 QA 计划：Agent 会运行所有能执行的检查并记录结果，同时留下一小部分手动检查内容，其中包含具体步骤、行内检查点，以及通过／失败／跳过复选框。计划的两部分都以代码实际变更为依据，而非通用检查清单。计划会写入 docs/qa/，方便人工从头到尾执行手动检查并确认功能通过。

人工负责的是 判断：界面看起来是否正确，是否符合设计稿，流程体验是否顺畅，文案是否易读。其他工作都由 Agent 完成。这样做的价值在于，计划严谨且以差异为依据；手动部分之所以简短，是因为机器能确认的内容不会出现在其中。

凡是具有可观察的通过条件，都不应列入人工检查清单：命令的输出、端点的响应、返回值，以及在有浏览器驱动时页面显示的内容（数字显示为 7、点击后跳转到 /account/orders/、搜索框不存在、宽度为 375 px 时没有溢出）。Agent 会自行执行这些检查，并在计划末尾的 自动化验证 部分报告结果，让人工无需手动重跑，就能看到检查已通过。Agent 还会为人工需要判断的每个屏幕截取屏幕截图，因此手动检查的大部分工作就是查看图片。

计划围绕设置组织，而非围绕不同维度。设置决定了手动 QA 检查的实际成本：重新填充数据、登录、让应用进入特定状态。如果五个用例各自重复相同的设置，导致测试人员要重建五次状态，这样的计划就不如用例更少、内容更完整的计划。

适用场景

用户完成某项功能后，希望手动验证，例如：“写一份 QA 计划”“手动测试计划”“如何测试这个功能”“给我一份测试清单”“/qakit”，或在编码会话后只说一句“QA 一下”。qakit 会生成一份由人工执行手动用例的计划。它不会编写测试代码。它会运行项目现有的测试、lint 和构建命令，并且只将运行中的应用用于可由 Agent 验证的浏览器检查，因此人工无需重复执行机器能够确认的检查（参见自行运行自动化检查）。如果用户想要新增自动化测试（单元、集成、E2E），请说明并停止，不要生成手动计划：新工作的测试应由 implementkit 在 TDD 模式下编写，而完全没有测试的代码库应使用 testkit。如果没有这些工具包，请明确说明常规做法：在变更旁边编写测试。

流程

1. 界定功能范围

根据实际构建的内容制定计划，否则通用计划毫无价值。按以下优先顺序收集信息：

• 会话上下文，即用户的要求，以及你在本次会话中实现的内容。如果功能是你亲自构建的，这是最佳信息来源，而且无需额外成本：相比差异内容，你更了解它的入口和失效模式。
• 更改内容，如果存在仓库：使用 git diff --stat HEAD 和 git log --oneline -10 查看涉及的文件和提交。QA 计划应以行为（端点、屏幕、标志、命令、状态）为单位编写，而不是以代码行为单位；因此，只需阅读那些涉及你尚无法明确说明其行为的文件的完整差异：路由或处理程序、表单、CLI 入口点、迁移、配置默认值。完全跳过锁文件、构建输出和供应商目录；如果会话上下文已告知某个文件的行为，就不要阅读该文件的完整差异。
• 用户，仅当意图仍不明确时才询问。用一个聚焦的问题询问该功能应该实现什么，以及他们通常如何使用它（URL、命令、屏幕、凭据），不要把对话变成访谈。

在心中记下：功能预期行为、入口点和依赖项（服务、数据、身份验证、配置）。后续所有工作都以此为基础。

同时记录被测版本：git rev-parse HEAD，以及 git status --porcelain 是否为空。计划头部标记和每项复用的检查结果都与这两者绑定。

差异涉及数据层（迁移、架构文件、模型或查询）→ 阅读 db.md，然后在其中指定的每个步骤中按要求操作。

更改会在 UI 中呈现数据，且存在驱动程序，或者用户要求尝试破坏某个组件 → 阅读 worst.md，然后在其中指定的每个步骤中按要求操作。

如果更改包含 UI，请按优先级列出浏览器驱动程序：首先是 PATH 中可打开 URL、点击、读取页面并写入屏幕截图的 CLI 驱动程序（探测 command -v playwright-cli），然后是本次会话中的每组浏览器自动化 MCP 工具（主机自带的预览浏览器也算）。亲自运行自动化检查会启动第一个驱动程序；若失败，则继续使用列表中的下一个。没有驱动程序时，页面检查由人工负责，具体如推导测试维度所述。不要安装驱动程序；安装 verifykit 后，其 setup 命令会负责安装。若项目提供 DESIGN.md 断点，则读取其中的视口宽度；否则使用 1440 px 和 375 px。

如果项目声明了一次性目标环境，请找出它：例如某个游乐场应用或本地数据库容器，有文档说明可通过命令销毁并重建，并且项目的 Agent 指令文件或 README 将其标明为临时环境，同时注明重置命令。只有声明过的目标环境，才允许 Agent 在其上验证会更改状态的命令。切勿自行推断：无人声明为临时环境的本地数据库可能存有他人的工作。

满足以下条件即完成此步骤：已记录预期行为、每个入口点、每项依赖和版本对；已确定是否适用 db.md 和 worst.md、可用的浏览器驱动程序，以及项目声明的一次性目标环境（如有）。

2. 推导测试维度

逐一检查以下所有维度，并为适用于该功能的每个维度生成候选测试用例。只有在某个维度确实无关时才跳过，并在计划的未覆盖部分说明原因，让测试人员知道这是经过考虑，而非遗漏：

• 正常流程。 按预期使用功能，端到端走完主要流程。
• 边界与极限。 空输入、最大值／最小值、差一错误的边界、不常见但有效的状态、重复项、Unicode／大负载。适用 worst.md 时，它会为每个渲染字段添加最坏情况的值。
• 负面场景／错误处理。 错误输入、缺失／过期的身份验证、依赖项不可用、网络故障；断言失败时能够妥善处理，提供清晰的消息且不会造成数据损坏。
• 回归。 此更改可能影响的相邻行为（共享组件、先前流程、相邻功能）。
• 安全与权限。 角色／所有权检查、访问其他用户的数据、注入式输入、日志或响应中不泄露机密。
• 数据与状态。 重新加载／重启后数据仍持久保存、幂等性、正确的创建／更新／删除、没有孤立或过时的状态。如果差异涉及数据层，db.md 会添加数据库断言。如果完全没有涉及，则跳过数据库部分，并像其他维度一样在 未覆盖 下说明。
• 并发与时序。 同时执行操作、重复提交、竞争条件、重试、响应缓慢。
• 兼容性。 如果有 UI：目标浏览器／操作系统／设备、响应式／移动端布局、深色模式。
• 无障碍。 如果有 UI，检查键盘导航、焦点顺序、屏幕阅读器标签和对比度。
• 性能。 在实际或大量数据下的响应能力；没有明显的变慢或内存泄漏。
• 易用性／UX。 必须由人判断的体验：文案清晰、默认值合理、操作易于发现、空状态／加载状态有帮助。

优先级：给每个用例标注三个等级之一，并配上表情符号，让测试人员一眼看出紧急程度：

• 🔴 严重。 发布前必须通过；失败会阻止发布。
• 🟡 普通。 应当通过；失败属于实际 Bug，但不会阻止发布。
• 🟢 低。 有则更好、润色或影响较小的边界情况。

不要凑数，因为每种行为一个明确的检查，胜过十个重复检查。根据功能涉及范围和风险调整用例数量。完成此步骤后，你会得到一组未分类的候选用例；下一步将决定哪些用例实际上彼此独立。

区分仅限人工检查和可由 Agent 验证的检查。 生成用例时，为每个检查点安排一项测试：能否将其通过条件写成脚本可评估的断言？ 如果可以，它就属于可由 Agent 验证的检查。这包括命令输出、HTTP 响应、返回值，以及借助浏览器驱动程序可检查的页面内容：文本和图表、点击后的 URL、元素是否存在、链接的 href 和 target、主题等类名或属性、键盘焦点顺序、无障碍名称、控制台错误，以及指定宽度下的水平溢出。如果不可以，它就属于仅限人工检查：屏幕看起来是否正确、是否符合模型图、深色模式下是否易读、操作是否流畅，或文案是否恰当。应用无法观察到的外部效果（WhatsApp 消息是否送达、付款是否结算、邮件是否到达），以及任何需要真实凭据或实体设备的情况，也属于仅限人工检查。没有浏览器驱动程序时，页面检查也属于仅限人工检查。会更改状态的命令（设置、迁移、删除、重置）只有在已声明的一次性目标上才属于可由 Agent 验证的检查；在其他目标上都应由人工检查。

只有仅限人工检查的检查点才会进入计划的测试用例。你自己运行可由 Agent 验证的检查，并在 自动化验证 部分记录结果。绝不要将带有可观察通过条件的检查列为手动步骤。一个用例通常可以拆分：图表和链接交给 Agent 检查，而“布局符合模型图”则由人工检查。UI 计划中的人工检查点通常应不超过 10 个。超过时，请对每个检查点再次应用断言测试。

当每个维度都有候选用例或一行 未覆盖 说明，并且每个候选用例都标注了优先级以及仅限人工检查或可由 Agent 验证时，此步骤即完成。

3. 将用例归入场景

场景是指一次设置、所有可在该设置基础上运行的用例，以及最后的一次重置。根据每个候选用例所需的初始状态对其排序，然后：

• 每种不同的初始状态对应一个场景。 需要相同状态的两个用例始终属于同一场景。测试人员只需设置一次，运行整个场景，然后重置一次。
• 合并共享同一设置和流程的用例。 如果确认三种行为只需走一遍流程，并在过程中查看三项内容，那么这就是一个带有三个检查点的用例，而不是三个各自重复相同六个步骤的用例。通过检查点来隔离失败：未勾选的方框能和失败的用例一样精确地指向某个行为，而且测试人员无需付出额外成本即可到达该检查点。这是合并，而不是迁移，所以合并后的用例有三个检查点，而不是把三个用例各自列出的所有断言都堆叠成一列方框。 编写计划文件 中的检查点规则可以防止压缩后的内容只是在下一级重新出现。
• 仅在流程确实分歧时拆分，也就是入口点不同，或某个用例留下的状态无法被后续用例接受。
• 场景内按顺序排列：先只读，再修改状态，最后执行破坏性操作。 如果某个用例会删除其他用例需要的记录，就将其放在最后，或单独设为一个场景。
• 在仍能覆盖各个维度的前提下，场景数量尽可能少。 新场景必须有理由采用真正不同的初始状态；“感觉像是不同主题”并不充分。

场景名称应描述其初始状态（“全新租户，无数据”“已有 200 个订单的用户”“功能标志已关闭”），而不是主题（“验证”“错误处理”）。名称可以让测试人员判断自己是否已处于正确状态。

在场景内为用例编号：TC-<scenario>.<case>，因此 TC-2.3 表示场景 2 的第三个用例。

当每个人工执行候选用例都恰好属于一个场景，且每个场景都有不同的初始状态时，此步骤即完成。

适用于整个计划的设置不属于场景设置。 分支、构建、基础 URL、凭据、身份验证令牌、功能标志和启动命令只需在顶部的 Environment 中填写一次。每个场景的 Setup 仅包含该场景特有的内容。这样划分可确保设置与需要它的用例关联起来。

4. 编写计划文件

将文件写入 docs/qa/NNNN-qa-<feature-slug>-YYYY-MM-DD.md，使用下一个序号、简短的小写 kebab-case 功能标识，以及计划的 ISO 创建日期（例如 0012-qa-login-throttle-2026-07-23.md）。要获取序号 NNNN，请在当前工作树、git worktree list 列出的所有其他工作树，以及 origin/HEAD（执行 git fetch origin 后运行 git ls-tree --name-only origin/HEAD docs/qa/）中，找出 docs/qa/ 里最高的四位前导序号，再加一；如果没有序号，则从 0001 开始。检查这三处，否则并行工作树可能会使用相同序号。若某个来源不可用（例如没有远程仓库），则跳过该来源；如果没有 git，则仅列出该目录。序号按目录独立计算，且不得重复使用。后续编辑时保持整个文件名不变；需要时在文档内记录更新日期。如果 docs/qa/ 不存在，则创建它。对于同一产物的现有 QA 计划，应就地更新；即使文件没有序号，也要保留其名称。

文件结构如下（下方外围代码围栏使用四个反引号，仅为展示内部的 ```sh 代码块；实际文件使用普通的三个反引号围栏）：

# QA Plan: <Feature name>

_Generated <date> · against `<commit sha>` (<clean or uncommitted changes>) · covers <brief scope>_

## Summary
- What the feature does, in one short sentence.
- What "working" means, in one short sentence.

## Environment
True for the whole plan. Do this once, before Scenario 1.

- Branch / build under test
- Base URL, credentials, and how to obtain any auth token the calls need
- Feature flags / config

Launch with:

```sh
<launch command>
```

- [ ] Environment ready

## Test cases at a glance

Priority legend: 🔴 Critical · 🟡 Normal · 🟢 Low

| # | Scenario | Test case | Priority |
|------|----------|-----------|----------|
| TC-1.1 | 1: <starting state> | <short title> | 🔴 Critical |
| TC-1.2 | 1: <starting state> | <short title> | 🟡 Normal |
| TC-2.1 | 2: <starting state> | <short title> | 🟢 Low |

## Scenario 1: <starting state>

**Setup.** Run once, for every case in this scenario.

1. <setup action>

```sh
<setup command>
```

- [ ] Setup complete

### TC-1.1: <short title>  ·  🔴 Critical

**Goal.** <one line: what this case proves>

**Steps**

1. <concrete action a human takes>
   - [ ] <one judgment the tester stops to make right here>
     - <what to look at, when the judgment needs a guide; a plain bullet, not a checkbox>
     - <another thing taken in at the same glance>
     - screenshot: `<path>` <light 1440 px · dark 1440 px · light 375 px, as captured>
   - [ ] <a second judgment, only when it's a genuinely separate look>
2. <next action; a command goes in its own block>

   ```sh
   <command to run>
   ```

   - [ ] <what the output or screen must show>

**Result**

- [ ] Pass
- [ ] Fail
- [ ] Skipped

**Notes.** _what actually happened on a fail; why it was skipped_

### TC-1.2: <short title>  ·  🟡 Normal
...

**Reset.** Run after every case above, before moving to Scenario 2.

```sh
<reset command>
```

## Scenario 2: <starting state>
...

## Automated verification (by AI agent)
_Checks the agent ran itself. No action needed from the tester; listed here for context and sign-off._

Commands run (one per block; chain with `&&` when they must run together):

```sh
<command 1>
```

```sh
<command 2>
```

- ✅ <command 1> → <what the output confirmed>
- ✅ <endpoint / assertion checked> → <result>
- ❌ <anything that failed, with the actual output> _(if any)_

### Browser checks
_Driven with `<driver>` against `<base URL>` at `<revision>`. Screenshots in `<screenshot directory>`._

- ✅ <page> · <what was asserted> → <the observed value>
- ❌ <page> · <what was asserted> → <the observed value, and what was expected>

## Not covered / needs human judgment
- <anything that can't be scripted: visual polish, UX feel, external integrations, timing>
- <dimension deliberately skipped, and why>

## Overall result
_Tick one when you finish the run, or skip the ticks. Report each failure in the agent session or as a PR comment, and the agent records it here._

- [ ] Pass: every case passed
- [ ] Fail: at least one case failed
- [ ] Partial: cases were skipped or not reached

编写良好测试用例的规则：

• 绝不让测试人员抄录你已经知道的信息。 标题戳记包含日期和编写测试计划时所依据的确切提交，因此要自行从 git log 获取并填写这两项，不要留一张空表让人手动复制 SHA。计划只要求测试人员做一项机器无法做出的判断：给出总体结论。如果他们最终使用的构建与戳记中的不同，应将其记入某个用例的 备注，而不是留在每份计划中永远空着的字段里。

• 总体结果放在最后，也就是文件末尾。 测试人员在运行结束时勾选它，而运行会在计划底部结束。把结论框放在顶部，会让他们不得不滚回去查看刚完成的每个用例，因此框就会一直空着。

• 用例正文固定，始终按以下四部分排列： 目标、步骤、结果、备注。不能省略任何一部分，也不能增加第五部分。测试人员应能跳到任意计划中的任意用例，并找到相同的结构。

• 目标用一行说明用例证明什么，而不是用例要做什么：“过期令牌无法访问其他租户的订单”，而不是“测试订单端点”。

• 验证内容放在产生它的步骤下方。 绝不要在用例末尾单独列出预期结果：每个步骤后面立即跟着它自己的 - [ ] 检查项，让测试人员边做边勾选，而不是把五项预期都记在脑中，最后再逐一核对。没有可观察内容的步骤就不需要检查项。

• 每项检查对应一个判断，而不是一条断言。 检查项是测试人员停下来做出判断的一件事，不是功能所断言的一条事实。判断方法是：他们是否可能勾选一个框，而不勾选下一个？ 如果他们扫一眼就会同时确认两项，那就应该合并成一个检查项。细化程度超过测试人员注意力所及，并不能提高精度，只会制造假象：没人会在滚动浏览一次页面时做出七个独立判断，因此七个框最后都会被机械地勾选，然后被当成七项从未真正做出的确认。

• 拆分不同的判断；将同一判断应用于一组内容时则合并。 “页脚的标题、链接、分隔线和版权信息都清晰可辨”只需查看同一处一次，因此用一个检查项。“图标变成了月亮”和“存储现在保存着 dark”需要查看两个位置，因此用两个检查项。判断标准不是有没有“和”，而是测试人员的视线是否需要移动。

• 详细内容放在检查项下方，作为普通的未勾选子列表。 值得具体说明要检查的内容，因为这能让测试人员知道，要留意的是定价表中最容易消失的精选方案，而不只是“检查页面”。但这些内容不值得每项都单独勾选：

  1. Set the state to `light`. Scroll the whole page top to bottom at ≥1280px.
     - [ ] Every block reads correctly, with nothing illegible and nothing invisible on its own background
       - navbar: sticky background opaque; logo, links and control legible
       - hero: heading, sub-copy, both buttons; primary label against the primary fill
       - pricing-table: the toggle in both positions; the featured plan distinguishable; check marks
       - footer: headings, links, separator rule, copyright
  

  即使合并了检查项，失败隔离仍然有效，因为 备注 已经存在，而任何未通过的检查项都需要备注。这种不对称性正是目标：计划通过时执行成本低，只有失败的部分才会增加成本。

• 重复执行只保留一个检查项，并补充任何新内容。 第二个变体重新执行测试人员已经做过的检查时（另一种配色、第二个浏览器、下一个断点、替换后的预设），绝不要再列举相同项目。绝不要写“与 <variant> 中的内容相同”。 一行如果没有自己的观察内容，就只是一个让人手动勾选的循环计数器：

  2. Set the state to `dark`. Scroll the page again.
     - [ ] The same sweep is clean in dark
     - [ ] Nothing is pure-black-on-dark where a muted token was intended
  

• 每个复选框都必须独占一行。 只有当 - [ ] 位于行首时，它才会显示为可点击复选框：若在同一行写 [ ] Pass [ ] Fail，所有预览器都会将其显示为无法交互的纯文本，测试人员只能手动编辑。这同样适用于 Result 的三种结果、每个步骤的检查点，以及 Environment 和 Setup 的复选框：每行一个，没有例外，绝不能为了节省纵向空间而并排放置。

• 描述可观察内容，而非内部状态。 写出测试人员能看到或测量的内容，不要写他们无法检查的状态。

• 每项视觉判断都要关联对应截图。 关于屏幕外观的检查点应附带一个普通的 screenshot: 子项，路径指向自行运行自动化检查中捕获的截图，每个变体各一张。这样，测试人员可以根据图像判断大多数屏幕，只需打开应用检查动效、使用感受和实际交互。若没有运行驱动程序，则省略该子项。

• 具体且可复现。 使用真实值并列出精确步骤，不要只写“测试登录”，而要写“输入 [email protected] / 空密码，然后点击 Sign in”。

• Skipped 是一种正式结果。 Result 应提供 Pass、Fail 和 Skipped，每项各占一行；Notes 应说明原因。若测试人员因环境缺失、依赖不可用或时间不足而无法运行某个案例，该案例必须与无人执行的案例有所区分；如果计划中留下未标注原因的空白，后续读者就无从得知情况。

• 整份计划都使用程序性表达。 测试人员通常会在执行任务时查看计划，而且常常需要争分夺秒，因此计划从 Goal、Setup、Reset、Steps、检查点到 Not covered，都必须使用 ASD-STE100 简明技术英语。每句只包含一条指令。程序性句子不超过 20 个单词，描述性句子不超过 25 个单词。使用主动语态和现在时，并明确指出执行者（写 “the app redirects to /login”，不要写 “a redirect occurs”）。保留冠词。不要使用隐喻、习语或有多种含义的词。优先使用短句和项目符号子列表，避免段落。每个事物都选定一个称呼，并在整份计划中始终使用该称呼：例如，若 Setup 中称其为 cart，后续步骤就不要改称 basket，检查点也不要改称 order。这条规则最费心，却也最有用：如果测试人员必须费力判断两个词是否指同一事物，就会不再信任这两个词。此规则仅适用于单份计划；其他文档可以使用不同的称呼。

• 如实说明遗漏。 在 Not covered 下列出计划无法验证的内容，包括任何有意跳过的维度，不要假装已覆盖。

• 每条命令都必须单独放在一个 ```sh 代码块中。 不要在正文或表格单元格中以内联形式写终端命令，也不要在一个代码块中堆叠多条命令，这样测试人员就能通过预览器的复制按钮一次点击复制一条命令。如果必须连续运行多条命令，则在单个代码块的一行中用 && 串联，这样一次复制粘贴即可运行整个序列。

• 每个 API 端点都必须提供可运行的 curl 命令。 只要某个案例或检查会调用 HTTP 端点，就必须在单独的 ```sh 代码块中提供准确的 curl 命令，而不能只用文字描述请求。明确写出方法、完整 URL（使用本地基础 URL，或使用由 Environment 定义的 $BASE_URL）、所有必需的标头，以及包含真实示例值的具体 JSON 正文；命令必须可直接复制粘贴，不能包含需要测试人员猜测的 <placeholders>。如果检查点涉及状态码，则使用 -i（或 -s -w '\n%{http_code}\n'）。这是 QA 过程中最大的提速方式：测试人员可以直接运行请求，而不必重新拼凑它。

当文件已存在于其序列化路径、每个案例都包含全部四个正文部分，并且每条命令和 curl 都各自位于独立代码块中时，此步骤即告完成。

5. 自行运行自动化检查

交接前，实际运行你在推导测试维度中拆分出的、可由 Agent 验证的检查，也就是终端命令、端点请求和返回值断言，并在计划的自动化验证部分记录每项结果（✅ 通过，并说明输出确认了什么；❌ 失败，并附上实际输出）。对于通过 HTTP 访问的内容，请将实际运行的 curl 命令单独放在 ```sh 代码块中，这样人工执行者无需重新构造请求，就能重跑或调整命令。这是计划中由 Agent 完成而非人工完成的部分。如果没有 shell 或文件系统，请说明，并将该部分留给人工填写。

运行哪些检查，以及原因。 运行项目现有的测试、lint 和构建命令（如果适用，还要运行 db.md 中定义的只读检查），以及下面的浏览器检查。这些都是机器可以确认的检查，因此运行它们可以免去人工执行。不要编写新测试或编辑测试文件；由驱动浏览器执行的检查记录在计划中，而不是测试套件中。

一类绝不运行的命令，以及一类重复使用而不重新运行的命令：

• 绝不运行：任何会销毁或重建状态的命令，例如 *:destroy、*:reset、先拆除再重新搭建的命令、数据库写入或删除命令，或会清除构建产物的 clean 命令。这包括每个场景自己的设置和重置区块：这些内容是写给人工执行者的，Agent 绝不执行。描述它们，但不要执行。你是在为某个环境编写计划，而不是管理环境；重置状态的 QA Agent 可能会清除人工执行者正准备测试的构建。唯一例外是下文所述的已声明可丢弃目标。
• 重复使用：已在当前修订版本上记录为通过的门禁，也就是测试、构建、lint 或验证结果中注明了与你在界定功能范围记录的相同 HEAD SHA 和相同脏状态。记录结果内容、运行时所用的修订版本，以及通过状态；重新运行只会再次得到相同结果，却要付出完整成本，而这也是这一步在流水线中最常变得昂贵的原因。未注明修订版本，或 SHA、脏状态不同的结果，不可重复使用：应运行该门禁。如果被测改动本身就是该门禁，则也要运行。

这两条规则的核心相同：检查现有内容，不要重复生成。 如果需要构建产物来编写合适的用例，请查看现有产物。

在可丢弃目标上运行的场景。 如果界定功能范围中发现了已声明的可丢弃目标，请自行运行设置、步骤和重置都仅涉及该目标的每个场景：

• 先说明目标。 在第一条命令之前，用一行说明目标及其重置命令，以便操作人员能及时叫停。
• 按原样运行场景。 运行设置，然后按顺序运行每个用例的命令，最后运行重置。不要运行任何涉及目标之外内容的命令；一旦有命令会访问其他主机、其他数据库或共享服务，就停止该场景。
• 在用例中记录证据。 勾选已确认的每个检查点，勾选用例的结果，并在其备注中写下真实输出，只保留能够证明检查点的行。将场景标题标记为 · 由 Agent 在 <target> 上于 <revision> 运行。
• 确保目标恢复干净。 如果最后一个场景改动了目标，结束时运行已声明的重置命令，并记录该次运行。

这些场景应保留在计划的用例中，而不是放在自动化验证部分，因为评审人员会直接查看其中的输出记录。目标未声明为可丢弃的命令用例仍由人工执行。

浏览器检查。 使用界定功能范围中提供的浏览器驱动来操作运行中的应用，并在浏览器检查下记录每项页面断言。如果 worst.md 适用，还要在范围内的每个屏幕上运行其模拟、重新加载和断言循环：

• 访问应用。 复用已提供基础 URL 的开发服务器。否则，使用计划中的启动命令启动一次，并在检查结束时将其停止。除非目标已声明为可丢弃目标，否则不要运行 Setup、Reset、seed 或 migration 来达到某种状态。在其他任何目标上，需要执行这些操作的检查都保留为人工检查点。
• 仅操作本地状态。 创建、删除、提交、付款或发送内容的点击操作，都通过应用写入数据。仅在使用示例或演示数据的本地服务器，或已声明为可丢弃的目标上执行这些操作。在其他任何主机上，该检查都保留为人工检查。
• 先断言，再记录观察到的值。 “✅ /account/ · Active orders 卡片 → 7”比“✅ 数值正确”更有证明力。❌ 要记录页面显示的内容以及计划中的预期。
• 截取需要人工检查的屏幕。 对每个需要人工检查的屏幕，在该变更支持的每个变体中各截取一张截图：浅色和深色；对于响应式页面，还要覆盖界定功能范围中列出的每种视口宽度。将截图保存到 ${TMPDIR:-/tmp}/qakit/<plan file name without .md>/ 下，绝不要放在代码仓库内，并在对应检查点中写入每个截图路径。
• 检查结束时关闭浏览器，因为 CLI 驱动程序会让后台浏览器在命令之间保持运行。

驱动程序无法启动时，在 Browser checks 下记录一次错误，然后尝试列表中的下一个驱动程序。所有驱动程序都无法启动时，将页面检查移回人工用例，并在交接说明中列出每个错误。不要更改驱动程序的沙盒或安全设置来使其启动；这由操作人员决定。

❌ 表示发现了人工原本不必发现的缺陷。不要修复它，因为 qakit 不会写入代码。将它放在交接说明的首位。

当推导测试维度中的每项 Agent 可验证检查都有 ✅ 或 ❌ 条目，或有条目注明所复用结果的修订版本；可丢弃目标上的每个场景都有勾选项和输出，且目标已重置；每个人工视觉检查点都有截图或计划说明未提供截图的原因；并且你启动的浏览器或服务器都已停止运行时，本步骤即完成。

6. 交接

本节采用程序性语体撰写：每句一条指令，使用主动语态和现在时，不用比喻。

结尾写成四个简短部分：

• 先列失败项。 如果浏览器检查或自动化检查失败，先列出每个 ❌ 及其观察值。
• 变更内容。 用一行总结：场景和人工检查点的数量（以及其中 🔴 严重项的数量），再加上自动化和浏览器检查结果（例如，“2 个场景，7 个人工检查点，2 个严重项 · 运行了 6 条命令和 41 项浏览器检查，失败 1 项 · Agent 在 playground 上运行了场景 3，之后已重置”）。说明没有标记任何人工用例。告诉人工检查者在当前会话中或以 PR 评论的形式报告失败；是否勾选文件由其自行决定。
• 文件位置。 提供计划路径 docs/qa/<file>、编写该计划时所依据的修订版本，以及截图目录。
• 下一步。 有 ❌ 时，先用 implementkit 修复（否则手动修复），然后再次运行 qakit。没有 ❌ 时，用 prkit 创建 PR，并将 docs/qa/<file> 交给它，以便 PR 的测试计划链接到 QA 计划。没有 prkit 时，运行 gh pr create，并在正文中写入计划路径。

不要自行将任何人工用例标记为已通过，因为这些用例需要人工执行。Agent 仅填写自动化验证部分，以及它在可丢弃目标上运行的场景，不填写其他内容。将任务转交 prkit；不要调用它。

说明

• Shell 的使用范围。 qakit 仅使用 shell 阅读变更并运行项目自身的验证检查：使用 git diff/git log 为计划提供依据，并运行自行运行自动化检查中列出的自动化检查（项目的测试、lint 和构建命令；在本地或已确认的主机上进行只读数据库检查；以及使用浏览器驱动程序访问本地开发服务器）。它运行的每条命令都会回显在计划的自动化验证部分中，因此用户可以确切看到运行了哪些命令。它不会获取远程代码、接触凭据或运行任何破坏性操作，并且只有在门禁结果对应相同修订版本时才会复用该结果；请参阅自行运行自动化检查中的两条命令规则。如果某个验证步骤会修改状态或需要提升权限，应将其描述给人工处理，而不是运行它。
• 计划，而非测试套件。 qakit 的输出是一份 QA 计划，其中填入了自动化检查结果，并将手动测试用例留给人工处理。它不会编写单元、集成或 E2E 测试；它会运行项目已有的测试套件，并为这份计划操作浏览器。
• 浏览器 MCP 不在 allowed-tools 范围内。 Bash 可用于调用 playwright-cli 之类的 CLI 驱动程序。浏览器 MCP 以服务自行选择名称的工具形式提供，因此，严格执行 allowed-tools 的宿主必须授予这些工具，否则 qakit 将在没有驱动程序的情况下运行，并将页面检查留作手动操作。新增自动化测试应由新功能开发使用的 implementkit（TDD 模式）或没有测试的代码库使用的 testkit 负责；如果两者都未安装，应明确列出具体步骤，而不是假设存在某个特定技能。
• 无法访问文件系统或 shell？ 你无法写入文件或读取 diff。此时应请用户粘贴变更或描述功能，然后将完整计划打印为代码块，并附上规范路径 docs/qa/NNNN-qa-<feature-slug>-YYYY-MM-DD.md；如果无法列出用户的 QA 计划，则使用 0001，让用户自行保存。