Claude Code pour les enquêtes sur les performances : une démarche mesurée

Pourquoi le travail de performance échoue sans mesure

Les bugs de performance invitent à la supposition. Quelqu’un remarque qu’une page semble lente ou qu’une API timeoute, et le réflexe le plus rapide est de « nettoyer » le code, ajouter du cache ou réécrire une boucle. Le problème, c’est que « on dirait lent » n’est pas une métrique, et « plus propre » n’est pas forcément synonyme de plus rapide.

Sans mesure, les équipes passent des heures à changer la mauvaise chose. Le chemin critique peut être dans la base de données, le réseau ou une allocation isolée, tandis que l’équipe polit du code qui s’exécute à peine. Pire, un changement qui semble malin peut aggraver la performance : du logging supplémentaire dans une boucle serrée, un cache qui augmente la pression mémoire, ou du travail parallèle qui crée des contention sur des verrous.

La supposition risque aussi de casser des comportements. En modifiant le code pour le rendre plus rapide, vous pouvez altérer les résultats, la gestion d’erreurs, l’ordre d’exécution ou les retries. Si vous ne revérifiez pas la correction et la vitesse ensemble, vous pouvez « gagner » un benchmark tout en livrant silencieusement un bug.

Traitez la performance comme une expérience, pas comme un débat. La boucle est simple et répétable :

• Choisissez une métrique qui représente la douleur (latence, débit, CPU, mémoire, temps DB).
• Capturez une baseline dans les mêmes conditions.
• Changez une petite chose.
• Mesurez à nouveau et comparez.

Beaucoup de gains sont modestes : gagner 8 % sur le p95, réduire 50 Mo de mémoire au pic, ou enlever une requête DB. Ces gains comptent, à condition d’être mesurés, vérifiés et reproductibles.

Le workflow : mesurer, émettre une hypothèse, changer, re‑mesurer

Cela marche mieux en boucle, pas en requête ponctuelle « rendre ça plus rapide ». La boucle vous oblige à rester honnête, car chaque action se rattache à une preuve et à un nombre que vous pouvez suivre.

Séquence claire :

• Mesurer : choisissez une métrique et enregistrez une baseline.
• Hypothèse : expliquez ce que vous pensez être lent et pourquoi.
• Changer : faites le plus petit ajustement possible qui teste l’hypothèse.
• Re‑mesurer : refaites la même mesure et comparez.

Chaque étape vous protège d’un type différent d’auto‑illusion. Mesurer d’abord vous empêche de « corriger » quelque chose qui n’était pas un vrai problème. Une hypothèse écrite vous empêche de changer cinq choses à la fois puis de deviner laquelle a compté. Des changements minimaux réduisent le risque de casser le comportement ou d’ajouter de nouveaux goulots. Re‑mesurer détecte les gains placebo (par exemple une exécution plus rapide due à un cache chaud) et expose les régressions.

« Fini » n’est pas un ressenti. C’est un résultat : la métrique cible a bougé dans la bonne direction et le changement n’a pas provoqué de régressions évidentes (erreurs, mémoire plus élevée, p95 pire, ou endpoints voisins plus lents).

Savoir quand s’arrêter fait partie du workflow. Arrêtez quand les gains se tassent, quand la métrique est déjà suffisante pour les utilisateurs, ou quand l’idée suivante demande de gros refactors pour un faible gain. Le travail de performance a toujours un coût d’opportunité ; la boucle vous aide à dépenser du temps là où ça rapporte.

Choisir la métrique et verrouiller une baseline

Si vous mesurez cinq choses à la fois, vous ne saurez pas ce qui a vraiment amélioré. Choisissez une métrique principale pour cette investigation et traitez le reste comme des signaux complémentaires. Pour beaucoup de problèmes utilisateurs, la métrique est la latence. Pour du batch, cela peut être le débit, le temps CPU, l’usage mémoire, ou même le coût cloud par exécution.

Soyez précis sur le scénario. « L’API est lente » est trop vague. « POST /checkout avec un panier typique de 3 articles » est mesurable. Gardez les entrées stables pour que les chiffres aient du sens.

Notez la baseline et les détails d’environnement avant de toucher au code : taille du dataset, type de machine, mode de build, feature flags, concurrence et warmup. Cette baseline est votre ancre. Sans elle, chaque changement peut sembler être un progrès.

Pour la latence, fiez‑vous aux percentiles plutôt qu’à une moyenne. Le p50 montre l’expérience typique, tandis que le p95 et le p99 exposent la queue douloureuse dont se plaignent les utilisateurs. Un changement qui améliore p50 mais détériore p99 peut pourtant sembler plus lent.

Décidez à l’avance de ce que « significatif » veut dire pour ne pas célébrer le bruit :

• Latence : au moins 10 % d’amélioration sur le p95 (ou un seuil fixe comme 50 ms)
• Débit : au moins 5 % de requêtes en plus par seconde au même taux d’erreur
• CPU ou mémoire : réduction suffisante pour éviter une montée en charge ou des plantages
• Coût : baisse mesurable par exécution ou par 1 000 requêtes

Une fois ces règles fixées, vous pouvez tester des idées sans bouger les objectifs.

Collecter des preuves avec du profiling et des métriques simples

Commencez par le signal le plus simple en lequel vous avez confiance. Un seul timing autour d’une requête peut vous dire si vous avez un vrai problème et à peu près son ampleur. Réservez le profiling approfondi pour expliquer pourquoi c’est lent.

Les bonnes preuves viennent généralement d’un mix de sources :

• Logs applicatifs (durée des requêtes, taux d’erreur, endpoints les plus lents)
• Traces APM (où le temps est passé entre services)
• Sorties de profiler ou flame graphs (fonctions chaudes et piles d’appels)
• Statistiques DB (requêtes lentes, attentes de verrous, taux de cache hit)
• Métriques d’infrastructure (CPU, mémoire, réseau, redémarrages de conteneurs)

Utilisez des métriques simples quand la question est « est‑ce plus lent, et de combien ? ». Profilez quand la question est « où va le temps ? ». Si le p95 a doublé après un déploiement, commencez par des timings et des logs pour confirmer la régression et la circonscrire. Si les timings montrent que la majorité du retard est dans votre code app (pas dans la DB), alors un profiler CPU ou un flame graph peut pointer la fonction exacte qui a gonflé.

Rendez les mesures sûres. Collectez ce dont vous avez besoin pour déboguer la performance, pas le contenu utilisateur. Préférez des agrégats (durées, comptes, tailles) aux payloads bruts, et redigez les identifiants par défaut.

Le bruit est réel, donc prenez plusieurs échantillons et notez les valeurs aberrantes. Exécutez la même requête 10 à 30 fois, et enregistrez la médiane et le p95 plutôt qu’une seule meilleure exécution.

Écrivez la recette de test exacte pour pouvoir la répéter après les changements : environnement, dataset, endpoint, taille du corps de requête, niveau de concurrence et méthode de capture des résultats.

Transformer les preuves en une hypothèse claire

Commencez par un symptôme que vous pouvez nommer : « p95 passe de 220 ms à 900 ms lors des pics », « CPU à 95 % sur deux coeurs », ou « la mémoire augmente de 200 Mo par heure ». Les symptômes vagues comme « ça semble lent » mènent à des changements aléatoires.

Ensuite, traduisez ce que vous avez mesuré en une zone suspecte. Un flame graph peut montrer beaucoup de temps en encodage JSON, une trace peut révéler un chemin d’appels lent, ou les stats DB peuvent montrer qu’une requête domine le temps total. Choisissez la plus petite zone qui explique la majorité du coût : une fonction, une requête SQL unique, ou un appel externe.

Une bonne hypothèse tient en une phrase, est testable et liée à une prédiction. Vous demandez à tester une idée, pas à un outil de rendre tout plus rapide magiquement.

Modèle simple d’hypothèse

Utilisez ce format :

• À cause de (preuve), (suspect) cause (symptôme).
• Si nous changeons (comportement spécifique), alors (métrique) devrait s’améliorer d’environ (montant).
• Nous saurons que ça a marché si (résultat de la re‑mesure).

Exemple : « Parce que le profil montre 38 % du CPU dans SerializeResponse, l’allocation d’un nouveau buffer par requête provoque des pics CPU. Si nous réutilisons un buffer, la latence p95 devrait baisser d’environ 10–20 % et le CPU chuter de 15 % sous la même charge. »

Tenez‑vous en à nommer des alternatives avant de toucher au code. Peut‑être que la partie lente est en réalité une dépendance en amont, une contention de verrou, un changement du taux de cache miss, ou un déploiement qui a augmenté la taille des payloads.

Rédigez 2 à 3 explications alternatives, puis choisissez celle que vos preuves soutiennent le mieux. Si votre changement ne bouge pas la métrique, vous aurez déjà la prochaine hypothèse prête.

Comment utiliser Claude Code sans dériver vers la supposition

Claude est le plus utile en performance quand vous le traitez comme un analyste soigneux, pas comme un oracle. Reliez chaque suggestion à ce que vous avez mesuré, et assurez‑vous que chaque étape peut être infirmée.

Donnez‑lui des entrées réelles, pas une description vague. Collez de petites preuves ciblées : un résumé de profiling, quelques lignes de logs autour de la requête lente, un plan de requête et le chemin de code spécifique. Incluez les chiffres « avant » (p95, temps CPU, temps DB) pour qu’il connaisse votre baseline.

Demandez‑lui d’expliquer ce que les données suggèrent et ce qu’elles n’expliquent pas. Ensuite forcez des explications concurrentes. Un prompt utile se termine par : « Donne‑moi 2–3 hypothèses, et pour chacune, dis‑moi ce qui la falsifierait. » Cela empêche de s’accrocher à la première histoire plausible.

Avant de changer quoi que ce soit, demandez la plus petite expérience qui puisse valider l’hypothèse principale. Gardez‑la rapide et réversible : ajoutez un timer autour d’une fonction, activez un flag de profiler, ou lancez une requête DB avec EXPLAIN.

Si vous voulez une structure serrée pour la sortie, demandez :

• Ce que les preuves indiquent (et le niveau de confiance)
• 2–3 hypothèses avec un test de falsification
• Le plus petit changement de code ou config pour tester la principale
• La métrique exacte à re‑mesurer et la direction attendue

Si l’outil ne peut pas nommer une métrique spécifique, une localisation et un résultat attendu, vous retombez dans la supposition.

Faire des changements minimaux et réversibles

Après avoir des preuves et une hypothèse, résistez à l’envie de « tout nettoyer ». Le travail de performance est plus fiable quand le changement est petit et facile à annuler.

Changez une seule chose à la fois. Si vous ajustez une requête, ajoutez du cache et refactorez une boucle dans le même commit, vous ne saurez pas ce qui a aidé (ou nui). Les changements à variable unique rendent la mesure suivante significative.

Avant de toucher au code, écrivez ce que vous attendez en nombres. Exemple : « p95 devrait tomber de 420 ms à moins de 300 ms, et le temps DB devrait chuter d’environ 100 ms. » Si le résultat manque cette cible, vous apprenez vite que l’hypothèse était faible ou incomplète.

Gardez les changements réversibles :

• Préférez un petit diff qui peut être revert proprement.
• Mettez le changement derrière un flag pour pouvoir le désactiver rapidement.
• Évitez les refactors de passage qui changent noms, formatage et logique en même temps.
• Limitez la portée : un endpoint, un chemin chaud, un appel coûteux.
• Ajoutez une courte note dans le message de commit avec les métriques attendues avant/après.

« Minimal » ne veut pas dire « trivial ». Cela signifie ciblé : cacher le résultat d’une fonction coûteuse, supprimer une allocation répétée dans une boucle serrée, ou arrêter un travail inutile pour certaines requêtes.

Ajoutez un timing léger autour du goulot suspect pour voir ce qui a bougé. Un simple timestamp avant et après un appel (loggé ou capturé comme métrique) peut confirmer si votre changement a touché la partie lente ou simplement déplacé le temps ailleurs.

Re‑mesurer et décider de la suite

Après un changement, relancez exactement le même scénario utilisé pour la baseline : mêmes entrées, environnement et forme de charge. Si votre test dépend des caches ou d’un warm‑up, explicitez‑le (par exemple : « première exécution froide, puis 5 exécutions chaudes »). Sinon vous « trouverez » des améliorations qui étaient juste de la chance.

Comparez les résultats avec la même métrique et les mêmes percentiles. Les moyennes peuvent cacher la douleur, gardez un œil sur p95 et p99, ainsi que sur le débit et le temps CPU. Lancez suffisamment de répétitions pour voir si les chiffres se stabilisent.

Avant de célébrer, vérifiez les régressions qui ne se voient pas sur un seul chiffre :

• Exactitude : les réponses correspondent toujours aux attentes.
• Taux d’erreur : timeouts, 5xx, retries.
• Mémoire : pic plus élevé ou croissance soutenue entre exécutions.
• Latence tail : p99 pire même si p50 s’améliore.
• Coût en ressources : CPU ou charge DB en hausse.

Décidez ensuite sur la base des preuves, pas de l’espoir. Si l’amélioration est réelle et que vous n’avez pas introduit de régressions, gardez la modification. Si les résultats sont mitigés ou bruités, revertissez et formulez une nouvelle hypothèse, ou isolez davantage le changement.

Si vous travaillez sur une plateforme comme Koder.ai, prendre un snapshot avant l’expérience peut rendre le rollback instantané, ce qui facilite de tester des idées audacieuses en sécurité.

Enfin, écrivez ce que vous avez appris : la baseline, le changement, les nouveaux chiffres et la conclusion. Ce court historique évite de répéter les mêmes impasses la fois suivante.

Erreurs courantes qui font perdre du temps

Le travail de performance part souvent en vrille quand le fil entre ce que vous avez mesuré et ce que vous avez changé est perdu. Gardez une chaîne de preuves propre pour pouvoir dire, avec confiance, ce qui a amélioré ou détérioré les choses.

Les récidivistes :

• Cibler la mauvaise chose : vous célébrez un median (p50) plus rapide, mais la queue (p95/p99) reste mauvaise.
• Changer plein de choses à la fois : refactors, caches et tweaks de requête dans un même commit vous empêchent de savoir ce qui a aidé.
• Croire à une exécution bruyante : un benchmark local qui varie de 20 % entre exécutions n’est pas une preuve.
• Prendre un profil comme vérité absolue : un flame graph pointe le parsing JSON, mais les requêtes s’accumulent à cause d’un ralentissement DB.
• Comparer des pommes et des oranges : jeux de données, feature flags, hardware ou niveaux de concurrence différents, puis tirer des conclusions malgré tout.

Un petit exemple : un endpoint semble lent, vous optimisez le serializer car il est chaud dans un profil. Vous retestez avec un dataset réduit et ça paraît plus rapide. En production, le p99 empire parce que la DB est toujours le goulot et que votre changement a augmenté la taille du payload.

Si vous utilisez Claude Code pour proposer des fixes, gardez‑le en laisse courte. Demandez 1 à 2 changements minimaux qui correspondent aux preuves que vous avez collectées, et exigez un plan de re‑mesure avant d’accepter un patch.

Une checklist rapide avant de déclarer « plus rapide »

Les affirmations de vitesse s’effondrent quand le test est flou. Avant de célébrer, assurez‑vous de pouvoir expliquer ce que vous avez mesuré, comment vous l’avez mesuré et ce que vous avez changé.

Commencez par nommer une métrique et notez la baseline. Incluez les détails qui font varier les chiffres : type de machine, charge CPU, taille du dataset, mode de build (debug vs release), feature flags, état du cache et concurrence. Si vous ne pouvez pas recréer le setup demain, vous n’avez pas de baseline.

Checklist :

• La métrique et la baseline sont enregistrées avec notes d’environnement (hardware, config, données, cache chaud ou froid).
• Les étapes du test sont écrites et répétables.
• Vous avez une hypothèse avec une prédiction (par exemple : « si on supprime les requêtes N+1, p95 devrait baisser d’environ 30 % »).
• Vous avez fait un petit changement réversible et documenté exactement ce qui a bougé (fichier, fonction, requête, réglage).
• Vous avez re‑mesuré avec plusieurs échantillons et comparé à l’identique (mêmes entrées, même charge).

Après que les chiffres semblent meilleurs, faites un rapide passage de vérification : exactitude (mêmes sorties), taux d’erreur et timeouts. Surveillez les effets secondaires comme mémoire plus haute, pics CPU, démarrage plus lent ou plus de charge DB. Un changement qui améliore p95 mais double la mémoire peut être un mauvais arbitrage.

Exemple : investiguer un endpoint API lent pas à pas

Une équipe signale que GET /orders paraît correct en dev, mais ralentit en staging sous charge modérée. Les utilisateurs se plaignent de timeouts, mais la latence moyenne paraît « correcte », piège classique.

D’abord, posez une baseline. Sous un test de charge stable (mêmes données, même concurrence, même durée), vous enregistrez :

• p95 : 1,8 s (l’objectif est < 600 ms)
• CPU API : ~70 % avec des pics occasionnels
• DB : une requête prend 900–1100 ms, et le temps total DB par requête est ~1,3 s

Collectez des preuves. Une trace rapide montre que l’endpoint exécute une requête principale pour les commandes, puis boucle et récupère des items liés par commande. La réponse JSON est aussi volumineuse, mais le temps DB domine.

Transformez cela en liste d’hypothèses testables :

• Une requête lente nécessite un index.
• Des requêtes N+1 multiplient le temps DB.
• La sérialisation est lente à cause d’un payload énorme.
• Une contention sur des verrous bloque les lectures pendant les écritures.

Demandez un changement minimal qui colle à la preuve la plus forte : éliminer un appel N+1 en récupérant les items liés dans une seule requête clé par IDs de commande (ou ajouter l’index manquant si le plan montre un full scan). Gardez‑le réversible et en commit focalisé.

Re‑mesurez avec la même charge. Résultats :

• p95 : 1,8 s → 720 ms
• Temps DB total : ~1,3 s → ~420 ms
• CPU : légèrement inférieur, mais toujours avec des pics

Décision : déployer le correctif (gagnant clair), puis lancer un deuxième cycle focalisé sur le gap restant et les pics CPU, puisque la DB n’est plus le limiteur principal.

Étapes suivantes : rendre ce workflow routinier

Le moyen le plus rapide de s’améliorer est de traiter chaque essai comme une petite expérience reproductible. Quand le processus est constant, les résultats deviennent plus fiables à comparer et à partager.

Un simple template d’une page aide :

• Métrique + comment elle est mesurée (outil, commande, dataset)
• Baseline (chiffres, environnement, quand capturé)
• Hypothèse (une phrase, testable)
• Changement (petit diff, ce qui a été touché)
• Résultat (avant/après, et décision)

Décidez où ces notes résident pour qu’elles ne disparaissent pas. Un endroit partagé importe plus que l’outil parfait : un dossier repo près du service, un doc d’équipe ou les notes d’un ticket. L’important est la découvrabilité. Quelqu’un doit pouvoir retrouver « pic p95 après changement de cache » des mois plus tard.

Faites des expériences sûres une habitude. Utilisez snapshots et rollback facile pour tester une idée sans peur. Si vous construisez avec Koder.ai, Planning Mode peut être un endroit pratique pour décrire le plan de mesure, définir l’hypothèse et garder la portée avant de générer un diff serré et re‑mesurer.

Fixez une cadence. N’attendez pas les incidents. Ajoutez de petites vérifications de performance après des changements comme de nouvelles requêtes, nouveaux endpoints, payloads plus gros ou mises à jour de dépendances. Un check baseline de 10 minutes maintenant peut économiser une journée de devinettes plus tard.