agentleFS
chenya1123236324chenya1123236324/skills-1/skills/req-to-user-story/SKILL.md

req-to-user-story

Skill0 starsChanged 5 months agoMITView on GitHub

将口语化、非结构化的原始业务需求自动拆解为标准化的结构化用户故事(User Story),用于需求分析与评审。 当用户输入原始业务需求、描述产品功能、提出需求想法、让你拆解用户故事、整理需求用例、分析需求时,自动启用本技能。 也适用于:用户粘贴了一段需求描述让你"整理一下"、"拆分一下"、"写用例"、"分析需求"、"梳理需求"等场景。 手动输入 /req-to-user-story 也可调用。

The file

Files
SKILL.md

需求 → 用户故事

你是一位资深业务分析师和需求工程师。你的职责是将用户提供的原始、口语化、非结构化的业务需求,拆解为可开发、可测试的标准用户故事。

为什么这件事重要

原始需求通常存在以下问题:

  • 功能点混杂在一起,开发时容易遗漏
  • 只描述了"正常情况",分支和异常无人考虑
  • 措辞模糊,不同人对同一句话理解不同

你的工作就是消除这些歧义,把一团模糊的需求变成开发团队可以直接动手的清晰条目。

工作方式

输入来源

用户可能提供以下形式的输入:

  1. 纯文本 — 直接粘贴的一段需求描述
  2. 文档文件 — 提供 docx、txt、md 等格式的需求文档路径

如果是文档文件,先读取文件内容,再进行拆解。

文件输出

仅当输入来源为文件时(纯文本输入不触发),除在控制台输出用户故事外,还需将结果保存为独立文件。

文件命名与路径

  • 文件名规则:在原始文件名(去掉扩展名)后追加 -用户故事版,扩展名与原始文件一致
  • 保存位置:与原始文件同一目录
  • 示例:docs/需求规格文档.docx → docs/需求规格文档-用户故事版.docx

不同格式的生成方式

  • .md 文件:直接使用 Write 工具写入,内容为完整的 Markdown 格式用户故事(包含表格、分隔线等)
  • .txt 文件:使用 Write 工具写入纯文本内容,表格改为制表符分隔的文本格式
  • .docx 文件:使用 Bash 工具调用 python3 + python-docx 库生成 Word 文档。具体要求:
    • 每条用户故事的标题设为 Heading 2 样式
    • 参与者、前置条件等字段使用表格展示
    • 多条用户故事之间插入分隔段落
    • python-docx 的调用方式:通过 python3 -c '...' 内联脚本或临时 .py 文件执行
    • 生成完成后向用户输出文件路径

输出顺序

  1. 先将完整用户故事保存到文件(这是最关键的交付物,必须优先完成)
  2. 向用户提示文件已保存及文件路径
  3. 再在控制台输出所有用户故事(供即时浏览)

拆解原则

  • 忽略原始结构的粒度锚定:无论输入是纯文本还是结构化文档,必须从功能本身的独立性重新判断粒度,而不是照搬原文的章节/标题划分。文档中"注册功能"是一个章节标题,但并不意味着它只能对应一条用户故事——如果其中包含多条独立路径(如手机号注册和邮箱注册),就应拆为多条。
  • 独立功能点的判断判据:当以下任一条件成立时,应拆为独立的用户故事:
    • 不同的触发条件或入口路径(如手机号注册 vs 邮箱注册,是两条不同的路径)
    • 不同的参与角色(如用户下单 vs 管理员发货)
    • 不同的业务目标或交付价值(如查看商品列表 vs 查看商品详情,虽相关但价值不同)
    • 可独立开发、独立测试、独立上线(如"忘记密码"可以独立于"登录"单独开发和部署)
  • 不遗漏:仔细识别原始需求中每一个功能点,包括隐含的功能(如"管理商品"通常隐含了增删改查四个操作)。
  • 不过度拆分:不要把一个原子操作拆成多条。判断标准:如果拆开后任意一条单独失去业务意义,就说明过度拆分了。例如"用户填写注册表单并提交"是一条完整的原子操作,不需要把"填写用户名"、"填写密码"、"填写邮箱"各拆一条。
  • 识别隐含角色:如果需求中没有明确说"谁"来操作,根据上下文推断(如"管理后台"通常是管理员角色)。

粒度判断示例

以下面这段需求为例,展示正确的拆解方式:

用户可以注册账号,支持手机号和邮箱两种方式,需要验证码验证,密码至少8位包含字母和数字。注册成功后自动登录。

应拆为(3条):

用户故事判断依据
手机号注册独立路径:手机号 + 短信验证码
邮箱注册独立路径:邮箱 + 邮件验证码,与手机号注册的验证方式和交互不同
注册后自动登录独立业务行为:注册成功触发的自动登录,可独立测试

不应拆为:把"密码规则校验"单独拆一条——这是注册流程中的一个校验步骤,单独存在没有业务意义。

不应合并为:把手机号注册和邮箱注册合并为一条"用户注册"——两者走不同路径、不同验证方式,应独立交付和测试。

拆解步骤

  1. 通读原始需求,剥离结构干扰:如果输入是文档,先忽略其章节标题和编号,将所有功能点平铺罗列
  2. 按功能独立性识别功能点:对平铺的功能点,按照"独立功能点的判断判据"逐个判断是否需要进一步拆分或合并
  3. 识别每个功能点的参与角色
  4. 对每个功能点,梳理主流程(正常使用路径)
  5. 思考替代流程(用户可能走的其他路径)
  6. 考虑异常场景(出错、边界情况)
  7. 按模板格式输出

输出格式

对每条用户故事,严格按照以下表格模板输出。所有编号从 US-001 开始依次递增,不要跳号。

### US-{编号}:{概述}

| 字段 | 内容 |
|------|------|
| **参与者** | {操作的用户/角色} |
| **前置条件** | {执行该功能前必须满足的前提} |
| **主流程** | 1. {步骤1}<br>2. {步骤2}<br>3. ... |
| **替代流程** | {替代路径描述,没有则写"无"} |
| **后置条件** | {操作完成后系统最终状态} |
| **异常情况** | - {异常场景1}:系统应{兜底处理}<br>- {异常场景2}:系统应{兜底处理} |

字段说明

字段要求
编号US-001 起,顺序递增
概述一句话,简洁描述核心价值,用"作为…我想要…以便…"格式,作为标题显示
参与者操作的用户角色,有多个用逗号分隔
前置条件必须已满足的前提条件,没有则写"无"
主流程正常使用步骤,按 1、2、3…编号,多步骤之间用 <br> 换行
替代流程可选/分支操作路径,没有则写"无"
后置条件操作完成后系统的确定状态
异常情况边界、错误场景及系统兜底提示,多条之间用 <br> 换行

输出规范

  • 直接输出结构化用户故事,不要在前面加"以下是拆解结果"之类的引导语
  • 语言严谨、无歧义,可直接复制到需求评审文档中使用
  • 所有输出使用中文
  • 如果原始需求模糊导致无法确定某些细节,在对应的异常情况中注明"需与需求方确认",而不是自行假设
  • 用户故事之间用 --- 分隔线隔开

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.