Ralph pentru Claude Code

Ralph este un loop autonom de agent AI care rulează Claude Code în mod repetat până când toate task-urile dintr-un PRD sunt complete.

Adaptat din snarktank/ralph (pentru Amp) pentru a funcționa cu Claude Code CLI.

Cum funcționează

┌──────────────────────────────────────────────────────────────────┐
│                      CICLUL RALPH                                │
├──────────────────────────────────────────────────────────────────┤
│  1. Citește prd.json → selectează story cu prioritate minimă     │
│  2. Lansează instanță fresh Claude Code (context curat)          │
│  3. Implementează story-ul selectat                              │
│  4. Rulează quality checks (typecheck, tests, lint)              │
│  5. Commit dacă trece → marchează story ca "passes: true"        │
│  6. Salvează learnings în progress.txt                           │
│  7. Repetă până toate story-urile sunt complete                  │
└──────────────────────────────────────────────────────────────────┘

Memoria între iterații

Mecanism	Descriere
git history	Commit-uri din iterațiile anterioare
prd.json	Starea task-urilor (care sunt complete)
progress.txt	Learnings și patterns descoperite

Instalare rapidă

Cerințe

• Claude Code CLI instalat și autentificat
• jq pentru procesare JSON (apt install jq)
• Git repository

Instalare Skills (recomandat)

git clone git@gitea.romfast.ro:romfast/ralph-claude.git
cd ralph-claude
./install.sh

Aceasta instalează skill-urile /prd și /ralph global în ~/.claude/skills/.

Instalare manuală (per proiect)

# Copiază în proiectul tău
cp -r ralph-claude/scripts/ralph/ /path/to/your/project/scripts/ralph/
chmod +x scripts/ralph/ralph.sh

Utilizare

Workflow complet

1. /prd              → Generează PRD markdown cu întrebări clarificatoare
2. /ralph            → Convertește PRD în prd.json pentru execuție
3. ./ralph.sh        → Rulează loop-ul autonom

Pas 1: Generează PRD

Într-o sesiune Claude Code, folosește skill-ul /prd:

/prd

Vreau să adaug funcționalitate de export CSV pentru dashboard.

Claude va:

• Pune întrebări clarificatoare
• Genera PRD structurat în /tasks/prd-export-csv.md

Pas 2: Convertește în JSON

După ce PRD-ul e aprobat, folosește /ralph:

/ralph

Convertește PRD-ul din tasks/prd-export-csv.md

Claude va:

• Crea structura scripts/ralph/
• Genera prd.json cu user stories
• Inițializa progress.txt

Pas 3: Rulează Ralph

# Cu 10 iterații (implicit)
./scripts/ralph/ralph.sh

# Cu număr specific de iterații
./scripts/ralph/ralph.sh 20

Pas 4: Monitorizare

# Status stories
jq '.userStories[] | {id, title, passes}' scripts/ralph/prd.json

# Learnings acumulate
cat scripts/ralph/progress.txt

# Logs per iterație
ls scripts/ralph/logs/

Structura proiectului

your-project/
├── scripts/ralph/
│   ├── ralph.sh          # Script principal
│   ├── prompt.md         # Instrucțiuni per iterație
│   ├── prd.json          # Task-uri și status (generat)
│   ├── progress.txt      # Learnings (generat)
│   ├── logs/             # Logs per iterație
│   └── archive/          # Rulări anterioare arhivate
├── tasks/
│   └── prd-*.md          # PRD-uri markdown
└── AGENTS.md             # Patterns codebase (opțional)

Format prd.json

{
  "projectName": "export-csv",
  "branchName": "ralph/export-csv",
  "description": "Adaugă export CSV pentru dashboard",
  "userStories": [
    {
      "id": "US-001",
      "title": "Funcție de conversie la CSV",
      "description": "Ca developer, vreau o funcție care convertește date în CSV",
      "priority": 1,
      "acceptanceCriteria": [
        "Funcția acceptă array de obiecte",
        "Returnează string CSV valid",
        "npm run typecheck passes"
      ],
      "passes": false,
      "notes": ""
    }
  ]
}

Reguli pentru stories bune

Mărime corectă (1 context window)

• Adaugă un câmp în DB + migration
• Creează un component UI simplu
• Adaugă un endpoint API
• Scrie tests pentru o funcție

Prea mare (trebuie spart)

• "Implementează autentificarea completă"
• "Creează dashboard-ul admin"
• "Adaugă sistem notificări end-to-end"

Ordinea priorităților

1. Schema/Database (priority: 1-10)
2. Backend logic (priority: 11-20)
3. API endpoints (priority: 21-30)
4. UI components (priority: 31-40)
5. Integration/polish (priority: 41-50)

Debugging

Story nu progresează

# Vezi ultimul log
cat scripts/ralph/logs/iteration-*.log | tail -100

Tests failing

Verifică că proiectul are comenzile necesare:

npm run typecheck  # sau equivalent
npm run lint       # opțional
npm run test       # opțional

Context overflow

Story-ul e prea mare - sparge-l în părți mai mici.

Diferențe față de Ralph original

Aspect	Original (Amp)	Adaptat (Claude Code)
CLI	amp	claude -p
Flag permisiuni	--dangerously-allow-all	--dangerously-skip-permissions
Skills location	~/.config/amp/skills/	~/.claude/skills/
Output	Direct	+ salvat în logs/

Skills incluse

Skill	Descriere
/prd	Generează PRD structurat cu întrebări clarificatoare
/ralph	Convertește PRD markdown în prd.json pentru execuție

Credite

• snarktank/ralph - Ralph original pentru Amp
• snarktank/amp-skills - Skills originale

Licență

MIT