[An autonomous AI-driven coding loop that implements one user story per iteration until all tasks are complete and verified.

הסבר בעברית – מדריך שימוש

לולאת ראלף היא תצורה שמאפשרת לCLAUDE CODE לרוץ על משימה עד להשלמה שלה בצורה המלאה, בלי לעצור בדרך משום סיבה שהיא.

המסמך באנגלית הוא המסמך הטכני “הרשמי”, שמסביר בדיוק איך Ralph עובד, אילו קבצים מעורבים, ואיך כל חלק במערכת מתקשר לאחרים. החלק הזה בעברית מסביר כיצד להשתמש במידע הזה בפועל בצורה ברורה ומעשית.

בחלק הראשון, ה-Overview, חשוב להבין את העיקרון: Ralph הוא לולאה שבה AI מבצע משימה אחת בכל סיבוב, בודק שהיא עובדת, מתעד ולוחץ קדימה רק אם הכל תקין. זה מבטיח סדר ומניעת טעויות שנגרמות כשמספר משימות מבוצעות בו זמנית.

מבנה הקבצים מסביר איפה נמצא כל דבר: ralph.sh מריץ את הלולאה, prompt.md מכיל הוראות מפורטות, prd.json הוא רשימת המשימות, ו-progress.txt הוא זיכרון קצר שמצטבר לאורך זמן עם תבניות ולמידות חוזרות.

החלק How Ralph Works עוזר להבין את הזרימה הלוגית: מה קורה בכל איטרציה, ואיך לבדוק שה-AI לא בורח מהסדר או מבצע יותר מדי משימות יחד. מודל הזיכרון מסביר שכל הזיכרון נשמר אך ורק בקבצים הרלוונטיים – אין זיכרון פנימי נסתר.

ה prompt.md הוא חוזה ההתנהגות של ה-AI: הוא אומר לו איזה סיפור לבחור, מה לבדוק, מתי לבצע קומיט, ואיך לעדכן מסמכים. progress.txt הוא המקום שבו מצטברים הידע והתבניות, והוא מאפשר ל-AI ללמוד ולהשתפר לאורך זמן. prd.json הוא ה-To-Do list – ברור, מדוד ומפורט, כי אם הוא לא ברור – התוצאה תיפגם.

ה ralph.sh הוא המנוע שמפעיל את הלולאה – פשוט, יציב וניתן לשליטה. Acceptance Criteria מבטיח שכל סיפור קטן וברור, כדי שה-AI יוכל לבצע אותו בלי שגיאות. AGENTS.md מכיל ידע ארוך-טווח שנשמר גם לעתיד. החלק של מתי להשתמש ומתי לא להשתמש ב-Ralph נותן הנחיות פרקטיות: הוא מתאים לעבודה מבוססת משימות קטנות וברורה, ולא לפרויקטים חקרניים או רגישים.

📁 File Structure

scripts/ralph/
├── ralph.sh# Main execution loop
├── prompt.md# Agent instructions per iteration
├── prd.json# Task list (User Stories)
└── progress.txt# Persistent learnings and memory

🔁 How Ralph Works (High-Level)

1. A Bash loop pipes a prompt into the AI agent
2. The agent:
   • Selects the next user story (lowest priority, passes = false)
   • Implements only one story
   • Runs typecheck and tests
   • Commits if everything passes
   • Marks the story as passes: true
   • Logs learnings
3. Loop repeats until all stories pass