La chose la plus coûteuse dans le travail avec un agent est de réexpliquer le contexte. Chaque matin, tu réexpliques les décisions de la veille, tu colles le dernier message de commit, tu rétablis quel bug bloque le déploiement. Multiplie cela par chaque session et le coût caché est de plusieurs heures par semaine, pas des minutes.
STATE.md élimine cette taxe. Un fichier, mis à jour à la fin de chaque session, chargé au début de la suivante. La discipline : avant de fermer une session, passe trois minutes à mettre à jour le fichier. Demain, ces trois minutes en économiseront vingt.
STATE.md contient trois choses, rien de plus.
Décisions : ce que tu as décidé et pourquoi. Sans le pourquoi, ton futur toi rouvrira la décision. "Triggers Postgres au lieu de cron pour le digest quotidien : les triggers sont transactionnels, cron est en concurrence avec le chemin d'écriture."
En cours : ce qui est à moitié fait, suffisamment spécifique pour être transmis. "Migration 014 écrite à /migrations/014_add_subscription_columns.sql mais non appliquée. Doit être exécutée avant que le gestionnaire de webhook ne soit mis en ligne."
Bloqueurs : ce qui empêche d'avancer, y compris ce que tu as essayé. "La signature du webhook Stripe échoue dans l'environnement de test. J'ai essayé le parseur de corps brut, toujours 400. Prochaine étape : vérifier la variable d'environnement dans l'aperçu Vercel."
Limite-le à 60-80 lignes. Quand quelque chose est résolu, supprime-le. Quand quelque chose est livré, archive-le.
La discipline de mise à jour. Ajoute un hook Stop pour te le rappeler :
{
"hooks": {
"Stop": [
{
"command": "echo 'Avant de fermer : mets à jour STATE.md avec les décisions, les éléments en cours et les bloqueurs de cette session.'"
}
]
}
}Le rappel seul ne suffit pas ; l'habitude doit être automatique. Le chemin le plus rapide : fais-le pendant cinq sessions consécutives. À la sixième session, tu te sentiras mal de fermer sans mettre à jour. L'inconfort est le signal que l'habitude est formée.
MEMORY.md est l'index de tout ce qui est durable. Chaque entrée est une ligne pointant vers un fichier séparé. Quatre types :
user_* : faits durables te concernant : fuseau horaire, contexte de carrière, préférences. user_location.md
feedback_* : règles apprises des erreurs, avec un champ de confiance. Commence à 0.3, passe à 0.5 lorsque le motif se répète, promeut à CLAUDE.md à 0.9+. feedback_public_endpoints_need_rate_limits.md
project_* : état et décisions datés pour un projet. Archive-le lorsqu'il est livré. project_stripe_integration_2026_05.md
reference_* : tables de consultation pour les personnes, les outils, les API. reference_neon_db_config.md
Garde chaque ligne d'index sous 200 caractères et l'index sous 200 lignes. Au-delà, les entrées sont tronquées et Claude ne peut pas les voir.
STATE.md est pour maintenant. MEMORY.md est pour toujours. La règle générale : si tu le dirais lors d'un stand-up, cela va dans STATE.md. Si tu l'écrirais dans un wiki ou un document d'intégration, cela va dans un fichier de mémoire. Les stand-ups sont transitoires ; les wikis sont durables.
Lorsqu'un projet est livré et que STATE.md contient encore cinq lignes à son sujet, déplace ces lignes vers un fichier de mémoire project_* daté et efface-les. Le projet n'a pas cessé d'être important ; il a cessé d'être actuel. Cette distinction maintient l'utilité de STATE.md.
Écris l'état, pas un journal. Une entrée de journal : "J'ai travaillé sur l'intégration Stripe. C'était délicat." Une entrée d'état : "Point de terminaison webhook à app/api/webhooks/stripe/route.ts. La vérification de signature fonctionne localement, échoue dans l'aperçu Vercel (mauvais format de corps brut). Prochaine étape : vérifier la configuration du middleware rawBody." L'une donne à la prochaine session un point de départ ; l'autre lui donne un mémoire.
Deux autres anti-modèles : les entrées en cours sans action concrète que pourrait exécuter une nouvelle session, et les entrées en double pour le même sujet à travers les sessions. Fusionne les doublons : un sujet, une entrée, état actuel uniquement.
Une bonne mise à jour de session fait neuf à douze lignes : une décision avec sa justification, un élément en cours avec l'étape suivante, un bloqueur avec ce que tu as essayé.
Mise à l'échelle au-delà de 50 fichiers de mémoire : la couche de résumé. Chaque ligne de pointeur MEMORY.md coûte environ 100-150 jetons. À 200 lignes, cela représente 20-30K jetons de purs pointeurs. La solution : STRATEGY-DIGEST.md, un résumé de 2-3 phrases de chaque document majeur plus un champ "Utiliser quand :" :
## q2-positioning.md
Le positionnement du T2 cible l'activation de l'IA dans les organisations de vente du marché intermédiaire.
Utiliser quand : discuter du client cible, de la tarification ou de la qualification des leads.Claude lit le résumé (environ 3K jetons) et ne charge un document complet que lorsqu'il est pertinent. Pour 25 documents de stratégie, cela représente 3K jetons au lieu de 50K. Le champ "Utiliser quand :" est le mécanisme de routage : écris-le comme une condition de déclenchement spécifique, pas une description du fichier.
STATE.md capture l'état actuel (décisions, en cours, bloqueurs) en moins de 80 lignes ; mets-le à jour à la fin de la session et archive rapidement l'historique. MEMORY.md indexe les connaissances durables en quatre types (utilisateur, feedback, projet, référence), plafonné à 200 lignes. Commence ce soir avec trois lignes : une décision, un élément en cours, un bloqueur. Trois lignes valent mieux que zéro pendant que l'habitude se forme.