CLAUDE.md : configurer les instructions de Claude Code, avec un exemple

Claude Code sait explorer votre code, mais certaines règles de travail n'y figurent pas : pourquoi l'environnement de test ne doit jamais écrire aux clients, quels dossiers sont générés, quel contrôle confirme qu'une correction a fonctionné. Si vous répétez ces explications à chaque nouvelle tâche, consignez-les dans CLAUDE.md.

CLAUDE.md est un fichier Markdown d'instructions persistantes pour Claude Code. On y range les commandes du projet, les contraintes importantes et les critères de vérification. Un seul fichier à la racine du dépôt suffit pour commencer. La documentation d'Anthropic précise où placer ces fichiers et comment ils sont chargés.

• documentation Anthropic

L'exemple ci-dessous porte sur un petit projet web. Remplacez ses commandes et ses chemins par les vôtres : c'est un modèle pour apprendre, que personne n'a testé sur votre application.

Quelles règles écrire ?

Imaginez qu'il faille ajouter un champ « Entreprise » à un formulaire de demande. Savoir que le projet est en TypeScript n'avance guère l'agent. Il doit trouver le formulaire, comprendre où partent les données et tester l'envoi sans que la demande arrive chez les vrais commerciaux.

Une bonne règle aide à prendre une décision concrète :

La colonne de droite ne vaut pas pour tous les dépôts. Elle est utile parce qu'elle colle à ce projet. Si TextField n'existe pas chez vous, réécrivez la règle, sinon c'est l'instruction elle-même qui produira des erreurs.

Reprenez les remarques que vous avez faites récemment à l'agent. Lesquelles resserviront ? Une exigence qui porte sur un seul bouton reste dans la tâche en cours. Une convention valable pour tous les formulaires a sa place dans les règles du projet.

Où placer CLAUDE.md ?

Placez les règles communes à l'équipe dans `CLAUDE.md`, à la racine du projet. Vos préférences personnelles, valables d'un projet à l'autre, peuvent aller dans `~/.claude/CLAUDE.md`. Les fichiers des sous-dossiers sont chargés lorsque Claude lit des fichiers dans ces dossiers.

• Guide du contexte

Une structure simple pour démarrer :

project/
├── CLAUDE.md
├── README.md
├── package.json
└── src/

Si le fichier existe déjà, commencez par le lire. Deux jeux de règles voisins sont pénibles à entretenir : on met à jour la commande de test dans l'un et on l'oublie dans l'autre.

Vérifiez aussi le nom exact du fichier. Un éditeur qui masque les extensions peut vous laisser un `CLAUDE.md.txt` sans que vous le remarquiez.

Obtenir une première version

Lancez `/init` dans une session Claude Code ouverte. La commande prépare un premier CLAUDE.md à partir du projet. Relisez le résultat : les commandes doivent exister, les chemins être à jour et les contraintes correspondre à votre façon de travailler. Voyez les recommandations d'Anthropic.

• recommandations Anthropic

Pour voir une proposition avant toute modification de fichier, demandez :

Examine README, les scripts de package.json et l'arborescence. Propose un CLAUDE.md avec les commandes de lancement et de vérification, les limites importantes et les particularités impossibles à déduire avec certitude du code. Transforme les inconnues en questions. Ne crée et ne modifie aucun fichier pour l'instant.

Vous obtenez un texte à confronter au dépôt. Ne l'acceptez pas parce qu'il présente bien. `npm test` ne sert à rien si le projet n'a pas ce script.

Exemple pour un projet web

Nous avons écrit ce modèle pour ce guide. Il décrit un site de services fictif qui utilise npm, TypeScript, des dictionnaires de traduction et des tests de formulaire configurés à part. Les noms de commandes et de dossiers ne servent qu'à illustrer la structure ; remplacez-les par ceux de votre projet.

# Projet

Site de services avec formulaire de contact, en russe et en anglais.
Parcours principal : choisir un service et envoyer une demande.

## Où trouver le code
- src/components/forms/ — champs et formulaires.
- src/server/leads/ — traitement des demandes.
- src/i18n/ — dictionnaires de l'interface.
- tests/leads/ — tests du traitement des demandes.

## Commandes
- npm run dev — démarrage local.
- npm run typecheck — vérification des types.
- npm run test:leads — tests des demandes.
- npm run build — compilation de l'application.

## Règles de modification
- Réutiliser les composants de formulaire et gestionnaires d'erreurs.
- Conserver les textes dans les dictionnaires des deux langues.
- Ne pas ajouter de dépendance si les outils du projet suffisent.
- Préserver les modifications inachevées des autres personnes.

## Vérification
- Pour une demande, vérifier champs obligatoires, email invalide
  et envoi réussi vers un destinataire de test.
- Lancer npm run typecheck pour les changements TypeScript.
- Lancer npm run test:leads pour le traitement des demandes.
- Vérifier l'écran concerné dans le navigateur après une modification d'interface.
- Si un contrôle est impossible, indiquer la raison et l'incertitude restante.

## Environnement
- Utiliser uniquement le destinataire de test pour vérifier l'envoi.
- Les noms des variables nécessaires figurent dans .env.example.
- Ne pas copier de secrets dans le code, les rapports ou la documentation.

## Rapport
Décrire brièvement modification, vérifications et problèmes restants.
Séparer résultats des tests et hypothèses sur l'application.

Commencez par vérifier les commandes. Assurez-vous ensuite que les contrôles demandés sont réalisables. Une instruction ne fera pas apparaître un destinataire de test qui n'existe pas : préparez l'environnement de test ou décrivez une autre vérification possible.

Vous n'avez pas besoin de toutes les sections. Pour une bibliothèque, ce sont l'API publique et la compatibilité qui comptent. Pour un site d'articles, la structure du contenu, les métadonnées et les liens internes.

Vérifier l'utilité des instructions

Il y a là deux questions distinctes : le fichier a-t-il été chargé, et le comportement de l'agent a-t-il changé ?

Lancez `/context` et cherchez votre fichier sous Memory files. Confiez ensuite à l'agent une petite tâche au résultat clair. Anthropic recommande expressément cette façon de vérifier le chargement.

• Configuration de CLAUDE.md

Pour le site de l'exemple :

Ajoute un champ facultatif « Entreprise » au formulaire. Avant de modifier, trouve le composant existant et le gestionnaire d'envoi. Vérifie ensuite l'envoi avec et sans entreprise. Liste seulement les contrôles réellement effectués.

Regardez ensuite trois points :

1. Le composant prévu et les dictionnaires ont-ils été utilisés ?
2. L'envoi sans ce champ fonctionne-t-il toujours ?
3. Les résultats annoncés correspondent-ils aux sorties des outils ?

Si l'un des trois points pèche, cherchez pourquoi. La règle est peut-être ambiguë. Le code contient peut-être un second gestionnaire qui ressemble au premier. Les tests ne couvrent peut-être pas le scénario. N'ajoutez une interdiction qu'après avoir compris ce qui a échoué.

Pour vos observations, un petit tableau suffit : la tâche, l'action attendue, le résultat obtenu, la règle corrigée. C'est une méthode que nous proposons ; nous ne rendons pas compte ici d'une expérience. Un essai réussi ne prouve pas que la règle sera toujours suivie.

Si Claude ignore CLAUDE.md

Confirmez d'abord que le bon fichier est chargé. Cherchez ensuite, ailleurs dans le projet, des consignes sur le même sujet. D'après la documentation, tous les CLAUDE.md découverts sont réunis dans le contexte ; un fichier imbriqué n'annule donc pas automatiquement les règles posées plus haut.

• Ordre de chargement

Regardez ensuite la formulation. « Teste soigneusement » laisse trop de latitude à l'agent. « Lance telle commande après avoir modifié le gestionnaire de demandes » désigne une action dont on voit le résultat.

L'instruction est peut-être tout simplement périmée. Quand les tests déménagent ou que l'arborescence change, relisez les règles qui s'y rapportent. Un agent ne peut pas grand-chose d'un document qui décrit un projet disparu.

Enfin, supprimez les répétitions et les vœux généraux. Anthropic conseille des consignes courtes, propres au projet, et révisées au fil du travail. Aucune longueur de fichier ne garantit qu'elles seront respectées.

• Conseils de rédaction

Quand utiliser rules et Skills ?

Quand le projet grandit, répartissez les instructions selon leur rôle. `.claude/rules/` accueille des règles thématiques, y compris des règles liées à certains chemins. Les Skills conviennent aux procédures répétables dont on n'a besoin que dans certaines situations.

• Règles
• Skills

Les instructions deviennent plus faciles à entretenir : quand la préparation d'une version change, vous n'avez pas à réécrire chaque scénario. Mais découper en fichiers ne rend pas les règles plus précises. Les contradictions restent à résoudre sur le fond.

CLAUDE.md ne remplace pas les permissions

« N'écris pas à de vrais clients » décrit utilement une façon de travailler. Les restrictions techniques, elles, se configurent à part. Claude Code propose `/permissions` et les règles allow, ask et deny, et rien de ce que vous écrivez dans CLAUDE.md ne les modifie.

• Gestion des permissions

Pour l'exemple du formulaire, configurez l'environnement de test de sorte que les envois partent réellement vers un destinataire de test. Le bon destinataire ne dépend plus alors de la lecture que l'agent fait d'un paragraphe.