CLAUDE.md : 7 bonnes pratiques pour rendre ton repo agent‑native

Accroche — en une phrase : si tu veux que des agents IA puissent travailler sur ton code sans casser la base, écris un CLAUDE.md clair. Voici un template réutilisable, 7 règles concrètes et une checklist pour déployer en 10 minutes.

Pourquoi ce guide ? Les fichiers CLAUDE.md se multiplient sur GitHub : ils servent de “contrat” entre ton repo et les agents (Claude Code, subagents MCP, etc.). Pourtant, la plupart sont soit trop verbeux, soit incomplets. Cet article te donne un format minimal et des pratiques testées sur des projets open-source (ClaudeForge, claude-code-mastery, awesome-claude-md, etc.).

H2: Qu’est‑ce que CLAUDE.md et pourquoi ça change tout

CLAUDE.md est un fichier de configuration / onboarding pour les agents IA (Claude Code et outils compatibles). Il contient : le contexte du projet, les règles de style, les commandes utiles, les zones à ne pas toucher et des outils d’exécution (MCP servers, scripts). Bien écrit, il réduit les erreurs de modification, diminue les boucles de QA et autorise des tâches plus risquées (refactor, tests) en donnant au modèle un cadre sûr.

Ce que CLAUDE.md apporte, en pratique :

• contexte immédiat pour l’agent (structure, routes critiques, points de douleur)
• règles de permission explicites (outils autorisés/deny)
• commandes reproductibles pour lancer l’agent en local (mcp, test, build)

H2: Quand et pour qui rédiger un CLAUDE.md

Rédige un CLAUDE.md quand :

• ton repo contient du code productif ou des scripts infra (backend, infra-as-code)
• des contributions automatiques doivent être sûres (merge automatisé, CI modifié par agent)
• tu veux que des agents fassent des tâches récurrentes (changelog, refactor, tests)

Public cible : devs, mainteneurs, lead devs et CTOs qui acceptent des contributions d’agents et veulent éviter les régressions.

H2: Template minimal — copie/colle et adapte

Utilise ce template minimal dans la racine de ton repo (fichier CLAUDE.md) :

# CLAUDE.md - template minimal

## 1. Thèse (1 ligne)
Ex : "Ce repo est une API Next.js + Postgres ; agents autorisés à : corriger bugs, ajouter tests unitaires, refactor non-breaking."

## 2. Contexte court (3-6 lignes)
- Stack : Next.js 14 (app router), Prisma, Postgres, GitHub Actions
- Entrées critiques : scripts/migrations, packages/core, infra/terraform

## 3. Règles d'édition (permissions)
- Allow: Bash(git diff:*), Read, Glob, WebFetch
- Deny: Bash(rm:*), Write(/prod/config/*), WebFetch(external-auth:*)

## 4. Commandes utiles (préparées)
- dev: `pnpm dev`
- test: `pnpm test --ci`
- build: `pnpm build`
- run migrations: `pnpm prisma migrate dev`

## 5. Tests & critères d'acceptation
- Les nouveaux PRs doivent réussir `pnpm test` et `pnpm lint` pour merger
- Aucun changement direct au dossier infra/ sans revue humaine

## 6. Sources et docs (liens)
- README.md
- docs/architecture.md
- .github/workflows/ci.yml

## 7. Contact humain
- Mainteneur principal: @nom

## 8. Danger zones (ne pas modifier sans approbation)
- /migrations
- /scripts/deploy-prod.sh

Ce template est volontairement court : les agents lisent mieux un fichier scannable que dix paragraphes.

H2: Les 7 bonnes pratiques (avec exemples)

1. Être explicite sur les permissions (ne pas compter sur le silence)

• Pourquoi : les agents exécutent des outils. Autorise/deny explicitement Bash, WebFetch, Write.
• Exemple : deny: Bash(rm:*) évite les suppressions accidentelles.

2. Indiquer les commandes reproductibles (dev/test/build)

• Pourquoi : quand l’agent doit vérifier une modification, il doit pouvoir lancer les tests localement.
• Astuce : fournis des scripts npm (ex : scripts/check-ci) qui encapsulent lint + test.

3. Lister les “danger zones” et donner une procédure pour les toucher

• Pourquoi : certains dossiers demandent une revue humaine (migrations, infra).
• Procédure : “Pour modifier infra/, créer une PR, tagguer infra-team, attendre approbation humaine”.

4. Fournir des exemples de PR attendus (templates)

• Pourquoi : les agents peuvent créer des PR, mieux vaut un template avec checklist. Ajoute un exemple minimal dans CLAUDE.md.

5. Versionner la configuration agent-friendly

• Pourquoi : si CLAUDE.md évolue, l’agent doit savoir l’historique. Garder un changelog court dans .claude/changelog.md aide à la traçabilité.

6. Mesurer et documenter les tests critiques

• Pourquoi : donne confiance pour des merges automatiques.
• Ex : “Coverage backend must not drop below 80%” ou “run smoke test endpoint /health”.

7. Fournir un point de contact humain et fallback

• Pourquoi : quand l’agent bute, on veut une escalade claire (Slack, issue triage).
• Ex : If in doubt: open issue with label agent-fail.

H2: Exemples publics (sources primaires)

J’ai vérifié plusieurs projets open-source qui documentent CLAUDE.md et workflows agent-friendly :

• https://github.com/josix/awesome-claude-md (collection d’exemples et patterns)
• https://github.com/alirezarezvani/ClaudeForge (outil de génération/maintenance CLAUDE.md)
• https://github.com/TheDecipherist/claude-code-mastery (guide complet: CLAUDE.md, MCP servers, commandes)
• https://github.com/centminmod/my-claude-code-setup (starter template CLAUDE.md)
• https://github.com/Piebald-AI/claude-code-system-prompts (exemples de prompts et hooks)

Ces repos montrent des patterns récurrents : sections courtes, liste d’outils autorisés, commandes reproductibles et templates de PR. Ils sont notre base pour le template ci‑dessus.

H2: Checklist rapide (featured-snippet friendly)

• Fichier CLAUDE.md à la racine
• Contient : thèse, contexte court, permissions, commandes, danger zones
• Scripts dev/test/build présents et fonctionnels
• Exemple de PR + checklist dans le repo
• Contact humain et procédure d’escalade
• assetsPending: true ajouté au frontmatter de l’article (si tu publies un guide)

H2: Limites et risques — ce que CLAUDE.md ne remplace pas

• CLAUDE.md ne remplace pas la revue humaine pour changements critiques (infra, finance).
• Mal configuré, il peut donner trop de liberté à un agent : privilégie le principe du moindre privilège.
• Ne confonds pas CLAUDE.md avec des politiques RBAC : garde les règles simples et auditées.

H2: Et maintenant ? (ce que tu peux faire en 10 minutes)

1. Crée CLAUDE.md en copiant le template ci‑dessus
2. Ajoute 3 scripts dev/test/build qui lancent les checks
3. Ouvre une PR avec le fichier et un exemple de PR template
4. Tagge un mainteneur humain dans la PR pour la valider

FAQ (2-3 questions rapides)

Q: CLAUDE.md doit-il être long ? R: Non. Préfère la clarté. Les agents lisent mieux un format structuré et court.

Q: Peut-on autoriser l’agent à pousser directement en main ? R: Non, sauf cas très contrôlés. Préfère des merges automatisés via CI après checks verts.

Q: Où stocker les secrets pour l’agent ? R: Jamais dans le repo. Utilise le gestionnaire de secrets (Vault, GitHub Secrets) et documente leur usage dans CLAUDE.md.

Sources & lecture complémentaire

Voir les repos cités dans les exemples pour des templates étendus et des outils qui génèrent/maintiennent CLAUDE.md automatiquement.

Ce qu’il faut retenir

Un bon CLAUDE.md, c’est : permissions claires, commandes reproductibles, danger zones identifiées, et une procédure humaine d’escalade. Si tu adoptes ces règles, tes agents pourront devenir de vrais coéquipiers sans risquer la prod.

---