Gestion de la mémoire

Comment écrire dans la mémoire automatique de Claude Code et dans CLAUDE.md pour que la bibliothèque reste consultable à mesure que le projet grandit.

Référence rapide

L'utilisateur dit…	Faites ceci
"Note ça" (flou, plusieurs candidats) / "Revue" / "Développement terminé, qu'y a-t-il à noter ?"	→ Mode 1 : Évaluation de candidats (filtrage multi-candidats)
"Note le bug X d'aujourd'hui" (un élément spécifique) / Après correction d'un bug majeur / Fin d'incident de sécurité / Décision unique avec conclusion non évidente	→ Mode 2 : Créer une mémoire (direct)
"Mettre à jour cette mémoire / Corriger la conclusion de X"	→ Mode 3 : Mise à jour d'une mémoire existante (prioritaire sur la création)
Section à ajouter > 100 lignes ou fichier déjà > 4 sujets H2	→ Règle 6 : Diviser plutôt que mettre à jour
"Modifier le schéma / Ajouter un nouveau type / Changer la structure de la mémoire"	→ Mode 4 : Changement structurel (lire impérativement la liste des pièges)
"Nouveau projet sans mémoire / Comment commencer"	→ Mode 5 : Bootstrap sans mémoire
"Le système de mémoire semble désorganisé / Audit"	→ Exécuter `scripts/audit-memory.sh` s'il existe dans la racine du projet ; sinon, se référer à `templates/audit-memory.template.sh` pour en créer un

Règles importantes

Règle 1 : Les faits vont dans la mémoire, les méthodes dans la compétence

Le fichier de mémoire contient "le piège X dans lequel on est tombé", "les données Y du secteur", "l'état Z du projet" ; cette compétence contient "comment décider quoi noter / comment écrire / comment organiser". Ne mettez pas les spécifications du schéma dans la mémoire (erreur de catégorie).

Règle 2 : D'abord juger "si ça vaut la peine d'être noté", ensuite "où le noter"

Toutes les découvertes ne méritent pas d'être notées. Arbre de décision :

Signal	Doit-on le noter ?
Même piège rencontré une 2e fois	✅ Obligatoire
Découverte non évidente lors d'une revue de conformité	✅ Noter le "Pourquoi" de la décision
Référence sectorielle / Chiffres mesurés (base de référence réutilisable)	✅ Noter
Debug ponctuel corrigé sans valeur de capitalisation	❌ Ne pas noter (le message de commit suffit)
État temporaire qui va changer	⚠️ Selon la persistance, noter seulement si durable
Grave mais rare (pas lu depuis six mois mais reste la seule vérité)	✅ Conserver — Pas consulté depuis 30 jours ≠ obsolète ; le critère de suppression est "le sujet a disparu/a été remplacé", pas "depuis combien de temps il n'a pas été lu"

Juger "où le noter" — Routage à quatre niveaux par proximité (locality) :

Poser d'abord une question orthogonale : "Quand ce fait sera nécessaire à l'avenir, est-ce que je regarde un endroit précis du code, ou bien je prends une décision transversale / je débogue un type d'erreur ?"

Condition de déclenchement	Destination	Mécanisme
Observer une ligne/un bloc spécifique, le POURQUOI tient en une phrase	Commentaire de code en ligne (juste au-dessus de cette ligne)	Sûr à 100 % lors de la modification du fichier, coût d'indexation nul
Contrat / Liste de vérification concernant un ensemble spécifique de fichiers	`.claude/rules/<x>.md` + frontmatter `paths:`	Injection automatique du contexte lorsque les chemins correspondent
Le déclencheur est un scénario/une erreur/un type de problème, ou transversal à plusieurs fichiers, ou n'appartient pas à un seul fichier du dépôt (piège de plateforme/SDK)	Mémoire (ce système)	La description est la clé de ciblage
Règles à respecter à chaque session (commandes, stack technique, préférences de collaboration)	CLAUDE.md	Permanent

Un feedback lié à un fichier est par défaut SPLIT : le cœur local du fichier va dans un commentaire en ligne (avant d'écrire, grep ce code, il y a probablement déjà un commentaire équivalent) ; la mémoire ne conserve que les principes réutilisables entre fichiers + un pointeur vers ce fichier.

Trois garde-fous contre la migration excessive (par défaut dans la mémoire, plutôt moins migrer) :

Si en retirant le fichier spécifique, il reste une leçon générale → laisser dans la mémoire (ex. "Ne pas prendre un champ optionnel comme décision dans un chemin critique", le fichier spécifique n'est qu'un exemple, le principe est transférable)
Un comportement de plateforme/SDK qui se reproduit dans plusieurs fichiers → laisser dans la mémoire, même si lié au code
Une stèle (X est retiré → voir Y) / SOP d'investigation / Raisonnement économique métier → laisser dans la mémoire (déclenchement au niveau architecture/scénario)

Données empiriques (audit complet d'une bibliothèque de production de 175 fichiers) : seulement ~15 % des entrées sont liées à un seul fichier, et la plupart de ces fichiers avaient déjà leur cœur dans des commentaires de code — la "migration" consiste souvent à supprimer une copie redondante dans la mémoire, pas à un vrai déplacement.

Écriture de .claude/rules/*.md (à placer dans le dossier .claude/rules/ du projet, dans git → partagé entre machines/worktrees) :

---
description: Ce que cette règle régit en une phrase
paths:
  - src/components/SomeDialog.tsx
  - src/lib/providers/*.ts          # glob supporté
---
Contrat / liste de vérification injecté automatiquement lorsqu'on touche aux chemins ci-dessus (pièges multiples).

⚠️ Limites connues de l'injection native des règles (vérifié en juillet 2026, issues anthropics/claude-code) : les règles avec paths: ne sont injectées que lors de la lecture d'un fichier correspondant, pas lors de l'écriture/création de fichier (#23478) ; les règles paths: dans ~/.claude/rules/ au niveau utilisateur sont ignorées, seules celles du projet fonctionnent (#21858). Les contrats qui doivent s'appliquer même à la création de nouveaux fichiers doivent être dans CLAUDE.md, pas seulement dans les règles.

Règle 3 : Privilégier la mise à jour d'une mémoire existante, ne pas en créer une nouvelle

Si un fichier existe déjà sur le sujet → mettre à jour ce fichier (ajouter une section ou une section de changelog). Ne créer un nouveau fichier que si le sujet est totalement orthogonal. Créer un nouveau fichier entraîne une fragmentation thématique → difficulté à trouver → perte de mémoire.

Règle 4 : La mémoire n'est pas chargée automatiquement, la description détermine le ciblage

Les fichiers de mémoire (memory/*.md) ne sont pas chargés au démarrage d'une session. Claude utilise la description dans l'index MEMORY.md pour décider s'il doit les lire. La description doit être un mélange de mots-clés de scénario + conclusion centrale, sinon Claude décidera de lire en fonction de ses impressions.

Vérification du mécanisme natif (juillet 2026, docs officiels fr/memory) : il n'y a pas de rappel sémantique/vectoriel automatique — la découverte repose entièrement sur "ligne d'index MEMORY.md + nom de fichier", Claude utilise Read pour lire à la demande ; lors de la lecture, le harnais injecte une indication de fraîcheur "Cette mémoire a N jours". La qualité de la ligne d'index est le seul facteur de ciblage, c'est un comportement natif, pas une convention de cette compétence.

Règle 5 : La compétence elle-même doit respecter les normes qu'elle enseigne

Si cette compétence demande à l'utilisateur d'écrire une section ## Why, elle doit aussi expliquer le Pourquoi de chacune de ses propres règles (elles sont toutes en ligne dans ce fichier).

Attention au périmètre : La règle 5 s'applique à "la méthode/la forme d'écriture/le format de la référence rapide, etc.", ne s'applique pas récursivement aux règles du schéma. Le schéma (nommage/frontmatter/section Why) est destiné aux fichiers de mémoire, pas à la compétence elle-même. La compétence n'est pas un fichier de mémoire.

Règle 6 : Quand diviser plutôt que mettre à jour (éviter la surcharge d'un seul fichier/d'un seul groupe)

La règle 3 privilégie la mise à jour, mais avec des seuils. Signaux déclenchant une division (au niveau fichier) :

Signal	Action
Fichier existant > 100 lignes, ET le nouveau contenu est orthogonal au sujet d'origine	Créer un nouveau fichier, ne pas intégrer
Fichier existant avec ≥ 4 sections H2 de premier niveau, ET le nouveau contenu est le 5e sujet indépendant	Créer un nouveau fichier
La longueur totale après ajout dépasse 150 lignes	Évaluer la division (selon l'indépendance thématique)
Le contenu ajouté ne correspond pas au titre/description du fichier existant	Créer un nouveau fichier (le fichier d'origine doit rester concentré sur son sujet déclaré)

Surcharge de groupe (au niveau de l'index) :

Signal	Action
Nombre d'entrées d'un grand groupe dans MEMORY.md ≥ 15	Envisager la création d'une mémoire hub (index de section) remplaçant l'index plat, les nouvelles entrées sont rattachées au hub
La somme des descriptions d'un groupe, une fois lues, dépasse 25 lignes	Idem
MEMORY.md > 23 000 caractères (`wc -m`) ou > 190 lignes	🔴 Limite native dure = les 200 premières lignes ou 25K caractères, le premier atteint l'emporte (la documentation officielle dit "25KB", en pratique c'est la longueur des caractères qui est mesurée : un index de 27 972 caractères/37,9KB a été tronqué exactement au 25 000e caractère, alors que par octets il aurait dû être tronqué ~35 % plus tard). ⚠️ N'utilisez pas `wc -c` (octets) pour estimer : le chinois UTF-8 fait 3 octets par caractère, surestimant la marge de ~35 %. Proche de la limite, le harnais injecte un avertissement, si vous voyez `Seule une partie a été chargée`, cela signifie que l'index est déjà tronqué.
Une seule ligne d'index > ~160 caractères	Trop de détails dans la description → les déplacer dans le fichier mémoire ou descendre dans les commentaires de code, l'index ne doit garder que "mot-clé de scénario + conclusion centrale"

Pourquoi la surcharge d'un groupe est aussi problématique : Claude scanne l'index MEMORY.md pour cibler via les descriptions, un groupe de 20+ descriptions risque des omissions lors d'un seul scan. Après avoir créé un hub, l'index du groupe ne contient qu'une ligne pointant vers le hub, et le hub fait office de carte thématique.

Pourquoi la surcharge globale de l'index est la plus dangereuse : la surcharge d'un seul fichier/groupe ne fait que réduire la capacité de ciblage ; mais l'index global tronqué = les dernières lignes entières ne sont pas chargées = capacité de ciblage nulle, et ce en silence, sans erreur. Donc ⭐⭐⭐ les entrées couronnées doivent être placées en haut de MEMORY.md (assurance contre la troncature).

Priorités pour réduire la taille en cas de dépassement / fichier trop gros (compresser la description est la pire première action, car elle nuit au ciblage) :

D'abord migrer : les entrées locales à un fichier → commentaires en ligne / .claude/rules (l'index devient plus petit et le taux de ciblage augmente, voir la Règle 2 sur le routage à quatre niveaux)
Ensuite supprimer : les vraies stèles (sujet disparu/remplacé et sans valeur anti-réapparition)
Ensuite réorganiser : déplacer les ⭐⭐⭐ vers le haut de MEMORY.md
Ensuite hiérarchiser : répartir le budget des lignes d'index par importance — entrées couronnées ≤160 caractères, entrées normales ≤110, entrées longue traîne et peu fréquentes fusionnées en une ligne multi-liens (sous-thème → [a](f1.md) · [b](f2.md), une ligne pour 5-10 fichiers). Aussi, utiliser des étiquettes courtes sans préfixe de type pour les liens ([foo-bar](feedback_foo_bar.md)), ne pas répéter le nom complet du fichier, économisant 12-45 caractères par ligne
En dernier seulement compresser la quantité d'informations d'une ligne de description individuelle

Exemples de pièges historiques (référence, pas une règle)

Surcharge d'un seul fichier : un fichier de référence est devenu trop long (130+ lignes), contenant 7-8 sujets indépendants (infrastructure, liste cron, manuel de panne, etc.), la description dans l'index MEMORY.md était trop vague pour que Claude cible le bon sous-sujet. Après l'avoir divisé en 5 fichiers mémoire indépendants, chaque sujet est ciblé avec précision.
Surcharge d'un groupe : un groupe a accumulé 20+ entrées, lors d'une nouvelle session Claude a manqué certaines entrées lors du scan, provoquant une redécouverte inutile. La création d'une mémoire hub agrégeant les entrées connexes a résolu le problème.
Surcharge globale de l'index : MEMORY.md a atteint 43KB octets (≈31K caractères, dépassant la limite de 25K caractères), 93 descriptions de 400-900 caractères chacune, tronqué silencieusement au démarrage, les entrées ⭐⭐⭐ de fin ont été ignorées → lors d'une enquête, un mécanisme fonctionnant comme conçu a été interprété à tort comme une vulnérabilité. Leçon : une description trop détaillée n'est pas toujours meilleure ; un excès de détails peut faire sauter l'index et nuire au ciblage.
Confusion octets/caractères dans le calibrage : lors de la gestion de la surcharge, le seuil d'avertissement a été fixé à 32KB en octets (wc -c), alors que le harnais utilise les caractères (3 octets par caractère chinois) → le seuil en octets donnait l'impression d'avoir de la marge, et l'index a été de nouveau tronqué. Leçon : pour se synchroniser avec le harnais, il faut utiliser la même unité ; pour le monitoring, utiliser wc -m.

Modes opératoires

Mode 1 : Évaluation de candidats (plusieurs candidats, besoin de filtrage)

Scénarios de déclenchement (plusieurs candidats → besoin du Mode 1 pour filtrer) :

Développement d'une fonctionnalité terminé / Long debug terminé / Revue de conformité terminée
Gestion d'abus terminée (plusieurs points de jugement + leçons)
Incident de sécurité terminé / Localisation de panne terminée
L'utilisateur dit "Note ça" (flou, sans préciser quel piège)

Un seul élément spécifique → aller directement en Mode 2 : l'utilisateur dit "Note le bug wildcard d'aujourd'hui" / "Note le manuel de panne pour la fuite de connexion" → déjà un élément spécifique → Mode 2, pas Mode 1.

Étapes :

Revoir les points clés de la session actuelle (corrections de l'utilisateur, découvertes de la revue de conformité, bugs inattendus, requêtes de référence sectorielle, conclusions non évidentes d'une décision unique)
Appliquer l'arbre de décision de la Règle 2 à chaque point, filtrer ceux qui méritent d'être notés
Pour chaque candidat, juger :
- Un fichier mémoire existe-t-il déjà sur le sujet ? (grep dans l'index MEMORY.md) → si oui, aller en Mode 3 (mise à jour), sinon en Mode 2 (création)
- Le contenu à ajouter dépasse-t-il le seuil de division de la Règle 6 ? → créer un nouveau fichier
- Devrait-il aller dans CLAUDE.md plutôt que dans la mémoire ? (voir tableau ci-dessous)
Confirmer la liste avec l'utilisateur : lister les candidats "suggérés pour ajout / suggérés pour mise à jour / suggérés pour division", attendre la confirmation de l'utilisateur avant d'écrire

Frontière mémoire vs CLAUDE.md :

Type de contenu	Où le mettre
Piège spécifique appris (bug SDK, limitation de plateforme, données sectorielles)	mémoire `feedback_*`
Référence approfondie / Méthode standard / Documentation de processus	mémoire `reference_*`
Faits d'état (travail en cours, configuration temporaire, instantané d'architecture actuel)	mémoire `project_*`
Règles à respecter à chaque session (commandes, stack technique, préférences de collaboration)	CLAUDE.md
Règles nécessaires uniquement lors de la manipulation de fichiers spécifiques	`.claude/rules/*.md` avec frontmatter `paths`

Mode 2 : Créer une mémoire (processus standard)

Étape 0 : D'abord vérifier le routage de proximité (Règle 2, quatre niveaux)

Avant d'écrire, confirmer que ça mérite vraiment d'aller dans la mémoire : fichier unique → commentaire en ligne ; contrat pour un groupe de fichiers → .claude/rules+paths ; scénario/transversal/piège de plateforme → alors seulement dans la mémoire. Les feedbacks liés à un fichier sont par défaut SPLIT (le cœur dans un commentaire, la mémoire ne garde que le principe transversal + un pointeur). Voir la Règle 2 pour plus de détails.

Étape 1 : Déterminer le type

Type	Quand l'utiliser	Informations obligatoires
feedback	Piège appris (bug SDK, limitation de plateforme, préférence utilisateur)	Raison (pourquoi cette conclusion) + Quand le réutiliser (scénario de déclenchement)
reference	Référence approfondie / Méthode standard / Référence sectorielle / Pipeline réutilisable	Pas de section raison obligatoire (descriptif)
project	Faits d'état (instantané d'architecture, travail en cours, analyse économique)	Pas de section raison obligatoire (état)

Forme de présentation des informations obligatoires pour feedback (une seule suffit) :

Section séparée : ## Why ou équivalent en anglais ## Root cause / en français ## Raison / ## Leçon / ## Pourquoi (l'audit accepte tout)
En ligne en gras : **Why**: / **Raison**: (aussi pour les courtes conclusions)
En ligne dans la description ou dans le titre ## (si la conclusion elle-même implique déjà la raison + le moment de réutilisation, par exemple un tableau ❌/✅)

Information "Quand le réutiliser" : peut être une section séparée ## Comment appliquer, ou bien la description contient des mots-clés de scénario (par exemple, tabulation / mutation suggère déjà le scénario de déclenchement).

Étape 2 : Nom du fichier

<type>_<sujet>[_<modificateur>].md tout en minuscules avec underscores :

✅ feedback_supabase_from_deadlock.md
✅ reference_supabase_egress_favorites_refactor.md
❌ feedback-supabase-deadlock.md (a utilisé des traits d'union)
❌ FeedbackSupabaseDeadlock.md (CamelCase)
❌ _schema.md (commence par un underscore, sera traité comme fichier caché, et Claude ne le lira pas automatiquement)

Étape 3 : Écrire le frontmatter

---
name: slug-en-kebab-case
description: Mots-clés de scénario + conclusion centrale
type: feedback | reference | project       # À plat (recommandé)
# ou :
# metadata:
#   type: feedback | reference | project   # Imbriqué (écriture compatible)
---

Emplacement du champ type : type: à plat (recommandé) ou metadata.type: imbriqué, les deux sont acceptés. Le script d'audit reconnaît les deux. Pour les nouveaux fichiers, privilégier le format à plat pour s'aligner sur la majorité existante.

Critères de qualité de la description :

✅ Bonne description	❌ Mauvaise description
`Mutation supabase.from() côté navigateur avec interblocage après changement d'onglet, utiliser fetch() pour appeler l'API REST`	`Problèmes liés à Supabase`
`Échec des transformations d'images CF avec cache de 7 jours / cf-resized err= / motif de retry FavoriteCard`	`Les images ne s'affichent parfois pas`
`Les politiques RLS doivent être encapsulées avec (SELECT auth.uid()), sinon évaluées à chaque ligne`	`Optimisation des performances RLS`

Critère : en lisant la description, Claude peut-il immédiatement savoir "c'est la conclusion Y à consulter pour le scénario X" ?

Étape 4 : Écrire le corps

Classe feedback (doit contenir raison + moment de réutilisation) :

# Titre (Quoi — en une phrase)

[Conclusion centrale + 1-2 paragraphes de contexte]

## Why (ou équivalent : ## Raison / ## Leçon / ## Pourquoi)

[Pourquoi cette conclusion — le piège spécifique rencontré, les découvertes de la revue de conformité, les préférences utilisateur]
**Pourquoi c'est obligatoire** : sans section raison, la prochaine fois qu'on discutera de la même décision, on risque d'arriver à la même conclusion erronée.

## Comment appliquer (peut être omis si la description contient déjà des mots-clés de scénario)

[Quand réutiliser cette entrée — scénario de déclenchement, liste de vérification, étapes pour éviter le piège]

Classes reference / project : pas de structure de section obligatoire, organiser naturellement par sujet.

Étape 5 : Ajouter à l'index MEMORY.md

Choisir un groupe existant, ne pas créer de nouveau groupe
Ajouter la description à la position correspondante dans le groupe (haute importance avec ⭐⭐ / ⭐⭐⭐ en gras)
Sujet transversal : ajouter à la fin de la description (voir aussi [[autre-fichier]])

Mode 3 : Mettre à jour une mémoire existante (prioritaire sur la création)

Étape 1 : Utiliser grep pour confirmer l'appartenance au sujet existant

grep -l "<mot-clé>" memory/*.md

Étape 2 : Décider du mode de mise à jour

Situation	Comment mettre à jour
Nouvelles données / nouveau cas complétant la conclusion existante	Ajouter une section ou une section de changelog dans le corps
Conclusion existante réfutée	Ajouter `⚠️ Remplacé par [[nouveau-slug-fichier]]` en haut de l'ancien fichier, et dans le nouveau fichier, écrire "Remplace quelle partie de [[ancien]]"
Seulement la description est peu claire	Modifier l'index MEMORY.md, ne pas toucher au fichier lui-même (sauf si on ajoute aussi du contenu)

Étape 3 : Synchroniser MEMORY.md

Si la description a été modifiée, la ligne correspondante dans MEMORY.md doit aussi être modifiée.

Mode 4 : Changement structurel (modifier le schéma / ajouter un nouveau type / modifier les groupes)

Liste des pièges déjà rencontrés à lire impérativement :

Ne pas essayer le hook if: "Write(memory/*.md)" avec une syntaxe glob — if: est une règle de permission, pas un glob de fichier, déjà vérifié comme inefficace
Ne pas utiliser exit 2 pour bloquer le hook — déjà vérifié comme cassant les flux batch de pré-déploiement (Claude n'a pas de mécanisme de reprise automatique)
Ne pas mettre la source faisant autorité du schéma dans un fichier commençant par _schema.md — Claude ne lit pas les fichiers avec préfixe underscore
Ne pas configurer de hook dans .claude/settings.json du projet — ce dossier est généralement dans .gitignore, n'est pas dans git et n'est pas partagé entre worktrees
Lors de l'ajout d'un nouveau champ obligatoire, synchroniser 3 endroits : (a) cette compétence, section "Mode 2 → Étape 3" (b) section récapitulative en haut de MEMORY.md (c) liste des champs dans le script audit-memory.sh
Avant de modifier un hook/ajouter une contrainte, exécuter bash scripts/audit-memory.sh pour voir le taux de conformité actuel — une action ferme n'est nécessaire que si <95 %, ≥95 % maintenir un avertissement doux
La surveillance de la taille de MEMORY.md doit être en caractères (wc -m) pas en octets (wc -c) — la limite native (200 lignes/25K caractères) est mesurée en caractères ; le chinois fait 3 octets par caractère, un calibrage en octets entraînerait une troncature silencieuse (voir l'exemple historique dans la Règle 6)

Processus de modification du schéma :

Exécuter l'audit pour obtenir la base de référence actuelle
Concevoir le changement (modifier cette compétence + le hub du projet)
Vérifier si les mémoires existantes violent massivement la nouvelle règle (>10 % → reporter, d'abord migrer selon la nouvelle règle)
Mettre à jour la section récapitulative de MEMORY.md en synchronisation
Modifier la liste des champs du script d'audit
Réexécuter l'audit pour voir le nouveau taux de conformité

Mode 5 : Bootstrap sans mémoire (nouveau projet)

Lorsque l'utilisateur dit "commencer à construire la mémoire" dans un projet sans système de mémoire :

Étape 1 : Confirmer le chemin du répertoire de mémoire automatique

Claude Code crée automatiquement ~/.claude/projects/<slug-du-projet>/memory/, où <slug-du-projet> = le chemin absolu du projet avec / remplacé par -. Exemples :

Projet /Users/alice/Project/myapp → slug -Users-alice-Project-myapp

Si Claude Code a déjà créé de la mémoire automatique pour ce projet, le répertoire existera. Vérification : ls ~/.claude/projects/ | grep <nom-du-projet>.

Étape 2 : Créer l'index MEMORY.md

Modèle pour le haut (peut être compressé à ~25 lignes) :

# Mémoire du projet <nom-du-projet>

## ⭐⭐⭐ Aide-mémoire pour écrire dans la mémoire (règles strictes)
- Nom de fichier : `<type>_<sujet>.md` tout en minuscules avec underscore ; type ∈ {feedback, reference, project}
- Frontmatter obligatoire : name / description / type
- Les feedbacks doivent contenir une section ## Why (ou équivalent : ## Raison / ## Leçon / ## Pourquoi)
- Style de description : mots-clés de scénario + conclusion centrale (une ligne ≤160 caractères)
- S'il existe déjà un fichier sur le même sujet → mettre à jour, ne pas en créer un nouveau (sauf dépassement du seuil de la Règle 6 → diviser)
- Limite stricte de cet index : les 200 premières lignes ou 25K caractères (le premier atteint l'emporte), au-delà, troncature silencieuse
- Méthode détaillée : compétence memory-management

## ⭐ Liste des sujets du projet
(Actuellement vide — des groupes seront ajoutés ultérieurement par thème)

Étape 3 : Seuils d'évolution des groupes (structure déterminée par le nombre de fichiers)

Nombre de fichiers mémoire	Structure recommandée
< 15	Liste plate, sans groupe (une seule liste suffit, les groupes fragmenteraient inutilement)
15-25	Introduire 3-5 grands groupes (agrégation par thème)
> 25	Groupes matures, geler les groupes interdire la création de nouveaux, rattacher les nouvelles entrées aux groupes existants (sujets transversaux avec `(voir aussi X)`)

Étape 4 : Ajouter un protocole Mémoire en haut de CLAUDE.md (3-5 lignes)

## Gestion de la mémoire
Pour toute écriture / mise à jour / modification de schéma de mémoire → utiliser la compétence `memory-management`.
- Règle d'aide-mémoire : section ⭐⭐⭐ en haut de MEMORY.md
- Taux de conformité santé : `bash scripts/audit-memory.sh` (optionnel, voir les templates de la compétence/)

Étape 5 : Réutiliser les méthodes générales de cette compétence

Ne pas copier le contenu de la compétence dans le projet. La compétence est au niveau utilisateur, tous les projets partagent une seule copie des méthodes. Le projet ne contient que son état spécifique (listes de groupes / tâches / pièges propres au projet).

Spécifications du schéma (source faisant autorité)

Nommage des fichiers

<type>_<sujet>[_<modificateur>].md tout en minuscules avec underscore, type ∈ {feedback, reference, project}

Frontmatter obligatoire

---
name: slug-en-kebab-case
description: Mots-clés de scénario + conclusion centrale
type: feedback | reference | project       # À plat (recommandé)
# ou :
# metadata:
#   type: feedback | reference | project   # Imbriqué (compatible)
---

Le script d'audit reconnaît les deux. Pour les nouveaux fichiers, privilégier le format à plat.

Informations obligatoires pour feedback

Section raison (une au choix) :

## Why ou titre équivalent en anglais ## Root cause / en français ## Raison / ## Leçon / ## Pourquoi (peut être avec : anglais ou : français)
En ligne en gras **Why**: / **Raison**: etc.

Quand le réutiliser (une au choix) :

Section séparée ## Comment appliquer
Description contenant des mots-clés de scénario (implique le scénario de déclenchement)

Style de description

Mélange (mots-clés de scénario + conclusion centrale), pour que Claude puisse cibler "scénario X → conclusion Y" via la description. Une ligne ≤ ~160 caractères — les détails vont dans le fichier mémoire ou les commentaires de code (limite stricte de l'index = 200 lignes/25 000 caractères, le premier atteint l'emporte, au-delà troncature silencieuse)

Format de la ligne d'index

-[étiquette courte](nom complet du fichier.md) — hook. Étiquette courte = nom du fichier sans le préfixe de type et avec des traits d'union (ex. [interblocage-supabase](feedback_supabase_from_deadlock.md)) ; pour les entrées longue traîne et peu fréquentes, utiliser une ligne agrégée (sous-thème → [a](f1.md) · [b](f2.md))

Gel des groupes

Choisir parmi les grands groupes existants, interdire la création de nouveaux groupes. Pour les sujets ambigus, utiliser (voir aussi hub-X) comme référence croisée.

Erreurs courantes

Erreur	Correct
Écrire une description vague de mémoire : "Problème Supabase"	Écrire mots-clés de scénario + conclusion : "Interblocage supabase.from() lors du changement d'onglet, utiliser fetch"
Feedback ne contenant que "quoi"	Feedback doit toujours avoir ## Why, pour protéger contre une remise en question future
Créer un deuxième fichier pour le même sujet	Privilégier la mise à jour d'un fichier existant, la création fragmente
Créer un groupe "Problèmes réseau" pour une seule entrée	Utiliser un groupe existant, les sujets transversaux avec `(voir aussi X)`
Mettre les spécifications du schéma dans un fichier de mémoire	Le schéma est dans cette compétence, la mémoire contient les faits
Utiliser hook exit 2 pour bloquer de force	Utiliser un avertissement doux (stderr + exit 0) ou un audit postérieur

Auto-vérification (après avoir écrit)

Intégration d'outils

Le script d'audit est un outil de projet optionnel.

Si scripts/audit-memory.sh existe à la racine du projet → exécuter :

bash scripts/audit-memory.sh  # voir le taux de conformité / lister les violations / lister les entrées non consultées depuis 30 jours

Sortie : nombre total de fichiers / frontmatter manquant / Why manquant / liens cassés MEMORY.md / non consulté depuis 30 jours / taille de MEMORY.md (caractères + lignes, par rapport à la limite native de 200 lignes/25K caractères) / taux de conformité en %. Taux de conformité cible ≥ 95 %.

Si aucun script d'audit n'existe → créer à partir du modèle :

# Modèle générique fourni avec la compétence au niveau utilisateur
cp ~/.claude/skills/memory-management/templates/audit-memory.template.sh \
   <votre-projet>/scripts/audit-memory.sh
# Modifier MEMORY_DIR pour pointer vers le répertoire de mémoire automatique de votre projet
chmod +x <votre-projet>/scripts/audit-memory.sh
bash <votre-projet>/scripts/audit-memory.sh

Chemin par défaut de la mémoire automatique : ~/.claude/projects/<slug-du-projet>/memory/, voir Mode 5, Étape 1.

Demander à votre IA préférée

Documentation