Vale a pena revisar a spec antes de deixar o Claude Code escrever código?

Fala aí, beleza? A linha mais cara do seu projeto não é a mais difícil de escrever: é a que o agente escreveu a partir de uma spec ambígua

Ela passa no lint, passa no build, às vezes até passa no teste

E só quebra quando você percebe que ela resolveu outro problema, não o seu 😅

O dilema é esse: você gasta uns minutos lendo o plano ANTES, ou gasta o tempo que for lendo o diff DEPOIS?

O tema virou pauta agora porque o Claude Code tem gate de plano nativo: existe um modo de planejamento em que ele pesquisa e propõe as mudanças sem executá-las, lê arquivos, roda comandos de exploração e escreve um plano, mas não edita o código-fonte

Ou seja, a revisão da spec deixou de ser disciplina de processo e virou uma tecla

Revisar a spec antes x revisar o diff depois

Os dois modos existem e os dois são legítimos, só que eles não custam a mesma coisa

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Do lado do diff, a rede de segurança é real: o Claude Code cria um checkpoint a cada prompt enviado e tira snapshot dos arquivos antes de cada mudança, e você volta atrás com Esc duas vezes ou pelo comando /rewind

O menu ainda deixa escolher o que restaurar: só a conversa mantendo o código atual, só o código mantendo a conversa, ou retomar a partir de uma mensagem

E isso persiste junto com a sessão, então dá pra fechar o terminal, voltar depois e ainda assim desfazer

Mas se liga nisso, porque é aqui que muita gente se ferra: os checkpoints só rastreiam mudanças feitas pelas ferramentas de edição de arquivo do Claude

Alterações feitas por comandos Bash ou por processos externos ficam FORA do checkpoint

Traduzindo: script que roda no shell, migration aplicada, arquivo movido por comando… nada disso volta com um rewind

É exatamente a categoria de mudança onde revisar antes vale mais que desfazer depois

O que olhar na leitura rápida do plano:

A ideia não é auditar linha por linha, é uma passada de olhos com cinco perguntas na cabeça

Se você quer o passo anterior, de escrever a spec antes de mandar implementar, tem post separado sobre isso aqui no blog

Aqui a gente já está com o plano na tela, e o checklist é esse:

• Quais arquivos ele diz que vai tocar? se aparece arquivo que você não esperava, ou se falta um que obviamente precisa mudar, o entendimento dele está torto
• O objetivo declarado bate com o que você pediu? leia a primeira frase do plano como se fosse o commit message: se ela descreve outra tarefa, para tudo
• Tem passo de verificação? rodar teste, subir a aplicação, conferir a saída… plano que termina em "implementar" e ponto costuma terminar em retrabalho
• Ele inventou dependência ou caminho? biblioteca que o projeto não usa, pasta que não existe, comando de build diferente do seu
• O plano cabe no que já está no CLAUDE.md? os arquivos CLAUDE.md dão instruções persistentes de projeto e são lidos no início de toda sessão, servindo pra comandos de build, convenções, layout do projeto e regras do tipo "sempre faça X"

Se você não lembra o que tem lá dentro, o comando /memory lista e abre os arquivos de memória da sessão, incluindo CLAUDE.md e CLAUDE.local.md, nos escopos de usuário e de projeto

E achou algo torto no plano? Não precisa escrever um textão explicando: o plano proposto pode ser aberto no seu editor de texto com Ctrl+G pra edição direta antes do Claude prosseguir

Corrige a frase errada na fonte, salva, aprova 🙂

As ambiguidades que sempre viram retrabalho:

Tem padrão de spec vaga que se repete tanto que dá pra colecionar

Cada um vem com a pergunta que mata a ambiguidade ANTES de você aprovar:

1. Escopo sem fronteira, o clássico "e ajuste o resto". Pergunta: quais arquivos entram e quais ficam explicitamente de fora?
2. Nome de conceito com dois significados no repo, tipo "usuário" sendo a tabela do banco em um canto e o objeto de sessão em outro. Pergunta: quando o plano diz esse nome, ele está falando de qual dos dois?
3. Critério de pronto ausente. Pergunta: qual comando eu rodo pra saber que terminou, e qual saída eu espero ver?
4. Decisão de arquitetura deixada implícita, quando o plano não diz se a lógica nova mora numa camada existente ou numa nova. Pergunta: isso vai onde, e por quê ali?
5. Migração de dados escondida dentro de "refatorar". Pergunta: esse renomear mexe em dado que já existe?

Esse último é o mais traiçoeiro, porque migration costuma rodar por comando no shell

E comando de shell, como já falamos, não entra no checkpoint

Tome cuidado! Um "refatorar o modelo de usuário" que na prática altera dados existentes é o tipo de coisa que você quer discutir no plano, nunca no rollback

Como colocar o gate humano no fluxo do Claude Code:

O fluxo abaixo é só o que a documentação sustenta, sem invenção

1. Entre no plan mode pelo teclado. Pressione Shift+Tab até a barra de status mostrar o indicador ⏸ plan mode on. O erro comum aqui é passar do ponto: o Shift+Tab circula entre os modos de permissão, então confira o indicador antes de mandar o prompt
2. Ou já abra a sessão dentro dele, quando você sabe que a tarefa é grande:

claude --permission-mode plan

3. Precisa do plano só numa pergunta? Prefixe aquele prompt com /plan e o plan mode se aplica a um único prompt, sem mudar o modo da sessão inteira
4. Peça o plano e diga explicitamente pra não escrever código até você confirmar. As boas práticas oficiais recomendam exatamente isso, e o motivo é bem prático: sem as etapas de pesquisar e planejar antes, o modelo tende a partir direto pra codar uma solução, e planejar primeiro melhora bastante o resultado em problemas que exigem raciocínio mais profundo
5. Em base grande, peça pra ele gravar o plano num arquivo markdown do repositório. A documentação recomenda isso porque a sessão longa compacta o contexto no caminho, e o plano salvo sobrevive onde o histórico da conversa não sobrevive. O erro comum é confiar que a conversa lembra: depois da compactação, o que valia estava no arquivo, não no scroll
6. Leia o plano e corrija na fonte com Ctrl+G, que abre o plano no seu editor de texto pra edição direta
7. Escolha como prosseguir no gate. Quando o plano fica pronto, o Claude Code apresenta o plano e pergunta como seguir, oferecendo Yes, and use auto mode ou Yes, manually approve edits. Depois de aprovar, o fluxo segue pro modo de aceitar edições ou pro modo manual pra executar o plano
8. Não gostou do plano? Shift+Tab de novo sai do plan mode sem aprovar. Nada foi editado, porque no plan mode só operações de leitura rodam sem pedir permissão e edições de arquivo nunca são auto-aprovadas, mesmo quando existe uma regra de allow que daria match

Se quiser conferir o comportamento de cada modo com calma, está tudo na documentação de permission modes

O que eu vi na prática antes de aprovar plano

Tem um caso meu que ilustra bem por que a preparação vale mais que o conserto

No vídeo abaixo eu pego um projeto Next que já tinha pronto e, antes de pedir QUALQUER código novo, monto o contexto que o agente vai usar

O problema de partida é conhecido: o agente trabalhando com informação desatualizada de biblioteca que muda muito, o que gera erro e ainda queima token pra descobrir a correção

Rodei o gerador pelo terminal, passei por um login e respondi uma sequência de perguntas descrevendo a expertise que eu queria: decisão entre server e client component, server actions, handlers, padrões de middleware, estratégias de cache e data fetching

Aí veio a parte que é o gate humano na veia: eu mesmo escolhi quais fontes de documentação entrariam e descartei parte do que apareceu sugerido automaticamente

Escolhi também o foco (arquitetura de componentes), o estágio do trabalho (criar componentes e features) e os padrões desejados (arquitetura para escalabilidade)

Depois de gerado, instalei o arquivo dentro do projeto e revisei o conteúdo INTEIRO antes de deixar o agente usar

E aqui vai a observação honesta: o material é bem técnico, e faz mais sentido pra quem já conhece Next

Revisar de verdade exige conhecer o assunto, não tem jeito

Só depois dessa preparação eu pedi a criação da página, e mostro o resultado rodando: a página de contato saiu seguindo o que foi pedido e mantendo o design system do projeto

Quando testei, ficou claro o padrão que vale pra spec também: o desvio aparece na leitura do material, não no diff

No diff você vê um componente bonitinho e não tem como saber que ele foi construído em cima de um padrão que não é o do seu projeto

Uma coisa que eu prefiro, e falo isso no vídeo: trabalhar com o arquivo salvo em vez de disparar consulta a cada prompt

O argumento é consumo, puro e simples: consultar toda hora gasta mais contexto, e com muitas páginas pra criar o arquivo salvo sai mais barato

É o mesmo raciocínio de pedir o plano gravado em markdown: material salvo você relê, material que vive só na conversa some na compactação

Minha recomendação lá foi criar esse material no COMEÇO do projeto, quando as tecnologias já estão definidas, e reutilizar a cada nova página ou funcionalidade em vez de refazer

Veredito: quando pular a revisão da spec é aceitável

Vou ser honesto: nem toda tarefa merece gate

Se a mudança é mecânica, curta e reversível (renomear uma variável em um arquivo, ajustar um texto, trocar um valor de config), aprovar direto e revisar o diff compensa

O plano vai ser uma paráfrase do seu pedido, e ler paráfrase não te ensina nada

Agora, se a mudança cruza vários arquivos, toca dados ou define onde a arquitetura vai morar daqui pra frente, o gate na spec ganha com folga

Nesses casos o diff é grande demais pra revelar intenção: você lê o que ficou, não o que era pra ser

E tem o que o gate NÃO resolve, que é importante dizer: plano bom não garante execução boa

O Claude pode ter escrito exatamente o plano certo e ainda assim tropeçar na hora de aplicar

Por isso, em mudança sensível, Yes, manually approve edits continua valendo mesmo com um plano que você leu e aprovou

Mesma lógica de quando você decide deixar o Claude Code commitar por você: quanto mais irreversível o passo, menos automático ele deveria ser

Conclusão

Revisar a spec no Claude Code é o ponto mais barato de corrigir rumo, porque nesse momento a única coisa que existe é texto

Depois que o código foi escrito, corrigir rumo significa desfazer trabalho, e parte desse trabalho (o que passou por Bash ou por processo externo) nem volta com rewind

Próximo passo bem concreto: na sua próxima tarefa não trivial, entre em plan mode com Shift+Tab, leia o plano com o checklist deste post, corrija o que estiver torto com Ctrl+G e SÓ ENTÃO escolha entre auto mode e aprovar edição por edição

E se o mesmo desvio aparece toda semana no plano, o lugar dele não é no seu prompt: é no CLAUDE.md, que é lido no início de toda sessão

Consolida as regras fixas do projeto lá e o plano já nasce alinhado 😀

Bora testar na próxima feature? Depois me conta como foi

Até o próximo post!