📄 GUIDE CLAUDE CODE
CLAUDE.md pour Claude Code : guide complet 2026
Mise à jour 30 avril 2026 · 9 min de lecture
Le fichier CLAUDE.md est devenu la convention dominante en 2026 pour configurer Claude Code (l'agent IA d'Anthropic) sur un projet Git. Posé à la racine d'un repo, il informe Claude Code des spécificités du projet, des règles de codage, des décisions techniques, et des préférences de l'équipe.
Ce guide vous donne la structure officielle, des exemples complets, et les bonnes pratiques d'intégration dans un workflow de développement.
1. Qu'est-ce que CLAUDE.md ?
CLAUDE.md est un fichier Markdown placé à la racine d'un projet qui décrit ce que Claude Code doit savoir avant de travailler dessus. Il est lu automatiquement par Claude Code à chaque session, et reste persistant tant que le fichier existe.
Concrètement, c'est l'équivalent d'un README.md mais destiné à l'IA. Il documente :
- Le contexte du projet (objectif, stack, structure)
- Les conventions de code (linting, formatage, tests)
- Les décisions techniques tranchées
- Les contraintes (sécurité, performance, dépendances)
- Les commandes utiles pour build, test, déployer
2. Différences avec MEMORY.md
| Critère | CLAUDE.md | MEMORY.md |
|---|---|---|
| Localisation | Racine d'un projet Git | Hors projet (collé en début de conversation ou Custom Instructions) |
| Cible | Spécificités du projet | Profil utilisateur global |
| Lecture par Claude Code | Automatique à chaque session | Manuelle (collage) |
| Versionnement | Git du projet (souvent commit) | Git privé personnel |
| Partage | Toute l'équipe du projet | Personnel |
| Structure | Project Context, Tech Stack, Conventions, Commands | Profil, Préférences, Décisions, Leçons, Stack |
| Longueur typique | 500-2000 mots | 300-1500 mots |
En pratique, vous pouvez combiner les deux : un CLAUDE.md à la racine du projet (partagé équipe) + votre MEMORY.md personnel collé en Custom Instructions Claude.
3. Structure recommandée d'un CLAUDE.md
Sections généralement présentes
- Project Context — vue d'ensemble du projet (objectif, contexte business, état)
- Tech Stack — technologies principales avec versions
- Project Structure — arborescence des dossiers et leur rôle
- Conventions — style code, naming, tests, git workflow
- Decisions — choix techniques importants avec justification
- Commands — commandes shell utiles (build, test, deploy)
- Constraints — limites de sécurité, performance, dépendances
- Lessons Learned — pièges déjà rencontrés à éviter
4. Exemple complet — projet FastAPI Python
# CLAUDE.md
# Projet : ScoreCredit — Courtage crédit immobilier
# Maintenu par : équipe technique (3 devs)
# Dernière mise à jour : 2026-04-30
## Project Context
ScoreCredit est une plateforme de courtage en crédit immobilier français, ciblant
les emprunteurs avec des dossiers complexes (TNS, fonctionnaires, primo-accédants
sans apport). L'objectif : capter du trafic SEO long-tail puis convertir via un
funnel humanisé (Dr Lysiane Tendil, courtière ORIAS 26000195).
## Tech Stack
- Backend : Python 3.12, FastAPI 0.110+
- BDD : SQLite (production légère, <10k leads/an)
- Frontend : HTML statique avec Alpine.js + Tailwind CSS
- Infra : VPS OVH, systemd, Cloudflare devant
- Email : SMTP transactionnel pour notifications leads
- Analytics : GA4, Microsoft Clarity, GSC
## Project Structure
\`\`\`
/var/www/scorecredit/
├── app.py # FastAPI principal (routes, middleware)
├── routes_blog.py # Articles blog
├── routes_seo_pages.py # Pages SEO (taux, simulateurs)
├── database.py # SQLite + helpers
├── emails.py # Templates emails
├── nurture_sender.py # Cron J+3 J+6
├── static/
│ ├── pages/ # HTML statiques (articles)
│ ├── lead_magnet_widget.html
│ ├── exit_intent_popup.html
│ └── funnel_tracking.html
└── creditscore.db # BDD leads
\`\`\`
## Conventions
- Pas de f-string Python pour générer du HTML (problèmes d'échappement avec accents)
- Préférer des fichiers HTML statiques + open().read() pour les pages éditoriales
- Routes blog : convention /blog/[slug] avec slug = nom du fichier sans préfixe blog-
- Logging via print() vers stdout (capturé par systemd)
- Variables d'environnement dans /etc/scorezenith/master.env
- Backup avant patch majeur : /var/backups/scorecredit-pre-X-YYYYMMDD.tar.gz
## Decisions
- 2026-04-30 : ORIAS 26000195 (le bon numéro, PAS 20001195)
- 2026-04-29 : refonte funnel — popup CRO aspire les sliders simulateur
- 2026-04-22 : gel SEO en cours jusqu'au 22/05 pour mesurer impact
- 2026-04-15 : Turnstile Cloudflare obligatoire sur tous les endpoints API
- 2026-03 : middleware ASGI pour injecter widgets sitewide
## Commands
\`\`\`bash
# Restart
systemctl restart scorecredit
# Logs
journalctl -u scorecredit -f
# Backup
cd /var/www && tar czf /var/backups/scorecredit-$(date +%Y%m%d-%H%M%S).tar.gz scorecredit/
# Cloudflare purge
curl -X POST 'https://api.cloudflare.com/client/v4/zones/Z/purge_cache' -H "X-Auth-Key: $CF_KEY" --data '{"purge_everything":true}'
\`\`\`
## Constraints
- Latence p95 < 800ms (clients sur mobile 4G)
- Aucune donnée bancaire stockée (juste leads + simulations)
- RGPD : exports leads sur demande, suppression sous 30j
- Accessibilité : niveau WCAG AA cible
- Pas de framework JS lourd (Vue, Angular) — Alpine.js suffit
## Lessons Learned
- Ne jamais modifier titres/metas pendant un gel SEO
- Toujours backup avant restart sur fichiers critiques
- Cloudflare purge_everything peut casser le cache 5-10 min
- Les leads sans contexte projet (montant, durée) ne sont pas appelés par Lysiane
- Apostrophes en JSON Python : doubler avec backslash dans triples quotes
5. Exemple court — projet React + TypeScript
# CLAUDE.md
## Project Context
Application e-commerce B2B (catalogue + panier + paiement Stripe).
Stack moderne, équipe de 3 frontend devs.
## Tech Stack
- React 19, TypeScript 5.4 strict mode
- Vite 5, Tailwind CSS 4, shadcn/ui
- TanStack Query, Zustand
- Vitest + Playwright
- Backend : API GraphQL externe (pas dans ce repo)
## Conventions
- Composants en PascalCase, fichiers en kebab-case
- Types via interface (pas type) pour les props
- Imports absolus depuis @/ (alias)
- Tests obligatoires sur les composants > 50 lignes
- Commits : conventional commits (feat:, fix:, chore:)
## Commands
\`\`\`bash
npm run dev # Dev server localhost:5173
npm run build # Build prod
npm run test # Vitest unit
npm run test:e2e # Playwright E2E
npm run lint # ESLint + Prettier check
\`\`\`
## Decisions
- 2026-04 : passage à React 19 (use hook stable)
- 2026-03 : abandon Redux pour Zustand (trop lourd)
- 2026-01 : Tailwind 4 avec @theme inline (vs config JS)
## Constraints
- Bundle size < 250 ko gzip
- Lighthouse score > 90 sur les 3 pages clés
- Pas de dépendances avec license GPL/AGPL
6. Comment générer son CLAUDE.md automatiquement
Si vous avez déjà conversé avec Claude sur votre projet, MemoryForge peut extraire un CLAUDE.md prêt à commit :
- Aller sur MemoryForge
- Coller votre conversation Claude (ou export JSON)
- Sélectionner le format CLAUDE.md (Claude Code)
- Cliquer Extraire la mémoire
- Copier le résultat et le placer à la racine de votre projet Git
git add CLAUDE.md && git commit -m "docs: add CLAUDE.md for Claude Code"
⚡ Générer un CLAUDE.md depuis vos conversations Claude
Importez vos conversations Claude existantes, exportez en CLAUDE.md prêt à commit.
🧠 Aller sur MemoryForge7. Bonnes pratiques d'utilisation
À faire
- ✅ Mettre à jour à chaque décision technique majeure
- ✅ Commiter dans Git avec le code (l'équipe partage)
- ✅ Linker les conventions vers la doc complète si pertinent
- ✅ Garder les commandes shell copiables-collables (sans aliases perso)
- ✅ Documenter les "gotchas" du projet (les pièges connus)
À éviter
- ❌ Mettre des secrets, tokens API, mots de passe (Claude Code lit ce fichier !)
- ❌ Faire trop long (>3000 mots = LLM perd en précision)
- ❌ Dupliquer le contenu du README.md existant
- ❌ Mentionner des informations confidentielles couvertes par NDA
- ❌ Oublier de le mettre à jour pendant 6 mois
8. CLAUDE.md vs autres formats agents IA
| Fichier | Cible | Localisation |
|---|---|---|
| CLAUDE.md | Claude Code | Racine projet Git |
| .cursorrules | Cursor IDE | Racine projet Git |
| .continue/config.json | Continue IDE | Sous-dossier projet |
| AGENT.md | Agents autonomes | Racine ou sous-dossier |
| USER.md | Hermes Agent | Profil utilisateur |
| MEMORY.md | Universel (toutes IA) | Personnel ou racine |
Si vous travaillez avec plusieurs IA (Claude Code, Cursor, Continue), vous pouvez avoir plusieurs fichiers cohabitant. La spec MEMORY.md sert de format pivot universel.
9. Roadmap CLAUDE.md 2026
Anthropic n'a pas publié de spec officielle figée pour CLAUDE.md. Les conventions évoluent rapidement. Tendances observées :
- YAML frontmatter : ajout de métadonnées en début (version, date, mainteneur)
- Sections @ : sections taggées
@security,@performanceque Claude Code prioritise - Includes :
@include ./docs/api.mdpour fragmenter - Tools list : section listant les outils MCP disponibles dans le projet
Pour rester à jour, suivez la documentation officielle Anthropic et le repo Claude Code.
🚀 Créez votre CLAUDE.md en 30 secondes
MemoryForge convertit vos conversations Claude en CLAUDE.md prêt à commit. Format Claude Code natif.
⚡ Tester MemoryForge