Aan de slag met Ralph Wiggum Deel 2: De driefasenmethodologie

Je hebt Ralph geïnstalleerd, een loop gedraaid, en... het werkte min of meer? Misschien liep het vast. Misschien draaide het in cirkels. Misschien bouwde het iets, maar niet helemaal wat je nodig had.

Dat is normaal. Ralph zonder structuur is als elke autonome agent—capabel maar richtingloos.

Dit deel behandelt de driefasenmethodologie: een praktische workflow om vage projectideeën om te zetten in werkende code terwijl jij slaapt.

Het kernidee: scheid planning van bouwen

Geoffrey Huntley beschrijft het als "Een trechter met 3 Fasen, 2 Prompts en 1 Loop." Hier is de uitsplitsing:

• Fase 1: Requirements — Jij + Claude in gesprek, specificaties en acceptatiecriteria definiëren
• Fase 2: Planning — Claude analyseert specs (read-only loop), levert een geprioriteerde TODO-lijst op
• Fase 3: Bouwen — Claude implementeert taken één voor één, commit, loopt door tot alles klaar is

De scheiding is cruciaal. Zoals The Ralph Playbook het stelt: "De PLANNING-prompt doet gap-analyse en levert een geprioriteerde TODO-lijst op—geen implementatie, geen commits. De BUILDING-prompt pakt taken op, implementeert, draait tests, commit."

Waarom dit werkt: De planningmodus voorkomt dat Claude in code duikt voordat het het volledige plaatje begrijpt. De bouwmodus blijft gefocust op één taak tegelijk in plaats van te ontsporen in chaos.

Fase 1: Requirements (het menselijke deel)

Dit is de enige fase die jouw actieve betrokkenheid vereist. En het is precies waar de meeste mensen bochten afsnijden—wat precies de reden is dat hun Ralph-sessies rommel opleveren.

Besteed minstens 30 minuten aan het doorpraten van requirements met Claude voordat je ook maar één regel code schrijft. Serieus. Dit gesprek is waar je de "oh wacht, hoe zit het met..."-momenten vangt die anders je autonome build zouden laten ontsporen.

Wat er in specs-bestanden komt

Maak specs/*.md-bestanden die de bron van waarheid worden. Denk niet te lang na over het formaat—focus op duidelijkheid:

Tip: Wil je een gestructureerde aanpak voor het verzamelen van requirements? Bekijk dan JeredBlu's PRD Creator—een conversationeel promptsysteem dat je begeleidt bij het maken van uitgebreide specificaties.

specs/
├── authentication.md    # Login, JWT, sessies
├── api-design.md        # Endpoints, request/response-formaten
├── database.md          # Schema, relaties
└── testing.md           # Dekkingsvereisten, teststrategie

Het gesprek dat ertoe doet

Zo verloopt een goed requirements-gesprek:

Jij: "Ik wil een REST API bouwen voor het beheren van todos"

Claude: "Laten we dit opsplitsen. Welke operaties heb je nodig?"

Jij: "CRUD-operaties - todos aanmaken, lezen, bijwerken en verwijderen"

Claude: "Begrepen. Hoe zit het met authenticatie? Gebruikersaccounts?"

Jij: "Ja, gebruikers mogen alleen hun eigen todos zien"

Claude: "Logisch. Hoe moeten we omgaan met..."

Dit heen-en-weer brengt randgevallen aan het licht waar je alleen niet aan zou denken. Na het gesprek genereert Claude gestructureerde specificaties die alles wat besproken is documenteren.

De investering betaalt zich terug: 30 minuten requirements-gesprek voorkomt uren waarin Ralph ronddraait op onduidelijke doelen.

Fase 2: Planning

Dit is een aparte modus die PROMPT_plan.md gebruikt. Je draait de planningmodus expliciet wanneer je je implementatieplan moet genereren of opnieuw moet genereren.

De planningmodus doet gap-analyse tussen specs en code en maakt een geprioriteerde TODO-lijst zonder enige implementatie of commits.

Twee manieren om Ralph te draaien

Er zijn twee methoden om Ralph-loops te draaien, en begrijpen wanneer je welke gebruikt is cruciaal:

Plugin-methode (/ralph-loop) — Draait iteraties binnen één contextvenster. Makkelijker op te zetten, goed voor kortere taken (minder dan 20-30 iteraties).

Bash Loop-methode (loop.sh) — Start een verse Claude-instantie per iteratie. Zoals Geoffrey Huntley's originele gids uitlegt, laadt elke iteratie "deterministisch dezelfde bestanden en leest de huidige staat van schijf." Dit voorkomt context-bloat en hallucinatie die kunnen optreden bij veel iteraties in één context. Zie community-voorbeelden: snarktank/ralph.sh, frankbria/ralph_loop.sh, peteristhegreat's gist.

Waarom verse context belangrijk is: De plugin draait alles in één contextvenster, dat na verloop van tijd vol raakt. Na 30-40 iteraties kan Claude delen van je prompt negeren of inconsistente beslissingen nemen. De bash loop-methode vermijdt dit door elke keer vers te starten—de enige gedeelde staat is wat naar schijf geschreven wordt (je code, IMPLEMENTATION_PLAN.md en progress.txt). Voor geavanceerde technieken, zie Advanced Context Engineering for Coding Agents.

We laten je zien hoe je loop.sh maakt in het gedeelte Het Bash Loop-script hieronder.

Planning draaien

Voor planning werkt de plugin-methode prima, aangezien je maar ~5 iteraties nodig hebt (context-bloat is geen probleem):

/ralph-loop "$(cat PROMPT_plan.md)" --max-iterations 5 --completion-promise "PLAN COMPLETE"

Of met de bash loop (zie Het Bash Loop-script hieronder):

./loop.sh plan

PROMPT_plan.md-template

Hier is het complete template voor de planningmodus. Voor praktijkvoorbeelden, zie ClaytonFarr's PROMPT_plan.md of snarktank's prompt.md.

# PLANNING MODE

You are in PLANNING mode. Your job is analysis, not implementation.

## Your Task
1. Read all files in specs/
2. Review the existing codebase in src/
3. Perform gap analysis between requirements and current implementation
4. Create/update IMPLEMENTATION_PLAN.md with prioritized tasks

## Task Structure
Each task in the plan should include:
- Unique ID (e.g., TASK-001, TASK-002)
- Priority level (high/medium/low)
- Clear description (what needs to be built)
- Acceptance criteria (how you'll know it's done)
- Required tests (specific test files or patterns)
- Dependencies (tasks that must complete first)

## File Organization
Organize tasks by priority:
- High Priority: Critical path items
- Medium Priority: Important but not blocking
- Low Priority: Nice-to-haves

## Critical Rules
- DO NOT write any code
- DO NOT make any commits
- DO NOT implement features
- DO NOT run tests or builds
- ONLY analyze and plan

When complete, output "PLAN COMPLETE"

Bekijk echte voorbeelden: Blader door daadwerkelijke promptbestanden uit de community:

• snarktank/ralph — Compleet prompt.md met AGENTS.md
• ClaytonFarr/ralph-playbook — PROMPT_plan.md-template
• frankbria/ralph-claude-code — Implementatie met exit-detectie

Wat planning oplevert

De planningmodus genereert:

IMPLEMENTATION_PLAN.md - Je levende TODO-lijst

Voorbeeldstructuur:

# Implementation Plan

## High Priority

### TASK-001: User Authentication
- **Status**: pending
- **Description**: Implement JWT-based auth with login/logout
- **Acceptance Criteria**:
  - User can register with email/password
  - User can login and receive JWT token
  - Protected routes require valid JWT
- **Tests**: `auth.test.ts`
- **Dependencies**: none

### TASK-002: Todo CRUD Endpoints
- **Status**: pending
- **Description**: Create POST, GET, PUT, DELETE endpoints for todos
- **Acceptance Criteria**:
  - POST /api/todos creates a todo
  - GET /api/todos returns user's todos
  - PUT /api/todos/:id updates a todo
  - DELETE /api/todos/:id deletes a todo
- **Tests**: `todos.test.ts`
- **Dependencies**: TASK-001

## Medium Priority

### TASK-003: Input Validation
- **Status**: pending
- **Description**: Add Zod validation for all endpoints
...

Belangrijk: Zoals The Ralph Playbook opmerkt, is het plan wegwerpbaar. Als het verouderd of onnauwkeurig wordt, verwijder het en genereer opnieuw door de planningmodus nogmaals te draaien.

Fase 3: Bouwen

Dit is de doorlopende loop-modus die PROMPT_build.md gebruikt. Hier schittert Ralph—autonoom taken implementeren terwijl jij slaapt.

Wat is backpressure? In de Ralph-methodologie verwijst backpressure naar geautomatiseerde validatiemechanismen—tests, type-checks, linters, builds—die onacceptabel werk afwijzen. In plaats van exact voor te schrijven hoe Claude iets moet implementeren, maak je "poorten" die slechte output afwijzen. Falende tests dwingen Claude om te itereren tot de code correct is. Dit is het kernidee achter autonome codeerloops.

De bouwmodus gaat ervan uit dat het plan bestaat, pakt één taak tegelijk op, implementeert deze met tests, commit, en loopt dan door met verse context.

Bouwmodus draaien

Snel starten met de plugin:

/ralph-loop "$(cat PROMPT_build.md)" --max-iterations 50 --completion-promise "ALL TASKS COMPLETE"

Voor langlopende builds (aanbevolen): Gebruik de bash loop-methode voor verse context per iteratie. Na het opzetten van loop.sh (hieronder getoond):

./loop.sh              # Standaardmodus is bouwen
./loop.sh build 100    # Met aangepast iteratielimiet

PROMPT_build.md-template

Hier is het complete template voor de bouwmodus. Voor praktijkvoorbeelden, zie ClaytonFarr's PROMPT_build.md of frankbria's PROMPT.md.

# BUILDING MODE

You are in BUILDING mode. Your job is implementation with quality gates.

## Your Task Loop
For each iteration:
1. Read IMPLEMENTATION_PLAN.md and progress.txt
2. Pick the SINGLE highest priority task with status: pending
3. Study existing code before implementing
4. Implement the feature completely
5. Write comprehensive tests
6. Run all tests and type checks: npm test && npm run type-check
7. If tests fail, fix them immediately—DO NOT proceed
8. When all tests pass:
   - Commit with descriptive message format: "feat(area): description"
   - Update task status to completed in IMPLEMENTATION_PLAN.md
   - Append learnings to progress.txt with timestamp

## Critical Rules
- Work on ONE task at a time—no exceptions
- NEVER commit failing tests
- NEVER skip test execution
- Tests are your backpressure—respect them
- Each commit must be atomic and working
- Don't add features not in the plan
- Don't refactor unrelated code

## Backpressure Enforcement
Tests MUST pass before committing:
```bash
npm test && npm run type-check && npm run lint
```

If any check fails, fix it in the same iteration.

## Progress Tracking
After completing each task, append to progress.txt:
```
[YYYY-MM-DD HH:MM] Completed TASK-XXX: Task Title
- What was implemented
- Key decisions made
- Challenges encountered
- Learnings for next tasks
```

When all tasks show status: completed, output "ALL TASKS COMPLETE"

Bekijk echte voorbeelden: Blader door daadwerkelijke PROMPT_build.md-implementaties:

• ClaytonFarr/ralph-playbook — PROMPT_build.md-template
• frankbria/ralph-claude-code — Implementatie met intelligente exit-detectie
• mikeyobrien/ralph-orchestrator — Verbeterde orkestratie-implementatie

Meer verdieping: Geoffrey Huntley's Don't Waste Your Back Pressure legt uit waarom validatie- en afwijzingsmechanismen cruciaal zijn voor autonome loops.

Het Bash Loop-script

Hier is een loop.sh-script dat zowel planning- als bouwmodus ondersteunt. Dit patroon komt van JeredBlu's gids en Geoffrey Huntley's originele aanpak:

#!/bin/bash
# loop.sh - Fresh context per iteration

MODE=${1:-build}  # Default to build mode
MAX_ITERATIONS=${2:-50}

if [[ "$MODE" == "plan" ]]; then
  PROMPT_FILE="PROMPT_plan.md"
  COMPLETION="PLAN COMPLETE"
  MAX_ITERATIONS=${2:-5}  # Planning needs fewer iterations
else
  PROMPT_FILE="PROMPT_build.md"
  COMPLETION="ALL TASKS COMPLETE"
fi

echo "Running in $MODE mode with max $MAX_ITERATIONS iterations"
echo "Using prompt: $PROMPT_FILE"
echo "Completion signal: $COMPLETION"
echo "=========================================="

for ((i=1; i<=$MAX_ITERATIONS; i++)); do
  echo "Iteration $i / $MAX_ITERATIONS"
  echo "--------------------------------"

  # The -p flag runs Claude in one-shot mode (see Mastery Part 1: https://jocv.dev/blog/claude-code-mastery-01-getting-started#one-shot-mode-quick-questions)
  result=$(claude -p "$(cat $PROMPT_FILE)" --output-format text 2>&1) || true
  echo "$result"

  if [[ "$result" == *"$COMPLETION"* ]]; then
    echo "=========================================="
    echo "$MODE complete after $i iterations."
    exit 0
  fi

  echo "--- End of iteration $i ---"
done

echo "Reached max iterations ($MAX_ITERATIONS)"
exit 1

Maak het uitvoerbaar:

chmod +x loop.sh

Gebruik:

./loop.sh plan      # Draai planningmodus (standaard 5 iteraties)
./loop.sh build     # Draai bouwmodus (standaard 50 iteraties)
./loop.sh           # Zelfde als ./loop.sh build
./loop.sh build 30  # Bouwmodus met maximaal 30 iteraties

Dit geeft je verse context per iteratie, waardoor de context-bloat die kan optreden bij de plugin-methode bij langlopende sessies wordt voorkomen.

Voor meer geavanceerde implementaties met foutafhandeling, logging en parallelle uitvoering, zie snarktank/ralph en mikeyobrien/ralph-orchestrator.

De bouwloop-flow

Zoals 11 Tips for AI Coding with Ralph Wiggum documenteert:

1. Pak de hoogste prioriteitstaak uit IMPLEMENTATION_PLAN.md
2. Implementeer de feature
3. Draai alle tests en type-checks (backpressure!)
4. Commit alleen als alles slaagt
5. Werk progress.txt bij met geleerde lessen
6. Loop met verse context → herhaal

Belangrijk inzicht: Elke iteratie draait in een vers contextvenster (met de bash loop-methode). Dit voorkomt contextdegradatie en houdt Claude gefocust.

Complete driefasen-workflow

Zo stroomt het allemaal samen (met het loop.sh-script uit het vorige gedeelte):

# Fase 1: Definieer Requirements (conversationeel, geen loop)
# Praat met Claude om specs/*.md-bestanden te maken
# Voorbeeld: specs/authentication.md, specs/api-design.md, specs/database.md

# Fase 2: Genereer Plan (draai eenmalig, of wanneer het plan ververst moet worden)
./loop.sh plan
# Of met de plugin: /ralph-loop "$(cat PROMPT_plan.md)" --max-iterations 5 --completion-promise "PLAN COMPLETE"
# Maakt IMPLEMENTATION_PLAN.md aan met geprioriteerde taken

# Fase 3: Bouw Autonoom (doorlopende loop)
./loop.sh
# Of met de plugin: /ralph-loop "$(cat PROMPT_build.md)" --max-iterations 50 --completion-promise "ALL TASKS COMPLETE"
# Implementeert taken één voor één, commit, loopt door

# Wanneer het plan verouderd raakt (features veranderd, nieuwe requirements):
rm IMPLEMENTATION_PLAN.md
./loop.sh plan          # Genereer plan opnieuw
./loop.sh               # Hervat bouwen

Bestandsstructuur

Je project moet deze structuur hebben:

jouw-project/
├── specs/
│   ├── authentication.md
│   ├── api-design.md
│   ├── database.md
│   └── testing.md
├── PROMPT_plan.md          # Planningmodus-prompt
├── PROMPT_build.md         # Bouwmodus-prompt
├── IMPLEMENTATION_PLAN.md  # Gegenereerd door planning, bijgewerkt door bouwen
├── progress.txt            # Append-only log van geleerde lessen
├── loop.sh                 # Bash-orchestratorscript
└── src/                    # Je daadwerkelijke code
    ├── api/
    ├── auth/
    └── tests/

Belangrijkste verschillen tussen modi

Planningmodus:

• Promptbestand: PROMPT_plan.md
• Doel: Analyseren & plannen
• Maakt commits? Nee
• Schrijft code? Nee
• Draait tests? Nee
• Werkt plan bij? Ja (maakt aan/overschrijft)
• Typisch aantal iteraties: 1-5
• Wanneer draaien? Eenmalig, of bij verversing van het plan

Bouwmodus:

• Promptbestand: PROMPT_build.md
• Doel: Implementeren & testen
• Maakt commits? Ja
• Schrijft code? Ja
• Draait tests? Ja
• Werkt plan bij? Ja (markeert taken als voltooid)
• Typisch aantal iteraties: 20-100+
• Wanneer draaien? Doorlopend tot alles klaar is

Essentiële bestanden voor langlopende Ralph-loops

progress.txt

Houd bij wat er over iteraties heen is bereikt. Zoals The Ralph Playbook uitlegt: "progress.txt is een standaardpraktijk voor langlopende agents. Geef het aan de agent via de prompt en gebruik het werkwoord 'append' om ervoor te zorgen dat eerdere invoer niet overschreven wordt."

Ralph leest dit om context te begrijpen zonder de codebase opnieuw te moeten verkennen.

Hoe je het gebruikt:

Instrueer in je prompt de agent om:
"Na elke taak, APPEND (overschrijf niet) je geleerde lessen aan progress.txt"

Voorbeeld progress.txt-invoer:

[2026-01-16 14:30] Completed TASK-001: User Authentication
- Implemented JWT signing/verification using jsonwebtoken
- Added httpOnly cookie storage for tokens
- All auth tests passing (12/12)
- Learning: Cookie sameSite setting needed for cross-origin requests
- Challenge: Had to debug token expiry edge case
- Next: Tackle TASK-002 (Todo CRUD endpoints)

IMPLEMENTATION_PLAN.md

Je levende TODO-lijst die Ralph bijwerkt naarmate het taken voltooit. Dit bestand verbindt de planning- en bouwmodus.

Structuur:

# Implementation Plan

## High Priority

- [ ] TASK-001: User Authentication (status: pending)
  - Tests: auth.test.ts
  - Dependencies: none

## Medium Priority

- [ ] TASK-002: Todo CRUD (status: pending)
  - Tests: todos.test.ts
  - Dependencies: TASK-001

## Completed

- [x] TASK-000: Project Setup (status: completed)
  - Completed: 2026-01-15 22:00

Effectieve Ralph-prompts schrijven

Cruciale promptelementen

Zoals gedocumenteerd in 11 Tips for AI Coding with Ralph Wiggum, moet elke Ralph-prompt deze elementen bevatten:

Voortgang bijhouden:

Read progress.txt to see what's been accomplished.
After completing each task, APPEND (never overwrite) your progress.

Backpressure door testen:

Each commit MUST pass all tests and type checks.
Run: npm test && npm run type-check && npm run lint
If anything fails, fix it before moving on.
NEVER commit broken code.

Scopebeheersing:

Pick the SINGLE highest priority task from IMPLEMENTATION_PLAN.md.
Work ONLY on that task—don't add features or refactor unrelated code.

Eerst verkennen:

Study the codebase first.
Don't assume something isn't implemented—verify by reading files.
Use ultrathink before making changes.

Taalpatronen die werken

Op basis van community-ervaringen van The Ralph Wiggum Playbook en 11 Tips verbeteren deze zinnen het gedrag van Claude:

• "Study the codebase first" → Vermindert aannames over wat er bestaat
• "Don't assume not implemented" → Moedigt verificatie aan voordat er geschreven wordt
• "Ultrathink before acting" → Bevordert zorgvuldige planning vóór wijzigingen (ultrathink wijst het maximale denkbudget toe voor complexe redenering—zie Mastery Part 9)
• "Capture the why in commits" → Verbetert de kwaliteit van de git-geschiedenis
• "MUST pass all tests" → Dwingt kwaliteitspoorten strikt af

Wat volgt

Je hebt nu de professionele methodologie: specs voor requirements, planningmodus voor gap-analyse, bouwmodus voor autonome uitvoering. De bestandsstructuur. De prompttemplates.

In Deel 3: Ralph TUI-monitoring behandelen we real-time zichtbaarheid voor langlopende loops—dashboards, toetsenbordbesturing en sessiebeheer.

Daarna duiken we in Deel 4: Geavanceerde patronen & probleemoplossing in geavanceerde prompt-engineering, veelvoorkomende valkuilen, uitgebreide probleemoplossing en enterprise-grade patronen.