Claude Craft 3 : 126 commandes, 55 skills et Ralph Wiggum v2.0

Troisième volet de la série Claude Craft, et c'est précisément là que le framework bascule du statut de promesse à celui d'infrastructure de travail à plein régime. Les deux épisodes précédents ont posé les fondations — architecture des agents spécialisés, dynamique multi-agents avec BMAD v6. Mais l'impact quotidien vient de trois mécanismes concrets : les 126 slash commands que tu invoques dix fois par jour, les 55 skills qui calibrent le comportement de l'agent sans répéter le contexte à chaque session, et Ralph Wiggum v2.0 qui maintient la boucle longue sans dériver. Claude Craft v8.18.1, sorti le 28 juin 2026, consolide ces trois piliers en un système cohérent. Ce guide entre dans le détail opérationnel : configuration du circuit breaker, hooks Claude Code natifs, dashboard de monitoring. Du concret, pas de la théorie.

126 commandes, 15 namespaces : la carte du territoire

Claude Craft organise ses 126 commandes core en 15 namespaces thématiques — 220 au total en comptant les commandes d'infrastructure. La logique est simple : chaque namespace couvre une dimension précise du cycle de développement, et le routage est automatique en fonction du stack détecté dans le projet. Un repo Symfony n'expose pas les mêmes commandes /{tech}:* qu'un projet React ou Flutter. Le framework scanne composer.json, package.json et pyproject.toml au démarrage, puis active uniquement les namespaces pertinents — les autres restent masqués.

• /workflow:* — cycle de vie complet : init, auto-sprint, configuration initiale du projet
• /team:* — orchestration multi-agents : audit architecture, sprint coordonné, revue collective
• /common:* — utilitaires transverses : pre-commit-check, ralph-run, getting-started
• /sprint:* — opérations backlog : next-story, story-validate, story-complete
• /qa:* — assurance qualité : TDD flows, recette navigateur, mutation testing
• /gate:* — points de validation avant merge : DoD check, coverage gate, security gate
• /{tech}:* — commandes stack-specific (react, symfony, flutter, node, python...)
• /paperclip:* — 8 commandes d'optimisation de contexte, ajoutées en v8.18

L'atout central de cette organisation, c'est la découvrabilité. Quand tu arrives sur un projet inconnu, /common:getting-started génère un plan d'intégration personnalisé en analysant la structure du dépôt. Quand tu veux valider avant de committer, /common:pre-commit-check enchaîne lint, types, tests unitaires et audit de sécurité — sans configurer le moindre hook git manuellement. Et quand le sprint déraille, /team:audit produit une revue architecture plus sécurité en mode multi-agents, en quelques minutes.

/workflow:auto-sprint : le sprint de bout en bout en une commande

La pièce maîtresse de v8.18.0, c'est /workflow:auto-sprint. Elle orchestre l'intégralité d'un sprint dans un enchaînement isolé : décomposition de la story, implémentation en contexte dédié, ouverture de PR, surveillance du CI, revue automatisée, merge conditionnel. Chaque phase tourne dans son propre contexte de sub-agent — ce qui remplace le /clear manuel entre les étapes et évite la contamination de contexte qui fait dériver les agents sur les tâches longues.

# Sprint complet avec merge automatique si les gates passent
/workflow:auto-sprint --story "US-42" --auto-merge --max-fix-attempts 3

# Suivre l'avancement
/workflow:status

# Stack Symfony : générer un service avec test et migration Doctrine
/symfony:generate-service UserNotificationService --with-test --with-migration

# Stack React : générer un composant aux standards du projet
/react:generate-component Button --with-story --with-test

# Gate qualité avant merge : vérifie coverage, lint et sécurité
/gate:pre-merge --story "US-42"

Le flag --max-fix-attempts 3 est le premier filet de sécurité de la chaîne. Sans lui, un agent bloqué sur une erreur CI peut itérer indéfiniment. Avec trois tentatives plafonnées, il produit un rapport d'échec explicite et passe la main au développeur. C'est le circuit breaker primitif — suffisant pour les tâches courtes et déterministes, insuffisant pour les refactorings de plusieurs heures. C'est là que Ralph Wiggum v2.0 prend le relais.

55 skills : injecter le bon expert sans charger le contexte

Les 55 skills de Claude Craft sont des best-practices encodées dans le format natif Claude Code. La différence avec des règles CLAUDE.md classiques réside dans le mécanisme de chargement : les skills sont référencés via @ et injectés à la demande, pour un coût de contexte de ~3 500 tokens en mode actif contre ~70 000 si tout était embarqué statiquement dès le démarrage. En pratique, seuls les skills pertinents au stack et à la tâche en cours sont activés — les autres restent en attente sur l'étagère.

• Architecture : DDD (aggregate, repository, domain event), hexagonale, CQRS, Clean Architecture
• Testing : TDD red-green-refactor, mutation testing, contract testing, test isolation
• Security : OWASP Top 10, injection, validation d'entrée, secrets management, CSRF
• Performance : N+1 Doctrine, cache strategy, profiling Symfony, lazy loading
• DevOps : Docker multi-stage, CI gate, GitOps, observabilité
• Code quality : SOLID, refactoring patterns, clean code, dette technique

L'activation est contextuelle par défaut : Claude Craft scanne le CLAUDE.md du projet et les fichiers de configuration au démarrage de session, puis charge les skills pertinents automatiquement. Tu peux aussi forcer un skill pour un contexte spécifique, ou consulter ce qui est actif dans la session courante sans quitter le terminal.

# Activer explicitement un skill pour la session courante
/common:activate-skill security-owasp

# Combiner plusieurs skills pour un contexte DDD + Symfony
/common:activate-skill symfony-doctrine ddd-aggregate-design

# Voir les skills actifs et leur coût en tokens
/common:skills-status

# Lister tous les skills disponibles
/common:skills-list --filter architecture

Ralph Wiggum v2.0 : de la boucle naïve au supervisor d'agent

La technique Ralph Wiggum originale — popularisée par Geoffrey Huntley en 2025 — était d'une simplicité brutale : réinjecter le même prompt jusqu'à ce que la condition de sortie soit atteinte. Une boucle while avec un LLM à l'intérieur. Ça tient sur les tâches courtes et déterministes. Ça s'effondre sur les refactorings de trois heures où l'agent commence à tourner en rond sans s'en rendre compte. V2.0, intégrée nativement dans Claude Craft, ajoute quatre couches au-dessus : un circuit breaker adaptatif, une auto-détection des dérives comportementales, un dashboard temps réel et des hooks Claude Code natifs. Ce n'est plus une boucle — c'est un agent supervisor.

La commande d'entrée dans Claude Craft est /common:ralph-run, orchestrée par l'agent ralph-conductor. Ce conductor gère la boucle, valide la Definition of Done à chaque itération via les templates DoD du projet, et déclenche les mécanismes de protection dès qu'une dérive est détectée. L'intégration native avec /goal de Claude Code permet de formuler une condition de sortie vérifiable objectivement — build qui passe, tests verts, coverage atteint — plutôt qu'une correspondance de chaîne fragile et silencieuse.

# Lancer Ralph sur une tâche longue avec DoD explicite
/common:ralph-run "Migrer tous les controllers vers l'architecture hexagonale" \
  --max-iterations 20 \
  --completion-promise "RALPH_DONE: migration controllers terminée" \
  --ralph-mode supervised

# Mode non-supervisé pour les runs overnight
/common:ralph-run "Appliquer les correctifs Dependabot sur toutes les dépendances mineures" \
  --max-iterations 30 \
  --ralph-mode unattended

# Vérifier l'état du circuit breaker en temps réel
ralph --circuit-status

# Reset manuel si le circuit s'est ouvert sur une erreur transitoire
ralph --reset-circuit

Circuit breaker adaptatif : les seuils qui arrêtent la dérive

Le circuit breaker de Ralph Wiggum v2.0 fonctionne sur trois états — CLOSED (normal), OPEN (bloqué), HALF_OPEN (récupération) — avec des seuils configurables selon la nature des erreurs. La configuration se fait dans .ralphrc à la racine du projet, surchargeable via variables d'environnement pour le CI.

# .ralphrc — configuration du circuit breaker Ralph Wiggum v2.0

# Ouvre le circuit après N itérations sans modification de fichier
CB_NO_PROGRESS_THRESHOLD=3

# Ouvre le circuit après N itérations avec la même erreur répétée
CB_SAME_ERROR_THRESHOLD=5

# Ouvre le circuit si la qualité des outputs chute de plus de X%
CB_OUTPUT_DECLINE_THRESHOLD=70

# Durée de cooldown avant tentative de récupération (état HALF_OPEN)
CB_COOLDOWN_MINUTES=30

# true = reset automatique au redémarrage (utile en CI)
CB_AUTO_RESET=false

# Webhook d'alerte si le circuit s'ouvre
ALERT_WEBHOOK_URL=https://hooks.slack.com/services/xxx/yyy/zzz
ALERT_ON_CIRCUIT_OPEN=true
ALERT_ON_MAX_ITERATIONS=true

Le seuil le plus décisif en pratique, c'est CB_NO_PROGRESS_THRESHOLD=3. Zéro modification de fichier après trois itérations, c'est l'agent qui produit du texte sans effet réel — la dérive la plus courante sur les refactorings complexes, où le modèle commence à réfléchir à voix haute plutôt qu'à agir. CB_SAME_ERROR_THRESHOLD=5 cible les boucles d'erreur CI : la même exception de compilation répétée cinq fois indique que l'agent ne sait pas corriger ce problème seul et qu'il a besoin d'un contexte supplémentaire. L'état du circuit est persisté dans .ralph/status.json, ce qui permet de reprendre une session interrompue sans perdre l'historique des itérations.

Hooks Claude Code natifs : l'infrastructure bas niveau de la boucle

Ralph Wiggum v2.0 s'appuie sur deux hooks Claude Code configurés dans .claude/settings.json. Le hook Stop intercepte chaque tentative d'arrêt de l'agent avant qu'elle soit exécutée — c'est le mécanisme fondamental qui transforme une session Claude Code ordinaire en boucle persistante. Le hook PostToolUse sur les commandes Bash enregistre chaque sortie d'outil dans l'historique Ralph, alimentant la détection de dérive par analyse des patterns répétés.

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "ralph --check-dod && echo 'DOD_MET' || echo 'CONTINUE'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "ralph --record-iteration >> .ralph/history.log 2>&1"
          }
        ]
      }
    ]
  },
  "env": {
    "ENABLE_PROMPT_CACHING_1H": "true"
  }
}

Le hook Stop vérifie la Definition of Done avant chaque arrêt potentiel. Si la commande ralph --check-dod retourne un code non-zéro, Claude Code reçoit CONTINUE et relance une itération. Le hook PostToolUse alimente en parallèle le journal d'itérations qui permet au circuit breaker de détecter les patterns de stagnation. L'activation du prompt caching 1h via la variable d'environnement est critique pour contenir les coûts API sur les sessions longues — sans caching, une boucle de 20 itérations sur un contexte de 50k tokens devient rapidement prohibitive.

Dashboard et alertes : monitorer Ralph en conditions réelles

Pour les sessions supervisées, Ralph Wiggum v2.0 expose un dashboard temps réel via tmux : état du circuit breaker, nombre d'itérations écoulées, fichiers modifiés depuis le lancement, erreurs répétées détectées. Pour les runs overnight en mode non-supervisé, les alertes webhook configurées dans .ralphrc envoient une notification Slack ou Teams dès que le circuit s'ouvre, que le maximum d'itérations est atteint, ou que la DoD est validée avec succès.

# Ouvrir le dashboard dans un panel tmux séparé
ralph --monitor

# Tester la configuration des alertes
ralph --test-alert

# Inspecter l'historique des itérations
ralph --history --last 10

# Export du rapport de session (utile pour le post-mortem)
ralph --export-report session-$(date +%Y%m%d).json

Pour intégrer Ralph dans un pipeline CI, le flag CB_AUTO_RESET=true combiné à --max-fix-attempts permet de déléguer des corrections automatiques sur les PR. L'agent essaie de corriger les erreurs CI dans la limite configurée, échoue proprement avec un rapport d'erreur si le circuit s'ouvre, et retourne un exit code non-zéro clair au pipeline. C'est la différence fondamentale entre un agent fantôme qui brûle des tokens en silence et un agent monitoré qui signale ses limites — le contrat de fiabilité que Ralph Wiggum v2.0 formalise.

# .github/workflows/ralph-autofix.yml
name: Ralph Wiggum Auto-Fix

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ralph-fix:
    runs-on: ubuntu-latest
    if: contains(github.event.pull_request.labels.*.name, 'ralph-fix')
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Setup Claude Code
        run: npm install -g @anthropic-ai/claude-code@latest

      - name: Reset circuit breaker
        run: ralph --reset-circuit
        env:
          CB_AUTO_RESET: "true"

      - name: Run Ralph auto-fix
        run: |
          /common:ralph-run "Corriger les erreurs CI de cette PR" \
            --max-iterations 5 \
            --max-fix-attempts 3 \
            --ralph-mode ci
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          CB_NO_PROGRESS_THRESHOLD: "2"
          CB_SAME_ERROR_THRESHOLD: "3"

      - name: Commit and push corrections
        run: |
          git config user.name "ralph-wiggum[bot]"
          git config user.email "ralph@noreply.github.com"
          git diff --quiet || \
            git commit -am "fix(ci): corrections automatiques Ralph Wiggum [skip ci]" && \
            git push

Claude Craft v8.18.1 n'est pas une collection d'outils — c'est une discipline de travail avec l'agent. Les 126 commandes structurent le workflow, les 55 skills maintiennent la qualité sans surcharger le contexte, et Ralph Wiggum v2.0 garantit que les tâches longues finissent sans dériver ni brûler des tokens inutilement. La partie 4 de la série abordera la configuration avancée du CLAUDE.md multi-projet et le partage de contexte entre équipes. D'ici là, l'essentiel est dans ce guide — commence par /common:ralph-run sur ta prochaine tâche longue et observe ce que le monitoring révèle sur ton flux de travail réel.