Quando o Claude usa a versão antiga

O que é e porque importa

Pedes ao Claude uma funcionalidade nova, ele escreve-a cheio de certeza, e a app deixa de arrancar. Lês o erro e descobres que usou uma opção que já não existe na versão instalada da biblioteca, ou um ficheiro com o nome antigo. O código parecia certo. E estava, para a biblioteca de há uns meses.

É para isso que serve o stalemap. Olha para as versões das bibliotecas do teu projeto, encontra o que mudou depois da data até à qual o Claude aprendeu e dá-lhe uma lista curta antes de começar. Depois, a cada alteração, verifica o código: se o Claude usou algo desatualizado, diz-lhe o que usar agora.

É para quem constrói com o Claude Code uma app em JavaScript ou TypeScript, com bibliotecas que mudam muitas vezes. Uma coisa logo à partida: não é da Anthropic. É um projeto open source da comunidade, com licença MIT, criado a 19 de outubro de 2026. É jovem e mantido por uma só pessoa: trata-o como uma ajuda extra, não como uma garantia.

1. Porque é que o Claude escreve código desatualizado

Um modelo como o Claude aprende com uma montanha de textos e código recolhidos até uma certa data. Essa data chama-se data de corte do treino, em inglês training cutoff. O que acontece depois, o Claude não sabe.

As bibliotecas, pelo contrário, não param. Sai a versão mais recente, uma opção desaparece, uma função muda de nome, um ficheiro passa a chamar-se de outra forma. O Claude não sabe e usa os nomes que viu mil vezes quando aprendia. O README do stalemap dá três exemplos:

• maxSteps, uma opção de streamText no AI SDK, que as versões novas já não aceitam.
• required_error, uma opção do zod que as versões novas alteraram.
• middleware.ts no Next.js, que nas versões novas se chama proxy.ts.

O stalemap faz uma conta simples. Lê que modelo estás a usar e encontra a sua data de corte. Para cada biblioteca que o teu código importa, estima que versão o modelo conhecia: a mais recente publicada pelo menos 30 dias antes dessa data. Depois compara-a com a versão que tens mesmo instalada, olhando para os tipos da biblioteca e para as notas de versão, ou seja, a lista de novidades que quem a mantém publica. O que mudou pelo meio passa a ser uma nota.

2. Instala-o no Claude Code

Precisas do Node.js 20 ou mais recente e de um projeto JavaScript ou TypeScript com um package.json. Depois, dentro de uma sessão do Claude Code, escreve dois comandos:

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

1. O primeiro adiciona o marketplace do stalemap, ou seja, o catálogo de onde o Claude Code vai buscar o plugin. Fazes isto uma só vez.
2. O segundo não instala logo: abre o painel /plugin na ficha do plugin, onde escolhes onde o ativar, por exemplo só para ti ou para o projeto todo.
3. Antes de confirmar, lê a ficha. Um plugin pode correr comandos e um servidor MCP no teu computador: convém saber o que estás a instalar.
4. Para o desligar ou remover mais tarde, abre /plugin e vai ao separador Installed.

O plugin adiciona dois hooks, ou seja, comandos que o Claude Code corre sozinho num momento preciso: um no início da sessão e outro depois de cada alteração. Adiciona ainda um servidor MCP, com o qual o Claude pode procurar as alterações de uma biblioteca por palavras suas, e duas skills. Vemos um de cada vez.

3. O que o Claude vê no início da sessão

Quando abres uma sessão, o stalemap põe no contexto do Claude as notas sobre as bibliotecas que mudaram, calculadas para o modelo dessa sessão. Volta a fazê-lo depois de /clear e depois da compactação, quando o Claude Code resume uma conversa longa. Não escreve nenhum ficheiro: as notas só existem na sessão.

As notas são uma lista curta e ordenada. Primeiro vêm as alterações que tocam no que o teu projeto usa mesmo: as funções que importas, as opções de configuração, os nomes dos ficheiros. Cada nota diz o que foi removido ou mudou de nome e o que usar no lugar.

Se quiseres as notas no CLAUDE.md

Com a skill /stalemap:sync as notas vão também para o CLAUDE.md ou para o AGENTS.md, o ficheiro com as regras do projeto. Assim ficam no repositório e quem trabalha contigo também as vê. O bloco fica entre duas marcas, <!-- stalemap:start --> e <!-- stalemap:end -->, e o resto do ficheiro não é tocado.

Um pormenor: o Claude Code lê o CLAUDE.md, não o AGENTS.md. Se as tuas notas estão no AGENTS.md, acrescenta ao CLAUDE.md a linha @AGENTS.md.

4. A verificação depois de cada alteração

Sempre que o Claude escreve ou altera um ficheiro, arranca o segundo hook, o guarda. Corre a verificação de tipos do teu projeto, ou seja, o tsc, o compilador de TypeScript, e reporta ao Claude o que encontra, por esta ordem:

1. Os erros que vêm de uma biblioteca que mudou depois da data de corte, com a nota que diz como os corrigir.
2. O que ainda compila mas mudou: chaves de configuração e membros que mudaram de sítio, ficheiros com nome novo, como middleware.ts que passou a proxy.ts.
3. Os outros erros do compilador, no ficheiro alterado e nos que o usam. Estes não dizem que uma biblioteca mudou: são erros normais.

Assim o Claude vê o erro e a correção logo, enquanto trabalha, em vez de seres tu a descobrir quando abres a app. Um limite a saber: o código desatualizado que ainda compila, o guarda só o encontra em parte. O resto só o apanha se houver uma nota que fale disso.

Antes de atualizar uma biblioteca

O plugin tem também uma skill, upgrade, que diz ao Claude para procurar as alterações de um pacote antes de o usar ou atualizar. Eu peço-lhe assim:

Quero atualizar [nome da biblioteca] para a versão mais recente. Antes de mexeres no código, usa o stalemap para procurar o que mudou nesta biblioteca: funções removidas ou com nome novo, opções novas obrigatórias, ficheiros com um nome novo.
Depois faz-me uma lista dos sítios do meu projeto que têm de mudar, com o nome do ficheiro de cada um.
Não alteres nada até eu dizer ok.

E quando a atualização estiver feita:

Atualizei [nome da biblioteca]. Corre a verificação de tipos e os testes, e diz-me o que se partiu e porquê. Corrige uma coisa de cada vez.

5. No terminal e nas verificações automáticas

O stalemap também se usa sem o plugin, no terminal, na pasta do projeto:

• npx stalemap: uma pré-visualização. Mostra o que mudou e o bloco que escreveria.
• npx stalemap sync: escreve o bloco no CLAUDE.md ou no AGENTS.md.
• npx stalemap check: verifica se o bloco existe e está atualizado.

O check é pensado para a CI, ou seja, as verificações automáticas que correm a cada push, por exemplo com o GitHub Actions. Se o bloco faltar ou estiver desatualizado, termina com um erro e a verificação falha. Assim, se alguém atualizar uma biblioteca e se esquecer das notas, dás por isso logo. No README há também uma GitHub Action já pronta.

Lembra-te de que as notas ocupam espaço no contexto do Claude, ou seja, tokens a mais em cada sessão. Por omissão o stalemap mantém-nas em cerca de 1800 tokens e põe primeiro as que dizem respeito ao código que usas.

6. O que sai do teu computador

É a parte que eu verificaria primeiro, por isso escrevo-a de forma clara. No uso básico:

• O teu código nunca sai. Que bibliotecas importas, ele vê no teu próprio computador.
• Só saem nomes e versões dos pacotes: vão para o registo do npm, para o GitHub por causa das notas de versão e para o models.dev por causa das datas de corte dos modelos.
• Não precisas de chave API, e o stalemap não tem servidor próprio nem recolhe telemetria.

Depois há três opções, --llm, --guides e --examples, que põem o Claude a escrever resumos, notas tiradas dos guias de atualização e exemplos de antes e depois. Com elas, o Claude recebe as diferenças de tipos, excertos das notas de versão e os nomes das funções que importas. O teu código não. Mas gastam tokens: usa-as quando precisares, não por hábito.

Os erros mais comuns

• Instalá-lo num projeto Flutter, Python ou Swift. Só funciona com JavaScript e TypeScript.
• Confirmar a instalação sem ler a ficha do plugin. Corre comandos no teu computador: vê primeiro o que faz.
• Achar que substitui os testes. As notas ajudam, mas às vezes o Claude ignora-as. Os testes e a verificação de tipos continuam a ser a tua rede de segurança.
• Usá-lo num monorepo com vários package.json. Por agora só lê um, sem workspaces.
• Ligar --llm, --guides ou --examples em todas as execuções. Enviam dados ao Claude e gastam tokens.

Checklist

• O projeto é JavaScript ou TypeScript, com um só package.json
• Tenho o Node.js 20 ou mais recente
• Li a ficha do plugin antes de o instalar
• Corri os dois comandos no Claude Code
• Vi as notas com npx stalemap
• Se quero as notas no repositório, corri /stalemap:sync
• A CI corre npx stalemap check
• Só uso --llm, --guides e --examples quando são precisos

Perguntas frequentes