# Claude Code: 20 boas práticas da Anthropic

> Published 2026-10-12T22:58:42.866Z on https://www.crazystack.com.br/pt/p/claude-code-20-boas-praticas-da-anthropic/
> Source video: https://www.youtube.com/watch?v=iMso7WbhUr0

Claude Code funciona melhor quando você segue as boas práticas que a própria Anthropic publicou na documentação do produto. Este guia reúne 20 delas, da verificação no prompt ao gerenciamento de sessões, contexto e permissões, para reduzir retrabalho e manter o histórico sob controle.

## Boas práticas Claude Code: o que a Anthropic recomenda de fato

As boas práticas Claude Code publicadas pela Anthropic giram em torno de verificação explícita, escopo pequeno e controle de contexto, não de prompts mais longos. A [documentação oficial do Claude Code](https://docs.anthropic.com/en/docs/claude-code) reúne essas orientações em páginas sobre fluxos de trabalho comuns, automação, checkpoints e permissões. O [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) é a ferramenta de codificação agêntica da [Anthropic](https://www.anthropic.com/) que roda no terminal e executa tarefas sobre o seu repositório.

O roteiro abaixo parte de uma leitura dessa documentação e a organiza em 20 decisões de uso. Algumas valem para qualquer tarefa; outras fazem diferença em refatorações grandes, sessões paralelas ou execuções não assistidas. O ponto em comum é sempre o mesmo: você define o resultado esperado e o critério que prova que ele foi atingido.

Vale separar o que é recomendação oficial do que é prática de comunidade. Neste texto, cada item indica a origem quando ela é relevante, e as inferências editoriais aparecem marcadas como tal.

## Verificação no prompt: como provar que o resultado está certo

A primeira orientação da Anthropic embutir o método de verificação no próprio prompt. Em vez de pedir só a execução, você descreve como o resultado será conferido — rodar a suíte de testes, comparar um screenshot com o design original, listar diferenças e corrigir.

A documentação cita exemplos simples, como uma função de validação de e-mail em que `[email]` é válido e `user@.com` é inválido. O padrão se repete em tarefas de interface, quando você fornece uma imagem, pede a implementação, exige um print do resultado e uma lista de divergências.

Esse item costuma render mais ganho que qualquer ajuste de tom. Sem critério de aceite, o agente decide sozinho quando terminou; com critério, ele consegue voltar atrás sozinho quando a verificação falha.

## Descreva o estado desejado, não a sequência de passos

Descreva o resultado esperado, não o caminho até ele, e deixe o agente localizar os arquivos. A própria Anthropic reforça isso na biblioteca de prompts do Claude Code, que traz exemplos funcionando sem nomear um único caminho de arquivo.

Prescrever a sequência de ações engessa a execução e força o modelo a seguir um roteiro que talvez não sirva ao código real. Descrever o estado desejado dá espaço para o agente escolher a abordagem e ainda manter o objetivo visível.

Em modelos mais fortes, como os da família Opus, a orientação fica mais forte: foque o prompt no resultado, nas restrições e nas evidências que comprovam o resultado. Quanto maior a capacidade do modelo, melhor esse formato tende a funcionar em relação a uma lista rígida de comandos.

## Refatorações em pequenos incrementos testáveis

Refatorações devem acontecer em incrementos pequenos e verificáveis, nunca em uma única passada sobre a base inteira. A documentação do Claude Code traz essa orientação na seção de fluxos de trabalho comuns, junto com receitas de prompt, retomada de conversas e sessões paralelas com worktrees.

O motivo é operacional: cada incremento gera um ponto de verificação e um ponto de retorno. Se o passo seguinte degradar o comportamento, você recupera o estado anterior sem desfazer horas de trabalho.

A mesma lógica vale para interromper o agente cedo. Se ele parte de uma premissa errada ou segue por um caminho ruim, redirecionar nos primeiros minutos custa menos do que corrigir um diff grande depois.

## Regras concretas, contexto limpo e escopo de diretório

Regras curtas e concretas produzem resultado mais preciso do que instruções genéricas. Dizer “use Clean Code” muda pouco; apontar uma spec, um comando ou um contrato entre serviços específico muda o output.

O mesmo princípio se aplica ao contexto. Ao iniciar uma tarefa sem relação com a conversa anterior, comece um contexto novo — com o comando de limpeza, um subagente ou uma sessão nova — para que a tarefa não carregue informação irrelevante. A Anthropic trata poluição de contexto como custo, não como detalhe.

O escopo de diretório segue essa lógica. Em um monorepo com front-end e back-end, uma tarefa exclusivamente de back-end deve começar dentro da pasta do back-end. Se a tarefa atravessa as duas camadas, aí sim o monorepo inteiro faz sentido como raiz.

## Subagentes, checkpoints e sessões nomeadas

Você pode dividir trabalho entre modelos conforme o impacto da tarefa. Planejamento e arquitetura pedem o modelo mais forte; implementação de tarefas já especificadas pode ficar com um modelo menor e mais barato, inclusive em subagentes paralelos.

O padrão que aparece na documentação é em camadas: um modelo forte produz a especificação, outro quebra em tarefas e um terceiro implementa cada item. O ganho não está no modelo mais caro, e sim em reservar capacidade para as decisões que realmente travam o projeto.

Checkpoints e sessões completam o quadro. Existe um comando de rewind para voltar a um ponto anterior de uma conversa que saiu do trilho, e existem sessões nomeáveis que preservam histórico e contexto entre retomadas. Commits no Git recuperam o código; a sessão recupera o raciocínio que levou até ele.

## Automação, revisão de código, permissões e retenção local

Para metas verificáveis de longo prazo, existe o comando de execução por objetivo: você define o alvo, como “zero erros nos testes”, e o agente continua até atingi-lo. A documentação do Claude Code trata isso na seção de automação.

A revisão de código tem arquivo próprio. Mantenha ali apenas o que diz respeito a review — o que verificar, o que ignorar, qual formato seguir — e deixe as regras gerais do projeto no `CLAUDE.md`. O inverso também vale: informação de review não deve poluir o arquivo de contexto geral.

Sobre permissões, existe um modo com menos fricção e um mecanismo de exceção para ações sensíveis, como um `git push`, que passa a exigir autorização explícita. Para execuções longas e não assistidas, a recomendação é rodar em ambiente isolado, como uma máquina virtual ou um contêiner de desenvolvimento.

Por fim, retenção de dados. As sessões ficam salvas localmente, no diretório de projetos da sua máquina, e o período padrão de limpeza é de 30 dias, ajustável nas configurações. Sessões individuais podem ser apagadas, e o conteúdo continua legível enquanto o prazo não vence.

## Como aplicar isso no seu projeto sem travar o time

Comece pelo arquivo de regras do projeto versionado no repositório. Ele é o ponto de encontro entre o time e o agente, e o lugar onde as decisões repetidas deixam de ser redigitadas em cada prompt.

Trate o [Crazystack Typescript](https://crazystack.com.br) como referência prática para transformar stack em convenção escrita, do mesmo jeito que um [Bootcamp do Dev Doido](https://crazystack.com.br) organiza o aprendizado em etapas verificáveis. É a mesma lógica de incremento testável: cada etapa precisa de um critério claro de conclusão.

Canais como o de [Gustavo Dev Doido](https://crazystack.com.br) ajudam a manter esse repertório atualizado com quem usa a ferramenta no dia a dia, mas a referência final continua sendo a documentação do fabricante.

Depois de escrever as regras, revise o que realmente importa para o seu fluxo: verificação no prompt, escopo de diretório, sessões nomeadas e permissões para ações destrutivas. Os quatro cobrem a maior parte dos acidentes comuns.

## Perguntas frequentes sobre boas práticas do Claude Code

- **O que são as boas práticas do Claude Code?** São orientações publicadas pela Anthropic documentação do produto, cobrindo verificação no prompt, incrementos testáveis, gestão de contexto, sessões, permissões e automação. Elas descrevem como estruturar a tarefa para o agente executar com menos retrabalho.

- **Devo descrever os passos ou o resultado esperado?** O resultado esperado, com restrições e critérios de verificação. A documentação recomenda descrever o estado desejado e deixar o agente localizar os arquivos, em vez de prescrever cada ação.

- **Por que usar um contexto novo para cada tarefa?** Porque contexto irrelevante reduz a precisão. Ao iniciar algo sem relação com a conversa anterior, limpe o contexto ou use um subagente para carregar apenas o que a tarefa exige.

- **Como voltar atrás depois de uma refatoração ruim?** Use o comando de rewind para retornar a um ponto anterior da conversa. O Git cobre o código, mas a sessão preserva o raciocínio que levou até aquele estado.

- **Sessões do Claude Code são salvas na nuvem?** As sessões ficam salvas localmente na sua máquina, no diretório de projetos. O período padrão de limpeza é de 30 dias e pode ser ajustado nas configurações.

- **Qual modelo usar em cada tipo de tarefa?** O modelo mais forte para planejamento, arquitetura e decisões de alto impacto. Para implementação de tarefas já especificadas, modelos menores costumam ser suficientes e saem mais baratos.

- **Existe suporte a sessões paralelas?** Sim. A documentação de fluxos de trabalho comuns cita worktrees do Git para executar sessões paralelas, com receitas de prompt próprias para esse cenário.

- **Como pedir autorização em ações sensíveis?** Configure exceções de permissão para comandos específicos, como `git push`, de modo que o agente precise pedir autorização antes de executar. Para execuções longas sem supervisão, rode em ambiente isolado.

- **Preciso nomear as ferramentas no prompt?** Não. As ferramentas do Claude Code carregam descrição própria no contexto e o agente decide quando usá-las. Basta descrever o objetivo da tarefa.

## Transforme o que você já ensina em vídeo em texto publicado

As 20 práticas deste artigo seguem o mesmo princípio: dar contexto útil a quem precisa executar. Quem grava vídeos técnicos quase sempre já tem esse material pronto em áudio — a explicação, o exemplo e o passo a passo.

O Skala Blog transforma esse material existente em artigo: você cola a URL do vídeo, a transcrição é gerada e o texto sai estruturado para revisão.

[Skala Blog](https://skalablog.com)

[Source video](https://www.youtube.com/watch?v=iMso7WbhUr0)