Projeto legado sem nenhum teste: qual é o primeiro pedido seguro para o Claude Code?

Tem um medo que nenhuma ferramenta de IA cura sozinha: abrir um projeto de anos atrás, sem um teste sequer, e ter que mudar alguma coisa lá dentro

O sistema roda em produção, funciona por motivos que ninguém sabe explicar direito, e quem escreveu aquilo já não trabalha mais lá

Sem teste, sem documentação, sem rede de proteção nenhuma…

Aí você abre o Claude Code naquela pasta e a ferramenta está a um Enter de começar a editar arquivo

A pergunta que importa aqui não é se o Claude Code dá conta de código legado

É outra, bem mais prática: qual é o primeiro pedido seguro? 🙂

O caminho deste post é esse: um primeiro pedido que não muda nada, uma verificação mínima construída em cima do que a ferramenta descobriu, e só então o primeiro diff aceito

Antes de abrir o Claude Code no projeto legado

Três coisas precisam estar de pé antes de você digitar qualquer prompt, beleza?

1. O projeto versionado em git, com tudo commitado

O Claude Code faz checkpointing automático: ele captura o estado do código antes de cada prompt que inicia um turno, e a sessão guarda os 100 checkpoints mais recentes

Só que isso cobre as edições feitas por ele, e nada além disso

Edição que você fez na mão não volta, efeito de comando bash não volta

A própria documentação recomenda usar checkpoint JUNTO com controle de versão, não no lugar dele

Então: git status limpo antes de começar, sempre

2. Saber em qual plano você está

Isso muda o comportamento inicial da sessão e muita gente descobre no susto

Nos planos Pro, Max e Team, em sessão interativa de terminal, o padrão é o auto mode: um classificador aprova a maior parte das ações no seu lugar

Nos demais planos o padrão é o manual mode, que pergunta antes de escrever arquivo, rodar comando Bash e usar ferramenta MCP

Em base legada, adivinhar em qual modo você está é a receita do desastre

3. Uma regra deny para o que ele não deve nem ler

Projeto antigo costuma ter .env com credencial de produção largada na raiz

O Claude Code aceita regras allow, ask e deny no settings.json (por exemplo ~/.claude/settings.json), e a regra deny bloqueia a ferramenta inclusive no modo bypassPermissions

{
  "permissions": {
    "deny": [
      "Read(./.env)"
    ]
  }
}

Tome cuidado! Esse arquivo é JSON estrito

Comentário // ou vírgula sobrando geram erro de sintaxe, e na próxima inicialização o Claude Code reporta um Settings Error

Se o teu contato com a ferramenta até agora foi só em projeto novo, vale lembrar que começar um projeto do zero é MUITO mais tranquilo do que isso aqui: lá você escreve as regras, aqui você descobre as regras que já existem

Passo a passo: do primeiro pedido até a primeira alteração aceita

1. Entre no plan mode antes de qualquer coisa

O plan mode é o modo em que o Claude explora o repositório e produz um plano, sem alterar os arquivos-fonte antes da sua aprovação

É exatamente o que você quer num código que ninguém entende: leitura primeiro, opinião depois

Pra entrar, você aperta Shift+Tab até a barra de status mostrar o plan mode ativo, ou já abre a sessão assim:

claude --permission-mode plan

O Shift+Tab alterna o permission mode da sessão a qualquer momento, então dá pra corrigir no meio do caminho também

O erro comum deste passo: digitar o pedido de correção antes de trocar o modo

Você escreve "arruma o bug do relatório" achando que ele vai só analisar, e na sessão em auto mode ele já sai editando

2. Faça um pedido de leitura, e só de leitura

O primeiro prompt não pede mudança nenhuma

Ele pede entendimento de um pedaço pequeno: qual é o fluxo daquele arquivo, o que entra, o que sai, quem chama aquilo e quais são os efeitos colaterais

Algo nessa linha:

Leia o arquivo relatorios/fechamento.py e me explique:
o fluxo principal, as entradas e saídas dessa função,
quem chama ela no projeto e quais efeitos colaterais ela tem
(escrita em disco, banco, chamada externa).
Não proponha nenhuma mudança ainda.

O erro comum deste passo: pedir o repositório inteiro de uma vez

"Explica o projeto" num legado gordo devolve um resumo bonito e genérico, que não te ajuda a decidir nada

Um módulo por vez rende MUITO mais

3. Transforme o que ele descobriu em characterization test

Aqui está o pulo do gato

Characterization test é um termo cunhado por Michael Feathers no livro Working Effectively with Legacy Code: é o teste que documenta o comportamento ATUAL e real do código, não o comportamento correto

Ou seja: se a função arredonda errado desde 2017, o teste registra o arredondamento errado

Parece estranho? É proposital

O objetivo não é consertar, é congelar, pra você ter como saber se a próxima alteração mudou algo que não devia

Começa por função pura, aquela que só recebe e devolve valor, sem banco e sem rede

Se isso virar rotina no projeto, vale documentar o que uma skill de testes precisa saber do teu repositório, pra não repetir a explicação toda sessão

O erro comum deste passo: consertar o comportamento esquisito na hora de escrever o teste

Aí você perde a única referência que tinha do estado anterior

4. Registre o básico no CLAUDE.md

O CLAUDE.md é um arquivo markdown com instruções persistentes do projeto, lido pelo Claude no começo de toda sessão

É o lugar dos comandos de build, das convenções, do layout do projeto e das regras do tipo sempre faça X

# Projeto Fechamento

## Comandos
- Build: make build
- Testes: pytest tests/

## Regras
- Sempre rode os testes de tests/caracterizacao antes de propor um diff
- Nunca edite arquivos em migrations/ sem pedir confirmação

Em legado isso economiza um absurdo de tempo, porque você para de reexplicar o mesmo contexto todo santo dia

5. Só então autorize a primeira alteração minúscula

Minúscula mesmo: uma função, um arquivo, uma coisa que o teste do passo 3 cobre

Você tem uma rede aqui: existe snapshot automático antes de cada prompt que inicia um turno, e dá pra voltar apertando Esc duas vezes ou usando /rewind

Ao voltar pra um checkpoint, você escolhe restaurar o código, a conversa ou os dois

O erro comum deste passo: achar que o rewind desfaz tudo

Ele não reverte edição manual sua nem efeito de comando bash, e é por isso que o passo 1 lá de cima era o git status limpo

Quais tarefas servem como primeiro pedido (e quais não servem)

A regra de bolso é simples: quanto mais fácil de VERIFICAR e de reverter, melhor o candidato

Se você não consegue responder "como eu sei que isso deu certo?" em uma frase, não é primeiro pedido

Repara no padrão: a coluna da direita quase sempre fala de verificação, não de dificuldade técnica

O Claude Code até dá conta de coisa grande, o problema é você não ter como saber se quebrou algo

O que muda quando você faz isso na prática

No vídeo abaixo dá pra ver o fluxo da ferramenta rodando de ponta a ponta

O que dá pra sentir na prática é o RITMO de cada modo de permissão

No manual mode, cada escrita de arquivo passa por uma aprovação sua, uma a uma, e o desenvolvimento fica bem mais pausado

No auto mode você pede duas mudanças de uma vez e recebe só o resultado final, sem parada nenhuma no meio

Massa pra protótipo

Péssimo pra legado, porque o hábito de conferir antes de aceitar simplesmente não se forma

É onde iniciante escorrega: solta o agente no modo automático, recebe o resultado pronto e não tem como verificar o que mudou

A recomendação pra projeto de equipe ou de empresa é direta: mantenha os modos mais pausados, aprovando as ações antes, pra entender o que está acontecendo antes de sair mudando tudo

O modo totalmente automático é pra quem está sozinho fazendo vibe coding

E tem o plan mode, que resolve boa parte disso no legado: o Claude analisa e propõe o plano sem alterar arquivo-fonte antes da sua aprovação

Em código que você não conhece, ler esse plano vale quase tanto quanto ler o diff

Vale testar os modos um a um pra descobrir qual se adapta melhor ao teu jeito de trabalhar 😀

Deu errado mesmo assim: o que fazer

O rewind não trouxe o arquivo de volta

Sintoma: você voltou num checkpoint e o arquivo continua alterado

Causa: o checkpointing cobre só o que o próprio Claude editou

Edição manual sua, efeito de comando bash, e também arquivo que é symlink ou hard link ficam de fora (nesses caminhos o Claude Code pula a restauração e mostra um aviso)

Solução: cai pro git, que é a rede de verdade

Como prevenir: commit limpo antes de cada bloco de trabalho, sem exceção

O Claude está agindo demais, sem perguntar nada

Sintoma: você pediu análise e ele já editou meio projeto

Causa: a sessão está em auto mode, o padrão em Pro, Max e Team no terminal interativo

Solução: Shift+Tab troca o permission mode da sessão na hora

Como prevenir: abrir a sessão de legado já com claude --permission-mode plan

O Claude leu um arquivo que não devia

Sintoma: conteúdo sensível aparecendo no contexto da conversa

Causa: faltou a regra deny no settings.json

Solução: adicionar a regra deny de Read no caminho do arquivo

Como prevenir: lembrar que deny prevalece inclusive sobre bypassPermissions, então ela é a trava mais forte que você tem

Settings Error na inicialização

Sintoma: o Claude Code reclama das settings ao abrir

Causa: o arquivo é JSON estrito e alguém colocou um comentário // ou deixou vírgula sobrando

Solução: tirar o comentário e a vírgula extra

Como prevenir: validar o JSON antes de salvar, porque erro de sintaxe aqui derruba tua configuração inteira

Sumiu o histórico antigo da sessão

Sintoma: o checkpoint de horas atrás não está mais na lista

Causa: a sessão guarda os 100 checkpoints mais recentes

Solução: usar o git pra recuperar o estado antigo

Como prevenir: commitar em marcos curtos, em vez de deixar tudo pendurado numa sessão gigante

Próximo passo no seu legado

Se eu pudesse resumir o post numa linha só: o primeiro pedido seguro é um pedido que não muda nada

A rede de proteção você constrói ANTES de aceitar qualquer diff, não depois que o estrago apareceu

O próximo passo concreto é escolher um módulo só, um, e rodar o ciclo inteiro: plan mode pra entender, characterization test pra congelar o comportamento real, alteração mínima pra testar a rede

Quando isso virar rotina, o legado deixa de ser um campo minado e vira só um projeto sem documentação, o que é bem mais fácil de resolver 🙂

E pra ampliar o repertório de pedidos, a documentação oficial mantém uma página de fluxos comuns do Claude Code com receitas pra explorar código, corrigir bugs, refatorar, testar, abrir PRs e documentar

Bora começar pelo módulo mais chato do teu projeto?

Até o próximo post!