187
.claude/rules/ralph-loops.md
Normal file
187
.claude/rules/ralph-loops.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# Ralph Loop Guide
|
||||
|
||||
## What is a Ralph Loop?
|
||||
|
||||
A Ralph Loop is an autonomous AI development pattern where a language model is invoked repeatedly in a loop, performing exactly one task per iteration. Each iteration is a **fresh context** — the model has no memory of previous runs. Persistence is achieved through files: the model reads project state from disk at the start of each iteration and writes its results back before stopping.
|
||||
|
||||
The name originates from [Geoffrey Huntley's technique](https://ghuntley.com/loop/) for autonomous coding with Claude Code. The core insight: by constraining each iteration to a single task and using files as shared memory, you get reliable, incremental progress without context window exhaustion.
|
||||
|
||||
Sources and further reading:
|
||||
|
||||
- [Geoffrey Huntley — Everything is a Ralph Loop](https://ghuntley.com/loop/)
|
||||
- [snarktank/ralph — Original implementation](https://github.com/snarktank/ralph)
|
||||
- [frankbria/ralph-claude-code — Claude Code adaptation](https://github.com/frankbria/ralph-claude-code)
|
||||
|
||||
## How Ralph Works in This Project
|
||||
|
||||
### Directory Structure
|
||||
|
||||
Each Ralph run lives in its own directory under `.ralph/`:
|
||||
|
||||
```
|
||||
.ralph/
|
||||
└── my-run/
|
||||
├── instructions.md # Agent prompt (user-created, required)
|
||||
├── meta.md # Run metadata (auto-generated)
|
||||
├── chief-wiggum.md # Chief Wiggum directives (auto-generated template)
|
||||
├── answers.md # Human answers to questions (auto-generated template)
|
||||
├── questions.md # Questions raised by Ralph (auto-generated template)
|
||||
├── progress.txt # Iteration log (auto-generated template)
|
||||
└── run.log # Execution log (auto-generated)
|
||||
```
|
||||
|
||||
### The Iteration Cycle
|
||||
|
||||
```
|
||||
┌─────────────────────────────────┐
|
||||
│ ralph.sh starts iteration N │
|
||||
│ │
|
||||
│ 1. Read project state │
|
||||
│ (files listed in │
|
||||
│ instructions.md) │
|
||||
│ │
|
||||
│ 2. Select ONE task │
|
||||
│ (by priority order) │
|
||||
│ │
|
||||
│ 3. Execute that task │
|
||||
│ (edit files as needed) │
|
||||
│ │
|
||||
│ 4. Append summary to │
|
||||
│ progress.txt │
|
||||
│ │
|
||||
│ 5. Stop │
|
||||
│ (or emit COMPLETE signal) │
|
||||
└────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
ralph.sh checks output
|
||||
for <promise>COMPLETE</promise>
|
||||
│
|
||||
┌────┴────┐
|
||||
│ Found? │
|
||||
├─Yes─────┼──► Loop ends
|
||||
└─No──────┘
|
||||
│
|
||||
▼
|
||||
Sleep 2s, start iteration N+1
|
||||
```
|
||||
|
||||
### File Roles
|
||||
|
||||
Each run directory contains files with specific roles:
|
||||
|
||||
| File | Purpose | Who writes it |
|
||||
|------|---------|---------------|
|
||||
| `instructions.md` | Defines what Ralph does, which files to read, task priorities | Human (before run) |
|
||||
| `progress.txt` | Append-only iteration log — Ralph's memory across iterations | Ralph |
|
||||
| `chief-wiggum.md` | Directives from the Chief Wiggum session | Chief Wiggum |
|
||||
| `answers.md` | Human answers to Ralph's questions | Human |
|
||||
| `questions.md` | Questions Ralph raises when encountering ambiguity | Ralph |
|
||||
| `meta.md` | Run metadata (date, model, config) | Auto-generated |
|
||||
| `run.log` | Execution log (start/stop times, iteration count) | ralph.sh |
|
||||
|
||||
## How to Run Ralph
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```bash
|
||||
./ralph.sh .ralph/my-run
|
||||
```
|
||||
|
||||
This runs the default configuration: up to 20 iterations, using Claude Opus, with Read/Edit/Write tools.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
The run directory must contain an `instructions.md` file. All other files are auto-created as templates if they don't exist.
|
||||
|
||||
### Options
|
||||
|
||||
```bash
|
||||
./ralph.sh <run-directory> [options]
|
||||
|
||||
Options:
|
||||
-n, --max-iterations N Maximum iterations (default: 20)
|
||||
-m, --model MODEL Claude model to use (default: opus)
|
||||
-t, --tools TOOLS Allowed tools, quoted (default: "Read Edit Write")
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Short run with cheaper model
|
||||
./ralph.sh .ralph/my-run -n 10 -m sonnet
|
||||
|
||||
# Run with more tools (e.g. for coding tasks)
|
||||
./ralph.sh .ralph/my-run -n 30 -t "Read Edit Write Bash Glob Grep"
|
||||
|
||||
# New run
|
||||
mkdir .ralph/my-new-task
|
||||
# Write .ralph/my-new-task/instructions.md, then:
|
||||
./ralph.sh .ralph/my-new-task -n 15
|
||||
```
|
||||
|
||||
### Path Convention in instructions.md
|
||||
|
||||
Use `{{RUN_DIR}}` as a placeholder for run-specific files. The script substitutes it automatically before passing the prompt to Claude:
|
||||
|
||||
```
|
||||
{{RUN_DIR}}/progress.txt # run-specific
|
||||
{{RUN_DIR}}/chief-wiggum.md # run-specific
|
||||
{{RUN_DIR}}/answers.md # run-specific
|
||||
{{RUN_DIR}}/questions.md # run-specific
|
||||
```
|
||||
|
||||
All other file paths are relative to the project root as usual.
|
||||
|
||||
## How to Communicate with Ralph
|
||||
|
||||
Ralph cannot be talked to directly. Communication happens through files:
|
||||
|
||||
### As Chief Wiggum (directing Ralph)
|
||||
|
||||
Edit `chief-wiggum.md` in the run directory **before** starting the loop:
|
||||
|
||||
- **`## Action Required`** — Ralph MUST address these, one per iteration, in order.
|
||||
- **`## Observations`** — Informational notes. Ralph may use them but is not required to act.
|
||||
|
||||
Ralph never modifies `chief-wiggum.md`. To confirm an item was addressed, check `progress.txt`.
|
||||
|
||||
### As the Human (answering questions)
|
||||
|
||||
When Ralph raises a question in `questions.md`, write your answer in `answers.md` in the run directory. On the next iteration, Ralph will process the answer.
|
||||
|
||||
### Monitoring Progress
|
||||
|
||||
- **`progress.txt`** — Append-only log of every iteration. What Ralph did and why.
|
||||
- **`run.log`** — Execution metadata (start time, iterations, completion status).
|
||||
- **Project files** — Diff the files Ralph was allowed to edit to see actual changes.
|
||||
|
||||
## Writing instructions.md
|
||||
|
||||
The `instructions.md` file defines Ralph's behavior for a run. Key elements:
|
||||
|
||||
1. **Role definition** — What is Ralph doing? (Refining stories, writing code, reviewing, ...)
|
||||
2. **One-task-per-iteration rule** — Always enforce this. Without it, the model tries to do everything at once and produces lower-quality results.
|
||||
3. **Startup sequence** — Which files to read and in what order. This is Ralph's "memory load." Use `{{RUN_DIR}}` for run-specific files.
|
||||
4. **Task selection priorities** — A strict priority list. Ralph picks the first applicable task, does it, and stops.
|
||||
5. **File ownership table** — What Ralph may read vs. write. Prevents accidental overwrites.
|
||||
6. **Completion signal** — How Ralph signals that all work is done (`<promise>COMPLETE</promise>`).
|
||||
7. **Guardrails** — Rules to prevent Ralph from making unauthorized decisions.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Do
|
||||
|
||||
- **Keep iterations small.** One task per iteration produces better results than batching.
|
||||
- **Use progress.txt as memory.** Ralph reads it every iteration. Be explicit about what was done and what was deferred.
|
||||
- **Clean up chief-wiggum.md** between runs. Remove addressed items to avoid confusion.
|
||||
- **Review diffs after the loop.** Ralph is autonomous but not infallible. Spot-check the changes.
|
||||
- **Use the right model.** Opus for complex reasoning tasks, Sonnet for straightforward work.
|
||||
- **Match tools to the task.** Read/Edit/Write for spec work. Add Bash/Glob/Grep for coding tasks.
|
||||
|
||||
### Don't
|
||||
|
||||
- **Don't modify files Ralph owns during a run.** File conflicts will confuse the model.
|
||||
- **Don't give Ralph tools it doesn't need.** Minimal tool sets reduce unintended side effects.
|
||||
- **Don't expect Ralph to remember across iterations.** Every iteration is a fresh context. If it's not in a file, it doesn't exist.
|
||||
- **Don't skip instructions.md.** Running without a structured prompt loses the task selection that makes Ralph reliable.
|
||||
Reference in New Issue
Block a user