CLAUDE.md et AGENTS.md : donner une mémoire à ton agent IA

Tu as déjà eu l'impression que ton agent IA oublie tout entre deux conversations ?

C'est normal. Les LLMs n'ont pas de mémoire persistante. À chaque conversation, tu dois ré-expliquer qui tu es, ton projet, tes conventions. C'est comme briefer un nouveau dev à chaque fois.

La solution ? Un fichier markdown à la racine de ton projet qui donne du contexte à ton agent. Automatiquement. À chaque session.

Et c'est pas juste une bonne pratique. Vercel l'a mesuré : un simple fichier AGENTS.md atteint 100% de réussite sur leurs evals Next.js 16, contre 53% sans contexte et 79% avec un système de skills plus complexe. Un fichier texte bat un système sophistiqué de retrieval. Pourquoi ? Parce que l'info est toujours là, pas besoin de décider quand la charger.

Deux standards, même idée

Il existe deux formats pour ça.

AGENTS.md est un standard ouvert porté par la Linux Foundation. Il marche avec plus de 20 outils : OpenAI Codex, Google Gemini CLI, Cursor, Windsurf, OpenCode, Aider, GitHub Copilot, Devin, et d'autres. C'est le format universel.

CLAUDE.md est le format spécifique à Claude Code. Même concept de base, mais avec des fonctionnalités avancées en plus (rules ciblées, hooks, skills, hiérarchie mémoire).

L'équipe engineering d'Anthropic ne mâche pas ses mots :

"CLAUDE.md is the single most important file in your codebase for using Claude Code effectively."

Si tu utilises plusieurs outils (Claude Code + OpenCode par exemple), tu peux avoir les deux fichiers. Ou créer un symlink :

ln -s AGENTS.md CLAUDE.md

Le contenu de base est le même. C'est les features avancées qui diffèrent.

Sans vs Avec fichier de contexte

Un exemple concret

Voici à quoi ressemble un fichier de contexte simple mais efficace. Ce contenu marche dans les deux formats :

# Bash commands
- npm run build: Build the project
- npm run typecheck: Run the typechecker
- npm test: Run tests

# Code style
- Use ES modules (import/export) syntax
- Destructure imports when possible
- Prefer const over let

# Testing
- Run tests before committing
- All new features need tests
- Mock external APIs in tests

Simple. Clair. Efficace. En 15 lignes, l'agent sait comment builder, tester et coder sur ton projet. Que tu utilises Claude Code, OpenCode, Cursor ou Codex.

Les 3 règles d'or

Ces règles s'appliquent quel que soit l'outil.

Règle #1 : Moins c'est plus

Selon HumanLayer :

"Keep your file to fewer than 300 lines; aim for less than 60 lines."

Pourquoi ? Les LLMs peuvent suivre environ 150 à 200 instructions de manière fiable. Le system prompt de ton agent en consomme déjà une partie. Si ton fichier fait 500 lignes, une bonne partie sera ignorée.

Garde ton fichier léger. Va à l'essentiel. Si une règle n'est pas critique, elle n'a pas sa place dans le fichier principal.

Règle #2 : Chaque erreur devient une règle

L'équipe Anthropic utilise cette méthode :

"Anytime we see Claude do something incorrectly we add it to the CLAUDE.md, so Claude knows not to do it next time."

Ça marche avec n'importe quel agent. Ton agent push sur main sans demander ? Ajoute "JAMAIS push sur main sans accord explicite". Il utilise le mauvais package manager ? Ajoute "Utiliser pnpm, pas npm".

Ton fichier de contexte évolue avec le temps. C'est un document vivant.

Règle #3 : Donne des alternatives, pas juste des interdictions

Mauvais :

Ne jamais utiliser le flag --force

Bon :

Ne jamais utiliser --force. Utiliser --force-with-lease à la place.

Pourquoi ? Parce que si tu dis juste "ne fais pas X", l'agent va se retrouver bloqué quand il pensera devoir utiliser X. Donne toujours une alternative.

Organiser pour les gros projets

Quand ton projet grossit, un seul fichier ne suffit plus. Les deux standards supportent les fichiers en sous-dossiers.

monorepo/
├── AGENTS.md              # Instructions globales
├── packages/
│   ├── api/
│   │   └── AGENTS.md      # Instructions spécifiques à l'API
│   └── frontend/
│       └── AGENTS.md      # Instructions spécifiques au frontend

Le fichier le plus proche du fichier édité a la priorité. Tes règles API ne polluent pas le contexte quand tu travailles sur le frontend.

OpenAI utilise plus de 88 fichiers AGENTS.md dans son repo principal. C'est une pratique standard pour les gros projets.

Ce que Claude Code ajoute

Tout ce qui précède marche partout. Ce qui suit est spécifique à Claude Code.

Organisation de la mémoire Claude Code

Rules avec ciblage par chemin

Claude Code propose un système de rules via le dossier .claude/rules/ :

.claude/
├── CLAUDE.md           # Instructions principales (concis)
└── rules/
    ├── code-style.md   # Conventions de code
    ├── testing.md       # Comment tester
    └── security.md     # Règles de sécurité

La fonctionnalité la plus puissante : le ciblage par chemin.

---
paths: src/api/**/*.ts
---
# Règles API
- Valider tous les inputs avec Zod
- Retourner des erreurs cohérentes

Avec ce frontmatter YAML paths, ces règles ne s'activent que quand Claude édite des fichiers dans src/api/. Tes règles API ne consomment pas de tokens quand tu travailles sur du React.

Imports avec la syntaxe @

Pas besoin de tout recopier dans ton CLAUDE.md. La syntaxe @ permet d'importer n'importe quel fichier :

# Mon Projet

Voir @README.md pour l'overview.
Conventions Git : @docs/git-workflow.md
Architecture : @docs/architecture.md

Claude Code charge automatiquement les fichiers référencés. Tu peux voir tout ce qui est chargé avec /memory.

Hiérarchie mémoire (8 niveaux)

CLAUDE.md n'est pas seul. Claude Code charge plusieurs niveaux de mémoire, du plus global au plus local :

1. Managed policy    → /etc/claude-code/CLAUDE.md (admin, pour toute l'org)
2. User memory       → ~/.claude/CLAUDE.md (toi, tous tes projets)
3. User rules        → ~/.claude/rules/*.md (toi, tous tes projets)
4. Project memory    → ./CLAUDE.md (équipe, via git)
5. Project rules     → ./.claude/rules/*.md (équipe, via git)
6. Local memory      → ./CLAUDE.local.md (toi, ce projet)
7. Sub-directory     → ./src/api/CLAUDE.md (contexte activé à la demande)
8. Auto memory       → ~/.claude/projects/<project>/memory/ (notes auto)

Le plus spécifique gagne. Si ton CLAUDE.md de projet dit "utilise des tabs" et ton CLAUDE.md utilisateur dit "utilise des espaces", les tabs gagnent quand tu bosses sur ce projet.

Hooks

Les hooks, c'est du code qui s'exécute automatiquement quand Claude fait certaines actions. Configuré dans .claude/settings.json.

L'exemple le plus utile : reformater automatiquement après chaque édition.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ]
  }
}

Chaque fois que Claude modifie un fichier, Prettier le formate. Sans intervention de ta part. Les hooks couvrent 14 événements différents (début de session, avant/après chaque outil, compaction...). La doc officielle des hooks détaille tout.

Skills

Les skills transforment des tâches répétitives en commandes. Crée .claude/skills/review/SKILL.md :

---
name: review
description: Code review d'un fichier ou PR
---

Fais une code review du code fourni en suivant nos conventions :
1. Vérifie la logique métier
2. Vérifie la gestion d'erreurs
3. Vérifie les types TypeScript
4. Suggère des améliorations

Tape /review et Claude fait la review avec tes critères. Plus besoin de tout ré-expliquer à chaque fois.

Récap : ce qui marche où

| Fonctionnalité | AGENTS.md | CLAUDE.md | |----------------|-----------|-----------| | Fichier markdown à la racine | Oui | Oui | | Sous-dossiers (monorepo) | Oui | Oui | | Commandes build/test/lint | Oui | Oui | | Conventions de code | Oui | Oui | | Priorité au fichier le plus proche | Oui | Oui | | Rules avec ciblage par chemin | Non | Oui | | Imports (@fichier) | Non | Oui | | Hiérarchie mémoire (8 niveaux) | Non | Oui | | Hooks (14 événements) | Non | Oui | | Skills (commandes custom) | Non | Oui | | Auto memory | Non | Oui | | Outils compatibles | 20+ | Claude Code |

Commence simple

Crée un fichier AGENTS.md à la racine de ton projet (compatible avec tout)
Si tu utilises Claude Code, crée aussi un CLAUDE.md (ou un symlink)
Ajoute tes commandes de base (build, test, lint)
Ajoute tes conventions de code principales
Chaque fois que ton agent fait une erreur, ajoute une règle
Si tu es sur Claude Code et que ça grossit, découpe dans .claude/rules/

La différence entre un agent qui te fait perdre du temps et un agent qui te rend productif ? Souvent, c'est juste ce fichier.

Sources :