The “Ralph loop” is a popular workflow but nobody, at least to me, seems to explain it in layman’s terms
The repo says stuff like this:
“Ralph is an autonomous AI agent loop that runs repeatedly until all PRD items are complete.”
It references the term PRD repeatedly without ever defining it, or even trying to define it.
I’ve worked in software for many years now (ow my back) and hadn’t come across the word PRD…So wtf is it?
A PRD (“project requirements document”) is just a TODO list
Your “PRD” can just be a markdown file (e.g. PRD.md) with checkboxes like a
normal TODO list:
- [ ] Add priority column to tasks table
- [ ] Show priority badge on task cards
- [ ] Add priority selector to task edit modal
- [ ] Filter tasks by priority, persist in URL
You don’t even need the checkbox brackets if you want.
The important part is that you are going to let the AI also manage your TODO list. As it is working, it will be reading the TODOs, and writing what it has completed or discovered, and adding further TODOs.
You be the Ralph
The Ralph concept, as originally proposed, uses an autonomous loop that keeps running to solve all the todo items.
However, you don’t have to use this to get a lot of the benefits
Just use Claude like usual but start each session with:
read PRD.md, and continue working on tasks. update PRD.md when done
You can be pretty loosy goosy with the wording, just type whatever you want to alert Claude to work on the TODOs. Then you can just use the Claude interface to steer it mid-task as usual, and do whatever you normally do
Conclusion
This post might be a really obvious post for some. I dunno. I just wanted to convey that there is nothing mysterious behind the idea of a “PRD”…it is just a TODO list, and that you do not have to go full Ralph to get the majority of the benefits from having your AI power through your todos
If I’m missing something let me know. Enjoy :)
Footnote - Why did I write this? Or where am I coming from when writing this?
I recently told myself that I need to be even more ambitious in my use of Claude for coding.
However, once you are trying to tackle very large tasks, you can end up having a lot of ongoing parallel todos. I was having some challenges keeping track of all this, and had a LOT of back and forth with the bots.
This method is a way that can help potentially. Hence, “Maximizing agentic coding”. Note that I am also not strict about making each Claude session only solve one task at a time and stuff like that. Just do what works for you
Footnote 2 - the Ralph loop
I made this a footnote because it is not really the focus of my article to focus on the autonomous ralph loop, I just wanted to highlight the concept of the TODO list. But for reference, the ralph concept uses a bash shell script similar to this
while true ; do
OUTPUT =$( claude --dangerously-skip-permissions --print < CLAUDE.md)
if echo " $ OUTPUT " | grep -q "<promise>COMPLETE</promise>" ; then
exit 0
fi
done
so it’s a bash loop that just keeps running Claude until the literal string
<promise>COMPLETE</promise> is found in the output via grep and then, the
entire TODO list is done. The CLAUDE.md from the ralph repo (read the raw text
https://raw.githubusercontent.com/snarktank/ralph/refs/heads/main/CLAUDE.md) is
what tells it to output this special string, and do one task at a time, and
various other things.
Side note1 : What is this the <promise> tag? It is not explained in the ralph
repo. It’s just an arbitrary signal string for the grep. Could be anything as
long as the agent wouldn’t accidentally produce it in normal output.
Side note 2: the ralph github repo also uses a json format for prd.json and a
progress.txt but this stuff isn’t really needed since the plain markdown format
for the PRD.md is fine (feel free to also just call it todo.md)
Footnote 3
If this post, again, still sounds really dumb and obvious but you haven’t tried just giving Claude your entire todo list, try it. You may want to spend a little bit creating the todo list. And like I said above…do ambitious things!