Como obter bons resultados com o Claude Code

• Nos últimos meses, ao experimentar vários agentes de programação com LLM, Claude Code foi a ferramenta que trouxe os resultados mais satisfatórios
• Graças ao Claude Code, foi possível criar cerca de 12 programas e projetos em pouco tempo, incluindo trabalhos que normalmente nem seriam iniciados por falta de tempo
• Para ter sucesso no uso, o essencial é ter uma especificação clara, fornecer documentação com a estrutura do projeto e como executar build e lint, pedir que a IA faça revisão do próprio código e manter um guia global de agente personalizado
• Como o código escrito pela IA muitas vezes pode ser impreciso ou ineficiente, é indispensável revisar pessoalmente todo o código e todos os casos de teste, além de adicionar testes faltantes ou pedir que a IA os escreva e depois revisá-los novamente
• O guia global de agente divulgado no apêndice inclui diretrizes detalhadas de desenvolvimento, como plano de implementação em etapas, desenvolvimento orientado a testes, filosofia centrada em simplicidade, clareza e pragmatismo, critérios de qualidade e processo de resolução de problemas

---

Experiência com o Claude Code e seus efeitos

• Nos últimos meses, foram testados vários agentes de programação com LLM, e a experiência com Claude Code foi especialmente a melhor
• Não é uma ferramenta sem problemas, mas permitiu concluir mais de 12 programas e projetos em pouco tempo
• Sem Claude Code, teria sido quase impossível realizar tudo isso no mesmo período
• Muitos desses trabalhos provavelmente nem teriam sido tentados por causa do tempo necessário

Estratégias para usar o Claude Code

• Escrever uma especificação clara
  • Antes de iniciar o projeto, documentar claramente os requisitos e o contexto para fornecer ao agente
  • Isso deixa mais nítidos o direcionamento e o escopo da implementação
• Documentar a estrutura do projeto
  • Preparar documentação incluindo como executar build, lint e testes
  • Assim, o agente consegue navegar pela base de código e trabalhar com mais eficácia
• Solicitar revisão de código ao agente
  • Pedir ao Claude Code que revise o código que ele mesmo gerou ajuda a encontrar melhorias inesperadas ou bugs
• Usar um guia global pessoal
  • Manter um processo de desenvolvimento consistente por meio do ~/.claude/CLAUDE.md, com regras pessoais sobre abordagem de resolução de problemas, aplicação de TDD, manutenção de simplicidade e clareza, e limite de tentativas (3 vezes)

Validação de código escrito por LLM

• O código gerado por IA frequentemente apresenta problemas como erros lógicos, queda de desempenho e testes incompletos
• O autor revisa manualmente todo o código e verifica seu funcionamento
  • Adiciona diretamente os casos de teste ausentes
  • Ou pede à IA que os escreva e depois revisa novamente código e testes
• No ambiente profissional, enfatiza-se que, se o PR leva o seu nome, a responsabilidade final pela qualidade é sua

Principais pontos do guia “global” pessoal de agente

Esse guia é mantido no arquivo ~/.claude/CLAUDE.md

• Filosofia e princípios centrais

  • Progresso incremental: fazer mudanças pequenas, sempre compilando e passando nos testes
  • Aprender com o código existente: analisar padrões do código e elaborar um plano antes de implementar
  • Pragmatismo em primeiro lugar: abordagem flexível de acordo com a situação do projeto
  • Clareza em primeiro lugar: código fácil de ler e com intenção clara, evitando truques desnecessários

• Definição de simplicidade

  • Funções e classes com responsabilidade única
  • Evitar abstração prematura
  • Reduzir complexidade e buscar código que não precise de explicação

• Processo de trabalho

  • 1. Planejamento e definição de etapas:
    • Dividir tarefas complexas em 3 a 5 etapas e registrá-las em IMPLEMENTATION_PLAN.md
    • Especificar objetivo, critérios de sucesso, casos de teste e status de progresso de cada etapa
  • 2. Fluxo de implementação:
    • entender → escrever testes (vermelho) → implementação mínima (verde) → refatoração → commit
  • 3. Reavaliar após limite de 3 tentativas:
    • Em caso de falha, registrar tentativas, erros e causas
    • Explorar alternativas (2 ou 3 abordagens)
    • Revisar novamente o design fundamental e a decomposição do problema
    • Tentar outros padrões ou funcionalidades

• Padrões técnicos

  • Priorizar composition e usar injeção de dependência
  • Usar interfaces para facilitar os testes
  • Fluxo de dados explícito
  • Recomendar TDD e proibir desativar testes

• Regras de qualidade de código

  • Todo commit deve compilar com sucesso, passar nos testes, incluir testes para novas funcionalidades e seguir o estilo de código
  • Antes do commit, executar formatter e linter, revisar as mudanças por conta própria e escrever mensagens de commit explicando o “porquê”

• Tratamento de erros

  • Falhar rápido e com mensagens específicas
  • Fornecer o contexto necessário para debugging
  • Tratar exceções no nível apropriado e não ocultá-las

• Critérios de decisão

  • 1. Facilidade de teste
  • 2. Legibilidade que ainda faça sentido daqui a 6 meses
  • 3. Consistência com os padrões do projeto
  • 4. Simplicidade
  • 5. Facilidade de mudança

• Integração com o projeto

  • Analisar pelo menos 3 funcionalidades semelhantes
  • Reutilizar padrões e bibliotecas já existentes
  • Usar os mesmos utilitários de teste
  • A introdução de novas ferramentas exige uma justificativa forte

• Quality gate

  • Todos os testes passam
  • Regras do projeto são seguidas
  • Nenhum aviso do linter
  • Mensagem de commit clara
  • A implementação corresponde ao plano
  • TODOs incluem número da issue

• Diretrizes de teste

  • Testes focados em comportamento, não em implementação
  • Se possível, uma asserção por teste
  • Nomes claros que descrevam o cenário
  • Reutilizar utilitários de teste existentes
  • Os testes devem ser determinísticos

• Absolutamente proibido

  • Burlar hooks com --no-verify
  • Desativar testes
  • Fazer commit de código que não compila
  • Suposições sem verificação

• Deve ser feito obrigatoriamente

  • Commits incrementais
  • Atualização contínua da documentação
  • Aprender com implementações existentes
  • Reavaliar a abordagem após 3 falhas

Projetos open source criados com Claude Code

• Proxy reverso com reconhecimento de HTML/XML (cdzombak/xrp)
• Tema Solarized para VS Code (claro/escuro) (cdzombak/dzsolarized-vscode)
• Gerador de RSS para photostream do Flickr (cdzombak/flickr-rss)
• Ferramenta de metadados para biblioteca de fotos do Lychee (cdzombak/lychee-meta-tool)
• Relato do estado de bloqueio de tela do macOS via MQTT (cdzombak/macos-screenlock-mqtt)
• Configuração automática de títulos de fotos do Bird Buddy no Lychee (cdzombak/lychee-birb-title)
• Organização automática de fotos com base em LLM local (cdzombak/lychee-ai-organizer)
• Automação de instalação em lote de software para macOS (cdzombak/mac-install)
• Projeto de serviço RSS (cdzombak/rss.church)
• Exportação total/seletiva de fotos do Flickr com preservação de metadados (cdzombak/flickr-exporter)
• Gerador de galeria HTML estática (cdzombak/gallerygen)