Versionamento seguro com Changesets e Claude Code

Claude Code acelera o trabalho de release, mas versionamento não deve ser decidido sem critério. Um breaking change publicado como patch quebra builds de usuários. Um package interno publicado sem querer no npm pode deixar uma marca difícil de remover. Changesets resolve parte desse problema porque registra, no PR, qual package mudou, qual bump precisa e por quê.

Este guia mostra um fluxo prático com Claude Code e Changesets: SemVer, release notes, packages em monorepo, packages privados ou internos, GitHub Actions, riscos de npm publish, qualidade do CHANGELOG e prompts para evitar bumps errados gerados por IA. Use como referência oficial SemVer, Changesets, a documentação de publicação npm e GitHub Actions. Para complementar, veja boas práticas de CLAUDE.md, CI/CD com Claude Code e gestão de monorepo.

SemVer antes da automação

SemVer significa versionamento semântico. Em 1.4.2, o formato é major.minor.patch. patch corrige bugs sem alterar o contrato público. minor adiciona funcionalidade compatível. major indica que usuários podem precisar mudar código.

Contrato público inclui mais do que funções exportadas. Props React, tokens CSS, flags de CLI, códigos de saída, comportamento padrão e tipos TypeScript exportados também contam. Coloque essa regra no prompt para o Claude Code; caso contrário, ele pode recomendar um bump pelo tamanho do diff.

Casos de uso reais:

Caso	Risco	O que Claude Code revisa
UI package	props, variants, CSS tokens, peer dependencies	se o bump combina com a API pública
CLI package	flags, comandos, exit codes	se README, testes e código concordam
Monorepo	ranges de dependências internas	se package dependente também precisa release
Package interno	publicação acidental	private, ignore, registry e token

Configuração inicial

Instale e inicialize:

npm install -D @changesets/cli @changesets/changelog-github
npx changeset init

Configuração inicial:

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": [
    "@changesets/changelog-github",
    {
      "repo": "your-org/your-repo"
    }
  ],
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}

fixed mantém packages sempre na mesma versão. linked sobe packages relacionados juntos, preservando versões próprias. updateInternalDependencies define como ranges internos mudam. Em monorepo, isso evita que algo funcione localmente com workspace:*, mas quebre para usuários depois da publicação.

Scripts compartilhados:

{
  "scripts": {
    "changeset": "changeset",
    "changeset:status": "changeset status --since=origin/main",
    "version": "changeset version",
    "release": "changeset publish",
    "build": "tsc -p tsconfig.json",
    "test": "vitest run"
  }
}

Criar o changeset

Para cada PR que altera um package público:

npx changeset

Exemplo:

---
"@myapp/ui": minor
"@myapp/utils": patch
---

Add the `outline` variant to Button and keep the existing `solid` and `ghost` variants compatible.

Fix `formatCurrency` so it handles zero-decimal currencies without rounding errors.

@myapp/ui recebe minor por adicionar uma opção compatível. @myapp/utils recebe patch por corrigir uma função existente. Remover prop, renomear flag de CLI ou mudar comportamento padrão deve ser tratado como candidato a major.

Prompt para Claude Code:

Leia o diff do PR atual e crie um rascunho de changeset para Changesets.

Regras:
- Siga SemVer: breaking change é major, feature compatível é minor, correção é patch
- Não edite versões diretamente em package.json
- Não execute npm publish
- Não inclua packages com private: true no plano de publicação

Retorne:
- packages alterados
- bump recomendado para cada package
- justificativa
- conteúdo proposto para .changeset/*.md
- pontos incertos para revisão humana

Monorepos e packages internos

Repositórios reais misturam packages publicáveis e apps que nunca devem ser publicados. Exemplo:

{
  "name": "@myapp/app",
  "private": true,
  "version": "0.0.0",
  "scripts": {
    "build": "next build"
  },
  "dependencies": {
    "@myapp/ui": "workspace:*"
  }
}

Exclusão no Changesets:

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": [
    "@changesets/changelog-github",
    {
      "repo": "your-org/your-repo"
    }
  ],
  "commit": false,
  "fixed": [
    ["@myapp/core", "@myapp/cli"]
  ],
  "linked": [
    ["@myapp/ui", "@myapp/theme"]
  ],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": ["@myapp/app", "@myapp/docs"]
}

Para registry interno:

{
  "name": "@my-company/internal-kit",
  "version": "1.8.0",
  "publishConfig": {
    "registry": "https://npm.pkg.github.com",
    "access": "restricted"
  }
}

Separe o token desse registry do token usado no npm público.

Release com GitHub Actions

changesets/action cria o PR de versionamento e publica após o merge.

name: Release

on:
  push:
    branches:
      - main

concurrency: release-${{ github.ref }}

permissions:
  contents: write
  pull-requests: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: "https://registry.npmjs.org"

      - run: npm ci
      - run: npm test
      - run: npm run build

      - name: Create release PR or publish to npm
        uses: changesets/action@v1
        with:
          version: npm run version
          publish: npm run release
          title: "chore: version packages"
          commit: "chore: version packages"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Check no PR:

name: Changeset Check

on:
  pull_request:
    branches:
      - main

permissions:
  contents: read

jobs:
  changeset:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx changeset status --since=origin/main

PRs de documentação podem não precisar de changeset. Se houver label de skip, ela deve ser regra do time, não uma exceção inventada pela IA para passar CI.

Qualidade do CHANGELOG

Ruim:

---
"@myapp/ui": minor
---

Update Button.

Bom:

---
"@myapp/ui": minor
---

Add `variant="outline"` to `Button`.

Existing `solid` and `ghost` variants keep the same props and class names. Teams using a custom theme should add `--button-outline-border` only if they want to override the default border color.

Prompt de revisão:

Revise este changeset como texto público de CHANGELOG.

Verifique:
- se usuários entendem o impacto
- se o texto combina com o bump major/minor/patch
- se há passos de migração quando necessário
- se palavras vagas como "updated" ou "improved" substituem detalhes reais
- se nomes de packages, funções e props existem

Liste pontos suspeitos como perguntas. Não reescreva silenciosamente.

Falhas comuns

Primeiro: pedir apenas “aumente a versão”. Claude Code pode editar package.json direto e não criar changeset.

Segundo: publicar breaking change como minor. Mudanças de tipo TypeScript também podem quebrar builds.

Terceiro: publicar package interno. Confira private: true, ignore, publishConfig.registry, permissões do token e npm pack --dry-run.

Quarto: esquecer dependency bump interno. Se @myapp/core muda, talvez @myapp/cli também precise release.

Verificação local

Antes de publicar:

npm run changeset:status
npm test
npm run build
npm run version -- --snapshot canary
git diff -- package.json package-lock.json pnpm-lock.yaml yarn.lock CHANGELOG.md
npm pack --dry-run

Snapshot verifica cálculo de versão e CHANGELOG sem publicar. npm pack --dry-run mostra o tarball e ajuda a detectar .env, fixtures grandes, docs internas ou artefatos de build ausentes.

Monetização e adoção

Um release flow confiável sustenta receita. UI kits, CLIs, SDKs e templates podem virar produtos pagos, treinamento e consultoria. Bumps errados e CHANGELOG vazio prejudicam confiança.

Para aplicar em um repositório real, treinamento e consultoria Claude Code ajuda a definir Changesets, CLAUDE.md, GitHub Actions, limites de token npm, prompts de revisão e política de monorepo.

Resultado prático

Validei este fluxo em um pequeno npm workspace: inicialização, changeset, changeset status, release PR e guardrails de publish. Claude Code é bom para rascunhar release notes a partir do diff, mas seu julgamento SemVer sozinho não é estável. Pedir que explique por que uma mudança não é breaking revela bumps minor ou patch duvidosos antes do npm.