Preamble (run first)
bash "$(dirname "${BASH_SOURCE[0]}")"/check-update.sh 2>/dev/null || true
# 检查方案设计目录
mkdir -p docs/02-方案设计
# 检查前置文档
echo "📊 正在检查前置文档..."
if [ -f "docs/02-方案设计/PRD产品需求文档.md" ]; then
echo "✅ PRD文档 - 已找到"
else
echo "⏳ PRD文档 - 未找到"
fi
if [ -f "docs/02-方案设计/功能细节拆解.md" ]; then
echo "✅ 功能细节拆解 - 已找到"
else
echo "⏳ 功能细节拆解 - 未找到"
fi
执行流程
digraph pm_user_story {
rankdir=TB;
node [shape=box, style=filled, fillcolor="#e3f2fd"];
"选择故事范围" [shape=box, fillcolor="#bbdefb"];
"读取前置数据" [shape=box, fillcolor="#bbdefb"];
"确认编写原则" [shape=box, fillcolor="#bbdefb"];
"识别Epic故事" [shape=box, fillcolor="#c8e6c9"];
"编写Story故事" [shape=box, fillcolor="#ffe0b2"];
"Story拆分优化" [shape=box, fillcolor="#ffe0b2"];
"优先级排序" [shape=box, fillcolor="#fff9c4"];
"输出故事清单" [shape=box, fillcolor="#fff9c4"];
subgraph cluster_subagent {
label="Subagent 并行编写";
style=filled;
fillcolor="#f3e5f5";
"Epic1 Story编写" [shape=box, fillcolor="#e1bee7"];
"Epic2 Story编写" [shape=box, fillcolor="#e1bee7"];
"Epic3 Story编写" [shape=box, fillcolor="#e1bee7"];
"验收标准生成" [shape=box, fillcolor="#e1bee7"];
"Epic1 Story编写" -> "合并汇总" [style=dashed];
"Epic2 Story编写" -> "合并汇总" [style=dashed];
"Epic3 Story编写" -> "合并汇总" [style=dashed];
"验收标准生成" -> "合并汇总" [style=dashed];
"合并汇总" [shape=box, fillcolor="#d1c4e9"];
}
"选择故事范围" -> "读取前置数据";
"读取前置数据" -> "确认编写原则";
"确认编写原则" -> "识别Epic故事";
"识别Epic故事" -> "编写Story故事";
"编写Story故事" -> "Story拆分优化";
"Story拆分优化" -> "优先级排序";
"优先级排序" -> "输出故事清单";
}
步骤 1: 选择用户故事范围
使用 AskUserQuestion 询问：
您需要编写哪方面的用户故事？
A) 全部功能用户故事（基于PRD功能列表） B) 单个模块的用户故事（请指定模块） C) 单个功能的用户故事（请指定功能） D) Epic级用户故事（高层次需求） E) 其他（请手动输入）
💡 提示：
- Sprint规划 → 推荐单个模块的用户故事
- 产品规划 → 推荐Epic级用户故事
- 开发准备 → 推荐全部功能用户故事
记录到变量 STORY_SCOPE
步骤 2: 读取前置数据
根据范围读取相应文档：
必需文档：
- PRD产品需求文档（如果存在）
- 功能细节拆解（如果存在）
可选文档：
- MVP方案
- 用户画像
读取失败处理：
如果 PRD 文档不存在：
⚠️ 未找到 PRD 文档
用户故事需要明确的功能需求作为输入。
您可以选择： A) 执行 /pm-docs 生成 PRD B) 使用功能细节拆解作为输入 C) 手动输入功能需求（快速模式）
步骤 3: 用户故事编写原则
📝 用户故事标准格式：
作为 <角色> 我想要 <功能> 以便于 <价值>验收标准（BDD格式）：
GIVEN <前置条件> WHEN <触发操作> THEN <预期结果>是否继续编写？
A) 理解了，开始编写 B) 我需要更多示例 C) 我有特定的编写规范
步骤 4: Epic级用户故事
4.1 识别Epic
基于PRD识别出Epic：
| Epic ID | Epic名称 | 描述 | 包含Story数 |
|---|---|---|---|
| E001 | 用户管理 | 用户注册、登录、信息管理 | 5 |
| E002 | 商品浏览 | 商品列表、搜索、详情 | 4 |
| E003 | 购物车管理 | 加入购物车、编辑、结算 | 3 |
| E004 | 订单管理 | 订单创建、支付、查看 | 6 |
是否需要调整Epic划分？
A) 划分合理，继续 B) 需要调整 C) 我有其他划分方式
4.2 Epic详细描述
对每个Epic进行描述：
**Epic: E001 用户管理**
作为 产品系统
我想要 提供用户管理功能
以便于 用户可以注册登录，管理个人信息
业务价值：
- 用户可以拥有个人账号
- 支持个性化服务
- 提供用户数据用于数据分析
包含Story：US001-US005
优先级：P0
预估工时：5人天
逐个对每个Epic确认后继续。
步骤 5: Story级用户故事
5.1 逐个编写Story
对每个功能，按以下模板编写用户故事：
US001: 用户注册
作为 新用户 我想要 通过手机号注册账号 以便于 拥有个人账号，享受个性化服务验收标准 - 场景1：正常注册
GIVEN 用户未注册过，打开注册页面 WHEN 用户输入手机号、验证码、密码，点击"注册" THEN 创建账号成功，自动登录，跳转到首页场景2：手机号已注册
GIVEN 手机号已注册 WHEN 用户输入该手机号 THEN 提示"已注册，请直接登录"场景3：验证码错误
GIVEN 用户已获取验证码 WHEN 输入错误验证码 THEN 提示"验证码错误"，允许重新输入技术备注：验证码5分钟有效，密码bcrypt加密 依赖：无 风险：验证码发送失败 → 提供邮箱注册备选
这个用户故事是否完整？
A) 完整，继续下一个Story B) 需要调整 C) 需要补充更多场景
逐个Story编写，直到功能列表完成。
5.2 Subagent 并行编写（v2.0 增强）
如果有大量Story（>10个），使用 Agent 工具并行生成：
使用 Agent 工具并行派发：
Agent 1: 编写Epic1的所有Story
- 输入：Epic1 描述 + 功能列表
- 输出：完整用户故事（含验收标准）
Agent 2: 编写Epic2的所有Story
- 输入：Epic2 描述 + 功能列表
- 输出：完整用户故事（含验收标准）
Agent 3: 编写Epic3的所有Story
- 输入：Epic3 描述 + 功能列表
- 输出：完整用户故事（含验收标准）
Agent 4: 验收标准生成
- 输入：所有 Story 列表
- 输出：每个 Story 的 BDD 验收标准
主 agent 等待所有 subagent 完成，合并汇总输出最终文档。
版本对比（v1 vs v2）
| 维度 | v1（串行） | v2（Subagent 并行） |
|---|---|---|
| Story 编写 | 逐个编写 | Subagent 按 Epic 并行编写 |
| 验收标准 | 手动逐条编写 | Subagent 批量生成 |
| Token 占用 | 全部 Story 占用主上下文 | Subagent 独立上下文 |
| 执行效率 | 线性顺序 | 并行 3-4x 加速 |
步骤 6: Story拆分
对于复杂的Story（Story Point > 8 或 验收标准过多），进行拆分：
🔍 Story拆分建议：
US004: 购物车管理 → 拆分为：
- US004-1: 加入购物车
- US004-2: 查看购物车
- US004-3: 编辑购物车商品数量
- US004-4: 删除购物车商品
是否接受拆分？
A) 接受拆分 B) 我有其他拆分方式 C) 不需要拆分
步骤 7: Story优先级排序
基于业务价值和依赖关系排序：
P0（必须有）：US001注册、US002登录、US006商品列表、US008商品详情、US010加入购物车、US014订单创建、US015订单支付
P1（应该有）：US003找回密码、US004个人信息、US007搜索、US011购物车编辑
P2（可以有）：US008收藏、US009评价、US014取消订单
是否需要调整优先级？
步骤 8: 输出用户故事清单
使用 Write 工具创建 docs/02-方案设计/用户故事清单.md。
参考 references/output-template.md 模板，文档结构如下：
- 用户故事总览 - Epic清单（ID、名称、描述、Story数、优先级、工时）
- Epic详情及Story清单 - 每个Epic下的Story列表
- 完整用户故事 - 每个Story的完整描述（角色、功能、价值、验收标准）
- Story依赖关系图 - 依赖关系图示
- Sprint规划建议 - Sprint划分和工时估算
- 附录 - 用户故事模板、Story Point指南
兜底机制
场景 1: 无前置文档
提供手动输入模式，允许用户逐个输入功能需求。
场景 2: 用户中途退出
保存已编写的Story列表到草稿文件。
注意事项
- INVEST原则：每个Story应独立（Independent）、可协商（Negotiable）、有价值（Valuable）、可估算（Estimable）、小型（Small）、可测试（Testable）
- 验收标准：每个Story至少包含1个正常场景和1个异常场景
- Story Point：使用斐波那契数列（1,2,3,5,8,13）
- 完整输出模板参见：
references/output-template.md
输出质量对比
✅ Good 示例：
- 有数据引用：「根据 Q4 数据，留存率从 35% 降至 28%」
- 有验证来源：「数据来源：Google Analytics, 2025-12-01」
- 有明确建议：「建议将新手引导步骤从 5 步减少至 3 步」
❌ Bad 示例：
- 模糊结论：「数据表明留存率有所下降」
- 无来源：「根据经验，这个功能很重要」
- 没有行动建议：「留存是个问题」
常见误区 / Red Flags — STOP
出现以下情况立即停止并回溯：
| 误区 | 正确做法 |
|---|---|
| 使用"应该"、"大概"、"看起来"做结论 | 必须基于实际数据和验证 |
| 未运行检查就声称已完成 | 先验证，再陈述 |
| 因时间紧迫跳过关键步骤 | 没有例外，时间紧更要严格 |
| "这次应该没问题"的想法 | 每次都要重新验证 |
产出质量检查 / Verification Checklist
- 前置依赖已满足（输入文档/数据已收集）
- 核心步骤已全部执行
- 输出文档已生成到
docs/目录 - 每个判断都有数据/证据支撑
- 已推荐 2-3 个后续 skill
⚠️ 任何一项未通过 → 补全后再标记完成。