🗺️O novo fluxo dos devs: planejar como gente grande, codar com IA
Santiago Valdarrama, referência em engenharia de software, compartilhou o workflow que está usando com o Claude Code: duas etapas separadas antes de codar qualquer coisa. Primeiro, uma fase de design que analisa o código existente, faz perguntas, propõe alternativas e gera uma especificação. Depois, uma fase de planejamento que quebra tudo em tarefas pequenas e prescritivas. --- O resultado é um plano em markdown tão detalhado que parece receita de bolo: "Passo 1: escreva o teste. Passo 2: rode e garanta que falha. Passo 3: implemente. Passo 4: rode e garanta que passa." Segundo ele, agentes de código adoram instruções assim - pequenas, detalhadas, sequenciais. --- Matt Pocock, outro dev conhecido, testou uma abordagem complementar: iterar na velocidade máxima até ter um protótipo que funcione, e depois usar o agente pra reorganizar e limpar a arquitetura. "Vamos ver se dá pra polir o código gerado no improviso", brincou. São duas filosofias diferentes, mas o padrão é o mesmo: o humano pensa, a IA executa.
I'm now using two separate skills to generate a plan before I give it to Claude Code: designing → planning The "designing" skill does the following: 1. Gathers context by looking at local files, commits, and documentation. 2. Analyzes my request 3. Interviews me with clarifying questions 4. Proposes alternative solutions 5. Writes a specification document Then, the "planning" skill takes over: 1. Reads the specification document 2. Breaks it down into small tasks 3. Generates a plan specifying how to complete each task The output of running these two skills is a set of markdown files I can give the agent to implement (sometimes in parallel, sometimes sequentially). These plans are very prescriptive. Here is an example of what a potential plan could look like: """ Goal: Implement add() function File: src/calculator .py Description: Implement an add() function that takes two values and returns the sum. Step 1: Implement a filing test in tests/test_calculator .py Step 2: Run the test and ensure it fails Step 3: Implement the add() function Step 4: Run the test and ensure it passes Step 5: Run a code review Step 6: Commit the code """ I've found that these agentic coding tools love detailed, bite-sized instructions.
— @svpino View on X
Desenvolvedores experientes estão abandonando a prática de pedir às IAs para "apenas codar". O novo padrão de produtividade exige separar rigorosamente o planejamento da execução, tratando agentes de código como implementadores de especificações técnicas detalhadas, não como arquitetos de soluções.
O workflow em duas etapas
Santiago Valdarrama estruturou seu fluxo com o Claude Code em duas fases distintas antes de gerar qualquer linha de código:
**Fase de designing:** - Coleta contexto analisando arquivos locais, commits e documentação existente - Examina a solicitação e faz perguntas esclarecedoras para eliminar ambiguidades - Propõe alternativas técnicas e consolida tudo em um documento de especificação formal
**Fase de planning:** - Consome a especificação e a decompõe em tarefas atômicas - Gera um plano prescritivo em markdown detalhando cada passo — desde escrever testes unitários até executar code review
O resultado funciona como uma receita técnica onde o agente sabe exatamente o que fazer em cada momento.
Por que micro-instruções funcionam
Ferramentas de agentic coding operam com maior precisão quando recebem instruções fragmentadas e sequenciais. Ao invés de solicitar "implemente uma calculadora", o desenvolvedor fornece passos delimitados: escreva o teste, execute e confirme a falha, implemente a função, valide o sucesso. Essa granularidade reduz alucinações do modelo e minimiza o débito técnico gerado por soluções improvisadas que quebram integrações existentes. O padrão se alinha ao TDD (Test Driven Development) e práticas de engenharia de software tradicionais, mas acelerado pela capacidade da IA de executar mecânicas repetitivas sem perder o foco na lógica de negócio.
Duas filosofias, mesmo princípio
Matt Pocock, outro desenvolvedor influente, experimenta uma abordagem complementar: iterar em velocidade máxima até obter um protótipo funcional, para depois utilizar o agente especificamente para refatorar e reorganizar a arquitetura. Embora distintas, ambas as metodologias convergem em um ponto fundamental — o humano define a estratégia e a estrutura, enquanto a IA cuida da implementação operacional.
Implicações para o mercado brasileiro
Para desenvolvedores e tech leads no Brasil, essa separação de responsabilidades exige uma mudança na gestão de prompts e na arquitetura de sistemas. A disciplina de especificar antes de executar reduz drasticamente o tempo gasto em correções posteriores e eleva a qualidade do código gerado por LLMs. Em um cenário onde a commoditização da codificação acelera a competição por talentos, a capacidade de planejar como "gente grande" — definindo escopo, edge cases e critérios de aceitação antes da execução — torna-se o diferencial técnico efetivo entre profissionais juniores e seniores.