Règles de Claude Code : Comment écrire CLAUDE.md et gérer le contexte de codage agentique

Les règles de Claude Code résident dans les fichiers CLAUDE.md — des fichiers Markdown que vous placez dans votre dépôt projet, votre répertoire personnel ou la configuration de votre organisation, que Claude lit au début de chaque session. Combinées à des règles limitées par chemin dans .claude/rules/, à un settings.json pour les permissions, et à une mémoire automatique pour les préférences apprises, le système de règles vous offre un contrôle précis et persistant sur la manière dont l’agent de codage se comporte dans n’importe quelle tâche.

Que sont les règles de Claude Code ?

Chaque session Claude Code commence avec une fenêtre de contexte vide. Les règles sont la façon dont vous préchargez le contexte dont Claude a besoin pour ne pas repartir de zéro — ou refaire la même erreur.

Deux systèmes complémentaires gèrent cela :

Les fichiers CLAUDE.md sont des fichiers Markdown que vous écrivez et que Claude lit au début de chaque session. Utilisez-les pour des instructions qui doivent toujours s’appliquer : commandes de build, conventions de code, décisions d’architecture, contraintes strictes.

La mémoire automatique sont des notes que Claude écrit lui-même en fonction des corrections et préférences que vous lui donnez pendant les sessions. Elles s’accumulent automatiquement ; Claude décide ce qui mérite d’être conservé et relit ces notes lors des futures sessions.

Les deux se chargent dans le contexte au début de la session, mais ce ne sont pas des configurations imposées. Ce sont des instructions que Claude suit comme contexte. Pour une application stricte — bloquer une commande spécifique quoi que Claude décide de faire — vous avez besoin d’un PreToolUse hook ou d’une règle deny dans settings.json. La distinction est importante pour les exécutions autonomes où vous voulez un comportement prédictible, pas une conformité probabilitiste.

Emplacements et portée des fichiers CLAUDE.md

Claude Code charge les fichiers CLAUDE.md depuis plusieurs emplacements, chacun couvrant une portée différente. Ils se chargent dans l’ordre du plus large au plus spécifique :

Emplacement	Portée	Utilité
~/.claude/CLAUDE.md	Tous les projets sur votre machine	Préférences personnelles, habitudes de worklflow globales
./CLAUDE.md (racine du dépôt)	Toutes les sessions dans ce projet	Conventions du projet, commandes de build, règles partagées par l’équipe
./CLAUDE.local.md (racine du dépôt)	Uniquement vos sessions locales	Préférences par dévelopeur ; ajouter à .gitiignore
./src/CLAUDE.md (sous-répertoire)	Sessions touchant des fichiers dans ce répertoire	Règles spécifiques au module qui ne s’appliquent pas à tout le projet

Tous les fichiers découverts sont concaténés dans le contexte — ils ne se remplacent pas mutuellement. Dans cette concaténation, le contenu du système de fichiers racine jusqu’à votre répertoire de travail est ordoné du plus large au plus spécifique, donc une instruction de projet apparaît après une instruction utilisteur. Cela donne une natuelité naturelle : une règle de projet l’emporte là où elle entre en conflict avec une règle de niveau utilsateur.

Vous pouvez importer des fichiers supplémentaires avec des références @path dans n’importe quel CLAUDE.md :

@./docs/architecture.md
@./CONTRIBUTING.md

Les fichiers importés se chargent au début de la session, tout comme le CLAUDE.md lui-même. Les imports sont utiles pour l’organisation mais n’économisent pas de contexte — le contenu importé compte dans votre budget de tokens.

Pour les équipes : commitez le CLAUDE.md du projet dans le contrôle de source. Cela garantit que toutes les sessions Claude de chaque développeur — et toutes les exécutions d’agents basées sur CI — commencent avec le même contexte partagé. Traitez-le comme .eslintrc ou pyproject.toml.

Que mettre dans CLAUDE.md

Le contenu le plus utile est ce que vous réexpliqueriez sinon à chaque session, ou ce qu’un nouveau membre de l’équipe aurait besoin de savoir dans sa première heure.

Bons candidats :

• Les commandes de build et de test qui diffèrent des valeurs par défaut évidentes (./scripts/test.sh --ci, pas seulement npm test)
• Les conventions de code non capturées par le linter (“nous utilisons des exports nommés partout ; pas d’exports par défaut dans les utilitaires partagés”)
• Les décisions d’architecture qui ne sont pas évidentes en lisant le code (“le répertoire lib/ est partagé entre les services — n’y ajoutez pas de logique spécifique à un service”)
• Les pièges connus (“le fichier config.ts est généré lors du build ; ne le modifiez pas manuellement”)
• Les contraintes de workflow (“toujours créer une branche avant de faire des modifications ; pousser vers le remote avant d’ouvrir une PR”)

Choses à laisser de côté :

• Listes de répertoires et arborescences de fichiers — Claude les lit depuis le dépôt
• Listes de dépendences — disponibles dans package.json, pyproject.toml, etc.
• Descriptions en prose de ce que fait le code existant — Claude lit le code source directement
• Modifications récentes — Claude utilise git log et git diff quand il a besoin de l’historique

Gardez CLAUDE.md concentré sur ce qui ne peut pas être dérivé de la lecture du codebase. Les fichiers de plus de 200 lignes consomment plus de contexte et réduisent la fiabilité de l’observance. La commande /doctor dans Claude Code audite un CLAUDE.md commité et suggère de supprimer le contenu dérivable du code — un moyen utile de réduire un fichier trop volumineux.

Écrire des règles efficaces

La spécificité compte. Comparez :

# Vague — moins cohérent
Suivez les normes de codage du projet.

# Spécifique — plus cohérent
- Utilisez pnpm, pas npm ou yarn
- Lancez pnpm test avant chaque commite ; ne commitez pas si les test échouent
- Exportez tous les types partagés depuis src/types/index.ts — ne définissez pas les types en ligne dans les fichiers des composants
- Le répertoire data/ est en lecture seule dans les test ; utilisez les fixtures de test depuis tests/fixtures/ à la place

Chaque règle doit être actionable sans explication supplémentaire. Si vous deviez expliquer le raisonnement d’une règle à quelqu’un, ajoutez le raisonnement en ligne — cela aide Claude à appliquer la règle coreectement dans les cas limites.

Règles limitées par chemin avec .claude/rules/

Le répertoire .claude/rules/ vous permet d’attacher des règles à des motifs de fichiers spécifiques sans les charger dans chaque session. Claude découvre les fichiers dans .claude/rules/ et les charge quand vous travaillez avec des fichiers correspondants.

Une structure typique pour un monorepo TypeScript :

.claude/rules/
  api.md             # règles pour src/api/** — validation des requêtes, formats d'erreur
  components.md      # règles pour src/components/** — types de props, conventions de style
  tests.md           # règles pour tests/** — motifs de fixtures, configuration des mocks
  database.md        # règles pour migrations/ et models/ — nommage des migrations, motifs de requêtes

Chaque fichier de règle utilise un frontmatter YAML avec un champ paths pour contrôler quand il se charge :

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

# Règles de développement API

- Tous les gestionnaires de route doivent valider les entrées avec zod avant toute logique métier
- Renvoyer les erreurs sous la forme `{ error: string; code: string }` — jamais de chaînes simples
- Le limitage de débit est appliqué à la passerelle ; ne l'ajoutez pas à l'intérieur des gestionnaires

Les règles sans champ paths se chargent sans condition au début de la session, comme le contenu du CLAUDE.md du projet. Les règles avec paths se chargent uniquement lorsque Claude ouvre des fichiers correspondant à ces motifs.

Cela permet de garder le CLAUDE.md racine du projet concis et garantit que les conventions détaillées pour une couche de la stack ne remplissent pas le contexte pendant les sessions axées sur un domaine différent.

settings.json vs CLAUDE.md

CLAUDE.md contrôle ce que Claude sait et a l’intention de faire. settings.json contrôle ce que Claude est réellement autorisé à faire.

	CLAUDE.md	settings.json
Objectif	Instructions et contexte	Permissions et configuration
Appliqué ?	Non — Claude agit en tant que guide	Oui — les règles deny bloquent les appels d’outils sans condition
Format	Markdown libre	JSON structuré
Emplacement	./CLAUDE.md, ~/.claude/CLAUDE.md	.claude/settings.json, ~/.claude/settings.json

Un settings.json de projet à .claude/settings.json :

{
  "permissions": {
    "allow": [
      "Bash(pnpm test)",
      "Bash(pnpm build)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)"
    ]
  }
}

La liste allow pré-approuve des commandes spécifiques pour que Claude puisse les exécuter sans demande. Cela accélère les sessions interactives pour les opérations auxquelles vous faites confiance. La liste deny bloque les commandes sans condition — quoi que Claude décide de faire, quoi que dise CLAUDE.md. Utilisez deny pour les opérations irréversibles sur les données de production ou l’infrastructure.

Les paramètres au niveau de l’utilisateur à ~/.claude/settings.json s’appliquent à tous les projets. Les paramètres de projet à .claude/settings.json s’appliquent uniquement dans ce dépôt. Les paramètres de projet prennent le pas sur les paramètres utilisateur là où ils se chevauchent.

Si votre équipe a également besoin d’une référence de packaging pour les outils MCP, et pas seulement de règles pour les gouverner, associez ces garde-fous au guide de documentation des plugins Claude Code. Il explique où un plugin MCP se situe par rapport aux règles, hooks et config autonome.

Mémoire automatique : les notes de Claude

La mémoire automatique est le pendant de CLAUDE.md. Alors que CLAUDE.md est des instructions que vous écrivez, la mémoire automatique est des notes que Claude écrit lui-même en fonction de ce qu’il apprend pendant vos sessions.

Lorsque vous coreigez Claude pendant une session — “nous utilisons Vitest, pas Jest dans ce projet” — il peut sauvegarder cela comme une note dans ~/.claude/projects/<repo>/memory/. La session suivante, Claude lit cette note et applique la corection sans avoir à la réexpliquer.

Le répertoire de mémoire contient :

~/.claude/projects/<repo>/memory/
  MEMORY.md          # index que Claude utilise pour trouver d'autres fichiers ; les 200 prenières lignes se chargent à chaque session
  debugging.md       # motifs que Claude a découverts en résolvant des problèmes dans ce dépôt
  conventions.md     # conventions que Claude a apprises de vos corections

C’est local à la machine et par dépôt. La mémoire automatique complète CLAUDE.md plutôt que de le rempalcer : CLAUDE.md est pour les règles de projet partagées par l’équipe ; la mémoire automatique est pour les modèles personnels que Claude a appris en travaillant avec vous.

La mémoire automatique est un markdown lisible que vous pouvez modifier ou supprimer à tout moment. Exécutez /memory dans une session pour parcourir et modifier les fichiers. Si quelque chose est obsolète ou erroné, supprimez-le — Claude cessera d’appliquer la règle obsolète.

Bonnes pratiques pour le codage agentique

Exécuter Claude Code de manière autonome — via claude -p, le SDK Agent, ou des pipelines CI — augmente les enjeux pour votre configuration de règles. L’agent peut effectuer des dizaines d’appels d’outils sans pause, et il n’y a pas d’échanges interactifs pour rattraper les malentendus en cours de route.

Écrivez des contraintes explicites, pas seulement des préférences. Claude interactif peut vous demander de clarifier. Une exécution autonome travaille avec ce qu’elle trouve dans le contexte. Si “ne jamais modifier les fichiers de migration sans d’abord créer un instantané de la base de données” est important, cela doit être dans CLAUDE.md. Ne supposez pas que Claude inférera la contrainte à partir de la structure du codebase.

Utilisez des règles deny pour tout ce qui est difficile à annuler. Pré-approuver Bash(pnpm build) accélère les sessions interactives et présente peu de risques. Mais pour les exécutions autonomes, la liste deny est votre filet de sécurité pour les opérations qui touchent à l’infrastructure de production, committent de manière permanente dans l’historique git, ou suppriment des données.

Gardez le CLAUDE.md du projet dans le contrôle de version. Un CLAUDE.md commité à la racine du dépôt s’applique de manière cohérente aux sessions interactives, aux exécutions CI, et à l’agent local de tout membre de l’équipe. C’est le bon endroit pour les règles qui définissent ce que “correct” signifie pour votre codebase.

Utilisez .claude/rules/ pour du contenu spécifique à un domaine. Si votre projet a des couches distinctes — composants frontend, API backend, schéma de base de données, scripts d’infrastructure — mettez les règles pour chaque couche dans .claude/rules/ avec une portée par chemin. Un seul CLAUDE.md de 400 lignes contenant tout est plus difficile à naviguer pour Claude et coûte plus de contexte par session.

Déplacez le matériel de référence vers les compétences. Les compétences (.claude/skills/) se chargent à la demande, pas au début de la session. Les longues documentations d’API, les procédures de déploiement en plusieurs étapes et les guides de dépannage appartiennent aux compétences que vous invoquez avec /deploy ou /debug — pas dans CLAUDE.md où elles consomment du contexte même lorsqu’elles ne sont pas pertinentes.

Vérifiez régulièrement la mémoire automatique. La mémoire automatique s’accumule avec le temps. Les commandes de build changent, les conventions sont refactorisées, les motifs de test évoluent. Une note de mémoire obsolète qui dit “utilisez le client API v1” alors que vous avez migré vers v2 provoquera des bugs subtils dans les exécutions autonomes. Auditez ~/.claude/projects/<repo>/memory/ lorsque vous apportez des modifications significatives à la structure du projet.

Utiliser des modèles open-source avec votre configuration de règles

Le contexte CLAUDE.md et les .claude/rules/ que vous avez construits fonctionnent de la même manière quel que soit le modèle qui effectue l’inférence. Une fois vos règles écrites, changer de backend de modèle préserve tout — et les modèles open-source via l’API LLM de Novita AI sont une option pratique pour le travail agentique à volume élevé.

La configuration est une variable d’environnement :

export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_AUTH_TOKEN="<votre-clé-api-novita>"
export ANTHROPIC_MODEL="qwen/qwen3-coder-480b-a35b-instruct"

Avec ANTHROPIC_BASE_URL pointant vers Novita AI, Claude Code envoie toutes les requêtes d’inférence vers le point de terminaison compatible Anthropic de Novita au lieu de api.anthropic.com. Votre CLAUDE.md, vos règles limitées par chemin et votre settings.json s’appliquent exactement comme avant — la couche de règles est en amont de la sélection du modèle.

Novita AI héberge des modèles open-weight axés sur le codage, notamment Qwen3-Coder, GLM-4.7, MiniMax M2.5 et DeepSeek V4. Ces modèles sont optimisés pour l’utilisation d’outils en plusieurs étapes et l’appel de fonctions, ce qui correspond bien aux schémas d’appel d’outils que Claude Code utilise en interne pour les modifications de fichiers, les commandes shell et la navigation dans les dépôts.

Pour les équipes exécutant des tâches agentiques à grande échelle — pipelines de révision de code, refactoring automatisé dans de grands dépôts, génération de tests — les modèles open-weight chez Novita coûtent généralement beaucoup moins cher par million de tokens que les alternatives propriétaires, tout en lisant et en appliquant efficacement les règles de votre projet.

Si vous exécutez des agents sur une base de code de production et souhaitez une couche de sécurité supplémentaire au-delà des règles deny, envisagez de combiner l’API LLM de Novita avec le bac à sable Agent de Novita. Le bac à sable offre à l’agent un environnement Linux complet pour les opérations sur les fichiers et l’exécution de commandes, isolé de votre système hôte. Votre contexte CLAUDE.md accompagne la tâche ; le risque d’exécution reste contenu.

FAQ

Qu’est-ce que CLAUDE.md dans Claude Code ?

CLAUDE.md est un fichier Markdown qui donne à Claude Code des instructions persistantes entre les sessions. Il se charge au début de la session afin que Claude n’ait pas besoin de réapprendre vos conventions de projet à chaque fois. Vous pouvez avoir des fichiers CLAUDE.md à plusieurs niveaux : niveau utilisateur (~/.claude/CLAUDE.md) pour les préférences personnelles qui s’appliquent partout, niveau projet (racine du dépôt) pour les règles partagées par l’équipe et versionnées, et niveau sous-répertoire pour les règles spécifiques à un module.

Que dois-je mettre dans les fichiers de règles claude ?

Écrivez ce que vous réexpliqueriez autrement à chaque session : commandes de build et de test, conventions de codage qui diffèrent des valeurs par défaut du framework, contraintes d’architecture et pièges connus du codebase. Laissez de côté le contenu que Claude peut dériver du codebase lui-même — arborescences de fichiers, listes de dépendances et descriptions de ce que fait le code existant. Gardez les fichiers sous 200 lignes pour une observance cohérente.

Quelle est la différence entre CLAUDE.md et settings.json dans Claude Code ?

CLAUDE.md est des instructions que Claude suit comme guide. settings.json est une configuration que Claude Code applique au niveau système. Une règle dans CLAUDE.md façonne ce que Claude a l’intention de faire ; une entrée deny dans settings.json bloque un appel d’outil sans condition. Pour tout ce qui ne doit pas arriver quoi que Claude décide — suppressions irréversibles, force pushes, opérations sur l’environnement de production — utilisez settings.json, pas CLAUDE.md.

Qu’est-ce que le répertoire .claude/rules/ ?

.claude/rules/ contient des fichiers de règles limitées par chemin qui se chargent uniquement lorsque Claude travaille avec des fichiers correspondant à la portée de la règle. Cela permet d’écrire des règles détaillées et spécifiques à un domaine sans les charger dans chaque session. Les règles sont des fichiers Markdown avec un frontmatter YAML optionnel spécifiant des motifs glob paths. Les règles sans frontmatter paths se chargent sans condition au début de la session, comme du contenu CLAUDE.md supplémentaire.

CLAUDE.md fonctionne-t-il dans les tâches CI et Claude Code automatisées ?

Oui. Toute invocation claude -p, appel au SDK Agent ou pipeline CI s’exécutant dans un répertoire de dépôt charge le CLAUDE.md du projet. Cela rend CLAUDE.md efficace pour imposer un comportement cohérent dans des contextes interactifs et automatisés. Le commiter dans le contrôle de version garantit que chaque exécution — locale et CI — commence avec le même contexte partagé.

Comment fonctionne le contexte de Claude Code et comment le gérer ?

Le contexte est le budget de tokens pour la session en cours. Les fichiers CLAUDE.md, les références importées, la mémoire automatique et l’historique de la conversation comptent tous dans ce budget. Gérez-le en gardant CLAUDE.md concis, en utilisant .claude/rules/ pour charger le contenu du domaine uniquement lorsqu’il est pertinent, et en utilisant /compact pour résumer les longues sessions sans perdre la continuité. Après /compact, Claude relit le CLAUDE.md racine du projet depuis le disque et le réinjecte automatiquement dans la session.

Comment utiliser les meilleures pratiques de Claude Code pour le codage agentique dans une équipe ?

Commitez le CLAUDE.md du projet dans votre dépôt pour que tous les membres de l’équipe et les agents CI partagent les mêmes règles. Utilisez .claude/rules/ avec une portée par chemin pour le contenu spécifique à un domaine. Ajoutez des règles deny à .claude/settings.json pour les opérations qui ne doivent jamais s’exécuter dans des contextes automatisés. Gardez la mémoire automatique hors de la CI — elle est locale à la machine et par développeur ; le CLAUDE.md commité est la source de vérité pour le comportement partagé.

Novita AI est une plateforme cloud d’IA qui offre aux développeurs un moyen simple de déployer des modèles d’IA via notre API simple, tout en fournissant également un cloud GPU abordable et fiable pour construire et passer à l’échelle.

Articles recommandés

• Comment utiliser les agents Claude Code : Configuration, outils, permissions et workflow de bac à sable
• Plugins Claude Code : Comment les outils MCP étendent Claude Code avec des capacités externes
• Documentation CLI Claude Code : Configuration, commandes slash et intégration API LLM
• SDK Claude Code : Construire des agents autonomes avec Python et TypeScript
• Construire un agent de codage avec le bac à sable Agent de Novita

---

Sources vérifiées le 21 juillet 2026 : Docs mémoire Claude Code, Aperçu des fonctionnalités Claude Code, API LLM Novita AI