From PRD to Code: How Ralph’s Autonomous AI Agent Loop Automates Development

Core Principle

Ralph runs a Bash loop script ( ralph.sh) that, for each iteration, starts a fresh AI instance (Amp or Claude Code), reads prd.json, processes a single explicit task, runs quality checks, commits the result, updates state files, and proceeds to the next iteration.

创建 PRD
    ↓
转换为 JSON → prd.json（任务清单）
    ↓
ralph.sh（Bash 循环）
    ↓
启动 AI 实例 → 读取 prd.json → 选择未完成任务
    ↓
实现单个任务 → 运行质量检查 → 提交代码 → 更新 AGENTS.md / CLAUDE.md
    ↓
更新 prd.json → 将经验写入 progress.txt → 进入下一轮
    ↓
所有任务完成 → 输出 <promise>COMPLETE</promise>

Each iteration uses a brand‑new context window; the AI does not rely on prior conversation memory but reads external state from the Git history, progress.txt and prd.json. This avoids context overflow and guarantees that every step works from an auditable project state.

Core Concepts

New AI instance per iteration – a fresh model context reduces error risk.

External state storage

Git history records project changes and conventions. progress.txt stores current progress and key learnings. prd.json holds the task list and completion status.

Small‑Task Principle – tasks must be small enough to finish within a single iteration. Examples of suitable tasks: add a DB column, add a UI component, modify server logic. Tasks that are too large (full dashboard, full auth system, major API refactor) should be split.

AGENTS.md / CLAUDE.md updates – after each iteration Ralph appends learned patterns, pitfalls, and useful context to these files. Subsequent AI instances read them, forming a continuous learning loop.

Feedback loop

Type checking (e.g., tsc --noEmit).

Unit tests (e.g., npm test).

Custom checks as needed.

Workflow

The end‑to‑end process consists of three steps.

1. Create PRD

# Load PRD skill and create requirement document
加载 prd 技能，为「你的功能描述」创建 PRD

The tool interacts with the user to confirm details and saves a structured PRD to tasks/prd‑[feature‑name].md.

2. Convert to Ralph format

# Load Ralph skill and convert PRD
加载 ralph 技能，将 tasks/prd‑[feature‑name].md 转换为 prd.json

The PRD is parsed into a JSON task list ( prd.json).

3. Run Ralph Loop

# Use Amp (default)
./ralph/ralph.sh [max_iterations]
# Use Claude Code
./ralph/ralph.sh --tool claude [max_iterations]

Key parameters: --tool: amp or claude. max_iterations: default 10.

During each iteration Ralph:

Creates a feature branch based on branchName in prd.json ( git checkout -b feature/your‑feature‑name).

Selects the highest‑priority unfinished user story.

Runs the task in a fresh AI instance.

Executes quality checks (type check, unit tests, custom commands).

If checks pass, commits code:

git add .
git commit -m "feat: [Story ID] - [Story Title]"

Updates prd.json to mark the task as completed.

Writes learnings to progress.txt (patterns, pitfalls, useful context).

Repeats or exits when all tasks are done, outputting <promise>COMPLETE</promise>.

Quick‑Start Guide

Prerequisites

AI coding tool (choose one): Amp CLI or Claude Code. jq for JSON processing (install via winget install jqlang.jq on Windows or brew install jq on macOS).

Initialize a Git repository in the project.

Installation Methods

Method 1 – Copy into Project

# In project root
mkdir -p ralph
cp /path/to/ralph/ralph.sh ralph/
cp /path/to/ralph/prompt.md ralph/prompt.md   # for Amp
# or
cp /path/to/ralph/CLAUDE.md ralph/CLAUDE.md   # for Claude Code
chmod +x ralph/ralph.sh

Method 2 – Global Skill Installation

# For Amp
cp -r skills/prd ~/.config/amp/skills/
cp -r skills/ralph ~/.config/amp/skills/
# For Claude Code
cp -r skills/prd ~/.claude/skills/
cp -r skills/ralph ~/.claude/skills/

Method 3 – Claude Code Plugin (Recommended)

# Add marketplace
/plugin marketplace add snarktank/ralph
# Install plugin
/plugin install ralph-skills@ralph-marketplace

Hands‑On Example: Building a Todo App with Claude Code

Step 1 – Initialise Project

# Create project
mkdir ralph-todo-app
cd ralph-todo-app
git init

Step 2 – Create PRD

/prd 创建一个简单、可扩展的 Todo 应用，支持本地持久化。功能包括：新增、编辑、删除以及筛选待办事项

The AI generates tasks/prd‑todo‑app.md with the full requirement.

Step 3 – Convert to Ralph Format

/ralph tasks/prd‑todo‑app.md

The result is a prd.json containing a list of user stories.

Step 4 – Copy Ralph Files

cp ~/.claude/plugins/marketplaces/ralph-marketplace/ralph.sh ralph/
cp ~/.claude/plugins/marketplaces/ralph-marketplace/CLAUDE.md ralph/CLAUDE.md
chmod +x ralph/ralph.sh

Step 5 – Run the Loop

# Windows (Git Bash)
sh ./ralph/ralph.sh --tool claude 10
# macOS / Linux
./ralph/ralph.sh --tool claude 10

The loop creates feature branches, implements each story, runs tsc --noEmit and npm test, commits, and records progress.

Step 6 – Inspect Progress

cat progress.txt

Shows learned patterns, pitfalls, and useful context for the next iteration.

Step 7 – Review Git History

git log --oneline ralph/todo-app

Each commit is atomic and easily reversible.

Best Practices & Tips

Browser validation : use dev‑browser or playwright skills to automatically open a browser, navigate, and verify UI behavior.

Monitoring & debugging : inspect prd.json with jq, view progress.txt, and check recent Git commits.

Custom prompt templates : tailor prompt.md (Amp) or CLAUDE.md (Claude) with project‑specific quality checks, coding conventions, and known pitfalls.

Suitable scenarios : feature iteration, small module development, clear PRD with acceptance criteria, rapid MVP prototyping.

Unsuitable scenarios : exploratory development with vague requirements, large‑scale refactoring, security‑critical code, deep performance optimisation.

Common Questions

Q1: Ralph gets stuck in an iteration

# Inspect unfinished tasks
cat prd.json | jq '.userStories[] | select(.passes == false)'
# Run checks manually
npm run typecheck
npm test
# Fix issues and restart
./ralph/ralph.sh

Q2: Task too large for a single context window

Manually split the task in prd.json or enable Amp’s auto‑handoff feature:

{
  "amp.experimental.autoHandoff": {
    "context": 90
  }
}

Q3: AGENTS.md / CLAUDE.md not updated correctly

Correct the file manually and add explicit instructions in the prompt template to ensure future iterations record learning accurately.

Conclusion

Ralph demonstrates a new AI‑programming paradigm: instead of relying on a single long‑running model, it repeatedly spawns fresh instances, each operating on a well‑defined task and sharing state through Git, progress.txt, and prd.json. This feedback‑driven loop trusts the model to improve through iteration, reduces context‑size limits, and keeps costs predictable.

References

[1] Ralph Loop Model – https://ghuntley.com/ralph/

[2] Interactive Flowchart – https://snarktank.github.io/ralph/

GitHub Repository – https://github.com/snarktank/ralph