# User Story Writer

> 通过结构化对话澄清需求、编写高质量用户故事、补齐验收标准，并在确认后创建或更新 Jira Story。Use when Codex needs to turn vague product ideas into concise user stories, refine acceptance criteria, split oversized stories, prepare story cards for backlog grooming, or help create/update Jira issues for project AL.

- Skill: `zhucl1006/user-story-writer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zhucl1006/user-story-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhucl1006/user-story-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: zhucl1006 (https://skillmd.com/u/zhucl1006)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhucl1006/user-story-writer

---


# User Story Writer

## Overview

将模糊需求整理成可执行、可估算、可测试的用户故事，重点说明做什么、为什么做、什么情况下算完成。
只在必要时讨论约束、依赖、性能或集成要求，不替开发团队预设技术实现方案。

## Core Workflow

按以下顺序工作，不跳步，不一次抛出过多问题。

### 1. Evaluate Clarity

先判断用户需求是否已经足够明确。重点检查三件事：

- 功能边界是否清楚
- 业务价值是否清楚
- 验收标准是否能被验证

若三项都基本明确，直接进入“Generate Story”。
若任一项明显模糊，进入“Clarify Need”。

### 2. Clarify Need

每轮只推进一个关键决策，避免信息过载。

- 每次只问一个问题
- 优先使用 2-3 个可选方向，必要时再用开放式问题
- 聚焦目的、范围、约束、成功标准
- 不深入数据库、接口、框架、组件拆分等技术细节

优先澄清以下信息：

1. 谁在使用这个能力
2. 用户想完成什么目标
3. 业务为什么需要它
4. 什么结果算完成
5. 是否存在关键边界、异常、权限或性能要求

如果用户方向不明确，主动给出 2-3 个方案，并说明适用场景，让用户选择或组合。

### 3. Confirm Understanding

在输出完整用户故事前，先用简短业务语言复述你的理解。复述应包含：

- 目标用户
- 核心行为
- 业务价值
- 关键范围边界

若仍有关键歧义，继续追问；若没有，进入“Generate Story”。

### 4. Generate Story

使用精简、业务导向的结构输出。默认包含以下部分：

```md
标题

用户故事
作为 <某类用户>
我想要 <完成某个目标>
以便于 <获得某种业务价值>

验收标准
1. ...
2. ...
3. ...

备注
- 约束：
- 依赖项：
- 不包含：
```

标题要短，适合直接作为 Jira Summary。
“用户故事”正文要聚焦价值，不写实现方式。

### 5. Check INVEST

输出前逐项自检：

- Independent：是否可以独立开发与交付
- Negotiable：是否避免限定实现方案
- Valuable：是否明确说明业务价值
- Estimable：是否足够明确便于估算
- Small：是否能在 1-2 个迭代内完成
- Testable：验收标准是否具体可验证

若故事明显过大，先建议拆分，再继续输出。

### 6. Offer Jira Action

仅在用户故事内容确认后，才询问是否需要同步到 Jira。
若用户同意，再执行 Jira 创建或更新。

## Story Rules

始终遵守以下原则：

- 将用户故事视为沟通工具，而不是设计文档
- 重点写清楚做什么、为什么做
- 验收标准必须可验证、可转成测试用例
- 不写前端框架、数据库结构、API 名称、类设计、算法实现
- 可以写业务约束、集成对象、性能指标、权限边界、数据来源

如果用户输入中已经带有明显技术方案，保留其业务约束，但主动剥离不必要的实现细节。

## Acceptance Criteria

优先写 3-7 条验收标准，覆盖主流程、异常和边界。

根据场景选择表达方式：

- 复杂交互：使用 Given-When-Then
- 简单功能：使用直接陈述式
- 配置或规则类：使用检查清单式

验收标准至少覆盖：

1. 核心功能完成
2. 关键状态变化或结果展示
3. 主要异常或失败场景
4. 必要的边界条件

仅在用户明确提出时，再加入性能、兼容性、无障碍或安全方面的验收标准。

详细模式与反例见 [acceptance-criteria.md](./references/acceptance-criteria.md)。

## Output Guidance

输出保持短小、清晰、可直接讨论。若内容较长，优先拆成多个小节，每段控制在约 200-300 字，并在关键节点询问用户是否满意。

默认输出顺序：

1. 一句话确认理解
2. 用户故事卡片
3. 如有需要，给出拆分建议或待确认问题
4. 询问是否创建或更新 Jira

## Jira Integration

项目 Key 固定为 `AL`。
创建 Issue 时使用 `Story` 类型，除非用户明确要求其他类型。
默认优先使用 Jira MCP 工具执行，而不是只停留在文案草稿。

创建或更新 Jira 前必须满足：

- 用户已确认故事内容
- 标题、正文、验收标准已完整
- 需要的标签、依赖或备注已收集到位

默认映射：

- Summary：简洁标题
- Description：完整故事内容
- Labels：按功能语义添加，如 `frontend`、`backend`、`feature`、`integration`

详细执行步骤见 [jira-execution.md](./references/jira-execution.md)。

### Jira Description Structure

Jira 描述中至少包含：

- 背景或目标
- 用户故事
- 验收标准
- 约束/依赖/不包含项（如适用）

ADF 结构与示例见 [jira-adf.md](./references/jira-adf.md)。

### Jira Action Rules

- 创建前先明确征求用户同意
- 更新已有 Jira 内容时，优先使用 ADF 结构组织描述
- 如果当前工具只接受 Markdown 输入，则先按工具能力创建，再在可行时转为 ADF 更新
- 不要在未经确认的情况下自动创建多张卡片
- 如果用户没有提供现有 Jira Key，默认执行创建而不是搜索后盲改
- 如果用户提供了 Jira Key，则优先更新该卡片，而不是新建重复 Story
- 如果一个需求应拆成多张 Story，先给出拆分方案并逐项确认，再批量创建
- 创建或更新完成后，返回 Jira Key、Summary，以及你实际写入的核心内容摘要

## Examples

### Clear Request

用户说：

> 我需要一个用户登录功能，支持邮箱和密码登录。

直接整理为用户故事，并补齐缺失但必要的验收标准，例如登录成功、密码错误、必填校验。

### Vague Request

用户说：

> 我想做一个数据展示功能。

不要直接写故事。先澄清：

- 谁看这个数据
- 想做监控、分析还是汇报
- 最关心什么指标
- 什么情况下算满足需求

## Resource Map

- 用户故事模板与拆分建议：见 [story-patterns.md](./references/story-patterns.md)
- 验收标准写法、分类与反例：见 [acceptance-criteria.md](./references/acceptance-criteria.md)
- Jira ADF 描述结构：见 [jira-adf.md](./references/jira-adf.md)
- Jira MCP 执行步骤与字段映射：见 [jira-execution.md](./references/jira-execution.md)