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.

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.

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

Exécutez uniquement l'étape validée

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

Validez
Fenêtre de terminal
```
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.

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.

Plan borné

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

Exécution étape par étape

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

Validez après chaque étape
Fenêtre de terminal
```
uv run ruff check .
uv run pytest -q
```

Workflow 3, Ajouter un test manquant

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

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.

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

Exécution

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

Validez
Fenêtre de terminal
```
uv run pytest -q
```
Puis vérifiez que ruff reste vert :
Fenêtre de terminal
```
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.

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.

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.

Exécution

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

Validation (sans test technique mais avec contrôle humain)
Fenêtre de terminal
```
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.

Vérifiez l'état courant
Fenêtre de terminal
```
git status
git log main..HEAD --oneline
```
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
Validez une dernière fois avant de pousser
Fenêtre de terminal
```
uv run ruff check .
uv run pytest -q
```
Poussez vous-même
Fenêtre de terminal
```
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

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

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

Briques Claude Code : quand utiliser quoi Choisir entre CLAUDE.md, rules, settings, hooks, skills pour chaque règle

Dépannage avancé Claude Code Diagnostiquer permissions, config, diff et sessions qui dérivent

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