La plupart des conseils CLAUDE.md sont écrits pour les développeurs solo travaillant sur un projet à la fois. Le travail en agence est différent : vous avez un portefeuille de projets clients, chacun avec ses propres conventions, et le même ingénieur peut toucher à six d'entre eux en une semaine. La stratégie CLAUDE.md qui fonctionne pour un dev solo échoue à l'échelle d'une agence. C'est l'approche opérationnelle que nous avons établie chez Seahawk Media après 18 mois d'itération sur 200+ dépôts clients actifs.
Point clé : CLAUDE.md à l'échelle d'une agence nécessite trois couches, des standards au niveau agence, des remplacements client et des notes par engagement, afin qu'un ingénieur puisse naviguer entre six dépôts avec le bon contexte.CLAUDE.md at agency scale needs three layers, agency-wide standards, client overrides, and per-engagement notes, so one engineer can move across six repos with the right context.
Si vous gérez une agence qui utilise Claude Code quotidiennement et constatez que les ingénieurs obtiennent des résultats très différents selon les projets, cet article est la solution structurelle.
Pourquoi les conseils CLAUDE.md solo échouent à l'échelle d'une agence
Le conseil standard CLAUDE.md est : écrivez-le une fois, optimisez-le pour votre projet, gardez-le sous 500 lignes. Ça fonctionne quand vous avez un seul projet. Quand vous avez 50 dépôts clients, trois problèmes surgissent. Le même ingénieur ne peut pas se souvenir des conventions qui s'appliquent à quel client. Les nouveaux ingénieurs qui arrivent sur un projet font face à cinquante fichiers CLAUDE.md différents. Le contenu CLAUDE.md dérive au fur et à mesure que les ingénieurs mettent à jour un projet et oublient les autres.
Résoudre cela à l'échelle d'une agence nécessite une approche en couches : standards agence-wide en un seul endroit, overrides spécifiques au client ailleurs, et contexte par mission dans un troisième. Les couches s'empilent plutôt que de se dupliquer.
Le modèle CLAUDE.md à trois niveaux
Niveau 1 : standards à l'échelle de l'agence
Un seul modèle CLAUDE.md réside dans un dépôt GitHub privé de notre agence. Il couvre : le style de code dans les langages que nous déployons, nos patterns interdits, nos conventions de test, nos standards de sécurité, notre règle d'orthographe britannique éditoriale, nos defaults de déploiement. Ce fichier fait environ 400 lignes et change quelques fois par an.
Chaque nouveau projet client commence en créant un lien symbolique ou en copiant ce fichier. Les changements au fichier à l'échelle de l'agence sont intégrés dans les projets selon un rythme trimestriel. Les ingénieurs peuvent se fier au fait que ces conventions sont identiques peu importe le projet qu'ils ouvrent.
Niveau 2 : CLAUDE.md spécifique au client
Chaque dépôt client a son propre CLAUDE.md qui importe celui à l'échelle de l'agence et ajoute les spécificités du client : leur stack, leur hosting, leurs plugins, leurs conventions d'équipe, leur voix éditoriale, leurs plugins interdits. Ce fichier fait généralement entre 100 et 200 lignes et change quand l'engagement client change de forme.
Nous utilisons une simple directive d'inclusion au début : « ## Standards de l'agence » avec un lien vers le fichier à l'échelle de l'agence, puis « ## Spécificités du client » avec les surcharges. Claude lit les deux parce qu'ils sont tous les deux dans l'arborescence du projet.
Niveau 3 : notes par engagement
Contexte spécifique et limité dans le temps : l'objectif du sprint actuel, les découvertes actives, le journal des décisions récentes, la liste des questions ouvertes. Réside dans CLAUDE_NOTES.md ou similaire, mis à jour hebdomadairement pendant l'engagement, archivé à la clôture de l'engagement.
C'est là que la plupart des agences échouent en matière d'hygiène CLAUDE.md. Les deux premiers niveaux restent bien ordonnés ; le troisième dérive et devient obsolète. Nous résolvons cela avec un rythme d'examen vendredi après-midi : chaque ingénieur révise son CLAUDE_NOTES.md actif et le met à jour ou l'archive.
La liste des motifs interdits qui s'accumulent
L'élément de plus grand impact dans notre CLAUDE.md à l'échelle de l'agence est la liste des motifs interdits. Vingt entrées, actualisées trimestriellement. Exemples de la liste actuelle :
Ne jamais utiliser eval() dans aucun langage que nous déployons.
Ne jamais utiliser query_posts() dans WordPress (utiliser WP_Query à la place).WordPress (use WP_Query instead).
Ne jamais utiliser any en TypeScript sans un commentaire explicite "// suppressed: <reason>".
Ne jamais utiliser document.write() dans aucun contexte.
Ne jamais valider des secrets dans git, jamais, peu importe la branche.
Ne jamais utiliser de tirets longs dans aucune copie client (standard opérationnel pour éviter la détection par IA).
Ne jamais désactiver RLS sur les tables Supabase pour corriger un bogue.Supabase tables to fix a bug.
Ne jamais pousser directement vers main (toujours par PR).
Ne créez jamais un nouveau fichier quand un fichier existant peut être modifié.
La liste s'accumule parce que chaque fois qu'un ingénieur enfreint l'une de ces règles, nous ajoutons la règle. Claude lit la liste de motifs interdits à chaque session et refuse de générer du code qui les viole. La classe de bugs que nous avions l'habitude de déployer en staging a disparu.
Ce qu'il faut exclure de CLAUDE.md
Cinq choses que nous ne mettons explicitement pas dans les fichiers CLAUDE.md d'agence :
Les mises à jour du statut du projet. Elles deviennent obsolètes ; elles appartiennent à Linear ou Notion.
Les long rationnels architecturaux. Ils appartiennent aux documents de conception ; CLAUDE.md devrait les référencer, pas les dupliquer.
Les secrets côté client, identifiants ou quoi que ce soit de sensible. Même les fichiers CLAUDE.md privés sont trop exposés au risque de fuite.
Les préférences personnelles d'ingénieurs individuels. Les standards doivent être à l'échelle de l'agence ; les préférences spécifiques à un ingénieur appartiennent à leur propre fichier .claude/settings.json.
Le texte marketing ou le langage commercial. CLAUDE.md est du contexte technique ; il devrait lire comme s'il était écrit par un ingénieur senior pour d'autres ingénieurs.
Comment CLAUDE.md change l'équation du recrutement
Un ingénieur senior capable de livrer du code dans l'ensemble de notre portefeuille clients sans réapprendre chaque projet à chaque visite est dramatiquement plus précieux qu'un qui ne peut pas. Le système CLAUDE.md à trois couches est ce qui rend cela possible. Le temps d'intégration pour les nouveaux ingénieurs a chuté d'environ 2 semaines de montée en charge spécifique au projet à 3 jours parce que les conventions sont codifiées plutôt que tribales.
Le même ingénieur, plus de résultats, moins de coût d'intégration, moins de surcharge de changement de contexte. La boucle de recrutement a expédié moins d'ingénieurs juniors et plus d'ingénieurs seniors une fois que nous avions ce système en place, parce que les ingénieurs juniors n'étaient plus nécessaires pour absorber le contexte spécifique au projet qui était auparavant la seule façon dont les conventions se transmettaient.
Conclusion
CLAUDE.md à l'échelle d'une agence est un système en couches : les normes à l'échelle de l'agence comme base, les remplacements spécifiques au client comme couche intermédiaire, les notes par engagement comme couche supérieure. La liste des motifs interdits est la section à plus fort effet de levier. Évitez le contenu obsolète dans la couche par engagement avec un cadence d'examen du vendredi.
Implémentez le modèle à trois couches et vos ingénieurs cesseront de livrer des résultats incohérents dans votre portefeuille. Ignorez-le et vous payez pour une assistance IA qui produit un travail différent selon le projet que l'ingénieur a ouvert en dernier.
Questions fréquemment posées
Qu'est-ce qu'un fichier CLAUDE.md ?
CLAUDE.md est un fichier projet qui indique à Claude Code vos standards, votre stack et vos conventions afin que sa sortie s'adapte à votre codebase. À l'échelle d'une agence, un seul fichier plat par projet ne suffit pas, c'est pourquoi cela utilise un modèle à trois niveaux sur plusieurs repos clients.
Comment mettre à l'échelle CLAUDE.md sur de nombreux projets clients ?
Avec un modèle à trois niveaux : des standards au niveau de l'agence qui s'appliquent partout, des surcharges spécifiques au client par compte, et des notes par engagement pour un projet donné. Le même ingénieur peut basculer entre six repos clients en une semaine et avoir le bon contexte dans chacun sans le réécrire.
Que ne doit pas aller dans CLAUDE.md ?
Les secrets, tout ce qui change constamment, et le bruit qui dilue les règles importantes. Limitez-vous aux standards et conventions durables. Un CLAUDE.md surcharisé est ignoré ; un CLAUDE.md compact et stratifié qui énonce clairement les motifs interdits est ce qui change réellement la sortie.
CLAUDE.md change-t-il la façon dont vous embauchez ?
Cela réduit le coût d'intégration. Quand les standards vivent dans un CLAUDE.md stratifié, un nouvel ingénieur hérite des conventions de l'agence par l'outil plutôt que par des mois de connaissance tribale. Cela oriente le recrutement vers le jugement et l'éloigne de la mémorisation du style maison.