Aller au contenu
Me contacter

Ouvert à un CDI · Métropole lilloise

Tous les articles
Mis à jour le 8 min de lecture

Claude Code au quotidien : bonnes pratiques, MCP et TDD

Comment je travaille avec Claude Code depuis fin 2025 : un contexte versionné dans le dépôt, des garde-fous techniques, une démarche spec, plan puis TDD, des agents de revue et quelques serveurs MCP. Une méthode utilisée sur un projet en production, la DXP Goodbizz, ainsi que sur ce portfolio et mon socle Next.js × Payload, avec les limites rencontrées en chemin.

  • Claude Code
  • IA
  • MCP
  • TDD
  • Next.js

Quand j’ai commencé à utiliser Claude Code, je cherchais une façon de travailler avec lui sans perdre la compréhension du projet ni le contrôle sur ce qu’il modifie. J’utilise Claude Code au quotidien depuis fin 2025, sur des projets en production, comme la DXP Goodbizz, comme sur ce portfolio et sur un socle réutilisable de sites vitrines en Next.js et Payload CMS. Au fil des mois, j’ai fini par adopter une méthode simple : donner à l’assistant le même contexte qu’à un développeur qui rejoint l’équipe, l’empêcher techniquement de faire ce qu’il ne doit pas faire, et vérifier ce qu’il annonce avant de l’accepter.

Pourquoi structurer le travail avec un assistant IA ?

Sans contexte, un assistant devine. Il choisit une convention plausible, une API qu’il croit connaître, une structure de fichiers « habituelle », et le résultat, qui compile souvent, ne ressemble pas pour autant au reste du projet. Il faut alors le reprendre à la main.

Avec un contexte versionné, il peut suivre les règles du projet comme le ferait un nouveau venu bien accueilli. L’effort se fait une fois, dans le dépôt, et profite à chaque session. C’est ce qu’on appelle souvent le context engineering : organiser et maintenir les informations utiles que l’assistant doit consulter avant et pendant son travail, plutôt que de les répéter dans chaque demande.

Que mettre dans CLAUDE.md, et que laisser ailleurs ?

Claude Code lit automatiquement le fichier CLAUDE.md à la racine du projet. La tentation est d’y tout mettre ; je fais l’inverse, avec un fichier court qui renvoie vers le reste.

  • CLAUDE.md : le but du projet, la stack, les règles non négociables en une ligne chacune, les commandes de vérification, et un tableau « où trouver quoi » ;
  • .claude/rules/ : des règles courtes et actionnables (git, sécurité des changements, pas de sur-ingénierie, TypeScript, tests, puis celles propres au projet comme Next.js ou SCSS) ;
  • docs/ : le « pourquoi » et les faits du projet (architecture, design system, stratégie de tests) ;
  • .claude/checklists/ : la définition de « terminé » d’une fonctionnalité.

Le fichier lui-même tient en une page. En voici la forme, réduite à l’essentiel :

# my-project

Showcase site in production. Next.js 16 (App Router), strict TypeScript,
SCSS Modules, npm.

## Non-negotiable rules

- Git: read-only for the assistant, enforced by a PreToolUse hook.
- Minimal diff, root cause before any fix.
- Never claim "done" without running the checks below.

## Checks

npm test · npm run lint · npx tsc --noEmit · npm run build

## Where to find what

| Topic        | File                 |
|--------------|----------------------|
| Architecture | docs/architecture.md |
| Short rules  | .claude/rules/       |

Chaque règle vit à un seul endroit, et un fichier qui se met à expliquer ce qu’un autre explique déjà renvoie vers lui. Pour Next.js 16, dont les API ont changé, une consigne simple évite beaucoup d’erreurs : lire la documentation disponible dans node_modules au lieu de s’appuyer uniquement sur sa mémoire.

Comment poser des garde-fous qui ne dépendent pas de la bonne volonté ?

Je préfère garder les commits, les branches et l’historique sous mon contrôle. J’ai donc retiré à Claude Code la possibilité de modifier l’état Git. Dans mon environnement, un hook bloque donc les opérations d’écriture sur Git, quel que soit le mode de permission. Cette règle figure dans les consignes, mais c’est un hook PreToolUse qui l’applique, c’est-à-dire un script exécuté avant chaque commande shell et qui refuse les opérations interdites. Claude Code lui transmet l’appel en attente au format JSON sur l’entrée standard, et un code de sortie 2 bloque l’appel. En voici le principe, simplifié :

// .claude/hooks/block-git-writes.js (simplified): default-deny for git
const { readFileSync } = require('node:fs')

const ALLOWED = new Set(['status', 'log', 'diff', 'show', 'blame', 'ls-files', 'fetch'])

function blockedGitSubcommand(command) {
  for (const segment of command.split(/&&|\|\||;|\||\n/)) {
    const [bin, subcommand] = segment.trim().split(/\s+/)
    if (bin === 'git' && subcommand && !ALLOWED.has(subcommand)) return subcommand
  }
  return null
}

// Claude Code sends the pending tool call as JSON on stdin
const input = JSON.parse(readFileSync(0, 'utf8'))
const blocked = blockedGitSubcommand(input.tool_input?.command ?? '')
if (blocked) {
  console.error(`git ${blocked} changes the repository: ask the user to run it`)
  process.exit(2) // exit code 2 blocks the call, stderr is shown to Claude
}

Le vrai script ajoute une seconde passe, plus large, pour repérer une écriture cachée dans un pipe ou un sous-shell, et bloque aussi la création ou la fusion de pull requests. Sur ce portfolio, seules les commandes de vérification (lint, typage, tests, build) sont par ailleurs autorisées d’office, et tout le reste demande mon accord.

Le hook se déclare dans .claude/settings.json, versionné avec le projet, si bien que chaque session et chaque poste en héritent. Le matcher Bash le limite aux commandes shell :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/block-git-writes.js\""
          }
        ]
      }
    ]
  }
}

Pourquoi passer par une spec, un plan, puis des tests ?

Pour les fonctionnalités non triviales, je ne commence pas par demander à Claude de coder. Chaque étape laisse une trace versionnée :

  1. une spécification, qui fixe le périmètre fonctionnel, précise le « quoi » et tranche les questions encore ouvertes ;
  2. un plan d’implémentation, découpé en tâches courtes et vérifiables, qui liste les fichiers concernés et les tests attendus ;
  3. une implémentation en TDD, où le test est écrit en premier et vu en échec avant que le code minimal ne le fasse passer ;
  4. une vérification complète (tests, lint, typage, build), dont les résultats sont lus avant de considérer le travail comme terminé ;
  5. une revue finale, suivie du commit, que je fais moi-même.

La règle la plus utile s’énonce en trois mots, preuve avant affirmation. Elle vise le « c’est corrigé » annoncé sans aucune vérification : une modification n’est pas terminée parce que Claude estime qu’elle devrait fonctionner.

L’assistant doit lancer les vérifications prévues, puis lire leur résultat avant de conclure. Sur mon socle Next.js × Payload, dont la toute première spec décrit l’environnement Claude Code lui-même, avant toute ligne de code applicatif, cette discipline se traduit par 15 specs, 22 plans et plus d’une centaine de fichiers de tests (unitaires, d’intégration et de bout en bout), exécutés par la CI à chaque pull request et à chaque push sur la branche principale. Les images Docker ne sont publiées qu’une fois toutes ces vérifications passées, et c’est cette même image qui est déployée en staging, sur un VPS distinct, comme en production.

À quoi servent les skills et les agents ?

Un skill est un workflow réutilisable, décrit dans un fichier que l’assistant charge quand la tâche s’y prête. J’utilise beaucoup ceux du plugin Superpowers, qui couvrent le cadrage d’une idée, la rédaction et l’exécution d’un plan tâche par tâche, le TDD, le débogage méthodique et la vérification avant d’annoncer qu’un travail est fini. S’y ajoutent des skills propres à chaque projet, pour ajouter un contenu, corriger un bug, modifier un composant ou préparer une mise en production.

Un agent est un assistant spécialisé, lancé dans un contexte neuf. Ce portfolio en compte quatre (frontend, code review, SEO, accessibilité) et le socle Payload en compte neuf, notamment pour la sécurité, la performance et les tests. Les agents de revue sont en lecture seule : ils signalent, ils ne corrigent pas. Leur intérêt vient justement du fait qu’ils ne sont pas ceux qui viennent d’écrire le code. Lorsqu’un même contexte conçoit, implémente puis juge sa propre solution, certains problèmes peuvent facilement passer inaperçus. Sur ce site, ils vérifient par exemple la cohérence d’une implémentation avec les règles du projet, l’accessibilité d’un composant ou une fonctionnalité au regard de sa spécification.

Quels serveurs MCP et outils connectés au quotidien ?

Avec les serveurs MCP, Claude Code accède aux outils que j’utilise réellement, au lieu de travailler uniquement à partir du code présent dans le dépôt.

J’en utilise surtout cinq :

  • Context7, qui fournit la documentation à jour des librairies, là où le modèle s’en remettrait à sa mémoire ;
  • Google Search Console, pour appuyer un plan SEO sur les vraies données d’indexation et de recherche ;
  • Playwright, pour vérifier un rendu ou une interaction dans un vrai navigateur ;
  • Claude in Chrome, pour certaines vérifications directement dans le navigateur ;
  • Serena, pour naviguer dans le code par symboles et non par simple recherche de texte.

Le navigateur coûte cher en contexte, aussi je le réserve à une passe finale, quand le rendu se vérifie difficilement autrement (animation, mise en page délicate, design). Pour le reste, le HTML et le CSS générés suffisent.

Quelles limites ?

Chacune de ces limites est apparue sur ce portfolio et y a laissé une règle ou un script. Aucune n’empêche de travailler avec l’assistant, mais aucune ne se règle une fois pour toutes :

  • Le ton des textes. En français, l’assistant glisse volontiers des formules toutes faites ou des tournures calquées sur l’anglais, dans une documentation comme dans un message de commit. Une règle de rédaction et un script de détection des tics servent de premier filtre, mais seule une relecture attentive les repère toutes.
  • Les faits plausibles. Sans le code source sous les yeux, un assistant complète avec ce qui semble probable. Une règle lui impose donc de lire le code concerné avant d’affirmer un fait technique, dans une réponse comme dans une documentation.
  • Le coût en contexte. Un navigateur piloté, un skill de 10 à 35 Ko ou un agent qui relit le projet depuis zéro consomment vite le contexte et les quotas ; d’où une seule passe de navigateur en fin de tâche, et des skills et des agents lancés seulement quand l’étape le justifie.
  • L’initiative de trop. Une question posée pour comparer deux options a déjà été comprise comme une demande de modification, et le changement appliqué dans la foulée. Depuis, la consigne est explicite : une question appelle une analyse des options, et le code ne change qu’après un accord clair.
  • Les trous du garde-fou. La première version du hook git pouvait être contournée par une commande imbriquée. À l’inverse, il bloque une commande qui contient seulement le texte d’une écriture git, une recherche dans la documentation par exemple.

Qu’est-ce qui ne se délègue pas ?

Je garde d’abord la réflexion. Avant de solliciter l’assistant, je pose par écrit ce que je veux obtenir, les contraintes et les pistes que j’ai déjà en tête. Quand la demande le justifie, je fais d’abord améliorer ce prompt, que je relis avant de le confier à Claude Code.

Les décisions ne lui reviennent pas davantage. Les questions ouvertes d’une spec, les arbitrages entre deux options ou le contenu publié sous mon nom, je les tranche sur mes propres projets et je les soumets au lead dev, au chef de projet ou au client sur les leurs. Quant au code, c’est moi qui le relis, le valide et le commite.