Guide d'utilisation de CLAUDE.md
CLAUDE.mdC'est le fichier de configuration le plus important de Claude Code, utilisé pour transmettre à Claude des instructions persistantes au niveau du projet. Chaque fois qu'une session Claude Code est démarrée, il lit et charge automatiquement le contenu de ce fichier, en l'intégrant à chaque conversation comme contexte au niveau système.
En termes simples,CLAUDE.mdc'est un manuel de travail que vous rédigez pour Claude dans le projet — lui indiquant ce qu'est le projet, quelles normes suivre et à quoi faire attention, afin qu'il puisse travailler d'une manière qui réponde aux exigences du projet à chaque fois, au lieu de devoir tout réexpliquer à chaque conversation.
Le rôle de CLAUDE.md
SansCLAUDE.mdlui, Claude commence à comprendre votre projet à partir de zéro à chaque fois, et vous devez lui répéter : quel gestionnaire de paquets utiliser, quel est le style de code, comment exécuter les tests, quels fichiers ne pas toucher... AvecCLAUDE.md, cette information n'a besoin d'être écrite qu'une seule fois, et Claude la suivra à chaque fois.
Plus précisément,CLAUDE.mdil peut vous aider à obtenir ce qui suit :
- Unifier le comportement de l'équipe: Validez le fichier dans git, et tous les membres de l'équipe suivent les mêmes normes lorsqu'ils utilisent Claude Code
- Réduire la communication répétitive: Les conventions de projet, les règles d'architecture et les éléments interdits sont écrits une seule fois et restent applicables en permanence
- Réduire la probabilité d'erreurs: Informer clairement Claude des opérations risquées, en l'empêchant de prendre de mauvaises décisions
- Accélérer la compréhension par l'IA: Aider Claude à localiser rapidement les fichiers clés et à comprendre la structure du projet, en réduisant l'exploration inutile des fichiers
Emplacement des fichiers
Claude Code se charge depuis plusieurs emplacementsCLAUDE.md, et les fichiers dans différents emplacements ont des portées différentes :
| Emplacement | Chemin | Portée | Effectuer un commit dans git ? |
|---|---|---|---|
| Répertoire racine du projet | {项目根目录}/CLAUDE.md |
Toutes les sessions du projet actuel | ✅ Recommandé pour un commit, partagé par l'équipe |
| Local au projet | {项目根目录}/.claude/CLAUDE.md |
Toutes les sessions du projet actuel | ❌ Ajouter à .gitignore, pour un usage personnel uniquement |
| Sous-répertoire | {任意子目录}/CLAUDE.md |
Chargé automatiquement lorsque Claude ouvre des fichiers dans ce répertoire | ✅ Adapté aux dépôts multi-modules |
| Niveau utilisateur global | ~/.claude/CLAUDE.md |
Tous les projets de l'utilisateur actuel | ❌ Configuration personnelle, ne pas committer |
Lorsque plusieurs emplacements ontCLAUDE.md, Claude Code vacharger et fusionner tous ces emplacements, avec priorité de la plus haute à la plus basse comme suit :
Project local → Project root directory → Subdirectory → Global user level
Celui du répertoire racine du projet
CLAUDE.mdIl est recommandé de committer dans git afin que toute l'équipe partage le même ensemble de normes de travail IA.Les préférences personnelles (comme ne pas aimer les points-virgules) doivent être placées dans
.claude/CLAUDE.mdet ajoutées à.gitignore, sans affecter les autres.
Créer rapidement CLAUDE.md
La façon la plus simple est de laisser Claude Code générer automatiquement une version initiale. Après avoir démarré Claude Code dans le répertoire du projet, exécutez :
/init
Claude Code analysera la structure de votre projet, le style de code et les fichiers de configuration existants (tels quepackage.json、pyproject.toml、.eslintrcetc.), et générera automatiquement une version correspondant à la situation réelle du projetCLAUDE.md, puis vous pourrez la compléter et l'ajuster en vous basant sur celle-ci.
Vous pouvez également le créer manuellement dans le répertoire du projet :
touch CLAUDE.md
Structure du contenu du fichier
CLAUDE.mdIl s'agit d'un fichier Markdown ordinaire sans exigences de format obligatoires, mais une bonne structure peut aider Claude à trouver plus rapidement les informations clés. Voici la structure de contenu recommandée :
# 项目名称 一句话说明这个项目是什么,方便 Claude 快速定位项目性质。 ## 技术栈 - 语言:Python 3.11 - 框架:FastAPI 0.110 - 数据库:PostgreSQL 15 + SQLAlchemy ORM - 测试:pytest ## 常用命令 ### 开发 ```bash uv run uvicorn main:app --reload # 启动开发服务器 uv run pytest # 运行所有测试 uv run pytest -k "test_auth" # 运行指定测试 ``` ### 代码检查 ```bash uv run ruff check . # 代码检查 uv run ruff format . # 代码格式化 ``` ## 项目结构 - `src/api/` — API 路由和请求处理 - `src/models/` — 数据库模型定义 - `src/services/` — 业务逻辑层 - `tests/` — 测试文件,与 src/ 目录结构镜像对应 ## 编码规范 - 使用 `uv` 管理依赖,不使用 pip 直接安装 - 所有函数必须有类型注解 - 字符串一律使用双引号 - 新增 API 路由必须同步添加测试 ## 注意事项 - 不要修改 `migrations/` 目录下的已有文件,只能新增迁移文件 - `config/secrets.py` 包含敏感配置,禁止输出其内容到日志或终端 - 数据库操作必须通过 Service 层,不要在路由层直接操作 ORM
Explication détaillée des modules de contenu principaux
1. Commandes courantes
C'estCLAUDE.mdMedium, la partiela plus fréquemment référencée. Lorsque Claude effectue des tâches telles que les tests, la compilation et l'analyse statique du code, il recherchera d'abord les commandes définies ici, ce qui évite de deviner ou d'utiliser des commandes incorrectes :
## 常用命令 ### 安装依赖 ```bash npm ci # 安装依赖(CI 环境使用,严格按 lock 文件安装) ``` ### 开发 ```bash npm run dev # 启动开发服务器(端口 3000) npm run build # 构建生产版本 npm run preview # 预览生产构建 ``` ### 测试 ```bash npm test # 运行所有测试 npm test -- --watch # 监听模式 npm test -- --coverage # 生成覆盖率报告 ``` ### 代码质量 ```bash npm run lint # ESLint 检查 npm run lint:fix # 自动修复可修复的问题 npm run typecheck # TypeScript 类型检查 ```
2. Description de la structure du projet
Aide Claude à localiser rapidement les fichiers et à réduire les analyses de répertoires inutiles, particulièrement efficace dans les grands projets :
## 项目结构 ``` src/ ├── app/ # Next.js App Router 页面 │ ├── (auth)/ # 需要登录才能访问的页面组 │ └── api/ # API 路由 ├── components/ # 可复用 UI 组件 │ ├── ui/ # 基础 UI 组件(Button、Input 等) │ └── features/ # 业务组件(按功能模块组织) ├── lib/ # 工具函数和配置 │ ├── db/ # 数据库客户端和查询 │ └── auth/ # 认证相关逻辑 └── types/ # TypeScript 类型定义 ``` 关键文件: - `src/lib/db/client.ts` — 数据库连接配置 - `src/middleware.ts` — 认证中间件,处理路由保护 - `env.example` — 所有必要的环境变量示例
3. Normes de codage
Informe Claude du style de code et des conventions du projet, en veillant à ce que le code généré soit cohérent avec le style de la base de code existante :
## 编码规范
### 通用
- 文件名使用 kebab-case(如 `user-profile.ts`),类名使用 PascalCase
- 优先使用具名导出(named export),避免默认导出(default export)
- 异步函数一律使用 async/await,禁止使用 .then() 链式调用
### 组件规范
- 组件文件与其测试文件放在同一目录(如 `Button.tsx` 和 `Button.test.tsx`)
- Props 类型使用 interface 定义,命名格式为 `${组件名}Props`
- 不要将业务逻辑写在组件中,提取为自定义 Hook 或 Service
### 错误处理
- API 路由使用统一的错误响应格式:`{ error: string, code: string }`
- 客户端错误通过 Error Boundary 捕获,不要在每个组件里单独 try/catch
4. Contraintes d'architecture et points interdits
C'est la partie clé pour empêcher Claude de prendre des décisions « intelligentes mais erronées ». Pour les situations particulières que vous comprenez mais que Claude ne connaît pas, vous devez les écrire clairement :
## 架构约束 - 所有数据库查询必须通过 `src/lib/db/queries/` 中的函数执行,不要在路由或组件中直接写 SQL - 状态管理使用 Zustand,不要引入 Redux 或其他状态管理库 - 样式使用 Tailwind CSS utility class,不要新增 CSS 文件或使用 CSS Modules ## 注意事项(重要) - `legacy/` 目录下的代码是遗留代码,**禁止修改**,只能读取 - `.env.local` 和 `.env.production` 包含真实密钥,**禁止输出文件内容** - `prisma/migrations/` 中已有的迁移文件**禁止修改**,数据库变更只能新增迁移 - 修改 `src/middleware.ts` 前必须先告知我,该文件影响所有路由的认证逻辑
5. Description de l'environnement de développement
Aide Claude à comprendre l'environnement d'exécution du projet, en évitant les échecs d'exécution de commandes dus aux différences d'environnement :
## 开发环境 - Node.js:需要 v20 或以上版本(通过 `.nvmrc` 指定) - 包管理器:pnpm(禁止使用 npm 或 yarn 安装依赖) - 本地数据库:Docker Compose 启动(`docker compose up -d`) - 端口:前端 3000,API 3001,数据库 5432 ### 环境变量 参考 `.env.example` 文件配置本地环境变量,复制为 `.env.local` 后填入实际值。 必填项:`DATABASE_URL`、`NEXTAUTH_SECRET`、`NEXTAUTH_URL`
Configuration pour un dépôt multi-modules (monorepo)
Dans un monorepo, vous pouvez placer un fichier global dans le répertoire racine du dépôtCLAUDE.md, et placer le fichier correspondant dans chaque répertoire de sous-package.CLAUDE.mdLorsque Claude ouvre un fichier dans un sous-package, il chargera à la fois les fichiers du répertoire racine et ceux du répertoire du sous-package :
my-monorepo/
├── CLAUDE.md ← 全局规范:共用命令、整体架构、通用约定
├── packages/
│ ├── web/
│ │ └── CLAUDE.md ← 前端专属:React 规范、样式约定、构建流程
│ ├── api/
│ │ └── CLAUDE.md ← 后端专属:API 设计规范、数据库约定
│ └── shared/
│ └── CLAUDE.md ← 共享包:导出规则、版本管理约定
└── tools/
└── CLAUDE.md ← 工具脚本:特殊说明和使用限制
<!-- 根目录 CLAUDE.md(全局规范) --> # My Monorepo 使用 pnpm workspace 管理的前后端一体化项目。 ## 全局命令 ```bash pnpm install # 安装所有包的依赖 pnpm -r build # 构建所有包 pnpm -r test # 运行所有包的测试 pnpm --filter web dev # 只启动 web 包的开发服务器 ``` ## 包之间的依赖关系 - `web` 和 `api` 都依赖 `shared` - 禁止 `shared` 依赖 `web` 或 `api`(防止循环依赖) - 跨包引用使用包名(如 `@my-app/shared`),不要使用相对路径
Référencer des fichiers externes avec la syntaxe @
Lorsque le projet possède déjà des documents de spécification (tels que des spécifications de conception d'API, des documents de conception de base de données, etc.), il n'est pas nécessaire de copier le contenu dansCLAUDE.mdAu lieu de cela, utilisez directement@file pathpour les référencer.
Lorsque Claude litCLAUDE.mdil chargera automatiquement le contenu du fichier référencé :
## 规范文档 详细的 API 设计规范请参考: @docs/api-design-guide.md 数据库设计约定: @docs/database-conventions.md 组件库使用说明: @docs/component-guidelines.md
Le chemin du fichier référencé est relatif à
CLAUDE.mdle répertoire où se trouve le fichier. Le contenu du fichier référencé occupera de l'espace dans la fenêtre de contexte, donc évitez de référencer des fichiers trop volumineux (il est recommandé qu'un fichier référencé ne dépasse pas 500 lignes).
Conseils d'utilisation du CLAUDE.md global
Niveau utilisateur~/.claude/CLAUDE.mdconvient pour stocker des préférences et habitudes personnelles communes à tous les projets ; ces contenus prennent effet pour tous les projets :
<!-- 文件路径:~/.claude/CLAUDE.md --> # 个人全局配置 ## 回答偏好 - 回复使用中文 - 代码修改前先简要说明修改思路,不要直接给出代码 - 遇到有多种实现方案时,列出选项让我选择,而不是直接选一种 ## 通用约定 - 提交信息使用英文,格式:`type(scope): description` - 新文件开头不加版权注释 - 优先使用原生 API,避免引入不必要的依赖 ## 安全习惯 - 修改认证相关代码前主动提示我注意安全影响 - 不要在代码注释或日志中输出任何密钥或 token
Conseils de maintenance pour CLAUDE.md
1. Soyez concis
CLAUDE.mdLe contenu occupera de l'espace dans la fenêtre de contexte à chaque session. Trop de contenu comprimera l'espace de contexte réel disponible pour Claude, réduisant l'efficacité. Il est recommandé de suivre ces principes :
- Écrivez chaque règle une seule fois ; ne répétez pas la même signification.
- N'incluez pas d'informations de contexte sans rapport avec le code (comme les présentations d'entreprise, les plans de produit).
- Les informations qui peuvent être transmises par le code lui-même (comme la configuration eslint qui définit déjà le style de code) n'ont pas besoin d'être
CLAUDE.mddéclarées à nouveau dans le fichier. - Il est recommandé de garder le nombre total de mots dans la limite de 500 mots ; lorsqu'il dépasse 1000 mots, envisagez de simplifier.
2. Mettre à jour en continu
À mesure que le projet évolue,CLAUDE.mdil doit également être mis à jour de manière synchrone. Les occasions suivantes doivent déclencher des mises à jour :
- Changement de gestionnaire de paquets ou d'outil de build
- Ajout ou suppression de bibliothèques de dépendances importantes
- A établi de nouvelles conventions de codage
- A découvert que Claude commet de façon répétée le même type d'erreur (ce qui indique qu'il doit être
CLAUDE.mdcomplété dans le fichier) - Un certain fichier ou module est devenu non modifiable à volonté (à ajouter aux précautions)
3. Utiliser un langage impératif
Plus l'instruction est claire, plus la probabilité que Claude la suive est élevée. Évitez les descriptions vagues et utilisez des commandes directes :
| ❌ Description vague | ✅ Instruction claire |
|---|---|
| Le code doit être relativement propre | Les fonctions ne doivent pas dépasser 50 lignes ; si c'est le cas, elles doivent être scindées. |
| Essayez d'écrire des tests | Chaque nouvelle fonction doit avoir un test unitaire correspondant |
| Faites attention à la sécurité | Les entrées utilisateur doivent passer parsanitize()un traitement de fonction avant d'être transmises aux requêtes de base de données |
| Le répertoire legacy n'est pas très important | Il est interdit de modifierlegacy/tout fichier dans le répertoire |
| Il est préférable d'utiliser pnpm | Pour la gestion des dépendances, utilisez uniquement pnpm ; npm et yarn sont interdits. |
Exemple complet
Ce qui suit est l'exemple complet d'un projet full-stack Node.js + TypeScriptCLAUDE.mdqui peut servir de modèle de référence pour votre projet :
Exemple
Basé sur Next.js 14 App Router + Prisma +Système de gestion e-commerce avec PostgreSQL.
## Stack technique
-Frontend : Next.js 14(App Router), TypeScript, Tailwind CSS, shadcn/ui
-Backend : Next.js API Routes, Prisma ORM
-Base de données : PostgreSQL15
-Authentification : NextAuth.js v5
-Gestionnaire de paquets : pnpm
## Commandes courantes
```bash
pnpm dev # Démarrer le serveur de développement (port3000)
pnpm build &&pnpm start # Compiler et démarrer le serveur de production
pnpm test # Exécuter tous les tests
pnpm test:e2e # Exécuter les tests de bout en bout (nécessite de démarrer d'abord le serveur de développement)
pnpm db:migrate # Exécuter les migrations de base de données
pnpm db:studio # Ouvrir Prisma Studio (outil de visualisation de base de données)
pnpm lint &&pnpm typecheck # Vérification du code et des types
```
## Structure du projet
- `src/app/` — Pages de l'App Router et routes API
- `src/app/(dashboard)/` — Pages d'administration nécessitant une connexion
- `src/app/api/` — Routes API (style RESTful)
- `src/components/` — Composants réutilisables
- `src/lib/` — Fonctions utilitaires, client de base de données, configuration d'authentification
- `prisma/schema.prisma` — Définitions du schéma de base de données
## Normes de codage
-Utilisez uniquement des exports nommés (namedexport), les exports par défaut sont interditsdefault export(sauf pour Next.jsfichiers de page)
-Les composants serveur sont asynchrones par défaut ; les composants client ajoutent ` en haut du fichier"use client"`
-Les routes API utilisent un format de réponse unifié : succès `{ data: T }`, échec `{ error: string, code: string }`
-Les requêtes de base de données sont encapsulées dans le répertoire `src/lib/db/` ; n'utilisez pas le client `prisma` directement ailleurs
## Remarques
- `prisma/migrations/Les fichiers existants dans `**ne doivent pas être modifiés**; les modifications de la base de données ne peuvent être effectuées qu'en exécutant `pnpm db:migrate` pour ajouter de nouvelles migrations
- `.env.local` contient de vrais secrets,**Ne lisez ni n'affichez le contenu du fichier**
- `src/lib/auth.ts` est le fichier d'authentification central,**vous devez m'informer avant de le modifier**
-Après avoir modifié `prisma/schema.prisma`, vous devez exécuter `pnpm db:migrate` et committer les fichiers de migration
Questions fréquentes
Q : Et si Claude ne suit pas les règles de CLAUDE.md ?
Tout d'abord, vérifiez si la règle est formulée de manière suffisamment claire (voir la suggestion « utiliser un langage impératif » ci-dessus). Si elle est déjà claire mais toujours pas suivie, vous pouvez la réaffirmer dans la conversation spécifique, ou déplacer la règle vers une position antérieure dans le fichier — Claude accorde plus d'attention au contenu dans la première moitié du fichier.
Q : Un CLAUDE.md plus long est-il préférable ?
Non. Un contenu trop volumineux a deux inconvénients : premièrement, il occupe de l'espace dans la fenêtre de contexte, ce qui réduit la place dont Claude dispose pour traiter les tâches réelles ; deuxièmement, les règles importantes sont noyées dans de grandes quantités de texte et ont moins de chances d'être suivies. Il est recommandé de réviser périodiquement et de supprimer les entrées qui ne sont plus applicables ou qui ont peu de valeur.
Q : Quand le CLAUDE.md d'un sous-répertoire est-il chargé ?
Lorsque Claude ouvre ou modifie un fichier dans ce sous-répertoire, celui du sous-répertoireCLAUDE.mdest automatiquement chargé. Vous n'avez pas besoin de demander manuellement à Claude de le lire ; tout le processus est automatique.
Q : Puis-je référencer un autre CLAUDE.md dans CLAUDE.md ?
Vous ne pouvez pas le référencer directement, mais vous pouvez utiliser@file pathla syntaxe pour référencer le contenu de n'importe quel fichier Markdown. S'il existe des conventions partagées entre les modules, il est recommandé de les extraire dans un fichier de document séparé, puis dans chaqueCLAUDE.mduse@pour y faire référence.