Design Image To Test Requirements

设计图 / 图片 → 面向测试的功能需求文档

使用时机

• 用户提供界面截图、设计稿、交互说明图（单张或多张），需要产出可测的功能需求 Markdown 时。
• 用户要求面向测试、不写样式开发规格、或「按图片生成需求说明」时。
• 输入为图片或图片描述；与 Figma URL / MCP 无关（Figma 链路用 figma-requirements-from-figma-mcp）。

输入要求

• 必填：至少一张设计相关图片（工作区路径、会话附件、或可读图片描述）。
• 可选：
  • 输出路径：如 docs/requirements-xxx.md；未指定则按下文「输出文件名规则」。
  • 标题要素：产品/系统名、主功能/主单据名；未提供时据画面推断，并在「待确认事项」中列出命名待确认（若不确定）。

输出文件名规则（用户未指定路径时）

1. 用户给出功能简称：docs/requirements-<slug>.md（非法文件名字符改为 -）。
2. 画面主标题可识别：docs/requirements-<规范化主标题>.md。
3. 否则：docs/requirements-from-design-image.md。

默认覆盖写入；用户要求「追加」时仅在指定文件末尾追加章节。

总体流程

1. 读图：模块边界、字段标签、按钮与枚举、表格列头、提示/规则文案（含独立「交互说明」类附图）。
2. 归类：映射到下文「输出文档骨架」中的模块；区分录入字段、操作、纯展示文案。
3. 功能抽象：只写行为、数据、规则、分支、联动；禁止把视觉规格当需求正文（见「禁止项」）。
4. 未定稿：图中无法确定的必填、边界、接口一律进 ## 待确认事项，不得写成已定事实。
5. 成文：严格遵循下文「章节约束」与「输出文档骨架」，写入目标 Markdown 文件。
6. 回告：对话中给出文件路径、主模块列表、待确认条数。

可选脚本（降低 token 消耗）

本 skill 不依赖脚本即可完成；若希望少生成「骨架 Markdown」、减少格式差错，可在读图后先用脚本落盘模板，再在文件中填空。

• 路径（相对于仓库根）：.claude/skills/design-image-to-test-requirements/scripts/scaffold_design_requirements.py（Python 3，仅标准库）。
• 生成骨架（覆盖写入 --output）：

python .claude/skills/design-image-to-test-requirements/scripts/scaffold_design_requirements.py scaffold ^
  -o docs/requirements-<slug>.md ^
  --product "<产品/系统名>" ^
  --feature "<主功能或主单据名>" ^
  --material "<图片相对路径1>" ^
  --material "<图片相对路径2>"

未传 --material 时，「对照素材」默认为 - 见会话附件。--product / --feature 可省略（使用占位符），读图后再改标题与 ## <主单据> 标题。

• 建议输出路径（仅打印，不写文件）：

python .claude/skills/design-image-to-test-requirements/scripts/scaffold_design_requirements.py suggest-path --title "<画面主标题或功能名>"

• 结构自检（写完後可选）：

python .claude/skills/design-image-to-test-requirements/scripts/scaffold_design_requirements.py check docs/requirements-xxx.md

校验失败时退出码非 0（缺必填 ## 或「业务流程」与「待确认事项」之间无主单据章节）。

Windows PowerShell 可将行尾 ^ 改为 ` 续行或写成单行。

需求文档生成规则

• 语言：说明性文字用中文；按钮、选项、专有名可与界面一致，可加引号或书名号。
• 推测：允许合理推断流程；须在「待确认事项」列出可验证假设，或正文中将必填标为 待确认。
• 多图：交互规则图并入对应 ### 的编号列表，不单设「样式章」。
• 禁止项（正文）：不写像素、色值、字体、圆角、间距比例、主辅色、hover、分栏百分比等纯视觉规格（除非用户明确要求验收视觉）。

可测性写法约束（禁止笼统省略）

面向测试编写时，需求正文必须具体到可直接派生用例，禁止用模糊措辞掩盖已从图中可读出的信息。

禁用措辞（当所指集合在设计稿中已可见或可枚举时）

• 严禁单独使用「等」「之类」「包括但不限于」「……」「若干」「相关」「多余」「其它类似」等一笔带过。
• 严禁在「付款方式」「导航菜单」「表格列」「单选项」「操作按钮」类描述末尾加「等」省略可见项。

必须怎么做

1. 逐项列出：凡界面可见的选项、表格列名、主导航名称、弹窗按钮（确定/取消/查询/重置等）、分支条件与对应结果，均用完整列表（Markdown 1. 列表或表格行），与稿面文案一致。
2. 测试范围 / 业务流程：每条用例路径写清前置条件 → 操作 → 系统行为 → 预期结果；不得写「必要时校验」「按需提示」而无判定标准。
3. 信息 genuinely 不全：不写「等」，应改为明确句式：「图中仅见以下 n 项：…」或「是否存在额外项：待确认」，并把缺口写入 ## 待确认事项 单独编号，不得在正文用「等」假装已穷尽。
4. 同一语义不得重复省略：例如枚举已在列表写出，后文不得再写「上述选项等」。

豁免

• 脚手架脚本生成的占位符 …、骨架括号说明仅供填空，不视为成品需求。
• 引用外部法规/制度全称且与界面无关时，可用书名号完整引用，仍避免「等相关规定」式模糊（改为列出本章适用的具体条款名或写入待确认）。

输出文档骨架（Markdown 模板）

生成文件时必须贴合下列结构；占位符按需替换，--- 分隔符不得省略。

# <产品/系统名> · <主功能或主单据名>（功能需求 · 测试用）

**读者**：测试  
**说明**：本文仅描述**功能行为、数据与业务规则**，不含视觉样式、布局比例、组件皮肤等前端实现要求。  
**对照素材**（验收时可对照设计稿）：

- <每张输入图一行：工作区相对/绝对路径；仅会话附件无路径时写「见会话附件」>

---

## 概述

<1～3 短段：入口、主任务、关键能力（业务语言）>

---

## 测试范围

| 类型 | 内容 |
|------|------|
| **本期建议覆盖** | <逐项列出可测能力，不用「等」省略；每条宜对应可设计用例的能力点> |
| **本期不展开**（缺独立需求时记为「未覆盖」） | <图中未覆盖或需独立 PRD 的部分> |

---

## 功能模块与入口

| 模块 | 功能要点（可测） |
|------|------------------|
| 全局入口 | <若有导航/入口则写；否则删改此行> |
| … | <每个独立功能区一行：如何进入 + 能做什么> |

---

## 业务流程

1. <主路径步骤：条件 + 操作 + 预期，勿用「等」省略分支>
2. <联动/分支：逐项>
3. <继续编号直至覆盖稿面可见关键路径；未知项写入待确认，不用「等」>

---

## <主单据或主功能名>

以下按模块展开：各小节先说明**业务流程与规则**（编号列表），再给出**表单字段**表格（有则列；无独立录入字段的模块仅列规则或展示要求）。

### <子模块名 A>

<可选：一句非样式的场景说明>

1. <规则或流程，含条件与结果>
2. …

| 字段 | 含义 | 必填 | 测试注意 |
|------|------|------|----------|
| … | … | 是/否/待确认 | … |

<若有固定枚举，在表后列出全部选项>

---

### <子模块名 B（明细表）>

1. <增删行、校验、联动：每条规则单独编号，勿用「等」省略分支>

| 列名 | 说明 | 测试注意 |
|------|------|----------|
| … | … | … |

---

### <子模块名 C（仅展示指引，无表单字段）>

1. <可见性、与填写进度是否无关：逐条写出可验证点>

| 序号 | 应包含的业务语义 |
|------|------------------|
| 1 | … |

---

### <子模块名 D（底部操作栏）>

1. <提交/草稿/取消等行为说明>

| 操作 | 含义 | 业务流程说明 |
|------|------|----------------|
| … | … | … |

---

## 待确认事项

1. …
2. …

章节约束（MUST）

以下是对「骨架」的硬约束；缺信息时保留章节标题，表格单元格用 待确认，不得删章。

文档头部

• 一级标题格式固定：# …（功能需求 · 测试用）。
• 对照素材小节必须存在；能列路径则列路径，否则写「见会话附件」。

分隔符

• 每个 ## 章节结束后：单独一行 ---。
• ## <主单据或主功能名> 下每个 ### 结束后：---。

## 概述

• 只写业务背景与关键能力；不写布局与组件外观。

## 测试范围

• 必须为两列表格，列名与骨架一致。
• 「本期建议覆盖」不得写图中无法推断的接口细节。
• 「本期建议覆盖」须拆成多条可测能力点（可分号分隔）；禁止用「等」省略已从图中识别的模块或规则。

## 功能模块与入口

• 必须为表格；至少一行全局入口（若图中有）+ 各功能区；表述可测，不是 UI 陈设描述。

## 业务流程

• 必须为有序列表 1. 2. …；覆盖主路径与关键分支（联动、条件显隐、提交/存草稿/取消若存在）。
• 不写「按钮在右下角」类位置描述（除非业务含义依赖位置）。
• 每条步骤须有可验证语义（触发条件、用户动作、系统响应、数据变化至少具备其二）；禁止用「等」「必要时」「按需」省略稿面已给出的分支。

## <主单据或主功能名>

• 标题须与画面主标题或业务单据名一致；禁止用泛名「详细功能」代替。
• 标题下必须紧跟骨架中的固定引导段（「以下按模块展开…」原文允许微调用词，语义不变）。

每个 ### 子模块

• 顺序固定：可选一句场景说明 → 编号列表规则 → 空行 → 表格（若适用）→ 枚举（若有）→ ---。
• 禁止先大段表格后写规则；永远先规则列表，后表格。
• 禁止用「图一/图二」当小节标题。
• 枚举穷尽：稿面出现的选项值、表格列、多选框标签须在本节全部写出；不得以「等」代替末项。若怀疑稿面不全，用「待确认」条目说明而非「等」。

表格列名（按模块类型选一种，不得自创列名混用）

• 必填列只允许：是 / 否 / 待确认，不得留空。
• 测试注意无则写 —。

## 待确认事项

• 必须为有序列表；图中凡未定必填、删除行规则、混合条件优先级、附件规格、权限接口等必须反映在此。
• 禁止把图中已可见的枚举、联动写进待确认而不写进对应 ###。
• 单条待确认须唯一、可指派，避免「及其它」式合并多条未定假设。

自检清单（写出文件前内部核对）

• 文首元信息 + 概述、测试范围、功能模块与入口、业务流程、## 主单据名、待确认事项 齐全。
• ## 主单据名 下各 ### 均为：编号规则 → 表格（若适用）→ 枚举（若有）→ ---。
• 正文无大段纯视觉描述。
• 正文「必填=待确认」与「待确认事项」无矛盾。
• 检索全文：对图中已可见的枚举类内容，正文不出现用「等」「包括但不限于」省略列举的情况；未知范围已写入待确认。

具体执行指引（给智能体）

1. 识别触发：用户上传/指向设计图并要求需求说明、测试向 PRD、图片转需求等 → 使用本 skill（非 Figma URL）。
2. 解析输入：收集图片路径或附件、可选输出路径、可选产品/功能命名。
3. （可选）脚手架：若未指定输出路径，可先运行脚本的 suggest-path；需要省 token 时运行 scaffold 生成骨架，再基于读图结果替换占位符与增删 ###。
4. 抽取信息：字段、枚举、表格列、操作按钮、提示文案、跨字段规则；多图合并到同一文档对应模块。
5. 生成正文：按「输出文档骨架」与「章节约束」组装；子模块划分与图中区块对齐（申请人区、表单区、明细表、附件区、侧栏指引、底部操作等）。若已 scaffold，仅在骨架上增量修改，避免整篇重写骨架。遵守「可测性写法约束」：枚举与分支逐项写出，禁止用「等」省略稿面已有信息。
6. 写入文件：在项目 docs/ 下按规则命名写入；覆盖或追加依用户指示。
7. （可选）校验：对落地文件运行脚本 check。
8. 反馈用户：报告路径、模块大纲、待确认事项 条数。

与 Figma 需求 skill 的区分