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 ?

Ces cinq workflows visent une taille précise : la tâche qui tient en une session de vingt minutes et se termine par un diff relisible. En dessous, vous irez plus vite à la main. Au-dessus, aucun des cinq ne s'applique tel quel, il faut d'abord découper la tâche. Les situations ci-dessous sont celles où ce format apporte le plus.

• 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

Si vous ne retenez qu'une ligne de ce tableau, prenez la première. La lecture sans modification est ce qui distingue une session cadrée d'une session qui part en vrille : elle force l'agent à nommer les fichiers concernés avant d'écrire, et vous donne un point de contrôle où corriger le périmètre coûte zéro. Les quatre autres gestes découlent de celui-là, ils protègent le même acquis à des moments différents du cycle.

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)

Ces quatre symptômes ont la même racine : une information manquante dans le prompt que l'agent a comblée par une hypothèse. La correction consiste donc toujours à ajouter une contrainte explicite, jamais à relancer le même prompt en espérant un meilleur résultat. Un point de méthode : quand une correction s'applique, réécrivez le prompt d'origine plutôt que d'empiler un message de rattrapage, sinon la contrainte disparaît à la session suivante.

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

Cochez ces cinq points sur votre propre dépôt, pas en relisant la page. Le troisième est le plus difficile à valider honnêtement : la dérive de périmètre ne se voit pas dans le résultat final, elle se voit dans le git diff. Comptez les fichiers modifiés et comparez au nombre annoncé dans le plan, c'est la seule mesure objective.

• 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é

Pour aller plus loin

• Quelle brique utiliser quand ? : Où ranger chaque règle de ces workflows : CLAUDE.md, rules, settings, hooks ou skill.
• Claude Code dans VS Code : Les mêmes workflows transposés dans l'éditeur, avec diff côte à côte et checkpoints.
• Dépannage avancé : permissions, config, diff : Le diagnostic à mener quand un de ces workflows bloque sur une permission ou un diff trop large.

×

📖 Voir la documentation →