Ralph最佳实践：避免10个常见陷阱，确保AI代理高效运行

林菁琚

645人浏览 · 2026-03-18 00:22:10

林菁琚 · 2026-03-18 00:22:10 发布

Ralph最佳实践：避免10个常见陷阱，确保AI代理高效运行

【免费下载链接】ralph Ralph is an autonomous AI agent loop that runs Amp repeatedly until all PRD items are complete. 项目地址: https://gitcode.com/gh_mirrors/ralph1/ralph

Ralph是一个创新的自主AI代理循环系统，能够运行AI编码工具（如Amp或Claude Code）反复执行，直到所有PRD（产品需求文档）项目完成。这个强大的工具通过git历史、progress.txt和prd.json实现记忆持久化，每个迭代都是具有干净上下文的新实例。本文将分享10个关键的最佳实践，帮助您避免常见陷阱，确保Ralph AI代理高效运行。

1. 正确规划PRD：避免任务过大导致失败

核心问题：每个用户故事必须能够在一个Ralph迭代中完成（一个上下文窗口内）。如果任务过大，LLM会在完成之前耗尽上下文，产生错误的代码。

正确做法：

适当大小的故事：添加数据库列和迁移、向现有页面添加UI组件、更新具有新逻辑的服务器操作、向列表添加过滤器下拉菜单
需要拆分的过大任务：构建整个仪表板、添加身份验证、重构API

关键文件：skills/ralph/SKILL.md 提供了详细的任务拆分指南。

2. 合理排序用户故事：确保依赖关系正确

常见陷阱：UI组件依赖于尚未存在的数据库模式。

正确顺序：

架构/数据库变更（迁移）
服务器操作/后端逻辑
使用后端的UI组件
聚合数据的仪表板/摘要视图

检查点：在创建prd.json之前，确保没有故事依赖于后面的故事。

3. 编写可验证的验收标准

错误示例："工作正常"、"用户可以轻松执行X"、"良好的用户体验"、"处理边缘情况"

正确示例：

"向tasks表添加status列，默认值为'pending'"
"过滤器下拉菜单具有选项：全部、活动、已完成"
"点击删除显示确认对话框"
"类型检查通过"
"测试通过"

关键规则：每个故事的最后必须包含"Typecheck passes"作为验收标准。对于UI故事，还必须包含"使用dev-browser技能在浏览器中验证"。

4. 充分利用AGENTS.md文件

最佳实践：在每个迭代后更新相关的AGENTS.md文件。这是关键，因为AI编码工具会自动读取这些文件，因此未来的迭代（以及未来的人类开发人员）可以从发现的模式、陷阱和约定中受益。

应添加到AGENTS.md的内容：

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

避免添加：故事特定的实现细节、临时调试笔记、已存在于progress.txt中的信息。

5. 正确配置反馈循环

关键检查点：

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

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

6. 有效管理进度记录

正确格式：始终追加到progress.txt（永远不要替换，始终追加）：

## [日期/时间] - [故事ID]
线程：https://ampcode.com/threads/$AMP_CURRENT_THREAD_ID
- 实现了什么
- 更改的文件
- **未来迭代的学习：**
  - 发现的模式（例如，"这个代码库使用X来做Y"）
  - 遇到的陷阱（例如，"更改W时不要忘记更新Z"）
  - 有用的上下文（例如，"评估面板在组件X中"）
---

整合模式：如果发现可重用模式，添加到progress.txt顶部的"## 代码库模式"部分（如果不存在则创建）。仅添加通用且可重用的模式，而不是故事特定的细节。

7. 正确处理工具选择

配置选项：

使用Amp（默认）：./scripts/ralph/ralph.sh [最大迭代次数]
使用Claude Code：./scripts/ralph/ralph.sh --tool claude [最大迭代次数]

关键文件：ralph.sh 脚本支持两种工具，确保根据您的环境正确配置。

8. 正确设置停止条件

完成信号：当所有故事都有passes: true时，Ralph输出<promise>COMPLETE</promise>，循环退出。

调试状态：

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

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

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

9. 正确归档先前运行

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

手动检查：在编写新的prd.json之前，检查是否存在来自不同功能的现有prd.json：

读取当前的prd.json（如果存在）
检查branchName是否与新功能的branchName不同
如果不同且progress.txt的内容超出标题：
- 创建归档文件夹：archive/YYYY-MM-DD-feature-name/
- 将当前的prd.json和progress.txt复制到归档
- 使用新标题重置progress.txt

10. 定制提示模板

项目特定定制：将prompt.md（用于Amp）或CLAUDE.md（用于Claude Code）复制到项目后，为您的项目定制它：

添加项目特定的质量检查命令
包含代码库约定
为您的技术栈添加常见陷阱

关键指令：每个迭代只处理一个故事，频繁提交，保持CI绿色，在开始前阅读progress.txt中的代码库模式部分。

总结

通过遵循这10个最佳实践，您可以确保Ralph AI代理系统高效运行，避免常见陷阱。记住，Ralph的成功依赖于适当的任务分解、正确的依赖排序、可验证的验收标准以及有效的知识共享机制。通过精心设计的PRD和遵循这些指南，您可以充分利用这个强大的自主AI代理系统，显著提高开发效率。

重要提醒：始终从[prd.json.example](https://link.gitcode.com/i/632772e869821b50b5073267c89fa93b)开始，确保您的PRD格式正确，并定期检查progress.txt中的学习内容，这些是Ralph系统持续改进的关键。

【免费下载链接】ralph Ralph is an autonomous AI agent loop that runs Amp repeatedly until all PRD items are complete. 项目地址: https://gitcode.com/gh_mirrors/ralph1/ralph