using-user-stories

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Working with User Stories

使用用户故事开展工作

Document and track feature implementation with user stories. Workflow for authoring stories, building features, and marking acceptance criteria as passing.

User stories document what features should do and track implementation status. When AI agents work through user stories systematically, they produce better results and leave a clear trail of what was done.

使用用户故事记录并跟踪功能实现。包含编写故事、构建功能以及标记验收标准为通过的工作流。

用户故事记录了功能应实现的内容并跟踪实施状态。当AI Agent系统地处理用户故事时，它们能产出更好的结果，并留下清晰的工作轨迹。

Workflow

工作流

When working on features:

Author/Update: Create or modify user story features before building
Build & Test: Implement until tests pass
Mark Passing: Set
```
passes: true
```
when verified

处理功能时：

编写/更新：在构建前创建或修改用户故事功能
构建与测试：实施直至测试通过
标记为通过：验证后设置
```
passes: true
```

When to Create User Stories

何时创建用户故事

Create user stories when:

Starting a new feature or flow
Fixing a bug that should have test coverage
Implementing requirements from a design or spec
Breaking down a large feature into testable increments

在以下场景创建用户故事：

启动新功能或流程时
修复应具备测试覆盖的漏洞时
实施来自设计或规范的需求时
将大型功能拆分为可测试的增量部分时

Writing Effective Steps

编写有效的步骤

Steps should be:

Verifiable: Each step can be checked by running the app or tests
Imperative: Written as commands ("Navigate to", "Click", "Verify")
Specific: Include URLs, button names, expected values

Good:

json

{
  "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
}

Avoid vague steps:

json

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

步骤应满足：

可验证：每个步骤都可以通过运行应用或测试来检查
命令式：以命令形式编写（如“导航至”、“点击”、“验证”）
具体：包含URL、按钮名称、预期值

示例：

json

{
  "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
}

避免模糊步骤：

json

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

Documenting Work Done

记录已完成的工作

When completing a feature:

Verify all steps work manually or via tests
Update
```
passes: true
```
in the user story
Commit both the implementation and the updated story

This creates a log of completed work that future agents can reference.

完成功能时：

通过手动或测试验证所有步骤均可正常运行
在用户故事中更新
```
passes: true
```
提交实现代码和更新后的故事

这会创建一份已完成工作的日志，供后续Agent参考。

Using with AI Agents

与AI Agent配合使用

AI agents can read user stories to:

Understand what features need to be built
Know the exact acceptance criteria
Find features that still need work (
```
passes: false
```
)
Log their progress by marking features as passing

For automated agent loops, see the Ralph Agent Loop recipe.

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

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

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

Verifying Stories

验证故事

Run the verification script to check all stories have valid format:

bash

bun run user-stories:verify

This validates:

All files are valid JSON
Each feature has required fields
Steps are non-empty strings
Shows pass/fail counts per file

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

bash

bun run user-stories:verify

此脚本会验证：

所有文件都是有效的JSON
每个功能都包含必填字段
步骤为非空字符串
显示每个文件的通过/失败计数