Bonnes pratiques CLAUDE.md : modèle concret pour projets Claude Code

CLAUDE.md sert à éviter de répéter à chaque session la structure, les commandes et les règles du projet. Ce n’est pas une barrière de sécurité et ce n’est pas une archive complète.

Les règles partagées doivent être courtes et vérifiables; les préférences personnelles restent locales; les interdictions fortes passent par permissions et hooks. Cet article explique ce qui doit rester dans CLAUDE.md et ce qui doit vivre ailleurs, avec une approche utilisable par un débutant.

Le but est de démarrer avec un modèle copiable et de permettre à l’équipe de le maintenir sans créer une encyclopédie.

Core idea: CLAUDE.md is guidance, not enforcement

Les règles partagées doivent être courtes et vérifiables; les préférences personnelles restent locales; les interdictions fortes passent par permissions et hooks. Dans la documentation officielle, CLAUDE.md est un guidage contextuel, Auto memory garde des apprentissages locaux, settings configure le client et hooks exécute des commandes lors d’événements précis.

Mechanism	Role	Best for
CLAUDE.md	Human-written persistent guidance	Conventions, architecture, verification commands
Auto memory	Claude’s local learned notes	Debugging insights, preferences, repeated discoveries
settings / permissions	Client configuration and permission rules	Allow, deny, extra directories
hooks	Commands run at lifecycle events	Blocking risky actions, verification, formatting

Where to place CLAUDE.md files

Claude Code lit CLAUDE.md et CLAUDE.local.md depuis le dossier de travail vers les parents. Les règles racine sont chargées au départ; les règles imbriquées arrivent quand les fichiers concernés sont lus.

repo/
  CLAUDE.md                 # shared project guidance
  CLAUDE.local.md           # personal, gitignored
  .claude/
    rules/
      api.md                # path-scoped rule
  packages/admin/CLAUDE.md  # loaded when this subtree is read

What to keep in always-loaded memory

Gardez les commandes de build, tests, frontières d’architecture, règles de nommage, interdictions et contrôles de revue. Excluez secrets, longs logs, comptes rendus, plans ponctuels et grosses recherches.

• Keep build, test, lint, type-check, and release verification commands.
• Keep edit boundaries, non-edit boundaries, naming rules, and review gates.
• Do not keep secrets, long meeting notes, historical logs, or one-off task instructions.
• Do not paste entire official docs. Keep the URL and the decision rule.

Copy-paste CLAUDE.md template

Le modèle ci-dessous reste court pour ne pas alourdir le contexte. Adaptez-le au projet et gardez des règles vérifiables.

# Project Instructions

## Project map
- App: Next.js 15 + TypeScript
- API: src/app/api/**
- DB: Prisma schema in prisma/schema.prisma
- Tests: Vitest for units, Playwright for critical browser flows

## Commands
- Install: npm ci
- Type check: npm run typecheck
- Unit tests: npm test
- Lint: npm run lint
- Build: npm run build

## Change rules
- Prefer small edits that follow existing patterns.
- Do not change auth, billing, or migrations without explicit task scope.
- When editing API handlers, update validation and tests in the same pass.
- Before final response, report commands run and any skipped verification.

## Review checklist
- No secrets in code, logs, fixtures, or screenshots.
- Error paths are tested, not only the happy path.
- Public copy and docs use the same terminology as the UI.

Use imports and .claude/rules carefully

Les imports @path organisent le fichier mais ne réduisent pas les tokens. Le contenu importé entre aussi dans le contexte. Pour les grands projets, supprimez l’ancien et déplacez les règles par chemin vers .claude/rules/.

# CLAUDE.md

Read the short project overview in @docs/project-map.md.
Do not import long meeting notes here.

## Compact Instructions
- Preserve current objective, files changed, tests run, and unresolved risks.
- Drop raw command output unless it explains a failure.

---
paths:
  - "src/api/**/*.ts"
---

# API rules
- Validate request bodies with Zod.
- Return typed error responses.
- Add or update tests for every changed handler.

Three practical use cases

1. Les cas les plus rentables sont l’onboarding, la correction de bugs et la production de contenu avec une ligne éditoriale stable. Pour l’onboarding, écrivez d’abord la carte du projet et les commandes de vérification.
2. Pour un bug, ajoutez la reproduction, l’emplacement des logs et le test minimal.
3. Pour le contenu, gardez le ton, les liens internes et les contrôles qualité dans CLAUDE.md; les notes longues restent dans Obsidian ou docs.

Failure cases and pitfalls

1. L’erreur typique est d’importer tout le README, d’écrire des règles vagues ou de compter sur CLAUDE.md pour la sécurité. Gardez seulement les règles toujours utiles.
2. Remplacez “rends cela propre” par des commandes et des frontières de fichiers précises.
3. La sécurité forte exige permissions et PreToolUse hooks; CLAUDE.md seul ne suffit pas.

Team maintenance rule

Mettez CLAUDE.md à jour quand une erreur se répète, quand une review répète le même commentaire, ou quand une commande ou frontière change.

# quick review before changing CLAUDE.md
rg -n "TODO|deprecated|temporary|secret|password|token" CLAUDE.md .claude/rules
git diff -- CLAUDE.md .claude/rules

Next step and monetization path

Pour un workflow complet, reliez cette pratique à Obsidian, à l’optimisation des tokens et à la page de consultation. Le workflow complet se combine avec Obsidian, l’optimisation des tokens et la page de consultation. Related articles: Obsidian workflow, productivity tips, permissions guide, and consultation page.

What was verified

Cette mise à jour suit les pages officielles memory, context window, settings et commands. Official references: memory, context window, settings, and commands.