ralph

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ralph PRD Converter

Ralph PRD 转换器

Converts existing PRDs to the prd.json format that Ralph uses for autonomous execution.

将现有PRD转换为Ralph用于自主执行的prd.json格式。

The Job

任务内容

Take a PRD (markdown file or text) and convert it to

prd.json

in your ralph directory.

将PRD（Markdown文件或文本）转换为你的ralph目录下的

prd.json

文件。

Output Format

输出格式

json

{
  "project": "[Project Name]",
  "branchName": "ralph/[feature-name-kebab-case]",
  "description": "[Feature description from PRD title/intro]",
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": [
        "Criterion 1",
        "Criterion 2",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

json

{
  "project": "[Project Name]",
  "branchName": "ralph/[feature-name-kebab-case]",
  "description": "[Feature description from PRD title/intro]",
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": [
        "Criterion 1",
        "Criterion 2",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Story Size: The Number One Rule

用户故事规模：首要规则

Each story must be completable in ONE Ralph iteration (one context window).

Ralph spawns a fresh Amp instance per iteration with no memory of previous work. If a story is too big, the LLM runs out of context before finishing and produces broken code.

每个用户故事必须能在一次Ralph迭代（一个上下文窗口）内完成。

Ralph每次迭代都会生成一个全新的Amp实例，不会保留之前工作的记忆。如果用户故事过大，大语言模型会在完成前耗尽上下文，导致生成的代码出现问题。

Right-sized stories:

合适规模的用户故事：

Add a database column and migration
Add a UI component to an existing page
Update a server action with new logic
Add a filter dropdown to a list

添加数据库列和迁移脚本
向现有页面添加UI组件
使用新逻辑更新服务端动作
向列表添加筛选下拉框

Too big (split these):

过大的用户故事（需要拆分）：

"Build the entire dashboard" - Split into: schema, queries, UI components, filters
"Add authentication" - Split into: schema, middleware, login UI, session handling
"Refactor the API" - Split into one story per endpoint or pattern

Rule of thumb: If you cannot describe the change in 2-3 sentences, it is too big.

"构建完整的仪表盘" - 拆分为：数据库模式、查询语句、UI组件、筛选功能
"添加认证功能" - 拆分为：数据库模式、中间件、登录UI、会话处理
"重构API" - 拆分为每个端点或模式对应一个用户故事

**经验法则：**如果你无法用2-3句话描述变更内容，说明这个故事太大了。

Story Ordering: Dependencies First

用户故事排序：依赖优先

Stories execute in priority order. Earlier stories must not depend on later ones.

Correct order:

Schema/database changes (migrations)
Server actions / backend logic
UI components that use the backend
Dashboard/summary views that aggregate data

Wrong order:

UI component (depends on schema that does not exist yet)
Schema change

用户故事按优先级顺序执行。前面的故事不能依赖后面的故事。

正确顺序：

数据库模式/变更（迁移脚本）
服务端动作/后端逻辑
调用后端的UI组件
聚合数据的仪表盘/汇总视图

错误顺序：

UI组件（依赖尚未存在的数据库模式）
数据库模式变更

Acceptance Criteria: Must Be Verifiable

验收准则：必须可验证

Each criterion must be something Ralph can CHECK, not something vague.

每条准则必须是Ralph可以检查的内容，而非模糊描述。

Good criteria (verifiable):

良好的准则（可验证）：

"Add
```
status
```
column to tasks table with default 'pending'"
"Filter dropdown has options: All, Active, Completed"
"Clicking delete shows confirmation dialog"
"Typecheck passes"
"Tests pass"

"向tasks表添加
```
status
```
列，默认值为'pending'"
"筛选下拉框的选项：全部、进行中、已完成"
"点击删除按钮显示确认对话框"
"类型检查通过"
"测试通过"

Bad criteria (vague):

糟糕的准则（模糊）：

"Works correctly"
"User can do X easily"
"Good UX"
"Handles edge cases"

"正常工作"
"用户可以轻松完成X操作"
"良好的用户体验"
"处理边缘情况"

Always include as final criterion:

必须包含的最终准则：

"Typecheck passes"

For stories with testable logic, also include:

"Tests pass"

"Typecheck passes"

对于包含可测试逻辑的故事，还需添加：

"Tests pass"

For stories that change UI, also include:

对于变更UI的故事，还需添加：

"Verify in browser using dev-browser skill"

Frontend stories are NOT complete until visually verified. Ralph will use the dev-browser skill to navigate to the page, interact with the UI, and confirm changes work.

"Verify in browser using dev-browser skill"

前端故事只有在视觉验证后才算完成。Ralph会使用dev-browser技能导航到页面、与UI交互并确认变更正常工作。

Conversion Rules

转换规则

Each user story becomes one JSON entry
IDs: Sequential (US-001, US-002, etc.)
Priority: Based on dependency order, then document order
All stories:
```
passes: false
```
and empty
```
notes
```
branchName: Derive from feature name, kebab-case, prefixed with
```
ralph/
```
Always add: "Typecheck passes" to every story's acceptance criteria

每个用户故事对应一个JSON条目
ID：按顺序编号（US-001、US-002等）
优先级：基于依赖顺序，再参考文档顺序
所有故事：
```
passes: false
```
且
```
notes
```
为空
branchName：从功能名称衍生，使用短横线命名法，前缀为
```
ralph/
```
必须添加：每个故事的验收准则中包含"Typecheck passes"

Splitting Large PRDs

拆分大型PRD

If a PRD has big features, split them:

Original:

"Add user notification system"

Split into:

US-001: Add notifications table to database
US-002: Create notification service for sending notifications
US-003: Add notification bell icon to header
US-004: Create notification dropdown panel
US-005: Add mark-as-read functionality
US-006: Add notification preferences page

Each is one focused change that can be completed and verified independently.

如果PRD包含大型功能，需要拆分：

原始需求：

"添加用户通知系统"

拆分后：

US-001：向数据库添加通知表
US-002：创建用于发送通知的通知服务
US-003：向页面头部添加通知铃铛图标
US-004：创建通知下拉面板
US-005：添加标记为已读功能
US-006：添加通知偏好设置页面

每个都是独立的聚焦变更，可以单独完成和验证。

Example

示例

Input PRD:

markdown

undefined

输入PRD：