atishaytuli07/versioning-ai-work

Versionamento de Trabalhos com IA

Pessoas que iteram com IA perdem versões boas: uma regeneração as sobrescreve, um desfazer vai longe demais ou a conversa se perde. Este skill faz de cada alteração uma versão numerada que permanece até o usuário deletá-la, permitindo ver, comparar e retornar a qualquer estado anterior.

As três regras

1. Cada alteração recebe uma versão. Uma solicitação do usuário que altera arquivos é uma versão, salva no final daquele turno, antes de você responder. Salvar por requisição, não por edição de arquivo, mantém o histórico legível.
2. Voltar atrás nunca deleta uma versão. Apenas o script escreve em .ai-versions/. Nunca edite, mova ou exclua nada lá, mesmo que peçam para limpar. Direcione o usuário para backup.
3. Voltar atrás é uma nova versão. Restaure usando o script; nunca reconstrua trabalho antigo de memória. Uma restauração é salva como uma nova versão, para que também possa ser desfeita.

O script escolhe cada número de versão. Nunca adivinhe um; informe o número que ele imprime.

Escolha o modo uma vez por projeto

• Você pode executar comandos e editar arquivos (Claude Code, Cursor, Codex, Windsurf, Copilot, Gemini CLI, Replit Agent, claude.ai com execução de código): use o modo de arquivos abaixo.
• O projeto tem .github/workflows/ai-versions.yml: ele usa a camada de versão do GitHub. Não execute init. Em vez disso, a cada alteração, sobrescreva .ai-versions/pending.json e, para voltar atrás, escreva .ai-versions/restore.json. Ambos são descritos em assets/rules/github-layer-rules.md.
• Você não pode executar comandos (um chat simples): siga references/chat-mode.md.
• O usuário constrói no Lovable, Bolt ou v0 (Bolt e v0 estão em beta: não testados ao vivo ainda) ou Figma Make e pergunta como versionar lá: leia references/app-builders.md.

Modo de arquivos

O script é scripts/aiv.py dentro da pasta deste skill (a pasta que contém este SKILL.md). Chame-o pelo caminho completo e aponte para o projeto com --root:

python3 "<pasta deste skill>/scripts/aiv.py" --root "<pasta do projeto>" <comando>
# Windows: py em vez de python3

Após init, cada projeto também tem sua própria cópia, então a partir da pasta do projeto python3 .ai-versions/aiv.py <comando> funciona da mesma forma. Abaixo, aiv significa qualquer uma das formas. Se o Python não estiver instalado, informe ao usuário que ele é necessário (python.org) e use o modo de chat até que esteja.

Iniciar

Antes de sua primeira edição em um projeto sem .ai-versions/, execute init. Ele salva os arquivos atuais como v1.0.0, para que o usuário sempre possa retornar a como as coisas estavam antes de você tocá-las.

Se a pasta contiver mais do que o projeto (uma sandbox, uma pasta pessoal, uma pasta de Downloads), escope-a: init --only poster.html assets/. init recusa pastas com mais de 5.000 arquivos porque isso geralmente indica a pasta errada.

Após cada alteração

aiv save --bump minor --summary "Adicionada uma seção de preços com 3 planos" \
  --reason "Nova seção; layout e estilo inalterados" --prompt "adicionar preços com 3 planos"

--bump	Mostrado ao usuário como	Quando
patch	Pequeno ajuste	Mesmas funcionalidades, pequeno ajuste: texto, cor, espaçamento, tamanho, uma pequena correção
minor	Nova funcionalidade	Algo novo, mesma direção: uma seção, página, componente, funcionalidade
major	Grande mudança	A direção mudou: reformulação, novo layout, novo sistema de estilo, remoção de uma funcionalidade

Uma solicitação com várias alterações leva o nível mais alto. Em caso de dúvida entre dois níveis: escolha o mais baixo e mencione isso em --reason. Casos especiais (documentos, refatorações, atualizações de conteúdo) estão em references/bump-levels.md.

Escreva --summary para o usuário, não para um desenvolvedor: "Deixou a imagem do herói maior", não "Atualizar Hero.tsx". Coloque a solicitação do usuário, encurtada para uma linha, em --prompt.

Em seguida, termine sua resposta com uma linha, por exemplo: Salvo v1.3.0 (Nova funcionalidade): Adicionada uma seção de preços com 3 planos.

Se save disser que os arquivos correspondem exatamente a uma versão mais antiga, ele registra o salvamento como um retorno àquela versão. Informe ao usuário que foi isso que aconteceu.

Quando o usuário perguntar

O usuário diz	Execute	Em seguida
"mostrar versões", "histórico"	list	Mostre uma tabela resumida. Para uma linha do tempo visual, execute view e compartilhe o arquivo HTML que ele cria.
"o que mudou na v1.3.0"	diff v1.3.0^ v1.3.0	Explique em palavras simples. vX^ significa a versão anterior a vX.
"comparar v1.2 e v2.0"	diff v1.2.0 v2.0.0 --stat, depois sem --stat para detalhes	Diga o que mudou, o que melhorou, o que piorou. Se você puder renderizar o trabalho (HTML, imagens), mostre ambos lado a lado.
"voltar para v1.2.0", "desfazer isso"	restore v1.2.0, ou restore prev para desfazer	Em seguida, execute o passo abaixo.
"trazer de volta apenas o cabeçalho antigo", "design antigo mas manter o novo texto"	restore v1.2.0 --path <arquivos>	Apenas esses arquivos mudam; é salvo como um Pequeno ajuste.
"tentar outra direção a partir da v1.2.0"	restore v1.2.0	Em seguida, faça a nova alteração e salve-a como de costume.
"qual é a versão atual", "algo não salvo"	status
"me dê a v1.2.0 como arquivos"	export v1.2.0 --out v1.2.0.zip
"continuar isso em outro chat ou ferramenta"	backup --out history.zip	No novo local: import history.zip.

Quando o usuário nomear uma versão vagamente ("a azul", "antes da reformulação"), execute list e combine os resumos. Se duas versões se encaixarem, pergunte qual.

Após voltar atrás

Uma restauração completa coloca todos os arquivos do projeto de volta como eram, incluindo arquivos que o usuário pode não considerar parte do trabalho, como notas ou dados. Informe ao usuário quais arquivos mudaram (o script os lista). Se ele primeiro salvou trabalho não salvo, diga qual versão o contém e ofereça trazer arquivos específicos de volta com restore <aquela versão> --path <arquivo>. Quando a solicitação visar claramente apenas parte do projeto ("as cores antigas"), use --path desde o início.

Execute handoff <versão que você restaurou> e trate sua saída como a verdade atual antes de fazer a próxima alteração. Ela lista apenas as decisões que levaram àquela versão e nomeia as descartadas, para que instruções de direções abandonadas não retornem. Se a conversa for longa, ofereça continuar em um novo chat e forneça ao usuário o texto de handoff para colar lá.

Rede de segurança para salvamentos esquecidos

No Claude Code ou Cursor, ofereça isso uma vez por projeto: install-hooks claude-code ou install-hooks cursor. Ele adiciona um hook que salva qualquer alteração que você esqueceu de salvar como um Pequeno ajuste quando você terminar. Instale apenas após o usuário concordar, pois ele escreve nas configurações da ferramenta do usuário.

Falando sobre versões

Use as palavras do usuário: Pequeno ajuste, Nova funcionalidade, Grande mudança, Voltou atrás. Mencione números de versão, não commits, arquivos em .ai-versions/ ou hashes. Notas específicas de ferramentas (claude.ai, Replit, Windows) estão em references/tools.md.

Quando um usuário voltar atrás, lembre-o uma vez de que apenas os arquivos voltam: linhas de banco de dados e outros dados ao vivo permanecem como estão.

Todos os comandos

Comando	O que faz
init [--only CAMINHO...]	Iniciar o histórico e salvar v1.0.0
save --bump B --summary S [--reason R] [--prompt P]	Salvar os arquivos atuais como uma nova versão
status	Versão atual e alterações não salvas
list [--all] [--json]	Versões, da mais recente para a mais antiga
show V	Detalhes de uma versão e arquivos alterados
diff [A] [B] [--stat] [--path P...]	Sem argumentos: alterações não salvas. Um: A até a última. Dois: A para B
restore V [--path P...] [--note N]	Voltar atrás (todos os arquivos, ou apenas alguns); salva o trabalho não salvo primeiro, depois salva a restauração como uma nova versão
handoff [V]	Contexto limpo para continuar a partir de V
view [--out ARQUIVO]	Linha do tempo HTML de todas as versões
export V --out DIR_ou_ZIP	Os arquivos de uma versão
backup --out ARQUIVO.zip / import ARQUIVO.zip	Mover todo o histórico
install-hooks claude-code|cursor	Salvar automaticamente o que a IA esquecer
setup-github [--with-pill]	Adicionar a camada GitHub a um repositório de app builder
doctor	Verificar o histórico em busca de peças faltantes

As versões podem ser escritas como v1.2.0, 1.2.0, latest, prev ou v1.2.0^.