Como aproveitar todos os recursos do Claude Code

 (blog.sshh.io)
84 pontos por GN⁺ 2025-11-03 | 2 comentários | Compartilhar no WhatsApp
  • Claude Code é amplamente usado em projetos pessoais e em ambientes corporativos de monorepo, com um resumo de como seus componentes centrais e recursos avançados são usados na prática
  • O ponto central para operar agentes com eficácia está na qualidade do PR final, não no estilo de saída nem na UI, e o objetivo é a delegação no modelo “configurar e deixar rodar” (shoot and forget)
  • O centro da base de código é o arquivo CLAUDE.md, que funciona como uma “constituição” ao definir as regras de comportamento do agente e como usar as ferramentas
  • Recursos como gerenciamento de contexto, comandos slash, subagentes, Hooks e GitHub Action (GHA) aumentam o nível de colaboração e automação
  • Ao distinguir a relação entre Skills e MCP (Model Context Protocol), o texto enfatiza uma estrutura de agentes flexível, centrada em scripts
  • É apresentado um guia prático para expandir o Claude Code de uma simples ferramenta de CLI para uma infraestrutura de desenvolvimento com IA de nível enterprise
  • Uso muito o Claude Code
    • Em projetos por hobby, rodo várias vezes por semana em uma VM e transformo ideias em código imediatamente com --dangerously-skip-permissions
    • No trabalho, a equipe constrói regras e ferramentas de AI IDE, e nosso time de engenharia consome dezenas de bilhões de tokens por mês só com geração de código
  • O mercado de agentes em CLI está lotado com Claude Code, Gemini CLI, Cursor e Codex CLI, mas a concorrência real é entre Anthropic e OpenAI
    • Mesmo assim, ao conversar com desenvolvedores, a escolha da ferramenta depende de fatores superficiais
      • Como uma implementação “de sorte” de algum recurso ou o “vibe” do system prompt preferido
    • Neste momento, todas essas ferramentas já são bastante boas
  • Algumas pessoas focam demais em estilo de saída ou UI
    • Bajulação como “you're absolutely right!” não é um bug digno de tanta atenção
    • Na verdade, isso é um sinal de que o usuário está participando demais do loop
  • Minha filosofia central de uso é “Shoot and Forget”
    • O fluxo é delegar, configurar o contexto e executar a tarefa
    • A ferramenta é julgada pelo PR final, avaliada pelo resultado, não pelo processo até chegar lá
  • Este texto é uma reflexão sobre todo o ecossistema com base na minha experiência usando Claude Code nos últimos meses
    • Quase todos os recursos que uso (e os que não uso)
    • O arquivo básico CLAUDE.md
    • Comandos slash personalizados
    • O poderoso universo de Subagent, Hook e GitHub Actions
  • O texto ficou bem longo, então recomendo usá-lo mais como referência do que ler do começo ao fim

CLAUDE.md: a constituição do agente

  • O CLAUDE.md na raiz é a principal fonte de verdade do agente sobre como o repositório funciona
    • Projeto por hobby: deixe o Claude escrever com bastante liberdade
    • Monorepo enterprise: gerenciamento rigoroso em torno de 13 KB (podendo chegar a 25 KB)
    • Documente apenas as ferramentas usadas por mais de 30% dos engenheiros
    • Defina um limite máximo de tokens para documentar cada ferramenta interna (como se estivesse “vendendo espaço publicitário”)
    • Se você não consegue explicar a ferramenta de forma concisa, então o CLAUDE.md ainda não está pronto

  • Dicas e antipadrões comuns

    • Comece com guardrails, não com um manual: comece com uma documentação pequena, baseada nas partes em que o Claude costuma errar
    • Não documente arquivos com @
      • Se você mencionar com @ uma documentação extensa em outro lugar, o arquivo inteiro será embutido na janela de contexto a cada execução, ficando inflado
      • Se mencionar só o caminho, o Claude tende a ignorar
      • É preciso “sugerir” ao agente por que e quando ele deve ler o arquivo
      • Exemplo: “Para uso complexo ou ao ocorrer FooBarError, consulte path/to/docs.md para troubleshooting avançado”
    • Não diga apenas o que “nunca pode” ser feito
      • Evite restrições em forma negativa como “nunca use a flag --foo-bar”
      • Isso trava o agente quando ele acha que precisa usar essa flag
      • Sempre ofereça uma alternativa
    • Use o CLAUDE.md como função de forçamento
      • Se um comando de CLI for complexo e verboso, não escreva um parágrafo explicativo para isso (um remendo para problema humano)
      • Em vez disso, crie um wrapper simples em bash com uma API clara e intuitiva e documente o wrapper
      • Manter o CLAUDE.md o mais curto possível é uma excelente função de forçamento para simplificar a base de código e as ferramentas internas

  • Estrutura de exemplo

    # Monorepo  

## Python  
- Always ...  
- Test with <command>  
... 10개 항목 ...  

## <Internal CLI Tool>  
... 80% 사용 사례에 집중한 10개 불릿 ...  
- <usage example>  
- Always ...  
- Never <x>, prefer <Y>  

복잡한 사용법이나 오류 시 path/to/<tool>_docs.md 참조
  • Mantenha compatibilidade com outras AI IDEs usadas pelos engenheiros sincronizando também com o arquivo AGENTS.md
  • Dica extra: consulte "AI Can't Read Your Docs", "AI-powered Software Engineering", "How Cursor (AI IDE) Works"

Compact, Context, Clear: gerenciamento da janela de contexto

  • Use o comando /context para verificar o uso da janela de 200k tokens
    • Mesmo no Sonnet-1M, ainda não está claro se a janela de contexto inteira é usada de forma eficaz
    • Em uma nova sessão de monorepo, cerca de 20k tokens (10%) já são consumidos por padrão, e os 180k restantes ficam para o trabalho de modificação (e acabam rápido)
  • Três fluxos de trabalho principais
    • /compact (evitar): a compactação automática é opaca, falha e não é bem otimizada, então deve ser evitada ao máximo
    • /clear + /catchup (reinício simples): método padrão de reboot, limpando o estado com /clear e depois usando o /catchup personalizado para ler todos os arquivos alterados na branch git
    • “Document & Clear” (reinício complexo): para trabalhos grandes, o Claude despeja o plano e o progresso em um .md → /clear → na nova sessão, lê o .md e continua

Comandos slash personalizados

  • Comandos slash são apenas atalhos simples para prompts usados com frequência, nada mais, nada menos
  • Configuração mínima
    • /catchup: prompt para ler todos os arquivos alterados na branch git
    • /pr: helper para organizar o código, fazer staging e preparar o PR
  • Uma lista complexa de comandos personalizados é um antipadrão
    • O ponto central de um agente como o Claude: conseguir gerar resultados úteis e combináveis com praticamente qualquer entrada em linguagem natural
    • Obrigar engenheiros (ou não engenheiros) a aprender uma lista obrigatória de “comandos mágicos” para executar tarefas = fracasso
    • O objetivo é construir um agente com CLAUDE.md mais intuitivo e ferramentas melhores

Subagent personalizado

  • Em teoria, um recurso poderoso de gerenciamento de contexto
    • Trabalho complexo: contexto de entrada de X tokens + contexto de trabalho de Y tokens + resposta de Z tokens
    • N tarefas = (X + Y + Z) * N tokens na janela principal
    • Solução com Subagent: delegar tarefas (X + Y) * N a um agente especializado e retornar apenas a resposta final de Z tokens
  • Na prática, os Subagents personalizados criam dois novos problemas
    • Gatekeeping de contexto: ao criar um Subagent PythonTests, todo o contexto de testes fica oculto do agente principal → raciocínio global impossível → acaba sendo necessário chamar o Subagent para saber como verificar o próprio código
    • Imposição de workflow humano: força o Claude a seguir um workflow rígido definido por humanos → instruir como delegar passa a ser exatamente o problema que o agente deveria resolver

  • Pessoalmente, prefiro o recurso Task(...)

    • Criar uma cópia de um agente genérico com o recurso embutido Task(...) do Claude
      • Colocar todo o contexto central em CLAUDE.md
      • O agente principal decide quando e como delegar trabalho à própria cópia
      • Mantém as vantagens de economia de contexto do Subagent, mas elimina as desvantagens
      • O agente gerencia dinamicamente a própria orquestração
    • Chamado de arquitetura "Master-Clone" em "Building Multi-Agent Systems (Part 2)"
      • Fortemente preferida em relação ao modelo "Lead-Specialist" induzido por Subagents personalizados

Resume, Continue, History

  • Uso básico
    • Uso claude --resume e claude --continue com frequência
    • Reinício rápido de terminais com bug ou de sessões antigas
    • Retomar uma sessão de alguns dias atrás com claude --resume para resumir como um erro específico foi superado → melhorar CLAUDE.md e ferramentas internas
  • Uso avançado
    • O Claude Code salva todo o histórico de sessões em ~/.claude/projects/
    • Tenho scripts que aproveitam os dados brutos do histórico das sessões
    • Executo meta-análises nos logs: busco exceções comuns, solicitações de permissão e padrões de erro → melhoro o contexto dado ao agente

Hooks

  • Essenciais em repositórios enterprise: não uso em projetos de hobby
  • Regras determinísticas de "must-do" que complementam as sugestões de "should-do" do CLAUDE.md
  • Dois tipos
    • Hook de bloqueio na etapa de commit (Block-at-Submit): estratégia principal
      • Uso um Hook PreToolUse para encapsular todos os comandos Bash(git commit)
      • Verifica o arquivo /tmp/agent-pre-commit-pass (criado apenas quando um script de testes confirma que todos os testes passaram)
      • Se o arquivo não existir, o commit é bloqueado → força o Claude a entrar em um loop de "testar-corrigir" até o build passar
    • Hook de dica: Hook simples sem bloqueio, que fornece feedback "fire-and-forget" quando o agente toma um caminho subótimo
  • Não uso intencionalmente Hook de bloqueio na etapa de escrita (Edit ou Write)
    • Bloquear o agente no meio do plano causa confusão ou "frustração"
    • É muito mais eficaz verificar o resultado final na etapa de commit, depois que o trabalho estiver concluído

Modo de planejamento

  • Ao fazer mudanças "grandes" de funcionalidade com uma AI IDE, planejamento é obrigatório
  • Projetos de hobby: uso exclusivamente o modo de planejamento embutido
    • Serve para me alinhar antes de iniciar o Claude
    • Define como fazer o build e os "checkpoints de inspeção" em que o trabalho deve parar e mostrar resultados
    • O uso regular cria uma forte intuição sobre o contexto mínimo necessário para obter um bom plano sem que o Claude estrague a implementação
  • Monorepo enterprise: comecei a implementar uma ferramenta de planejamento personalizada baseada no Claude Code SDK
    • Parecida com o modo de plano nativo, mas com prompts focados em alinhar a saída ao formato de design técnico já existente
    • Vem com imposição embutida de boas práticas internas (da estrutura de código até privacidade de dados e segurança)
    • Permite que engenheiros façam o "vibe plan" de novas funcionalidades como se fossem arquitetos sêniores (ou pelo menos essa é a proposta)

Skills

  • Concordo com Simon Willison: Skills são (provavelmente) algo maior do que MCP
  • Evolução em 3 etapas do modelo mental de autonomia de agentes
    • Single Prompt: fornecer todo o contexto ao agente em um único prompt gigantesco (frágil, não escalável)
    • Tool Calling: modelo de agente "clássico", com ferramentas criadas manualmente e abstrações da realidade para o agente (melhorou, mas criou novos gargalos de abstração e contexto)
    • Scripting: dar ao agente acesso ao ambiente bruto (binários, scripts, documentação) → o agente escreve código na hora para interagir
  • Agent Skills são claramente o próximo recurso: uma oficialização em produto da camada de "Scripting"
  • Se você já preferia CLI a MCP, já obteve implicitamente os benefícios de Skills
    • Arquivos SKILL.md são uma forma mais organizada, compartilhável e fácil de descobrir de documentar essas CLIs e scripts e expô-los ao agente
  • Skills são a abstração correta: formalizam um modelo de agente baseado em "scripting" mais robusto e flexível do que o modelo rígido, semelhante a API, representado pelo MCP

MCP (Model Context Protocol)

  • A existência de Skills não significa que o MCP morreu (veja "Everything Wrong with MCP")
  • Problema anterior: muita gente construiu MCPs horríveis e pesados em contexto, com dezenas de ferramentas que espelhavam APIs REST (read_thing_a(), read_thing_b(), update_thing_c())
  • O modelo de "Scripting" (formalizado por Skills) é melhor, mas precisa de uma forma segura de acessar o ambiente → esse é o novo papel, mais focado, do MCP

  • Novo papel do MCP: gateway de dados

    • Em vez de APIs inchadas, oferecer um gateway simples e seguro com algumas ferramentas poderosas de alto nível
      • download_raw_data(filters…)
      • take_sensitive_gated_action(args…)
      • execute_code_in_environment_with_state(code…)
    • Papel do MCP: não abstrair a realidade para o agente, mas gerenciar autenticação, rede e limites de segurança, e depois sair do caminho
      • Fornecer um ponto de entrada para o agente → o agente faz o trabalho real com scripting e contexto em markdown
    • Único MCP que uso hoje: Playwright (faz sentido por ser um ambiente complexo e com estado)
      • Todas as ferramentas sem estado (Jira, AWS, GitHub) foram migradas para CLI simples

SDK do Claude Code

  • O Claude Code não é apenas uma CLI interativa, mas também um SDK poderoso para criar agentes totalmente novos tanto para tarefas de programação quanto não relacionadas à programação
  • Em muitos projetos novos por hobby, está começando a ser usado como framework de agentes padrão em vez de ferramentas como LangChain/CrewAI
  • Três principais formas de uso
    • Scripting paralelo em larga escala: para grandes refatorações, correções de bugs e migrações, sem usar chat interativo
      • Escrever scripts bash simples chamando claude -p &quot;in /pathA change all refs from foo to bar&quot; em paralelo
      • Muito mais escalável e controlável do que fazer o agente principal gerenciar dezenas de tarefas de Subagent
    • Construção de ferramentas internas de chat: perfeito para encapsular processos complexos em uma interface de chat simples para usuários não técnicos
      • Ex.: um instalador que, em caso de erro, faz fallback para o SDK do Claude Code para resolver o problema do usuário
      • Ex.: uma ferramenta interna "v0-at-home" para a equipe de design fazer vibe-code de frontends mockados com o framework interno de UI da empresa (garantindo alta fidelidade da ideia e uso mais direto no código de frontend de produção)
    • Prototipagem rápida de agentes: o caso de uso mais comum, não limitado a programação
      • Quando há uma ideia de tarefa para um agente (por exemplo, um “agente de investigação de ameaças” usando CLI customizada ou MCP)
      • Antes de fazer commit do scaffolding completo de deploy, criar e testar rapidamente um protótipo com o SDK do Claude Code

GitHub Action (GHA) do Claude Code

  • Um dos recursos preferidos e mais subestimados: conceito simples (executar o Claude Code no GHA), mas essa simplicidade é a fonte do seu poder
  • Semelhante ao agente em segundo plano do Cursor ou à web UI gerenciada do Codex, mas muito mais customizável
    • Controle total do contêiner e do ambiente → melhor acesso aos dados
    • Sandboxing e controles de auditoria muito mais fortes do que em outros produtos
    • Suporte a todos os recursos avançados, como Hook e MCP

  • Casos de uso

    • Construir uma ferramenta customizada de “PR de qualquer lugar”
      • Possibilidade de disparar PRs a partir do Slack, Jira e até alertas do CloudWatch
      • O GHA devolve um PR totalmente testado após corrigir o bug ou adicionar a funcionalidade
    • Flywheel orientado por dados
      • Logs do GHA = logs completos do agente
      • Revisão periódica dos logs no nível da empresa: descobrir erros comuns, falhas de bash e práticas de engenharia desalinhadas
      • Flywheel: bug → melhoria em CLAUDE.md/CLI → agente melhor
      • $ query-claude-gha-logs --since 5d | claude -p &quot;see what the other claudes were getting stuck on and fix it, then put up a PR&quot;

settings.json

  • Configurações específicas essenciais tanto para projetos por hobby quanto para o trabalho
  • HTTPS_PROXY/HTTP_PROXY: para debugging
    • Inspecionar o tráfego bruto para ver os prompts exatos que o Claude está enviando
    • Para agentes em segundo plano, é uma ferramenta poderosa para sandboxing de rede granular
  • MCP_TOOL_TIMEOUT/BASH_MAX_TIMEOUT_MS: aumentar os valores
    • Preferência por executar comandos longos e complexos; o timeout padrão costuma ser conservador demais
    • Ainda não está claro se isso continua necessário após os trabalhos bash em segundo plano, mas é mantido por garantia
  • ANTHROPIC_API_KEY: no trabalho, usar uma chave de API enterprise (via apiKeyHelper)
    • Migrar de licenciamento “por assento” para precificação “baseada em uso” (um modelo muito melhor para essa forma de trabalhar)
    • Levar em conta a enorme diferença de uso entre desenvolvedores (foi observada diferença de 1:100 entre engenheiros)
    • Permite que engenheiros experimentem scripts de LLM que não sejam do Claude Code com uma única conta enterprise
  • &quot;permissions&quot;: fazer autoauditoria periódica da lista de comandos que o Claude tem permissão para executar automaticamente

Encerramento

  • É bastante coisa, mas espero que seja útil
  • Se você ainda não usa agentes baseados em CLI como Claude Code ou Codex CLI, deveria usar
  • Quase não há bons guias sobre esses recursos avançados, e a única forma de aprender é mergulhando de cabeça

Leituras relacionadas

2 comentários

 
GN⁺ 2025-11-03
Comentários no Hacker News

  • Estamos mantendo o arquivo sincronizado com AGENTS.md para compatibilidade com outras AI IDEs
    Investigando recentemente, vi que a forma recomendada pela Anthropic é colocar apenas uma linha @AGENTS.md no arquivo CLAUDE.md e deixar o conteúdo real em AGENTS.md
    Documentação relacionada: Claude Code Best Practices

    • Acho que, para alinhar ao padrão, deveríamos renomear CLAUDE.md para AGENTS.md
    • Estamos usando AGENTS.md com link simbólico para CLAUDE.md, e funciona bem
    • Parece uma forma mais limpa de fazer isso
    • Fico na dúvida se usar link simbólico é uma boa ideia
    • Pela minha experiência, o Claude e outros agentes na prática não leem AGENTS.md nem CLAUDE.md a menos que você dê uma instrução explícita em cada sessão

  • Gostei muito desta parte do texto sobre MCP
    Gostei da visão de que “MCP deveria ser um gateway enxuto que gerencia autenticação, rede e limites de segurança, e sai da frente no resto”, em vez de uma API complexa
    Texto relacionado

    • Quando o MCP apareceu pela primeira vez, eu não imaginava esse tipo de uso, mas agora dá para sentir que o Claude quer mais script de dados do que vários “tools”. Meu papel é só entregar bem os dados
    • Meu MCP é só um interpretador de código. Recentemente estou testando um MCP proxy que permite chamar MCPs de dentro do interpretador de código
      Mesmo assim, quase não uso MCP. Queria que focassem mais na parte de auth
      Link de referência: post no X
    • Usando MCP como API gateway interno, ele funciona mais ou menos assim. Na prática é parecido com OpenAPI, mas otimizado um pouco melhor para inferência de LLM

  • É meio triste que um texto de 3000 palavras seja “longo demais, só para referência”
    Eu gostaria de ver uma versão ainda mais longa com exemplos reais

    • Hoje em dia estou pessimista sobre quanto as pessoas realmente vão ler
    • Eu também esperava mais, e fiquei decepcionado com a limitação do conteúdo. Ainda assim, tirei alguns pontos úteis

  • Estou usando uma rotina simples de reinício com /clear e /catchup para resetar o estado do Claude e fazê-lo reler os arquivos alterados
    Provavelmente o comando /compact vai acabar assumindo esse papel em breve

    • Por causa da latência do /compact, quase não dá para usar
      Mesmo quando aparece “0% context remaining”, na prática uns 30% ficam reservados para compressão
      E ainda assim metade das vezes a compressão falha ou bate no limite da API

  • Também é bom usar o Claude Code para melhorar a própria configuração
    Recomendo mudar para o modo plan e usar o seguinte prompt:
    “Leia este documento(How I use every Claude Code feature) e me diga como melhorar minha configuração do Claude Code”

  • Desisti de manter o CLAUDE.md porque o Claude não segue nem comandos simples ali
    Por exemplo, mesmo mandando nomear scripts gerados como <foo>.aigen.ts, ele ignora isso em metade das vezes
    Então estou contornando colocando o contexto diretamente no prompt toda vez
    Será que só eu tenho esse problema?

    • Meu CLAUDE.md é bem longo, mas ele quase sempre segue. Quando ignora, eu mudo para algo como “IMPORTANT! ALWAYS DO …” com ênfase em maiúsculas, e em 95% dos casos funciona direito
      Tive resultados parecidos em vários projetos
    • Tive exatamente a mesma experiência. Só que já desisti faz tempo, então não sei se melhorou nas versões mais recentes
    • Isso já é um problema conhecido entre nós, Claudemasters

  • Tinha um comentário dizendo “se você não está usando agentes baseados em CLI, deveria estar”, e fiquei curioso se isso é realmente melhor do que o app do Cursor
    O Cursor é bom porque fica fácil selecionar uma parte específica do código e apertar Cmd-L para dizer “conserta isso aqui”
    Mandar trechos de código pela CLI parece um pouco trabalhoso

    • Eu uso Claude e Codex no VS Code, e o fluxo de dar comandos direto no código selecionado funciona muito bem
    • Tenho resultados melhores usando Codex + GPT5 ou o Claude Code CLI diretamente do que com o Cursor. Parece que o Cursor faz um ajuste para reduzir o tamanho da saída a fim de economizar tokens
    • Eu também comecei no Cursor, passei por um uso híbrido e no fim migrei totalmente para CLI
      Tanto a UX leve quanto a eficiência são melhores. O Claude funciona melhor no CC
    • O Claude reconhece automaticamente as linhas de código selecionadas no VS Code
    • Também dá para selecionar vários arquivos ao mesmo tempo para focar, e executar comandos do PATH (gh etc.)

  • Ao ver a frase “Claude Code não é só uma CLI, é um SDK para criar novos agentes”, senti um cansaço por soar como texto escrito por IA
    Pareceu um jeito de escrever que não respeita o leitor

    • Eu também tinha uma rejeição instintiva a texto gerado por IA, mas hoje tento julgar pelo conteúdo em si
      Neste texto, achei que havia sinais de que o autor realmente leu e editou o material, então considero um bom exemplo
      Já copiar e colar a saída da IA sem revisar merece crítica
    • Isso me lembra a frase “a internet morreu. Vida longa à internet”
    • Ninguém te obrigou a ler, então não entendo por que isso pareceu ofensivo
      Eu, pelo contrário, me senti respeitado e li até o fim

  • Essas ferramentas são interessantes, mas me preocupa se a indústria não está mais uma vez focando na tecnologia em si, e não no cliente
    (Lembra o ensaio “Top idea in your mind”, do Paul Graham)

    • Sim. Ferramentas de programação baseadas em LLM são boas para métricas corporativas como velocidade e redução de custo, mas o que o cliente quer é funcionalidade e estabilidade
      Se o produto foi feito rápido e barato, mas está cheio de bugs, isso não vale nada
      Com IA é a mesma coisa: CEOs estão olhando só como ferramenta de corte de pessoal, mas a tecnologia ainda não está num nível de trazer benefício real para o cliente
      Chatbots de IA só deixam o cliente mais irritado
    • Fico curioso sobre o que “cliente” quer dizer aqui. Eu uso essas ferramentas para entender melhor os clientes

  • A velocidade de evolução do Claude Code é surpreendentemente rápida
    Ele continua melhorando a ponto de toda semana surgir algo novo para aprender

    • Olhando para o uso de CPU e memória, isso nem é tão surpreendente assim
      Se ele conseguisse adicionar recursos sem deixar meu M4 Mac (64GB RAM) mais lento, aí sim seria mágica
 
hyeonseokoh94 2025-11-05

É bom, mas..