Claude Code - Boas práticas com Agentes de IA

Neste artigo veremos como aplicar boas práticas para o desenvolvimento com IA Autônoma no Claude Code.

O Claude Code não é apenas mais um assistente de codificação com IA, é uma mudança completa de paradigma na forma como abordamos o desenvolvimento de software.

Diferente de ferramentas tradicionais de IA que exigem intervenção manual constante, o Claude Code vive no seu terminal, entende toda a sua base de código e pode executar ações reais: ler arquivos, rodar testes, fazer commits de mudanças e até criar pull requests. É codificação agentic em seu melhor nível.

O fluxo de trabalho dourado: Pesquisa -> Planejamento -> Implementação

O maior erro que desenvolvedores cometem com Claude Code é ir direto para a implementação. Embora o Claude possa escrever código sob demanda, pular a fase de pensamento reduz significativamente a qualidade para problemas complexos.

Existe um processo de 3 etapas para um fluxo de trabalho melhor.

Etapa 1 - Pesquisa

Peça ao Claude para explorar sua base de código e coletar contexto antes de tocar em qualquer código.

O Claude usará suas capacidades de busca de arquivos para entender sua arquitetura, identificar componentes-chave e trazer à tona possíveis casos extremos que você pode ter ignorado.

Etapa 2- Planejamento

Uma vez que o contexto foi obtido, peça ao Claude para criar um plano detalhado de implementação.

O Claude vai descrever:
• Arquivos que precisam ser modificados
• Novos arquivos a serem criados
• Dependências a serem instaladas
• Casos de teste a serem considerados
• Estratégias de migração

Etapa 3 - Implementação

Somente agora você deve pedir ao Claude para escrever código.

Exemplo em um cenário simulado:

Veja como esse fluxo de trabalho evitou um bug em produção para uma equipe:

Desenvolvimento Orientado a Testes (TDD)

O TDD se torna exponencialmente mais poderoso com codificação agentic. O ciclo de escrever teste → implementar → verificar pode rodar de forma autônoma enquanto você foca em decisões de design de nível mais alto.

O loop de TDD com Claude Code 

Com base neste prompt o Claude vai fazer o seguinte:
 - Criar casos de teste abrangentes
 - Executar os testes (eles irão falhar)
 - Implementar a funcionalidade
 - Executar os testes novamente
 - Iterar até que tudo passe
 - Fazer commit com uma mensagem descritiva

Padrão Avançado de TDD

Para funcionalidades complexas, use uma etapa secundária de verificação adicionando detalhes no arquivo CLAUDE.md:

# No seu arquivo CLAUDE.md Ao implementar funcionalidades: 1.Escreva os testes primeiro 2.Implemente a solução 3.Execute a suíte de testes completa 4.Se os testes passarem, verifique casos de borda (edge cases): -Inputs nulos -Condições de contorno -Acesso concorrente 5.Adicione testes de integração 6.Verifique vulnerabilidades de segurança

Personalize a Configuração da Sua Aplicação

Um dos passos fundamentais para uma codificação agentic eficaz com Claude Code é configurar seu ambiente para que a ferramenta “conheça seu mundo” antecipadamente.

Você pode definir diretrizes do projeto dentro da pasta .claude no diretório raiz com arquivos CLAUDE.md ou CLAUDE.local.md.

O que vai no CLAUDE.md ?

Pense no CLAUDE.md como o documento constitucional do seu projeto para interações com IA. Claude lê automaticamente esse arquivo e segue suas diretrizes durante toda a sessão.

Você pode definir essas diretrizes para si mesmo ou compartilhá-las com toda a equipe enviando ao repositório.

Exemplo:

#Contexto do Projeto

Esta é uma API ASP.NET Core utilizando C# e Entity Framework Core (EF Core).

## Estilo de Código

-Siga as C# Coding Conventions (Microsoft)
-Prefira async/await para todas as operações de I/O
-Comprimento máximo da linha: 100 caracteres
-Use nomes de variáveis descritivos (sem letras únicas,
 exceto em contadores de loop como i, j)
-Utilize Dependency Injection (DI) nativa para gerenciamento de serviços

## Requisitos de Teste

-Cada nova funcionalidade precisa de testes unitários
-Testes de integração para os endpoints da API (usando WebApplicationFactory)
-Use xUnit ou NUnit para os testes e FluentAssertions para validações
-Meta de cobertura superior a 80% (>80%)

## Comandos de Build

-dotnet watch run: Inicia o servidor de desenvolvimento com hot reload
-dotnet publish -c Release: Build de produção
-dotnet test: Executa a suíte de testes
-dotnet format: Verifica e corrige o estilo do código (linting)

## Erros Comuns (Pitfalls)

-Sempre valide os inputs do usuário (use FluentValidation ou Data Annotations)
-Use LINQ e EF Core corretamente para evitar queries parametrizadas manuais
 (evite FromSqlRaw com strings concatenadas)
-Verifique a autenticação e autorização via Policies ou Attributes antes do
 acesso aos dados
-Registre erros via ILogger, mas nunca exponha detalhes da exceção ou stack 
traces no ambiente de produção

## Convenções de Banco de Dados

-Use PascalCase para nomes de tabelas e colunas (padrão .NET) ou configure 
para snake_case via Fluent API
-Nomes de tabelas são no plural
-Sempre inclua propriedades de auditoria: CreatedAt e UpdatedAt
-Implemente Soft Delete utilizando filtros globais de consulta (HasQueryFilter) 
com a coluna DeletedAt

Dicas para CLAUDE.md

Atualização dinâmica:
Durante uma sessão, você pode atualizar o arquivo:

Ajuste contínuo:
Como esse arquivo faz parte do contexto do prompt do agente, trate-o como qualquer prompt: refine, melhore e ajuste continuamente.

Exemplo:

Use comandos slash personalizados
Você pode criar templates de prompt em .claude/commands que ficam disponíveis via menu / no Claude Code.

Exemplo:  Arquivo .claude/commands/fix-github-issue.md:

Uso :  claude /fix-github-issue 1234

Use ferramentas bash

Como o Claude herda seu ambiente shell, ele pode executar comandos como ls, grep, npm run build.

Exemplo:  "Rode o comando npm run lint:ci seguido de npm test:unit. Caso ocorra alguma falha, interrompa o processo e exiba o log de erros."

Pensamento Estendido: Quando os Problemas Ficam Difíceis

Às vezes Claude precisa de mais tempo para pensar em problemas complexos.

Modos de pensamento:

Quando usar

Use pensamento estendido para:
• Decisões arquiteturais complexas
• Debugging difícil
• Refatoração de código legado
• Problemas de performance

Use modo padrão para:
• Correções simples
• Funcionalidades básicas
• Testes
• Documentação

Exemplo real:

Claude identificou:
- Falta de isolamento de transações no banco
- Handlers duplicados
- Colisão de chaves Redis
- Solução completa para os três

Segurança em Primeiro Lugar: Gerenciamento de Permissões

Claude Code pode executar comandos poderosos, o que significa que também pode causar danos.

Sistema de Permissões:

Opções:

y → uma vez
always → sempre permitir
n → negar

Configurando permissões

Evite usar:  --dangerously-skip-permissions

No seu ambiente principal, e se for necessário :

• Use Docker
• Use VM descartável
• Desative a rede
• Use mounts somente leitura

Ao longo deste artigo, vimos que obter bons resultados com essa abordagem não depende apenas da ferramenta, mas principalmente de como estruturamos nosso fluxo de trabalho. O uso do ciclo Pesquisa → Planejamento → Implementação, aliado a práticas como TDD, definição de contexto com CLAUDE.md e uso consciente de permissões, permite extrair muito mais valor da ferramenta.

Além disso, técnicas como pensamento estendido e automação com comandos personalizados mostram que o Claude Code não é apenas um gerador de código, mas um verdadeiro parceiro no processo de desenvolvimento.

No entanto, com esse poder vem a responsabilidade. O uso seguro da ferramenta, especialmente no gerenciamento de permissões e execução de comandos, é essencial para evitar problemas no ambiente de desenvolvimento.

Ao aplicar essas boas práticas, desenvolvedores conseguem não apenas aumentar produtividade, mas também melhorar a qualidade e consistência das soluções entregues.

E estamos conversados...  

"Àquele que não conheceu pecado (Jesus), o fez pecado por nós; para que nele fôssemos feitos justiça de Deus. 2 Coríntios 5:21

Curso Spec-Driven Development com OpenSpec e Claude Code