La plupart des agents IA n’échouent pas parce que le modèle est mauvais.
Ils échouent parce qu’ils se réveillent amnésiques à chaque session.
Tu dis à Claude : « on utilise pnpm, pas npm. »
Session suivante : il réessaie npm.
Tu lui dis : « pas d’exports par défaut ici. »
Session suivante : il écrit un export par défaut.
Chaque correction que tu fais disparaît dès que la session se termine.
Il existe une solution en un seul fichier.
Il m’a fallu trois mois à me répéter pour la trouver.
Voici tout ce que j’ai appris.
Pourquoi la plupart des agents IA échouent
Ce n’est pas le modèle.
C’est la couche manquante en dessous du modèle.
→ Tu écris un prompt
→ L’agent exécute la tâche
→ La session se termine
→ La mémoire disparaît
→ Session suivante : mêmes erreurs
→ Tu répètes les mêmes instructions
→ Pour toujours
Cette boucle est la plus grande source de temps perdu dans le codage avec l’IA.
Pas le mauvais code. Pas les hallucinations.
La répétition.
La couche manquante : la mémoire
Tout le monde s’obsède sur le modèle le plus intelligent.
Mauvaise couche.
La vraie amélioration n’est pas un modèle plus intelligent.
C’est donner au modèle un endroit où stocker ce qu’il apprend.
→ Prompts → indique à l’agent quoi faire maintenant
→ Agents → exécutent la tâche
→ Mémoire → persiste le contexte entre les sessions
→ Contexte persistant → plus de corrections répétées
→ Système d’apprentissage → l’agent s’améliore avec le temps
C’est la différence entre un outil et un coéquipier.
Un outil fait ce que tu dis, à chaque fois, à partir de zéro.
Un coéquipier se souvient de la veille.
Les 5 fichiers mémoire dont chaque agent IA a besoin
Une fois que tu acceptes que la mémoire est la couche manquante, la question suivante est : où vit-elle ?
Cinq fichiers. Chacun avec un rôle différent.
→ CLAUDE.md — le document d’accueil personnel de Claude
→ AGENTS.md — le standard universel, lu par tous les outils majeurs
→ CLAUDE.local.md — tes préférences personnelles, jamais commité dans git
→ MEMORY.md — notes que l’IA écrit sur elle-même, automatiquement
→ README.md — pour les humains, pas pour les agents
Voyons chacun d’eux.
CLAUDE.md — celui qui a tout commencé
Dépose-le à la racine de ton projet.
Claude le lit au début de chaque session.
Considère-le comme un document d’accueil pour un nouveau membre d’équipe amnésique.
Un bon CLAUDE.md comporte quatre sections :
→ Contexte du projet — une ligne. « Application e-commerce Next.js avec Stripe et Postgres. »
→ Style de code — pas « formate le code correctement » mais « utilise les modules ES, exports nommés, indentation 2 espaces. »
→ Commandes — chaînes exactes. pnpm test:integration, pas « lance les tests. »
→ Architecture — « Les routes API vont dans /src/api/[resource]/route.ts. Pattern repository pour l’accès DB. »
1# CLAUDE.md23## Contexte du projet4Application e-commerce Next.js 14. Intégration Postgres + Stripe.56## Style de code7- Modules ES uniquement8- Exports nommés, jamais d’exports par défaut9- Indentation 2 espaces10- Mode strict TypeScript1112## Commandes13- Installation : pnpm install14- Développement : pnpm dev15- Tests : pnpm test:integration16- Lint : pnpm lint:fix1718## Architecture19- Routes API : /src/api/[resource]/route.ts20- Accès DB : pattern repository uniquement21- Composants : /src/components, un fichier par composant
Objectif : moins de 300 lignes.
Chaque ligne est en concurrence pour attirer l’attention avec le vrai travail.
Exécute /init et Claude génère automatiquement un fichier de départ.
Ensuite, supprime la plus grande partie.
Le fichier par défaut inclut des choses que Claude sait déjà grâce à ton package.json. Ne garde que ce que Claude aurait faux sans le fichier.
Le système @imports — garde-le léger
CLAUDE.md n’a pas besoin de tout contenir.
Il peut importer d’autres fichiers :
Voir
@README .md pour l’aperçu du projet Voir
@docs/api-patterns .md pour les conventions API Voir
@package .json pour les scripts npm disponibles
Les importations peuvent être récursives — jusqu’à 5 niveaux de profondeur.
Cela résout le problème du « fichier unique géant ».
Pour les équipes : l’équipe frontend possède docs/frontend-rules.md.
La sécurité possède docs/security.md.
CLAUDE.md se contente de tous les importer.
Un fichier racine. De nombreuses sources spécialisées.
AGENTS.md — le standard universel
CLAUDE.md ne fonctionne que pour Claude.
Si ton équipe utilise aussi Cursor, Copilot ou Gemini CLI — ils ne le lisent jamais.
AGENTS.md résout ce problème.
Un fichier. Tous les agents majeurs le lisent.
Supporté par Claude Code, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Aider, Zed, Warp, et plus encore.
C’est du Markdown standard. Pas de schéma spécial. Pas de YAML requis.
1# AGENTS.md23## Aperçu du projet4Plateforme e-commerce construite avec Next.js 14, Postgres et Stripe.56## Build & Test7- Installation : pnpm install8- Développement : pnpm dev9- Tests : pnpm test10- Lint : pnpm lint:fix1112## Standards de code13- Mode strict TypeScript14- Exports nommés plutôt qu’exports par défaut15- Les routes API suivent les conventions REST dans /src/api/1617## Exigences de test18- Toutes les PR doivent inclure des tests19- vitest pour les tests unitaires, playwright pour les tests e2e
Considère-le comme un README pour les agents IA.
README.md est pour les humains. AGENTS.md est pour tous les agents, quelle que soit l’entreprise. CLAUDE.md ajoute des extras spécifiques à Claude par-dessus.
Ils sont complémentaires. Pas concurrents.
Mémoire automatique — l’IA qui prend ses propres notes
C’est la couche la plus récente et la plus intéressante.
Claude Code écrit maintenant ses propres fichiers mémoire pendant tes sessions.
memory/ ├── MEMORY.md ← index, chargé à chaque session ├── debugging.md ← notes sur les patterns de débogage ├── api-conventions.md ← décisions de conception API └── ...
Le changement clé :
Tu écris CLAUDE.md. Tu fournis les instructions.
Claude écrit MEMORY.md. Il capture ce qu’il a appris.
→ L’humain écrit les règles
→ L’agent découvre des patterns en travaillant
→ L’agent écrit sa propre mémoire
→ Les futures sessions démarrent plus intelligemment
Tu peux déclencher cela directement. À la fin d’une session productive, dis simplement :
« Mets à jour tes fichiers mémoire avec ce que tu as appris sur notre codebase aujourd’hui. »
Les apprentissages persistent. Plus besoin de réexpliquer ton wrapper ORM personnalisé pour la cinquième fois.
Exécute /memory à tout moment pour réviser ou modifier ce que Claude a enregistré.
Le workflow /init puis suppression
Le moyen le plus rapide d’amorcer un fichier mémoire sur un nouveau projet :
- Exécute /init dans ton répertoire de projet
- Claude génère un CLAUDE.md de départ basé sur ton codebase
- Supprime ce dont tu n’as pas besoin
L’étape 3 est là où la plupart des gens se trompent.
Le fichier généré est un brouillon, pas un produit fini.
Il contient souvent du remplissage. « Ce projet utilise JavaScript. » Merci — visible depuis package.json.
Éditer à partir d’un brouillon raisonnable est mieux que d’écrire à partir d’un fichier vierge.
Après la configuration, construis organiquement.
Quand Claude fait une hypothèse erronée — par exemple, il continue d’importer un package déprécié — ne le corrige pas qu’une fois.
Dis-lui : « ajoute à mon CLAUDE.md : toujours importer depuis @company/utils-v2, pas @company/utils. »
L’instruction persiste pour toutes les sessions futures.
Toutes les quelques semaines, demande à Claude de réviser et nettoyer CLAUDE.md.
Les instructions s’accumulent. Certaines deviennent redondantes. D’autres commencent à se contredire. Un passage rapide le maintient efficace.
Ma configuration actuelle
Après avoir testé tout cela sur plusieurs projets de production, voici ce qui a fonctionné :
→ AGENTS.md à la racine du projet — instructions partagées que tout outil IA peut lire. Commandes de build, standards de code, exigences de test.
→ CLAUDE.md avec @imports pour le comportement spécifique à Claude. Reste en dessous de 100 lignes, pointant principalement vers les fichiers docs/.
→ CLAUDE.local.md pour les particularités personnelles — mes données de test, URL de sandbox, commandes raccourcies. Jamais commité dans git.
→ Mémoire automatique activée. Claude prend ses propres notes. Je révise mensuellement.
→ Tout le reste remplacé par des liens symboliques pointant vers AGENTS.md. Une source de vérité unique.
1# Configuration des liens symboliques pour la cohérence multi-outils2ln -sfn AGENTS.md .github/copilot-instructions.md3mkdir -p .cursor/rules && ln -sfn ../../AGENTS.md .cursor/rules/main.mdc
Pas élégant.
Mais ça élimine la dérive des instructions entre tous les outils de l’équipe.
Le changement plus large
La plupart des développeurs pensent :
Meilleur modèle = meilleur agent.
Faux.
La vraie formule :
Modèle + Mémoire + Récupération + Retour d’information = Agent utile
Un modèle plus intelligent sans mémoire oublie encore ta commande de test demain.
Un modèle modeste avec une excellente mémoire devient plus affûté chaque semaine.
La mémoire est la variable composée.
L’intelligence du modèle ne l’est pas.
La plus grande amélioration que j’ai apportée à mon workflow IA n’a pas été de changer de modèle.
C’était de donner une mémoire au modèle.
La différence entre :
« Claude, on utilise pnpm » — à chaque session
et :
« Claude le sait déjà » — à chaque session
C’est la différence entre un outil et un coéquipier.
Si cela a été utile :
→ Reposte pour le partager avec tous les développeurs qui se répètent encore à Claude
→ Suis @sairahul1 pour plus de systèmes qui composent pendant que tu dors
→ Mets-le en favori — configure-le ce soir, arrête de corriger demain
J’écris sur l’IA, la construction de produits et les systèmes qui fonctionnent sans toi.
