ralph-prd

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ralph PRD Generation

Ralph PRD 生成

Generate

prd.json

files that define scoped work items for autonomous agent execution. Each item has explicit completion criteria and verification steps.

生成用于自主Agent执行的、定义了限定范围工作项的

prd.json

文件。每个工作项都包含明确的完成标准和验证步骤。

When to Use

适用场景

Batch migrations (API changes, library upgrades, lint fixes)
Large-scale refactoring across many files
Any task decomposable into independent, verifiable units
Work that benefits from "done" being explicitly defined

批量迁移（API变更、库版本升级、Lint修复）
跨多文件的大规模代码重构
任何可分解为独立可验证单元的任务
需要明确定义“完成状态”的工作

PRD Structure

PRD 结构

json

{
  "instructions": "<markdown with context, examples, constraints>",
  "items": [
    {
      "id": "<unique identifier>",
      "category": "<task category>",
      "description": "<what needs to be done>",
      "file": "<target file path>",
      "steps": [
        "<action step>",
        "<verification step>"
      ],
      "passes": false,
      "skipped": null
    }
  ]
}

json

{
  "instructions": "<包含上下文、示例、约束的Markdown内容>",
  "items": [
    {
      "id": "<唯一标识符>",
      "category": "<任务分类>",
      "description": "<需要完成的工作内容>",
      "file": "<目标文件路径>",
      "steps": [
        "<操作步骤>",
        "<验证步骤>"
      ],
      "passes": false,
      "skipped": null
    }
  ]
}

Field Reference

字段说明

Field	Purpose
`instructions`	Markdown embedded in PRD - transformation examples, docs links, constraints
`id`	Unique identifier (typically file path or task name)
`category`	Groups related items
`description`	Human-readable summary
`steps`	Actions + verification commands
`passes`	`false` initially, `true` when complete
`skipped`	`null` or `"<reason>"` if task cannot be completed

字段	用途
`instructions`	嵌入在PRD中的Markdown内容 - 包含转换示例、文档链接、约束条件
`id`	唯一标识符（通常为文件路径或任务名称）
`category`	对相关工作项进行分组
`description`	易读的工作项摘要
`steps`	操作步骤 + 验证命令
`passes`	初始值为 `false` ，完成后设为 `true`
`skipped`	若任务无法完成，设为 `"<原因>"` ，否则为 `null`

Generation Workflow

生成流程

PRD Generation Progress:
- [ ] Step 1: Define scope (what files/items are affected?)
- [ ] Step 2: Gather input data (lint output, file list, API changes)
- [ ] Step 3: Design item granularity (per-file, per-error, per-component?)
- [ ] Step 4: Define verification steps (type-check, tests, lint)
- [ ] Step 5: Write instructions (examples, constraints, skip conditions)
- [ ] Step 6: Generate items (script or manual)
- [ ] Step 7: Review sample items

PRD 生成进度:
- [ ] 步骤1：定义范围（涉及哪些文件/工作项？）
- [ ] 步骤2：收集输入数据（Lint输出、文件列表、API变更内容）
- [ ] 步骤3：设计工作项粒度（按文件、按错误、按组件？）
- [ ] 步骤4：定义验证步骤（类型检查、测试、Lint校验）
- [ ] 步骤5：编写说明内容（示例、约束、跳过条件）
- [ ] 步骤6：生成工作项（通过脚本或手动方式）
- [ ] 步骤7：审核样本工作项

Clarifying Questions

需要明确的问题

Before generating, resolve these with the user:

在生成PRD前，需与用户确认以下问题：

Granularity

粒度选择

Per-file? Per-error? Per-component?
Trade-off: fewer items = less overhead, more items = finer progress tracking

按文件？按错误？按组件？
权衡：工作项越少 = 管理开销越低，工作项越多 = 进度跟踪越精细

Verification Steps

验证步骤

What commands confirm completion?
Type-check? Tests? Lint? Build?
Which tests - related test file only, or broader?

用哪些命令确认任务完成？
类型检查？测试？Lint校验？构建？
测试范围 - 仅相关测试文件，还是更广泛的测试？

Instructions Content

说明内容

What context does the executing agent need?
Before/after examples?
Links to documentation?
Type casting or naming conventions?

执行Agent需要哪些上下文信息？
是否需要提供前后对比示例？
是否需要链接到相关文档？
类型转换或命名规范？

Skip Conditions

跳过条件

What should cause an item to be skipped rather than fixed?
Example: "class component requires manual refactor"

哪些情况应标记工作项为跳过而非修复？
示例：“类组件需要手动重构”

Path Format

路径格式

Relative or absolute paths?
ID format (filename only risks collisions)

相对路径还是绝对路径？
ID格式（仅用文件名可能会导致冲突）

Instructions Section Best Practices

说明部分的最佳实践

The

instructions

field is markdown that the executing agent reads. Include:

Violation/task types with before/after examples
Scope rules - what's in bounds, what's out
Skip conditions - when to mark
```
skipped: "<reason>"
```
instead of fixing
Links to relevant documentation
Type/naming conventions specific to the codebase

Keep instructions focused. The agent discovers patterns; instructions provide guardrails.

instructions

字段是供执行Agent读取的Markdown内容，应包含：

违规/任务类型及前后对比示例
范围规则 - 哪些内容在范围内，哪些不在
跳过条件 - 何时应标记
```
skipped: "<原因>"
```
而非修复
相关文档链接
代码库特定的类型/命名规范

说明内容应聚焦重点。Agent会自主发现模式，说明仅需提供规则边界。

Verification Steps

验证步骤

Each item should have at least one verification step. Common patterns:

json

"steps": [
  "Fix all N lint errors for rule-name",
  "Run yarn type-check:go - must pass",
  "Run yarn test <path> - if test exists"
]

For test detection, check:

__tests__/<filename>.test.{ts,tsx,js,jsx}

```
<filename>.test.{ts,tsx,js,jsx}
```
sibling
```
__tests__/integration/<filename>.test.*
```

每个工作项至少包含一个验证步骤。常见模式：

json

"steps": [
  "修复所有N个rule-name规则下的Lint错误",
  "运行yarn type-check:go - 必须通过",
  "若存在测试文件则运行yarn test <路径>"
]

检测测试文件时，可检查以下路径：

__tests__/<filename>.test.{ts,tsx,js,jsx}

同级目录下的
```
<filename>.test.{ts,tsx,js,jsx}
```
```
__tests__/integration/<filename>.test.*
```

Example: Generating from Lint Output

示例：从Lint输出生成PRD

Input: JSON array of lint errors grouped by file

javascript

const prd = {
  instructions: `## Migration Instructions...`,
  items: lintErrors.map(entry => ({
    id: entry.filePath.replace(REPO_ROOT + '/', ''),
    category: 'migration',
    description: `Fix violations in ${path.basename(entry.filePath)}`,
    file: entry.filePath,
    errorCount: entry.errorCount,
    steps: [
      `Fix all ${entry.errorCount} lint errors`,
      'Run yarn type-check:go - must pass',
      ...(testExists ? [`Run yarn test ${testPath}`] : [])
    ],
    passes: false,
    skipped: null
  }))
};

输入：按文件分组的Lint错误JSON数组

javascript

const prd = {
  instructions: `## 迁移说明...`,
  items: lintErrors.map(entry => ({
    id: entry.filePath.replace(REPO_ROOT + '/', ''),
    category: 'migration',
    description: `修复${path.basename(entry.filePath)}中的违规问题`,
    file: entry.filePath,
    errorCount: entry.errorCount,
    steps: [
      `修复全部${entry.errorCount}个Lint错误`,
      '运行yarn type-check:go - 必须通过',
      ...(testExists ? [`Run yarn test ${testPath}`] : [])
    ],
    passes: false,
    skipped: null
  }))
};

Anti-Patterns

反模式

Vague verification

模糊的验证步骤

json

// Bad
"steps": ["Fix the issue", "Make sure it works"]

// Good  
"steps": ["Fix lint error on line 42", "Run yarn type-check:go - must pass"]

json

// 错误示例
"steps": ["修复问题", "确保可用"]

// 正确示例  
"steps": ["修复第42行的Lint错误", "运行yarn type-check:go - 必须通过"]

Missing skip conditions

缺失跳过条件

If some items can't be completed (e.g., requires larger refactor), define skip conditions in instructions so agents mark

skipped

instead of attempting impossible fixes.

若部分工作项无法完成（例如：需要更大规模的重构），需在说明中定义跳过条件，以便Agent标记

skipped

而非尝试不可能的修复。

Over-scoped items

范围过大的工作项

Items that touch many files are harder to verify and resume. Prefer one file per item for file-based migrations.

涉及多个文件的工作项更难验证和恢复。对于基于文件的迁移，建议每个工作项对应一个文件。

Under-specified instructions

说明内容不明确

The executing agent shouldn't have to guess conventions. Specify type casting, naming patterns, import sources.

执行Agent不应需要猜测规范。需明确指定类型转换、命名模式、导入来源。