test

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Output style (plain words, no dashes, no hyphens)

输出风格（平实语言，无破折号、连字符）

Write everything this skill produces, files and messages alike, in plain simple language. Keep technical terms that carry real meaning; explain each in plain words. Never use a dash or a hyphen as punctuation: no em dash, no en dash, and no hyphenated compounds. Write

read only

, not

read-only

. Say it in simple words, or reword the sentence. Code, file paths, command flags, and values other skills match on keep their hyphens. Use short sentences, commas, or parentheses. Clear beats clever.

本技能生成的所有内容（文件和消息）均使用简洁平实的语言书写。保留具有实际意义的技术术语，并以平实语言逐一解释。切勿使用破折号或连字符作为标点：不要使用长破折号、短破折号，也不要使用连字符构成的复合词。写

read only

，不要写

read-only

。用简单的词语表达，或改写句子。代码、文件路径、命令标志以及其他技能匹配的值保留其连字符。使用短句、逗号或括号。清晰胜过巧妙。

What this skill does

本技能的功能

Role: a senior test engineer writing the suite the code deserves, no more, no less. Test what a caller relies on and what would actually break someone, not lines for a coverage number. Pick a strategy per file by reading what the thing is. Refuse tests that lock in scaffolding the slice was never meant to make real.

Target: the code changed in this branch but not yet committed. Each changed file is classified (pure logic, component, API route, page/flow) and tested with the right strategy; tests verify real behavior and catch regressions, not coverage farming. The main thread writes the tests itself (a read only

scout

may do the heavy file reading for a large set); with a governing spec, tests trace to its acceptance criteria (Steps 7 and 8).

Does not write application code. Does not update

AGENTS.md

CLAUDE.md

context files (/sync owns that).

角色：资深测试工程师，为代码编写恰如其分的测试套件，不多不少。测试调用者依赖的内容以及实际会导致故障的点，而非为了覆盖率数字而凑行数。通过分析文件类型为每个文件选择测试策略。拒绝为代码片段中本就不会实际落地的脚手架编写锁定性测试。

目标：当前分支中已修改但未提交的代码。每个变更文件会被分类（纯逻辑、组件、API路由、页面/流程）并采用对应策略测试；测试验证实际行为并捕获回归问题，而非为了提高覆盖率而测试。主线程自行编写测试（若文件数量较多，只读型

scout

子代理可承担繁重的文件读取工作）；基于主规格说明，测试会关联到其验收标准（步骤7和步骤8）。

不编写应用代码。不更新

AGENTS.md

CLAUDE.md

上下文文件（该工作由/sync技能负责）。

Asks vs acts

请求与操作

Acts without asking when
```
test-preferences.json
```
exists, the tool is installed, and uncommitted source files exist: straight to writing.
Always asks one thing every run, even with prefs: run the suite after writing, or hand back manual instructions (Step 7.5). Per run choice, never saved.
Otherwise asks only when: no
```
test-preferences.json
```
(framework; E2E addon only if pages/flows changed); a chosen tool is not installed (confirm first); no uncommitted changes (Step 3); >15 files (Step 1b).
No scope question. The git working tree defines the scope.

当
```
test-preferences.json
```
存在、工具已安装且存在未提交的源文件时，无需询问直接执行：开始编写测试。
每次运行时，即使已有偏好设置，也总会询问一件事：编写完成后是否运行测试套件，还是返回手动执行说明（步骤7.5）。该选择仅针对本次运行，不会保存。
仅在以下情况时才会发起询问：不存在
```
test-preferences.json
```
（询问框架；仅当页面/流程变更时才询问E2E插件）；所选工具未安装（先确认）；无未提交变更（步骤3）；变更文件超过15个（步骤1b）。
不询问范围问题。Git工作区定义了测试范围。

Artifact ownership

产物归属

Test files (
```
*.test.ts
```
,
```
*.spec.ts
```
,
```
test_*.py
```
,
```
*_test.go
```
, etc.), created by this skill
```
test-preferences.json
```
at the project root, created and maintained by this skill

测试文件（
```
*.test.ts
```
、
```
*.spec.ts
```
、
```
test_*.py
```
、
```
*_test.go
```
等），由本技能创建
项目根目录下的
```
test-preferences.json
```
，由本技能创建并维护

Portability (any OS, any agent)

可移植性（支持任意操作系统、任意Agent）

Any Agent Skills client on macOS, Linux, or Windows:

```
git
```
is the only required CLI, identical everywhere; run the
```
git
```
lines as shown. Other shell snippets are POSIX reference, not literal scripts: do not assume
```
find
```
,
```
grep
```
,
```
sed
```
,
```
cat
```
,
```
test
```
/
```
[ ]
```
,
```
xargs
```
,
```
mkdir -p
```
, or
```
node -e
```
exist. Use your agent's cross platform file tools (read, search/glob, write) and apply branching logic yourself, not via shell
```
if
```
/variables/redirects.
Bundled files: referenced relative to this skill's folder. The main thread resolves the folder to an absolute path and reads the bundled files itself at write time (Step 8):
```
agent-prompt.md
```
and
```
writing-guide.md
```
.
No interactive question support? Ask any multiple choice question as plain text with the same options.

In the Ask blocks below, each option is

"label": "description"

; render them through your agent's picker (

AskUserQuestion

on Claude Code) or as plain text.

运行在macOS、Linux或Windows上的任意Agent Skills客户端：

```
git
```
是唯一必需的CLI工具，在所有系统上功能一致；按所示命令执行git指令。其他shell代码片段仅作为POSIX参考，并非字面脚本：不要假设
```
find
```
、
```
grep
```
、
```
sed
```
、
```
cat
```
、
```
test
```
/
```
[ ]
```
、
```
xargs
```
、
```
mkdir -p
```
或
```
node -e
```
已存在。使用Agent的跨平台文件工具（读取、搜索/通配、写入）并自行实现分支逻辑，而非通过shell的
```
if
```
/变量/重定向。
捆绑文件：相对于本技能的目录引用。主线程会在写入时（步骤8）将目录解析为绝对路径并自行读取捆绑文件：
```
agent-prompt.md
```
和
```
writing-guide.md
```
。
不支持交互式问题？将选择题以纯文本形式呈现，保留相同选项即可。

在下方的询问块中，每个选项格式为

"label": "description"

；通过Agent的选择器（Claude Code上的

AskUserQuestion

）或纯文本形式展示。

Execution

执行流程

Pre-flight (main thread)

预检查（主线程）

1. Determine scope from git (do this first, if empty, no point asking anything)

1. 从Git确定测试范围（优先执行，若范围为空则无需询问任何问题）

Changed but uncommitted files (cross platform git):

Tracked (staged + unstaged), excluding deletions:
```
git diff --name-only --diff-filter=ACMR HEAD
```

Untracked, and not ignored:

git ls-files --others --exclude-standard

No commits yet (

git diff HEAD

errors): use

git diff --name-only --diff-filter=ACMR --cached

Combine, remove duplicates, filter out files that cannot be tested:

Test files:

*.test.*

*.spec.*

test_*.py

*_test.go

, anything under

__tests__/

e2e/

tests/

cypress/

Config:
```
*.config.*
```
,
```
.*rc
```
,
```
tsconfig*
```
,
```
*.json
```
(except where logic lives in JSON),
```
Dockerfile
```
, CI yaml
Lock files,
```
.lock
```
, generated/build output (
```
dist/
```
,
```
build/
```
,
```
.next/
```
,
```
coverage/
```
)
Styling:
```
*.css
```
,
```
*.scss
```
,
```
*.module.css
```
; type only declarations:
```
*.d.ts
```
Docs and markdown, specs,
```
design.md
```
,
```
test-preferences.json
```

The remainder is the scope. Empty: go to Step 3. Otherwise continue.

已修改但未提交的文件（跨平台git命令）：

已跟踪文件（已暂存+未暂存），排除已删除文件：
```
git diff --name-only --diff-filter=ACMR HEAD
```

未跟踪且未被忽略的文件：

git ls-files --others --exclude-standard

尚无提交记录（

git diff HEAD

报错）：使用

git diff --name-only --diff-filter=ACMR --cached

。

合并结果，去除重复项，过滤无法测试的文件：

测试文件：

*.test.*

、

*.spec.*

、

test_*.py

、

*_test.go

、

__tests__/

、

e2e/

、

tests/

、

cypress/

下的所有文件

配置文件：
```
*.config.*
```
、
```
.*rc
```
、
```
tsconfig*
```
、
```
*.json
```
（除非JSON中包含逻辑）、
```
Dockerfile
```
、CI yaml文件
锁定文件、
```
.lock
```
、生成/构建输出文件（
```
dist/
```
、
```
build/
```
、
```
.next/
```
、
```
coverage/
```
）
样式文件：
```
*.css
```
、
```
*.scss
```
、
```
*.module.css
```
；仅类型声明文件：
```
*.d.ts
```
文档和markdown文件、规格说明、
```
design.md
```
、
```
test-preferences.json
```

剩余文件即为测试范围。若范围为空：跳转至步骤3。否则继续执行。

1b. Classify each scoped file

1b. 对每个范围内的文件进行分类

Classify from path and filename alone, cheaply; if genuinely ambiguous, tag

logic

and tag it again when you read the file at write time. Record each file's class for the write step.

Signals in path / filename	Class	Test strategy
`.tsx` / `.jsx` / `.vue` / `.svelte` not under a route/page path	component	Component test (render + interact + assert DOM/ARIA)
`app/*/page.` , `pages/*` (not `pages/api` ), `Screen.` , `View.*`	page/flow	E2E candidate + component test of pieces
`app/*/route.` , `pages/api/*` , `.controller.` , `.handler.` , `.resolver.` , `actions.`	api/server	Integration test (call handler, mock at boundary)
Plain `.ts` / `.js` / `.py` / `.go` / `.rs` , utils, hooks, services, domain logic	logic	Unit test (inputs → outputs, edge cases, errors)
`cli.` , `bin/` , `.command.` , `cmd/*`	cli	Integration test invoking the command

E2E_RELEVANT = yes

if any file is page/flow; otherwise

no

Large diff guard: more than 15 source files, don't try to write them all in one pass. Prioritise by class (logic and api/server first, most risk, cheapest to test well) and ask:

Ask: "<N> changed files is a lot for one pass. How should I focus?"  (header: "Scope size")
- "Logic & API first (recommended)": "Test the <count> logic/api files now; I'll note the rest as not-yet-covered"
- "Test everything in batches": "Cover all <N> files across multiple passes, slower but complete"
- "Let me narrow it": "I'll tell you which files or directory matter most"

Monorepo resolution: find each scoped file's nearest enclosing

package.json

(walk up). Different roots: group by root (own framework, package manager, test dir; install and write per group). One shared root (common case): single project. Record each file's

packageRoot

for the write step.

仅通过路径和文件名快速分类；若确实存在歧义，先标记为

logic

，在写入时读取文件后重新标记。记录每个文件的分类，供写入步骤使用。

路径/文件名中的特征	分类	测试策略
`.tsx` / `.jsx` / `.vue` / `.svelte` 且不在路由/页面路径下	component（组件）	组件测试（渲染+交互+断言DOM/ARIA）
`app/*/page.` 、 `pages/*` （不含 `pages/api` ）、 `Screen.` 、 `View.*`	page/flow（页面/流程）	E2E测试候选+组件拆分测试
`app/*/route.` 、 `pages/api/*` 、 `.controller.` 、 `.handler.` 、 `.resolver.` 、 `actions.`	api/server（API/服务端）	集成测试（调用处理器，在边界处模拟）
纯 `.ts` / `.js` / `.py` / `.go` / `.rs` 文件、工具类、钩子、服务、领域逻辑	logic（逻辑）	单元测试（输入→输出、边界情况、错误处理）
`cli.` 、 `bin/` 、 `.command.` 、 `cmd/*`	cli（命令行工具）	集成测试（调用命令）

若存在任何page/flow类型的文件，则

E2E_RELEVANT = yes

；否则为

no

。

大差异防护：若源文件超过15个，不要尝试一次性全部编写测试。按分类优先级（逻辑和api/server优先，风险最高且测试成本最低）询问：

询问："<N>个变更文件数量较多，是否需要调整测试重点？" （标题："范围大小"）
- "优先测试逻辑与API（推荐）": "现在测试<count>个逻辑/API文件；其余文件会标记为暂未覆盖"
- "分批测试所有文件": "分多次完成所有<N>个文件的测试，速度较慢但覆盖全面"
- "我来缩小范围": "我会告知你哪些文件或目录最重要"

单体仓库处理：找到每个范围内文件最近的父级

package.json

（向上遍历）。不同根目录：按根目录分组（各自的框架、包管理器、测试目录；按分组安装和编写测试）。单一共享根目录（常见情况）：视为单个项目。记录每个文件的

packageRoot

，供写入步骤使用。

2. Load preferences

2. 加载偏好设置

Read

test-preferences.json

at the project root (file tool; "not found" = no prefs). Branch on whether it names a

tool

, not on whether the file exists:

tool
is set (the common write path): load

tool

additionalTools

e2eTool

testDir

filePattern

packageManager

; skip to Step 5.

tool
is
null
and
gate
is set (
```
GATE_ONLY
```
): this project gates without a test runner, by an earlier deliberate choice. Do not write a suite, do not install a runner, do not ask again, and do not read
```
modes/setup.md
```
. Run the project's typecheck/lint gate, then stop and report: "This project gates on
```
<gate>
```
, not a test suite. Ran the typecheck gate; use
```
/check verify
```
to confirm behavior."
No file (
```
NO_PREFS
```
, first run): read
```
modes/setup.md
```
and do its Step 4 (stack detection and framework questions), then return here for Step 5 (installation check), then do its Step 6 (save preferences), then continue at Step 7. Do not read
```
modes/setup.md
```
on a write run.
Malformed (a file with neither
```
tool
```
nor
```
gate
```
, or unparseable JSON): say so, then treat it as
```
NO_PREFS
```
and run setup again, which overwrites it.

读取项目根目录下的

test-preferences.json

（通过文件工具；"未找到"表示无偏好设置）。根据是否指定了

tool

分支处理，而非根据文件是否存在：

已设置
tool
（常见写入路径）：加载
```
tool
```
、
```
additionalTools
```
、
```
e2eTool
```
、
```
testDir
```
、
```
filePattern
```
、
```
packageManager
```
；跳转至步骤5。
tool
为
null
且已设置
gate
（
```
GATE_ONLY
```
模式）：该项目通过早期的明确选择，无需测试运行器即可进行门禁检查。不要编写测试套件，不要安装运行器，不要再询问，也不要读取
```
modes/setup.md
```
。运行项目的类型检查/代码门禁，然后停止并报告："该项目采用
```
<gate>
```
作为门禁检查，而非测试套件。已运行类型检查门禁；使用/check verify确认行为。"
无文件（
```
NO_PREFS
```
，首次运行）：读取
```
modes/setup.md
```
并执行其步骤4（栈检测和框架询问），然后返回此处执行步骤5（安装检查），接着执行其步骤6（保存偏好设置），之后继续执行步骤7。写入运行时不要读取
```
modes/setup.md
```
。
格式错误（文件中既无
```
tool
```
也无
```
gate
```
，或JSON无法解析）：告知用户，然后视为
```
NO_PREFS
```
并重新运行设置流程，设置流程会覆盖该文件。

3. No uncommitted changes

3. 无未提交变更

Empty scope: skip the framework questions, tell the engineer, offer fallbacks:

Ask: "No uncommitted source changes found. What should I test?"  (header: "No changes")
- "The last commit": "Diff HEAD~1..HEAD and test what that commit changed"
- "Specific files": "I'll test the files or directory you name"
- "Nothing right now": "Stop. I'll run /test after I make changes"

Last commit: scope =

git diff --name-only --diff-filter=ACMR HEAD~1 HEAD

, run Step 1b again.

Specific files: classify the named files, continue.
Nothing: stop cleanly.

范围为空：跳过框架询问，告知工程师并提供备选方案：

询问："未找到未提交的源文件变更。需要测试什么内容？" （标题："无变更"）
- "最后一次提交": "对比HEAD~1..HEAD并测试该提交的变更内容"
- "特定文件": "我会测试你指定的文件或目录"
- "暂时不测试": "停止操作。我会在做出变更后运行/test"

最后一次提交：范围 =
```
git diff --name-only --diff-filter=ACMR HEAD~1 HEAD
```
，重新执行步骤1b。
特定文件：对指定文件进行分类，继续执行。
暂时不测试：干净地停止操作。

5. Installation check

5. 安装检查

Check the chosen unit tool, E2E tool (if any), and addon (if any) with file tools:

JS/TS: under
```
node_modules/<pkg>
```
, or in
```
package.json
```
devDependencies?

Python: in

pyproject.toml

requirements.txt

(or

pip show <tool>

where Python is available)?

Go:
```
stretchr/testify
```
in
```
go.sum
```
?

All present → Step 6. Any missing → confirm first:

Ask: "<missing tools> not installed. Install now?"  (header: "Install")
- "Yes, install and continue": "Run the install with the detected package manager, then write tests"
- "No, write runnable stubs": "Skip install; write tests I can run once I install the tools myself"

Yes: install with the project's package manager (

pnpm

shown; substitute the detected npm/yarn/bun, or the language's manager for Python/Go):

bash

pnpm add -D vitest                                            # unit
pnpm add -D @testing-library/react @testing-library/user-event @testing-library/jest-dom  # addon
pnpm add -D @playwright/test && pnpm exec playwright install  # E2E (Playwright)
pnpm add -D cypress                                          # E2E (Cypress)
pip install pytest pytest-mock                                # Python
go get github.com/stretchr/testify                           # Go

"No": record

INSTALL=deferred

; write complete tests anyway, the run command is reported as "run after installing".

通过文件工具检查所选的单元测试工具、E2E工具（若有）和插件（若有）：

JS/TS：是否在
```
node_modules/<pkg>
```
下，或是否在
```
package.json
```
的devDependencies中？
Python：是否在
```
pyproject.toml
```
/
```
requirements.txt
```
中（或在Python可用时执行
```
pip show <tool>
```
）？
Go：
```
go.sum
```
中是否包含
```
stretchr/testify
```
？

所有工具均已安装 → 步骤6。存在缺失工具 → 先确认：

询问："<缺失的工具>未安装。是否现在安装？" （标题："安装"）
- "是，安装并继续": "使用检测到的包管理器执行安装，然后编写测试"
- "否，编写可运行的存根": "跳过安装；编写测试，待我自行安装工具后即可运行"

选择"是"：使用项目的包管理器安装（示例为pnpm；替换为检测到的npm/yarn/bun，或Python/Go对应的语言包管理器）：

bash

pnpm add -D vitest                                            # 单元测试
pnpm add -D @testing-library/react @testing-library/user-event @testing-library/jest-dom  # 插件
pnpm add -D @playwright/test && pnpm exec playwright install  # E2E测试（Playwright）
pnpm add -D cypress                                          # E2E测试（Cypress）
pip install pytest pytest-mock                                # Python
go get github.com/stretchr/testify                           # Go

选择"否"：记录

INSTALL=deferred

；仍编写完整测试，运行命令会标注为"安装后运行"。

7. Gather lightweight pointers (do NOT read heavy files here)

7. 收集轻量级指针（此处不要读取大文件）

Paths and cheap signals only; the heavy reading happens at write time (by you, or a

scout

if offloaded). Do not read specs or

design.md

in full here. Don't read source files here; they're read at write time.

With file tools:

List the 3 most recently modified spec paths under
```
docs/specs/
```
(paths only).
Identify the governing spec: the feature dir
```
docs/specs/NNNN-<feature>/
```
(or single
```
docs/specs/NNNN-<feature>.md
```
) these files implement, matched by branch/feature name or touched surfaces (a
```
docs/scope/
```
entry, if present, points to it). Note its path and whether a
```
verify.md
```
sits beside it (
```
docs/specs/NNNN-<feature>/verify.md
```
). This contract is what tests trace to; it may not be among the 3 recent paths. Set
```
TRACE_TO_CONTRACT = yes
```
when a governing spec exists, else
```
no
```
.
Note whether
```
design.md
```
exists at the project root; use its path only when a component or page/flow file is in scope, else
```
none
```
.
Read
```
AGENTS.md
```
(canonical;
```
CLAUDE.md
```
if absent) as project context (short and cheap). Also note the build approach as one line: the slice shaping approach the team chose, recorded in the scope header (or root
```
AGENTS.md
```
), e.g. thin end to end path, thinnest usable whole core loop, UI first shell on placeholders, full user journey per phase. It doesn't branch the logic; it calibrates your judgment when writing (Step 8, rule a).

Read

package.json

, note

scripts.test

RUN_COMMAND

<pkgmgr> test

when a

test

script exists (

<pkgmgr> run test

for npm); a raw invocation (e.g.

pnpm exec vitest run

) only when none does.

仅收集路径和简单特征；繁重的文件读取工作在写入时进行（由你自己执行，或在任务卸载时由

scout

执行）。此处不要完整读取规格说明或

design.md

。此处不要读取源文件；源文件会在写入时读取。

通过文件工具：

列出
```
docs/specs/
```
下最近修改的3个规格文件路径（仅路径）。
确定主规格说明：这些文件所实现的功能目录
```
docs/specs/NNNN-<feature>/
```
（或单个文件
```
docs/specs/NNNN-<feature>.md
```
），通过分支/功能名称或涉及的内容（若存在
```
docs/scope/
```
条目，会指向该规格）匹配。记录其路径以及旁边是否存在
```
verify.md
```
（
```
docs/specs/NNNN-<feature>/verify.md
```
）。该契约是测试关联的依据；它可能不在最近修改的3个路径中。当主规格说明存在时，设置
```
TRACE_TO_CONTRACT = yes
```
，否则为
```
no
```
。
记录项目根目录下是否存在
```
design.md
```
；仅当范围内存在component或page/flow类型文件时才使用其路径，否则为
```
none
```
。
读取
```
AGENTS.md
```
（标准文件；若不存在则读取
```
CLAUDE.md
```
）作为项目上下文（简短且成本低）。同时记录一行构建方式：团队选择的代码片段构建方法，记录在范围标题（或根目录
```
AGENTS.md
```
）中，例如：端到端极简路径、最精简可用核心循环、基于占位符的UI优先外壳、分阶段完整用户流程。它不会改变逻辑分支；仅在编写测试时校准判断（步骤8，规则a）。
读取
```
package.json
```
，记录
```
scripts.test
```
。当存在
```
test
```
脚本时，
```
RUN_COMMAND = <pkgmgr> test
```
（npm使用
```
<pkgmgr> run test
```
）；仅当不存在时才使用原始调用（例如
```
pnpm exec vitest run
```
）。

7.5 Ask whether to run the suite (always)

7.5 询问是否运行测试套件（每次运行必问）

Ask: "Tests will be written for <N> changed files. Run the suite after writing?"  (header: "Run tests?")
- "Yes, run and fix to green": "Execute the suite; I'll fix any test mistakes and flag real bugs the tests catch"
- "Skip, just write them": "Write the tests and give me manual run-and-verify instructions instead"

Set

RUN_AFTER = yes | no

and apply it at write time.

询问："将为<N>个变更文件编写测试。编写完成后是否运行测试套件？" （标题："运行测试？"）
- "是，运行并修复至通过": "执行测试套件；我会修复测试中的错误，并标记测试捕获到的真实bug"
- "跳过，仅编写测试": "编写测试并返回手动运行和验证的说明"

设置

RUN_AFTER = yes | no

并在写入时应用。

8. Write the suite (main thread)

8. 编写测试套件（主线程）

The main thread writes the tests itself. Do not spawn a writer. Resolve this skill's folder to an absolute path (you already resolve these relative paths, so you know the folder) and Read

agent-prompt.md

and

writing-guide.md

now (only now, at write time):

agent-prompt.md

is your operating template,

writing-guide.md

is the strategy, tool rules, iteration loop, and report format you follow. Reading the changed files under test is the one expensive part; for a large or unfamiliar set, offload just the reading to a read only

scout

subagent on the cheapest model (Claude Code:

haiku

, not inheriting the session model) that returns a compact map, then write from it.

The inputs to apply (the labeled values you gathered):

unit tool, E2E tool, additional tools,
```
INSTALL
```
state;
```
testDir
```
,
```
filePattern
```
, package manager, stack/framework,
```
packageRoot
```
; the classified scope (each file path with its class: logic / component / page flow / api server / cli);
```
RUN_COMMAND
```
,
```
RUN_AFTER
```
; project context plus the build approach line; the 3 recent spec paths or
```
none
```
(read only if relevant to what you're testing); the design.md path or
```
none
```
;
```
TRACE_TO_CONTRACT
```
, the governing spec path, and the
```
verify.md
```
path (each
```
none
```
if absent).
Two rules to apply: (a) let the build approach calibrate which behaviors are durably real for this slice (lock those in as stable assertions) versus deliberate scaffolding the slice fakes by design (don't assert a real implementation the plan hasn't built yet, e.g. a real backend expectation on a shell that stubs its data). (b) when
```
TRACE_TO_CONTRACT = yes
```
, read the acceptance criteria (from
```
verify.md
```
if present, preferring its already resolved
```
AC-N
```
-tagged checklist, else the spec's
```
## Requirements
```
) and lock in the durable ones: an automated test for every criterion that can be pinned as a stable assertion, each test tagged with the
```
AC-N
```
it covers (e.g. a
```
covers: AC-3
```
comment, or
```
AC-3
```
in the test title) so the suite traces back to the contract. Never fake a criterion that can't be automated (visual/manual/environmental, e.g. "email actually arrives"); record it in
```
NOT_COVERED
```
as
```
AC-N, <why not automatable> → defer to /check verify manual step
```
.

Monorepo (multiple package roots from Step 1b): write each root's suite in turn, scoped to its root's files, tool, and package manager (offload each root's file reading to its own

scout

if large). Single root (common case): just write it.

主线程自行编写测试。不要生成写入子代理。将本技能的目录解析为绝对路径（你已解析过这些相对路径，因此知道该目录），并在此时（仅在写入时）读取

agent-prompt.md

和

writing-guide.md

：

agent-prompt.md

是你的操作模板，

writing-guide.md

是你遵循的策略、工具规则、迭代循环和报告格式。读取待测试的变更文件是唯一的高成本操作；若文件数量多或不熟悉，可仅将读取工作卸载给只读型

scout

子代理（使用最便宜的模型，如Claude Code的

haiku

，不继承会话模型），该代理会返回紧凑的文件映射，然后你基于此编写测试。

需要应用的输入（你收集的带标签的值）：

单元测试工具、E2E工具、附加工具、
```
INSTALL
```
状态；
```
testDir
```
、
```
filePattern
```
、包管理器、技术栈/框架、
```
packageRoot
```
；已分类的测试范围（每个文件路径及其分类：logic / component / page flow / api server / cli）；
```
RUN_COMMAND
```
、
```
RUN_AFTER
```
；项目上下文加构建方式行；最近修改的3个规格文件路径或
```
none
```
（仅在与测试内容相关时读取）；
```
design.md
```
路径或
```
none
```
；
```
TRACE_TO_CONTRACT
```
、主规格说明路径和
```
verify.md
```
路径（若不存在则为
```
none
```
）。
需应用的两条规则：(a) 根据构建方式校准哪些行为对当前代码片段是持久真实的（将这些作为稳定断言锁定），哪些是代码片段故意模拟的临时脚手架（不要断言计划中尚未实现的真实功能，例如在使用数据存根的外壳中断言真实后端预期）。(b) 当
```
TRACE_TO_CONTRACT = yes
```
时，读取验收标准（优先从
```
verify.md
```
读取，若存在已解析的
```
AC-N
```
标记的检查列表，否则从规格说明的
```
## Requirements
```
读取）并锁定持久有效的标准：为每个可作为稳定断言的标准编写自动化测试，每个测试标记其覆盖的
```
AC-N
```
（例如
```
covers: AC-3
```
注释，或测试标题中包含
```
AC-3
```
），以便测试套件可追溯至契约。切勿为无法自动化的标准（视觉/手动/环境相关，例如"邮件实际送达"）编写虚假测试；将其记录在
```
NOT_COVERED
```
中，格式为
```
AC-N, <无法自动化的原因> → 推迟至/check verify手动步骤
```
。

单体仓库（步骤1b中存在多个包根目录）：依次编写每个根目录的测试套件，范围限定为该根目录的文件、工具和包管理器（若文件数量多，可将每个根目录的文件读取工作卸载给对应的

scout

）。单一根目录（常见情况）：直接编写即可。

After writing the suite

测试套件编写完成后

If the write failed or produced no report: say so and do it again; never report a passing or failing suite you didn't actually produce. Otherwise relay the format matching

RUN_AFTER

Update the scope: if this feature is on the scope (

docs/scope/

) and the suite passes, tick its

Test it

box. If

Design

Build

(+ its milestones),

Verify

, and

Test

are now all ticked, set the feature's status to

done

(in the At a glance table and beside the heading). If tests fail or coverage is partial, leave

Test it

unticked and the status

in-progress

. On

done

, advise

/clear

before the next feature: the scope and spec hold everything, a fresh session keeps the next build cheap.

Parse from the report:

TESTS_WRITTEN

NOT_COVERED

, plus

RUN_RESULT

and

BUGS_FOUND

when

RUN_AFTER = yes

, or

MANUAL_INSTRUCTIONS

when

RUN_AFTER = no

. Relay this template: keep lines marked

← yes

only when

RUN_AFTER = yes

← no

only when

RUN_AFTER = no

(a marked heading carries its list lines), unmarked lines always; strip the markers.

undefined

若写入失败或未生成报告：告知用户并重试；切勿报告未实际生成的测试套件通过或失败结果。否则根据

RUN_AFTER

的值匹配格式进行反馈。

更新范围：若该功能在范围中（

docs/scope/

）且测试套件通过，勾选其

Test it

复选框。若

Design

、

Build

（及其里程碑）、

Verify

和

Test

均已勾选，将功能状态设置为

done

（在概览表和标题旁）。若测试失败或覆盖不完整，保持

Test it

未勾选且状态为

in-progress

。当状态为

done

时，建议在下一个功能前运行/clear：范围和规格说明已包含所有信息，全新会话可降低下一次构建的成本。

从报告中解析：

TESTS_WRITTEN

、

NOT_COVERED

，当

RUN_AFTER = yes

时还需解析

RUN_RESULT

和

BUGS_FOUND

，当

RUN_AFTER = no

时需解析

MANUAL_INSTRUCTIONS

。按以下模板反馈：仅保留标记为

← yes

的行（当

RUN_AFTER = yes

时），仅保留标记为

← no

的行（当

RUN_AFTER = no

时）（标记的标题包含其下的列表行），未标记的行始终保留；移除标记。

undefined

/test complete (suite run) ← yes; when no, use: ## /test complete (not run)

/test 完成（已运行测试套件） ← yes; 若为no，使用：## /test 完成（未运行）

Scope: <N> changed files (uncommitted) Tool: <unit tool> [+ E2E tool] [+ addons] Preferences: loaded | saved to test-preferences.json

Tests written:

```
<file path>
```
, <N tests> covering <happy path / edges / errors / a11y> [→ AC-1, AC-3]

Run result: <X passed, Y failed> via

<RUN_COMMAND>

← yes

Traceability (only when TRACE_TO_CONTRACT=yes, spec NNNN):

AC-1 ✅ locked in,
```
<test file · test name>
```
AC-3 ✅ locked in,
```
<test file · test name>
```

Bugs caught (tests failing because the code is wrong, not the test): ← yes

<file:line, what's broken and the failing expectation> ← only if BUGS_FOUND is non-empty

How to run them: ← no

<setup step, e.g. install if INSTALL=deferred>
Run:
```
<RUN_COMMAND>
```
Watch a single file:
```
<focused command>
```

What you should see: <expected pass output, and which tests prove which behaviour> ← no If something fails: <how to read the failure, is it a test gap or a real bug> ← no

Not covered (consider adding):

<gap and why>
AC-N, <criterion that can't be automated (visual/manual/env)> → defer to /check verify manual step ← when TRACE_TO_CONTRACT=yes


If `BUGS_FOUND` is not empty, lead with it: a test that correctly fails on real broken code is a genuine finding, not something to silence. /test does not modify application code to make a test pass.

This skill is complete after relaying the report: it does not invoke other skills.

---

范围：<N>个变更文件（未提交）工具：<单元测试工具> [+ E2E工具] [+ 插件] 偏好设置：已加载 | 已保存至test-preferences.json

已编写测试:

```
<文件路径>
```
，<N>个测试，覆盖<正常流程 / 边界情况 / 错误处理 / 可访问性> [→ AC-1, AC-3]

运行结果：<X个通过，Y个失败>，通过

<RUN_COMMAND>

执行 ← yes

可追溯性（仅当TRACE_TO_CONTRACT=yes且存在规格NNNN时）:

AC-1 ✅ 已锁定，
```
<测试文件 · 测试名称>
```
AC-3 ✅ 已锁定，
```
<测试文件 · 测试名称>
```

捕获到的bug（测试失败是因为代码错误，而非测试本身问题）: ← yes

<文件:行号，问题描述及失败预期> ← 仅当BUGS_FOUND非空时显示

运行方式: ← no

<设置步骤，例如若INSTALL=deferred则需安装>
运行命令：
```
<RUN_COMMAND>
```
单独运行单个文件：
```
<聚焦命令>
```

预期结果: <预期的通过输出，以及哪些测试验证了哪些行为> ← no 若测试失败: <如何解读失败结果，是测试漏洞还是真实bug> ← no

未覆盖内容（建议补充）:

<漏洞及原因>
AC-N, <无法自动化的标准（视觉/手动/环境）> → 推迟至/check verify手动步骤 ← 当TRACE_TO_CONTRACT=yes时显示


若`BUGS_FOUND`非空，优先展示：正确捕获真实代码问题的失败测试是有效的发现，而非需要忽略的内容。/test不会修改应用代码使测试通过。

反馈报告后，本技能执行完成：不会调用其他技能。

---

Reference files (in this skill's folder; referenced by relative path)

参考文件（位于本技能目录下；通过相对路径引用）

```
modes/setup.md
```
: first run only steps (stack detection, framework questions, save preferences); read on the main thread only when
```
NO_PREFS
```
```
agent-prompt.md
```
: the operating template the main thread reads at write time (Step 8)
```
writing-guide.md
```
: strategy, tool rules, iteration loop, report format; the main thread reads it at write time too

```
modes/setup.md
```
: 仅首次运行时执行的步骤（技术栈检测、框架询问、保存偏好设置）；仅当
```
NO_PREFS
```
时由主线程读取
```
agent-prompt.md
```
: 主线程在写入时读取的操作模板（步骤8）
```
writing-guide.md
```
: 策略、工具规则、迭代循环、报告格式；主线程在写入时也会读取该文件