Como obter bons resultados com o Claude Code

 (dzombak.com)
45 pontos por GN⁺ 2025-08-09 | 5 comentários | Compartilhar no WhatsApp
  • 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

Leituras relacionadas

5 comentários

 
wedding 2025-08-11

O fato de ter saído um bom resultado significa que ele consultou bem um código que alguém já tinha feito.
 
aeolian21 2025-08-11

Todo mundo já faz isso que o autor fez há muito tempo, então em vez de se gabar de coisas inúteis,
seria muito mais útil escrever quais foram os motivos para você achar que o Claude foi o melhor ao comparar entre os LLMs.
Comparações do código realmente gerado, frequência de erros de compilação, estabilidade na compreensão de contexto etc.
Na prática, quem tem a melhor capacidade de compreensão de contexto é o Gemini (1 milhão de tokens).
 
zxcv123 2025-08-10

Só fez coisas sem utilidade e ainda enrolou com um texto longo demais.
 
knunu 2025-08-11

Pode ser útil pra alguém, haha
 
GN⁺ 2025-08-09
Comentários do Hacker News

  • Hoje tive pela primeira vez uma experiência realmente bem-sucedida usando o Claude como agente de programação. Antes eu já tinha usado o Cursor, mas agora também estou experimentando o Claude e outras opções. Como mencionado no artigo, o ponto-chave é escrever uma especificação clara. Passei 2 horas escrevendo à mão um documento de 12 etapas, organizando a forma de implementação e incluindo informações de contexto. O Claude seguiu esse procedimento e gerou o código passo a passo. Na minha estimativa, isso provavelmente me poupou umas 6 a 10 horas. Agora pretendo revisar, testar, ajustar gradualmente e adicionar funcionalidades. A base desse sucesso foi que eu mesmo escrevi com clareza todas as etapas que o Claude precisava executar; ou seja, eu desenhei todo o fluxo e o Claude apenas seguiu as instruções. Esse processo me deu a convicção de que desenvolvedores de nível intermediário ou acima não serão substituídos por IA tão cedo. Ainda assim, ver o Claude ler a especificação inteira e produzir código organizado e bem documentado é uma experiência realmente impressionante. É incrível não precisar programar tudo manualmente.

    • Eu consigo bons resultados com o Claude sem me preparar tanto assim. Quase como se eu estivesse escrevendo o código por conta própria, vou pedindo ao Claude uma etapa de cada vez. A cada mudança, já aplico e faço commit, depois reviso o diff. Se o Claude gera algo estranho, peço correção imediatamente. E também indico diretamente código existente ou referências de funções que quero que ele use. Desse jeito, dá para obter ótimos resultados com muito menos digitação e em menos tempo.

    • Recomendo ler “Programming as Theory Building”, do Naur. Foi uma experiência importante para aprender como entender o problema de forma teórica e modelá-lo por conta própria. Caso contrário, o LLM pode acabar criando uma teoria própria (e errada).
      Ler “Programming as Theory Building” - Naur

    • Como no artigo, especificações claras são realmente importantes. Estou criando uma linguagem de programação com o Claude, e senti isso na prática. Programar envolve uma sequência enorme de pequenas decisões. Se você não orientar com clareza, o LLM lida com a maioria delas na base do chute, e muitas vezes escolhe errado. Esses pequenos erros podem se acumular e levar a um resultado incorreto.

    • Seria ótimo se você pudesse compartilhar um exemplo desses documentos de especificação. Como alguém que está aprendendo desenvolvimento de forma autodidata e experimentando o Claude Code, isso ajudaria muito a entender que tipo de informação e nível de profundidade realmente são úteis.

    • Na verdade, bastante gente de nível intermediário e sênior também não sabe escrever uma especificação decente. Mas entendo a intenção do comentário.

  • Criar um ~/.claude/CLAUDE.md e colocar regras ali provavelmente não tem tanto efeito na prática. O Claude não é uma pessoa e não raciocina cuidadosamente linha por linha do código. Instruções subjetivas e ambíguas não fazem o código mudar de verdade. E ainda existe o problema do "context rot".
    (explicação sobre context rot: é quando o LLM perde ou distorce o contexto durante uma conversa ou tarefa longa; link de referência: https://news.ycombinator.com/item?id=44564248)
    Na prática, é impossível enfiar todo tipo de regra em um único arquivo e esperar que a IA siga tudo sozinha. Para isso funcionar, seria preciso criar um sub-agent para cada regra e separar isso em um pipeline convencional, não em algo dependente da IA. Mas aí o custo sobe exponencialmente.

    • Quanto ao custo, depois que o workflow estiver estabilizado, dá para usar LLMs mais baratos (embora o custo operacional ainda seja alto). É possível reduzir gastos com fine-tuning, otimização de prompts, técnicas especializadas de distillation etc. Já existe bastante pesquisa nessa área.

    • Fico curioso sobre o que seria bom incluir no CLAUDE.md.

  • Olhando os projetos de exemplo no fim da página, a maioria parece ser software otimizado para um objetivo bem específico. Acho que, no futuro, projetos open source também vão evoluir nesse formato, bem especializados para atender à necessidade de uma única pessoa. Tenho a impressão de que esse tipo de software (utilitário) vai virar código descartável gerado de uma vez só por LLM.

  • Minha abordagem com o Claude Code continua mudando. Ainda não consegui fazer o Claude Code contribuir diretamente com funcionalidades realmente relevantes em um grande app web da empresa. As especificações até ajudam um pouco, mas no fim o fluxo desanda para direções estranhas e entra em um loop de escolhas erradas. Isso pode ser um limite do Claude, ou pode ser que minhas especificações ainda não estejam precisas o suficiente. Fiz muitos experimentos, mas em coisas "desafiadoras ou que exigem muito conhecimento de domínio" tive tantas falhas que parei de insistir. Em vez disso, por recomendação de um amigo, comecei a usar o Claude em tarefas de backlog com carga mental quase zero. Por exemplo, pedi que ele criasse testes em Playwright em um novo workspace para algo pelo qual eu não tinha muito apego. Foi um grande sucesso. Expliquei a experiência do usuário ao Claude como explicaria a uma pessoa e informei o caminho do servidor dev. Usei o Playwright MCP para fazê-lo descobrir como cada feature deveria funcionar, documentar o processo de execução, escrever os testes e depurar os erros. Também incluí a tarefa de vasculhar o código de UI do projeto para adicionar seletores data-testid. Organizei o processo inteiro em um master task.md e pedi que ele também criasse markdowns de tarefa individuais para cada feature. Esse método funcionou muito bem. Usei inclusive em uma feature complexa em que 2 usuários no navegador interagem de forma pouco intuitiva; mesmo sem ficar 100% correto, quanto mais complexo era o caso, mais contexto adicional e correções de código eram necessários, mas no geral resolveu de uma vez tarefas chatas que levariam dias.

  • O melhor resultado para mim foi manter o CLAUDE.md o mais minimalista possível, com menos de 100 linhas.

    • resumo do contexto essencial e do objetivo do projeto
    • explicação mínima da estrutura do projeto para entender tipos, interfaces e helpers
    • apenas os comandos principais, para não ficar reprocessando o package.json toda hora Durante o fluxo de implementação/testes, percebi que o Claude às vezes tentava escrever todos os testes de uma vez antecipadamente ou só implementava tudo quando encontrava falha de import (o que não é TDD de verdade). Então criei um hook chamado TDD-Guard para forçar a passar apenas um teste por vez, garantir que o teste falhe pelo motivo certo e implementar o mínimo de código necessário para fazê-lo passar. Automatizei qualidade de código com husky, lint-staged, commitlint etc. e obtive resultados muito bons. Isso ajuda a preservar contexto para informações mais importantes. Concordo que, quando o Claude Code emperra, o melhor caminho no fim é o desenvolvedor intervir diretamente. Só acho uma pena quando a discussão fica em orientações genéricas demais.
    • Se tiver interesse em abordagens de automação:

  • Estou trabalhando diariamente com o Claude Code há mais de um mês. Já usei Cursor, Q e outros, mas o Claude Code é muito superior. As dicas mencionadas no artigo batem bastante com o que eu mesmo aprendi.
    Para compartilhar algumas reflexões adicionais:

    • começo com uma sessão de ideias com o Claude no console web, explicando o objetivo do projeto e esboçando em alto nível a modelagem de domínio e os marcos; em projetos pequenos, isso se organiza em poucas horas de conversa de ida e volta; é daí que sai a primeira versão do CLAUDE.md

    • quando o projeto de fato começa, o Claude lê tanto meu CLAUDE.md global quanto o CLAUDE.md do projeto; isso acontece em toda sessão

    • durante o andamento, também peço que o Claude Code continue atualizando o CLAUDE.md do projeto, marcando progresso conforme segue o plano e, ao fim da sessão, escrevendo um resumo do projeto, como ele funciona, como navegar pelo código etc.; isso serve como uma espécie de memória de longo prazo e funcionou bem

    • por melhores que sejam as diretrizes, o Claude tem tendência a sair na frente; por isso, quando estou participando ativamente, faço questão de manter tudo em pequenos incrementos e com foco etapa por etapa; quando é algo pontual ou um protótipo, deixo ele implementar mais livremente

      • Queria saber se o plano de assinatura de $20 vale mais a pena que o Cursor em termos de custo-benefício. Gostaria de entender se só compensa para quem usa todos os dias.

  • É melhor manter o CLAUDE.md no nível do projeto curto e conciso, e mover detalhes mais específicos para subpastas. O topo funciona como uma espécie de mapa. Sempre que planejo uma feature, faço o Claude olhar as pastas adequadas, consultar o contexto necessário e montar um plano de implementação por etapas. Ao fim de cada etapa, peço que o Claude atualize o plano de implementação com base no novo contexto. Assim, o contexto passa naturalmente para a próxima etapa e também dá para resetar a janela e entrar na fase seguinte com a cabeça limpa.

  • Estou fazendo um jogo ASCII estilo Factorio com o Claude Code. No começo deixei ele escrever código quase sem supervisão, e ele implementou de uma vez a maior parte das funcionalidades principais (save/load, opções, debug, geração de mapa, construção, esteiras, crafting, QoL etc.). Mas, ao tentar corrigir detalhes, acontecia de mudar o movimento e quebrar as esteiras, por exemplo, e outras partes continuavam se deteriorando. Então pedi que ele adicionasse automação com Playwright, mas os testes eram fracos e cheios de chamadas a sleep. Ao olhar o código com atenção, vi que a estrutura era baseada em frontend React com useEffect, e não em uma arquitetura de engine de jogo de verdade. Ele também não seguia bem as regras de hooks e tinha uma compreensão fraca de timing. Por isso, desta vez comecei tudo de novo com uma engine de jogo baseada em ticks e também adicionei code review. O progresso ficou mais lento, mas o desenvolvimento está muito mais sólido. Se eu conseguir terminar uma boa demo, pretendo publicar no Show HN.

    • Até a estrutura básica inicial ficar pronta, a contribuição direta de uma pessoa faz muita diferença. Depois que uma grande rodada de refatoração passa, dá para relaxar um pouco mais.

  • Se houver mais gente como eu que usa tanto a assinatura de trabalho quanto a pessoal do Claude, dá para trocar de conta de forma simples com algo como alias claude-personal="CLAUDE_CONFIG_DIR=~/.claude-personal claude".
    Blog sobre como usar várias contas do Claude com eficiência

  • Todo mundo diz que "o segredo é escrever uma especificação clara com antecedência e dar contexto", mas pela minha experiência isso nem sempre funciona. Já fiz uma sessão de CC com um especialista de verdade usando Opus 4 & Sonnet 4, e a pessoa tinha preparado uma spec realmente clara, mas o resultado não foi melhor que o meu jeito de trabalhar (pedir as coisas na hora, conforme as features vão surgindo, sem CLAUDE.md, cada pedido com seu próprio contexto). No workflow baseado em especificação, ele esquecia coisas importantes o tempo todo ou inventava coisas que não estavam no documento de contexto (inclusive coisas explicitamente proibidas). Já para mim, funcionava melhor dar instruções imediatas como, por exemplo, “adicione uma página de CRUD para invoices, mas antes analise o codebase”. Isso é só um relato empírico meu, mas depois de tocar mais de 100 projetos com o Claude, não consigo afirmar com confiança que existe uma abordagem superior além de ter hooks separados para impedir que ele ultrapasse os limites. Muita gente diz que o método baseado em spec é melhor, mas quando você pede para mostrarem na prática, muitas vezes acabam gastando tempo demais corrigindo repetidamente partes claramente erradas. E mesmo quando se escreve no CLAUDE.md algo como “nunca faça isso”, ele continua tendo tendência a fazer exatamente aquilo.