Claude Code: Boas Práticas de Uso Real em Produção

[Leitura do operador] Uso o Claude Code todo dia útil em dois negócios — uma marca de consultoria e a Pickleland, um espaço de pickleball em Pflugerville, no Texas — para tudo, desde o pipeline de publicação deste blog até o code review em Workers de produção. Isso não é uma introdução ao que é o Claude Code. São os hábitos que mantive depois de meses de uso real, e os que abandonei porque custavam mais do que economizavam.

Índice

Abrir Índice

• Escreva o CLAUDE.md como regras, não como documentação
• O que delego a um subagente e o que mantenho no meu próprio fio
• Gestão de contexto é a disciplina diária, não uma configuração de uma vez só
• O que aprendi a não deixar ele fazer sozinho
• Verifique antes de publicar — o “pronto” do Claude é uma afirmação, não um fato
• O veredito do operador
• FAQ
  • O que deveria realmente entrar em um arquivo CLAUDE.md?
  • Como você decide quando confiar na saída do Claude Code sem checar de novo?
  • Você deixa o Claude Code fazer commit e push sozinho?
  • Qual é o hábito que mais economizou tempo?

Escreva o CLAUDE.md como regras, não como documentação

A primeira versão de cada CLAUDE.md que escrevi era longa demais, e todas foram encurtando com o tempo, nunca aumentando. O erro é tratá-lo como uma página de wiki — contexto, filosofia, “por que fazemos assim”. O Claude lê o arquivo inteiro em toda sessão, precise ou não do detalhe para a tarefa atual, então todo parágrafo que não é uma instrução compete por atenção com os parágrafos que são.

O que sobrevive à edição é mais estreito: regras rígidas, idealmente aquelas que um teste exige para que não regridam em silêncio, mais links para documentos mais longos para os casos que realmente precisam do detalhe. “Títulos com menos de 60 caracteres” merece uma linha. A história de por que esse limite existe merece um link para um documento, não um parágrafo no arquivo que o Claude relê em toda sessão.

A segunda coisa que adicionei, e a que eu não esperava que importasse tanto: uma lista curta de fatos já resolvidos, escritos uma vez, com a instrução explícita de não investigá-los de novo. No começo, o Claude Code voltava a diagnosticar o mesmo alarme falso a cada poucas sessões — uma checagem instável, uma peculiaridade conhecida em uma etapa de build — e queimava contexto rederivando uma conclusão à qual eu já tinha chegado. Uma linha declarando o fato verificado e dizendo ao agente para seguir em frente em vez de reabrir a investigação derrubou esse tempo morto para quase zero. A regra que uso: se você já explicou duas vezes o mesmo “na verdade, isso é esperado”, isso pertence ao CLAUDE.md como fato, não como algo que você digita de novo no chat pela terceira vez.

O que delego a um subagente e o que mantenho no meu próprio fio

Já escrevi o framework de decisão completo sobre skills, comandos slash e subagentes separadamente, então não vou repetir aqui. O que vale a pena acrescentar é o filtro em nível operacional que de fato aplico antes de gerar um: consigo descrever em uma frase o que “pronto” significa, e eu realmente leria os passos intermediários se eles ficassem no meu fio principal?

Se a resposta às duas for não — a tarefa é delimitada e eu só quero o resultado — é um subagente. Traduzir este post para 12 idiomas é o exemplo mais claro: cada tradução é verificável de forma independente, esse leque é exatamente por que o pipeline de conteúdo roda um subagente por idioma, e eu jamais ia querer 12 idiomas de idas e vindas intermediárias poluindo o fio onde ainda estou decidindo se o post em inglês está certo.

Se a tarefa exige que eu veja o raciocínio enquanto acontece — uma mudança de schema em que a terceira decisão depende do que a segunda revelou — ela fica no meu fio principal. O modo de falha que de fato já enfrentei é gerar um subagente para esse tipo de tarefa mesmo assim, receber um resumo limpo, e então perguntar “espera, o que você achou exatamente” três vezes porque o resumo descartou o único detalhe que importava. Quando isso acontece duas vezes com o mesmo tipo de tarefa, paro de delegá-la.

Gestão de contexto é a disciplina diária, não uma configuração de uma vez só

O CLAUDE.md é a parte que as pessoas escrevem uma vez e esquecem. A janela de contexto é a parte que gerencio em toda sessão, e é ela que de fato determina se o resultado é bom.

• Leia antes de deixar ele editar. O Claude Code vai propor de bom grado uma mudança contra um arquivo cujo estado atual completo ele não viu. Faço ele ler o arquivo primeiro, sempre, mesmo quando estou confiante de que sei o que tem lá — já errei nesse “confiante” vezes suficientes para que isso não seja mais opcional.
• Não deixe uma sessão fazer dois trabalhos sem relação. Um fio que passou uma hora depurando um problema de deploy e então vira para escrever copy de marketing arrasta aquela hora de saída de ferramentas irrelevante para toda resposta seguinte. Começo uma sessão nova em vez de pedir ao Claude para “esquecer o assunto do deploy” — essa instrução não remove os tokens, só pede ao modelo para ignorá-los, o que ele faz de forma imperfeita.
• Planeje antes de deixar ele executar. Para qualquer coisa com mais de dois ou três passos, peço o plano primeiro e leio antes de aprovar a execução. Ler um plano de cinco linhas leva quinze segundos. Descobrir que o passo três estava errado depois que o passo cinco já rodou custa o resto da tarde.
• Colar blocos enormes é um custo, não uma conveniência. Jogar um arquivo de log inteiro ou uma resposta de API completa na conversa quando só três linhas importam queima contexto nos outros 97%. Faço grep primeiro e colo a correspondência.

É o mesmo princípio por trás de engenharia de contexto para agentes de IA de forma geral — o Claude Code só torna o custo visível mais cedo, porque é você quem vê o contexto encher em tempo real em vez de depurar isso depois em um log de Worker.

O que aprendi a não deixar ele fazer sozinho

Toda ação irreversível — commit, push, publicar, enviar, gastar — fica atrás de uma etapa de aprovação explícita que eu mesmo executo, nunca uma que o Claude Code decide tomar porque julgou a tarefa concluída. É o mesmo padrão de humano no ciclo que uso em todo lugar onde agentes tocam em consequências reais, e o Claude Code não é exceção só porque roda na minha própria máquina em vez da nuvem.

A outra coisa que parei de fazer: dar permissão ampla e permanente para comandos destrutivos. rm -rf, force-push, pular hooks de teste — nenhum deles recebe um sim geral. Cada um é pedido, toda vez, em contexto, porque a única vez que pré-aprovei algo amplo “para economizar tempo” foi a única vez que a tarefa saiu para um escopo que eu não tinha realmente revisado. Os cinco segundos que um prompt de permissão custa são um seguro barato contra a alternativa.

Verifique antes de publicar — o “pronto” do Claude é uma afirmação, não um fato

Esse é o hábito que mais se pagou, e é o menos chamativo: não confio em um relatório de conclusão. Rodo a checagem real.

O Claude Code vai dizer que um build passou, que uma suíte de testes está verde, que um link funciona. Às vezes esse relatório é gerado a partir de uma saída real. Às vezes é um resumo confiante de um comando que rodou pela metade, ou uma checagem que retornou cedo sem nada útil dentro. Os dois parecem idênticos na transcrição do chat. A única forma de diferenciá-los é olhar você mesmo a saída real — a mesma disciplina por trás de o eval harness que uso para lançar agentes: uma tarefa não é marcada como concluída porque o agente diz que sim, é marcada quando a checagem definida de fato passa.

Na prática isso significa: rodar o comando de build e ler a saída dele, não a paráfrase do Claude. Abrir o arquivo que ele diz ter editado. Clicar no link que ele diz que funciona. Para conteúdo especificamente, releio o rascunho de forma adversarial contra as regras que sei que são exigidas — limites de tamanho, padrões proibidos, links internos quebrados — em vez de confiar que o Claude as aplicou corretamente da primeira vez, porque quase sempre aplicou e ocasionalmente não, e o custo de o erro ocasional chegar a um site no ar é maior do que os noventa segundos que a releitura toma.

O veredito do operador

Nada disso é sobre confiar menos no Claude Code com o tempo — é sobre ser específico sobre onde essa confiança de fato precisa ser conquistada. CLAUDE.md curtos e exigíveis em vez de documentação longa. Subagentes para trabalho delimitado e verificável, seu próprio fio para tudo em que o raciocínio importa tanto quanto o resultado. Contexto novo em vez de uma sessão arrastada. Portões de aprovação em tudo que você não pode desfazer. E uma checagem real, lida por você mesmo, antes de qualquer coisa que você delegou ir ao ar. É essa a lista inteira, e é a que eu de fato sigo.

FAQ

O que deveria realmente entrar em um arquivo CLAUDE.md?

Regras que o agente precisa seguir em toda sessão, escritas como instruções — não o contexto de por que a base de código ficou do jeito que ficou. Se uma regra é exigida por um teste, diga isso e deixe o teste ser a fonte da verdade. Contexto mais longo pertence a um documento para o qual o CLAUDE.md aponta, lido só quando a tarefa realmente toca naquela área, não recarregado por padrão em toda sessão.

Como você decide quando confiar na saída do Claude Code sem checar de novo?

Não decido pular a checagem — decido o quanto ela custa. Rodar um comando de build é quase de graça, então sempre faço isso. Uma releitura adversarial completa de um documento longo leva mais tempo, então reservo isso para o que vai para um público real. A única coisa que nunca pulo: qualquer coisa irreversível — publicar, fazer commit, gastar dinheiro.

Você deixa o Claude Code fazer commit e push sozinho?

Não. Todo commit e todo push são algo que eu mesmo executo, depois de olhar o diff. O Claude Code propõe a mudança; eu sou o portão de aprovação para tudo que sai do estado de rascunho, a mesma regra que aplico a qualquer outro agente que rodo.

Qual é o hábito que mais economizou tempo?

Tratar um relatório de conclusão como uma afirmação, não como um fato, e rodar eu mesmo a checagem real. Parece que isso deixaria tudo mais lento. Na prática é o contrário — pegar um “pronto” falso em trinta segundos é mais rápido do que descobrir em produção três dias depois.

---

Relacionados: Claude skills vs. comandos slash vs. subagentes · A stack de agentes que uso para rodar mais de 30 agentes em produção · Agentes de IA com humano no loop: quando construir uma barreira de aprovação · Como usar as tarefas agendadas do Claude

Quer rodar o Claude Code assim no seu próprio negócio? Meu curso AI Agents for Beginners cobre os fundamentos de construção que este manual pressupõe. O programa cowork é onde ensino esses hábitos operacionais em grupo estruturado. Se preferir que eu faça a configuração para você, agende uma sessão de 30 minutos.