Quand Claude utilise l'ancienne version

Ce que c'est et pourquoi ça compte

Tu demandes à Claude une nouvelle fonction, il l'écrit sans hésiter, et l'app ne démarre plus. Tu lis l'erreur et tu découvres qu'il a utilisé une option qui n'existe plus dans la version installée de la bibliothèque, ou un fichier avec son ancien nom. Le code avait l'air juste. Et il l'était, pour la bibliothèque d'il y a quelques mois.

C'est à ça que sert stalemap. Il regarde les versions des bibliothèques de ton projet, trouve ce qui a changé après la date jusqu'à laquelle Claude a appris, et lui donne une courte liste avant qu'il commence. Ensuite, après chaque modification, il vérifie le code : si Claude a utilisé quelque chose de dépassé, il lui dit quoi utiliser maintenant.

C'est pour celles et ceux qui construisent une app en JavaScript ou TypeScript avec Claude Code, sur des bibliothèques qui changent souvent. Une chose à dire tout de suite : ce n'est pas un produit d'Anthropic. C'est un projet open source de la communauté, sous licence MIT, créé le 19 octobre 2026. Il est jeune et maintenu par une seule personne : vois-le comme une aide en plus, pas comme une garantie.

1. Pourquoi Claude écrit du code dépassé

Un modèle comme Claude apprend à partir d'une montagne de textes et de code collectés jusqu'à une certaine date. Cette date s'appelle la date limite d'entraînement, en anglais training cutoff. Ce qui se passe après, Claude ne le sait pas.

Les bibliothèques, elles, ne s'arrêtent pas. La dernière version sort, une option disparaît, une fonction change de nom, un fichier s'appelle autrement. Claude ne le sait pas et utilise les noms qu'il a vus mille fois pendant son apprentissage. Le README de stalemap donne trois exemples :

• maxSteps, une option de streamText dans l'AI SDK, que les nouvelles versions n'acceptent plus.
• required_error, une option de zod que les nouvelles versions ont modifiée.
• middleware.ts dans Next.js, qui s'appelle proxy.ts dans les nouvelles versions.

stalemap fait un calcul simple. Il lit quel modèle tu utilises et trouve sa date limite. Pour chaque bibliothèque que ton code importe, il estime quelle version le modèle connaissait : la plus récente sortie au moins 30 jours avant cette date. Puis il la compare avec la version que tu as vraiment installée, en regardant les types de la bibliothèque et ses notes de version, c'est-à-dire la liste des nouveautés que publient ses mainteneurs. Ce qui a changé entre les deux devient une note.

2. Installe-le dans Claude Code

Il te faut Node.js 20 ou plus récent et un projet JavaScript ou TypeScript avec un package.json. Ensuite, dans une session Claude Code, tape deux commandes :

/plugin marketplace add Umair/stalemap
/plugin install stalemap@stalemap

1. La première ajoute le marketplace de stalemap, c'est-à-dire le catalogue où Claude Code prend le plugin. Tu ne le fais qu'une fois.
2. La seconde n'installe pas tout de suite : elle ouvre le panneau /plugin sur la fiche du plugin, où tu choisis où l'activer, par exemple pour toi seul ou pour tout le projet.
3. Avant de confirmer, lis la fiche. Un plugin peut lancer des commandes et un serveur MCP sur ton ordinateur : mieux vaut savoir ce que tu installes.
4. Pour le désactiver ou le retirer plus tard, ouvre /plugin et va dans l'onglet Installed.

Le plugin ajoute deux hooks, c'est-à-dire des commandes que Claude Code lance tout seul à un moment précis : un au début de la session et un après chaque modification. En plus, un serveur MCP, avec lequel Claude peut chercher les changements d'une bibliothèque avec ses propres mots, et deux skills. On les voit un par un.

3. Ce que Claude voit au début d'une session

Quand tu ouvres une session, stalemap met dans le contexte de Claude les notes sur les bibliothèques qui ont changé, calculées pour le modèle de cette session. Il le refait après /clear et après la compaction, quand Claude Code résume une longue conversation. Il n'écrit aucun fichier : les notes n'existent que dans la session.

Les notes forment une liste courte et classée. D'abord viennent les changements qui touchent ce que ton projet utilise vraiment : les fonctions que tu importes, les options de configuration, les noms de fichiers. Chaque note dit ce qui a été retiré ou renommé et quoi utiliser à la place.

Si tu veux les notes dans le CLAUDE.md

Avec la skill /stalemap:sync, les notes vont aussi dans le CLAUDE.md ou l'AGENTS.md, le fichier avec les règles du projet. Comme ça, elles restent dans le dépôt et les personnes qui travaillent avec toi les voient aussi. Le bloc se trouve entre deux repères, <!-- stalemap:start --> et <!-- stalemap:end -->, et le reste du fichier n'est pas touché.

Un détail : Claude Code lit le CLAUDE.md, pas l'AGENTS.md. Si tes notes sont dans l'AGENTS.md, ajoute au CLAUDE.md la ligne @AGENTS.md.

4. La vérification après chaque modification

Chaque fois que Claude écrit ou modifie un fichier, le second hook se lance : le garde. Il lance la vérification des types de ton projet, c'est-à-dire tsc, le compilateur TypeScript, et rapporte à Claude ce qu'il trouve, dans cet ordre :

1. Les erreurs qui viennent d'une bibliothèque qui a changé après la date limite, avec la note qui dit comment les corriger.
2. Ce qui compile encore mais a changé : clés de configuration et membres déplacés, fichiers renommés, comme middleware.ts devenu proxy.ts.
3. Les autres erreurs du compilateur, dans le fichier modifié et dans ceux qui l'utilisent. Celles-là ne disent pas qu'une bibliothèque a changé : ce sont des erreurs normales.

Comme ça, Claude voit l'erreur et la correction tout de suite, pendant qu'il travaille, au lieu que tu le découvres en ouvrant l'app. Une limite à connaître : le code dépassé qui compile encore, le garde ne le trouve qu'en partie. Le reste, il ne l'attrape que si une note en parle.

Avant de mettre à jour une bibliothèque

Le plugin a aussi une skill, upgrade, qui dit à Claude de chercher les changements d'un paquet avant de l'utiliser ou de le mettre à jour. Moi, je lui demande comme ça :

Je veux mettre à jour [nom de la bibliothèque] vers la dernière version. Avant de toucher au code, utilise stalemap pour chercher ce qui a changé dans cette bibliothèque : fonctions retirées ou renommées, nouvelles options obligatoires, fichiers avec un nouveau nom.
Ensuite, fais-moi une liste des endroits de mon projet à changer, avec le nom du fichier pour chacun.
Ne modifie rien tant que je ne t'ai pas dit ok.

Et une fois la mise à jour faite :

J'ai mis à jour [nom de la bibliothèque]. Lance la vérification des types et les tests, et dis-moi ce qui a cassé et pourquoi. Corrige une chose à la fois.

5. Depuis le terminal et dans les vérifications automatiques

On peut aussi utiliser stalemap sans le plugin, depuis le terminal, dans le dossier du projet :

• npx stalemap : un aperçu. Il montre ce qui a changé et le bloc qu'il écrirait.
• npx stalemap sync : écrit le bloc dans le CLAUDE.md ou l'AGENTS.md.
• npx stalemap check : vérifie que le bloc est là et à jour.

check est fait pour la CI, c'est-à-dire les vérifications automatiques qui tournent à chaque push, par exemple avec GitHub Actions. Si le bloc manque ou n'est plus à jour, il sort avec une erreur et la vérification échoue. Comme ça, si quelqu'un met à jour une bibliothèque et oublie les notes, tu le vois tout de suite. Le README propose aussi une GitHub Action toute prête.

N'oublie pas que les notes prennent de la place dans le contexte de Claude, donc des tokens en plus à chaque session. Par défaut, stalemap les garde autour de 1 800 tokens et met en premier celles qui concernent le code que tu utilises.

6. Ce qui sort de ton ordinateur

C'est la partie que je vérifierais en premier, alors je te l'écris clairement. Dans l'usage de base :

• Ton code ne sort jamais. Les bibliothèques que tu importes, il les repère sur ton ordinateur.
• Seuls les noms et versions des paquets sortent : vers le registre npm, vers GitHub pour les notes de version et vers models.dev pour les dates limites des modèles.
• Pas besoin de clé API, et stalemap n'a pas de serveur à lui et ne collecte aucune télémétrie.

Il y a ensuite trois options, --llm, --guides et --examples, qui font écrire à Claude des résumés, des notes tirées des guides de mise à jour et des exemples avant/après. Avec elles, Claude reçoit les différences de types, des extraits des notes de version et les noms des fonctions que tu importes. Pas ton code. Mais elles consomment des tokens : active-les quand tu en as besoin, pas par habitude.

Les erreurs les plus courantes

• L'installer sur un projet Flutter, Python ou Swift. Il ne marche qu'avec JavaScript et TypeScript.
• Confirmer l'installation sans lire la fiche du plugin. Il lance des commandes sur ton ordinateur : regarde d'abord ce qu'il fait.
• Penser qu'il remplace les tests. Les notes aident, mais Claude les ignore parfois. Les tests et la vérification des types restent ton filet de sécurité.
• L'utiliser dans un monorepo avec plusieurs package.json. Pour l'instant, il n'en lit qu'un, sans workspaces.
• Activer --llm, --guides ou --examples à chaque fois. Ils envoient des données à Claude et consomment des tokens.

Check-list

• Le projet est en JavaScript ou TypeScript, avec un seul package.json
• J'ai Node.js 20 ou plus récent
• J'ai lu la fiche du plugin avant de l'installer
• J'ai lancé les deux commandes dans Claude Code
• J'ai regardé les notes avec npx stalemap
• Si je veux les notes dans le dépôt, j'ai lancé /stalemap:sync
• Ma CI lance npx stalemap check
• J'utilise --llm, --guides et --examples seulement quand j'en ai besoin

Questions fréquentes