ralph-marketplace

Ralph

English | 中文

中文版本

Ralph 是一个自主 AI 代理循环，反复运行 AI 编码工具（OpenCode 或 Claude Code）直到完成所有 PRD 项目。每次迭代都是一个具有干净上下文的新实例。内存通过 git 历史、progress.txt 和 prd.json 持续存在。

基于 Geoffrey Huntley 的 Ralph 模式。

前提条件

• 以下 AI 编码工具之一已安装并经过身份验证：
  • OpenCode CLI (默认)
  • Claude Code (npm install -g @anthropic-ai/claude-code)
• jq 已安装 (brew install jq on macOS)
• 您项目的 git 仓库

设置

方案 1：复制到您的项目

将 ralph 文件复制到您的项目中：

# 从您的项目根目录
mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/

# 为您的 AI 工具复制提示模板：
cp /path/to/ralph/AGENTS.md scripts/ralph/AGENTS.md    # For OpenCode and Claude Code

chmod +x scripts/ralph/ralph.sh

方案 2：全局安装技能

将技能复制到您的 OpenCode 或 Claude 配置中以供所有项目使用：

For OpenCode

cp -r skills/prd ~/.opencode/skills/
cp -r skills/ralph ~/.opencode/skills/

For Claude Code (manual)

cp -r skills/prd ~/.claude/skills/
cp -r skills/ralph ~/.claude/skills/

方案 3：使用 Claude Code Marketplace

将 Ralph marketplace 添加到 Claude Code：

/plugin marketplace add willin/ralph

然后安装技能：

/plugin install ralph-skills@ralph-marketplace

安装后可用的技能：

• /prd - 生成产品需求文档
• /ralph - 将 PRD 转换为 prd.json 格式

当您要求 Claude 时，技能会自动调用：

• "create a prd", "write prd for", "plan this feature"
• "convert this prd", "turn into ralph format", "create prd.json"

工作流程

1. 创建 PRD

使用 PRD 技能生成详细的需求文档：

Load the prd skill and create a PRD for [your feature description]

回答澄清问题。技能将输出保存到 tasks/prd-[feature-name].md。

2. 将 PRD 转换为 Ralph 格式

使用 Ralph 技能将 markdown PRD 转换为 JSON：

Load the ralph skill and convert tasks/prd-[feature-name].md to prd.json

这将创建带有为自主执行构建的用户故事的 prd.json。

3. 运行 Ralph

# 使用 OpenCode (默认)
./scripts/ralph/ralph.sh [max_iterations]

# 使用 Claude Code
./scripts/ralph/ralph.sh --tool claude [max_iterations]

默认为 10 次迭代。使用 --tool opencode 或 --tool claude 选择您的 AI 编码工具。

Ralph 将：

1. 创建功能分支（来自 PRD branchName）
2. 选择最高优先级的 passes: false 故事
3. 实现那个单独的故事
4. 运行质量检查（类型检查，测试）
5. 如果检查通过则提交
6. 更新 prd.json 将故事标记为 passes: true
7. 将学习成果追加到 progress.txt
8. 重复直到所有故事通过或达到最大迭代次数

关键文件

File	Purpose
ralph.sh	生成新 AI 实例的 bash 循环 (支持 --tool opencode 或 --tool claude)
AGENTS.md	OpenCode 和 Claude Code 的提示模板
prd.json	带有 passes 状态的用户故事（任务列表）
prd.json.example	示例 PRD 格式供参考
progress.txt	仅供追加的未来迭代学习成果
skills/prd/	生成 PRD 的技能（适用于 OpenCode 和 Claude Code）
skills/ralph/	将 PRD 转换为 JSON 的技能（适用于 OpenCode 和 Claude Code）
.claude-plugin/	Claude Code marketplace 发现的插件清单
flowchart/	Ralph 工作方式的交互式可视化

Flowchart

查看交互式流程图 - 点击查看每步的动画。

flowchart/ 目录包含源代码。本地运行：

cd flowchart
npm install
npm run dev

关键概念

每次迭代 = 新上下文

每次迭代都会生成一个具有干净上下文的新 AI 实例（OpenCode 或 Claude Code）。迭代之间唯一的内存是：

• Git 历史（来自先前迭代的提交）
• progress.txt（学习成果和上下文）
• prd.json（哪些故事已完成）

小任务

每个 PRD 项目应该足够小以在一个上下文窗口中完成。如果任务太大，LLM 会在完成之前耗尽上下文并产生糟糕的代码。

合适大小的故事：

• 添加数据库列和迁移
• 向现有页面添加 UI 组件
• 更新服务器操作并添加新逻辑
• 向列表添加筛选下拉菜单

太大（拆分这些）：

• "构建整个仪表盘"
• "添加身份验证"
• "重构 API"

AGENTS.md 更新至关重要

每次迭代后，Ralph 会用学习成果更新相关的 AGENTS.md 文件。这是关键，因为 AI 编码工具会自动读取这些文件，所以未来的迭代（以及未来的人类开发人员）会从发现的模式、陷阱和约定中受益。

应在 AGENTS.md 中添加的内容示例：

• 发现的模式（"这个代码库对 Y 使用 X"）
• 陷阱（"更改 W 时不要忘记更新 Z"）
• 有用上下文（"设置面板在组件 X 中"）

反馈循环

Ralph 只有在存在反馈循环时才能工作：

• 类型检查捕获类型错误
• 测试验证行为
• CI 必须保持绿色（损坏的代码会在迭代间累积）

UI 故事的浏览器验证

前端故事必须在验收标准中包含"使用 dev-browser 技能在浏览器中验证"。Ralph 将使用 dev-browser 技能导航到页面，与 UI 交互，并确认更改有效。

停止条件

当所有故事都具有 passes: true 时，Ralph 输出 <promise>COMPLETE</promise> 并退出循环。

调试

检查当前状态：

# 查看哪些故事已完成
cat prd.json | jq '.userStories[] | {id, title, passes}'

# 查看先前迭代的学习成果
cat progress.txt

# 检查 git 历史
git log --oneline -10

自定义提示

将 AGENTS.md（用于 OpenCode 或 Claude Code）复制到您的项目后，为其自定义：

• 添加特定于项目的质量检查命令
• 包括代码库约定
• 为您堆栈添加常见陷阱

归档

当您开始新功能时（不同的 branchName），Ralph 会自动归档以前的运行。归档保存到 archive/YYYY-MM-DD-feature-name/。

鸣谢与参考

本项目基于原始的 Ralph 模式，感谢以下贡献：

• Geoffrey Huntley's Ralph article - 原始 Ralph 模式的创建者
• OpenCode documentation - OpenCode 文档
• Claude Code documentation - Claude Code 文档
• Snarktank Ralph for AMP & Claude Code

English Version

Ralph is an autonomous AI agent loop that runs AI coding tools (OpenCode or Claude Code) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context. Memory persists via git history, progress.txt, and prd.json.