Créer son claude.md

Contexte

CLAUDE.md est un fichier Markdown qui permet à Claude de conserver en mémoire les informations relatives à votre projet. Créez-le une seule fois, et Claude le lira automatiquement au début de chaque session.

Qu'est-ce que CLAUDE.md ?

La plupart des développeurs considèrent CLAUDE.md comme un fichier de documentation, ce qui est faux !

CLAUDE.md est un fichier de configuration qui fait partie de l'invite de commande système de Claude .

[

Lorsque vous saisissez des instructions dans CLAUDE.md, Claude les suit à la lettre, bien plus que tout ce que vous tapez dans le chat.

Pourquoi Claude ignorera votre CLAUDE.md

Claude Code intègre à votre fichier CLAUDE.md un rappel système indiquant à Claude d'ignorer le contenu non pertinent.

Le conteneur réel ressemble à ceci :

<system-reminder>
  IMPORTANT: this context may or may not be relevant to your tasks. 
  You should not respond to this context unless it is highly relevant to your task.
</system-reminder>

Cela signifie que si vous remplissez votre fichier CLAUDE.md d'instructions qui ne sont pas universellement applicables, Claude les ignorera.

C’est pourquoi le principe « moins, c’est plus » est la meilleure astuce lors de la création de votre fichier CLAUDE.md.

Modèle mental

Considérez CLAUDE.md comme trois choses :

1. Mémoire du projet — Claude conserve en mémoire votre configuration d'une session à l'autre

2. Limites opérationnelles — Règles que Claude ne transgressera pas

3. Introduction au contexte — Claude est bien informé, et non pas novice.

Lorsque vous comprenez ce modèle mental, vous cessez de traiter CLAUDE.md comme un fichier README, car il s'agit du meilleur point de configuration dont vous disposez dans Claude Code

Système hiérarchique CLAUDE.md

Les fichiers CLAUDE.md peuvent se trouver à plusieurs emplacements, et Claude les lit dans un ordre précis.

Comprendre cette hiérarchie vous permet de créer des règles globales qui s'appliquent partout et des règles spécifiques à un projet qui ne s'appliquent que là où c'est nécessaire.

Trois niveaux

Comment chaque niveau se charge

[

Prenons un exemple concret :

Configuration du monorepo

my-monorepo/
├── CLAUDE.md                    # Monorepo-wide rules
├── apps/
│   ├── web/
│   │   └── CLAUDE.md            # Frontend-specific rules
│   └── api/
│       └── CLAUDE.md            # Backend-specific rules
├── packages/
│   └── shared/
│       └── CLAUDE.md            # Shared library rules
└── tests/
    └── CLAUDE.md                # Testing conventions

Options de nommage des fichiers

• CLAUDE.md— Standard, commit sur git, partage avec l'équipe

• CLAUDE.local.md— Ajouter aux .gitignoreparamètres personnels

À utiliser .local.mdselon vos préférences personnelles, si vous ne souhaitez pas effectuer d'envoi vers le dépôt.

Anatomie d'un grand CLAUDE.md

Un fichier CLAUDE.md bien structuré répond à trois questions pour Claude :

• QUOI — La pile technologique, la structure du projet, les fichiers clés

• POURQUOI — L'objectif du projet, le rôle de chaque partie

• COMMENT — Commandes à exécuter, flux de travail à suivre, conventions à respecter

Sections principales

# Project Context

Brief description of what this project is and your working philosophy.

## About This Project

Tech stack, architecture pattern, key dependencies.

## Key Directories

- `src/` — Source code
- `tests/` — Test files
- `docs/` — Documentation

## Commands

```bash
npm run dev      # Start development server
npm run test     # Run tests
npm run build    # Production build

normes

• Conventions de codage

• exigences de test

• Format du message de validation

Flux de travail

Procédures étape par étape pour les tâches courantes.

Notes

Pièges, avertissements, choses que Claude devrait savoir.

Voici un exemple :

### A Real Example

Here's a CLAUDE.md for a FastAPI project:

```markdown
# Project Context

When working with this codebase, prioritize readability over cleverness. 
Ask clarifying questions before making architectural changes.

## About This Project

FastAPI REST API for user authentication and profiles. 
Uses SQLAlchemy for database operations and Pydantic for validation.

## Key Directories

- `app/models/` — Database models
- `app/api/` — Route handlers
- `app/core/` — Configuration and utilities
- `tests/` — Test files (fixtures in `tests/conftest.py`)

## Commands

```bash
uvicorn app.main:app --reload  # Dev server
pytest tests/ -v               # Run tests
alembic upgrade head           # Run migrations

normes

• Des indications de type sont requises pour toutes les fonctions.

• pytest pour les tests

• PEP 8 avec des lignes de 100 caractères

• Tous les itinéraires utilisent /api/v1le préfixe

Notes

• Les jetons JWT expirent après 24 heures.
• La limitation du débit est de 100 requêtes/minute par adresse IP.
• Ne jamais inclure les fichiers .env dans un commit

Contenu Claude.md

La plupart des problèmes liés à CLAUDE.md proviennent d'un excès d'informations, et non d'un manque. C'est un équilibre délicat qui ne peut être atteint qu'à l'aide de mes quatre règles :

1) Limite d'instructions : 150-200

Les recherches montrent que les LLM de pointe peuvent suivre de manière fiable environ 150 à 200 instructions.

De plus, la qualité du suivi des instructions se dégrade ; non seulement pour les nouvelles instructions, mais de manière uniforme pour toutes.

L'invite de commande du système de Claude Code contient déjà environ 50 instructions.

Il vous reste donc environ 100 à 150 instructions avant que Claude ne commence à les ignorer.

[

](https://substackcdn.com/image/fetch/$s_!07Zz!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2Fee30c862-3d73-42e4-9eb1-7aac419cf5d7_729x421.png)

C’est pourquoi moins, c’est plus, car chaque instruction inutile réduit la capacité de Claude à suivre les instructions importantes.

Inclure systématiquement :

• Aperçu du projet (1-2 phrases)

• Pile technologique et dépendances clés

• Commandes essentielles (compiler, tester, exécuter)

• Structure des répertoires (dossiers principaux uniquement)

• Conventions critiques dont l'omission provoque des bogues

Inclure si applicable à tous :

• Conventions d'appellation des branches

• Format du message de validation

• exigences de test

• Processus de déploiement

N’incluez jamais :

• Informations sensibles (clés API, identifiants, chaînes de connexion)

• Consignes détaillées de style de code (utilisez plutôt un linter)

• Instructions spécifiques à la tâche (utiliser des fichiers séparés)

• Tout ce que Claude pouvait déduire en lisant votre code

Déplacer vers des fichiers séparés :

• Détails du schéma de base de données

• Procédures de flux de travail complexes

• Analyses approfondies de l'architecture

• Documentation d'intégration

Divulgation progressive

Au lieu de tout ajouter dans CLAUDE.md, conservez les instructions spécifiques à chaque tâche dans des fichiers séparés et indiquez à Claude où les trouver.

Par exemple :

project/
├── CLAUDE.md                        # Core instructions only
└── agent_docs/
    ├── building_the_project.md
    ├── running_tests.md
    ├── code_conventions.md
    ├── database_schema.md
    └── deployment_process.md

Dans votre fichier CLAUDE.md, faites référence à ces fichiers :

## Additional Documentation

Before starting specific tasks, read the relevant documentation:

- Building: `agent_docs/building_the_project.md`
- Testing: `agent_docs/running_tests.md`
- Database work: `agent_docs/database_schema.md`
- Deployment: `agent_docs/deployment_process.md`

Read only what's relevant to your current task.

Claude ne charge ces fichiers qu'en cas de besoin, ce qui permet de garder votre contexte principal allégé.

3) N’utilisez pas CLAUDE.md comme outil de linter.

C'est une erreur fréquente que je vois souvent chez de nombreux développeurs : ajouter des consignes de style de code trop détaillées.

# Don't do this

## Code Style
- Use 2 spaces for indentation
- Always use semicolons
- Prefer const over let
- Use arrow functions for callbacks
- Add trailing commas in arrays
- Use single quotes for strings
...50 more rules

Utilisez les outils appropriés :

• ESLint/Prettier pour JavaScript

• Noir/Ruff pour Python

• rustfmt pour Rust

Pour résoudre ce problème, je propose de configurer un hook pre-commit ou d'utiliser les hooks de Claude Code pour exécuter automatiquement le linter.

4) Ma règle d'or

Si une instruction n'est pas pertinente pour plus de 80 % de mes sessions Claude Code, elle n'a pas sa place dans CLAUDE.md. Je la déplace dans un fichier séparé ou l'associe à une commande personnalisée.

Comment créer votre CLAUDE.md


Méthode 1 : La commande /init

La méthode la plus rapide pour démarrer. Claude analyse l'intégralité de votre code source et génère un fichier CLAUDE.md de démarrage.

cd your-project
claude
/init

Claude examine vos fichiers de paquetage, la documentation existante, les fichiers de configuration et la structure du code. Il génère un fichier CLAUDE.md contenant :

• Commandes de construction

• Instructions de test

• Répertoires clés

• Il a détecté des conventions de codage

Important : à considérer /initcomme un point de départ, et non comme un produit fini. Le fichier généré met en évidence les tendances générales, mais ne tient pas compte des spécificités de votre flux de travail. Il est essentiel de toujours le vérifier et de l’améliorer.

Vous pouvez également exécuter cette commande /initsur les projets qui possèdent déjà un fichier CLAUDE.md. Claude suggérera des améliorations en fonction de ce qu'il apprend en explorant votre code source.

Méthode 2 : Création manuelle

Créez vous-même le fichier dans n'importe quel éditeur Markdown :

touch CLAUDE.md

Vous pouvez aussi utiliser l'éditeur de votre choix. Aucun format n'est requis ; enregistrez-le en CLAUDE.mdmajuscules à la racine de votre projet.

Quand utiliser la création manuelle :

• Vous voulez un contrôle total dès le départ

• Vous suivez un modèle spécifique

• Vous voulez éviter les ballonnements qui /initse produisent parfois

Méthode 3 : Le raccourci mémoire

Ajoutez des instructions à la volée pendant que vous travaillez avec Claude Code. Tapez #suivi de votre instruction :

# Always run tests before committing

[

](https://substackcdn.com/image/fetch/$s_!XEc9!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2Fed6cf526-d4e7-46a9-a9e9-0dcad0cbd0bd_1284x810.gif)

C'est un outil puissant pour consigner des idées au fur et à mesure de votre travail. Lorsque vous trouvez un nouvel élément potentiel à ajouter à CLAUDE.md, ajoutez-le avec un point #.

Ma recommandation

Commencez par /initétablir une base, puis affinez-la manuellement. Utilisez #-la pour ajouter des instructions au fur et à mesure que de nouvelles idées vous viennent à l'esprit, et gardez ceci à l'esprit : les meilleurs fichiers CLAUDE.md sont construits de manière itérative.

Modèles CLAUDE.md avancés

Une fois les bases maîtrisées, ces modèles vous permettront de faire passer votre fichier CLAUDE.md au niveau supérieur.

Modèle 1 : Fichiers d’index pour les grandes bases de code

Pour les bases de code volumineuses ou peu familières, créez des fichiers d'index qui aideront Claude à naviguer efficacement.

Étape 1 : Générer un index général

# general_index.md

## /src/api/
- `auth.py` — Authentication endpoints, JWT handling
- `users.py` — User CRUD operations
- `products.py` — Product catalog endpoints

## /src/models/
- `user.py` — User model, relationships to orders
- `product.py` — Product model, inventory tracking

## /src/utils/
- `validators.py` — Input validation helpers
- `formatters.py` — Response formatting utilities

Étape 2 : Référencez-le dans CLAUDE.md

## Navigation

I have provided index files to help you navigate:

- `general_index.md` — File descriptions for each module
- `detailed_index.md` — Function signatures and docstrings

These indexes may or may not be up to date. Verify by checking 
the actual files when needed.

La mention « peut ne pas être à jour » est importante : elle empêche Claude de se fier uniquement à l’index et encourage la vérification.

Modèle 2 : Conception modulaire CLAUDE.md

Divisez votre fichier CLAUDE.md en sections claires à l'aide d'en-têtes Markdown. Cela évite la superposition d'instructions entre les différentes zones fonctionnelles.

# CLAUDE.md

## Development Commands
<!-- Build, test, run instructions -->

## Code Standards  
<!-- Conventions that apply everywhere -->

## Workflow Procedures
<!-- How to complete common tasks -->

## File Boundaries
<!-- What Claude can and cannot modify -->

## Tool Integration
<!-- MCP servers, custom commands -->

Chaque section est autonome. Claude peut ainsi se concentrer sur la section concernée sans être perturbé par d'autres instructions.

Modèle 3 : Définitions du flux de travail

Définir des flux de travail étape par étape pour les tâches complexes.

Cela empêche Claude de se lancer directement dans le code sans planification.

## Workflows

### Adding a New API Endpoint

1. Check if similar endpoint exists in `src/api/`
2. Create schema in `src/schemas/` if new data types needed
3. Implement endpoint in appropriate router file
4. Add tests in `tests/api/`
5. Update API documentation
6. Run full test suite before committing

### Database Schema Changes

1. Describe the change and why it's needed
2. Create migration: `alembic revision --autogenerate -m "description"`
3. Review generated migration file
4. Test migration: `alembic upgrade head`
5. Test rollback: `alembic downgrade -1`
6. Update relevant models and schemas

Modèle 4 : Échange de contexte

Pour les projets comportant des phases distinctes (développement vs déploiement, frontend vs backend), conservez plusieurs variantes de CLAUDE.md :

project/
├── CLAUDE.md                 # Active configuration
├── .claude/
│   ├── CLAUDE.development.md # Development focus
│   ├── CLAUDE.deployment.md  # Deployment focus
│   └── CLAUDE.debugging.md   # Debugging focus

Échangez-les au besoin :

cp .claude/CLAUDE.deployment.md CLAUDE.md

Cela permet à Claude de rester concentré et précis sur sa tâche.

Modèle 5 : Instructions conditionnelles

Dites à Claude de se comporter différemment en fonction de ce sur quoi il travaille :

## Conditional Rules

When working in `src/api/`:
- All endpoints must have OpenAPI documentation
- Use dependency injection for database sessions
- Return appropriate HTTP status codes

When working in `tests/`:
- Use fixtures from `conftest.py`
- Mock external services, never call them
- Each test file mirrors the source file structure

When working in `scripts/`:
- Scripts must be idempotent (safe to run multiple times)
- Include --dry-run option for destructive operations
- Log all actions for debugging

Modèle 6 : Documentation du serveur MCP

Si vous utilisez des serveurs MCP, documentez-les dans CLAUDE.md afin que Claude sache quand et comment les utiliser :

## MCP Integrations

### Slack MCP
- Posts to #dev-notifications channel only
- Use for deployment notifications and build failures
- Do not use for individual PR updates
- Rate limited to 10 messages per hour

### Database MCP
- Read-only access to production replica
- Use for data exploration, never for writes
- Prefer this over raw SQL when possible

Cela est lié à notre prochain numéro consacré à la Masterclass Claude Code MCP .

---

CLAUDE.md + Hooks et sous-agents

CLAUDE.md gagne en puissance lorsqu'il est combiné à d'autres fonctionnalités de Claude Code. Voici un aperçu de leur fonctionnement conjoint.

CLAUDE.md + Crochets

Les hooks sont des actions automatisées qui s'exécutent à des moments précis du flux de travail de Claude. Votre fichier CLAUDE.md peut y faire référence et interagir avec eux.

[

](https://substackcdn.com/image/fetch/$s_!Y5F5!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2Fecddb4bc-c0e7-45e1-9ea9-e4b33a5b48a4_806x372.png)

Au lieu de demander à Claude de vérifier la mise en forme (lent et coûteux), mettez en place un hook :

## Standards

Code must pass linting before commit. 
A pre-commit hook runs `npm run lint` automatically.
Do not manually check formatting — the hook handles it.

Le fichier CLAUDE.md informe Claude de l'existence de la règle. Le hook l'applique. Claude peut alors se concentrer sur le codage proprement dit.

CLAUDE.md + Sous-agents

Les sous-agents sont des instances Claude isolées qui gèrent des tâches spécifiques. Ils possèdent leur propre fenêtre de contexte, empêchant ainsi les informations d'une tâche de perturber une autre.

[

](https://substackcdn.com/image/fetch/$s_!LALW!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F5822ea22-beb3-47f2-af65-209e74eec8b0_739x504.png)

Votre fichier CLAUDE.md aide les sous-agents à comprendre rapidement le projet sans avoir besoin de l'historique complet des conversations.

## Subagent Guidelines

When delegating tasks to subagents:
- Security reviews: Use fresh subagent, don't carry implementation context
- Code exploration: Subagent should read general_index.md first
- Documentation: Subagent can access docs/ freely

CLAUDE.md est déjà puissant en soi. Combiné à des hooks et des sous-agents, il devient un système d'automatisation complet :

• Le fichier CLAUDE.md définit les règles

• Les hooks les appliquent automatiquement.

• Les sous-agents gèrent des tâches spécialisées dans un contexte propre

---

Maintenance Claude.md

[

](https://substackcdn.com/image/fetch/$s_!h9vv!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2Fabb60890-4225-49ac-85fb-6f1cfe550c52_862x495.png)

CLAUDE.md n'est pas un fichier que l'on configure une fois pour toutes.

Les projets évoluent, les équipes adoptent de meilleures pratiques et de nouveaux outils s'intègrent à votre flux de travail. Voici comment le maintenir à jour.

Meilleures pratiques de maintenance

1. Mettez à jour avec vos PR

Ajoutez CLAUDE.md à votre liste de contrôle RP :

• [ ] Modifications du code terminées

• [ ] Tests réussis

• [ ] Documentation mise à jour

• [ ] CLAUDE.md mis à jour en cas de modification des flux de travail

2. Utilisez le raccourci # en continu.

Lorsque vous découvrez quelque chose que Claude oublie systématiquement, ajoutez-le immédiatement :

# Always run database migrations before starting the dev server

Ces petits ajouts s'accumulent pour former un fichier CLAUDE.md qui reflète la réalité.

3. Examen trimestriel

Programmez un rappel pour consulter votre fichier CLAUDE.md tous les quelques mois :

• Toutes les commandes sont-elles toujours exactes ?

• Des modifications ont-elles été apportées aux processus de travail ?

• Y a-t-il des éléments obsolètes ou redondants ?

• Peut-on enlever quelque chose ?

4. Contrôler les versions

Intégrez CLAUDE.md dans git. Votre équipe bénéficiera des améliorations et vous pourrez suivre les modifications apportées.

---

Réflexions finales

Le fichier CLAUDE.md est la base de tout dans Claude Code. Une fois ce fichier correctement configuré, toutes les autres fonctionnalités (hooks, sous-agents et MCP) fonctionnent mieux.

Points clés à retenir :

• CLAUDE.md est un fichier de configuration, pas de documentation.

• Claude considère cela comme des règles système, plus strictes que vos invites.

• Moins, c'est plus — si vous dépassez 100 à 150 instructions, vous en faites trop.

• Utilisez la hiérarchie : global → projet → imbriqué

• La divulgation progressive est préférable aux dossiers volumineux

• Itérez en continu avec le raccourci #

Dans le prochain numéro de Masterclass, nous aborderons l'automatisation par hooks . Votre fichier CLAUDE.md définira les règles, et les hooks les appliqueront.

Ressources

PS : Je travaille actuellement sur notre dépôt Git principal Claude Code Masterclass, où j’ajouterai tous ces extraits de code et modèles pour un accès rapide et facile.

Concernant ce problème, voici les ressources qui seront bientôt ajoutées au dépôt :

• Modèles Claude.md par type de projet

• Claude.md Erreurs courantes

• Tous les extraits de code partagés dans cette newsletter

---

À suivre : Les questions à venir

Les prochains numéros de cette série de masterclass aborderont les sujets suivants :

• Masterclass Claude Code Hooks — Automatisation sans intervention

• Masterclass Claude Code Subagents — Constituer votre équipe IA

• Masterclass Claude Code MCP — Étendre les fonctionnalités de Claude

Votre fichier CLAUDE.md constitue la base dont vous avez besoin avant de passer aux hooks, aux serveurs MCP et aux sous-agents.