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

Claude Code peut explorer le code, mais certaines règles de travail n'y figurent pas : pourquoi l'environnement de test ne doit pas écrire aux clients, quels dossiers sont générés, ou quelle vérification confirme une correction. Si vous répétez ces explications à chaque tâche, consignez-les dans CLAUDE.md.

CLAUDE.md est un fichier Markdown d'instructions persistantes pour Claude Code. Il accueille commandes, contraintes importantes et critères de vérification. Un fichier à la racine du dépôt suffit pour commencer. La documentation Anthropic explique les emplacements et le chargement.

• documentation Anthropic

L'exemple concerne un petit projet web. Adaptez commandes et chemins : c'est un modèle pédagogique, pas une configuration testée sur votre application.

Quelles règles écrire ?

Imaginez l'ajout d'un champ « Entreprise » à un formulaire. Savoir que le projet utilise TypeScript ne suffit pas. L'agent doit trouver le formulaire, comprendre le traitement des données et tester l'envoi sans contacter les commerciaux.

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

La colonne de droite n'est pas universelle. Si TextField n'existe pas, adaptez la règle ; sinon elle créera elle-même des erreurs.

Reprenez vos remarques récentes à l'agent. Lesquelles serviront encore ? Une exigence sur un bouton précis reste dans la tâche. Une convention pour tous les formulaires rejoint les règles du projet.

Où placer CLAUDE.md ?

Placez les règles partagées dans `CLAUDE.md` à la racine. Les préférences personnelles générales peuvent aller dans `~/.claude/CLAUDE.md`. Les fichiers des sous-dossiers sont chargés lorsque Claude y lit des fichiers. Guide du contexte.

• Guide du contexte

Structure de départ :

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

Si le fichier existe, lisez-le d'abord. Des règles en double compliquent la maintenance : une commande peut être actualisée d'un côté et oubliée de l'autre.

Vérifiez aussi le nom exact. Un éditeur masquant les extensions peut créer accidentellement `CLAUDE.md.txt`.

Obtenir une première version

Lancez `/init` dans une session Claude Code. La commande aide à préparer un fichier à partir du projet. Relisez-le : commandes existantes, chemins actuels et contraintes adaptées. Voir les recommandations Anthropic.

• recommandations Anthropic

Pour obtenir une proposition sans toucher aux fichiers :

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. Sa présentation soignée ne suffit pas : `npm test` ne sert à rien si ce script n'existe pas.

Exemple pour un projet web

Ce modèle pédagogique original suppose un site de services utilisant npm, TypeScript, des dictionnaires de traduction et des tests de formulaire configurés séparément. Les noms illustrent la structure ; remplacez-les par les vôtres.

# 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 les commandes, puis vérifiez la faisabilité des contrôles. Une instruction ne crée pas un destinataire de test absent : préparez l'environnement ou documentez une autre vérification possible.

Tous les blocs ne sont pas indispensables. Pour une bibliothèque, privilégiez API publiques et compatibilité ; pour un site éditorial, structure du contenu, métadonnées et liens internes.

Vérifier l'utilité des instructions

Distinguez le chargement du fichier et l'effet sur le comportement.

Lancez `/context`, puis consultez Memory files. Confiez ensuite une petite tâche au résultat clair. Anthropic recommande cette vérification du chargement. Configuration de CLAUDE.md.

• Configuration de CLAUDE.md

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.

Examinez 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 ?

En cas d'écart, cherchez la cause : règle ambiguë, second gestionnaire ressemblant au premier, tests incomplets. Ajoutez une interdiction après avoir compris l'échec.

Un tableau tâche, action attendue, résultat et règle corrigée suffit pour vos observations. C'est une méthode proposée, pas un compte rendu d'expérience. Une réussite ne garantit pas les suivantes.

Si Claude ignore CLAUDE.md

Confirmez d'abord le chargement, puis cherchez les consignes du même sujet ailleurs. Les fichiers découverts sont réunis dans le contexte ; un fichier imbriqué n'annule pas automatiquement toutes les règles précédentes. Ordre de chargement.

• Ordre de chargement

Examinez ensuite la formulation. « Teste soigneusement » laisse beaucoup de choix. Une commande précise après modification du gestionnaire décrit une action observable.

L'instruction peut être périmée. Après déplacement des tests ou réorganisation, relisez les règles concernées. Un document décrivant un ancien projet est difficile à suivre.

Supprimez enfin répétitions et souhaits généraux. Anthropic conseille des consignes courtes, pertinentes et révisées au fil du travail. Aucune longueur universelle ne garantit leur respect. Conseils de rédaction.

• Conseils de rédaction

Quand utiliser rules et Skills ?

Séparez les instructions selon leur rôle. `.claude/rules/` accueille des règles thématiques, éventuellement liées à des chemins. Les Skills conviennent aux procédures récurrentes nécessaires selon la situation. Règles, Skills.

• Règles
• Skills

La maintenance devient plus simple. Modifier la préparation d'une version ne demande pas de réécrire chaque scénario. La séparation seule ne résout toutefois pas les contradictions.

CLAUDE.md ne remplace pas les permissions

« Ne contacte pas de vrais clients » est une consigne utile ; les restrictions techniques se règlent séparément. Claude Code propose `/permissions` et les règles allow, ask, deny. CLAUDE.md ne les modifie pas. Gestion des permissions.

• Gestion des permissions

Pour le formulaire, configurez l'environnement pour diriger effectivement les envois vers le destinataire de test. Le choix du destinataire ne dépendra pas uniquement de l'interprétation d'un paragraphe.