AI Intermediate Bash

Ralph - PRD 驱动的自主式 AI 编码循环系统

自主式 AI 编码 Agent 循环系统，PRD 驱动，GitHub 17k Stars 的开源 AI 编程工具

GitHub: snarktank/ralph (16,017 stars) 2026年4月13日

aiai-agentclaudeautonomous-coding

What is Ralph?

Ralph 是一个自主式 AI 编码 Agent 循环系统。它以 prd.json（产品需求文档的 JSON 格式）为驱动，反复调用 AI 编码工具（Amp 或 Claude Code），每次迭代都是一个全新上下文窗口的 AI 实例，独立完成一个用户故事（User Story），然后更新进度并继续下一个，直到所有任务完成或达到最大迭代次数。

Ralph 基于 Geoffrey Huntley 提出的 Ralph 模式。核心思路是：将大任务拆成小到可以在单次上下文窗口内完成的故事，由 AI 自主循环执行，同时通过 git 历史、progress.txt 和 prd.json 在迭代间传递上下文。

Installation

前置依赖

# Amp CLI（默认）- 参见 https://ampcode.com

# Claude Code（备选）
npm install -g @anthropic-ai/claude-code

# jq（必须）
brew install jq   # macOS
# Linux: sudo apt install jq

安装方式一：复制到项目（推荐）

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

安装方式二：Claude Code Marketplace

/plugin marketplace add snarktank/ralph
/plugin install ralph-skills@ralph-marketplace

First Example

1. 创建 PRD：

Load the prd skill and create a PRD for adding a priority field to tasks

2. 转换为 Ralph 格式：

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

3. 运行 Ralph：

./scripts/ralph/ralph.sh                    # 默认 Amp，最多 10 次迭代
./scripts/ralph/ralph.sh --tool claude     # 使用 Claude Code
./scripts/ralph/ralph.sh --tool claude 20  # 指定迭代次数

How It Works

Ralph 执行流程：

从 prd.json 读取 branchName 创建特性分支
选取最高优先级且 passes: false 的故事
实现该故事
运行质量检查（typecheck / lint / test）
通过则提交：feat: [Story ID] - [Story Title]
更新 prd.json 标记 passes: true
向 progress.txt 追加学习笔记
重复直到全部完成或达到最大迭代

Core Features

🔄 迭代式自主执行：每次循环启动全新的 AI 实例，干净上下文不撑爆
📋 PRD 驱动：prd.json 定义用户故事 ID、标题、描述、验收标准和优先级
🛠️ 双工具支持：Amp CLI（默认）和 Claude Code（--dangerously-skip-permissions）
💾 自动上下文持久化：git 历史 + progress.txt + prd.json
📝 AGENTS.md / CLAUDE.md 自动更新：可复用模式写入，供后续迭代参考

Advanced Topics

prd.json 结构

{
  "project": "MyApp",
  "branchName": "ralph/task-priority",
  "description": "任务优先级系统",
  "userStories": [
    {
      "id": "US-001",
      "title": "添加优先级数据库字段",
      "description": "作为开发者，我需要存储任务优先级以便持久化。",
      "acceptanceCriteria": [
        "tasks 表添加 priority 列",
        "生成并成功运行迁移",
        "类型检查通过"
      ],
      "priority": 1,
      "passes": false
    }
  ]
}

字段	说明
`branchName`	自动创建此分支
`priority`	越小越先执行
`passes`	完成前为 false
`acceptanceCriteria`	质量检查标准

故事大小原则（最关键）

每个故事必须在单次上下文窗口内完成。

✅ 合适的故事	❌ 太大需拆分的故事
添加一个数据库列和迁移	”构建整个仪表盘”
在已有页面添加 UI 组件	”添加身份验证”
更新一个 Server Action	”重构整个 API 层”

Amp autoHandoff 配置

上下文快满时自动启动新实例接力：

// ~/.config/amp/settings.json
{
  "amp.experimental.autoHandoff": { "context": 90 }
}

Best Practices

1. PRD 先行

先用 /prd 技能生成完整需求，再转换为 prd.json，不要直接手工写 JSON。

2. 故事粒度要小

宁可多拆几个小故事，也不要一个大故事跨越多次迭代。

3. 重视 AGENTS.md / CLAUDE.md 更新

每次迭代发现的模式、坑和上下文都值得记录，这些是 AI 后续迭代最重要的知识来源。

4. CI 必须保持绿色

提交前确保 typecheck、lint、test 全部通过。坏代码会在迭代间累积，越早发现越好。

5. progress.txt 只追加不覆盖

append-only 方式保留完整历史，供回溯分析。

6. 设置合理的 max_iterations

任务规模	推荐迭代次数
小功能	5-10 次
大型功能	20-50 次

FAQ

Q: Ralph 和直接让 AI 写代码有什么区别？

A: 直接让 AI 写代码会受上下文窗口限制，Ralph 通过每次启动新实例 + prd.json 驱动的循环解决了这个问题。

Q: 迭代间 AI 不会遗忘之前的工作吗？

A: 不会。git 历史保存代码变更，progress.txt 保存学习笔记，prd.json 保存状态。

Q: Ralph 支持哪些 AI 工具？

A: 主要支持 Amp CLI 和 Claude Code（--dangerously-skip-permissions）。

Q: 可以同时运行多个 Ralph 实例吗？

A: 不建议。依赖 prd.json 和 progress.txt 作为状态文件，多实例会竞争状态。

Next Steps

GitHub 仓库 — 源码和示例
交互式流程图 — Ralph 执行流程可视化
Ralph 模式原始文章 — 设计思想
Amp CLI — AI 编程工具