Boas Práticas: Hábitos de Engenharia para Desenvolver com IA

📚 Navegação da Série: O capítulo anterior 48 Projeto Capstone consolidou os conhecimentos da série no desenvolvimento de um utilitário de lista de tarefas completo do zero. Este capítulo adota uma perspectiva estratégica — não introduziremos novas funcionalidades, mas organizaremos as principais orientações de boas práticas (coletadas de engenheiros experientes e da documentação oficial da Anthropic) para otimizar a velocidade e segurança de suas conversas.

"Este prompt está resumido demais."

Imagine um desenvolvedor iniciante no Claude Code digitando apenas "corrija o erro do login" no console e aguardando. Minutos depois, a IA apresenta uma refatoração extensa de rotas que não resolve o problema, deixando o desenvolvedor frustrado: "Eu não descrevi o que queria?"

No entanto, se você passar essa mesma instrução para um desenvolvedor estagiário recém-chegado à equipe, que ainda não conhece as pastas do projeto, ele seria capaz de resolver o bug? Certamente não. Ele não sabe qual fluxo de login está quebrado, qual o comportamento esperado, em quais arquivos a lógica está localizada ou como validar se a correção foi bem-sucedida.

Uma instrução eficiente e estruturada segue o formato: "Alguns usuários reportaram falhas de login após o timeout da sessão. Analise a lógica de atualização de tokens em src/auth/, crie um teste unitário que reproduza a falha e aplique a correção." Desse modo, o Claude localiza e resolve a inconsistência na primeira tentativa.

A qualidade dos resultados gerados pelo Claude Code depende fundamentalmente de como você orienta o agente. A IA possui capacidade técnica de desenvolvimento, mas necessita de parâmetros exatos de contexto para atuar. Compilaremos as melhores práticas técnicas de engenharia de prompts em regras estruturadas para o dia a dia.

Ao ler este capítulo, você obterá:

• A restrição técnica central: a janela de contexto é o recurso mais valioso da sessão, orientando todas as outras práticas.
• Cinco regras fundamentais de desenvolvimento: fornecer meios de auto-validação, separar planejamento de codificação, detalhar prompts, manter o CLAUDE.md conciso e realizar correções de rota de forma ágil.
• Tabelas comparativas contrapondo abordagens vagas e abordagens técnicas de engenharia de prompts.
• O roteiro de escolha de regras de acordo com o cenário, além de um exercício comparativo para validar os resultados no console.

---

01 A Janela de Contexto é o seu Recurso mais Valioso

Todas as boas práticas de desenvolvimento baseiam-se em uma única restrição física do sistema de inteligência artificial. A documentação oficial detalha este limite de forma clara:

A maior parte das boas práticas baseia-se em um limitador físico: a janela de contexto (context window) do Claude é preenchida rapidamente durante a sessão e, à medida que a memória acumula dados, a precisão e o desempenho analítico do modelo diminuem.

A janela de contexto armazena todas as interações da conversa — incluindo o histórico de prompts enviados por você, as respostas da IA, o código de todos os arquivos lidos e os logs de execução de comandos do terminal. Em refatorações complexas que envolvem leituras de pastas inteiras, a sessão acumula dezenas de milhares de tokens rapidamente (detalhado no Capítulo 19).

Quando a memória atinge limites elevados, o Claude Code torna-se impreciso, esquecendo instruções iniciais ou gerando inconsistências de lógica simples.

Analogia: O quadro branco de anotações. Imagine o Claude como um engenheiro assistente que possui raciocínio lógico rápido, mas trabalha em uma mesa contendo apenas um quadro branco de tamanho fixo. Toda instrução que você passa, todo arquivo de código que ele lê e todo log de teste gerado deve ser anotado nesse quadro. Quando o quadro fica totalmente preenchido de anotações, ele precisa apagar dados antigos para escrever as novas tarefas. Se o quadro acumular rascunhos de testes antigos ou erros passados, o assistente começará a esquecer as regras iniciais do projeto.

Gerenciar a sessão consiste em poupar o preenchimento desse quadro branco:

• Fornecer meios de validação automática para que a IA teste o código de forma independente, evitando loops repetitivos de perguntas e respostas que poluem a memória.
• Orientar o agente a planejar antes de programar, evitando gerar códigos incorretos que preenchem o quadro com lógicas descartadas.
• Escrever prompts específicos e detalhados na primeira instrução para evitar sessões longas de esclarecimentos.
• Manter as orientações permanentes do CLAUDE.md enxutas, evitando que dados secundários consumam o topo do quadro de anotações.
• Interromper a sessão e limpá-la (via /clear) assim que identificar que o agente tomou um caminho de refatoração equivocado.

Dominar estas regras garante o melhor desempenho analítico da IA durante todo o projeto.

💡 Resumo em uma frase: A janela de contexto acumula dados e reduz a acuidade da IA ao longo da sessão; poupe o espaço de memória adotando práticas de auto-validação, especificidade e limpeza de histórico.

---

02 Forneça Meios de Auto-Validação Técnica

Esta é uma das diretrizes mais importantes de desenvolvimento assistido:

Forneça ao Claude um comando de validação executável localmente — como suites de testes unitários, scripts de build ou validadores visuais. Isso diferencia sessões eficientes daquelas que exigem monitoramento manual contínuo.

A ausência de testes locais transfere o trabalho de validação de código para você, conforme aponta a documentação oficial:

Quando a tarefa parece concluída sob a perspectiva visual da escrita, o Claude encerra a edição. Se não houver testes que ele possa executar autonomamente no terminal, o critério de "parece concluído" é a única sinalização disponível, e o desenvolvedor passa a atuar como validador manual das saídas.

Em vez de atuar como revisor manual de cada linha de código proposta, integre um teste que retorne sucesso (pass) ou falha (fail) no terminal. Desse modo, o Claude Code roda o teste, lê o log de erro, ajusta a lógica e repete o processo de forma autônoma até obter a validação positiva.

Analogia: Equipe de assentamento de pisos. Ao contratar um profissional para assentar pisos na empresa, se você não fornecer um instrumento de medição (como um nível de bolha ou régua técnica), ele concluirá o trabalho confiando apenas na própria visão técnica. Eventuais desníveis só serão percebidos por você após a secagem. Fornecer a suite de testes equivale a entregar a régua de medição técnica nas mãos do assentador: ele mesmo confere cada peça colocada e corrige os desníveis antes de entregar a obra concluída.

Recursos recomendados para automação de validações na CLI:

• Suites de testes unitários (como pytest ou jest, que informam as falhas lógicas de forma direta no console).
• Scripts de compilação (build tools) (para validar erros de sintaxe ou tipagem estática).
• Linters de formatação (para garantir a padronização de escrita de código).
• Scripts de comparação de saídas técnicas.
• Ferramentas de captura e comparação visual (Capítulo 40).

Exemplos práticos de engenharia de prompts focados em validação:

Cenário de Código	❌ Prompt Sem Validação	✅ Prompt Com Auto-Validação
Criação de Funções	"Escreva uma lógica para validar endereços de e-mail."	"Desenvolva o método validateEmail em JS. Regras de teste: user@example.com é válido, invalid é inválido e user@.com é inválido. Execute a suite de testes local após a escrita para validar."
Ajustes de Layout	"Melhore o visual do painel de controle."	"[Insira a imagem de referência] Ajuste a estilização do card conforme o mockup. Tire uma captura de tela do navegador local, compare os diffs visuais e aplique as correções necessárias."
Correção de Builds	"O build do projeto está quebrando."	"O build retornou a seguinte falha: [Insira o log de erro]. Corrija a inconsistência e valide rodando o script de build local. Trate o problema raiz e evite desativar validações de linters."

A diferença crucial é que a coluna da direita entrega à IA as ferramentas necessárias para medir e validar a entrega de forma autônoma.

Ao instruir o agente a corrigir problemas lógicos de tipagem, reforce a necessidade de corrigir a causa raiz, em vez de aplicar conversões genéricas de tipos (como converter variáveis para any no TypeScript) apenas para passar pelos validadores de compilação.

Adicionalmente, exija que a IA apresente as evidências físicas de validação no chat:

Solicite ao Claude que exiba os dados de validação — como saídas do comando de testes do console ou imagens geradas —, em vez de apenas declarar textualmente que a tarefa foi concluída.

Isso aumenta a confiabilidade da entrega de tarefas de background.

💡 Resumo em uma frase: Forneça comandos de teste locais nos prompts para que o Claude valide seu próprio código, reduzindo loops manuais de verificação e garantindo a correção de bugs em nível de sistema.

---

03 Separe as Etapas de Planejamento e Codificação

Para refatorações extensas ou desenvolvimento de novos módulos, evite iniciar a escrita de código de imediato.

Instruir o Claude a iniciar a programação de imediato em problemas de larga escala frequentemente resulta em códigos desalinhados à arquitetura do projeto. Separe as etapas de diagnóstico/planejamento da escrita de arquivos física.

O ciclo de desenvolvimento recomendado pela documentação oficial divide-se em quatro fases distintas:

As etapas da esquerda focam em analisar e arquitetar o código sem modificar os arquivos locais. A linha divisória central indica o momento em que você aprova o plano técnico da IA e altera o console do Modo Plan para a escrita de dados no repositório.

Separar a análise da escrita física reduz riscos. A IA utiliza o Modo Plan (Modo de Planejamento) para ler arquivos e detalhar a arquitetura técnica sem gravar arquivos no disco.

Para iniciar a fase de exploração no Modo Plan, envie prompts de leitura contextualizados:

Analise a pasta src/controllers para identificar como o fluxo de sessoes de tokens e cookies está implementado. Indique como os dados sao armazenados sem alterar nenhum arquivo.

O agente lê a lógica local, expõe o funcionamento dos arquivos e apresenta uma proposta técnica de refatoração no chat. Se você identificar falhas na arquitetura proposta, edite a proposta técnica no editor de texto (usando o atalho Ctrl+G no console) e envie de volta com os ajustes antes de autorizar a fase de codificação.

No entanto, adote o bom senso conforme a complexidade da tarefa:

Para refatorações locais de escopo reduzido (como correções de ortografia, inclusão de mensagens de logs ou renomeação de variáveis), instrua o Claude a aplicar as mudanças diretamente no código.

Diretriz prática de decisão de escopo:

Se você puder resumir as modificações necessárias em uma única frase de commit, pule a fase de planejamento e codifique de imediato.

Para pequenas manutenções, o planejamento gera burocracia de tarefas desnecessária. Utilize a fase de planejamento apenas quando o desenvolvimento envolver múltiplos arquivos, lógicas não estruturadas ou bibliotecas desconhecidas.

💡 Resumo em uma frase: Pule o planejamento apenas em correções simples de uma linha; para mudanças que afetam múltiplos arquivos, utilize o Modo Plan para estruturar a arquitetura técnica antes de autorizar a gravação física no disco.

---

04 Escreva Prompts Específicos e Detalhados

Esta regra foca na precisão da escrita de prompts:

Quanto mais específico for o seu prompt, menor será a necessidade de refatorações de código de acompanhamento. A IA possui capacidade lógica, mas necessita de parâmetros detalhados de atuação para evitar caminhos incorretos.

Mapear nomes de arquivos exatos, limites de escopo e exemplos práticos de escrita no repositório melhora as respostas da IA.

Comparativo de prompts:

Tipo de Orientação	❌ Prompt Vago	✅ Prompt Técnico Específico
Escopo de Arquivos	"Adicione testes de cobertura para o arquivo users.py."	"Escreva testes unitários para a classe User em users.py. Cubra cenários de usuários deslogados e evite o uso de estruturas de mock em banco de dados."
Fontes de Consulta	"Por que a classe Factory está retornando erro?"	"Consulte o histórico de commits do Git do arquivo Factory.java para identificar o motivo de a assinatura do método ter sido alterada na última release."
Padrões de Escrita	"Crie um componente de formulário para a tela."	"Analise a estrutura de componentes existentes em components/Card.vue. Siga o mesmo padrão de tags e classes locais para construir um componente de formulário de contato, sem adicionar dependências externas de CSS."
Descrição de Falhas	"Corrija o erro do painel."	"Usuários reportaram erros de renderização no painel após o carregamento de listas vazias. Verifique a lógica de retorno do método getList em controller.ts, crie um teste de regressão que valide o retorno de listas vazias e aplique a correção."

A coluna da direita remove a ambiguidade da instrução. Ela especifica onde a IA deve atuar, quais restrições de arquitetura seguir e qual o comportamento de validação esperado.

O recurso de apontar referências de código existentes (terceira linha da tabela) é eficiente para garantir a padronização do código: indicar arquivos funcionais do repositório como exemplos de escrita instrui o Claude Code a seguir o mesmo estilo de desenvolvimento e nomenclatura, sem a necessidade de ditar regras de estilo de sintaxes extensas no prompt.

Você também pode usar prompts abertos intencionalmente em fases de diagnóstico:

Prompts vagos e abertos são úteis exclusivamente na fase de diagnóstico técnico inicial do projeto.

Prompts como "Quais melhorias de performance você sugere para este módulo?" ajudam a localizar débitos técnicos que você não havia mapeado. Após identificar os pontos críticos, restrinja o escopo da tarefa enviando prompts detalhados para a codificação de cada melhoria.

Fornecendo Contexto no Prompt

Forneça os arquivos e fontes de dados necessários de forma estruturada:

• Use o gatilho @ no console para indicar arquivos e diretórios específicos da máquina de forma direta.
• Cole imagens e capturas de tela de mockups ou logs de erros visuais diretamente no chat.
• Insira URLs e caminhos de documentações externas (e adicione os domínios na Allowlist via /permissions para agilizar acessos).
• Utilize a entrada por tubos do console (cat error.log | claude) para transferir logs longos de falhas.

💡 Resumo em uma frase: Escreva prompts específicos indicando arquivos, restrições e padrões funcionais do repositório como referência, limitando o uso de termos abertos apenas para diagnósticos iniciais.

---

05 Mantenha o CLAUDE.md Objetivo e Enxuto

As boas práticas de documentação do arquivo CLAUDE.md determinam a precisão do agente a longo prazo. Revisamos as diretrizes operacionais do arquivo:

O CLAUDE.md é lido de forma automática a cada inicialização de sessão da CLI, servindo para registrar caminhos de builds, suites de testes e estilos de escrita do repositório (Capítulo 18).

Analogia: Bilhete de orientações fixado no monitor. Ao sair de férias, você deixa uma folha de papel colada no monitor do computador do seu assistente contendo apenas três informações cruciais: a senha temporária do ramal, o IP do servidor de testes e o contato do cliente prioritário. O assistente lê essas regras em poucos segundos sempre que senta na mesa de trabalho. Se você colasse um manual de duzentas páginas sobre políticas corporativas no monitor, o assistente ignoraria o papel por conta da densidade dos dados, deixando de ler as informações prioritárias de suporte.

A documentação oficial alerta sobre a redundância de dados no arquivo:

Mantenha o arquivo CLAUDE.md objetivo. Para cada linha inserida, verifique se a sua ausência induziria a IA a cometer erros de desenvolvimento. Arquivos CLAUDE.md muito extensos ou redundantes dispersam a atenção do modelo, fazendo com que ele ignore suas instruções diretas no chat.

Evite cadastrar explicações de design de arquitetura complexas ou trechos longos de documentações de código no arquivo. Deixe que o Claude infira essas regras lendo o código-fonte existente no repositório. Mantenha no CLAUDE.md apenas parâmetros práticos que a IA não tem como deduzir sozinha — como comandos exatos de compilação ou comportamentos específicos de rotas do projeto.

Guia de inclusão de regras no CLAUDE.md:

✅ Regras Adequadas para Inclusão	❌ Dados Redundantes a Serem Removidos
Comandos de compilação e build específicos da máquina local.	Explicações lógicas de funcionamento do código do repositório.
Comandos específicos para rodar testes unitários locais.	Regras de tipagens óbvias da linguagem (como guias padrão de Java).
Diretrizes de padrões de commits exigidos pelo time.	Documentações longas de APIs externas (utilize URLs de referência).
Variáveis de ambiente obrigatórias para rodar a aplicação localmente.	Informações datadas sobre refatorações que já foram concluídas.
Decisões atípicas de design (ex: "Não use a pasta standard").	Descrições de utilidade de cada arquivo do projeto.

Se você notar que a IA está ignorando diretrizes do CLAUDE.md, reduza a extensão do arquivo e simplifique as frases operacionais. Para regras específicas que se aplicam apenas a arquivos ou tarefas pontuais do projeto, salve-as como Agent Skills (Capítulo 26) em vez de inflar o arquivo de configuração principal.

💡 Resumo em uma frase: O arquivo CLAUDE.md deve conter apenas comandos de build, testes e especificações atípicas do projeto; remova dados redundantes que a IA pode ler no código para economizar contexto.

---

06 Faça Correções de Rota de Forma Ágil

O gerenciamento ativo das sessões de chat previne o acúmulo de contexto com lógicas incorretas.

Ao identificar que o Claude Code tomou um caminho incorreto de refatoração ou começou a ler arquivos desalinhados à tarefa, interrompa e corrija a rota imediatamente.

A CLI oferece um conjunto de ferramentas para controle e reversão rápida de caminhos de execução:

Ação Desejada	Comando de Acionamento	Aplicação Prática
Parar processamento	Tecla Esc simples no terminal.	Interrompe comandos Bash longos ou leituras incorretas de arquivos.
Reverter edições locais	Comando /rewind ou teclas Esc consecutivas.	Restaura os arquivos modificados na sessão de chat ativa para o estado anterior.
Descartar alterações parciais	Instrução textual: "Descarte a última alteração".	Descarta a última edição de um arquivo de forma ágil.
Limpar memória da sessão	Comando /clear no terminal.	Limpa o histórico de contexto do chat para iniciar uma nova tarefa.

A regra prática de limite de correções é definida na documentação oficial:

Se você precisar corrigir a lógica proposta pela IA mais de duas vezes na mesma conversa para resolver um mesmo problema, a memória da sessão já está poluída com propostas incorretas. Execute o comando /clear para limpar o chat, ajuste seu prompt inicial incluindo as lições aprendidas e inicie um novo chat.

Iniciar uma conversa limpa contendo um prompt estruturado com os caminhos que falharam resolve o bug de forma mais rápida do que tentar depurar um histórico longo e confuso de conversas passadas.

Para tarefas analíticas de inspeção extensas, use a delegação via subagentes para preservar a memória do chat principal. Diga no chat "use um subagente para listar as ocorrências do método X", mantendo a sessão principal limpa e responsiva.

💡 Resumo em uma frase: Pare execuções incorretas imediatamente com Esc ou /rewind. Se o Claude falhar na correção de um bug por três vezes seguidas, execute o /clear e reescreva o prompt inicial com as lições aprendidas.

---

07 Dicas de Comunicação e Usabilidade

Pequenos hábitos de comunicação no console melhoram a ergonomia do fluxo de trabalho diário:

• Interaja com o Claude como faria com um colega de equipe sênior: Evite termos de comandos truncados ou rebuscados. Faça perguntas diretas que você faria a um desenvolvedor experiente ("Por que esta rota está priorizando o arquivo A em vez do B?", "Como posso incluir um novo endpoint neste controller?").
• Solicite que a IA crie especificações técnicas em projetos grandes: Antes de autorizar a escrita física de código em demandas complexas, instrua o Claude a gerar um arquivo SPEC.md contendo as regras e a arquitetura técnica propostas. Revise a especificação, faça as edições necessárias e utilize o documento como guia para a codificação em um chat limpo.
• Exija evidências físicas de validação: Evite aceitar mensagens como "ajustes aplicados com sucesso". Sempre inclua instruções como "rode a validação técnica local e apresente o log de saída para homologação".

---

08 Exercício Prático: Validando a Diferença de Prompts Específicos

Realizaremos um teste básico de desenvolvimento para verificar a diferença prática de legibilidade e validação entre prompts vagos e prompts técnicos detalhados.

Requisitos: Claude Code instalado na máquina de desenvolvimento.

Passo 1: Criar o diretório de testes (no terminal do sistema)

mkdir cc-boas-praticas-demo && cd cc-boas-praticas-demo && claude

Passo 2: Testar o comportamento com um prompt genérico

Na sessão do Claude, envie a seguinte instrução:

Escreva uma lógica para validar a força de uma senha.

Resultado esperado: O Claude criará um método de validação de senhas genérico. As regras de validação (comprimento mínimo, caracteres especiais) serão decididas de forma arbitrária pela IA e não haverá testes ou formas de validação automatizadas no chat, exigindo que você analise o código manualmente para deduzir as regras aplicadas.

Passo 3: Limpar a sessão e enviar o prompt detalhado

Limpe o histórico de contexto do chat ativo:

/clear

Envie o prompt contendo especificações exatas de validação e comandos de testes locais:

Escreva o método isStrongPassword(pwd) no arquivo password.js.
Regras de validação obrigatórias:
1. Comprimento mínimo de 8 caracteres.
2. Deve conter pelo menos uma letra maiúscula.
3. Deve conter pelo menos um número.
Exemplos de validação de testes:
- "Abc12345" deve retornar true.
- "abc12345" deve retornar false (sem maiúscula).
- "Abcdefgh" deve retornar false (sem número).
Crie um script de validação local contendo estes casos de testes, execute-o e exiba a saída no console para homologar a entrega.

Resultado esperado: A IA analisa as restrições e desenvolve a lógica exata de validação no arquivo password.js. Em seguida, cria o script de testes correspondente, executa-o no terminal local de forma direta e apresenta o log de saída com o resultado de sucesso de cada um dos três cenários no chat.

Passo 4: Limpar o repositório de testes

Encerre a sessão digitando /exit e remova o diretório de testes do seu computador.

💡 Resumo em uma frase: O exercício prático demonstra visualmente como a inclusão de especificações claras e comandos de testes no prompt direciona a IA a entregar códigos validados de forma autônoma, reduzindo a necessidade de revisão manual por parte do desenvolvedor.

---

09 Resumo

Adotar boas práticas de uso do Claude Code gerencia o consumo da janela de contexto e garante o desenvolvimento de códigos seguros e alinhados às especificações do projeto.

Regras de ouro de usabilidade revisadas neste capítulo:

Diretriz Fundamental	Ação Prática no Console
Auto-Validação	Adicione scripts de testes unitários ou builds locais no final do prompt para que o Claude verifique sua própria entrega.
Ciclo de Projeto	Use o Modo Plan para ler arquivos e alinhar a arquitetura de projetos médios, liberando a codificação após aprovar o planejamento.
Especificidade	Escreva prompts detalhados indicando arquivos específicos, limites de escopo e utilize arquivos existentes como referências de estilo.
Documentação	Mantenha o CLAUDE.md focado exclusivamente em comandos de rotina locais e remova explicações de códigos redundantes.
Limpeza de Chat	Limpe o histórico do console com /clear se a correção de um mesmo problema falhar por três vezes, iniciando a tarefa em um chat limpo.

Seguir estas orientações de engenharia de software melhora a eficiência de interação com o Claude Code e otimiza a qualidade das entregas no seu repositório local.

---

O próximo capítulo, 50 "Antipadrões", detalhará os erros mais comuns cometidos por desenvolvedores e como corrigi-los. Analisaremos falhas como acúmulo excessivo de conversas, dependência de respostas e falta de auditorias de código. Nos vemos no próximo capítulo!

---

Leituras Recomendadas

• Gerando Arquivos CLAUDE.md com o /init
• Desenvolvendo com Agent Skills Customizadas
• Trabalhando com Equipes de Agentes Paralelas

---