Le setup Claude Code qu'on fait tourner

La plupart des articles sur Claude Code expliquent les options de ligne de commande. Aucun ne montre une configuration qui a tourné sur de vrais projets clients pendant des mois, et aucun ne dit quelles parties valent leur place.

Voici la nôtre. Cinq agents, vingt skills, huit hooks, huit templates, deux fichiers de règles à portée de chemin, une mémoire persistante et deux fichiers de continuité. Ce n'est pas un tutoriel d'initiation, ce n'est pas une liste de conseils. Ce sont les fichiers que nous chargeons effectivement, avec le raisonnement derrière chacun, y compris les parties que nous avons délibérément mises de côté.

Un point avant tout. Une configuration n'est pas une personnalité. Tout ce qui suit existe pour prévenir un défaut précis que nous avons vu se produire, plus d'une fois. Si vous n'avez pas encore rencontré ce défaut, vous n'avez probablement pas encore besoin de la règle correspondante.

Le problème auquel répond une configuration

Livré à lui-même, un modèle de code dérive dans trois directions, de façon prévisible.

Il écrit long. Les fonctions grossissent au-delà de ce qu'on peut tenir en tête, et les fichiers grossissent au-delà de ce qu'on peut naviguer. Il construit en avance. Demandez-lui une chose, il livre cette chose plus une abstraction pour les deux cas que vous n'avez pas demandés, plus une option de configuration que personne ne configurera. Et il accumule. Le code remplacé reste avec un suffixe _old, les branches mortes restent en commentaire, et les marqueurs // TODO s'accumulent dans le code commité où personne ne les lira jamais.

Rien de tout cela ne se corrige en demandant poliment dans un prompt. Ça se corrige avec des règles qui vivent dans des fichiers que le modèle lit à chaque fois, et avec des hooks qui refusent l'action quand une règle ne suffit pas.

Les trois fichiers, et ce qui va dans chacun

Trois couches, chacune répondant à une question différente. Placer une règle dans la mauvaise couche est l'erreur la plus courante, et elle échoue de l'une de deux façons : la règle est répétée dans dix projets, ou elle est silencieusement ignorée parce que la couche projet l'a écrasée.

~/.claude/CLAUDE.md contient ce qui est vrai sur tous les projets que vous toucherez jamais. Les limites strictes sur la longueur des fonctions et des fichiers. La toolchain, si elle est réellement la vôtre sur tous vos projets. Les règles de sécurité. La politique git. Les règles de copie et de ton, si vous avez une voix maison. Rien ici ne peut mentionner un projet spécifique, jamais. Dès que c'est le cas, ça appartient à la couche du dessous.

Le CLAUDE.md du projet contient la stack, et uniquement les règles qui surchargent ou étendent la couche globale. Le nôtre est court : la version du framework et ses changements cassants, comment accéder aux credentials, la politique de branches propre à une équipe de deux, et le registre d'agents du dépôt. Si le fichier d'un projet répète le fichier global, supprimer la répétition. Une règle dupliquée est une règle qui va diverger.

CONTEXT.md est d'une nature différente, et c'est celui que la plupart des gens n'écrivent jamais. C'est un glossaire de domaine : le vocabulaire partagé entre vous, le modèle et le code. Pas des instructions, des définitions. Ce qu'est une "intervention" dans ce métier. Ce que signifie un "deal" dans ce schéma. Une phrase chacun, décrivant ce que la chose est.

Créez-le paresseusement. Pas à la création du projet, où vous inventeriez des termes, mais la première fois qu'un terme se stabilise dans une vraie conversation et que vous remarquez que vous l'avez expliqué deux fois. Écrit trop tôt, c'est de la fiction. Écrit au bon moment, il supprime toute une classe de questions, ce qui est le but : chaque terme défini une fois est un terme que le modèle ne vous demandera plus jamais de clarifier.

Limites strictes

Ce sont les règles qui arrêtent la dérive, exprimées en nombres pour qu'elles ne soient pas négociables.

• Fonctions : 40 lignes maximum. Extraire au-delà.
• Fichiers : 300 lignes maximum. Diviser au-delà.
• Pas de features spéculatives. Implémenter ce qui a été demandé, rien d'adjacent.
• Trois cas similaires avant d'extraire une fonction.
• Remplacer, ne pas déprécier. Pas de suffixes _old, pas de blocs commentés. Supprimer.
• Pas de // TODO dans le code commité. Le finir ou ouvrir une issue.

La troisième mérite une note, parce que c'est celle sur laquelle les gens résistent et celle qui rapporte le plus. Le biais architectural le plus fort d'un modèle est d'abstraire au deuxième cas. Deux choses se ressemblent, il invente le helper partagé, et le helper est faux parce que deux points ne déterminent pas la forme. Attendre le troisième cas coûte un bloc dupliqué et achète une abstraction qui tient.

L'heuristique associée, pour quand vous regardez un module et ne savez pas s'il mérite d'exister : imaginez qu'il est parti. Si la complexité disparaît avec lui, c'était un pass-through à inliner. Si la complexité réapparaît dans chaque appelant, le module gagne sa place. Ne pas confondre une interface profonde avec une grosse implémentation. Un module profond a une petite interface derrière laquelle vit beaucoup de comportement, pas un gros fichier.

Hooks : la partie qui bloque vraiment

Les règles dans un fichier markdown sont consultatives. Le modèle les lit, et les respecte en grande partie. Les hooks sont différents : ils interceptent l'appel d'outil et le refusent. C'est la partie d'une configuration Claude Code que la plupart des gens sautent, et c'est la seule partie qui transforme une préférence en garantie.

Nous en avons huit. Quatre existent uniquement pour rendre les erreurs irréversibles impossibles :

• block-push-main.js refuse un push sur main ou master. La protection de branche côté hébergeur couvre aussi ce cas, mais le hook échoue plus tôt et localement, ce qui signifie que vous l'apprenez avant le round trip.
• block-rm-rf.js refuse la suppression récursive forcée et indique ce qu'utiliser à la place.
• block-env-read.js refuse la lecture de fichiers de credentials.
• block-secret-leak.js refuse les formes de commandes connues pour afficher des secrets.

Deux des huit ont des fichiers de test à côté d'eux. C'est la partie qui vaut la peine d'être copiée. Un hook non testé est un hook que vous n'avez pas : soit il échoue ouvert, auquel cas vous pensiez être protégé et ne l'étiez pas, soit il échoue fermé sur des commandes innocentes, auquel cas vous le désactiverez dans la semaine. Les deux résultats sont pires qu'aucun hook, parce que les deux viennent avec une fausse certitude attachée.

Il y a aussi une limite structurelle qui vaut la peine d'être comprise, parce qu'elle change ce que vous devez écrire comme règle plutôt qu'automatiser. Un hook PreToolUse voit le texte d'une commande, jamais sa future sortie. Il peut refuser printenv. Il ne peut pas savoir que l'objet que vous allez afficher porte une clé API dans un champ, ou qu'un endpoint de configuration cloud va retourner tout l'environnement d'un container. Ces cas ne peuvent pas être hookés, du tout, et c'est exactement là que les vraies fuites arrivent. Ils doivent donc être couverts par des règles écrites qui tiennent que le hook se déclenche ou non : ne jamais afficher un secret même partiellement, ne jamais afficher un client SDK ou un objet de configuration entier pour déboguer, extraire le seul champ dont vous avez besoin.

Un hook se tient de l'autre côté, et ce sont ses limites qui méritent d'être dites clairement. Il s'exécute après l'outil, analyse la sortie à la recherche de chaînes en forme de credential, et quand il en trouve une, il ne peut rien effacer : la sortie est déjà dans le contexte. Ce qu'il peut faire, c'est forcer un rappel impossible à manquer au tour suivant et écrire une ligne d'audit, pour qu'une fuite laisse toujours une trace, qu'elle ait été remarquée ou non. C'est le second des deux hooks livrés avec un test.

Les trois derniers ne sont pas des gardes. L'un charge les notes de la session précédente au démarrage, l'un journalise les invocations d'agents pour les métriques, l'un audite les appels bash. Peu coûteux, et chacun supprime quelque chose que vous feriez autrement à la main à chaque session.

Agents : quand le routage bat le travail direct

Cinq agents spécialisés, découverts automatiquement depuis ~/.claude/agents/, scanné récursivement. Chacun est un fichier markdown avec frontmatter : name, description, tools, model. Nous les classons en sous-dossiers par territoire, ce qui est purement documentaire : l'identité vient du champ name seul, jamais du chemin. La description est ce qui fait le routage, elle porte donc le vocabulaire déclencheur plutôt qu'un intitulé de poste.

• ui pour les composants et les pages
• auth-billing pour l'authentification et les paiements
• backend-api pour les routes, les schémas, la validation, les emails transactionnels
• devops pour les containers, les pipelines, le DNS, les déploiements
• marketing pour le SEO, les métadonnées, les données structurées, l'analytique
• security-observability pour les audits, le rate limiting, les incidents

Quatre tournent sur un modèle intermédiaire. Un, l'agent de sécurité, tourne sur le plus puissant disponible, parce que le raisonnement sur les vulnérabilités est là où la capacité du modèle change réellement la réponse, et parce qu'un audit qui manque quelque chose est pire qu'aucun audit.

La discipline qui fait fonctionner tout cela n'est pas le registre, c'est l'évaluation forcée : avant toute tâche de code, décider explicitement si un agent dédié convient mieux que de travailler directement, et le dire. Laissé implicite, le routage vers les agents n'arrive jamais, et vous avez cinq fichiers qui ne servent à rien.

Là où ça paie le plus, c'est le travail parallèle sur des scopes disjoints. Un agent par scope, tous invoqués dans le même tour. Là où ça coûte, c'est une tâche qui croise les scopes, auquel cas le dire et demander plutôt que laisser deux agents éditer le même fichier.

Skills : des procédures, pas des raccourcis

Un skill est une procédure packagée que le modèle suit plutôt qu'il n'improvise. Les nôtres se divisent en deux familles.

Les skills d'ingénierie sont les trois porteurs :

• grill-me tourne avant toute implémentation non triviale. Il interroge le plan, parcourt chaque branche, et fait remonter les contradictions avec le code existant, jusqu'à ce que vous et le modèle vous accordiez réellement sur ce qui est construit. Presque chaque défaut de conception que nous avons détecté à peu de frais l'a été ici, avant qu'aucun code n'existe.
• diagnose pour un bug complexe ou une régression de performance : reproduire, minimiser, formuler une hypothèse, instrumenter, corriger, ajouter le test de régression. Dans cet ordre, ce qui est toute la valeur, puisque l'ordre tentant est de deviner et de patcher.
• cloture en fin de session : réécrire les fichiers de continuité, mettre à jour la mémoire, commiter délibérément.

Le reste sont des procédures de domaine : audits, rédaction de PRD, revues SEO, guidance spécifique à un framework. Ceux-là ne valent la peine que si vous faites ce type de travail de façon répétée. Écrit pour un cas unique, un skill est plus coûteux que de faire la tâche directement.

La même règle d'évaluation forcée s'applique : lister les skills pertinents, décider oui ou non avec une raison, et si oui l'invoquer avant toute autre chose. Un skill qui n'est pas évalué n'est jamais utilisé.

Continuité : deux fichiers avec des rôles distincts

Chaque projet porte deux fichiers à sa racine, versionnés avec le code. Les séparer compte, parce qu'ils répondent à des questions opposées.

lastdiscussion.md regarde en arrière. Sections fixes, sans invention : état actuel, décisions prises cette session avec une raison courte, ce qui a été fait concrètement, notes techniques couvrant les pièges et les dépendances non évidentes, et une suite immédiate en trois lignes maximum. Il est lu automatiquement au démarrage de session. Il est réécrit en entier, jamais en ajout, et seulement quand vous le demandez. Ajouter produit un journal que personne ne lit au bout de deux semaines.

todo.md regarde en avant. En cours, plafonné à un item pour que le multitâche ne puisse pas se cacher. Un backlog ordonné du haut vers le bas. Fait récemment, plafonné à dix items datés, au-delà desquels ils disparaissent simplement, puisque le détail vit déjà dans le log git.

L'habitude qui les rend valables : traiter le récit comme une affirmation, pas comme une vérité. Les notes d'une session précédente surestiment ou sous-estiment régulièrement l'état des choses, donc la première action d'une nouvelle session est git status, même quand les notes disent que rien n'est en cours. Nous avons démarré des sessions sur une branche périmée en faisant confiance au fichier.

Mémoire : un fait par fichier

Un seul fichier de mémoire croissant s'effondre. Il devient un journal, il est chargé en entier que ce soit pertinent ou non, et rien dedans n'est jamais supprimé parce que supprimer une ligne d'un mur de texte semble arbitraire.

Un fait par fichier résout les trois problèmes. Chaque fichier porte un frontmatter avec un nom, une description d'une ligne utilisée pour juger la pertinence, et un type : qui est l'utilisateur, un retour sur la façon de travailler, un état de projet non dérivable du code, ou un pointeur vers une ressource externe. Le corps contient le fait, et pour les retours et les notes de projet, pourquoi ça compte et comment l'appliquer. Les fichiers se relient entre eux, et pointer vers une mémoire qui n'existe pas encore est parfaitement valable, puisque ça marque quelque chose qui mérite d'être écrit.

Un index d'une ligne est chargé à chaque session, donc la pertinence est jugée depuis les descriptions plutôt qu'en chargeant tout.

Deux règles maintiennent l'honnêteté. Ne pas sauvegarder ce que le dépôt enregistre déjà : la structure du code, les corrections passées, l'historique git, les conventions déjà écrites dans CLAUDE.md. Et traiter un souvenir rappelé comme un arrière-plan, reflétant ce qui était vrai quand il a été écrit, pas comme une instruction actuelle. Si une mémoire nomme un fichier, une fonction ou un flag, vérifier qu'il existe encore avant d'agir dessus. La nôtre s'est trompée sur un tarif qui avait changé et sur l'emplacement d'un fichier qui avait bougé.

Ce que nous ne faisons délibérément pas

• Pas de settings.json modifié par un agent. Les hooks et les permissions sont changés par un humain, intentionnellement.
• Pas de .gitignore modifié par un agent, pour la même raison.
• Pas de fichiers de credentials créés ou modifiés par un agent, jamais.
• Pas d'instructions génériques "sois utile". Chaque ligne dans un fichier de règles contraint une décision ou c'est du bruit qui dilue les lignes qui le font.
• Pas de métriques que nous ne lisons pas. Nous journalisons les invocations d'agents parce que nous les regardons. Nous ne journalisons rien d'autre.

Par où commencer, si vous partez de zéro

Pas par les agents, et pas par les skills. Dans cet ordre :

1. Le CLAUDE.md global, avec les six limites strictes et vos règles de sécurité. Une demi-page. Ça seul change la sortie.
2. Les quatre hooks bloquants, avec un test pour chacun. C'est là que vient la garantie.
3. Les deux fichiers de continuité, et l'habitude de lancer git status avant de leur faire confiance.
4. CONTEXT.md, la première fois qu'un terme de domaine se stabilise. Pas avant.
5. Les agents, une fois que vous remarquez que vous répétez le même type de tâche dans le même périmètre.
6. Les skills, une fois qu'une procédure a été improvisée trois fois.

Les étapes un et deux représentent la plupart de la valeur, et elles prennent une après-midi. Tout ce qui suit est un raffinement d'un système qui fonctionne déjà.