Ensinando a IA a pensar como um engenheiro sênior

• Com uma metodologia que faz a ferramenta de IA para código planejar antes de escrever código, é possível evitar implementações incorretas e acelerar o desenvolvimento
• Aplicam-se 8 estratégias de planejamento conforme o nível de dificuldade, e cada estratégia segue uma estrutura em que agentes específicos pesquisam em paralelo e depois o desenvolvedor faz o julgamento e a tomada de decisão
• Cada estratégia inclui reprodução de bugs, busca por melhores práticas, análise da base de código existente, investigação do histórico do git etc., e as preferências e os padrões aprendidos pelos agentes vão se acumulando automaticamente
• É possível instalar no Claude Code o sistema disponibilizado como open source ou começar por uma única funcionalidade e, aos poucos, ensinar à IA a forma de pensar do desenvolvedor

---

Desenvolvimento orientado a planejamento com IA

• Introdução a uma abordagem que faz a IA elaborar um plano antes de escrever código
  • Em vez de apenas escrever código, esse método aumenta a velocidade de implementação de funcionalidades e reduz erros
• Como exemplo, é apresentado o processo de desenvolvimento da funcionalidade “email bankruptcy” do app de gerenciamento de e-mails Cora
  • Ao implementar uma função para organizar 53.000 e-mails sem perder mensagens importantes, um agente de pesquisa de IA fez a análise prévia
  • Isso permitiu descobrir com antecedência o limite de 2.000 itens do Gmail, timeouts do sistema e problemas de tempo de espera do usuário, evitando uma implementação incorreta

8 estratégias de planejamento

Estratégia 1: reproduzir e documentar bugs

• Objetivo: reproduzir o bug antes da correção e gerar um guia passo a passo
• Quando usar: Fidelity 1~2, especialmente em correções de bugs
• Logo após o lançamento da funcionalidade de email bankruptcy, ocorreu um problema em que 19 usuários ficaram presos em um estado de falha da tarefa
  • Ao investigar os logs do AppSignal, descobriu-se que erros de rate limit do Gmail estavam sendo ignorados em produção
  • Quando um lote falhava, toda a tarefa era interrompida, mas como o usuário não era avisado, ele via apenas um spinner de carregamento infinito
• Durante a reprodução, percebeu-se a necessidade de processamento em lotes e retomada de tarefas, confirmando que apenas tentar novamente não seria suficiente
• Efeito composto: foi adicionada à checklist do agente @kieran-rails-reviewer a verificação de “em jobs em background que chamam APIs externas, há tratamento de rate limit, retry e prevenção de estados parciais abandonados?”

Estratégia 2: investigar melhores práticas

• Objetivo: pesquisar na web casos semelhantes de resolução do problema
• Quando usar: em qualquer nível de dificuldade, especialmente com padrões pouco familiares
• Ao atualizar uma gem que estava duas versões atrasada, o agente pesquisou “caminho de upgrade da versão X para Y”, “breaking changes entre versões” e “problemas comuns de migração”
  • Encontrou o guia oficial de upgrade e 3 posts de blog de engenheiros que fizeram a mesma atualização
  • Uma pesquisa de 3 minutos evitou horas de debugging por tentativa e erro
• Também é útil para decisões não técnicas: “melhores práticas para tiers de preço em SaaS”, “copy de conversão para campanhas de e-mail drip”, “estratégia de retry para jobs em background” etc.
• Efeito composto: quando encontra padrões úteis, o sistema os salva automaticamente em arquivos docs/*.md, consultando-os primeiro na próxima pergunta semelhante antes de fazer uma busca na web

Estratégia 3: investigar a base de código

• Objetivo: procurar padrões semelhantes no código existente
• Quando usar: em qualquer tarefa que possa duplicar funcionalidades já existentes
• Antes de adicionar event tracking a uma nova funcionalidade, o agente pesquisou na base de código: “como o event tracking é tratado hoje?”, “qual é o padrão de chamadas de analytics?”, “onde os eventos são enviados?”
  • Foi encontrado um sistema de tracking já existente, inclusive com métodos helper (algo que o próprio autor havia esquecido)
  • Quando a IA não consulta a base de código, ela tende a tentar criar tudo do zero
• Em vez de criar um novo sistema de tracking, a solução foi estender o padrão existente, evitando construir um segundo sistema incompatível
• Efeito composto: criação do agente “@event-tracking-expert”, executado automaticamente ao planejar qualquer funcionalidade que exija tracking

Estratégia 4: investigar o código-fonte das bibliotecas

• Objetivo: ler diretamente o código-fonte de pacotes e gems instalados
• Quando usar: ao usar bibliotecas que evoluem rápido ou têm documentação insuficiente
• A gem RubyLLM recebe continuamente novos modelos, parâmetros e funcionalidades, mas a documentação fica para trás
  • O agente analisou o código-fonte do RubyLLM: “quais opções de modelo estão disponíveis?”, “quais parâmetros podem ser passados?”, “quais recursos não documentados existem na versão mais recente?”
  • Resultado: “suporte a streaming foi adicionado na versão 1.9, mas não foi documentado”, além dos nomes de parâmetros e exemplos de uso encontrados na suíte de testes
• Efeito composto: a cada atualização de dependência, o conhecimento também é atualizado automaticamente, evitando trabalhar com informações desatualizadas

Estratégia 5: estudar o histórico do git

• Objetivo: entender a intenção de decisões passadas analisando o histórico de commits
• Quando usar: em refatorações, retomada de trabalho ou sempre que for preciso entender o “porquê”
• Ao encontrar uma versão antiga do EmailClassifier em uso, antes de tentar o upgrade foi feita uma busca no histórico do git: “por que estamos usando a v1?”, “já tentamos atualizar para a v2?”
  • Foi encontrado um PR de outro membro do time de 3 meses antes: ao migrar para a v2, e-mails da caixa de entrada iam para o arquivo e e-mails arquivados iam para a caixa de entrada
  • A discussão no PR registrava em detalhes os motivos e mostrava que o rollback foi intencional
• Efeito composto: a memória institucional é preservada e pesquisável, permitindo que novos membros do time herdem a lógica por trás de decisões passadas

Estratégia 6: esclarecer requisitos por meio de prototipagem

• Objetivo: esclarecer requisitos com prototipagem rápida em um ambiente separado
• Quando usar: Fidelity 3, incertezas de UX e trabalho exploratório
• Ao redesenhar a interface do Brief de e-mail, foram criados no Claude 5 protótipos de layout diferentes, com 5 minutos para cada um
  • Foi possível clicar, testar e identificar os pontos desconfortáveis, além de mostrar a melhor versão a alguns usuários
  • Feedback de um usuário: “o layout é opressivo e eu não sei como arquivar um e-mail”
• Esse insight virou requisito no plano real: “o botão de arquivar deve ficar obrigatoriamente no canto superior esquerdo — a memória muscular do usuário espera essa posição por causa do Gmail”
• Efeito composto: a prototipagem transforma incerteza em especificações concretas e documenta a reação dos usuários

Estratégia 7: sintetizar com opções

• Objetivo: integrar toda a pesquisa em um único plano com trade-offs
• Quando usar: após a fase de pesquisa e antes da implementação
• Depois de executar as estratégias 1~6, o agente sintetiza: “com base nesta pesquisa, apresente 3 formas de resolver o problema. Para cada abordagem, inclua complexidade de implementação, impacto em performance, custo de manutenção e padrões existentes correspondentes”
• Exemplo de sincronização da caixa de entrada do Gmail:
  • Opção A — usar o sistema de sincronização existente: implementação rápida, mas com duplicação de código e pior separação de responsabilidades
  • Opção B — sincronização em tempo real: arquitetura mais limpa, mas mais lenta e com possível problema de confiabilidade
  • Opção C — construir um sistema de cache espelhado: melhor solução de longo prazo, separação mais limpa, mas com maior volume de trabalho inicial
• Depois da comparação, é possível tomar uma decisão informada em 30 segundos
• Efeito composto: as escolhas revelam preferências; se o desenvolvedor indicar “priorizar compatibilidade”, o sistema dará mais peso à compatibilidade em decisões semelhantes no futuro

Estratégia 8: revisão por agentes de estilo

• Objetivo: enviar o plano finalizado a revisores especializados em checar preferências do desenvolvedor
• Quando usar: na etapa final do plano, antes da implementação
• 3 agentes de revisão executados automaticamente:
  • Agente de simplificação: sinaliza overengineering, como “essa funcionalidade realmente precisa de 3 tabelas no banco? Não daria para usar 1 tabela com um campo de tipo?”
  • Agente de segurança: verifica vulnerabilidades comuns, como “este plano permite entrada do usuário diretamente em queries do banco — é preciso adicionar sanitização de entrada”
  • Agente de estilo Kieran: impõe preferências pessoais, como “há joins complexos aqui; Kieran prefere queries simples, então considere desnormalização”
• Efeito composto: com o tempo, os agentes acumulam o gosto do desenvolvedor; ao marcar “não gosto disso” ou “boa observação”, o sistema aprende

Como começar

O que você pode testar hoje

• O sistema de planejamento foi disponibilizado como open source no Github Marketplace da Every
• Ao instalar no Claude Code, é possível usar imediatamente o comando /plan e os agentes de pesquisa
• O plugin pode ser usado no Claude Code ou no Droid

Uma forma simples de começar

• Escolha uma funcionalidade Fidelity 2 que você está construindo nesta semana: algo com escopo claro e que atravesse vários arquivos (adicionar uma nova view, implementar um sistema de feedback, refatorar um componente)
• Antes de pedir à Claude Code ou ao Cursor para construir, faça 15~20 minutos de pesquisa:
  1. Melhores práticas: como outras pessoas resolveram isso? Pesquise blogs, Stack Overflow e documentação na web
  2. Seus próprios padrões: como você resolveu isso no passado? Procure funcionalidades semelhantes na sua base de código
  3. Recursos das bibliotecas: o que as ferramentas em uso realmente suportam? Use IA para ler a documentação ou o código-fonte
• Faça a IA sintetizar a pesquisa em um plano contendo:
  1. O problema a resolver (uma frase clara)
  2. De 2 a 3 abordagens de solução (com vantagens e desvantagens honestas)
  3. Padrões de código existentes que precisam ser respeitados
  4. Edge cases ou considerações de segurança
• Revise o plano e observe sua reação: se pensar “isso está complexo demais” ou “já existe uma forma melhor”, não ajuste só o plano; registre também por que você pensa assim
• Lance a funcionalidade com base no plano e compare a implementação final com o plano original: onde houve desvio? Por quê? O que teria tornado o plano melhor?
• Invista 10 minutos para formalizar um aprendizado: adicione-o ao arquivo CLAUDE.md e escreva uma regra como “ao fazer tarefas do tipo X, lembrar de checar Y” ou “preferir abordagem A à B por causa de C”
• Depois de acumular aprendizados, crie agentes de pesquisa ou comandos especializados: “Event Tracking Expert” (conhece seus padrões), “Security Checker” (sinaliza erros comuns)
• Repita na próxima semana, consulte suas notas, veja se o segundo plano é melhor do que o primeiro e, após alguns meses, construa um sistema que conhece a forma de pensar do desenvolvedor