Como pedir uma alteração no banco de dados ao Claude Code sem arriscar seus dados

Fala aí, beleza? Código zoado tu reverte, tabela apagada não

Essa é a assimetria que faz pedido de banco de dados ser diferente de qualquer outra tarefa que você joga pro assistente

Quando o pedido é "adiciona uma coluna", "cria um índice", "escreve essa migration", "faz o backfill dessa tabela", o resultado não é só um arquivo novo no repo, é um estado que já tem dado de gente real dentro dele

A boa notícia: o que separa um pedido tranquilo de um pedido arriscado não é confiar mais ou menos no modelo, é o que o seu prompt diz e o que você não delega

Neste post eu vou montar contigo o trio que todo pedido de esquema precisa carregar (estado atual, dados existentes e caminho de volta) e a linha clara entre o que o Claude Code faz e o que você mesmo executa

O que precisa estar pronto antes de abrir o Claude Code:

Antes de digitar qualquer prompt, três coisas precisam existir, e nenhuma delas depende do assistente 🙂

1. Controle de versão em dia

O Claude Code tem checkpointing, e ele ajuda muito no código

Mas a própria documentação oficial posiciona os checkpoints como complemento do controle de versão, não substituto, justamente porque eles se aplicam às edições do Claude e não às suas edições nem a comandos bash

Então commit limpo antes de começar, sempre

2. Um ambiente de teste separado do banco que importa

Essa é a parte chata que ninguém quer fazer e que salva o pescoço

O plano vai ser escrito uma vez e aplicado duas: primeiro onde errar é grátis, depois onde errar é currículo atualizado 😛

3. O CLAUDE.md do projeto com as regras do banco escritas

Arquivos CLAUDE.md guardam instruções persistentes de projeto e são lidos pelo Claude no início de toda sessão

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

É ali que mora a regra que você não quer repetir em cada prompt, tipo "toda alteração de esquema vem com script de reversão" e "nenhum comando que aplica migração é executado pelo assistente"

Pra abrir esse arquivo, o comando /memory lista os arquivos CLAUDE.md, CLAUDE.local.md e demais arquivos de memória nos escopos de usuário e projeto, e abre no editor o que você escolher (criando o arquivo se ele ainda não existir)

Se a sua dúvida ainda é anterior a isso, ou seja, o que delegar em migrations e o que nunca aplicar sem revisão, esse recorte já rendeu post próprio aqui

Passo a passo para pedir a alteração no banco de dados sem arriscar os dados:

O fluxo abaixo tem oito passos

Ele parece longo escrito, mas na prática é quase todo prompt, com uns poucos atalhos de teclado no meio

1. Entre no plan mode antes de descrever a tarefa

O modo de planejamento é acionado pressionando Shift+Tab até a barra de status mostrar o indicador de plan mode, ou iniciando a sessão já com a flag de modo de permissão de plano

claude --permission-mode plan

Ou, na sessão aberta, Shift+Tab até aparecer:

⏸ plan mode on

Nesse modo o Claude lê arquivos e responde perguntas sem fazer alterações

É exatamente o comportamento que você quer quando o assunto é esquema: pensar em voz alta, sem tocar em nada

O erro comum deste passo: pedir a migration direto no modo normal e ir descobrindo o plano pelos arquivos que já foram escritos

2. Descreva o estado atual do esquema no prompt

O assistente pode ler o projeto, mas o que ele lê é o código, não a realidade do banco em que a coisa vai rodar

Então você entrega isso de mão beijada:

Contexto do esquema atual:
- tabela: usuarios
- colunas hoje: id, email, criado_em, ativo
- a coluna ativo é booleana e não aceita nulo
- essa tabela é lida pelo login e pelo relatório semanal

O que eu quero: guardar o momento em que o usuário foi desativado

Repara que eu não pedi "adicione a coluna", eu descrevi o objetivo e o terreno

O erro comum deste passo: dizer "adicione a coluna X" sem dizer o que já existe, e receber um plano que assume um esquema que não é o seu

3. Declare o volume e a natureza dos dados existentes

Esse é o passo que quase todo mundo pula, e é o que muda o plano por completo

Uma coluna nova em tabela vazia é um comando

A mesma coluna em tabela com registro em produção é um comando, uma decisão de valor padrão e uma decisão sobre nulo

Dados existentes:
- a tabela já tem registros em produção
- nenhum registro pode ser perdido ou reescrito
- a coluna ativo já tem dado gravado e é usada em consulta
- se a alteração exigir valor padrão, me apresente as opções em vez de escolher sozinho

O erro comum deste passo: omitir que a coluna já tem dado em produção, e o plano tratar a alteração como se o terreno estivesse limpo

4. Exija o caminho de volta no mesmo pedido

A reversão não é um pedido de depois, ela é parte do entregável

Se o plano não tem o script que desfaz, o plano não está pronto

Regras do entregável:
- escreva a alteração e o script de reversão dela, no mesmo plano
- não execute nenhum comando: eu aplico
- liste o que quebra no código se a alteração for aplicada

Aquela última linha é de graça e vale ouro: é o assistente te contando onde o código ainda lê o que você está mexendo

O erro comum deste passo: aprovar plano sem reversão porque "depois eu escrevo"

5. Revise e edite o plano antes de aprovar

Dentro do plan mode dá pra abrir o plano no editor de texto e mexer nele antes do Claude prosseguir

Ctrl+G

Aqui é onde você corta o passo que não devia existir, ajusta a ordem e apaga qualquer linha que execute algo

Ler o plano inteiro custa um minuto

Não ler custa o fim de semana 😀

O erro comum deste passo: aprovar sem ler, confiando que o resumo bonito representa o que está escrito nos passos

6. Saia do plan mode com decisão consciente

Sai-se do plan mode aprovando o plano ou pressionando Shift+Tab novamente

A diferença entre os dois não é atalho, é intenção: aprovar significa "pode seguir com ISSO", Shift+Tab significa "eu volto ao modo normal e mando o que fazer"

Escolha sabendo qual dos dois você quis

7. Blinde o que não pode rodar, via regras de permissão

As permissões do Claude Code têm três tipos de regra: allow (permite a ferramenta sem aprovação manual), ask (pede confirmação a cada uso) e deny (bloqueia a ferramenta)

Na documentação, as regras deny são avaliadas primeiro no fluxo e têm precedência sobre allow e ask

E, ainda pela documentação, se uma regra deny casa, a ferramenta é bloqueada inclusive no modo bypassPermissions

Esse é o comportamento esperado, e é nele que você se apoia pra desenhar a regra

Guarda esse "esperado" com carinho: mais pra frente eu mostro as issues abertas no repositório oficial relatando deny ignorado, e por que deny não pode ser a sua única barreira

Agora a parte que pega muita gente: existe diferença entre regra com nome puro da ferramenta e regra com escopo

Regra com nome puro, tipo Bash, remove a ferramenta do contexto do Claude antes da avaliação

Apenas regras com escopo, tipo Bash(rm *), são checadas nessa etapa

O curinga vale pra subcomando também: Bash(git *) casa qualquer entrada do Bash que comece com git

E, se você prefere resolver na linha de comando, a CLI aceita as flags --allowedTools e --disallowedTools pra definir ferramentas permitidas ou proibidas sem pedir confirmação:

claude --allowedTools "Bash(git log:*)" "Bash(git diff:*)" "Edit"

O erro comum deste passo: escrever a regra no formato errado e achar que está protegido

8. Execute você mesmo o comando que aplica a alteração

Esse não é conselho de paranoico, é consequência de um fato bem específico

O checkpointing do Claude Code não rastreia arquivos modificados por comandos bash

Comandos como rm, mv e cp não podem ser desfeitos pelo rewind, porque só as edições feitas pelas ferramentas de edição de arquivo do Claude são rastreadas

Traduzindo pro nosso caso: o script que ele escreveu você reverte, o efeito de rodar o script não

Então o comando que aplica migração no seu projeto (aquele que você já conhece, com a ferramenta que você já usa) é digitado por você, com o olho na saída

O erro comum deste passo: liberar a execução "só essa vez, é rapidinho", num banco que importa

Três pedidos comuns e como escrever cada um:

Agora o trio na prática

Em todos, o padrão é o mesmo: estado atual, dados existentes, caminho de volta

Caso 1: adicionar coluna em tabela que já tem registros

Estou em plan mode. Não execute nada.

Estado atual: tabela pedidos, colunas id, cliente_id, total, criado_em.
Dados existentes: tabela com registros em produção, nada pode ser perdido.
Objetivo: guardar o canal de origem do pedido.

Entregue:
1. o script da alteração
2. o script de reversão
3. a decisão sobre nulo e valor padrão, com as opções e o efeito de cada uma nos registros que já existem
4. os pontos do código que precisam mudar junto

O detalhe que faz esse prompt funcionar é o item 3: você não deixa a escolha de valor padrão acontecer sozinha dentro de um script

Caso 2: renomear ou remover coluna que o código ainda lê

Esse é o pedido mais perigoso da lista, porque ele quebra em dois lugares ao mesmo tempo: no dado e na aplicação

Estou em plan mode. Não execute nada.

Estado atual: tabela usuarios, coluna nome_completo.
Objetivo: renomear para nome_exibicao.
Dados existentes: coluna preenchida em produção.

Antes de propor o script:
- liste TODOS os pontos do código que leem ou escrevem nessa coluna
- me diga o que acontece com cada um deles no instante seguinte à alteração

Depois disso, entregue a alteração e o script de reversão, na ordem em que devem ser aplicados.

O "me diga o que acontece no instante seguinte" é a pergunta que evita aquele deploy em que o banco já mudou e o código ainda não

Caso 3: backfill ou migração de dados entre colunas

Aqui não é o esquema que muda, é o conteúdo

E conteúdo reescrito é o tipo de estrago que nenhum rewind alcança

Estou em plan mode. Não execute nada.

Objetivo: preencher a coluna nova a partir da antiga.
Dados existentes: registros em produção, alguns com a coluna antiga vazia.

Entregue:
1. uma consulta que só CONTA quantos registros seriam afetados
2. o script de backfill
3. como reverter o backfill
4. o que fazer com os registros em que a coluna antiga está vazia

O item 1 é o meu favorito: contar antes de escrever é o equivalente barato de um ensaio

E vale o mesmo cuidado de pedir testes que realmente falham antes de mexer em dado, porque teste que só confirma o que o código já faz não protege backfill nenhum

Quem faz o quê em cada caso:

Quando a proteção falha: sintomas, causa e o que fazer:

Tem três situações que aparecem justamente quando a pessoa se sente protegida

"Pedi rewind e o dado não voltou"

A causa: o checkpointing cobre apenas edições feitas pelas ferramentas de edição de arquivo do Claude, e não efeitos de comandos bash

Comandos como rm, mv e cp não podem ser desfeitos pelo rewind

Dá pra sentir o escopo da coisa só de olhar o menu de rewind, que oferece três opções de restauração: ‘Restore code and conversation’, ‘Restore conversation’ e ‘Restore code’

Código e conversa: nenhum dos três é "restaurar dado"

A prevenção: controle de versão em dia mais execução manual de tudo que toca o banco

O rewind é rede pra edição de arquivo, não pra estado de banco

"Coloquei deny e a ferramenta rodou mesmo assim"

Aqui é a hora de fechar o parêntese que eu deixei aberto lá no passo 7

Tudo que eu disse sobre deny (avaliado primeiro, precedência sobre allow e ask, bloqueio inclusive em bypassPermissions) é o comportamento documentado

Comportamento documentado é o que você projeta, não é garantia de que a versão que está na sua máquina se comporta assim hoje

A causa: existem issues abertas no repositório oficial anthropics/claude-code relatando que regras deny em settings.json não são aplicadas, em versões diferentes e ao longo do tempo

A issue #6699 é o relato original, na versão 1.0.93

Depois vieram a #12918, com relato de deny para Edit/Write na v2.0.56, e a #27040, com deny ignorado em .claude/settings.json

Eu não vou te dizer que deny "não funciona", porque não achei confirmação de correção nem de reincidência na versão de hoje

Mas também não dá pra dizer que ele sempre pega, e é essa a leitura honesta: escreva a regra deny, conte com ela como camada, nunca como a última palavra

A prevenção é outra: não tratar deny como a ÚNICA barreira

O comando destrutivo do seu projeto fica fora do alcance do assistente por desenho, não por confiança em uma linha de configuração

"A regra de deny não pegou o comando que eu queria"

A causa: provavelmente é a diferença entre regra com nome puro e regra com escopo

Bash puro remove a ferramenta do contexto do Claude antes da avaliação

Já Bash(rm *) é regra com escopo, e é esse tipo que é checado na etapa de avaliação

A prevenção: escrever o padrão certo pro que você quer bloquear, e lembrar que o curinga também vale pra subcomando, como em Bash(git *)

Camadas extras que existem:

Sem entrar em configuração que eu não confirmei, vale saber que o cinto tem mais furos disponíveis:

• hooks, sendo que o PreToolUse é executado antes da chamada da ferramenta, ou seja, antes até das regras deny, allow e ask
• Bash em sandbox, que é recurso configurável do Claude Code e tem página própria na documentação oficial
• auto mode, que a Anthropic apresenta em material de engenharia como uma forma mais segura de pular permissões

Se o seu projeto mexe em banco toda semana, esses três merecem uma tarde de leitura da doc oficial 🙂

O próximo passo:

Recapitulando o que importa: a segurança de um pedido de banco não vem de confiar mais ou menos no modelo

Ela vem de duas coisas bem prosaicas

A primeira é escrever no prompt aquilo que o assistente não tem como adivinhar: como o esquema está hoje, que dado já mora ali e como se volta atrás

A segunda é manter na sua mão o comando que não tem volta, porque o rewind não alcança efeito de bash e ponto

Seu próximo passo é de cinco minutos: rode /memory, abra o CLAUDE.md do projeto e registre as regras do banco hoje

Como os arquivos CLAUDE.md são lidos no início de toda sessão, elas já valem na próxima vez que você abrir o terminal

E aí a conversa sobre esquema começa com as regras na mesa, não no meio do plano

Bora escrever essas regras? até o próximo post!