Por que o Claude Code é tão bom

 (minusx.ai)
8 pontos por GN⁺ 2025-08-24 | 2 comentários | Compartilhar no WhatsApp
  • Claude Code é um agente/fluxo de trabalho de IA excelente em termos de usabilidade
  • Graças à simplicidade arquitetural e a um loop de controle claro, ele oferece uma experiência em que depuração e manutenção são fáceis
  • Ao minimizar a adoção de RAG e usar ativamente prompts sofisticados e arquivos de contexto, ele maximiza os pontos fortes dos LLMs
  • Com várias ferramentas (tools) e diretrizes claras, mantém clareza e consistência no trabalho
  • Em vez de complexidade, aposta em uma estrutura fácil de entender e no design de prompts, com a vantagem de permitir implementar um agente LLM próprio de forma semelhante

Visão geral

  • Claude Code (doravante CC) oferece atualmente uma das experiências mais satisfatórias entre os agentes de IA/fluxos de trabalho de programação disponíveis
  • Os pontos fortes do CC estão na edição de código voltada ao alvo, na redução de interrupções desnecessárias e em uma UX agradável que preserva o controle do usuário
  • O modelo Claude 4 e seu característico Interleaved Thinking têm papel central, mas ele ainda oferece menos atrito do que outras ferramentas baseadas no mesmo modelo, como Cursor ou Github Copilot
  • Este texto disseca os princípios de implementação do CC e oferece um guia prático para implementar um agente LLM próprio que proporcione uma experiência semelhante

A virtude central do Claude Code: simplicidade

  • A maior lição é: "mantenha tudo simples (Keep Things Simple, Dummy)"
  • Quando agentes LLM adotam estruturas complexas (multiagente, RAG complexo, sistemas de verificação etc.), fica extremamente difícil depurar e melhorar
  • O CC adota um único loop principal, um conjunto de ferramentas simples e uma estrutura compreensível de relance, reunindo toda a lógica essencial em um único arquivo e eliminando boilerplate e complexidade desnecessários

Por que a simplicidade importa

  • Em vez de uma estrutura multiagente, ele processa a maior parte do trabalho em uma única thread principal
    • Resumo de histórico e consolidação de mensagens para UX são aplicados de forma auxiliar
    • Quando é necessário lidar com uma tarefa complexa, ele se replica para ramificar em um subagente (sem ramificação recursiva, permitida apenas em um nível)
  • Faz uso ativo de uma lista de tarefas (todo list)
    • Problemas complexos podem ser divididos e tratados pelo subagente, com os resultados sendo mesclados ao histórico principal de mensagens
    • Estruturas excessivamente abstratas e multicamadas (múltiplos agentes, navegação em grafos) podem, ao contrário, prejudicar a estabilidade e a escalabilidade do sistema

Uso ativo de modelos leves

  • Usa modelos LLM leves, como claude-3-5-haiku, na maioria das requisições
    • Processa com eficiência muitas tarefas, como leitura de arquivos grandes, parsing de páginas web e resumo de histórico do git
    • O uso de modelos leves pode reduzir os custos em até 70–80%
  • Recomenda-se usar combinações de modelos otimizadas para cada chamada de função principal

Design sofisticado de prompts

  • O prompt de sistema do CC é composto por grande volume (cerca de 2800 tokens) e várias seções (tom & estilo, gerenciamento de tarefas, política de uso de ferramentas, informações de SO/diretório etc.)
    • Ele sempre inclui arquivos de contexto inteiros, como claude.md, para maximizar a riqueza do contexto
    • O prompt de sistema orienta com muito detalhe sobre regras de política, exemplos, cuidados e o momento adequado de usar ferramentas

Uso simultâneo de XML e Markdown

  • O prompt usa ao mesmo tempo tags XML e estrutura Markdown
    • Com elementos como <system-reminder>, <good-example>, <bad-example>, transmite informações detalhadas e com bifurcações condicionais
    • Os headings em markdown separam as seções com clareza

A importância dos arquivos de contexto

  • A presença ou ausência de claude.md faz uma diferença enorme no desempenho do CC
    • É essencial para transmitir regras adicionais difíceis de inferir a partir do codebase (exclusão de pastas/bibliotecas, políticas preferidas etc.)
    • A MinusX também sistematiza preferências de equipe/usuário com minusx.md

Minimizar RAG, usar busca do LLM

  • Em vez de RAG (Retrieval Augmented Generation), o CC prefere uma estrutura baseada em busca direta de código, usando comandos como ripgrep, jq e find, como um desenvolvedor real
    • Isso oferece uma alternativa às possibilidades ocultas de falha trazidas por configurações complexas de RAG (por exemplo: função de similaridade, reranker, chunking)
    • Como o LLM explora e entende diretamente o contexto real do código, há menos peças móveis e até potencial de maior eficiência no treinamento por RL

Design de ferramentas (tool) e hierarquia

  • O CC oferece ferramentas de baixo nível (Bash, Read, Write), nível intermediário (Edit, Grep, Glob) e alto nível (Task, WebFetch etc.)
    • As ferramentas necessárias são separadas individualmente levando em conta frequência de uso e precisão
    • A descrição, os exemplos e o momento de uso de cada ferramenta são informados claramente no prompt de sistema
  • Tarefas complexas são gerenciadas de forma consistente por meio de Task ou ferramentas de alto nível

Gerenciamento explícito de Todo para evitar perda de contexto

  • Para resolver problemas típicos de agentes LLM de longa execução (perda de contexto, perda de direção), o CC gerencia estado com uma lista de Todo mantida diretamente
    • Em vez de um sistema multiagente, o modelo atualiza a lista de tarefas de forma autônoma e garante ao mesmo tempo direção de trabalho e flexibilidade

Controle do tom, estilo e nível de proximidade do agente

  • Tom, estilo e proatividade são gerenciados em seções separadas
    • Foi desenhada uma experiência de usuário consistente, como evitar explicações desnecessárias e permitir emojis apenas quando explicitamente solicitados
  • Usa modificadores fortes como "muito importante (IMPORTANT)", "nunca (NEVER)" e "sempre (ALWAYS)" para transmitir alertas

Design do algoritmo de decisão e do fluxo

  • Os principais algoritmos que o LLM deve seguir são descritos com clareza e exemplificados
    • Mais do que listar Do/Don't, fluxogramas e checklists por etapas são mais eficazes para manter a estabilidade do algoritmo
    • Considerando a possibilidade de conflito entre várias diretrizes e exemplos, o escopo do papel e as políticas são definidos de forma estrutural

Padrões de design e dicas práticas de aplicação

  • Sua estrutura forte e opinativa vale como benchmark imediato para projetar um agente próprio
    • Em vez de abusar de frameworks que só aumentam a complexidade mental, o importante é projetar uma estrutura simples e eficaz
  • Na prática, a MinusX já aplica vários desses princípios e planeja expandi-los gradualmente

Conclusão

  • A maior lição do Claude Code: “a simplicidade é a maior força”
  • Clareza estrutural, design de prompts com propósito e combinação de ferramentas leves tornam possível um agente LLM poderoso
  • Ao desenvolver seu próprio agente LLM, vale muito a pena tomar a filosofia de design e os guias do CC como referência ativa

Leituras relacionadas

2 comentários

 
kaydash 2025-08-25

Bom demais, feliz demais, é o melhor, é uma doçura, quero continuar pra sempre
 
GN⁺ 2025-08-24
Comentários do Hacker News

  • A opinião é que a simplicidade no estilo KISS sempre vence, e que o texto foi útil por organizar bem essas ideias

  • É uma pena que o Claude Code não seja open source, mas foi compartilhado que existem ferramentas para entender melhor o funcionamento interno; se você realmente quer ver como ele funciona, a recomendação é o Claude Trace
    https://github.com/badlogic/lemmy/tree/main/apps/claude-trace
    Essa ferramenta gera um arquivo JSON mostrando todas as ferramentas e prompts usados na sessão, além de um arquivo HTML formatado para facilitar a visualização

  • Houve quem achasse útil entender como uma organização centrada em LLM aborda isso em uma época em que sistemas multiagentes estão em alta, e disse se identificar por também experimentar vários pontos de vista de design no dia a dia
    Os principais insights seriam:
    (1) prompts longos podem ser bons, e é importante incluir explicações básicas como o propósito da ferramenta e como ela ajuda
    (2) chamada de ferramenta é algo muito básico, então o sistema precisa refletir mais contexto, como quando usar e quando não usar
    (3) gerenciar o estado do sistema como mensagens funciona bem; métodos mais sofisticados, como salvar dataframes ou fazer parsing de variáveis, também foram considerados, mas com uma janela de contexto maior, só mensagens já seriam suficientes

    • Prompts longos são bons, mas só quando o modelo foi otimizado para lidar bem com isso; alguém relatou ter trocado o modelo do Claude Code por outros e descoberto que quase nenhum modelo local entregava tão bem quanto a propaganda em prompts longos e uso de ferramentas
      Também tentou modelos da OpenAI e do Google Gemini, mas achou que nenhum funcionava tão bem quanto os da Anthropic, além de serem mais lentos; quanto maior o prompt, mais apareciam problemas como esquecer ferramentas ou devolver resultados em formato incorreto
    • (Autor do post) A opinião é que só com os recursos básicos já dá para tirar ótimo desempenho em quase 99% dos casos; o importante é manter o loop simples e oferecer ferramentas claras, mesmo que haja sobreposição de funções
      Clareza e simplicidade vêm em primeiro lugar

  • Houve uma pergunta sobre como o Google Gemini, especialmente a versão Pro, se compara ao Claude; a pessoa gosta de muitos produtos do Google, mas se preocupa com o hábito da empresa de descontinuar produtos com frequência, além de questões de controle corporativo, como no Chrome, e censura

    • O Gemini se destaca especialmente quando é possível jogar os arquivos de merge do repositório inteiro e conversar com isso; o nível de compreensão do codebase completo seria impressionante, e isso ajuda muito em arquitetura também, área em que o Claude ficaria bem atrás
      A estratégia pessoal dessa pessoa é usar o Gemini para gerar um resumo do projeto e um plano de design de alto nível, depois usar o gpt5 para refinamento e desenho do workflow detalhado, como documentos XML, e por fim passar isso para o Claude; só isso já quase elimina a tendência do Claude de ficar se perdendo
    • O Gemini Pro não seria ruim para programação, mas, pela experiência relatada, o Claude é muito melhor em tarefas ligadas a terminal, como CLI; a maioria dos CLIs também usa bastante Claude
      https://www.tbench.ai/leaderboard
    • Na UI web (chat), a pessoa gosta bastante do Gemini 2.5 Pro; em ferramentas de linha de comando, o Gemini code seria inútil e o Claude code seria lento na maior parte do tempo
    • O Gemini seria melhor para depurar problemas difíceis que exigem seguir várias chamadas de função; já o Claude seria sempre previsível e obedeceria bem às instruções, sendo especialmente bom em gerenciar listas de tarefas
    • Antes a pessoa gostava bastante, mas recentemente sente que ele ficou mais burro, e perguntou se mais alguém percebe isso

  • A opinião de uma pessoa é que o próprio modelo base é muito forte para trabalho real de programação, o que explica a avaliação positiva dos usuários, diferente de problemas de benchmark genéricos; segundo ela, ao usar GitHub Copilot, o Claude é muito superior aos modelos da OpenAI e do Google, com uma diferença tão grande que os outros chegam a parecer praticamente inúteis na prática

    • A Anthropic consegue otimizar internamente modelo e prompt durante o reinforcement learning, então o conselho do texto de “usar o jeito tradicional como está” pareceria mais adequado para os modelos da Anthropic; o modelo de assinatura também cria um forte incentivo para otimizar a eficiência do loop
    • Isso não pode ser explicado só pela diferença do modelo base; ao comparar usar opus e cline no VS Code com usar Claude code, a pessoa diz que é difícil quantificar a diferença de produtividade, mas consegue fazer mais coisas com CC
    • Outra pessoa disse que, depois de ver tantos elogios, usou o Claude Code por um mês cheio de expectativa e acabou só mais decepcionada; a experiência foi pior que a da sidebar do Cursor, e ficou se perguntando se estava usando errado, já que em dois codebases diferentes o sistema cometia erros de código absurdos com frequência

  • Alguém está tentando depurar problemas relacionados ao Elastic no Security Onion com Claude Code, mas depois de alguns minutos começa a sair um monte de código JS confuso e aparece o erro Error: kill EPERM
    Pelos logs, parece que o processo Node.js é encerrado e isso talvez mate o próprio Claude, ou então dá a impressão de que o Claude desiste sozinho por não conseguir resolver o problema
    De qualquer forma, a pessoa gostaria que ele ajudasse por mais tempo se o processo continuasse vivo

    • Claude e localstack às vezes não se dão bem, embora em Rust ele surpreendentemente funcione bem
      A opinião é que, no futuro, as linguagens, plataformas e arquiteturas que os LLMs conhecem melhor vão dominar cada vez mais; por exemplo, se o LLM for 10 vezes melhor com nodejs, então pode fazer sentido escolher nodejs desde o início em vez de Elixir ou Go, e até desenvolvedores júnior poderiam atuar em nível pleno ou sênior com ajuda de LLM
    • Esse erro pode acontecer quando se usa sudo para tentar executar processos com privilégios de superusuário e ocorre timeout
    • Em alguns casos, atualizar a instalação ou apagar os arquivos da instalação existente e reinstalar resolve o problema; uma pessoa disse que consertou assim
    • Outra relatou que já trocou para outro LLM para verificar o que estava acontecendo, embora não seja um conselho oficial
    • Houve também quem dissesse nunca ter obtido bons resultados com a combinação de Elasticsearch e LLM; na maioria das vezes seriam “alucinações” sem base, possivelmente porque não há muitos exemplos adequados na internet

  • Uma pessoa contou que criou todo o primeiro MVP da startup com Claude Code e que agora já tem clientes pagantes; claro, ainda existe uma ansiedade fundamental de que tudo pode ruir de uma vez em caso de um incidente SEV, mas mesmo assim continua usando Claude intensamente para corrigir vulnerabilidades de segurança, fazer desenvolvimento orientado a testes e projetar a arquitetura de software de acordo com o roadmap de longo prazo
    Ela espera que esse tipo de história se torne cada vez mais comum no futuro

    • Pediram que compartilhasse um link do produto, porque havia curiosidade sobre um caso real de uso
    • Houve uma pergunta em tom de brincadeira se “corrigir vulnerabilidades de segurança” não significaria que o próprio Claude escreveu o código e também criou as vulnerabilidades desde o começo
    • Também pediram exemplos concretos de como ele ajudou em coisas como desenvolvimento orientado a testes e design de software
    • Outra brincadeira foi que a pessoa mandou o Claude Code transferir dinheiro todo mês para sua conta bancária e ele realmente faz isso
    • Também pediram que dissesse mais especificamente o que foi construído com Claude Code

  • Houve a opinião de que, se a ideia é “Keep things simple”, então isso na prática até parece uma configuração um pouco complexa
    A pessoa diz que sempre conseguiu fazer bastante coisa com uma abordagem simples de fazer uma pergunta por prompt
    Não está convencida de qual valor adicional essas estruturas complexas discutidas trazem em relação a prompts muito bem elaborados
    Por exemplo, pensa que um prompt de uma frase como "como fazer um loop while em uma linguagem que estou aprendendo" pode até ser mais eficiente
    O fluxo de controle parece pouco claro, e há dúvida se o LLM realmente usa bem os apêndices, como ferramentas ou prompt de sistema; se o pedido fica complexo demais, talvez partes sejam ignoradas ou haja desperdício de tokens
    Programar soltando prompts separados por etapa parece muito mais natural para essa pessoa
    Ela gostaria de ver exemplos de quem usa outros métodos ou exemplos de prompts
    Também tem curiosidade sobre como as pessoas realmente constroem programas inteiros com LLMs e quer ver casos em que isso é feito por meio de prompts divididos por partes

    • Outra pessoa disse que usa exatamente do mesmo jeito e também tem curiosidade sobre as respostas dos demais

  • Como observação, foi dito que no fim do texto há um link para minusx.com, mas o certificado de segurança está vencido há 553 dias, então o site não é válido e é bom tomar cuidado