Accéder au contenu principal

Un auto-entrepreneur passionné à votre service,

Pour votre projet de site internet et vos dépannages informatiques

CLAUDE.md et AGENTS.md : les meilleures pratiques pour un meilleur code avec un agent IA

Publié le 15 Juin 2026, dernière mise à jour le 7 Juin 2026

Quelques lignes bien placées dans un fichier de configuration suffisent à transformer radicalement la qualité du code produit par un agent IA. Depuis que j'utilise Claude Code et d'autres agents de codage, j'ai pu mesurer à quel point un fichier CLAUDE.md ou AGENTS.md bien rédigé fait la différence entre un assistant générique et un véritable partenaire de développement, parfaitement calibré sur mon projet. Dans cet article, je vous partage ma méthode, les pièges à éviter absolument, et un modèle concret prêt à adapter.

Qu'est-ce que CLAUDE.md et AGENTS.md ?

Avant tout, il convient de bien distinguer ces deux fichiers, qui partagent le même objectif mais s'adressent à des écosystèmes différents.

CLAUDE.md est un fichier Markdown spécifique à Claude Code, l'agent de codage en ligne de commande développé par Anthropic. Comme le précise la documentation officielle, Claude Code le lit automatiquement à l'ouverture de chaque session de travail. Inutile de le mentionner dans vos prompts : il est chargé en arrière-plan, invisible mais actif, dès le démarrage.

AGENTS.md, quant à lui, est devenu un standard ouvert de la profession. Initialement popularisé par OpenAI avec son agent Codex, il a depuis été adopté comme norme par l'Agentic AI Foundation (un fonds hébergé par la Linux Foundation, dont Anthropic et OpenAI sont membres fondateurs). En juin 2026, AGENTS.md est reconnu par plus de 60 000 dépôts open source et lu nativement par la quasi-totalité des agents de code du marché : Cursor, Aider, Jules, Factory, GitHub Copilot, Windsurf, Gemini CLI, et bien d'autres.

En résumé : si vous utilisez exclusivement Claude Code, privilégiez CLAUDE.md. Si votre équipe jongle entre plusieurs agents ou si vous souhaitez adopter un format universel, AGENTS.md est la solution la plus pérenne. Les deux approches sont d'ailleurs cumulables : il est possible d'importer votre AGENTS.md dans votre CLAUDE.md via la syntaxe @AGENTS.md.

Dans cet article, les conseils s'appliquent indifféremment aux deux fichiers. Pour simplifier la lecture, j'utiliserai principalement le terme CLAUDE.md, mais tout ce qui est dit ici vaut pour AGENTS.md.

Pourquoi un agent de code a-t-il besoin d'un tel fichier ?

Un agent de code comme Claude Code n'a aucune mémoire persistante entre les sessions. À chaque démarrage, il repart de zéro : il ne connaît pas votre stack technique, vos conventions maison, la charte graphique de votre projet, ni les erreurs récurrentes à éviter. Sans instructions explicites, il produira du code correct mais générique, loin de refléter les spécificités et les standards de votre environnement.

Une bonne analogie consiste à imaginer que vous réembauchez un développeur senior expérimenté chaque matin, mais sans jamais lui remettre le dossier de présentation du projet. Il travaillera bien, mais pas forcément comme vous le souhaitez. Le fichier CLAUDE.md est précisément ce dossier d'onboarding : il contextualise chaque session dès le départ, sans effort de votre part.

Pour les néophytes : un "agent de code" est un programme d'intelligence artificielle capable de lire votre code source, de modifier des fichiers, d'exécuter des commandes dans un terminal et de résoudre des problèmes de développement en autonomie, sur simple instruction en langage naturel.

Un fichier rédigé en langage naturel : les règles de base

La première règle, et peut-être la plus importante : CLAUDE.md se rédige entièrement en langage naturel, comme un document ordinaire. Pas de syntaxe spéciale, pas de balises complexes. Le Markdown suffit pour la structuration.

Anthropic recommande de le garder court et de le structurer en sections thématiques claires. Un fichier trop long noie l'agent dans des informations inutiles et dilue l'efficacité des instructions importantes. Les consignes générales, celles qui s'appliquent à l'ensemble du projet, sont les seules à y figurer. Pour des règles spécifiques à un sous-projet ou à un répertoire particulier, la bonne pratique consiste à créer des fichiers CLAUDE.md imbriqués directement dans les sous-dossiers concernés (les agents respectent un principe dit "nearest-file-wins", c'est-à-dire qu'ils appliquent les instructions du fichier le plus proche dans l'arborescence).

Si vous constatez que certaines de vos instructions ne sont pas respectées par l'agent, deux causes reviennent systématiquement :

  • Le fichier est trop long : réduisez-le à l'essentiel. Supprimez les informations redondantes ou que l'agent peut déduire lui-même en lisant votre code.
  • Les instructions sont imprécises ou ambiguës : reformulez-les de manière directe et sans équivoque.

Pour les règles absolument critiques, Anthropic conseille d'utiliser des marqueurs d'emphase pour les faire ressortir dans le fichier. Des formulations comme TRÈS IMPORTANT ou VOUS DEVEZ ABSOLUMENT FAIRE X permettent à l'agent de hiérarchiser ses priorités et d'adhérer plus fermement aux consignes essentielles. C'est ce que l'on appelle dans le jargon la prompt adherence, soit la capacité du modèle à suivre fidèlement les instructions données.

Enfin, et c'est un conseil qui me semble fondamental : traitez votre CLAUDE.md comme du code. Modifiez-le, testez son effet dans Claude Code, observez les résultats, itérez. C'est à ce prix que vous obtiendrez un fichier vraiment performant.

Ce qu'il ne faut absolument pas mettre dans CLAUDE.md

La liste des instructions à bannir est longue, et elle m'a surpris au début. Voici ce que j'ai appris à ne plus écrire.

Les consignes trop générales ou évidentes
Inutile d'écrire des choses que l'agent peut inférer de lui-même en analysant votre code. Si vous utilisez React, il le verra. Si votre projet est en TypeScript, il le détectera. N'expliquez pas ce qui est visible.
Les conventions de codage standard
Les bonnes pratiques universelles (indentation, nommage des variables, commentaires…) sont déjà connues de l'agent par défaut. Les répéter ne fait qu'alourdir le fichier.
Le fonctionnement d'une API ou d'un service largement documenté
Inutile de réexpliquer le fonctionnement de l'API de Stripe ou les bases de SQL. L'agent les connaît. Concentrez-vous sur ce qui est propre à votre projet.
Les informations susceptibles de changer en cours de projet
C'est un piège classique : si vous ajoutez une information dynamique (numéro de version en cours de développement, fonctionnalité temporairement désactivée…), vous risquez de l'oublier dans le fichier, mais pas l'agent, qui continuera à l'appliquer.
Les tutoriels et longues explications de code
Le fichier n'est pas un manuel. Restez concis. Pointez vers la documentation si nécessaire, mais ne la reproduisez pas.
Les formulations prescriptives rhétoriques et vides de sens
C'était un conseil largement répandu, même chez certains éditeurs, mais il est désormais clairement contreproductif. Exit les "Rédige du code propre", "ne fais aucune erreur", "n'oublie pas de commenter le code"… Ces instructions n'apportent rien que l'agent ne ferait pas déjà. Elles encombrent inutilement le contexte.

Ce qu'il faut impérativement inclure

La règle d'or : ajoutez uniquement ce que l'agent ne peut pas deviner seul. Voici les catégories d'instructions réellement utiles, tirées de mon expérience terrain.

Les commandes bash spécifiques à votre projet
La commande pour lancer les tests, démarrer le serveur de développement, builder le projet, lancer les migrations… Toutes ces commandes propres à votre environnement doivent figurer dans le fichier. L'agent pourra les exécuter sans avoir à vous les demander.
Les conventions de codage et de nommage propres à votre organisation
Si votre équipe a adopté des règles de nommage spécifiques — par exemple, tous les composants React en PascalCase avec le suffixe Component, ou toutes les fonctions utilitaires préfixées par utils_ — précisez-les explicitement. Ce sont exactement le type d'informations "impossibles à deviner" mentionnées dans la documentation de Claude Code.
La charte graphique
Sans instructions explicites, un agent génère des designs génériques, souvent peu cohérents avec votre identité visuelle. Indiquez votre palette de couleurs (en codes hexadécimaux), vos typographies, vos espacements et vos composants UI de référence.
Les règles de sécurité internes
Interdictions absolues à rappeler : ne jamais écrire de tokens d'API ou de secrets en dur dans le code, toujours utiliser des variables d'environnement, ne jamais logger des données sensibles… Ces règles critiques méritent les marqueurs d'emphase évoqués plus haut.
L'environnement de développement atypique
Si votre projet tourne sur un VPS avec des contraintes de RAM spécifiques, si vous utilisez des versions fixées de Node.js ou Python, ou si vous avez des contraintes réseau particulières (proxy d'entreprise, restrictions de ports…), documentez-le.
Les choix architecturaux non conventionnels
Vous utilisez une architecture hexagonale alors que votre stack suggérerait plutôt du MVC standard ? Votre state management repose sur un pattern maison ? Documentez ces choix et les raisons qui les motivent. Cela évite que l'agent ne les "corrige" lors de ses modifications.
Les erreurs récurrentes observées
C'est probablement la section la plus précieuse sur le long terme. Chaque fois que vous constatez qu'un agent commet la même erreur à plusieurs reprises sur un point précis, ajoutez une instruction correctrice dans votre CLAUDE.md. Ce fichier doit s'enrichir au fil du projet.
Les références à des fichiers locaux ou des ressources en ligne
Le fichier peut pointer vers d'autres ressources. Par exemple : "Consulte /docs/architecture.md pour comprendre la structure globale du projet avant chaque modification structurelle." C'est un excellent moyen de connecter l'agent à votre documentation interne sans l'alourdir avec son contenu.

Mes recommandations pratiques après plus d'un an d'utilisation intensive

Au-delà des conseils généraux, voici les sections que j'ai progressivement ajoutées à mon propre CLAUDE.md après des mois d'utilisation quotidienne de Claude Code. Elles font partie de ce que je considère aujourd'hui comme des éléments indispensables.

La charte graphique détaillée

Sans consigne explicite, un agent produit systématiquement des interfaces génériques, que certains appellent le syndrome du "AI slop" : des designs corrects, fonctionnels, mais sans personnalité et sans cohérence avec l'identité visuelle existante. En précisant votre palette de couleurs, vos typographies et vos composants de référence, vous obtenez un résultat immédiatement intégrable dans votre projet.

La mise à jour automatique de la documentation

J'ai ajouté une instruction demandant à l'agent de mettre à jour la documentation correspondante dans mon dossier /docs à chaque ajout ou modification fonctionnelle. En format Markdown, systématiquement. Cela peut sembler anodin, mais cela change radicalement la maintenance sur le long terme : la documentation reste synchronisée avec le code sans effort supplémentaire de ma part.

Les tests unitaires systématiques

Je demande à l'agent d'écrire un test unitaire pour chaque ajout ou modification de code structurel. Un test unitaire est un test automatisé qui vérifie qu'une portion isolée du code (une fonction, une méthode) se comporte exactement comme prévu, pour chaque cas possible — entrée normale, cas limites, erreurs. Sans cette instruction, l'agent ne le fait généralement pas spontanément, même si le framework de test est déjà en place dans le projet.

Les tests d'expérience utilisateur avec Playwright

Playwright est un framework open source développé par Microsoft, qui permet d'automatiser des scénarios de navigation dans un vrai navigateur (Chromium, Firefox, WebKit). Concrètement, vous pouvez lui faire simuler les actions d'un utilisateur réel : cliquer sur des boutons, remplir des formulaires, naviguer entre les pages, vérifier qu'un texte s'affiche correctement. Je demande à l'agent de créer ces tests sur tous les parcours critiques susceptibles d'impacter l'interface : authentification, paiement, soumission de formulaires, navigation principale. Cela garantit que les modifications apportées au code ne cassent pas silencieusement l'expérience utilisateur.

L'audit par sous-agents sur le code structurel

C'est l'une des fonctionnalités les plus puissantes de Claude Code : la possibilité de déléguer des tâches à des sous-agents, c'est-à-dire des instances de Claude lancées en parallèle pour effectuer des vérifications spécifiques. Pour tout code structurel produit, je demande à l'agent de déclencher trois passes d'audit distinctes, chacune confiée à un sous-agent spécialisé :

  • Audit fonctionnel : le code fait-il bien ce qu'il est censé faire ? Tous les cas d'usage sont-ils couverts ?
  • Audit qualité : le code est-il lisible ? Y a-t-il des duplications ? Les conventions sont-elles respectées ?
  • Revue de sécurité : y a-t-il des vulnérabilités potentielles ? La validation des entrées est-elle correcte ? La gestion des erreurs est-elle robuste ?

Ce mécanisme de triple relecture automatisée change la donne sur la qualité finale du code livré.

La gestion Git (pour les projets personnels)

Sur mes projets personnels, j'ai ajouté une instruction demandant un commit atomique après chaque revue de code validée, et un push manuel en fin d'unité de travail cohérente. Un commit atomique est un commit qui ne contient qu'une seule modification logique, ce qui facilite la lecture de l'historique Git et simplifie les éventuels retours en arrière. Je précise "projets personnels uniquement" car sur des projets d'équipe, les règles Git sont généralement définies collectivement et peuvent différer.

Un modèle de CLAUDE.md prêt à l'emploi

Voici le modèle que j'utilise comme point de départ, construit à partir des retours d'expérience décrits ci-dessus. Il est conçu pour être adapté à votre contexte spécifique :

## Contexte projet

[Une à trois phrases : nature du projet, stack technique, environnement de déploiement.]

## Environnement

- Versions imposées : [Node X, Python X, etc.]
- Contraintes spécifiques : [VPS, RAM, réseau, proxy…]
- Commandes clés :
  - Démarrage dev : [commande]
  - Build : [commande]
  - Tests : [commande]
  - Migrations : [commande]

## Charte graphique

- Palette : principale `[#XXXXXX]`, secondaire `[#XXXXXX]`, accent `[#XXXXXX]`
- Typographies : titres `[police]`, corps `[police]`
- Framework UI : [UIkit3 / Tailwind / Bootstrap / autre]

TRÈS IMPORTANT : ne jamais générer de design générique. Respecter strictement la charte graphique définie ci-dessus.

## Documentation interne

À chaque ajout ou modification fonctionnelle, mettre à jour la documentation correspondante dans `/docs`.
Format : Markdown.
Consulter `/docs/architecture.md` avant toute modification structurelle.

## Tests unitaires

VOUS DEVEZ écrire un test unitaire pour chaque ajout ou modification de code structurel.
Framework imposé : [Jest / Vitest / Pytest / autre].
Couverture minimale attendue : [X]%.

## Tests d'UX (Playwright)

VOUS DEVEZ tester l'UX avec Playwright sur l'ensemble des modifications susceptibles d'impacter l'interface utilisateur.
Parcours prioritaires : authentification, paiement, formulaires critiques, navigation principale.

## Audit par sous-agents

Pour tout code structurel produit, déclencher trois passes de revue :

1. Audit fonctionnel : le code fait-il ce qu'il doit faire ?
2. Audit qualité : lisibilité, duplications, respect des conventions.
3. Revue sécuritaire : vulnérabilités, validation des entrées, gestion des erreurs.

## Conventions de nommage

[Vos règles spécifiques. Exemple : composants React en PascalCase + suffixe Component, fonctions utilitaires préfixées utils_]

## Règles de sécurité

VOUS NE DEVEZ JAMAIS écrire de tokens d'API, de mots de passe ou de secrets en dur dans le code.
Toujours utiliser des variables d'environnement (.env).
Ne jamais logger de données utilisateur sensibles.

## Git (projets personnels uniquement)

Après revue du code validée, commit atomique systématique.
Push manuel en fin d'unité de travail cohérente sur le dépôt GitHub.

## Problèmes récurrents

[À enrichir au fil du projet. Exemples :]
- Ne JAMAIS utiliser l'API dépréciée [X], utiliser [Y] à la place.
- Toujours vérifier la compatibilité avec [version X] avant d'utiliser une nouvelle fonctionnalité.

Attention : ce modèle est un point de départ, pas une recette universelle. Il doit être adapté à votre projet, à votre équipe et à votre façon de travailler. Un CLAUDE.md copié-collé sans réflexion sera moins efficace qu'un fichier minimaliste mais parfaitement taillé pour votre contexte.

CLAUDE.md comme du code : itérer, tester, affiner

Un dernier point que je ne saurais trop souligner : votre CLAUDE.md n'est jamais "terminé". À l'image du prompt engineering — l'art de formuler des instructions efficaces pour un modèle d'IA — le maniement de ce fichier est un processus d'itération continue. On teste, on observe, on ajuste.

Un élément auquel il faut prêter attention est ce que l'on appelle la prompt adherence : la capacité d'un modèle à suivre fidèlement les instructions qui lui sont données. Cette capacité varie sensiblement d'une version de modèle à l'autre. Lors d'une mise à jour majeure de Claude Code, ou de tout autre agent que vous utilisez, il est utile de reprendre votre CLAUDE.md et de vérifier que vos instructions restent bien interprétées comme prévu. Ce qui fonctionnait parfaitement avec une version peut nécessiter une reformulation avec la suivante.

Concernant l'écosystème en 2026, le paysage des agents de code a considérablement évolué. Claude Code reste parmi les mieux classés sur les benchmarks de référence (SWE-bench Verified), aux côtés de Codex et Cursor 3. Les formats CLAUDE.md et AGENTS.md coexistent, avec AGENTS.md qui s'est imposé comme standard de facto pour les équipes multi-outils. Si vous travaillez en équipe avec des développeurs utilisant des agents différents, AGENTS.md est aujourd'hui le choix le plus cohérent pour garantir que tout le monde bénéficie des mêmes instructions.

Conseil de pro : créez une section "Problèmes récurrents" dans votre fichier et enrichissez-la au fil des semaines. C'est souvent la section la plus précieuse sur le long terme, car elle capitalise sur les erreurs réelles observées dans votre projet spécifique.

En conclusion

Un fichier CLAUDE.md ou AGENTS.md bien structuré, c'est du context engineering : l'art de fournir à l'agent exactement les informations dont il a besoin, ni plus ni moins, pour produire un code cohérent avec votre projet. C'est ce qui distingue un développeur qui utilise un agent IA comme un simple outil de complétion de code de celui qui en tire une productivité réellement multipliée.

La clé est de garder à l'esprit que l'agent n'est qu'un exécutant : vous restez le donneur d'ordre. La qualité de votre CLAUDE.md est le reflet direct de la clarté de vos propres standards de développement. Et c'est précisément pour ça que ce fichier vaut la peine d'y consacrer du temps.