Claude Code au quotidien : méthode, MCP et TDD

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 suit 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, qui consiste à soigner ce que l’assistant lit avant d’agir davantage que la formulation de 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é.

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 embarquée dans node_modules au lieu de s’appuyer sur sa mémoire.

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

Une règle écrite peut être oubliée ; pour ce qui est difficile à défaire, mieux vaut un garde-fou technique. Dans mes projets, Claude Code ne modifie jamais l’état git, qu’il s’agisse d’un commit, d’un push, d’une branche ou d’une pull request. Cette règle figure dans les consignes, mais c’est surtout un hook PreToolUse qui l’applique, un script exécuté avant chaque commande shell et qui refuse tout ce qui n’est pas explicitement autorisé. En voici le principe, simplifié :

// PreToolUse hook: default-deny for git, only read-only subcommands pass
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;
}

// Exit code 2 blocks the tool call and shows the reason to the assistant

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. Il s’applique quel que soit le mode de permission, même si l’on désactive les confirmations. Sur ce portfolio, seules les commandes de vérification (lint, typage, build) sont par ailleurs autorisées d’office, et tout le reste demande mon accord.

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

Pour toute fonctionnalité non triviale, le travail suit le même chemin, et 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 que je trouve la plus utile tient en une phrase : preuve avant affirmation. L’assistant n’a pas le droit d’écrire « c’est corrigé » sans avoir lancé la vérification et lu son résultat. Sur mon socle Payload, cette discipline se lit dans les chiffres, avec 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 sur les branches de staging et principale.

À 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é), le socle Payload neuf, dont 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 est de relire sans les angles morts de celui qui a écrit le code, et cette étape fait partie du processus au même titre que les tests. Sur ce site, la revue a par exemple vérifié qu’un exemple de code exécuté côté serveur ne pouvait en aucun cas partager une session entre visiteurs, et confronté une affirmation de l’article sur Cora au fonctionnement réel du projet, ce qui a permis de la préciser.

Quels serveurs MCP au quotidien ?

Un serveur MCP (Model Context Protocol) ouvre à l’assistant un accès outillé à une source de données ou à un service. J’en utilise cinq au quotidien :

• 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 et Claude in Chrome, pour vérifier un rendu ou une interaction dans un vrai 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.

Ce que je ne 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.

En pratique : le socle Next.js × Payload CMS

Le socle Next.js × Payload que j’utilise pour les sites vitrines a commencé par là, puisque sa première spec décrit l’environnement Claude Code lui-même, avant toute ligne de code applicatif. On y retrouve tout ce qui précède à plus grande échelle, avec neuf agents, une douzaine de skills (nouveau bloc Payload, nouvelle collection, audit avant mise en production…), des checklists par domaine, et une CI qui enchaîne audit des dépendances, typage, lint, tests, build, puis tests de bout en bout sur le build de production.