Claude Code : workflows concrets — debug, refactor, test, doc, PR

Vous avez installé les briques : CLAUDE.md, .claude/rules/, skills, hooks, settings.json. Maintenant, comment s’en servir sur des tâches réelles et courtes ? Cette page propose cinq mini-workflows à appliquer tels quels sur lab-claude : debug ciblé, refactor léger, ajout de test manquant, mise à jour de doc, préparation de PR. Chacun tient en 3 à 5 étapes et se termine par ruff + pytest.

Ce que vous allez apprendre

• Dérouler 5 workflows courts, bornés, et vérifiables
• Choisir la bonne combinaison prompt + skill + validation selon le cas
• Conclure chaque workflow par une commande de validation
• Éviter la dérive de périmètre sur des tâches pourtant simples

Dans quel contexte utiliser ces workflows ?

• Vous voulez des cas d’usage concrets, pas un guide généraliste de plus
• Vous débutez les sessions intermédiaires et vous voulez un modèle
• Vous voulez former une équipe à des gestes plutôt qu’à des principes

Prérequis

• lab-claude à jour, ruff et pytest verts
• CLAUDE.md, .claude/settings.json et éventuellement rules/skills/hooks en place
• Rituel de validation familier (voir mode plan, diff et validations)

Règle commune aux 5 workflows

Chaque workflow respecte le même rythme :

Cadrer -> Explorer -> Planifier -> Exécuter une étape -> Valider

Si un workflow ne se termine pas par uv run ruff check . + uv run pytest -q, il n’est pas fini.

Workflow 1 — Debug ciblé

Objectif : localiser et corriger un bug précis sans étendre le périmètre.

1. Formulez le symptôme en une phrase

   L'endpoint /health renvoie parfois une erreur 500 au premier appel.
   Lis app/main.py et tests/test_health.py.
   Ne modifie aucun fichier. Résume l'hypothèse la plus probable en 3 points.

2. Demandez un plan de correction minimal

   Propose un correctif en 1 étape, limité à app/main.py.
   N'exécute rien tant que je n'ai pas validé.

3. Exécutez uniquement l’étape validée

   Applique l'étape 1 du plan. Ne touche à aucun autre fichier.

4. Validez

   uv run ruff check .
   uv run pytest -q

Piège à éviter : laisser Claude “améliorer pendant qu’il y est”. Si le correctif tient en 5 lignes, refusez tout ajout “utile”.

Workflow 2 — Refactor léger borné

Objectif : améliorer la lisibilité d’un morceau de code sans en changer le comportement.

1. Exploration en lecture seule

   Lis app/main.py.
   Identifie 3 petites améliorations de lisibilité qui ne changent pas le comportement.
   Ne modifie aucun fichier.

2. Plan borné

   Propose un plan en 3 étapes, chacune ≤ 10 lignes modifiées.
   Limite le périmètre à app/main.py.

3. Exécution étape par étape

   Applique uniquement l'étape 1. Résume exactement ce qui a changé.

4. Validez après chaque étape

   uv run ruff check .
   uv run pytest -q

Règle du refactor

Un refactor qui casse un test n’est pas un refactor : c’est un changement de comportement. Reculez avant d’aller plus loin.

Workflow 3 — Ajouter un test manquant

Objectif : couvrir un cas réel sans toucher au code de production.

1. Identifiez le trou de couverture

   Lis app/main.py et tests/test_health.py.
   Quels cas ne sont pas couverts côté /health ?
   Ne modifie aucun fichier.

2. Plan centré sur les tests

   Propose un test manquant en une seule fonction dans tests/test_health.py.
   N'écris rien tant que je n'ai pas validé.

3. Exécution

   Ajoute uniquement la fonction de test validée.
   Ne modifie aucun fichier applicatif.

4. Validez

   uv run pytest -q

   Puis vérifiez que ruff reste vert :

   uv run ruff check .

Si le test rouge révèle un vrai bug, basculez sur le Workflow 1 — mais comme un nouveau cycle, pas dans le même prompt.

Workflow 4 — Mettre à jour la doc après un changement

Objectif : synchroniser README.md ou un .md d’un dossier après un changement de code.

1. Demandez le diagnostic de décalage

   Compare README.md et le comportement réel de app/main.py.
   Liste en 3 points ce qui est désynchronisé.
   Ne modifie aucun fichier.

2. Plan de correction documentaire

   Propose une mise à jour minimale de README.md (≤ 15 lignes ajoutées ou modifiées).
   Ne touche à aucun fichier de code.

3. Exécution

   Applique la mise à jour validée uniquement sur README.md.

4. Validation (sans test technique mais avec contrôle humain)

   git diff README.md

   Relisez le diff pour vérifier que les promesses du README correspondent au code actuel.

Workflow 5 — Préparer une PR

Objectif : obtenir un résumé clair, un titre et un corps de PR, sans pousser.

1. Vérifiez l’état courant

   git status
   git log main..HEAD --oneline

2. Invoquez /prep-pr (skill défini dans skills Claude Code)

   /prep-pr

   Le skill vous retourne :

   • un titre ≤ 70 caractères
   • un corps en 3 bullets
   • la liste des fichiers touchés
   • ce qui reste à tester manuellement

3. Validez une dernière fois avant de pousser

   uv run ruff check .
   uv run pytest -q

4. Poussez vous-même

   git push

Le skill /prep-pr n’exécute pas git push : c’est volontaire. Le push est une action visible côté équipe, elle reste humaine.

Patterns communs aux 5 workflows

Geste	Pourquoi
Toujours commencer par une lecture sans modification	Ancre le périmètre avant tout changement
Demander un plan avant d’écrire du code	Rend le changement relisible avant qu’il n’existe
Exécuter une étape à la fois	Garde les diffs petits et relisibles
Finir par ruff + pytest	Ferme la boucle proprement
Refuser les “améliorations bonus”	Protège le périmètre

Glissez pour voir

Erreurs fréquentes (transversales)

Symptôme	Cause probable	Correction
Le diff déborde sur 5 fichiers	Prompt trop vague	Re-citer explicitement les fichiers autorisés
Le test ajouté échoue au premier run	Le bug existait déjà	Traiter comme Workflow 1 dans un nouveau cycle
La doc mise à jour reste fausse	Claude a deviné au lieu de lire	Exiger “Relis app/main.py avant de modifier README”
prep-pr retourne un corps vide	Pas de commits par rapport à main	Committer au moins une fois avant le skill

Glissez pour voir

Checklist de fin de guide

• J’ai rejoué au moins 2 des 5 workflows sur lab-claude
• Chaque workflow s’est terminé par ruff + pytest verts
• Je n’ai pas laissé Claude dériver sur des “améliorations bonus”
• J’ai utilisé un skill existant pour au moins un workflow
• Je sais où rebasculer (debug, refactor, test) si un workflow révèle un autre problème

À retenir

• Les briques (prompt, rules, skills, hooks, settings) existent pour servir des workflows, pas pour elles-mêmes
• Chaque workflow reste petit, borné, et se termine par la même validation
• Un workflow qui déborde doit être arrêté et redécoupé, pas sauvé en cours de route
• /prep-pr évite de recopier la même synthèse manuellement à chaque fois
• La discipline vient de la répétition des 5 rythmes, pas de leur complexité

Prochaines étapes

Claude Code dans VS Code Transposer ces workflows dans l'éditeur avec diff et checkpoints

Vue d'ensemble Claude Code Revenir à la carte du parcours et aux sujets avancés à venir

Hooks Claude Code Automatiser le rituel de validation qui clôt chaque workflow

×

📖 Voir la documentation →