# Testspec New

> TestSpec 新建测试工作（流程第 1 步）- 创建测试变更目录，编写 proposal.md，并在用户提供已有 PRD/需求片段时净化成可验收的 requirements.md。当用户要「新建测试」「开始测试」「创建测试变更」「建一个测试项目」或执行 testspec-new / testspec new 时使用。也适用于用户说「我要测 XXX 功能」「帮我准备测试」「有个新需求要测」「帮我整理/审查 PRD」的场景——如果尚无 testspec/changes/ 目录，这是流程的起点。产出 testspec/changes/{name}/ 目录结构、proposal.md，必要时产出 requirements.md。

- Skill: `winhok/testspec-new` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add winhok/testspec-new`
- Raw SKILL.md: https://api.skillmd.com/api/skills/winhok/testspec-new/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: MIT
- Author: winhok (https://skillmd.com/u/winhok)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/winhok/testspec-new

---


# testspec-new：新建测试工作（需求文档）

铁律：没有可追溯需求来源或明确的“信息不足”标记时，绝不能创建 TestSpec change；也绝不能仅靠重新排版就把原始 PRD 变成 `requirements.md`。

```text
TestSpec 新建进度：

- [ ] 步骤 1：确定 change 名称 ⚠️ 必需
- [ ] 步骤 2：评估输入材料 ⚠️ 必需
- [ ] 步骤 3：创建 change 工作区
- [ ] 步骤 4：写入包含协作检查点的 proposal.md
- [ ] 步骤 5：有原始 PRD 材料时执行 PRD intake 并写入 requirements.md
- [ ] 步骤 6：生成 requirements.md 后复核其质量
- [ ] 步骤 7：写入 context 元数据并报告下一步
```

## 职责

新建一次 TestSpec 测试工作：创建变更目录并编写测试提案初稿，在 proposal 中**关联或引用需求文档**（PRD、用户故事、接口说明等）。当输入是已有 PRD 或需求片段时，额外执行 PRD Intake：先审查模糊和缺失，再把材料净化成 `requirements.md`，作为后续 testspec-analysis 的高质量需求源。

`testspec-new` 只负责准备可信需求源；不要在本阶段做测试风险拆解、测试点设计或用例生成。

若当前变更目录已存在，且用户是在补充、修改、删除或澄清 PRD/API/UI/产品口径，改用 `testspec-update` 做需求源口径收敛，不要重新创建变更。

## 共享规则源

- proposal 模板：`references/proposal-template.md`
- requirements 模板：`references/requirements-template.md`
- 输出契约：`../_testspec-shared/references/output-contracts.md`
- 上下文协议：`../_testspec-shared/references/context-protocol.md`
- 来源与信任：`../_testspec-shared/references/source-provenance.md`
- 问题状态机与 frontier：`../_testspec-shared/references/interrogation-protocol.md`

## 确定变更名

- 从用户输入中提取被测对象（功能名、模块名、版本号等）。
- 将名称规范为短名：英文或拼音，空格与特殊字符替换为 `-`（如「用户登录」→ `user-login`，`release 2.0` → `release-2.0`）。

## 执行步骤

1. **确保根目录存在**：若项目下没有 `testspec/changes/`，直接创建（`mkdir -p testspec/changes`）。
2. **创建变更目录**：`testspec/changes/<name>/`，以及子目录 `specs/`、`artifacts/`。
3. **编写 proposal.md**：在变更目录下创建 `proposal.md`。

   模板见 `references/proposal-template.md`，核心字段：
   - 被测对象（功能/模块/版本）
   - **关联需求文档**：路径或链接（PRD、用户故事、接口文档等）
   - 测试目标与原因
   - 可选：关联的 OpenSpec

4. **协作检查点**（写入 proposal.md 末尾、context 元数据之前）：

   > 测试质量的上限取决于测试开始前的信息对齐程度。如果产品、开发、测试三方对需求范围和技术约束的理解不一致，后续分析和用例生成会建立在错误的假设之上。这个检查点的目的不是设置审批门禁，而是让 proposal 的信息质量从源头得到保障，减少下游返工。

   ```markdown
   ## 协作确认
   - [ ] 产品已确认需求范围和验收标准
   - [ ] 开发已确认技术约束和可测试性（如：是否有测试环境、数据准备方式、已知的技术限制）
   - [ ] 测试分析前需澄清的关键问题已列出（→ 将传递给 testspec-analysis 的质询清单）
   ```

   **使用说明**：
   - 默认生成为未勾选状态，不阻塞流程
   - 用户可手动勾选确认，也可跳过直接进入 testspec-analysis
   - 若全部未勾选进入 analysis，testspec-analysis 会在信号检测中识别到 material_quality 偏低，自动加深质询力度
   - 第三项"关键问题"若已填写，将直接传递给 testspec-analysis 作为质询清单的种子输入

5. **PRD Intake（按需）**：若用户提供已有 PRD 内容、PRD 链接/路径可读取内容，或明确要求审查/补全 PRD，则创建 `requirements.md`。
6. **需求质量复核（按需）**：若生成 `requirements.md`，执行六维质量复核并写入文档。
7. **告知用户**：变更目录路径、需求质量和 strategy requirement；下一步执行 testspec-analysis。

## PRD Intake 模式

触发条件：

- 用户粘贴已有 PRD、需求片段、用户故事或功能清单
- 用户提供可读取的 PRD/需求文档路径或链接
- 用户要求「审查 PRD」「补全需求」「整理成 requirements.md」

执行规则：

1. **先挑刺，不整理**：先识别模糊表述、隐含依赖、缺失验收条件、边界不清、合规/权限/数据隔离等隐藏假设。
2. **只描述做什么**：`requirements.md` 不写 Redis、MQ、数据库表、接口拆分、算法选型等实现方案；未确认项进入 question graph 或风险点。
3. **功能必须可验收**：功能列表每一条必须同时包含行为和验收条件；缺少标准的条目不得伪装完成，按影响进入 question graph 或风险点。
4. **边界必须显式化**：明确本期不做什么、输入输出边界、格式/容量/权限/数据隔离边界。
5. **交互追问一次一个问题**：需要用户补信息时，一次只问最高影响的一个问题；可以在 `requirements.md` 中保留完整澄清清单，但对话中只推进一个阻塞点。
6. **AI/算法类需求要有评估标准**：涉及搜索、推荐、问答、识别、生成等效果型能力时，验收条件必须包含样本集/benchmark、通过阈值、人工复核或失败处理标准；缺失则标为风险。
7. **输出产品问题清单**：当 readiness 不足或存在阻塞 analysis 的 active decision 时，输出当前 decision frontier；对话中默认只追问最高影响问题。
8. **默认 PRD-first**：PRD、产品回答和验收规则是默认需求源。不得要求代码访问；只有用户主动提供代码或明确要求代码调查时，才按 `../_testspec-shared/references/source-provenance.md` 记录可选代码证据。

### 审查维度

- 模糊词：合理、快速、稳定、友好、相关、适当、尽快、准确等不可直接验收的描述
- 隐含依赖：权限模型、租户/数据隔离、审计合规、通知链路、外部系统、内容安全
- 验收缺口：未说明完成标准、错误处理、边界值、容量限制、兼容范围、超时和重试
- 范围边界：本期不支持的角色、格式、平台、流程、异常数据和历史兼容
- 风险点：会影响开发排期、测试验收、合规或上线质量的未确认项

### requirements.md 写入规则

按 `references/requirements-template.md` 生成 `requirements.md`。材料不足时也可以生成，但必须：

- 在「功能列表」中只保留已有明确验收条件的条目
- 「功能列表」中的每条功能必须使用 `REQ-001` 形式编号，并保留来源（原 PRD 章节/第 N 条/链接锚点等）
- 按共享 interrogation 协议建立稳定 question graph；Fact 由 Agent 查证，Decision 由用户/产品裁决
- 在「风险点」中使用 `RISK-001` 形式编号，并说明影响、决策条件或备选处理
- 在末尾播种 context schema v2，包含 `questions`、`strategy_requirement`、`source_revision`、质量字段和 stale envelope；完整字段以模板为准

### 需求质量复核

生成 `requirements.md` 后，按六维给出 0-100 分：完整性、清晰性、一致性、可测试性、可追溯性、可行性。总分为六维平均值。

结论规则：

- `ready_for_analysis`：总分 >= 90，且无阻断级澄清项
- `needs_clarification`：总分 75-89，或存在会影响测试设计但可继续分析的问题
- `needs_revision`：总分 60-74，需求需明显补写后再继续
- `blocked`：总分 < 60，或核心范围/验收标准缺失导致无法进入后续流程

复核要求：

- 每个扣分原因必须指向具体 REQ-ID、章节或原 PRD 位置
- 风险点不能只登记，必须说明影响、决策条件或备选处理；缺失则扣完整性/可行性
- 发现技术词混入（如缓存、索引、异步、向量、队列、数据库、接口、算法）时，判断它是否为业务可见概念；若只是实现方案，改写成用户可感知行为并扣清晰性
- 执行“陌生人测试”：5 分钟内能否从文档回答系统做什么、谁在用、本期不做什么、成功/失败怎么算、最大风险是什么；答不上来则扣清晰性/完整性
- 总分低于 90 时，不得把 `readiness` 标为 `ready_for_analysis`

### 产品问题清单

当 `readiness != ready_for_analysis` 或存在阻塞 analysis 的 active decision 时，最终回复必须输出当前 frontier 中可直接转发给产品的问题：

```markdown
## 可复制给产品的问题清单
1. [P0/P1/P2] <问题>（影响：<阻塞的分析/验收判断>；需要产品给出：<规则/范围/样例/口径>）
```

排序规则：先按阻塞阶段，再按测试影响排序；每个问题关联 REQ/RISK/来源，只展示依赖已解决的 decision frontier。

## 反模式

- 不把原始 PRD 改个格式就当 `requirements.md`
- 不为缺失验收条件的功能补编规则
- 不把实现方案写成需求事实
- 不在总分低于 90 时标记 `ready_for_analysis`
- 不生成无 REQ-ID 或无来源的功能条目
- 不在需求未 ready 时只说“请补充需求”，必须给出可复制给产品的问题清单

## 材料评估与工具使用

在编写 proposal.md 之前，对用户提供的材料进行评估：

### 信息密度判断

- **完整 PRD**：用户提供了详细的需求文档链接或内容 → 在 proposal 中完整引用，并触发 PRD Intake 生成 requirements.md
- **简短描述**：用户只说了功能名称或一句话 → 在 proposal 中标注信息不足，建议补充
- **代码仓库**：仅当用户显式要求代码校准时，先创建本 change，再路由到 `testspec-code-calibrate`；本 skill 不直接扫描代码或从代码生成 canonical requirements

### 工具自主使用

- 若用户提供了 PRD 链接 → 抓取链接内容，提取关键信息写入 proposal
- 若用户明确要求从代码恢复需求 → proposal 标记信息不足，完成 workspace 后运行 `testspec-code-calibrate` recovery；草稿经产品确认后交 `testspec-update`
- 若用户要求用代码核对已有 PRD → 完成当前 PRD intake 后运行 `testspec-code-calibrate` comparison；本 skill 不读取代码
- 若用户提供了设计稿链接 → 抓取可访问内容，提取交互流程

### 上下文播种

在 proposal.md 末尾，按 `../_testspec-shared/references/context-protocol.md` 播种元数据：

```markdown
<!-- testspec-context
{
  "context_schema_version": 2,
  "source_skill": "testspec-new",
  "canonical_source_policy": "prd-first",
  "evidence_sources": [{"type": "prd", "source_ref": "<来源>", "authority": "canonical", "scope": ["product-behavior"]}],
  "questions": [{"id": "Q-001", "kind": "decision", "status": "open", "question": "<问题>", "depends_on": [], "blocks_stages": ["analysis"], "recommendation": {"value": "<建议答案>", "status": "proposed"}, "resolution": null}],
  "strategy_requirement": {"status": "<required/skipped>", "reasons": ["<原因>"]},
  "material_quality": "<high/medium/low>",
  "signals_detected": ["<从材料中发现的关键信号>"],
  "requirements_intake": {
    "generated": "<true/false>",
    "path": "<requirements.md 或空>",
    "open_question_count": "<阻塞 analysis 的 active question 数量>"
  },
  "source_revision": {
    "version": 1,
    "summary": "<本轮需求源口径摘要>",
    "updated_by_skill": "testspec-new"
  },
  "stale_downstream_artifacts": [],
  "requirement_quality": {
    "overall_score": "<六维平均分或空>",
    "readiness": "<ready_for_analysis/needs_clarification/needs_revision/blocked 或空>"
  }
}
-->
```

## 产物

- `testspec/changes/<name>/proposal.md`（含上下文元数据）
- `testspec/changes/<name>/requirements.md`（可选；当已有 PRD/需求片段可净化时生成）
- `testspec/changes/<name>/specs/`（空目录）
- `testspec/changes/<name>/artifacts/`（空目录）