Universal Claude.md – Redução dos tokens de saída do Claude

 (github.com/drona23)
2 pontos por GN⁺ 29 일 전 | 1 comentários | Compartilhar no WhatsApp
  • Um arquivo de configuração que reduz o desperdício de tokens de saída ao remover aberturas, encerramentos e reformulações desnecessárias dos modelos Claude
  • Ao adicionar CLAUDE.md na raiz do projeto, ele é aplicado imediatamente sem modificar código, com efeito médio de 63% de redução de tokens
  • Simplifica as respostas com 12 regras, como saída somente em ASCII, proibição de suposições e limitação da resposta ao escopo solicitado
  • Em ambientes com grande volume de saída, como pipelines de automação, geração de código e loops de agentes, o impacto na redução de custos é grande; para consultas únicas, pode ser ineficiente
  • Publicado sob licença MIT, permitindo gestão de regras baseada em perfis por equipe ou tarefa e contribuições da comunidade

Visão geral do problema

  • No Claude Code, toda palavra gerada gera custo em tokens, e na configuração padrão o usuário tem pouco controle sobre o formato da resposta
  • Por padrão, são incluídos automaticamente inícios educados, como “Sure!” e “Great question!”, encerramentos formais, como “I hope this helps!”, além de reformulações da pergunta e sugestões desnecessárias
  • Além disso, ele usa caracteres que podem quebrar parsers, como em dash, aspas inteligentes e caracteres Unicode, e inclui abstração excessiva de código ou expressões de concordância incorretas
  • Isso causa desperdício de tokens e quase não agrega valor informacional real

Como resolver

  • Ao adicionar um arquivo CLAUDE.md na raiz do projeto, o Claude Code o lê automaticamente e muda imediatamente o comportamento de saída
  • Funciona sem alteração de código nem configuração adicional e reduz o uso de tokens de saída em cerca de 63%
  • Exemplo de estrutura 
    your-project/
└── CLAUDE.md

Quando vale a pena aplicar e quando não vale

  • Casos favoráveis

    • Pipelines de automação, loops de agentes e geração de código com alto volume de saída

      • Quando as respostas padrão prolixas do Claude se acumulam em tarefas repetitivas e estruturadas
      • Em ambientes de equipe que exigem formato de saída consistente entre sessões

  • Casos desfavoráveis

    • Em consultas curtas únicas ou uso pontual, o CLAUDE.md ocupa tokens de entrada a cada vez e pode acabar aumentando o custo
    • Não ajuda em solução profunda de problemas como correção de alucinações ou ajuste de erros arquiteturais
    • Em pipelines que abrem uma nova sessão a cada tarefa, perde-se o efeito de economia baseado em sessões persistentes
    • Para garantir confiabilidade de parser em larga escala, é mais adequado usar modo JSON ou ferramentas baseadas em schema
    • Em tarefas exploratórias ou centradas em discussão, pode parecer restritivo

  • Trade-off real

    • Como o próprio CLAUDE.md consome tokens de entrada, só há ganho líquido quando o volume de saída é suficientemente alto
    • Em uso de baixo volume, o custo pode ser maior do que a economia

Resultados de benchmark

  • Testado com os mesmos 5 prompts
    Teste Padrão Otimizado Redução
    Explicação de async/await 180 palavras 65 palavras 64%
    Code review 120 palavras 30 palavras 75%
    Explicação de API REST 110 palavras 55 palavras 50%
    Correção de alucinação 55 palavras 20 palavras 64%
    Total 465 palavras 170 palavras 63%
  • Cerca de 295 palavras economizadas, sem perda de informação
  • Ainda assim, trata-se apenas de um indicador direcional; não houve controle estatístico nem experimentos repetidos
  • Só há efeito líquido de economia quando o volume de saída é alto

  • Exemplo de economia em uso em larga escala

    Volume de uso Tokens economizados por dia Economia mensal (base Sonnet)
    100 vezes/dia aprox. 9,600 aprox. $0.86
    1.000 vezes/dia aprox. 96,000 aprox. $8.64
    3 projetos aprox. 288,000 aprox. $25.92

Exemplo de comparação antes e depois

  • Resposta padrão de code review (120 palavras)

    • Inclui elogios prolixos, explicações e sugestões

  • Após aplicar CLAUDE.md (30 palavras)

    • No formato “Bug: <= causes an off-by-one error…”, transmitindo só o essencial e com 75% de redução de tokens

O que é corrigido

Nº Problema Forma de correção
1 Abertura bajulatória Proibida - a resposta começa na primeira linha
2 Encerramento vazio Proibido - remove “I hope this helps!”
3 Reformulação da pergunta Proibida - execução imediata
4 em dash, aspas inteligentes e Unicode Força saída somente em ASCII
5 Frases como “As an AI…” Proibidas
6 Disclaimers desnecessários Permitidos só em caso de risco real de segurança
7 Sugestões fora do pedido Proibidas - executar apenas o escopo solicitado
8 Abstração excessiva de código Permite apenas o código funcional mais simples
9 Alucinações sobre fatos incertos Declarar “não sei”, suposições proibidas
10 Ignorar correções do usuário As correções passam a valer como fato na sessão
11 Leitura repetida de arquivos Proibido reler o mesmo arquivo
12 Expansão de escopo Proibido modificar código fora do pedido

Dicas da comunidade

  • O mais eficaz é escrever regras de acordo com padrões reais de falha
    • Ex.: quando o Claude engole um erro de pipeline -> adicionar a regra “ao falhar uma etapa, interromper imediatamente e reportar o erro completo e o traceback”

  • O arquivo CLAUDE.md pode ser mesclado hierarquicamente

    • Global (~/.claude/CLAUDE.md): regras gerais (tom, ASCII etc.)
    • Raiz do projeto: restrições específicas do projeto (ex.: proibir modificações em /config)
    • Subdiretórios: regras detalhadas por tarefa
    • Isso permite gerenciar regras de forma distribuída e evita o crescimento excessivo do arquivo

Configuração de perfis

  • É possível escolher diferentes níveis de compressão por tipo de projeto
    Perfil Indicado para
    CLAUDE.md Uso geral
    profiles/CLAUDE.coding.md Desenvolvimento, code review e debugging
    profiles/CLAUDE.agents.md Automação e sistemas multiagente
    profiles/CLAUDE.analysis.md Análise de dados, pesquisa e relatórios

Como usar

Regras de override

  • O comando do usuário sempre tem prioridade

    • Se o usuário pedir explicitamente algo como “explique em detalhes”, o Claude segue esse pedido
    • O CLAUDE.md não suprime a intenção do usuário

Como contribuir

  • Ao encontrar um comportamento ajustável, registre uma Issue
    1. O comportamento padrão problemático
    2. O prompt que o provocou
    3. A regra de correção proposta
  • As sugestões da comunidade serão refletidas na próxima versão, com crédito aos contribuidores

Validação e referências

  • Os resultados completos de benchmark podem ser consultados em BENCHMARK.md
  • O projeto foi criado com base em casos reais de reclamações da comunidade Claude
  • Inclui várias fontes de referência relacionadas (GitHub Issues, The Register, DEV Community, Medium, Anthropic Docs etc.)

Licença

  • Licença MIT, com uso, modificação e distribuição livres

Leituras relacionadas

1 comentários

 
GN⁺ 29 일 전
Comentários no Hacker News

  • O benchmark aqui está enviesado para tarefas explicativas únicas e, na minha visão, não é adequado para loops de agente como geração de código
    Fico curioso se, quando um projeto está em andamento, as explicações prolixas do Claude na verdade ajudam a manter a consistência e o foco da sessão
    A regra de “não repetir contexto redundante” é boa, mas eu acho que usar mais tokens de raciocínio orientados a objetivos ajuda mais
    Ainda faltam dados para saber se essa abordagem funciona de fato em coding agentic

    • Eu criei uma skill chamada /handoff para gerar automaticamente um relatório em Markdown antes de a sessão atingir o limite de compressão
      Esse arquivo serve como registro permanente da sessão e como uma espécie de “relatório diário”, então é ótimo para consultar depois ou compartilhar com um gerente
      Para manter consistência de longo prazo, acho que esse tipo de documentação resumida é melhor
      O método de instalação está aqui
    • Graças à regra de “não explique o que vai fazer, apenas faça”, consegui perceber imediatamente quando o Claude ia na direção errada e ajustar o prompt
    • Não entendo por que as pessoas não colocam no CLAUDE.md regras para bloquear linguagem desnecessária
      Segundo pesquisas recentes, caminhos de raciocínio redundantes (self-consistency) e ensembling de modelos ajudam a melhorar o desempenho
    • Escalonamento do tempo de raciocínio também é importante. Usar mais tokens ao buscar uma resposta pode, na verdade, aumentar a qualidade
      Ficar obcecado com comprimento mínimo entra em conflito com o objetivo do treinamento por RL
    • Rodei testes de programação com várias configurações, e essa abordagem teve desempenho geral inferior em 30 execuções
      O código de teste está aqui

  • O planning mode do Claude Code não funciona direito, então sou cético em relação a essa abordagem com arquivo .md
    Na minha opinião, planning mode deveria simplesmente ser um recurso que desliga a escrita em arquivos

  • A regra “a resposta sempre na 1ª linha, o raciocínio depois” ignora a natureza autorregressiva dos LLMs
    Fixar a resposta primeiro cria um grande risco de o raciocínio posterior cair em viés de confirmação

    • A ideia dessa abordagem é boa, mas a implementação parece errada
      Uma forma de comprimir o raciocínio, como no artigo sobre Compressed Chain of Thought (CCoT), é mais eficiente
      Há uma pequena perda de qualidade, mas há vantagens em velocidade e custo (link do artigo)
    • Em sessões importantes, adiciono prompts de segunda revisão como “sanity check” para reavaliar o plano inicial
    • Um reasoning LLM pode gerar internamente milhares de tokens de raciocínio antes de escrever a resposta
      Ou seja, a regra “resposta primeiro” só muda a ordem de saída, não a ordem real do raciocínio
    • O Claude Code não tem opção “no thinking”, e no mínimo o modo low thinking é o padrão

  • Esse benchmark não faz sentido porque compara apenas a quantidade de tokens de saída sem considerar a acurácia
    Seria fácil inflar a pontuação também com um prompt como “responda sempre com uma palavra”
    Regras como “se o usuário apontar um erro factual, aceite sempre” são perigosas

    • Falam em “a engenharia de prompt voltou?”, mas nos últimos 1–2 anos meta-prompts não trouxeram grande melhora
    • Regras do tipo “não cometa erros” não são realistas

  • Acho que esse tipo de solução universal tende a perder o interesse rápido ou ser absorvido pelo CC
    Ficar mudando o workflow com frequência é cansativo demais
    A configuração padrão do Claude Code é, por enquanto, a mais estável

    • Penso parecido. Sinto que manter uma configuração vanilla é melhor no longo prazo
      Gosto de Skills, mas quase não uso MCP nem worktree
    • Como a Anthropic já está otimizando isso internamente com dogfooding, há grande chance de a configuração padrão ser a mais eficiente
      Basta tratar o CLAUDE.md como um rascunho de notas para um colega inteligente que ele já funciona muito bem
    • Concordo com a ideia de que “no fim isso vai ser integrado ao CC”
      Se a Anthropic não colocou isso diretamente, provavelmente é porque o ganho de desempenho ainda não foi comprovado
    • Essas “camadas de melhoria do Claude” acabam causando instabilidade no workflow
      Mesmo quando são úteis por um tempo, logo são absorvidas pelos recursos nativos ou desaparecem
    • O próprio Claude continua recebendo atualizações de otimização para md
      Então, mesmo usando esses scripts experimentais, atualizar os arquivos md com frequência ajuda a mantê-los em dia

  • À pergunta “se o arquivo é carregado no contexto a cada mensagem, isso não desperdiça tokens?”,
    eu diria que o recurso de personalization do Claude já cumpre esse papel
    Na minha visão, concisão só faz sentido quando melhora a qualidade
    Também achei interessantes algumas ferramentas relacionadas que vi no Reddit:
    Headroom comprime o contexto em 34%,
    RTK comprime a saída do CLI em 60–90%,
    e MemStack oferece memória persistente para evitar reler arquivos desnecessariamente

  • Tenho a impressão de que essas tentativas acabam mostrando um mal-entendido sobre os princípios básicos dos LLMs
    “Resposta primeiro, raciocínio depois” ignora a arquitetura autorregressiva dos transformers
    Como o treinamento por RL já ajusta comprimento ideal e qualidade, mexer demais nisso pode levar a queda de desempenho

    • Forçar a redução do tamanho da resposta piora a qualidade e a consistência do raciocínio e aumenta a probabilidade de alucinação
      O modelo foi treinado para fazer raciocínio em múltiplas etapas com base no inglês
    • A regra “resposta primeiro” não muda a ordem real do raciocínio. O modelo já terminou de pensar internamente antes de gerar a resposta
    • O autor provavelmente não desconhece transformers; parece mais que tentou um hack para reduzir custo de tokens
      É uma abordagem experimental focada mais em eficiência do que em qualidade
    • A maioria das APIs já oferece opções de controle do comprimento do COT. Em vez desse tipo de gambiarra, eu usaria as configurações da API
    • No fim, acho que as ferramentas feitas pela Anthropic são as mais confiáveis.
      Por isso eu só uso ferramentas 1st-party em vez de third-party como OpenCode

  • Como vi no vídeo do Karpathy, há uma tendência de a acurácia aumentar quando o modelo usa mais tokens
    Essa abordagem pode, na verdade, piorar o modelo

    • Ainda assim, se o objetivo aqui for reduzir saída de baixo valor (por exemplo, frases bajuladoras ou ruído de formatação), talvez faça sentido
      Mas forçar a resposta imediata sem raciocínio pode criar risco de viés de fechamento precoce
    • Saídas redundantes ajudam a reforçar a direção, então removê-las pode aumentar a ambiguidade

  • Não entendo por que esse tipo de projeto sem sentido vira tendência no HN
    As ferramentas que realmente reduzem uso de tokens são claude-mem e lumen

    • O motivo é simples: o algoritmo de tendências do HN é otimizado para engajamento, não para precisão

  • Antes as pessoas pesquisavam novos algoritmos de hash, criptografia e compressão
    Agora é irônico que estejamos pesquisando como mandar a IA ficar quieta