Le guide pratique de Ralph

##Présentation

Dans article précédent, nous avons compris les principes fondamentaux de Ralph - boucle infinie + nouveau contexte à chaque fois + fichier comme seule source de vérité. Ces trois piliers semblent simples, mais de la compréhension du concept à sa mise en œuvre réelle, de nombreux détails doivent être réglés.

Dans cet article, commençons. Vous apprendrez à utiliser snarktank/ralph pour terminer le processus complet, de l'installation à l'exécution. snarktank/ralph est l'une des implémentations Ralph les plus matures de la communauté (plus de 10 000 étoiles). Il prend en charge deux outils, Claude Code et Amp, ainsi qu'une chaîne d'outils complète pour la génération PRD, la conversion JSON et l'exécution automatisée.

Conditions préalables

Avant de commencer, assurez-vous que votre environnement répond aux exigences suivantes :

# 检查依赖
claude --version   # Claude Code CLI
jq --version       # JSON 处理
git --version      # Git

##Installation et configuration

snarktank/ralph propose une variété de méthodes d'installation, qui peuvent être sélectionnées en fonction du scénario d'utilisation.

Méthode 1 : Installer directement dans Claude Code (recommandé)

Le moyen le plus simple est de coller le lien GitHub dans la conversation Claude Code et de laisser Claude terminer automatiquement l'installation :

Install this skill for me: https://github.com/snarktank/ralph

Claude Code clonera automatiquement le référentiel et copiera les fichiers de compétences au bon emplacement. Les commandes /prd et /ralph sont disponibles après l'installation.

Méthode 2 : Installation du marché Claude Code

Installer via la commande market :

# 添加并安装插件
/plugin marketplace add snarktank/ralph
/plugin install ralph-skills@ralph-marketplace

Après l'installation, vous pouvez utiliser les deux compétences /prd (générer du PRD) et /ralph (convertir en JSON).

Méthode 3 : Installation manuelle des compétences (Claude Code/Amp)

Copiez manuellement le fichier de compétence dans le répertoire de configuration global de l'outil correspondant :

# 先克隆仓库
git clone https://github.com/snarktank/ralph.git /tmp/ralph

# Claude Code 用户
cp -r /tmp/ralph/skills/prd ~/.claude/skills/
cp -r /tmp/ralph/skills/ralph ~/.claude/skills/

# Amp 用户
cp -r /tmp/ralph/skills/prd ~/.config/amp/skills/
cp -r /tmp/ralph/skills/ralph ~/.config/amp/skills/

Les commandes /prd et /ralph sont disponibles après l'installation.

Méthode 4 : Installation au niveau du projet

Copiez le script Ralph directement dans le projet - idéal pour les scénarios où le partage en équipe ou des scripts personnalisés sont requis :

# 克隆 Ralph 仓库
git clone https://github.com/snarktank/ralph.git /tmp/ralph

# 复制核心文件到项目
mkdir -p scripts/ralph
cp /tmp/ralph/ralph.sh scripts/ralph/
cp /tmp/ralph/CLAUDE.md scripts/ralph/   # Claude Code 用户
# 或
cp /tmp/ralph/prompt.md scripts/ralph/   # Amp 用户

# 赋予执行权限
chmod +x scripts/ralph/ralph.sh

Une fois l'installation terminée, la structure du projet est la suivante :

your-project/
├── scripts/ralph/
│   ├── ralph.sh        # 核心循环脚本
│   └── CLAUDE.md       # Claude Code 的 Prompt 模板
├── tasks/              # PRD 文件目录（执行时自动创建）
│   └── prd.json        # 你的任务定义
└── ...

Suggestion : La première méthode est la plus simple : il suffit de lancer le lien GitHub vers Claude Code. Si vous souhaitez contrôler manuellement le processus d'installation, choisissez la méthode 2 (commande de marché) ou la méthode 3 (copie manuelle). Choisissez la méthode 4 lorsque vous devez partager le script avec l'équipe ou le personnaliser.

Structure du fichier de base

La mémoire de Ralph repose entièrement sur le système de fichiers. Comprendre le rôle de chaque fichier est un prérequis pour bien utiliser Ralph.

ralph.sh - moteur de boucle

C'est le cœur de Ralph : un script bash qui génère constamment de nouvelles instances d'IA.

# 基本用法
./scripts/ralph/ralph.sh [max_iterations]        # 默认：Amp
./scripts/ralph/ralph.sh --tool claude [iterations]  # 使用 Claude Code

À chaque itération, ralph.sh effectue les étapes suivantes :

1. Créez une branche de fonctionnalités (à partir de branchName dans prd.json)
2. Sélectionnez l'histoire inachevée avec la priorité la plus élevée (passes: false)
3. Générez une nouvelle instance d'IA pour mettre en œuvre cette histoire
4. Effectuer des contrôles qualité (contrôles de type, tests)
5. Vérification réussie → git commit ; échec de la vérification → laisser à l'itération suivante
6. Mettez à jour prd.json et marquez l'histoire comme passes: true
7. Ajoutez les leçons apprises au progress.txt
8. Répétez jusqu'à ce que toutes les histoires soient terminées ou que le nombre maximum d'itérations soit atteint

La limite d'itérations par défaut est de 10. Ajustez en fonction de la complexité du projet :

# 简单项目
./scripts/ralph/ralph.sh --tool claude 10

# 复杂项目
./scripts/ralph/ralph.sh --tool claude 50

prd.json - définition de la tâche

C'est le « cerveau » de Ralph, où toutes les tâches sont définies. C'est un fichier JSON plat :

{
  "projectName": "Blog i18n Translation",
  "branchName": "ralph/i18n-translation",
  "userStories": [
    {
      "id": "US-001",
      "title": "Translate homepage metadata",
      "description": "Create content/docs/meta.en.json with English translations for all navigation items",
      "acceptanceCriteria": [
        "meta.en.json file exists with valid JSON format",
        "All navigation titles are translated to English",
        "pnpm types:check passes"
      ],
      "priority": 1,
      "passes": false,
      "dependsOn": [],
      "notes": "Reference the existing meta.json structure"
    },
    {
      "id": "US-002",
      "title": "Translate blog post hello-world",
      "description": "Create content/blog/hello-world.en.mdx, translated from Chinese to English",
      "acceptanceCriteria": [
        "hello-world.en.mdx file exists",
        "All QuoteCard components have defaultLang='en'",
        "Internal links use /en/ prefix",
        "Code blocks remain untranslated",
        "pnpm types:check passes"
      ],
      "priority": 2,
      "passes": false,
      "dependsOn": ["US-001"],
      "notes": "Preserve MDX component props format"
    }
  ]
}

Description du champ :

progress.txt - journal d'expérience

C'est la « mémoire à long terme » de Ralph. Après chaque itération, l'IA ajoutera une expérience supplémentaire apprise :

=== 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

Une toute nouvelle instance de Claude pour la prochaine itération lira ce fichier et obtiendra immédiatement toute l'expérience précédente. C'est pourquoi les exécutions de Ralph s'améliorent de plus en plus : les connaissances s'accumulent entre les itérations, mais le contexte reste propre.

AGENTS.md - Base de connaissances persistante

En plus de progress.txt, Ralph met également à jour le fichier AGENTS.md (ou CLAUDE.md) dans le projet. Claude Code et Amp liront automatiquement ces fichiers au démarrage.

Contrairement à progress.txt, AGENTS.md enregistre des connaissances stables et inter-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

Écrire PRD

La qualité du PRD (Product Requirements Document) détermine directement les résultats d'exécution de Ralph. Bien écrit, navigation fluide jusqu'au bout, Ralph. Mal écrit, Ralph échouera à plusieurs reprises sur la même histoire.

Utilisez Skill pour générer du PRD

Si la compétence snarktank/ralph est installée, vous pouvez générer du PRD de manière interactive :

# 在 Claude Code 或 Amp 中
/prd I want to add i18n support to the blog, translating all Chinese content to English

L'IA vous posera quelques questions de clarification (quels documents sont impliqués, les limites de la pile technologique, les normes de qualité, etc.) puis générera un document PRD structuré.

Après génération, utilisez la commande /ralph pour convertir le PRD au format prd.json :

/ralph    # 转换 PRD 为 prd.json

Écrivez manuellement le PRD

Vous pouvez également écrire prd.json directement. Voici les principes de conception clés.

Principe 1 : la granularité de l'histoire est modérée

Chaque histoire doit être suffisamment petite pour être complétée en une seule itération et suffisamment grande pour apporter de la valeur de manière indépendante.

// ❌ 太大：一次迭代完不成
{
  "id": "US-001",
  "title": "Build complete user authentication system",
  "description": "Implement registration, login, forgot password, OAuth, permission management..."
}

// ❌ 太小：没有独立价值
{
  "id": "US-001",
  "title": "Create email field on User table",
  "description": "Add email field to User model"
}

// ✅ 刚好：一次迭代能完成，有独立价值
{
  "id": "US-001",
  "title": "Implement email/password login",
  "description": "Create login API and login page with email/password authentication",
  "acceptanceCriteria": [
    "POST /api/auth/login accepts email + password",
    "Returns JWT token",
    "Login page form submits successfully",
    "All tests pass"
  ]
}

Règle générale : une histoire implique 1 à 3 modifications de fichiers et comporte 3 à 5 critères d'acceptation.

Principe 2 : Les critères d'acceptation doivent être automatiquement vérifiables

Ralph doit déterminer si l'histoire est complète, les critères d'acceptation doivent donc être objectivement évaluables :

// ❌ 模糊的标准
"acceptanceCriteria": [
  "Code quality is good",
  "Performance is decent",
  "User experience is smooth"
]

// ✅ 可验证的标准
"acceptanceCriteria": [
  "pnpm types:check passes",
  "pnpm test passes",
  "API response time < 200ms",
  "File src/auth/login.ts exists and exports loginHandler function"
]

Principe 3 : Utilisez dependOn pour contrôler l'ordre d'exécution

Certaines histoires ont des dépendances. Le champ dependsOn garantit que Ralph est exécuté dans le bon ordre :

{
  "userStories": [
    {
      "id": "US-001",
      "title": "Create database schema",
      "dependsOn": []
    },
    {
      "id": "US-002",
      "title": "Implement user registration API",
      "dependsOn": ["US-001"]
    },
    {
      "id": "US-003",
      "title": "Implement login page",
      "dependsOn": ["US-002"]
    }
  ]
}

Principe 4 : Fournir du contexte dans les notes

Le champ Notes donne à l'IA des indications supplémentaires. Écrivez ici les informations que vous connaissez et que l'IA ne connaît peut-être pas :

{
  "notes": "Project uses fumadocs framework, i18n files follow .en.mdx suffix naming. Reference content/docs/notes/speckit/concept.en.mdx for translation style."
}

Exécuter la boucle Ralph

Une fois le PRD prêt, il est temps d'exécuter la boucle.

Démarrer l'exécution

# 使用 Claude Code，默认 10 次迭代
./scripts/ralph/ralph.sh --tool claude

# 指定迭代次数
./scripts/ralph/ralph.sh --tool claude 30

# 使用 Amp（默认）
./scripts/ralph/ralph.sh 20

Processus d'exécution

Après le démarrage, vous verrez un résultat similaire à celui-ci :

=== Ralph Loop - Iteration 1 ===
Branch: ralph/i18n-translation
Selected story: US-001 - Translate homepage metadata
Spawning fresh Claude instance...

[Claude Code executing...]

Quality check: pnpm types:check ... PASSED
Committing: feat: [US-001] - Translate homepage metadata
Updating prd.json: US-001 passes: true
Appending to progress.txt

=== Ralph Loop - Iteration 2 ===
Selected story: US-002 - Translate blog post hello-world
Spawning fresh Claude instance...

Chaque itération est une instance complètement nouvelle de Claude. Il sait quoi faire en lisant prd.json et ce qu'il a appris précédemment en lisant progress.txt.

###Signal complet

Lorsque toutes les histoires sont marquées passes: true, Ralph émet un signal d'achèvement et quitte :

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

Surveillance et débogage

Pendant que Ralph est en cours d'exécution, vous pouvez utiliser la commande suivante pour afficher la progression :

# 查看每个 story 的完成状态
cat tasks/prd.json | jq '.userStories[] | {id, title, passes}'

# 查看经验日志
cat progress.txt

# 查看最近的 git 提交
git log --oneline -10

# 实时跟踪 Ralph 输出
tail -f progress.txt

Archivage automatique

Lorsque vous démarrez une nouvelle fonctionnalité (en utilisant un autre branchName), Ralph archivera automatiquement les fichiers de la dernière exécution dans le répertoire archive/YYYY-MM-DD-feature-name/, gardant ainsi le répertoire de travail propre.

Boucles de rétroaction et contrôle de la qualité

La capacité de Ralph à « s'auto-corriger » dépend entièrement de la qualité de la boucle de rétroaction. Sans boucle de rétroaction, Ralph n'est qu'un script qui boucle aveuglément : il continue de produire du code sans pouvoir dire si le code est correct.

Configurer le contrôle qualité

Définissez les commandes QA 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

Niveau de contrôle d'accès qualité

Pour les histoires frontales, Ralph recommande d'ajouter ce critère d'acceptation : "Vérifiez dans le navigateur à l'aide de la compétence dev-browser" - laissez l'IA ouvrir réellement le navigateur pour confirmer que la page est rendue correctement.

Lorsque le contrôle qualité échoue

Si une histoire échoue à plusieurs reprises au contrôle qualité, Ralph ne réessaiera pas indéfiniment la même histoire. Il s'arrêtera après avoir atteint la limite supérieure de l'itération et conservera l'état actuel. Vous pouvez :

1. Consultez le fichier progress.txt pour comprendre la raison du blocage
2. Résolvez manuellement le problème, puis réexécutez
3. Ajustez la granularité de l'histoire (peut-être trop grande)
4. Ajoutez plus de contexte au champ de notes

Personnalisation rapide

Le modèle d'invite de Ralph (CLAUDE.md ou prompt.md) est votre principal moyen de contrôler le comportement de l'IA. Après l'installation, vous devez le personnaliser en fonction de votre projet.

Éléments de personnalisation clés

1. Commandes qualité spécifiques au projet

## Project-Specific Commands
- Typecheck: `pnpm types:check` (not `tsc` or `pnpm typecheck`)
- Test: `pnpm vitest run`
- Build: `pnpm build`
- Lint: `pnpm lint`

2. 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)

3. Pièges connus

## 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

4. Manipulation 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

Cas pratique : Traduire des blogs avec Ralph

Pour montrer comment Ralph fonctionne en pratique, voici un exemple concret : utiliser un agent autonome de style Ralph pour traduire un blog entier du chinois vers l'anglais.

Paramètres du projet

Ce projet nécessite la traduction de plus de 22 fichiers de contenu (articles de blog, documents, métadonnées de navigation) du chinois vers l'anglais. Le projet est basé sur le blog Next.js de fumadocs et prend en charge i18n. La tâche est définie dans le fichier prd.json et contient 16 user stories, chacune avec des critères d'acceptation clairs :

scripts/ralph/
├── prd.json          # 16 个 user story，带验收标准
└── progress.txt      # 经验日志，每个 story 完成后更新

Chaque user story suit un modèle cohérent :

• Livrable explicite : "Créer du contenu/blog/xxx.en.mdx"
• Critères vérifiables : "Typecheck réussis", "Les liens internes utilisent le préfixe /en/"
• Contraintes techniques : "Conserver les blocs de code non traduits", "Définir defaultLang='en' sur QuoteCard"

Mode d'exécution

Agent suit les principes fondamentaux de la méthodologie de Ralph :

1. Les documents sont la source de la vérité : prd.json suit les histoires transmises (passes: true/false). progress.txt Acquérir de l'expérience entre les itérations - par ex. "La commande Typecheck est pnpm types:check, pas pnpm typecheck"

2. Automated Quality Gate : après chaque traduction, pnpm types:check est exécuté pour vérifier que le fichier MDX a été correctement compilé. Si la vérification de type échoue, corrigez-la avant de la soumettre.

3. Avancement incrémentiel : chaque histoire est soumise indépendamment, avec des informations de soumission descriptives (feat: [US-003] - Translate blog/claude-code-quality-control.mdx), et peut être facilement annulée en cas de besoin.

4. Exécution parallèle : pour les articles plus longs, plusieurs sous-agents sont traduits simultanément - par exemple, US-010 (concept claude-skills + pratique), US-011 (concept speckit + pratique) et US-012 (claude-architecture + claude-sous-agent) sont exécutés en parallèle.

Leçons clés

Résultats

Les 16 user stories ont été complétées en une seule session : 8 fichiers de navigation meta.en.json ont été créés, 3 articles de blog ont été traduits, 12 pages de documentation ont été traduites et la construction complète du site a été vérifiée. Chaque traduction maintient une qualité constante car les critères d'acceptation sont clairs et une boucle de rétroaction (vérification de type) détecte immédiatement les problèmes.

Ce projet démontre le modèle de mise en œuvre complet de Ralph : tâches bien définies + critères de réussite clairs + vérification automatisée + livraison incrémentielle via le système de fichiers.

Mise en œuvre communautaire et alternatives

snarktank/ralph n’est pas la seule option. Chacune de ces implémentations possède ses propres forces et faiblesses, en fonction de vos besoins :

Alternative : GSD

GSD n'est pas strictement une "implémentation communautaire" de Ralph - c'est une alternative. Il applique les principes fondamentaux de Ralph (gestion du contexte, tâches atomiques) mais fournit un flux de travail plus complet : discuter → planifier → exécuter → vérifier.

Si vous pensez que Ralph est trop « brut » et a besoin de plus de soutien dans le processus, GSD peut être plus approprié. Voir Analyse approfondie GSD pour plus de détails.

Ressources recommandées

Source officielle :

Tutoriel vidéo :

Bonnes pratiques et FAQ

Contrôle des coûts

L'exécution automatisée de Ralph signifie que les frais d'API sont engagés de manière continue. Plusieurs mesures de contrôle :

• Toujours définir max_iterations : il s'agit du filet de sécurité le plus élémentaire
• Gardez une granularité de l'histoire raisonnable : une histoire trop volumineuse consommera plusieurs itérations ; une histoire trop détaillée augmentera les frais de démarrage.
• Tests à petite échelle d'abord : les nouveaux projets seront d'abord exécutés pendant 3 à 5 itérations, puis développés après avoir confirmé que les invites et le contrôle d'accès de qualité fonctionnent correctement.

Pièges courants

Piège 1 : L'histoire est trop grande

Symptômes : Une histoire échoue à plusieurs reprises et le nombre d’itérations est rapidement épuisé.

Solution : Divisez-le en 2 ou 3 histoires plus petites. "Créer un système d'authentification complet" est divisé en "Implémentation de l'API de connexion" + "Création de la page de connexion" + "Ajout du middleware JWT".

Piège 2 : Pas de boucle de rétroaction

Symptôme : Ralph prétend que l'histoire est terminée, mais il y a un problème avec le code lui-même.

Solution : Ajoutez des commandes de vérification exécutables dans les critères d'acceptation. "Le code est écrit" n'est pas un critère d'acceptation - "pnpm test all réussis" l'est.

Piège 3 : progress.txt n'est pas utilisé

Symptômes : la même erreur apparaît à plusieurs reprises dans différentes itérations.

Résolution : assurez-vous que votre modèle d'invite indique explicitement « lire progress.txt et suivre les règles qui y figurent ». Si l'IA n'ajoute pas automatiquement d'expérience, ajoutez « Une fois chaque histoire terminée, ajoutez de l'expérience à progress.txt » dans l'invite.

Piège 4 : Mauvais ordre de dépendance

Symptôme : une histoire repose sur du code qui n'existe pas encore, ce qui entraîne l'échec de l'implémentation.

Résolution : définissez correctement le champ dependsOn. Assurez-vous que l’histoire de l’infrastructure passe en premier.

FAQ

**Q : Quelle est la différence entre Ralph et le plug-in officiel ? **

Différence fondamentale : snarktank/ralph génère de nouveaux processus à chaque itération (vraiment un contexte complètement nouveau), alors que le plugin officiel boucle au sein de la même session (le contexte continue de s'accumuler). Voir analyse de l'article précédent pour plus de détails.

**Q : Prd.json peut-il être modifié manuellement pendant l'exécution ? **

Oui. Ralph relit prd.json au début de chaque itération. Vous pouvez modifier les descriptions d'histoires entre les itérations, ajouter de nouvelles histoires ou marquer manuellement une histoire comme passes: true (l'ignorer).

**Q : Que doit faire Ralph s'il est bloqué sur une histoire qui échoue à plusieurs reprises ? **

1. Vérifiez progress.txt pour comprendre la raison de l'échec
2. Ajouter plus de contexte dans les notes
3. Divisez l'histoire (peut-être trop grande)
4. Résolvez manuellement le problème de blocage, puis réexécutez

**Q : Puis-je faire d'autres choses pendant que Ralph court ? **

Oui. Ralph est conçu pour être un « humain en boucle » : vous n'avez pas besoin de le regarder. En mode AFK, commencez avant de quitter le travail et vérifiez les résultats le lendemain matin. Ne modifiez simplement pas le fichier sur lequel Ralph travaille.

**Q : Comment contrôler les coûts ? **

Trois méthodes : définir un max_iterations raisonnable, maintenir la granularité de l'histoire appropriée (pour réduire les itérations inutiles) et effectuer d'abord un essai à petite échelle pour confirmer que le processus est correct. De manière générale, pour les projets de 10 à 20 histoires, les frais de l'API se situent entre 50 et 100 $.

Résumé

Le flux de travail de Ralph peut être divisé en cinq étapes :

安装 → 编写 PRD → 配置质量门禁 → 运行循环 → 检查结果

Le concept de base reste le même : Laissez le document être la seule source de vérité, laissez chaque itération repartir de zéro et laissez le contrôle qualité contrôler pour vous.

Maintenant, revenez à votre projet, préparez prd.json, exécutez ./scripts/ralph/ralph.sh --tool claude et allez préparer une tasse de café.

Lectures complémentaires

• Analyse approfondie de Ralph Wiggum - Revisiter les principes fondamentaux de Ralph
• GSD Deep Analysis - Un système complet d'ingénierie de contexte construit sur la base de Ralph
• Que sont les compétences de Claude ——La compétence PRD de Ralph est une compétence de Claude
• Speckit Practical Guide - Un autre workflow de programmation IA structuré