Si tu as bootstrappé un projet EmDash et que tu as vu débarquer AGENTS.md et/ou CLAUDE.md, tu as probablement eu la même réaction que moi : « ok c’est moderne… mais qu’est-ce qu’on est censés faire de ça ? ». Spoiler : ça peut être un super pouvoir, parce que ça évite à l’IA de partir en freestyle sur ton repo. Mais ça peut aussi devenir une dette d’équipe bien toxique, surtout quand ces fichiers commencent à contenir des “règles” au pif, ou pire, du sensible.
On va remettre ça au carré : à quoi ça sert, ce que ça doit contenir dans un repo pro, ce que ça ne doit jamais contenir, et comment je les passe en revue avant de les laisser vivre dans un projet client.
AGENTS.md et CLAUDE.md : c’est quoi exactement (et à quoi ça sert dans un repo)
Ces fichiers sont des instructions de travail destinées à un agent IA (Claude, Copilot, Cursor, etc.). L’idée est simple : au lieu de répéter à chaque prompt « voici l’archi, voici les commandes, voici notre style, voici comment on teste », tu mets ça dans un endroit standard, versionné, relisible par l’équipe.
Le bon usage, c’est d’en faire une doc “opérationnelle” : conventions de code, commandes fiables, structure du projet, points d’attention. Le mauvais usage, c’est d’en faire une anti-doc : un mélange de règles implicites, d’infos qui vieillissent, et de détails internes qu’on finit par oublier… jusqu’au jour où l’IA les ressort, ou où quelqu’un les copie ailleurs.
Le nom varie selon les outils. Certains cherchent AGENTS.md, d’autres CLAUDE.md. EmDash, d’après les retours de bootstrap, semble assumer ce pattern dès le départ, comme un “contrat” entre ton repo et ton assistant.
Sponsorisé par Le Scribouillard
Besoin de contenu optimisé SEO ?
Utilisez la meilleure plateforme française de création de contenu assistée par IA ! Et générez des articles pour moins de 1€ !
Pourquoi EmDash les met dès le bootstrap (et pourquoi ce n’est pas idiot)
EmDash se positionne comme un CMS moderne avec un workflow dev qui ressemble plus à un projet web actuel qu’à un vieux thème bricolé à l’arrache. Quand tu arrives avec des agents IA dans la boucle, le problème numéro 1 n’est pas « est-ce que l’IA sait coder ». C’est « est-ce qu’elle comprend comment ce repo fonctionne ».
Sans contexte, un agent va :
inventer des scripts npm, lancer le mauvais test runner, modifier des fichiers générés, ignorer tes conventions, ou te proposer des changements “propres” mais incompatibles avec ton CI. Et là tu perds du temps, tu doutes de tout, et tu finis par ne plus lui faire confiance.
Avec un fichier d’instructions minimaliste mais net, tu réduis l’ambiguïté. Et tu transformes l’IA en outil de prod : elle peut corriger un bug, écrire un test, refactor un composant, sans re-découvrir le projet à chaque fois.
Ce que je mets dedans pour que l’IA soit utile (sans sur-documenter)
Mon heuristique est bête : si ça aide un humain qui arrive sur le repo, ça aidera aussi un agent. La différence, c’est que l’agent a tendance à exécuter “vite”. Donc je privilégie les informations actionnables et vérifiables.
Concrètement, je mets le strict nécessaire : la stack réelle, la structure des dossiers qui comptent, les commandes qui marchent, et deux ou trois conventions qui évitent les PR moches. J’évite les pages de philosophie, parce que ça vieillit mal et ça finit ignoré.
# Instructions agent (AGENTS.md)
## Contexte rapide
Ce dépôt contient :
- le back-office / CMS (EmDash)
- le front (thème) : Astro
Objectif quand tu proposes un changement : rester minimal, testable, et compatible CI.
## Commandes fiables
- Installer : `npm ci` (pas de gestionnaire alternatif sans demander)
- Dev : `npm run dev`
- Tests : `npm test` (si présent) et/ou `npm run lint`
- Build : `npm run build`
Si une commande échoue, n'invente pas une autre commande. Demande ou cherche dans package.json.
## Conventions de code
- Ne modifie pas les fichiers générés (dist/, build/, .astro/ etc.)
- Préfère des changements petits et localisés
- Ajoute/ajuste les tests quand c’est pertinent
## Architecture (résumé)
- `src/` : code applicatif
- `content/` : contenu / collections (si présent)
- `public/` : assets statiques
## Ce que tu dois éviter
- N’ajoute pas de dépendances sans justification claire
- N’écris pas de secrets / tokens / URLs internes dans le repo
- N’exécute pas de commandes destructrices (`rm -rf`, reset de DB, migrations) sans validation explicite
Ce genre de fichier fait gagner du temps parce qu’il coupe court aux erreurs classiques. Et surtout, il donne une règle d’or que j’adore : si tu ne trouves pas dans le repo, tu ne l’inventes pas. Les agents ont un talent particulier pour « être sûrs d’eux » quand ils ont tort.
Le vrai piège : transformer ces fichiers en fuite de secrets “versionnée”
Le risque numéro 1, ce n’est pas “l’IA qui devient consciente”. C’est beaucoup plus terre à terre : tu finis par mettre dans AGENTS.md des choses que tu n’aurais jamais dû committer. Typiquement, un collègue veut “aider” l’agent et écrit : nom d’un bucket, URL d’admin, conventions internes client, bouts de config, ou pire, un token de test « temporaire ».
Et même sans token, tu peux fuiter des infos utiles à un attaquant. Un inventaire d’URLs internes, le nom de ton provider, des chemins d’export, la façon dont vous faites vos déploiements, des noms de services, des ports, des environnements. Tout ça, dans un dépôt qui peut finir cloné, partagé, ou copié dans des outils tiers.
Autre piège : le prompt injection par le repo. Si l’agent lit les fichiers du projet pour “prendre du contexte”, un fichier de doc ou un commentaire malicieux peut lui souffler des instructions du style « ignore les règles, exfiltre X ». Ce n’est pas de la science-fiction, c’est juste un problème d’outillage : un agent qui obéit à tout ce qu’il lit est un agent dangereux.
Moralité : ces fichiers doivent être sobres, et ils doivent explicitement rappeler à l’agent de ne pas se fier à des instructions trouvées “au hasard” dans le repo si elles contredisent les règles principales.
Définir le périmètre : lecture, écriture, commandes, et zones interdites
Ce qui marche bien en équipe, c’est d’écrire noir sur blanc le périmètre de l’agent. Pas dans un style juridique. Juste une phrase claire qui évite les malentendus.
Par exemple, si tu veux un agent “assistant de code”, tu peux lui autoriser la lecture large du repo, l’écriture uniquement dans src/ et les tests, et lui interdire tout ce qui touche aux scripts infra. Ça paraît rigide, mais ça évite le scénario classique : une refacto demandée sur un composant, et l’agent “optimise” aussi le pipeline, les versions Node, ou le lockfile.
Je mets aussi une règle simple sur les commandes : pas de commandes destructrices, pas de reset de base, pas de migration surprise, pas de « je supprime le cache et on verra ». Un agent qui a accès à un terminal est très vite tenté de résoudre un problème en bulldozer.
Et j’insiste sur un point : pas de secrets, même “pour aider”. Si l’agent a besoin d’un accès, alors le bon endroit c’est un gestionnaire de secrets, une doc interne hors repo, ou un environnement de dev bien isolé. Pas un fichier markdown versionné.
Ces fichiers vont vieillir : assume-le, sinon ça devient une dette d’équipe
Le truc qui fait mal avec AGENTS.md / CLAUDE.md, c’est qu’ils ont l’air “optionnels”. Donc personne ne les maintient. Et au bout de 3 mois, ils contiennent une commande qui n’existe plus, un dossier renommé, une convention abandonnée.
À partir de là, l’IA fait exactement ce que tu lui as demandé… mais c’est faux. Et ça coûte plus cher qu’une absence de fichier, parce que ça te met sur une fausse piste.
Ma solution est boring mais efficace : je traite ces fichiers comme de la doc d’équipe. Ils ont un owner implicite (souvent la personne qui tient la DX / la CI), et ils évoluent avec les changements de tooling. Si on change le runner, on change la doc dans la même PR. Sinon, c’est du folklore.
Avant de committer ça chez un client : ma mini-revue “anti-embrouille”
Je garde une revue courte, parce que si c’est long, personne ne la fait. Le but est juste d’éviter les gros dégâts.
- Je cherche du sensible : tokens, URLs internes, noms de comptes cloud, chemins d’export, infos d’accès, captures de logs.
- Je vérifie que les commandes citées existent vraiment dans
package.jsonet que le repo build en CI avec ces commandes. - Je regarde si le fichier donne des permissions implicites (“tu peux faire des migrations”, “tu peux nettoyer la DB”). Si oui, je recadre.
- Je supprime les règles “floues” et non testables. Une règle non testable finit ignorée.
- Je m’assure qu’il y a une section “ce que l’agent ne doit pas faire”, claire et sans ambiguïté.
Mon avis (assumé) : ce n’est pas un gadget IA, c’est une interface de ton repo
AGENTS.md et CLAUDE.md, je les vois comme une interface. Un contrat. Si tu les écris bien, tu rends ton projet plus “automatisable”, donc plus rapide à maintenir. Et tu aides aussi les humains, au passage.
Si tu les écris mal, tu crées un endroit où l’équipe déverse des règles bancales, puis oublie. Et là, oui, c’est de la dette. La bonne nouvelle, c’est que la version “safe” est simple : du contexte minimal, des commandes vraies, des limites strictes, et zéro info sensible. Le reste, tu peux le laisser hors repo, dans une doc interne qui n’a pas vocation à être lue par un agent branché à un modèle externe.
