Obtenir de bons résultats avec Claude Code

 (dzombak.com)
45 points par GN⁺ 2025-08-09 | 5 commentaires | Partager sur WhatsApp
  • Après avoir expérimenté divers agents de programmation LLM ces derniers mois, Claude Code s’est révélé être l’outil le plus satisfaisant
  • Grâce à Claude Code, environ 12 programmes et projets ont pu être réalisés en peu de temps, y compris des travaux qui n’auraient normalement pas été lancés faute de temps
  • Pour une utilisation réussie, les éléments clés sont la rédaction de spécifications claires, la mise à disposition d’une documentation expliquant la structure du projet ainsi que les commandes de build et de lint, la demande à l’IA d’effectuer sa propre revue de code, et l’usage d’un guide global d’agent personnalisé
  • Le code écrit par l’IA pouvant souvent être inexact ou inefficace, il faut impérativement vérifier soi-même tout le code et tous les cas de test, puis ajouter les tests manquants ou demander à l’IA de les écrire avant de les revérifier
  • Le guide global d’agent publié en annexe inclut des consignes de développement détaillées : plan d’implémentation par étapes, développement piloté par les tests, philosophie centrée sur la simplicité, la clarté et le pragmatisme, critères de qualité et processus de résolution de problèmes

Retour d’expérience et effets de Claude Code

  • Ces derniers mois, divers agents de programmation LLM ont été testés, et l’expérience avec Claude Code a été de loin la meilleure
  • Même si tout n’est pas parfait, il a été possible de terminer plus de 12 programmes et projets en peu de temps
  • Sans Claude Code, il aurait été presque impossible d’accomplir tout ce travail sur la même période
  • Nombre de ces tâches n’auraient même pas été tentées en raison du temps qu’elles auraient demandé

Stratégie d’utilisation de Claude Code

  • Rédiger des spécifications claires
    • Avant de commencer le projet, documenter clairement les exigences et le contexte pour les fournir à l’agent
    • Cela permet de clarifier l’orientation et le périmètre de l’écriture du code
  • Documenter la structure du projet
    • Préparer une documentation incluant la manière d’exécuter le build, le lint et les tests
    • L’agent peut ainsi explorer la base de code et travailler plus efficacement
  • Demander une revue de code à l’agent
    • Faire relire par Claude Code le code qu’il a généré permet de découvrir des pistes d’amélioration ou des bugs inattendus
  • Utiliser un guide global personnel
    • Maintenir un processus de développement cohérent via ~/.claude/CLAUDE.md, qui contient des règles personnelles sur l’approche de résolution de problèmes, l’application du TDD, le maintien de la simplicité et de la clarté, ainsi qu’une limite de trois tentatives

Validation du code écrit par les LLM

  • Le code généré par l’IA présente souvent des problèmes comme des erreurs logiques, des baisses de performance ou des tests incomplets
  • L’auteur relit manuellement tout le code et vérifie son fonctionnement
    • il ajoute lui-même les cas de test manquants
    • ou demande à l’IA de les écrire, puis revoit à nouveau le code et les tests
  • Il souligne que, dans un environnement professionnel, dès lors que son nom figure sur une PR, la responsabilité finale de la qualité lui revient

Principaux éléments du guide “global” personnel de l’agent

Ce guide est géré dans le fichier ~/.claude/CLAUDE.md

  • Philosophie et principes fondamentaux

    • Progression incrémentale : modifier par petites unités, avec compilation et tests toujours au vert
    • Apprendre du code existant : analyser les patterns du code et établir un plan avant l’implémentation
    • Pragmatisme avant tout : adopter une approche flexible adaptée au contexte du projet
    • Clarté avant tout : écrire un code lisible et explicite, en évitant les astuces inutiles

  • Définition de la simplicité

    • les fonctions et classes ont une responsabilité unique
    • éviter l’abstraction prématurée
    • réduire la complexité et viser un code qui n’a pas besoin d’être expliqué

  • Processus de travail

    • 1. Planification et définition des étapes :
      • les tâches complexes sont divisées en 3 à 5 étapes et consignées dans IMPLEMENTATION_PLAN.md
      • pour chaque étape, préciser l’objectif, les critères de réussite, les cas de test et l’état d’avancement
    • 2. Flux d’implémentation :
      • compréhension → écriture des tests (rouge) → implémentation minimale (vert) → refactorisation → commit
    • 3. Réévaluation après une limite de 3 tentatives :
      • en cas d’échec, consigner les tentatives, les erreurs et leurs causes
      • explorer des alternatives (2 à 3 approches)
      • revoir en profondeur la conception ou la décomposition du problème
      • essayer d’autres patterns ou fonctionnalités

  • Standards techniques

    • Composition en priorité, avec recours à l’injection de dépendances
    • Utiliser des interfaces pour faciliter les tests
    • Flux de données explicite
    • TDD recommandé, interdiction de désactiver les tests

  • Règles de qualité du code

    • chaque commit doit compiler, passer les tests, inclure des tests pour les nouvelles fonctionnalités et respecter le style du code
    • avant un commit, exécuter le formateur et le linter, faire une auto-revue des changements et écrire un message de commit expliquant le « pourquoi »

  • Gestion des erreurs

    • échec rapide avec messages précis
    • fournir le contexte nécessaire au débogage
    • gérer les exceptions au bon niveau, sans les masquer

  • Critères de décision

    • 1. facilité de test
    • 2. lisibilité compréhensible encore dans 6 mois
    • 3. cohérence avec les patterns du projet
    • 4. simplicité
    • 5. facilité de modification

  • Intégration au projet

    • analyser au moins 3 fonctionnalités similaires
    • réutiliser les patterns et bibliothèques existants
    • utiliser les mêmes utilitaires de test
    • l’introduction d’un nouvel outil doit être solidement justifiée

  • Quality gates

    • tous les tests passent
    • respect des règles du projet
    • aucun avertissement du linter
    • message de commit clair
    • implémentation conforme au plan
    • les TODO incluent un numéro d’issue

  • Consignes de test

    • des tests centrés sur le comportement plutôt que sur l’implémentation
    • si possible, une seule assertion par test
    • des noms clairs décrivant le scénario
    • réutiliser les utilitaires de test existants
    • les tests doivent être déterministes

  • Absolument interdit

    • contourner les hooks avec --no-verify
    • désactiver les tests
    • committer du code qui ne compile pas
    • faire des suppositions sans vérification

  • À faire impérativement

    • des commits incrémentaux
    • mettre la documentation à jour en continu
    • apprendre des implémentations existantes
    • réévaluer l’approche après 3 échecs

Projets open source réalisés avec Claude Code

À lire aussi

5 commentaires

 
wedding 2025-08-11

Le fait d’obtenir de bons résultats signifie-t-il qu’on s’est bien appuyé sur du code déjà créé par quelqu’un d’autre ?
 
aeolian21 2025-08-11

Tout ce que l’auteur a fait, tout le monde le faisait déjà depuis longtemps, donc au lieu de se vanter de choses inutiles,
ce serait bien plus pertinent d’expliquer sur quelles bases il a jugé que Claude était le meilleur par rapport aux autres LLM.
Une comparaison du code réellement généré, la fréquence des erreurs de compilation, la stabilité dans la compréhension du contexte, etc.
En réalité, celui qui comprend le mieux le contexte, c’est Gemini (1 million de tokens).
 
zxcv123 2025-08-10

Ils n'ont fabriqué que des choses inutiles et ont juste allongé le texte de façon interminable.
 
knunu 2025-08-11

Ça peut être utile à certains, haha.
 
GN⁺ 2025-08-09
Avis Hacker News

  • Aujourd’hui, j’ai eu pour la première fois une vraie expérience réussie avec Claude comme agent de code. J’avais déjà essayé Cursor auparavant, mais maintenant j’essaie surtout Claude et d’autres outils en parallèle. Comme l’article le mentionne, la clé est de rédiger des spécifications claires. Pendant deux heures, j’ai moi-même rédigé un document en 12 étapes pour organiser l’approche d’implémentation, en y ajoutant aussi du contexte. Claude a ensuite généré le code en suivant cette procédure étape par étape. À mon avis, cela m’a probablement fait gagner entre 6 et 10 heures. Maintenant, je prévois de relire, tester, ajuster progressivement et ajouter des fonctionnalités. La base de cette réussite, c’est que j’ai moi-même décrit clairement toutes les étapes que Claude devait suivre. En d’autres termes, c’est moi qui ai conçu le flux global, et Claude s’est contenté de suivre les instructions. Ce processus m’a convaincu que les développeurs intermédiaires et au-delà ne seront pas remplacés par l’IA de sitôt. Mais voir Claude lire la spécification de bout en bout et produire un code structuré et bien documenté est vraiment fascinant. Le fait de ne pas avoir à coder moi-même est impressionnant.

    • J’obtiens de bons résultats avec Claude sans me préparer à ce point. Je lui demande presque les choses étape par étape comme si j’écrivais moi-même le code. À chaque fois, j’applique immédiatement les changements, je commit, puis je relis le diff. Si Claude produit quelque chose de bizarre, je lui demande aussitôt de corriger. Et je lui indique aussi directement le code existant ou les références de fonctions que je veux voir utilisées. Avec cette méthode, on peut obtenir d’excellents résultats avec bien moins de saisie et de temps.

    • Je recommande de lire « Programming as Theory Building » de Naur. Cela m’a appris qu’il faut comprendre le problème de manière théorique et le modéliser soi-même. Sinon, le LLM peut construire sa propre théorie — potentiellement erronée.
      Lire « Programming as Theory Building » - Naur

    • Comme dans l’article, des spécifications claires sont vraiment essentielles. Je suis en train de créer un langage de programmation avec Claude, et je le ressens directement. Programmer, c’est une succession de très nombreux petits choix. Si on ne guide pas clairement, le LLM compense surtout en devinant, et il fait souvent les mauvais choix. Ces petites erreurs peuvent s’accumuler et mener à un résultat incorrect.

    • Si quelqu’un pouvait partager un exemple concret de document de spécification comme celui-ci, ce serait vraiment utile. En tant qu’autodidacte qui expérimente avec Claude Code, cela m’aiderait énormément à comprendre quel type d’informations et quel niveau de détail sont réellement utiles.

    • En réalité, pas mal de développeurs intermédiaires ou seniors ne savent pas non plus rédiger correctement une vraie spécification. Mais je comprends bien l’idée.

  • Créer ~/.claude/CLAUDE.md pour y mettre des règles ne me semble pas très efficace en pratique. Claude n’est pas humain et ne raisonne pas soigneusement sur chaque ligne de code. Des consignes subjectives et ambiguës ne suffisent pas à modifier réellement le code. Et il y a aussi le problème du « context rot ».
    (explication du context rot : phénomène où un LLM perd ou déforme le contexte au cours d’une longue conversation ou d’un long travail ; lien de référence : https://news.ycombinator.com/item?id=44564248)
    En pratique, il est impossible de tout mettre dans un seul fichier en espérant que l’IA respecte toutes les règles toute seule. Pour faire cela, il faudrait créer un sub-agent pour chaque règle et séparer ça dans un pipeline classique plutôt que de laisser faire l’IA. Mais à ce moment-là, les coûts augmentent de manière exponentielle.

    • Si le problème est le coût, une fois le workflow stabilisé, on peut utiliser des LLM moins chers (même si les coûts d’exploitation restent élevés). On peut aussi réduire les coûts via le fine-tuning, l’optimisation de prompts, des techniques spécialisées de distillation, etc. Il existe déjà beaucoup de recherches sur le sujet.

    • Je me demande ce qu’il serait bon d’inclure dans CLAUDE.md.

  • Quand on regarde les projets d’exemple en bas de page, la plupart sont des logiciels optimisés pour un objectif très précis. Je pense qu’à l’avenir, les projets open source évolueront aussi vers des formes très spécialisées, conçues pour répondre au besoin d’une seule personne. J’ai l’impression que ce type de logiciel utilitaire va devenir du code jetable généré d’un seul coup par des LLM.

  • Mon approche de Claude Code continue d’évoluer. Je n’ai pas encore réussi à faire contribuer Claude Code directement à des fonctionnalités vraiment significatives dans la grosse web app de l’entreprise. Les spécifications aident un peu, mais au final le processus finit par dériver dans une direction étrange, puis s’enferme dans une boucle de mauvais choix répétés. C’est peut-être une limite de Claude, ou peut-être que ma spécification n’est pas encore assez précise. J’ai beaucoup expérimenté, mais pour tout ce qui est « difficile » ou demande beaucoup d’expertise métier, j’ai eu tellement d’échecs que je n’essaie plus vraiment. À la place, sur recommandation d’un ami, j’ai commencé à utiliser Claude pour des tâches de backlog qui ne me coûtent presque aucun effort mental. Par exemple, je lui ai demandé de créer des tests Playwright dans un nouveau workspace, un travail auquel je ne tiens pas particulièrement. Ça a très bien marché. Je lui ai expliqué l’expérience utilisateur comme je l’aurais fait à une personne, et je lui ai indiqué le chemin du serveur de dev. Je lui ai demandé d’utiliser Playwright MCP pour découvrir comment utiliser telle ou telle feature, de documenter l’exécution, d’écrire les tests et de déboguer les erreurs. Cela incluait aussi le fait de fouiller le code UI du projet pour ajouter des sélecteurs data-testid. J’ai tout résumé dans un master task.md, puis je lui ai demandé de créer aussi des fichiers markdown de tâches séparés pour chaque feature. Cette méthode a été très efficace. Je l’ai même utilisée pour une fonctionnalité complexe où deux utilisateurs navigateur interagissent d’une manière peu intuitive. Ce n’était pas correct à 100 %, mais plus c’était complexe, plus il fallait simplement corriger un peu le contexte et le code. Globalement, cela a réglé d’un coup des tâches pénibles qui auraient pris plusieurs jours.

  • Le mieux a été de garder CLAUDE.md aussi minimal que possible, idéalement sous les 100 lignes.

    • un résumé du contexte essentiel et des objectifs du projet
    • une description minimale de la structure du projet pour repérer types, interfaces et helpers
    • seulement les commandes principales, pour éviter de reparcourir package.json en boucle Pendant le flux d’implémentation/test, d’après mon expérience, Claude avait tendance soit à vouloir écrire tous les tests d’avance, soit à tout implémenter dès qu’un import échouait (ce qui n’est pas une vraie approche TDD). J’ai donc créé un hook appelé TDD-Guard pour lui imposer de ne faire passer qu’un seul test à la fois, de faire en sorte que le test échoue pour la bonne raison, puis d’implémenter le minimum de code nécessaire pour le faire passer. Pour la qualité du code, j’ai automatisé husky, lint-staged, commitlint, etc., avec d’excellents résultats. Cela permet de préserver du contexte pour des informations plus importantes. Je suis d’accord pour dire que lorsque Claude Code bloque, la meilleure solution reste qu’un développeur intervienne directement. En revanche, rester sur des conseils trop généraux est frustrant.
    • Si l’approche d’automatisation vous intéresse :

  • Cela fait plus d’un mois que je travaille tous les jours avec Claude Code. J’ai aussi essayé Cursor, Q et d’autres, mais Claude Code est bien meilleur. Les conseils mentionnés dans l’article recoupent beaucoup de choses que j’ai moi-même apprises.
    Pour partager quelques réflexions supplémentaires :

    • Je commence par une session d’idéation avec Claude dans la console web. J’explique les objectifs du projet, puis on esquisse ensemble le domain modeling et les grandes étapes. Pour un petit projet, quelques heures de va-et-vient suffisent. C’est là que naît la première version de CLAUDE.md.

    • Quand je démarre le projet réel, Claude lit à la fois mon CLAUDE.md global et le CLAUDE.md du projet. C’est le fonctionnement de chaque session.

    • En cours de route, je demande aussi à Claude Code de mettre à jour en continu le CLAUDE.md du projet, en marquant l’avancement par rapport au plan et, en fin de session, en y ajoutant un résumé du projet, son fonctionnement, comment naviguer dans le code, etc. Cela joue un peu le rôle de mémoire à long terme, et ça a bien marché.

    • Même avec de bonnes guidelines, Claude a tendance à vouloir prendre les devants. Donc, pour les tâches auxquelles je participe directement, je le force à avancer par petits incréments très ciblés. Pour quelque chose d’éphémère ou un prototype, en revanche, je le laisse implémenter librement.

      • Je me demande si l’abonnement à 20 $ a un bon rapport qualité-prix par rapport à Cursor, et s’il faut l’utiliser tous les jours pour que cela vaille vraiment le coup.

  • Au niveau du projet, il vaut mieux garder CLAUDE.md court et concis, puis déplacer les détails plus fins dans des sous-dossiers. Le niveau racine sert de carte. À chaque fois que l’on planifie une feature, Claude va consulter les dossiers appropriés, récupérer le contexte nécessaire et établir un plan d’implémentation étape par étape. À la fin de chaque étape, je lui demande de mettre à jour le plan avec le nouveau contexte. De cette manière, le contexte se transmet naturellement à l’étape suivante, et on peut aussi réinitialiser la fenêtre pour repartir sur de bonnes bases.

  • Je crée avec Claude Code un jeu ASCII de type Factorio. Au début, je l’ai laissé coder presque sans supervision, et il a implémenté d’un seul coup la plupart des grandes fonctionnalités (save/load, options, debug, génération de carte, construction, convoyeurs, crafting, QoL, etc.). Mais au moment de corriger les détails, si je modifiais par exemple le déplacement, cela cassait les convoyeurs, et ainsi de suite. Je lui ai donc fait ajouter une automatisation Playwright, mais les tests étaient de mauvaise qualité et remplis d’appels à sleep. En regardant le code de près, j’ai vu que l’architecture reposait sur un frontend React avec useEffect, et non sur une vraie structure de moteur de jeu. Les règles des hooks n’étaient pas bien respectées et la compréhension du timing était faible. Cette fois, j’ai donc introduit un moteur de jeu basé sur des ticks et recommencé depuis le début, tout en ajoutant des code reviews. Le rythme est plus lent, mais le développement est bien plus solide. Si j’obtiens une bonne démo, je compte la publier sur Show HN.

    • Tant que les fondations de base ne sont pas en place, la contribution humaine directe est vraiment précieuse. Une fois qu’un gros refactoring est passé, on peut ensuite se détendre un peu davantage.

  • Pour ceux qui, comme moi, ont à la fois un abonnement Claude pro et un abonnement perso, on peut simplifier le changement de compte avec quelque chose comme alias claude-personal="CLAUDE_CONFIG_DIR=~/.claude-personal claude"
    Blog sur l’usage efficace de plusieurs comptes Claude

  • Tout le monde dit que « la clé, c’est de rédiger à l’avance une spécification claire pour fournir du contexte », mais d’après mon expérience cela ne marche pas toujours. J’ai déjà fait une session CC avec de vrais experts en utilisant Opus 4 & Sonnet 4 ; la personne en face avait préparé une spec très claire, mais le résultat n’était pas meilleur que ma méthode à moi, qui consiste à demander les choses au fil de l’eau, sans CLAUDE.md, avec un contexte spécifique à chaque fois. Le workflow basé sur la spécification oubliait constamment des éléments importants, ou inventait des choses absentes du document de contexte — y compris parfois des choses explicitement interdites. Moi, au contraire, j’obtenais de meilleurs résultats avec des consignes immédiates du type : « ajoute une page CRUD pour les factures, commence d’abord par analyser le codebase ». Ce n’est qu’une anecdote empirique, mais après avoir mené plus de 100 projets avec Claude, je ne peux pas affirmer qu’une méthode soit meilleure qu’une autre, à part l’usage de hooks séparés pour l’empêcher de dépasser le cadre. Même quand beaucoup de gens disent que l’approche orientée spec est meilleure, lorsqu’on leur demande de montrer concrètement, ils passent souvent énormément de temps à corriger encore et encore des erreurs manifestes. Et même quand CLAUDE.md dit « ne fais surtout pas ceci », Claude a quand même tendance à le faire.