Utilisez Claude Code pour les enquêtes de performance avec une boucle répétable : mesurer, formuler une hypothèse, changer peu, puis re‑mesurer avant de déployer.
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 :
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.
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 :
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.
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 :
Une fois ces règles fixées, vous pouvez tester des idées sans bouger les objectifs.
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 :
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.
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.
Utilisez ce format :
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.
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 :
Si l’outil ne peut pas nommer une métrique spécifique, une localisation et un résultat attendu, vous retombez dans la supposition.
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 :
« 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.
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 :
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.
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 :
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.
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 :
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.
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 :
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 :
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 :
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.
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 :
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.
Commencez par un nombre qui correspond à la plainte, généralement la latence p95 pour un endpoint et une entrée précis·e. Enregistrez une baseline dans les mêmes conditions (taille des données, concurrence, cache chaud/froid), puis changez une chose et re-mesurez.
Si vous ne pouvez pas reproduire la baseline, vous ne mesurez pas encore — vous devinez.
Une bonne baseline inclut :
Écrivez cela avant de toucher au code pour ne pas déplacer la cible.
Les percentiles reflètent mieux l’expérience utilisateur qu’une moyenne. p50 montre l’expérience « typique », mais les utilisateurs se plaignent de la queue lente, donc regardez p95/p99.
Si p50 s’améliore mais que p99 se dégrade, le système peut sembler plus lent malgré une meilleure moyenne.
Utilisez des timings simples/logs quand vous demandez « est‑ce plus lent et de combien ? ». Utilisez le profiling quand vous demandez « où passe le temps ? »
Un flux pratique : confirmez la régression avec des timings de requête, puis profilez seulement après avoir prouvé que le ralentissement est réel et circonscrit.
Choisissez une métrique principale et traitez le reste comme des garde‑fous. Un ensemble courant :
Cela évite de « gagner » sur un graphique tout en provoquant des timeouts, une croissance mémoire ou une pire latence tail.
Rédigez une hypothèse en une phrase, liée à une preuve et avec une prédiction :
Si vous ne pouvez pas nommer la preuve et le mouvement attendu de la métrique, l’hypothèse n’est pas testable.
Faites‑la petite, ciblée et réversible :
De petits diffs rendent la mesure suivante significative et réduisent le risque de casser un comportement en poursuivant la vitesse.
Relancez exactement la même recette de test (mêmes entrées, environnement, forme de charge). Puis vérifiez les régressions au‑delà du chiffre principal :
Si les résultats sont bruyants, prenez plus d’échantillons ou revenez en arrière et resserrez l’expérience.
Donnez‑lui des preuves concrètes et obligez‑le à rester piloté par des tests :
Si la sortie n’inclut pas une métrique spécifique et un plan de re‑test, vous retombez dans la devinette.
Arrêtez quand :
Le travail de performance a un coût d’opportunité. La boucle (mesurer → hypothèse → changer → re‑mesurer) vous aide à consacrer du temps là où les chiffres le prouvent.
