Versionar é criar checkpoints

Quando comecei a explicar versionamento para uma equipe que está construindo seus primeiros agentes de IA, usei uma analogia simples: checkpoint de videogame.

Você chegou a um ponto importante, salva e continua. Se algo der errado depois, existe um estado conhecido para onde voltar.

Versionamento cumpre esse papel. A analogia tem um limite importante: no Git, o checkpoint não aparece sozinho. Alguém precisa escolher o que será registrado e criar um commit.

Com agentes de IA, esse hábito ficou ainda mais importante. Um agente consegue alterar prompts, AGENTS.md, templates, scripts e vários outros arquivos rapidamente. Isso acelera o trabalho, mas também torna fácil perder um estado que estava funcionando.

A pergunta aparece cedo:

Ontem funcionava. O que mudou?

Sem uma versão anterior registrada, começa uma investigação. Com ela, podemos comparar o estado atual com um ponto que já havia sido validado.

Esquema desenhado à mão mostra versões dos pacotes A e B compondo um estado conhecido de uma stack. — Um checkpoint pode registrar quais versões dos componentes formavam um estado conhecido do projeto.

Git registra os checkpoints

A principal ferramenta para isso é o Git. Ele é um sistema de controle de versão que registra alterações em arquivos. Git não é GitHub: o GitHub é uma plataforma baseada em Git, capaz de hospedar repositórios e acrescentar recursos de colaboração. É possível usar Git localmente sem publicar o projeto no GitHub.

Na analogia, cada commit é um checkpoint. Depois de preparar o repositório, um ciclo mínimo pode ser:

git status
git add AGENTS.md templates/ scripts/
git commit -m "Preserva primeiro fluxo funcional do agente"

O git status mostra o que mudou. O git add seleciona os arquivos que farão parte do checkpoint. O git commit registra aquele conjunto de mudanças no histórico.

Assim se forma uma linha do tempo:

checkpoint validado
   ↓
mudanças
   ↓
checkpoint validado
   ↓
mudanças
   ↓
checkpoint validado

Se algum resultado piorar, posso inspecionar a diferença e recuperar um estado anterior. O Git não decide se o checkpoint era bom; ele preserva o que foi registrado. Por isso, vale anotar no commit o que funcionava e como foi verificado.

Não é só para código

Em projetos com agentes, podemos versionar:

AGENTS.md;
prompts;
skills;
templates;
regras;
documentação;
HTML;
scripts e configurações.

São arquivos que transformam um modelo genérico em um agente adaptado ao projeto. Quando mudam, o comportamento também pode mudar. Mantê-los no mesmo histórico ajuda a comparar não apenas o código, mas o contexto que orientou cada execução.

Commit e versão não são a mesma coisa

Todo estado que vale preservar pode virar um commit. Isso não significa que todo commit precise receber um número de versão.

Quando um checkpoint será distribuído, implantado ou usado por outro projeto, podemos marcá-lo como uma versão. Se existe um contrato de compatibilidade claro, uma convenção possível é o Versionamento Semântico:

MAJOR.MINOR.PATCH

2.4.1

PATCH indica uma correção compatível:

2.4.0 → 2.4.1

MINOR adiciona uma capacidade mantendo compatibilidade com o contrato existente:

2.4.1 → 2.5.0

MAJOR indica uma mudança incompatível nesse contrato:

2.5.0 → 3.0.0

Para um agente, esse contrato pode incluir o formato de entrada e saída, os comandos disponíveis, a estrutura de um template ou um comportamento do qual outros componentes dependem. Sem definir o que precisa permanecer compatível, os números comunicam pouco.

Durante o desenvolvimento inicial, o Versionamento Semântico reserva a série 0.y.z para uma API ainda instável:

1.0
2.0
2.1
...
0.0

Nesse sistema, 1.0.0 define a primeira API pública. Não quer dizer que o projeto ficou livre de erros; quer dizer que existe um contrato que as próximas versões devem considerar.

Sessão é temporária, projeto é persistente

Há ainda uma consequência importante para o trabalho com agentes de IA.

A sessão é temporária. Ela termina, pode ser resumida e não deveria ser a única guardiã de uma decisão importante. Se uma regra precisa orientar o próximo trabalho, ela precisa sair da conversa e chegar ao projeto.

AGENTS.md
skills/
templates/
docs/
output/

Nem todo resultado gerado precisa entrar no Git, e segredos não devem ser registrados. Mas regras, decisões e saídas que precisam de auditoria podem virar arquivos e fazer parte do histórico.

A distinção fica simples:

sessão → temporária

projeto versionado → fonte persistente

O primeiro hábito

Não é necessário aprender o Git inteiro para começar. O primeiro hábito já reduz bastante o risco:

Quando eu chegar a um estado que vale a pena preservar, faço um checkpoint.

Um checkpoint fica mais útil quando sua mensagem ajuda a reconhecer o que funcionava naquele momento e como isso foi verificado.

A IA tornou muito barato mudar as coisas. O Git torna barato comparar essas mudanças e recuperar um ponto conhecido. O que nunca foi registrado, porém, não tem checkpoint para onde voltar.