Initial commit - Ralph adaptat pentru Claude Code
Adaptare a sistemului Ralph (snarktank/ralph) pentru Claude Code CLI. Features: - Script ralph.sh pentru loop autonom - Skill /prd pentru generare PRD structurat - Skill /ralph pentru conversie PRD în prd.json - Script install.sh pentru instalare globală skills - Documentație completă Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Claude Agent
221
README.md
Normal file
221
README.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# 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](https://github.com/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)
|
||||
|
||||
```bash
|
||||
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)
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Cu 10 iterații (implicit)
|
||||
./scripts/ralph/ralph.sh
|
||||
|
||||
# Cu număr specific de iterații
|
||||
./scripts/ralph/ralph.sh 20
|
||||
```
|
||||
|
||||
### Pas 4: Monitorizare
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```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ă
|
||||
```bash
|
||||
# Vezi ultimul log
|
||||
cat scripts/ralph/logs/iteration-*.log | tail -100
|
||||
```
|
||||
|
||||
### Tests failing
|
||||
Verifică că proiectul are comenzile necesare:
|
||||
```bash
|
||||
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](https://github.com/snarktank/ralph) - Ralph original pentru Amp
|
||||
- [snarktank/amp-skills](https://github.com/snarktank/amp-skills) - Skills originale
|
||||
|
||||
## Licență
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user