using-user-stories

使用用户故事

使用用户故事记录和跟踪功能实现。了解如何编写故事、构建功能，以及将验收标准标记为通过。

用户故事用于记录功能应有的行为，并跟踪实现状态。AI Agent 按照用户故事系统地开展工作时，能取得更好的成果，并清晰记录已完成的工作。

---

工作流

开发功能时：

1. 编写／更新：构建前创建或修改用户故事中的功能
2. 构建与测试：持续实现，直到测试通过
3. 标记为通过：验证通过后设置 passes: true

---

何时创建用户故事

在以下情况下创建用户故事：

• 开始开发新功能或流程
• 修复需要测试覆盖的错误
• 实现设计或规范中的需求
• 将大型功能拆分为可测试的增量

---

编写有效的步骤

步骤应当：

• 可验证：每个步骤都能通过运行应用或测试来检查
• 采用祈使句：写成命令（“前往”“点击”“验证”）
• 具体明确：包含 URL、按钮名称和预期值

示例：

{
  "description": "User deletes a chat",
  "steps": [
    "Navigate to /chats",
    "Click the menu button on a chat",
    "Click 'Delete' option",
    "Confirm deletion in dialog",
    "Verify chat is removed from list"
  ],
  "passes": false
}

避免含糊的步骤：

{
  "description": "User deletes a chat",
  "steps": ["Delete a chat", "Check it worked"],
  "passes": false
}

---

记录已完成的工作

完成一项功能时：

1. 手动或通过测试验证所有步骤均有效
2. 在用户故事中更新 passes: true
3. 同时提交实现代码和更新后的用户故事

这样就能记录已完成的工作，供后续 Agent 参考。

---

与 AI Agent 配合使用

AI Agent 可以读取用户故事，以便：

• 了解需要构建哪些功能
• 掌握确切的验收标准
• 找出仍需处理的功能（passes: false）
• 通过将功能标记为通过来记录进度

有关自动化 Agent 循环，请参阅 Ralph Agent Loop 配方。

---

验证故事

运行验证脚本，检查所有故事的格式是否有效：

bun run user-stories:verify

该脚本会验证：

• 所有文件都是有效的 JSON
• 每项功能都包含必需字段
• 步骤均为非空字符串
• 显示每个文件的通过／失败数量