Este artigo busca explorar como programar com assistência de IA, em especial usando o Claude Code, pode te levar a escrever um código melhor, não só fazê-lo mais rápido. A IA pode acelerar o desenvolvimento, sim, mas o foco aqui está em melhorar a qualidade, a manutenibilidade e a efetividade geral do código produzido.
Não me interprete mal: você vai ser mais rápido de qualquer jeito, porque a IA escreve código mais rápido que qualquer humano, mas o objetivo não é a velocidade, e sim obter melhores resultados. A rapidez é um efeito colateral do uso de uma IA.
Se você procurar no Google (ou perguntar para sua IA favorita), vai encontrar toneladas de boas práticas para trabalhar com IA, cheias de estratégias a seguir, dicas de configuração, a lógica e a filosofia por trás de cada guia, etc. E sim, este é mais um desses artigos.
A única coisa que diferencia este de outros repositórios de guias sobre IA é que eu não prometo que seja o melhor. Aliás, tenho quase certeza de que, assim que este artigo for publicado, vou querer fazer alguns ajustes aqui e ali. Pelo menos não vou querer reescrever tudo do zero!
As coisas estão mudando bem rápido, então é importante pensar em como queremos trabalhar sem nos apegar demais aos nossos processos.
Táticas pessoais
Inspirado em um e-mail de Shaw Talebi intitulado "5 Tips That Help Me Code 5X Faster with AI", parei para refletir sobre minha própria trajetória e as estratégias que uso para gerar código assistido por IA. Curiosamente, cada uma das cinco táticas que Talebi descreveu encaixa perfeitamente com os métodos que venho usando nos últimos meses, que já descrevi antes [4]. Também comparei essas abordagens com outras fontes, o que reforça minha perspectiva sobre o tema.
Tática 1: Incorporar o LLM diretamente na sua base de código para melhorar a produtividade
TL;DR: integrar LLMs diretamente no seu fluxo de trabalho significa tratá-los como colegas júnior dentro do seu repositório, não só como assistentes de chat. Essa estratégia não só melhora a produtividade, como também acelera padrões conhecidos por meio da automação e estimula a colaboração entre a inteligência humana e a artificial.
Incorporar modelos de linguagem grandes (LLMs) diretamente no seu ambiente de desenvolvimento pode melhorar bastante o seu processo. Em vez do método "tradicional" de copiar e colar código entre uma IA como o ChatGPT e o seu ambiente de desenvolvimento integrado (IDE), considere usar um IDE potencializado por IA que integre os LLMs diretamente na sua base de código. Essa abordagem permite que o modelo acesse e compreenda o contexto de todo o seu projeto, o que torna suas sugestões mais relevantes e precisas.
Simon Willison (cocriador do Django), defensor de incorporar LLMs em ferramentas e fluxos de trabalho, destaca a importância de tratá-los não como assistentes externos, mas como partes integrais do seu kit de engenharia. Ele diz:
“O que é realmente empolgante é conectar esses modelos aos seus próprios sistemas: que consigam fazer consultas sobre seus próprios dados ou código. É aí que as ferramentas de engenharia começam a ser realmente úteis.” [1]
Ao integrar os LLMs diretamente nos seus sistemas, você passa de uma simples conversa para um software mais inteligente, capaz de se adaptar dinamicamente às necessidades do seu projeto. Essa abordagem transforma os LLMs de simples chatbots em poderosos aceleradores quando tratados como componentes programáveis.
A chave para operacionalizar a IA de forma efetiva está em integrar esses modelos no seu ciclo de desenvolvimento. Ao conectá-los ao contexto do repositório, você permite que atuem como um engenheiro sênior trabalhando em par com você:
“Trate a IA como um engenheiro sênior em par com você: especifique, revise, itere.” [2]
Manter o contexto é fundamental: preservar ideias, especificações, arquitetura e regras no repositório garante que cada prompt de IA se beneficie desse contexto enriquecido.
Para aplicar essa tática de forma eficiente:
- Use a documentação existente de projetos anteriores, como docs/convention.md e docs/workflow.md, e integre-a em novos projetos copiando-a para o diretório .cursor/rules [2].
- Estabeleça limites e diretrizes claras sobre como os agentes de IA vão interagir com a base de código.
- Crie padrões arquiteturais sólidos que os agentes possam seguir para garantir consistência.
- Desenvolva ciclos de feedback efetivos entre desenvolvedores humanos e as capacidades de IA.
Como destacado na newsletter The Pragmatic Engineer:
“A IA se destaca ao nos ajudar a implementar padrões que já entendemos. É como ter um parceiro de programação infinitamente paciente que escreve muito rápido.” [3]
Ao integrar LLMs na base de código, os times conseguem automatizar o scaffolding, o refactoring e os testes, mantendo a coerência arquitetural. Os times mais efetivos dos próximos anos provavelmente serão os que aprenderem a aproveitar essas capacidades com inteligência.
Tática 2: Escrever especificações em nível de projeto
TL;DR: integrar essa tática no seu fluxo de trabalho, escrevendo especificações de projeto detalhadas, cria um ambiente em que a criatividade humana e as soluções geradas por IA podem prosperar juntas para alcançar os objetivos do projeto.
No contexto da programação assistida por IA, uma das estratégias mais efetivas é começar por especificações detalhadas em nível de projeto. Usar ferramentas como o arquivo CLAUDE.md do Claude Code para delinear com cuidado aspectos como o stack tecnológico, a arquitetura, o escopo e os usuários-alvo pode melhorar bastante o alinhamento entre a visão do projeto e as respostas geradas pelos modelos de linguagem (LLMs). Essa abordagem minimiza os erros que vêm de suposições erradas geradas pela IA.
Simon Willison enfatiza que os engenheiros obtêm melhores resultados quando fornecem contexto estruturado. Nas palavras dele:
“Se você disser ao modelo 'é isso que queremos alcançar', funciona muito melhor. Não jogue código: descreva a intenção por trás dele.” [1]
Isso mostra a importância de não pular a fase de planejamento. A maioria das pessoas parte direto para escrever prompts, mas os LLMs brilham quando recebem uma especificação detalhada. Ao trazer clareza desde o início, você reduz as surpresas mais adiante no desenvolvimento.
A ideia é que as especificações do projeto sirvam como uma "estrela-guia" tanto para os humanos quanto para as ferramentas de IA. Elas orientam as próximas ações e garantem que todos estejam alinhados com uma mesma visão.
Segundo o guia “Vibe-Coding Done Right” [2], a especificação deve ser "uma especificação técnica concisa" que funcione como uma "fonte única de verdade":
“Escreva uma especificação técnica concisa e executável que funcione como roteiro e documentação... incluindo o stack técnico, a arquitetura do projeto, o domínio e o modelo de dados, a API, a estratégia de testes, o armazenamento, a segurança, os orçamentos de performance, a estratégia de observabilidade e logging, as feature flags, i18n/a11y, as analytics, os não objetivos e a estratégia de deploy.” [2]
Esse documento serve como ponto de referência para todas as interações com a IA: cada prompt deveria estar alinhado com essa especificação.
Além disso, existe um guia de metaprompts sobre como gerar especificações com LLMs:
“Faça perguntas se algo não estiver claro ou se houver múltiplas opções. Mas não superengenharize. Foque em um MVP pronto para produção.” [2]
Uma especificação bem documentada fornece o contexto crucial para gerar código de alta qualidade e consistente com a IA. Sem essa "estrela-guia" compartilhada, tanto os sistemas de IA quanto os desenvolvedores humanos correm o risco de otimizar em torno de objetivos errados.
Para aproveitar a IA de forma realmente efetiva (cinco vezes melhor) é essencial investir tempo no planejamento e no design desde o início. Isso garante que cada passo seguinte seja orientado por objetivos claros, em vez de partir para o código sem direção.
“A IA não está tornando nosso software dramaticamente melhor porque a qualidade do software (talvez) nunca esteve limitada pela velocidade de codificação. As partes difíceis do desenvolvimento (entender os requisitos, projetar sistemas sustentáveis, lidar com casos extremos) ainda exigem julgamento humano.” [3]
Tática 3: Fornecer documentação
TL;DR: um desafio comum quando um time quer integrar IA no seu fluxo de trabalho é que os modelos de IA não estão familiarizados com bibliotecas ou SDKs novos ou pouco comuns. A solução? Documentação completa.
Uma estratégia efetiva é criar uma pasta dedicada dentro do projeto para guardar documentos relevantes ou textos sobre ferramentas novas, internas ou pouco conhecidas. Essa pasta vira uma mina de ouro de informação que ajuda a IA a entender e trabalhar melhor com tecnologias desconhecidas. Como Simon costuma enfatizar, a documentação é o combustível da assistência efetiva de IA:
“Os melhores resultados que consigo vêm de alimentar o modelo com minha própria documentação: arquivos README, docs da API, notas de arquitetura. De repente, ele entende o meu mundo.” [1]
A mágica acontece quando a IA compreende o jargão e o contexto específicos do seu projeto. A chave está em fornecer esse contexto por meio de documentação bem estruturada.
A geração aumentada por recuperação (RAG) é a abordagem mais prática para engenheiros que buscam usar a IA de forma eficiente:
“RAG é o herói não reconhecido. Você não precisa ajustar o modelo, só dar acesso aos seus documentos.” [1]
Essa tática mostra como a documentação estruturada estabelece as bases para todas as ações futuras de um projeto. De fato, frameworks como o Vibe Coding Guide são construídos com a documentação como coluna vertebral [2], em que cada etapa gera arquivos em formato Markdown.
A documentação não ajuda só a IA, mas também os desenvolvedores, ao funcionar como um repositório de memória (que, pelo menos para mim, naturalmente falta). Seu assistente de IA vai poder oferecer sugestões contextualizadas, aumentando a produtividade e minimizando a "deriva de contexto", porque conta com notas arquiteturais, documentação da API e decisões de design. Addy Osmani destaca essa importância:
“O padrão do 'primeiro rascunho com IA': deixe a IA gerar uma implementação básica, depois revise e refatore manualmente para modularidade, adicione tratamento de erros, escreva testes completos e documente as decisões-chave.” [3]
Começar novos chats de IA para cada tarefa ajuda a manter o foco e reduzir a confusão de contexto. Essa abordagem garante revisões frequentes e ciclos de feedback fechados.
Tática 4: Iterar sobre os planos, não sobre o código
Pular direto para o código no desenvolvimento costuma levar a um caos de depuração e a problemas arquiteturais. Em vez disso, usar a IA para gerar primeiro um plano completo pode simplificar muito o processo. Essa tática melhora a eficiência do planejamento e a compreensão da funcionalidade desejada ao esclarecer a tarefa e identificar lacunas desde o início.
O poder do planejamento
Um plano bem pensado serve de guia para a programação. Dedicar tempo no início para elaborar planos detalhados é a única forma de evitar dias perdidos corrigindo a arquitetura mais adiante. Esse método enfatiza a importância de que "planejar economiza tempo de debugging” [2], não só como uma frase de efeito, mas como um princípio norteador do desenvolvimento eficiente.
Simon Willison explica isso com clareza:
“As pessoas acham que o modelo deveria escrever código perfeito. Não deveria. Deveria te ajudar a explorar possíveis soluções: a verdadeira engenharia vem depois.” [1]
Usar a IA como parceira de brainstorming, e não só como geradora de código, permite esboçar ideias e refinar abordagens antes de escrever código de produção. É uma mudança de mentalidade: usar os LLMs para pensar e iterar, não só para gerar sintaxe.
Abordagem estruturada de planejamento
Para aplicar essa tática de forma eficaz, é fundamental planejar, simular e validar a arquitetura e as tarefas antes de gerar ou editar arquivos. A estratégia envolve estabelecer ciclos de feedback fechados antes de programar [2]:
- Determinismo em vez de vibe: estabeleça checklists e critérios de aceitação claros antes de começar. Faça a IA confirmar o plano antes de gerar o código.
- Ciclos curtos: siga um ciclo estruturado (como a geração multi-turn que mencionamos neste artigo).
Como detalhado na Seção 7, Architecture Plan, do guia de Vadim Ivanov:
“Escreva um plano de implementação por etapas... Para cada passo, inclua instruções exatas indicando à IA quais arquivos criar, quais tipos, interfaces e rotas, quais migrações, quais testes e quais critérios de aceitação.” [2]
Evitar o whack-a-mole debugging
A tendência de iterar infinitamente sobre o código sem revisar as suposições de alto nível leva ao whack-a-mole debugging [3]. Em vez de pedir correções pequenas que podem afetar outras partes, uma alternativa mais eficiente é pausar, avaliar e refinar a estratégia geral.
O artigo do The Pragmatic Engineer "How AI-assisted coding will change software engineering: hard truths" explica assim:
“O padrão dos 'dois passos para trás': você tenta corrigir um bug pequeno. A IA sugere uma mudança que parece razoável. Essa correção quebra outra coisa... e você repete.” [3]
Como dissemos no nosso artigo “Ser rápido não é suficiente: como programar com velocidade usando a IA”, os desenvolvedores deveriam começar por tarefas pequenas e isoladas e ir escalando para funcionalidades mais complexas. Também deveriam revisar cada linha gerada. Seguindo esses passos, dá para aproveitar a IA para acelerar tarefas conhecidas, explorar possibilidades e automatizar atividades rotineiras.
Em resumo, entender onde a IA se destaca permite que os desenvolvedores guiem sua saída com intenção, reduzindo erros acumulados com um design e estratégias de teste mais bem pensados.
Tática 5: Fazer commits pequenos e frequentes
TL;DR: iniciar novos chats de IA para tarefas específicas ajuda a manter um contexto claro, enquanto revisar e fazer commits frequentes garante o alinhamento com os padrões de engenharia. Use a IA para acelerar seu trabalho, não para substituir seu critério: questione qualquer código gerado que não faça sentido ou seja inconsistente com seus padrões.
No mundo do código assistido por IA, fazer commits pequenos e frequentes é inestimável. Essa prática facilita reverter erros e ajuda a entender como cada mudança afeta o conjunto do projeto. Além disso, as mensagens de commit descrevem com clareza o que cada mudança faz, o que reforça a compreensão e a responsabilidade.
Simon Willison defende tratar a codificação assistida como uma prototipagem rápida, com ciclos de feedback fechados por meio de pequenos experimentos. Nas palavras dele: "prompt small, commit small". Essa filosofia estimula a construção incremental, mantendo o controle do processo. Ao registrar ideias funcionais com frequência, você reduz o risco de perder o rumo e mantém uma trajetória clara.
Adotar essa abordagem está alinhado com as melhores práticas de muitos fluxos de trabalho. Manter o trabalho atômico, observável e revisável garante clareza tanto para os humanos quanto para a IA.
Os commits frequentes permitem verificar as mudanças geradas pela IA de forma isolada. Isso reflete o padrão de "conversa constante" de Addy Osmani, com ciclos fechados entre geração, revisão e validação [3]. Cada commit funciona como um ponto de controle em que você pode "confiar, mas verificar", garantindo que a velocidade da IA não comprometa a qualidade nem a compreensão.
Conclusão
Este artigo enfatiza programar melhor com ajuda de IA, não só mais rápido, mas com mais velocidade como um efeito colateral positivo. Embora existam muitos guias, este reconhece o ritmo acelerado de mudança na IA e defende a adaptabilidade acima de processos rígidos.
Para alcançar melhores resultados, apresentamos cinco táticas-chave:
- Integrar LLMs diretamente na sua base de código para aumentar a produtividade: trate os LLMs como colegas júnior dentro do seu repo, não só como assistentes de chat.
- Escrever as especificações do projeto desde o início para alinhar a criatividade humana com a IA e reduzir erros.
- Fornecer documentação para ajudar a IA a compreender bibliotecas e ferramentas novas por meio de Retrieval-Augmented Generation (RAG).
- Iterar sobre planos, não sobre código, usando a IA para planejar, refinar e projetar antes de programar.
- Fazer commits pequenos e frequentes para manter o foco, a clareza e os padrões de engenharia sem perder a agilidade.
Ao adotar essas estratégias, os desenvolvedores podem usar a IA não só para melhorar a eficiência do desenvolvimento, mas também para elevar a qualidade e a manutenibilidade do seu software.
[1]: AI tools for software engineers, but without the hype – with Simon Willison (Co-Creator of Django) - https://www.youtube.com/watch?v=uRuLgar5XZw
[2]: Vibe-Coding Done Right: Engineering Manager's Guide to Building Production-Ready AI Apps - https://github.com/vadim-givola/vibe-coding-guide
[3]: How AI-assisted coding will change software engineering: hard truths - https://newsletter.pragmaticengineer.com/p/how-ai-will-change-software-engineering
[4]: Ser rápido não é suficiente: como programar com velocidade usando a IA - https://www.howdylatam.com/blog/ser-rapido-no-es-suficiente-como-programar-con-velocidad-utilizando-la-ia
Se você já incorporou a IA ao seu workflow individual, o próximo passo é escalar seu workflow com agentes de IA.
