Quando Claude usa la versione vecchia

Cos'è e perché conta

Chiedi a Claude una funzione nuova, lui la scrive sicuro di sé, e l'app non parte più. Guardi l'errore e scopri che ha usato un'opzione che nella versione installata della libreria non esiste più, o un file con il nome vecchio. Il codice sembrava giusto. Ed era giusto, per la libreria di qualche mese fa.

stalemap serve a questo. Guarda le versioni delle librerie del tuo progetto, trova cosa è cambiato dopo la data fino a cui Claude ha studiato e glielo dice in un elenco corto, prima che cominci. Poi, dopo ogni modifica, controlla il codice: se Claude ha usato una cosa vecchia, gli dice cosa usare adesso.

È per chi costruisce con Claude Code un'app in JavaScript o TypeScript, con librerie che cambiano spesso. Una cosa va detta subito: non è di Anthropic. È un progetto open source della community, con licenza MIT, nato il 19 ottobre 2026. È giovane e lo segue una persona sola: trattalo come un aiuto in più, non come una garanzia.

1. Perché Claude scrive codice vecchio

Un modello come Claude impara da una montagna di testi e di codice raccolti fino a una certa data. Si chiama data di taglio dell'addestramento, in inglese training cutoff. Quello che succede dopo, lui non lo sa.

Le librerie invece non si fermano. Esce l'ultima versione, un'opzione sparisce, una funzione cambia nome, un file si chiama in un altro modo. Claude non lo sa e usa i nomi che ha visto mille volte quando studiava. Il README di stalemap fa tre esempi:

• maxSteps, un'opzione di streamText nell'AI SDK, che le versioni nuove non accettano più.
• required_error, un'opzione di zod che le versioni nuove hanno cambiato.
• middleware.ts in Next.js, che nelle versioni nuove si chiama proxy.ts.

stalemap fa un conto semplice. Legge quale modello stai usando e trova la sua data di taglio. Per ogni libreria che il tuo codice importa, stima quale versione il modello conosceva: la più recente uscita almeno 30 giorni prima di quella data. Poi la confronta con la versione che hai installato davvero, guardando i tipi della libreria e le note di rilascio, cioè l'elenco delle novità che pubblica chi la mantiene. Quello che è cambiato in mezzo diventa una nota.

2. Installalo in Claude Code

Ti servono Node.js 20 o successivo e un progetto JavaScript o TypeScript con un package.json. Poi, dentro una sessione di Claude Code, scrivi due comandi:

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

1. Il primo aggiunge il marketplace di stalemap, cioè il catalogo da cui Claude Code prende il plugin. Lo fai una volta sola.
2. Il secondo non installa subito: apre il pannello /plugin sulla scheda del plugin, dove scegli dove attivarlo, per esempio solo per te o per tutto il progetto.
3. Prima di confermare, leggi la scheda. Un plugin può far girare comandi sul tuo computer e un server MCP: è giusto sapere cosa installi.
4. Per spegnerlo o toglierlo più avanti, apri /plugin e vai nella scheda Installed.

Il plugin aggiunge due hook, cioè comandi che Claude Code lancia da solo in un momento preciso: uno a inizio sessione e uno dopo ogni modifica. In più un server MCP, con cui Claude può cercare le modifiche di una libreria con parole sue, e due skill. Li vediamo uno alla volta.

3. Cosa vede Claude a inizio sessione

Quando apri una sessione, stalemap mette nel contesto di Claude le note sulle librerie cambiate, calcolate per il modello di quella sessione. Lo rifà dopo /clear e dopo la compattazione, quando Claude Code riassume una conversazione lunga. Non scrive nessun file: le note vivono solo nella sessione.

Le note sono un elenco corto e ordinato. Prima vengono le modifiche che toccano quello che il tuo progetto usa davvero: le funzioni che importi, le opzioni di configurazione, i nomi dei file. Ogni nota dice cosa è stato tolto o rinominato e cosa usare al suo posto.

Se vuoi le note nel CLAUDE.md

Con la skill /stalemap:sync le note finiscono anche nel CLAUDE.md o nell'AGENTS.md, il file con le regole del progetto. Così restano nel repository e le vede chi lavora con te. Il blocco sta tra due segni, <!-- stalemap:start --> e <!-- stalemap:end -->, e il resto del file non lo tocca.

Un dettaglio: Claude Code legge il CLAUDE.md, non l'AGENTS.md. Se le tue note stanno nell'AGENTS.md, aggiungi al CLAUDE.md la riga @AGENTS.md.

4. Il controllo dopo ogni modifica

Ogni volta che Claude scrive o modifica un file, parte il secondo hook, la guardia. Lancia il controllo dei tipi del tuo progetto, cioè tsc, il compilatore di TypeScript, e riporta a Claude quello che trova, in quest'ordine:

1. Gli errori che vengono da una libreria cambiata dopo la data di taglio, con la nota che dice come correggerli.
2. Le cose che compilano ancora ma sono cambiate: chiavi di configurazione e membri spostati, file rinominati, come middleware.ts diventato proxy.ts.
3. Gli altri errori del compilatore, nel file modificato e in quelli che lo usano. Questi non dicono che una libreria è cambiata: sono errori normali.

Così Claude vede l'errore e la correzione subito, mentre lavora, invece di scoprirlo tu quando apri l'app. Un limite da sapere: il codice vecchio che compila ancora la guardia lo trova solo in parte. Il resto lo prende solo se c'è una nota che ne parla.

Prima di aggiornare una libreria

Il plugin ha anche una skill, upgrade, che dice a Claude di cercare le modifiche di un pacchetto prima di usarlo o aggiornarlo. Io glielo chiedo così:

Voglio aggiornare [nome della libreria] all'ultima versione. Prima di toccare il codice, usa stalemap per cercare cosa è cambiato in questa libreria: funzioni tolte o rinominate, opzioni nuove obbligatorie, file con un nome nuovo.
Poi fammi un elenco dei punti del mio progetto che vanno cambiati, con il nome del file per ognuno.
Non modificare niente finché non ti dico ok.

E quando l'aggiornamento è fatto:

Ho aggiornato [nome della libreria]. Lancia il controllo dei tipi e i test, e dimmi cosa si è rotto e perché. Correggi una cosa alla volta.

5. Dal terminale e nei controlli automatici

stalemap si usa anche senza il plugin, dal terminale, nella cartella del progetto:

• npx stalemap: un'anteprima. Ti mostra cosa è cambiato e il blocco che scriverebbe.
• npx stalemap sync: scrive il blocco nel CLAUDE.md o nell'AGENTS.md.
• npx stalemap check: controlla che il blocco ci sia e sia aggiornato.

check è pensato per la CI, cioè i controlli automatici che girano a ogni push, per esempio con GitHub Actions. Se il blocco manca o è vecchio, esce con un errore e il controllo fallisce. Così, se qualcuno aggiorna una libreria e si dimentica le note, te ne accorgi subito. Nel README c'è anche una GitHub Action già pronta.

Ricorda che le note occupano spazio nel contesto di Claude, cioè token in più a ogni sessione. Di default stalemap le tiene entro circa 1.800 token e mette prima quelle che riguardano il codice che usi.

6. Cosa esce dal tuo computer

È la parte che controllerei per prima, quindi te la scrivo chiara. Nell'uso base:

• Il tuo codice non esce mai. Quali librerie importi lo guarda sul tuo computer.
• Escono solo nomi e versioni dei pacchetti: vanno al registro di npm, a GitHub per le note di rilascio e a models.dev per le date di taglio dei modelli.
• Non serve una chiave API, e stalemap non ha un server suo né raccoglie telemetria.

Poi ci sono tre opzioni, --llm, --guides ed --examples, che fanno scrivere a Claude riassunti, note dalle guide di aggiornamento ed esempi prima e dopo. Con quelle, a Claude vanno le differenze dei tipi, pezzi delle note di rilascio e i nomi delle funzioni che importi. Il tuo codice no. Ma consumano token: usale quando ti servono, non per abitudine.

Gli errori più comuni

• Installarlo su un progetto Flutter, Python o Swift. Funziona solo con JavaScript e TypeScript.
• Confermare l'installazione senza leggere la scheda del plugin. Fa girare comandi sul tuo computer: guarda prima cosa fa.
• Pensare che sostituisca i test. Le note aiutano, ma a volte Claude le ignora. I test e il controllo dei tipi restano il tuo paracadute.
• Usarlo in un monorepo con più package.json. Per ora ne legge uno solo, senza workspace.
• Accendere --llm, --guides o --examples a ogni giro. Mandano dati a Claude e consumano token.

Checklist

• Il progetto è JavaScript o TypeScript, con un solo package.json
• Ho Node.js 20 o successivo
• Ho letto la scheda del plugin prima di installarlo
• Ho lanciato i due comandi in Claude Code
• Ho guardato le note con npx stalemap
• Se voglio le note nel repository, ho lanciato /stalemap:sync
• Nella CI c'è npx stalemap check
• Uso --llm, --guides ed --examples solo quando servono

Domande frequenti