Guide pratique de snarktank/ralph

Introduction

Dans l'article precedent, nous avons decouvert les principes fondamentaux de Ralph : boucle infinie + contexte entierement neuf a chaque iteration + fichiers comme source de verite. Ces trois piliers semblent simples, mais entre la comprehension theorique et la mise en pratique effective, il y a de nombreux details a maitriser.

Dans cet article, nous passons a la pratique. snarktank/ralph est l'implementation de la boucle externe de la methodologie Ralph — chaque iteration lance un tout nouveau processus Claude, resolvant definitivement le probleme du Context Rot. C'est l'une des implementations de Ralph les plus abouties de la communaute (10k+ stars), compatible avec les plateformes Claude Code et Amp, et fournissant une chaine d'outils complete pour la generation de PRD, la conversion JSON et l'execution automatisee.

Une autre approche d'implementation est frankbria/ralph-claude-code, qui fournit une chaine d'outils d'ingenierie complete (tableau de bord de surveillance, disjoncteur, limitation de debit), axee sur la controlabilite et les mecanismes de securite. La comparaison entre les deux se trouve dans cet article.

Prerequis

Avant de commencer, assurez-vous que votre environnement remplit les conditions suivantes :

# Verifier les dependances
claude --version   # Claude Code CLI
jq --version       # Traitement JSON
git --version      # Git

Installation et configuration

La methode la plus simple — collez directement le lien GitHub dans une conversation Claude Code :

帮我安装这个 skill：https://github.com/snarktank/ralph

Claude Code clonera automatiquement le depot et copiera les fichiers skill au bon emplacement. Une fois l'installation terminee, vous pouvez utiliser les commandes /prd et /ralph.

snarktank/ralph prend egalement en charge l'installation via le Marketplace, la copie manuelle des fichiers skill, l'installation au niveau du projet, etc. Consultez la documentation du depot GitHub pour plus de details.

Structure des fichiers principaux

La memoire de Ralph repose entierement sur le systeme de fichiers. Comprendre le role de chaque fichier est un prerequis essentiel pour bien utiliser Ralph.

ralph.sh — Le moteur de boucle

C'est le coeur de Ralph : un script bash charge de relancer continuellement de nouvelles instances d'IA.

# Utilisation de base
./scripts/ralph/ralph.sh [max_iterations]        # Amp par defaut
./scripts/ralph/ralph.sh --tool claude [iterations]  # Utiliser Claude Code

A chaque iteration, ralph.sh effectue les operations suivantes :

1. Cree une branche de fonctionnalite (basee sur le branchName dans prd.json)
2. Selectionne la story non terminee ayant la priorite la plus elevee (passes: false)
3. Lance une instance d'IA entierement nouvelle pour implementer cette story
4. Execute les controles de qualite (verification de types, tests)
5. Controle reussi → git commit ; echec → reporte a l'iteration suivante
6. Met a jour prd.json en marquant la story comme passes: true
7. Ajoute les enseignements tires de cette iteration dans progress.txt
8. Repete le processus jusqu'a ce que toutes les stories soient terminees ou que la limite d'iterations soit atteinte

La limite d'iterations par defaut est de 10. Ajustez-la en fonction de la complexite du projet :

# Projet simple
./scripts/ralph/ralph.sh --tool claude 10

# Projet complexe
./scripts/ralph/ralph.sh --tool claude 50

prd.json — Definition des taches

C'est le "cerveau" de Ralph — toutes les taches y sont definies. Le format est un fichier JSON plat :

{
  "projectName": "博客 i18n 翻译",
  "branchName": "ralph/i18n-translation",
  "userStories": [
    {
      "id": "US-001",
      "title": "翻译首页元数据",
      "description": "创建 content/docs/meta.en.json，包含所有导航项的英文翻译",
      "acceptanceCriteria": [
        "meta.en.json 文件存在且 JSON 格式正确",
        "所有导航标题都已翻译为英文",
        "pnpm types:check 通过"
      ],
      "priority": 1,
      "passes": false,
      "dependsOn": [],
      "notes": "参考现有 meta.json 的结构"
    },
    {
      "id": "US-002",
      "title": "翻译博客文章 hello-world",
      "description": "创建 content/blog/hello-world.en.mdx，从中文翻译为英文",
      "acceptanceCriteria": [
        "hello-world.en.mdx 文件存在",
        "所有 QuoteCard 组件设置 defaultLang='en'",
        "内部链接使用 /en/ 前缀",
        "代码块保持不翻译",
        "pnpm types:check 通过"
      ],
      "priority": 2,
      "passes": false,
      "dependsOn": ["US-001"],
      "notes": "注意保留 MDX 组件的 props 格式"
    }
  ]
}

Description des champs :

progress.txt — Journal d'experience

C'est la "memoire a long terme" de Ralph. A la fin de chaque iteration, l'IA y ajoute les enseignements tires de cette session :

=== Iteration 1 (US-001) ===
- Discovered: typecheck command is `pnpm types:check`, not `pnpm typecheck`
- Discovered: meta.en.json needs to mirror exact structure of meta.json
- Pattern: fumadocs i18n uses `.en.` suffix convention

=== Iteration 2 (US-002) ===
- Discovered: QuoteCard requires both `quote` and `quoteZh` props
- Gotcha: internal links must use /en/ prefix for English pages
- Pattern: code blocks should never be translated

La nouvelle instance de Claude de l'iteration suivante lira ce fichier et beneficiera immediatement de toute l'experience accumulee. C'est la raison pour laquelle Ralph devient de plus en plus performant au fil des iterations — les connaissances s'accumulent entre les iterations, tandis que le contexte reste propre.

AGENTS.md — Base de connaissances persistante

En plus de progress.txt, Ralph met egalement a jour le fichier AGENTS.md (ou CLAUDE.md) du projet. Claude Code et Amp lisent automatiquement ces fichiers au demarrage.

Contrairement a progress.txt, AGENTS.md enregistre des connaissances stables et generalisables a travers les projets :

# AGENTS.md

## Codebase Conventions
- Use fumadocs for documentation framework
- MDX files use custom components: QuoteCard, BlogImage, GlossaryCard
- i18n files use `.en.mdx` suffix

## Gotchas
- Always run `pnpm types:check` after modifying MDX files
- QuoteCard: set `defaultLang='en'` in English translations

Redaction du PRD

La qualite du PRD (Product Requirements Document) determine directement l'efficacite d'execution de Ralph. Un bon PRD permet a Ralph de progresser sans accroc ; un mauvais PRD fera echouer Ralph de maniere repetee sur la meme story.

Generer un PRD avec un Skill

Si vous avez installe le skill de snarktank/ralph, vous pouvez generer un PRD de maniere interactive :

# Dans Claude Code ou Amp
/prd 我想为博客系统添加 i18n 支持，需要将所有中文内容翻译成英文

L'IA vous posera une serie de questions de clarification (fichiers concernes, contraintes techniques, criteres de qualite, etc.), puis generera un document PRD structure.

Une fois genere, utilisez la commande /ralph pour convertir le PRD au format prd.json :

/ralph    # 将 PRD 转换为 prd.json

Redaction manuelle du PRD

Vous pouvez egalement rediger directement le prd.json. Voici les principes de conception essentiels.

Principe 1 : La granularite des stories doit etre appropriee

Chaque story doit etre suffisamment petite pour etre completee en une seule iteration, mais suffisamment grande pour apporter une valeur livrable independante.

// ❌ Trop grande : impossible a terminer en une iteration
{
  "id": "US-001",
  "title": "构建完整的用户认证系统",
  "description": "实现注册、登录、忘记密码、OAuth、权限管理..."
}

// ❌ Trop petite : pas de valeur independante
{
  "id": "US-001",
  "title": "创建 User 表的 email 字段",
  "description": "在 User 模型中添加 email 字段"
}

// ✅ Appropriee : realisable en une iteration, valeur independante
{
  "id": "US-001",
  "title": "实现邮箱密码登录",
  "description": "创建登录 API 和登录页面，支持邮箱密码验证",
  "acceptanceCriteria": [
    "POST /api/auth/login 接受 email + password",
    "返回 JWT token",
    "登录页面表单可提交",
    "所有测试通过"
  ]
}

Regle empirique : une story implique la modification de 1 a 3 fichiers et comporte 3 a 5 criteres d'acceptation.

Principe 2 : Les criteres d'acceptation doivent etre verifiables automatiquement

Ralph doit pouvoir determiner si une story est terminee, les criteres d'acceptation doivent donc etre objectivement evaluables :

// ❌ Criteres vagues
"acceptanceCriteria": [
  "代码质量好",
  "性能不错",
  "用户体验流畅"
]

// ✅ Criteres verifiables
"acceptanceCriteria": [
  "pnpm types:check 通过",
  "pnpm test 通过",
  "API 响应时间 < 200ms",
  "文件 src/auth/login.ts 存在且导出 loginHandler 函数"
]

Principe 3 : Utiliser dependsOn pour controler l'ordre d'execution

Certaines stories ont des relations de dependance. Le champ dependsOn garantit que Ralph les execute dans le bon ordre :

{
  "userStories": [
    {
      "id": "US-001",
      "title": "创建数据库 schema",
      "dependsOn": []
    },
    {
      "id": "US-002",
      "title": "实现用户注册 API",
      "dependsOn": ["US-001"]
    },
    {
      "id": "US-003",
      "title": "实现登录页面",
      "dependsOn": ["US-002"]
    }
  ]
}

Principe 4 : Fournir du contexte dans le champ notes

Le champ notes sert d'indication supplementaire pour l'IA. Inscrivez-y les informations que vous connaissez mais que l'IA pourrait ignorer :

{
  "notes": "项目使用 fumadocs 框架，i18n 文件命名规则是 .en.mdx 后缀。参考 content/docs/notes/speckit/concept.en.mdx 的翻译风格。"
}

Execution de la boucle Ralph

Le PRD est pret, lancons la boucle.

Demarrage de l'execution

# Avec Claude Code, 10 iterations par defaut
./scripts/ralph/ralph.sh --tool claude

# Specifier le nombre d'iterations
./scripts/ralph/ralph.sh --tool claude 30

# Avec Amp (par defaut)
./scripts/ralph/ralph.sh 20

Deroulement de l'execution

Apres le demarrage, vous verrez une sortie similaire a ceci :

Starting Ralph - Tool: claude - Max iterations: 35

===============================================================
  Ralph Iteration 1 of 35 (claude)
===============================================================
## US-001 Complete

**Summary of what was done:**
1. Created meta.en.json with all navigation items translated
2. Ran pnpm types:check — PASSED
3. Committed: feat: [US-001] - Translate homepage metadata

There are still **15 user stories with `passes: false`** remaining.
The next story is **US-002: 翻译博客文章 hello-world**.
Iteration 1 complete. Continuing...

===============================================================
  Ralph Iteration 2 of 35 (claude)
===============================================================

Chaque iteration est une instance de Claude entierement nouvelle. Elle sait quoi faire en lisant prd.json et connait les enseignements precedents grace a progress.txt.

Signal d'achevement

Lorsque toutes les stories sont marquees comme passes: true, Ralph affiche un signal d'achevement et se termine :

All stories completed!
<promise>COMPLETE</promise>

Surveillance et debogage

Pendant l'execution de Ralph, vous pouvez utiliser ces commandes pour suivre la progression :

# Voir l'etat d'achevement de chaque story (avec icones, plus visuel)
cat tasks/prd.json | python3 -c "
import json,sys
for s in json.load(sys.stdin)['userStories']:
    print(f'{\"✅\" if s[\"passes\"] else \"⬜\"} {s[\"id\"]}: {s[\"title\"]}')"

# Ou avec jq
cat tasks/prd.json | jq '.userStories[] | {id, title, passes}'

# Voir le journal d'experience
cat progress.txt

# Voir les derniers commits git
git log --oneline -10

# Suivre la sortie de Ralph en temps reel
tail -f progress.txt

# Une fois termine, voir toutes les modifications par rapport a la branche principale
git diff main...ralph/your-branch-name --stat

Interruption et reprise

L'execution de Ralph peut etre longue, l'interrompre en cours de route est parfaitement sur :

• Interruption : appuyez simplement sur Ctrl+C. Les stories terminees (passes: true) ne sont pas perdues, elles ont deja ete commitees et enregistrees dans prd.json
• Reprise : relancez la meme commande, Ralph reprendra automatiquement a partir de la premiere story ayant passes: false

# Pour reprendre apres une interruption, relancez simplement la meme commande
./scripts/ralph/ralph.sh --tool claude 35

Si une story echoue de maniere repetee et bloque la progression, vous pouvez la sauter manuellement — editez prd.json, changez le champ passes de cette story a true, puis relancez. Ralph la sautera et continuera avec les stories suivantes.

Archivage automatique

Lorsque vous demarrez une fonctionnalite differente avec un nouveau branchName, Ralph archive automatiquement les fichiers de l'execution precedente dans le repertoire archive/YYYY-MM-DD-feature-name/, maintenant ainsi un espace de travail ordonne.

Boucle de retroaction et controles de qualite

La capacite d'"autocorrection" de Ralph depend entierement de la qualite de la boucle de retroaction. Sans boucle de retroaction, Ralph n'est qu'un script qui tourne en aveugle — il produit continuellement du code, mais ne peut pas determiner si ce code est correct.

Configuration des controles de qualite

Definissez vos commandes de controle qualite dans CLAUDE.md (ou prompt.md) :

## Quality Commands

After implementing each story, run these checks IN ORDER:

1. `pnpm types:check` — TypeScript type checking
2. `pnpm test` — Unit tests
3. `pnpm build` — Full build verification

If any check fails:
- DO NOT commit
- Fix the issue
- Re-run all checks
- Only commit when all checks pass

Niveaux des controles de qualite

Pour les stories frontend, Ralph recommande d'ajouter aux criteres d'acceptation : "Verify in browser using dev-browser skill" — pour que l'IA ouvre reellement le navigateur et confirme que la page s'affiche correctement.

Lorsque les controles de qualite echouent

Si les controles de qualite d'une story echouent de maniere repetee, Ralph ne reessaiera pas indefiniment la meme story. Une fois la limite d'iterations atteinte, il s'arrete et laisse l'etat tel quel. Vous pouvez alors :

1. Consulter progress.txt pour voir ou l'IA est bloquee
2. Corriger manuellement le probleme puis relancer
3. Ajuster la granularite de la story (elle est peut-etre trop volumineuse)
4. Completer le champ notes avec davantage de contexte

Personnalisation du prompt

Le template de prompt de Ralph (CLAUDE.md ou prompt.md) est votre principal levier pour controler le comportement de l'IA. Apres l'installation, vous devriez le personnaliser en fonction de votre projet. Voici les principaux axes de personnalisation :

Contraintes de style de code

## Code Conventions
- Use TypeScript strict mode
- Prefer named exports over default exports
- Use fumadocs components for MDX content
- Follow existing file naming patterns (kebab-case)

Pieges courants

## Known Gotchas
- MDX files: always import components at the top
- i18n: English files use `.en.mdx` suffix
- Links: English pages must use `/en/` prefix
- QuoteCard: set `defaultLang` to match the file language

Comportement en cas de blocage

## When Stuck
If you cannot complete a story after 3 attempts within the same iteration:
1. Document what's blocking in progress.txt
2. Move to the next story if possible
3. Do NOT modify files unrelated to the current story

Etude de cas pratique : traduire un blog i18n avec Ralph

Pour illustrer le fonctionnement de Ralph dans un projet reel, voici un cas concret : l'utilisation d'un agent autonome de style Ralph pour traduire l'integralite d'un blog du chinois vers l'anglais.

Configuration du projet

Le projet necessitait la traduction de plus de 22 fichiers de contenu (articles de blog, documentation, metadonnees de navigation) du chinois vers l'anglais, avec pour objectif le support i18n d'un blog Next.js base sur fumadocs. Les taches etaient definies dans un fichier prd.json contenant 16 user stories, chacune avec des criteres d'acceptation precis :

scripts/ralph/
├── prd.json          # 16 user stories avec criteres d'acceptation
└── progress.txt      # Journal d'experience, mis a jour apres chaque story

Chaque user story suivait un schema coherent :

• Livrables explicites : "Create content/blog/xxx.en.mdx"
• Criteres verifiables : "Typecheck passes", "Internal links use /en/ prefix"
• Contraintes techniques : "Keep code blocks untranslated", "Set defaultLang='en' on QuoteCard"

Mode d'execution

L'agent suivait les principes fondamentaux de la methodologie Ralph :

1. Les fichiers comme source de verite : prd.json suit l'etat de chaque story (passes: true/false). progress.txt accumule l'experience au fil des iterations — par exemple "La commande typecheck est pnpm types:check, pas pnpm typecheck"

2. Controles de qualite automatises : apres chaque traduction, pnpm types:check est execute pour verifier que les fichiers MDX compilent correctement. Si le typecheck echoue, le probleme est corrige avant le commit.

3. Progression incrementale : chaque story fait l'objet d'un commit independant avec un message descriptif (feat: [US-003] - Translate blog/claude-code-quality-control.mdx), ce qui facilite les retours en arriere si necessaire.

4. Execution parallele : pour les articles les plus longs, plusieurs subagents traduisent simultanement — par exemple US-010 (claude-skills concept + practice), US-011 (speckit concept + practice) et US-012 (claude-architecture + claude-subagent) s'executent en parallele.

Enseignements cles

Resultats

Les 16 user stories ont ete completees en une seule session : 8 fichiers meta.en.json de navigation ont ete crees, 3 articles de blog ont ete traduits, 12 pages de documentation ont ete traduites, et la verification de build complete du site a reussi. Chaque traduction a maintenu une qualite constante, car les criteres d'acceptation etaient explicites et la boucle de retroaction (typecheck) detectait immediatement les problemes.

Ce projet illustre le mode d'implementation complet (Full Implementation Mode) de Ralph — des taches clairement definies, des criteres de reussite explicites, une verification automatisee et une livraison incrementale via le systeme de fichiers.

Bonnes pratiques et questions frequentes

Maitrise des couts

L'execution automatisee de Ralph implique des couts API continus. Voici plusieurs moyens de les controler :

• Definissez toujours max_iterations : c'est le filet de securite le plus elementaire
• Granularite raisonnable des stories : des stories trop volumineuses consomment de nombreuses iterations ; des stories trop fragmentees augmentent les couts de demarrage
• Testez d'abord a petite echelle : pour un nouveau projet, effectuez 3 a 5 iterations d'essai pour confirmer que le prompt et les controles de qualite fonctionnent correctement avant de passer a l'echelle

Pieges courants

Piege 1 : Story trop volumineuse

Symptome : une story echoue de maniere repetee, le nombre d'iterations s'epuise rapidement.

Solution : decoupez-la en 2-3 stories plus petites. "Construire un systeme d'authentification complet" se decompose en "Implementer l'API de connexion" + "Creer la page de connexion" + "Ajouter le middleware JWT".

Piege 2 : Absence de boucle de retroaction

Symptome : Ralph declare la story terminee, mais le code comporte des erreurs.

Solution : ajoutez des commandes de verification executables dans les criteres d'acceptation. "Le code est ecrit" n'est pas un critere d'acceptation ; "pnpm test reussit integralement" en est un.

Piege 3 : progress.txt n'est pas exploite

Symptome : la meme erreur reapparait dans differentes iterations.

Solution : verifiez que le template de prompt contient une instruction explicite "Lire progress.txt et suivre les enseignements qu'il contient". Si l'IA n'ajoute pas automatiquement les apprentissages, ajoutez au prompt : "After each story, append learnings to progress.txt".

Piege 4 : Ordre de dependance incorrect

Symptome : une story depend de code qui n'existe pas encore, ce qui provoque un echec d'implementation.

Solution : configurez correctement le champ dependsOn et assurez-vous que les stories d'infrastructure sont ordonnees en premier.

Questions frequentes

Q : Peut-on modifier manuellement prd.json en cours de route ?

Oui. Ralph relit prd.json au debut de chaque iteration. Vous pouvez modifier les descriptions de story entre les iterations, ajouter de nouvelles stories, ou marquer manuellement une story comme passes: true (pour la sauter).

Q : Que faire si Ralph echoue de maniere repetee sur la meme story ?

1. Consultez progress.txt pour identifier la cause de l'echec
2. Completez le champ notes avec davantage de contexte
3. Decoupez la story (la granularite est peut-etre trop importante)
4. Corrigez manuellement le probleme bloquant puis relancez

Q : Puis-je faire autre chose pendant que Ralph s'execute ?

Oui. Ralph est concu selon le principe "Human on the Loop" — vous n'avez pas besoin de le surveiller en permanence. En mode AFK, lancez-le avant de quitter le bureau et verifiez les resultats le lendemain. Evitez simplement de modifier les fichiers sur lesquels Ralph est en train de travailler.

Q : Comment maitriser les couts ?

Trois approches : definissez un max_iterations raisonnable, maintenez une granularite de story appropriee (pour reduire les iterations inutiles), et effectuez d'abord un test a petite echelle pour confirmer que le processus fonctionne. En general, un projet de 10 a 20 stories represente un cout API de l'ordre de 50 a 100 dollars.

Conclusion

Le flux d'utilisation de Ralph peut se resumer en cinq etapes :

Installation → Redaction du PRD → Configuration des controles de qualite → Execution de la boucle → Verification des resultats

L'idee centrale reste toujours la meme : faire des fichiers la source de verite, faire de chaque iteration un nouveau depart, et laisser les controles de qualite veiller pour vous.

Maintenant, retournez a votre projet, preparez votre prd.json, lancez ./scripts/ralph/ralph.sh --tool claude, puis allez vous servir un cafe.

Lectures complementaires

• Ralph Wiggum - Analyse approfondie — Revue des principes fondamentaux de Ralph
• Guide pratique de frankbria/ralph-claude-code — Implementation industrialisee de Ralph : surveillance, disjoncteur et mecanismes de securite
• GSD - Analyse approfondie — Un systeme complet d'ingenierie de contexte construit sur les bases de Ralph
• Qu'est-ce que Claude Skills — Le skill PRD de Ralph est un Claude Skill
• Guide pratique de Speckit — Un autre flux de travail structure pour la programmation IA