Guide : Comment bien Setup son Fichier CLAUDE.md ?

Ce qu’est vraiment le fichier CLAUDE.md

Le fichier CLAUDE.md est un fichier Markdown que vous placez (généralement à la racine de votre projet) pour donner du contexte permanent à Claude Code.

Il est chargé automatiquement au démarrage de chaque session, et son contenu devient le cadre de travail de Claude pour toutes les interactions avec le code.

C’est le mécanisme de mémoire explicite de Claude Code : un fichier Markdown que vous écrivez une fois et qui lui donne le contexte permanent dont il a besoin pour travailler correctement dans votre projet. Adieu les prompts système interminables.

Pas besoin de le mentionner, pas besoin de copier-coller quoi que ce soit — il est là, lu, intégré.

Ce fichier est fait pour contenir ce qui ne change pas d’une session à l’autre :

• Vos standards de code
• L’architecture du projet
• Les commandes de build
• Les conventions de nommage.
• Etc.

Tout ce que vous vous retrouvez à répéter dans vos prompts, c’est là que ça va.

Ce qu’il n’est pas : un fourre-tout pour tout documenter. Ce n’est pas un README.me, ce n’est pas un wiki. C’est un contexte de travail opérationnel, et sa valeur vient directement de sa concision (ça ce n’est pas moi qui le dit mais Anthropic !). 👇

Voici par exemple le fichier généré par Claude pour laConsole. Court, structuré, directement actionnable :

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

npm run dev          # Start dev server at localhost:4321
npm run build        # Build production site to ./dist/
npm run preview      # Preview production build locally
npm run prettier     # Format all files with Prettier

No test suite is configured. Use `npm run astro check` for TypeScript/Astro diagnostics.

## Tech Stack

- **Astro 5** — static site generator with file-based routing
- **Vue 3** — interactive components (islands architecture)
- **Tailwind CSS 3** — utility-first styling with custom theme
- **MDX** — content format for articles, formations, and lessons
- **Vercel** — deployment target (adapter configured)

## Architecture

### Content Collections (`src/content/`)

All editorial content lives in Astro content collections with Zod schemas defined in `src/content.config.ts`. Key collections:

- `article/` — blog posts (MDX)
- `formation/` — training courses (MDX); references lessons via frontmatter `lessons` array
- `lesson/{formation-slug}/` — lessons nested under their formation (MDX)
- `cheatsheet/` + `cheatsheetBlock/` — reference sheets
- `asset/`, `product/`, `authors/`, `logo/` — JSON-based data collections

### Routing (`src/pages/`)

File-based routing via Astro. Dynamic segments use `[slug].astro` or `[...rest].astro`. Main sections: `/blog/`, `/formations/`, `/cheatsheets/`, `/examens/`, `/glossaire/`, `/ressources/`.

### Component Organization (`src/components/`)

Components are grouped by feature (`article/`, `formation/` and `cheatsheet/`). Global UI lives in `global/`. MDX-specific components (`MdxCallout`, `MdxPart`, `MdxCode`...) live in `mdx/` and are used inline in content files.

### State Management

Lightweight [Nanostores](https://github.com/nanostores/nanostores) for client state, integrated with Vue via `@nanostores/vue`. Stores are in `src/stores/`.

### Path Aliases

Configured in `tsconfig.json`:
- `@/*` → `src/*`
- `@components/*` → `src/components/*`
- `@layouts/*` → `src/layouts/*`
- `@stores/*` → `src/stores/*`
- `@styles/*` → `src/styles/*`
- `@scripts/*` → `src/scripts/*`
- `@models/*` → `src/models/*`

### External Integrations

- **EngineMailer** — email marketing
- Keys are stored in `.env` (not committed)

## Content Conventions

- **Language**: French (spell-check configured for `fr`)
- **Dates**: ISO format in frontmatter (`publishedDate`, `updatedDate`)
- **Drafts**: Set `draft: true` in frontmatter to hide from production
- **Lessons**: Must be placed in `src/content/lesson/{formation-slug}/` and referenced in the parent formation's `lessons` frontmatter array
- **MDX components**: Use `<MdxCallout>` for callout boxes, `<MdxPart>` for content sections, `<MdxCode>` for code blocks with copy button, `<MdxGallery>` for image galleries, etc.

## Code Style

Prettier is the formatter (`.prettierrc`): 80-char line width, single quotes, trailing commas, Astro plugin enabled. Run `npm run prettier` before committing.

0% blabla, 100% value.

Notez ce qu’il y a, et surtout ce qu’il n’y a pas. Pas de philosophie sur “écrire du bon code”, pas de paragraphes explicatifs. Des règles concrètes et vérifiables, point.

Comment configurer CLAUDE.md ?

Création du fichier

claude /init

La commande /init analyse votre projet et génère automatiquement un CLAUDE.md de départ.

Claude inspecte votre codebase :

• Fichiers de configuration (package.json, tsconfig.json, .eslintrc, …)
• Arborescence des dossiers
• Commandes de build
• Etc.

Puis, à partir de cela, il en extrait ce qui mérite d’être dans le contexte permanent.

Le fichier généré n’est jamais parfait, mais il vous donne une base solide à affiner.

Importer d’autres fichiers existants

Vous pouvez référencer d’autres fichiers depuis votre CLAUDE.md avec la syntaxe @ :

# Contexte projet

@README.md
@docs/git-workflow.md
@docs/api-conventions.md

Ces fichiers sont inclus dans le contexte au même titre que le CLAUDE.md principal. C’est pratique pour éviter la duplication d’informations. Autrement dit, si votre README.md contient déjà l’architecture du projet, inutile de la réécrire !

Découper en règles thématiques

Sur les projets importants, un seul CLAUDE.md devient difficile à maintenir. La solution : créer un dossier .claude/rules/ et découper par domaine.

.claude/
├─ rules/
│  ├─ code-style.md
│  ├─ testing.md
│  ├─ security.md
│  └─ git-workflow.md

Chaque fichier reste focalisé sur son thème.

Vous pouvez aussi appliquer des règles à des chemins spécifiques via le frontmatter, ce qui est très pratique pour des conventions qui ne s’appliquent qu’à certaines parties du codebase :

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

## Conventions API
- Toujours valider les inputs avec Zod
- Retourner les erreurs au format { error: string, code: string }
- Pas de logique métier dans les route handlers — déléguer aux services

La mémoire automatique : l’autre mécanisme

En parallèle du CLAUDE.md, Claude Code dispose d’un second système : la mémoire automatique. Claude écrit lui-même ses apprentissages dans ~/.claude/projects/<project>/memory/. Cette mémoire repose sur un historique de fichiers JSON que Claude met à jour au fil de ses sessions. On y retrouve notamment :

• Les commandes qu’il a utilisées
• Les patterns observés
• Les solutions de debugging qui ont fonctionné.
• Etc.

Cette mémoire est chargée au début de chaque session (dans la limite des 200 premières lignes). Vous n’avez rien à faire : Claude gère ça de son côté, progressivement.

La distinction entre les deux systèmes est importante :

En pratique : ce que vous voulez imposer va dans CLAUDE.md, ce que Claude découvre au fil du temps se retrouve dans la mémoire automatique. Les deux sont complémentaires, pas redondants.

Les bonnes pratiques à retenir

Voici quelques règles d’or recommandées par Anthropic pour tirer le meilleur parti de votre CLAUDE.md :

• Restez sous 200 lignes. C’est la limite après laquelle l’attention de Claude se dilue. Si vous dépassez, coupez sans pitié.
• Structurez avec des titres Markdown. Claude parse la hiérarchie. Une section “Standards de code” bien séparée d’une section “Architecture” aide à la fois la lisibilité et la compréhension.
• Soyez spécifique et vérifiable. “Écrire du code propre” ne veut rien dire. “Indentation de 2 espaces, pas de tabulations, point-virgules obligatoires” est vérifiable. Si vous ne pouvez pas tester si une règle est respectée ou non, elle est trop vague pour être utile.
• Évitez les contradictions entre fichiers. Si vous avez plusieurs CLAUDE.md (racine + sous-dossiers), assurez-vous qu’ils ne se contredisent pas. Claude suit le fichier le plus spécifique, mais une contradiction explicite crée de la confusion.
• Mettez-le en versionning. Le CLAUDE.md fait partie du projet au même titre que le code. Il doit être commité, reviewé, et évoluer avec le codebase.