snarktank/ralph

项目介绍

Ralph 把 AI 编码命令行工具（默认 Amp，也支持 Claude Code）包进一个 bash 循环。你提供由 PRD 转换出的 prd.json，它每轮启动一个干净上下文的 Agent 实例，只实现一条故事，运行类型检查和测试，通过后提交、把该故事标为 passes: true，并把经验追加到 progress.txt；全部故事通过或达到迭代上限后退出。思路来自 Geoffrey Huntley 的 Ralph 模式。

各轮之间不共享对话上下文，记忆只靠 git 历史、progress.txt 和 prd.json。Ralph 还会把发现的约定和坑写进相关的 AGENTS.md，供后续轮次和开发者复用。

快速使用

准备：已安装并认证 Amp CLI 或 Claude Code，安装 jq，并有一个 git 仓库。

1. 把循环脚本和提示词复制进项目：

mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/
cp /path/to/ralph/prompt.md scripts/ralph/prompt.md    # Amp
# 或：cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md
chmod +x scripts/ralph/ralph.sh

2. 用 /prd 技能生成 PRD，再用 /ralph 转成 prd.json；README 的另两种方式分别把技能装到 Amp/Claude Code 全局配置，或通过 Claude Code 插件市场安装。

3. 在项目根目录运行：

./scripts/ralph/ralph.sh 20              # 默认 Amp，最多 20 轮
./scripts/ralph/ralph.sh --tool claude 20

全部故事变为 passes: true 后，脚本输出 <promise>COMPLETE</promise> 并停止。排查状态可用 cat prd.json | jq '.userStories[] | {id, title, passes}'、cat progress.txt 和 git log --oneline -10。

使用 Amp 时，README 建议在 ~/.config/amp/settings.json 中设置 "amp.experimental.autoHandoff": { "context": 90 } 启用自动交接。

使用约束

• 每条故事必须小到单个上下文窗口能完成；「构建整个仪表盘」「增加认证」这类大任务会降低产出质量。
• 依赖真实反馈回路：类型检查和测试必须可运行、CI 保持通过，否则坏代码会在多轮之间累积。
• 前端故事需在验收标准中写明浏览器验证，README 默认使用 dev-browser 技能。
• 每次运行按 PRD 的 branchName 建分支；换分支名开始新功能时，旧运行会归档到 archive/YYYY-MM-DD-feature-name/。
• 需要 jq、git 仓库和已认证的 Amp 或 Claude Code，许可证为 MIT。

HotRepo 点评

2026-11-08 的记录显示项目有 22,155 Star、2,098 Fork，当日新增 17 Star，并登上 TypeScript 日榜第 10 位。目前只有一条快照，这个名次只能说明当天的情况，不足以判断长期趋势。值得关注的是它把「每次新上下文」做成核心机制：不靠一个长会话，而是让 PRD 待办和 git 提交充当记忆，适合已经在用 Amp 或 Claude Code、并愿意保持任务小而测试常绿的团队。