Como usar o Claude Code: separando planejamento e execução

• Reestrutura de forma fundamental o uso de ferramentas de codificação com IA, propondo um fluxo de trabalho que exige uma etapa explícita de revisão do plano antes de escrever código
• O princípio central é “não deixar o Claude escrever código antes da aprovação do plano”, o que permite alcançar controle estrutural e uso eficiente de tokens
• Todo o processo segue uma estrutura cíclica de Research → Plan → Annotation → Todo List → Implementation → Feedback
• Em cada etapa, a colaboração gira em torno de documentos em Markdown (research.md, plan.md), repetindo comentários e revisões para aumentar a qualidade final
• Essa abordagem foca em separar e combinar a capacidade de execução da IA com o julgamento humano, para obter resultados estáveis e consistentes mesmo em sistemas complexos

---

Visão geral do fluxo de trabalho

• Ao longo de cerca de 9 meses usando o Claude Code como principal ferramenta de desenvolvimento, foi criado um processo sistemático que separa planejamento e execução, em vez da abordagem comum de “inserir prompt → gerar código → repetir correções”
• Antes de o Claude escrever qualquer código, ele só pode executar com base em um documento de planejamento (plan.md) revisado e aprovado pelo autor
• Essa abordagem reduz tentativas e erros desnecessários, mantém o controle sobre as decisões de arquitetura e maximiza a qualidade em relação ao uso de tokens

Fase 1: Research

• Todo trabalho começa com uma análise profunda da base de código
  • O Claude recebe a instrução de ler e analisar em profundidade uma pasta ou funcionalidade específica
  • O resultado deve ser sempre registrado no arquivo research.md
• Esse documento funciona como uma superfície de revisão para validar o nível de entendimento do Claude, corrigindo equívocos já nessa etapa
• Como uma pesquisa errada leva a um plano e a uma implementação errados, isso bloqueia antecipadamente o fator de falha de maior custo
• Exemplos de problemas evitados: ignorar a camada de cache, não refletir regras do ORM ou gerar lógica duplicada

Fase 2: Planning

• Após revisar a pesquisa, o Claude recebe a tarefa de escrever um plano detalhado de implementação (plan.md)
  • Incluindo snippets reais de código, caminhos dos arquivos a serem alterados e trade-offs
  • Em vez do modo de planejamento embutido, usa-se um arquivo Markdown gerenciável diretamente
• Fornecer também uma implementação de referência em open source melhora bastante a qualidade do plano elaborado pelo Claude
• Mais importante do que o documento de plano em si é o ciclo posterior de anotações (Annotation)

Ciclo de anotações

• O autor abre o plan.md e adiciona comentários inline diretamente
  • Corrigindo suposições erradas, rejeitando abordagens e acrescentando conhecimento de domínio
  • Ex.: “isso deve ser PATCH”, “cache é desnecessário”, “o campo visibility deve ir para o nível da lista”
• Depois, o Claude recebe a instrução de “atualizar o documento refletindo os comentários, mas sem implementar ainda”
• Esse ciclo de comentar e atualizar é repetido de 1 a 6 vezes, e o comando “don’t implement yet” evita execução prematura
• O documento em Markdown funciona como um estado compartilhável, mais claro e estruturado do que instruções apenas conversacionais
• Com a repetição, um plano genérico evolui para uma especificação perfeitamente ajustada ao sistema real

Criação da Todo List

• Antes da implementação, o Claude recebe a tarefa de acrescentar uma lista detalhada de tarefas (todo list)
  • Incluindo subtarefas por etapa para acompanhar o progresso
  • Como o Claude marca os itens concluídos, fica fácil entender o estado atual mesmo em sessões longas

Fase 3: Implementation

• Depois que todas as decisões foram fechadas, a execução é iniciada com um prompt padronizado
  • Como “não pare até concluir todas as tarefas”, “sem comentários desnecessários”, “proibido usar tipos any/unknown”, “executar typecheck continuamente” etc.
• Esse comando corresponde a uma etapa mecânica de executar o plano como está, já que o julgamento criativo foi concluído antes
• Implementar sem planejamento leva a construir código sobre suposições erradas, então a regra “don’t implement yet” é a principal proteção de segurança

Feedback durante a implementação

• Durante a execução, o autor assume o papel de supervisor
  • O feedback é passado de forma curta e clara: “faltou esta função”, “mover para o app admin” etc.
  • Em mudanças de frontend, também se usam instruções breves como “wider”, “2px gap” ou screenshots
• O código existente é usado com frequência como referência para manter a consistência de UI/UX
• Se o trabalho seguir em direção errada, fazer git revert e tentar novamente com escopo menor é mais eficaz do que corrigir gradualmente

Permanecendo no controle

• Não se dá autonomia total ao Claude; a decisão final continua sempre com a pessoa
• Apenas parte das sugestões do Claude pode ser escolhida, modificada ou removida, e as decisões técnicas podem ser redefinidas
  • Ex.: “na primeira use Promise.all”, “ignore a quarta e a quinta”
  • “remover a função de download”, “não alterar a assinatura da função”, “usar o método de uma biblioteca específica” etc.
• O Claude fica com a execução mecânica, enquanto a pessoa cuida de julgamento e priorização

Sessões únicas e longas

• Da pesquisa à implementação, tudo é feito em uma única sessão longa
  • Durante a sessão, o Claude acumula contexto continuamente, mantendo contexto suficiente com auto-compaction
  • O plan.md é preservado em sua forma completa ao longo de toda a sessão e pode ser consultado a qualquer momento

Resumo principal

• “Leia em profundidade, escreva o plano, refine com comentários e então execute de uma vez.”
• Mesmo sem prompts complexos ou instruções de sistema, é possível garantir alta qualidade com um pipeline disciplinado que separa Thinking de Typing
• Research evita mudanças feitas sem entendimento, Plan evita mudanças erradas, e Annotation injeta o julgamento humano
• A execução final é feita como um procedimento automatizado depois que todas as decisões já foram definidas, completando uma estrutura eficiente de colaboração

[naka98]

Também continuo enfrentando problemas parecidos. Quando colaboro com IA apenas no formato de chat, a decomposição do trabalho (WBS), o progresso e o registro das decisões acabam ficando pouco claros.

[pcj9024]

Se você simplesmente colocar o arquivo de plano dentro do repositório e fizer com que as mudanças geradas ao executar esse plano sejam salvas, o contexto acaba sendo mantido bem melhor.

[geekbini]

Esse conteúdo não se limita apenas ao Claude; parece que também pode ser aplicado de forma geral a outros serviços de IA baseados em CLI.

[GN⁺]

Comentários do Hacker News

• O ponto realmente central não é “planejar ou não”, e sim fazer o modelo explicitar suas suposições antes que elas se cristalizem em código
  LLMs falham menos na sintaxe e mais em premissas invisíveis, como arquitetura ou restrições. Por isso, um plano documentado vira uma superfície onde essas premissas podem ser depuradas

  • Nesse sentido, uma arquitetura com subagentes ajuda bastante. Se um cuida do planejamento, outro da implementação e outro da revisão, os papéis ficam claros. Também dá para fazer algo no estilo blue team/red team. No fim, a chave é ajudar o LLM a raciocinar corretamente com instruções mais claras
  • Incluir no guia o fluxo completo do caso de uso evita que o modelo tome atitudes sem sentido
  • Mas o próprio ato de expor essas suposições também pode mudar o comportamento do modelo. É como quando você coloca uma linha de printf() e o Heisenbug desaparece
  • Quase sem erro de sintaxe? Minha experiência foi diferente. Ao tentar adicionar um backend S3 a um pequeno projeto em Rust, o Claude entrou num loop de alucinação de API e queimou $20 em 30 minutos. E era só um problema simples de sintaxe
  • Será que este texto não foi escrito com ChatGPT?

• Dizem que é preciso usar palavras como “profundamente” ou “em detalhes” para o Claude não ler de forma superficial, mas sinceramente eu não consigo entender isso intuitivamente

  • Isso acontece por causa do mecanismo de attention. O LLM foi treinado na internet inteira, e textos com expressões como “observe os detalhes do problema” em geral contêm respostas de nível especialista. Então, quando essas palavras aparecem, o modelo tende a dar mais peso a esse tipo de dado. É o mesmo motivo de prompts como “aja como um professor do MIT” funcionarem
  • Mas esse tipo de explicação parece superstição. Não há evidência estatística validada, e isso soa como um pensamento mágico do tipo oferecer sacrifícios ao deus do sol. Se realmente funcionasse, daria para provar como um problema de otimização, mas ninguém publica os dados
  • Estamos mesmo numa era estranha do desenvolvimento de software. Ninguém sabe por que os LLMs se comportam desse jeito. Só torcemos para que o prompt mexa nas probabilidades a nosso favor. Era uma área antes determinística, e agora estamos escrevendo comandos em negrito num arquivo AGENTS.md como pais falando com filhos
  • É impressionante que alguém ainda leve isso a sério depois de ler esse tipo de coisa. Parece quase astrologia aplicada à engenharia
  • Se você imaginar o espaço latente (latent space) do modelo como uma paisagem, fica mais fácil entender. O prompt é como deixar uma bola cair num ponto específico, e a escolha das palavras define para qual vale essa bola vai rolar. Expressões como “em profundidade” fazem a bola permanecer mais facilmente na região desejada. Talvez não seja uma explicação perfeita, mas pensar assim funcionou bem na prática para mim

• Eu uso uma estrutura com três tipos de documento e duas skills
  Specs são os documentos estáticos de design do projeto, Plans são os planos de execução gerados pelo LLM, e arquivos de working memory acompanham o andamento.
  Eu crio novos planos com a planner skill do Gemini Pro e executo com a implementer skill do Codex.
  Assim, o contexto fica leve e focado, então a eficiência é alta. Mesmo com os planos de $20 do Codex/Gemini, dá para avançar com boa velocidade

  • Eu faço algo parecido. Crio arquivos spec com base em papers e evoluo o plano interagindo com o Claude. Gerencio requisitos–testes–documentação de definição como num documento de engenharia de sistemas no estilo IEEE. O Claude segue bem quando recebe guardrails. Para mim, ele combina mais com meu estilo do que o Codex
  • Boa abordagem. Mas fico na dúvida se um monorepo é uma escolha melhor na era da IA. Na nossa empresa, dividimos os apps em Next.js em vários repositórios, e estou pensando se não seria melhor juntar tudo

• A ideia de deixar comentários diretamente no documento de planejamento parece bem interessante. Fico curioso para saber se existe alguma forma de armazenar esses comentários separadamente ou gerenciá-los para revisão posterior

• Há algumas coisas nessa abordagem de que eu não gosto
  Primeiro, o modelo big bang de gerar todo o código de uma vez cria um bloco enorme de código difícil de entender. Eu acho melhor planejar e executar em etapas.
  Segundo, é frustrante dar feedback sem atualizar a base de conhecimento. Seria preciso registrar a causa dos erros para não repeti-los depois.
  Por fim, não há menção a testes. Seria bom incluir ao menos parte de desenvolvimento orientado a testes (TDD). É interessante pensar em como o desenvolvimento com suporte de IA vai se integrar a metodologias desse tipo

  • Tive uma experiência parecida. Divido o PLAN.md por etapas e escrevo os prompts com cuidado para executar só cada etapa específica. Também incluo testes no plano, mas por enquanto costumo adicioná-los mais para o fim

• Esse workflow é, na verdade, a forma padrão de usar o Claude Code recomendada pela Anthropic. Mas a desvantagem é que, se o plano não estiver perfeito, você precisa recomeçar desde o início.
  Por isso eu separo design → planejamento → execução em vários lotes. Quando você divide o plano em unidades de até 1.500 linhas, fica muito mais fácil controlar a complexidade.
  No meu app de 30 mil LOC, tenho 100 mil linhas de plano. É impossível fazer tudo de uma vez

  • Tive a mesma experiência. Por isso quebro em unidades de planejamento menores e gerencio os commits com branches por funcionalidade. Com IA, meus hábitos de desenvolvimento até melhoraram
  • Na verdade, é meio constrangedor chamar de workflow “radicalmente diferente” algo que no fim é só usar o modo Plan padrão
  • Eu também acho que a resposta é a execução gradual. Concluir um projeto gigantesco de uma vez ainda é pura fantasia
  • Não tem problema se o plano não for perfeito. Basta reverter só as partes alteradas pela IA e iterar de novo a partir da etapa anterior. A chave é reduzir a complexidade com mudanças pequenas
  • 100 mil linhas de plano dão quase um milhão de palavras. Só para ler isso já levaria 66 horas. É inviável na prática

• Em vez de plan.md, eu trabalho com scaffold executável e loops de validação
  Construí com IA um sistema real de pagamentos chamado Kolibri Tickets. O ponto principal não é o modelo escrever código rápido, mas projetar o loop de validação

  • manter uma estrutura executável desde o começo
  • adicionar apenas fatias verticais finas por vez
  • forçar artefatos verificáveis, como testes, tipos e máquinas de estado
  • tornar refatoração algo rotineiro
    Fazendo isso, dá para implantar mais rápido de verdade, e não só cair numa “ilusão de velocidade”. Documento de plano é uma forma de manter estado compartilhado, e um harness verificável é outra
  • Eu também passei a mirar em 100% de cobertura de testes agora que o código ficou barato. Estou adotando tipagem estática em Python, testes com Playwright e até mutation testing. Hoje os agentes conseguem rodar em loop por uma hora e entregar código que quase não precisa de correção

• Eu uso o Claude Code para preparar aulas
  Escrevo notas de aula em Quarto, e peço ao Claude para convertê-las em slides no Slidev. Depois, deixo comentários nos slides com feedback como “dividir isso em dois slides” ou “adicionar uma imagem aqui”.
  Esse feedback baseado em comentários é muito poderoso. Ajuda bastante com a distância entre tokens e a preservação de contexto

  • O próprio Quarto já suporta vários formatos, como PowerPoint, PDF e HTML. Então por que usar Slidev? Não daria para pedir ao Claude para regenerar o documento em Quarto?
  • Fiquei curioso se o feedback é deixado em comentários inline. Algo como # mudar esta parte para X?
  • Você chegou a abrir o código dessa skill do Claude?

• Ferramentas como Kiro da Amazon, Antigravity do Google, Spec Kit do GitHub e OpenSpec já oferecem esse tipo de funcionalidade

• O fracasso mais caro da programação assistida por IA não é erro de sintaxe, e sim uma implementação que funciona parcialmente, mas quebra o sistema como um todo
  Por isso, eu adiciono um brief.md logo no começo, especificando a definição do problema, métricas de objetivo e critérios para interromper funcionalidades. Isso reduz o custo de desalinhamento entre objetivos de negócio e implementação técnica