CLAUDE.md : 7 templates prêts à coller et comment écrire vos interdits

« Le CLAUDE.md, je note ma stack technique et c’est bon, non ? »

Moi aussi, au début, je le croyais. Astro, TypeScript et Tailwind : voilà, c’est écrit. Satisfait, j’ai confié une tâche à Claude Code et là, il a répété la même bêtise trois fois de suite. Il sautait les tests à chaque passage. Il s’approchait d’un fichier de config qu’il ne fallait surtout pas effacer. Il m’annonçait « C’est corrigé ! » alors que le build ne passait pas.

Un CLAUDE.md qui se contente de lister la stack, c’est comme dire à une nouvelle recrue « ici, on est une boîte Java » et la lâcher sur le terrain. Elle sait ce que vous utilisez, mais elle n’a aucune idée de comment elle doit travailler.

Dans cet article, je vous laisse 7 templates CLAUDE.md que j’utilise tels quels sur de vrais projets, dans un format que vous pouvez copier-coller. Pas des descriptions de stack : des fichiers entièrement tournés vers « l’ordre des étapes » et « ce qu’il ne faut surtout pas faire ».

Points clés

• Ce qui marche vraiment dans un CLAUDE.md, ce n’est pas la stack technique, ce sont deux choses : les règles de travail (Working Rules) et les interdits (Do Not).
• J’ai préparé 7 templates par usage : appli solo, site de contenu, API, équipe, legacy, automatisation, monorepo. Choisissez celui qui ressemble le plus à votre dépôt et collez-le, point.
• Quel que soit le template, vous devez ensuite ajouter 3 lignes de Do Not pour votre cas précis. C’est ce qui stoppe les accidents.
• « Plus c’est long, mieux c’est » est un mythe. Le CLAUDE.md n’est pas un manuel, c’est un fichier d’exploitation. Les règles d’action courtes gagnent.
• Quand Claude Code répète la même erreur trois fois, ne soupçonnez pas l’IA : soupçonnez la finesse de votre CLAUDE.md.

J’ai conçu cette page comme un « catalogue de pièces réelles » qui comble l’espace entre le guide complet pour débuter avec Claude Code et le guide complet pour écrire un CLAUDE.md. La théorie, lisez-la là-bas ; ici, repartez avec les objets concrets en main.

Ce qu’un bon CLAUDE.md fait, discrètement

Un CLAUDE.md solide n’écrit rien de génial. Il se contente de neutraliser, sans bruit, ces trois « accidents du quotidien » :

• l’endroit à modifier est le bon, mais Claude Code casse une convention propre au projet ;
• la correction est faite, mais il saute les tests ou la vérification à lancer ;
• son périmètre n’est pas clair, alors son exploration s’étale et fait fondre le temps.

Pour éviter ces trois pièges, voici les rubriques minimales à prévoir.

Rubrique	Rôle	Impact
Stack technique et commandes clés	Aligner les prérequis	Moyen
Rôle des dossiers	Resserrer le périmètre d’exploration	Moyen
Règles propres au projet	Faire respecter les conventions	Fort
Ordre de travail (les étapes)	Éviter les oublis de vérification	Fort
Interdits (Do Not)	Stopper les accidents	Très fort

Les deux premières lignes sont des bonus ; ce qui compte vraiment, ce sont les trois dernières. Surtout, dès que vous écrivez l’ordre de travail et les interdits, Claude Code se calme comme s’il avait changé de personne. « Comment avancer » et « ce qu’il ne faut pas faire » : au fond, c’est exactement le manuel qu’on donne à une nouvelle recrue humaine.

À partir d’ici, ce sont les pièces réelles. Collez le contenu des blocs de code directement dans votre CLAUDE.md.

1. Appli web en développement solo

Si vous faites tourner un petit service tout seul, commencez par celui-ci.

# Project Overview

Customer-facing Astro site with a small Node API.

## Tech Stack

- Frontend: Astro 5 + TypeScript
- Styling: Tailwind CSS
- Backend: Node.js 22
- Tests: Vitest

## Key Directories

- `site/src/pages/` route entrypoints
- `site/src/components/` reusable UI
- `site/src/content/` blog and docs content
- `scripts/` operational scripts

## Common Commands

- Build: `cd site && npm run build`
- Test: `npm run test`
- Search content: `rg "keyword" site/src/content`

## Working Rules

- Prefer minimal diffs over wide refactors
- Keep copy changes aligned with existing brand tone
- When editing UI, verify mobile width before calling the task done

## Do Not

- Do not rename routes unless required
- Do not delete analytics or SEO fields
- Do not claim deploy success without checking the public URL

Ici, ce qui pèse le plus n’est pas la description de la stack, mais les dernières lignes de Working Rules et de Do Not. « Ne dis pas que c’est terminé avant d’avoir vérifié le rendu en largeur mobile », « Ne dis pas que le déploiement a réussi avant d’avoir regardé l’URL publique ». Avant d’ajouter ces deux lignes, j’ai plusieurs fois sorti une UI nickel sur mon écran d’ordinateur qui débordait de partout sur le téléphone. Quand on enferme la condition de réussite dans une phrase, ce genre d’accident disparaît.

2. Site de contenu avec articles, PDF et tunnel produit

Ce blog en est l’exemple : un site avec un tunnel de revenus est bien trop fragile avec un template de dev générique.

# Project Overview

Multilingual Claude Code content site with free PDF lead magnet, Gumroad products, and consultation funnel.

## Business Goal

- Priority 1: free PDF registration
- Priority 2: Gumroad product clicks and purchases
- Priority 3: consultation inquiries

## Content Rules

- Every new article must include internal links
- Every article must include free PDF, product, and consultation CTA paths
- Use the same slug across all locales when publishing multilingual posts

## Verification Workflow

1. Build the site
2. Deploy the site
3. Open the public URL
4. Check mobile layout
5. Confirm CTA destination links

## Do Not

- Do not publish only one locale when the article requires all locales
- Do not treat build success as release success
- Do not prioritize pageviews over conversion path quality

Le point clé, c’est la dernière ligne de Do Not : « Privilégie la qualité du tunnel de conversion plutôt que les pages vues ». Sans cette ligne, Claude Code dérive vers « l’article qui a l’air de bien marcher » et produit en série des pages dont le CTA, justement, est anémique. Il suffit de hiérarchiser l’objectif business et de le placer tout en haut pour que la direction des sorties change du tout au tout.

3. API backend

Pour une API où l’intégrité est vitale, on force le « lire avant de corriger » et le « mettre des mots dessus une fois corrigé ».

# Project Overview

Internal TypeScript API for billing and account management.

## Tech Stack

- Node.js 22
- Fastify
- PostgreSQL + Prisma
- Zod
- Vitest

## Directory Map

- `src/routes/` HTTP handlers
- `src/services/` business logic
- `src/repositories/` DB access
- `src/lib/` shared utilities

## Required Workflow

1. Read the route or service first
2. Check for existing schema and tests
3. Make the smallest safe change
4. Run unit tests or type checks
5. Summarize risk in plain English

## Do Not

- Do not bypass Zod validation
- Do not edit migrations casually
- Do not touch billing logic without tests

Là-dedans, ce que je préfère, c’est la ligne Summarize risk in plain English. Mot à mot : « résume le risque en langage clair ». Avec cette ligne, Claude Code ne s’arrête plus à « c’est corrigé » : il met de lui-même des mots sur l’étendue de l’impact, du genre « ce changement est proche de la frontière de la logique de facturation, il pourrait toucher le batch mensuel ». Le premier coup d’œil de la revue devient nettement plus facile.

4. Développement en équipe

En équipe, ce qui pose vraiment problème, ce n’est pas le manque de productivité, ce sont les diffs difficiles à relire. On prend les devants.

# Team Workflow

- Work on the current branch only
- Do not revert changes you did not make
- Call out uncertainty before making broad edits
- Prefer review-friendly patches over large rewrites

## Pull Request Expectations

- Mention user-facing behavior changes
- Mention test coverage gaps
- Flag security, permissions, and deploy risks first

## Approval Boundaries

- Ask before deploy commands
- Ask before editing CI, infra, or secrets-related files
- Ask before changing lockfiles unless required

Do not revert changes you did not make (ne reviens pas tout seul sur des changements que tu n’as pas faits) : ça paraît anodin, mais c’est efficace. L’IA cherche parfois à « faire le ménage » au passage dans le code voisin et annule, ce faisant, des choix volontaires d’autres personnes. Pour la délimitation des frontières d’approbation, j’ai détaillé ça dans le guide des réglages Approval / Sandbox : si vous travaillez en équipe, jetez-y un œil.

5. Code legacy

Quand on modifie du vieux code, ce n’est pas la « propreté » qui fait foi, c’est le « ne rien casser ».

# Legacy Repo Notes

- This codebase has inconsistent patterns
- Prefer compatibility over elegance
- Preserve behavior unless the task explicitly allows change

## Investigation First

1. Explain current behavior
2. Locate the smallest responsible file set
3. Identify risks before editing

## Do Not

- Do not rename public methods casually
- Do not introduce new frameworks
- Do not rewrite files only to match modern style

Prefer compatibility over elegance (privilégie la compatibilité à l’élégance). Sur les projets legacy, c’est souvent ce qui compte le plus. Laissé à lui-même, Claude Code vous proposera, plein de bonnes intentions, « je te réécris ça dans un style plus moderne » — sauf qu’en legacy, c’est la porte d’entrée des accidents. On met Do not rewrite files only to match modern style dans les interdits pour mettre un couvercle sur cette bonne volonté.

6. Scripts d’automatisation et d’exploitation

Envoi d’e-mails, déploiement, écriture vers une API externe : si vous laissez l’IA toucher des scripts à effets de bord, c’est par celui-ci qu’il faut commencer.

# Automation Rules

- Dry-run whenever the script supports it
- Log intended side effects before executing
- Prefer idempotent operations
- Keep secrets out of logs and generated files

## Required Checks

- Confirm environment variables used
- Confirm target environment
- Confirm output path or destination service

## Do Not

- Do not send emails, deploy, or publish without explicit approval
- Do not delete generated assets unless cleanup is requested

Log intended side effects before executing (avant d’exécuter, écris noir sur blanc ce que tu t’apprêtes à provoquer) est la soupape de sécurité. En lui faisant déclarer d’abord « je vais envoyer 120 e-mails en production », un humain peut crier « stop » à temps. Couplé à Dry-run whenever the script supports it, on insère systématiquement un temps d’arrêt avant toute opération irréversible.

7. Monorepo

Si plusieurs applis et des packages partagés cohabitent, écrivez d’abord « quel package porte la responsabilité ».

# Monorepo Map

- `apps/web/` customer app
- `apps/admin/` internal admin tool
- `packages/ui/` shared UI
- `packages/config/` lint and tsconfig presets

## Ownership Rules

- Web UI work should stay inside `apps/web/` unless the task clearly needs a shared component change
- Shared package edits require checking downstream usage
- Avoid version or config churn unless necessary

## Verification

- Run the narrowest relevant build or test command first
- Describe cross-package impact before editing shared code

Rien que d’écrire les Ownership Rules réduit nettement les accidents d’édition transversale. Une petite correction censée rester dans apps/web/ finit, sans qu’on s’en rende compte, par toucher un composant partagé de packages/ui/, ce qui embarque jusqu’à apps/admin/ et casse tout : voilà l’accident type du monorepo. On fait déclarer le périmètre dès le départ et on glisse une phrase : « explique l’impact en aval avant de toucher au code partagé ».

Quel template choisir

Avec 7 modèles, on hésite ; voici donc le mode d’emploi, une ligne par cas.

• UI ou produit au centre → template solo
• articles, PDF, tunnel Gumroad → template site de contenu
• intégrité vitale → template API
• coût de coordination élevé → template équipe ou monorepo
• coût d’un accident élevé → template legacy ou automatisation

Pas besoin de mélanger les 7. Au contraire, en les mélangeant, le fichier s’allonge et perd en efficacité. Prenez un seul template comme base et n’ajoutez que les règles qui changent réellement le comportement sur votre terrain. C’est la bonne approche.

4 erreurs classiques avec un CLAUDE.md

Je vous partage telles quelles les mines sur lesquelles j’ai vraiment marché.

Erreur 1. Écrire long comme un wiki d’entreprise. « Plus l’explication est longue, mieux c’est » était une erreur totale. Le CLAUDE.md n’est pas un manuel, c’est un fichier d’exploitation. Une règle d’action courte vaut bien des longs paragraphes de contexte. On oublie trop vite que ce n’est pas un humain qui lit, mais une IA.

Erreur 2. Écrire les commandes sans écrire les étapes. Plutôt que de noter juste npm run test, si tu touches à billing, lance toujours les tests est infiniment plus fort. La commande ne dit que « ça existe ». L’étape dit aussi « quand l’utiliser ».

Erreur 3. Pas d’interdits. C’est le plus grand gâchis. Ne touche pas à .env, Ne dis pas que le déploiement a réussi sans avoir vérifié l'URL publique, Ne fais pas de force push. Une seule phrase évite l’accident d’une nuit entière. La section Do Not n’est pas un ornement, c’est une assurance.

Erreur 4. Ne pas mettre à jour. Quand Claude Code répète la même erreur trois fois, ce n’est généralement pas la faute de l’IA : c’est la finesse du CLAUDE.md qui manque. À ce moment-là, au lieu de gronder, ajoutez une ligne de règle. Le CLAUDE.md ne s’écrit pas une fois pour toutes : c’est un fichier qu’on fait grandir.

FAQ

Q. Où faut-il placer le CLAUDE.md dans le projet ? R. Placez-le à la racine du dépôt sous le nom CLAUDE.md et Claude Code le chargera automatiquement. En monorepo, vous pouvez aussi en mettre un à la racine de chaque package : le plus proche est prioritaire. Pour le mettre en place et vérifier qu’il agit, ces deux commandes suffisent.

# Placez-le simplement à la racine du projet. Claude Code le charge au démarrage.
cat > CLAUDE.md <<'EOF'
# Project
(collez le template ci-dessus tel quel)
EOF

# Vérifiez qu'il agit : demandez-lui de vous redire les règles.
claude -p "Cite-moi 3 interdits (Do Not) du CLAUDE.md de ce projet"

Pour les règles d’emplacement détaillées, consultez la documentation officielle de Claude Code.

Q. Est-ce que ça marche bien si j’écris en français ? R. Oui. Il m’arrive d’écrire les interdits et les étapes en français. Cela dit, garder le template lui-même en anglais facilite l’alignement avec des coéquipiers étrangers ou des exemples publics : c’est pourquoi, dans cet article, la base est en anglais. Tant que le sens passe, l’une ou l’autre langue convient.

Q. Un CLAUDE.md long ou court, lequel est préférable ? R. Le court. Visez de quoi tenir sur un écran. Dès qu’il s’allonge, c’est le signal qu’il faut en extraire une partie dans un autre document. Dans le CLAUDE.md, ne gardez que « les règles qui changent le comportement ».

Q. Une fois le template collé, qu’est-ce que j’ajoute en premier ? R. 3 lignes de Do Not pour votre cas précis. « Le fichier qu’on ne veut pas voir touché », « l’opération qu’on ne veut pas voir lancée », « le mensonge qu’on ne veut pas entendre (par ex. : un rapport de réussite alors que rien n’est vérifié) », une ligne chacun. C’est l’ajout au plus fort retour sur investissement.

Q. Quelle différence entre CLAUDE.md et les permissions ? R. Le CLAUDE.md, c’est « une demande, une orientation » ; les permissions, c’est « une liste d’autorisations qui a force contraignante ». Si vous voulez vraiment faire respecter les interdits, combinez les deux. La façon de découper les droits est aussi abordée dans le guide complet pour débuter avec Claude Code.

Ce que ça a donné en vrai

À l’époque où mon CLAUDE.md ne contenait que la stack technique, je guettais chaque sortie de Claude Code avec angoisse. « Est-ce qu’il va lancer les tests correctement cette fois-ci ? »

Depuis que j’ai ajouté Working Rules et Do Not, cette angoisse a quasiment disparu. La ligne « ne dis pas que le déploiement a réussi avant d’avoir regardé l’URL publique » a un effet qui se voit clairement dans les chiffres. Avant, il m’arrivait plusieurs fois par mois d’avoir un « c’est déployé » suivi d’un vrai 404 ; depuis cet ajout, c’est tombé à zéro.

La conclusion est simple. Le CLAUDE.md n’est pas un fichier pour rendre l’IA plus intelligente, c’est un fichier pour l’empêcher de provoquer des accidents. Ajouter 3 lignes d’interdits agit, à la louche, dix fois plus que rallonger la stack. Commencez par coller le template le plus proche de votre dépôt, puis ajoutez juste 3 lignes de Do Not.

Si vous voulez creuser la philosophie de conception du CLAUDE.md elle-même, lisez le guide complet pour écrire un CLAUDE.md ; pour la vue d’ensemble sur le « harnais » qui permet de confier des tâches à l’IA sans danger, allez voir Dire « débrouille-toi » à une IA, c’est l’accident assuré. Si vous voulez garder sous la main des recueils de templates et d’exemples de réglages, le Claude Code Quick Reference Cheatsheet gratuit et le Complete Claude Code Setup & Configuration Guide, qui pousse jusqu’aux hooks et aux permissions, vous seront utiles. Pour parcourir l’ensemble des supports, passez par le catalogue des supports ; pour caler ensemble jusqu’à la standardisation en équipe, direction la page de consultation.