Boas práticas do Claude Code: um checklist prático

As boas práticas do Claude Code que mais importam são simples: mantenha o CLAUDE.md curto, planeje antes de mudanças grandes, dê ao Claude uma checagem que ele possa rodar, trabalhe em tarefas pequenas, limpe o contexto entre elas, imponha regras rígidas com configuração em vez de texto e rode trabalho paralelo em git worktrees separados. Depois leia o diff e faça commits com frequência.

Esta página é um checklist. Cada item diz o que fazer, mostra o comando ou a configuração e aponta para um guia mais detalhado quando existe. Tudo aqui segue a documentação oficial do Claude Code de outubro de 2026; detalhes que mudam entre versões estão sinalizados.

O checklist em resumo

1. Mantenha o CLAUDE.md curto e objetivo

O Claude Code carrega o CLAUDE.md em toda sessão, então cada linha nele toma um pouco de atenção em toda tarefa, relevante ou não. O arquivo funciona melhor quando guarda só o que o Claude não consegue deduzir pelo código:

• Como confirmar o trabalho neste repositório: os comandos exatos de teste, typecheck e lint, e como rodar um único arquivo de teste.
• Lugares onde o código engana: um padrão antigo que código novo não deve copiar, um diretório que parece morto mas não está.
• Decisões que não estão no repositório: qual helper de erro a equipe escolheu, como funcionam os deploys.
• Qualquer coisa que você já teve que corrigir duas vezes.

Um arquivo que passa nesse teste fica pequeno:

# Commands
- Install: pnpm install
- Run one test file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm tsc --noEmit

# Conventions
- Use the error helpers in src/lib/errors.ts, never throw raw strings
- src/legacy/ is still live but don't copy its patterns into new code

# Gotchas
- Integration tests need DATABASE_URL set, see .env.example

Você não precisa descrever sua arquitetura ou a estrutura de pastas; o Claude lê o repositório. O /init escreve um primeiro rascunho e, a partir daí, o trabalho é basicamente apagar. O guia oficial de memória recomenda ficar abaixo de 200 linhas. O /context confirma que o arquivo foi carregado, e o /doctor sugere cortes. Preferências pessoais vão no CLAUDE.local.md, que você adiciona ao .gitignore.

Duas ferramentas relacionadas mantêm o arquivo principal enxuto. Regras que só importam em uma área vão em .claude/rules/*.md com um filtro paths:, para carregarem só quando o Claude trabalha ali. Procedimentos da equipe, como um checklist de release, vão em uma skill em .claude/skills/<name>/SKILL.md; o Claude só vê o nome e a descrição até precisar do texto completo. O passo a passo completo está em Como escrever CLAUDE.md e AGENTS.md.

Se o Claude continua ignorando uma linha, escrever IMPORTANT em maiúsculas raramente ajuda. Ou o arquivo está longo demais, ou a linha é uma regra sem exceções, e o lugar dela é um hook (veja o item 6).

2. Escreva prompts que digam onde, o quê e como checar

Um prompt vago faz o Claude adivinhar. Um específico cita o sintoma, onde procurar e como provar a correção:

Users report that login fails after the session times out. Look at the token refresh in src/auth/, write a failing test that reproduces it, then fix it.

Aponte arquivos com @, cole screenshots e mande logs por pipe em vez de descrevê-los. Quando você ainda não sabe o que quer, deixe o Claude te entrevistar primeiro:

I want to add rate limiting to the public API but haven't thought it through yet. Interview me until you could write the spec, then write it to SPEC.md.

Depois abra uma sessão nova que construa a partir do SPEC.md. O build começa com um contexto limpo e uma definição escrita de pronto, e a spec é o que o revisor usa como referência depois. Mais padrões de prompt em Como escrever prompts para agentes de código com IA.

Dois hábitos que você pode abandonar: frases como “think hard” não aumentam o esforço de raciocínio (use /effort high ou coloque ultrathink em um único prompt), e ênfase em CAIXA ALTA geralmente faz o Claude aplicar a regra em excesso.

3. Planeje antes de mudanças com vários passos

Para qualquer coisa que mexa em vários arquivos, separe pensar de editar. O plan mode deixa o Claude ler o código e propor um plano sem mudar nada. Você pode entrar nele com Shift+Tab ou começar uma sessão já nele:

claude --permission-mode plan

Leia o plano, corrija e só então deixe o Claude construir. Uma suposição errada pega no plano custa uma mensagem; pega no diff, custa uma reescrita. Correções pequenas e óbvias não precisam de plano. Os detalhes, incluindo como editar um plano antes de aprová-lo, estão em Plan mode do Claude Code.

4. Dê ao Claude uma checagem que ele possa rodar

Este é o hábito com o maior retorno. O Claude só sabe que terminou se tiver algo para rodar: uma suíte de testes, um typecheck, um comando de lint, o exit code de um build, um script que compara a saída com uma fixture. Se o seu repositório tem um, a linha mais útil do CLAUDE.md é o comando que o executa.

Você escolhe o quanto a checagem é rígida:

• No prompt. “Run the auth tests after, and keep going until they pass.” Funciona para qualquer tarefa, sem configuração.
• Como objetivo. /goal all tests in tests/auth pass and lint is clean define uma condição que um modelo separado verifica depois de cada turno. Mais útil em execuções longas.
• Como hook Stop. O Claude Code roda seu script quando o Claude tenta encerrar o turno e o manda de volta se o script sair com código 2.
• Com um revisor independente. O /code-review revisa o diff em um subagente novo que nunca viu sua conversa.

A versão em hook Stop de “o typecheck precisa passar” fica em .claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "pnpm tsc --noEmit 1>&2 || exit 2" }
        ]
      }
    ]
  }
}

O stderr volta para o Claude como o motivo de ele ainda não poder parar, por isso a saída do compilador é redirecionada para lá. Se o hook bloquear oito paradas seguidas sem nenhuma chamada de ferramenta no meio, o Claude Code encerra o turno mesmo assim; CLAUDE_CODE_STOP_HOOK_BLOCK_CAP aumenta esse limite.

Seja qual for a escolha, peça provas: o comando que o Claude rodou e a saída. “All tests pass” sozinho diz pouco. Depois de uma mudança de UI, o /verify faz o Claude buildar e rodar o app e olhar o resultado.

5. Mantenha as tarefas pequenas e o contexto limpo

Uma sessão, um objetivo. Uma conversa que acumulou três tarefas sem relação reenvia todas elas a cada turno da quarta, o que custa mais e deixa as respostas menos focadas.

• /clear entre tarefas sem relação. /clear oauth-migration também dá nome à sessão que você está deixando, para poder voltar a ela.
• /compact keep the API changes and the test commands encurta uma sessão longa mantendo o que importa. Em uma sessão longa, o próprio /compact é uma requisição grande.
• /usage mostra para onde vai seu uso, incluindo por subagente, skill e servidor MCP nos planos de assinatura.

Em outubro de 2026, a maioria dos modelos atuais tem uma janela de 1M de tokens e a compactação roda sozinha, então ficar sem contexto é raro. Limpar é questão de foco e custo, não de sobrevivência. O cache de prompt dura cerca de uma hora em uma assinatura e cerca de cinco minutos com uma API key, então uma sessão que ficou parada durante o almoço sai mais cara para continuar do que uma nova. A mecânica está em Gerenciamento de contexto no Claude Code.

6. Coloque as regras que não podem ceder na configuração

O CLAUDE.md guarda diretrizes, e o Claude pode decidir que uma diretriz não se aplica. Para as poucas regras em que “quase sempre” não basta, use controles que o próprio Claude Code aplica.

Regras de permissão. Permita o que é seguro e frequente, pergunte o que é arriscado, negue o que nunca pode acontecer:

{
  "permissions": {
    "allow": ["Bash(pnpm tsc --noEmit)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./.env.local)", "Read(./secrets/**)"]
  }
}

Deny rules valem em todos os modos de permissão, e a regra Read também pega comandos de shell comuns para ler arquivos, como cat .env. Ela não pega um script que abre o arquivo, então, para trabalho sensível em segurança, ative também o sandbox com /sandbox, que confina comandos de shell no nível do sistema operacional no macOS, Linux e WSL2.

Hooks. Um formatador que roda depois de toda edição deixa de depender da memória do Claude:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write --ignore-unknown \"$(jq -r '.tool_input.file_path')\"" }
        ]
      }
    ]
  }
}

Use hooks só para regras com zero exceções; “prefira named exports” fica no CLAUDE.md. O guia de hooks do Claude Code cobre todos os eventos e exit codes.

Modos de permissão. Em outubro de 2026, novas sessões interativas começam no modo auto, em que um classificador revisa ações arriscadas em vez de te perguntar a cada uma. Ele é bom, mas é um julgamento, então suas regras de “nunca” continuam pertencendo a deny rules e hooks. Se preferir aprovar cada passo, Shift+Tab alterna para Manual, ou comece com claude --permission-mode manual. Quando o Manual pergunta demais, /fewer-permission-prompts adiciona seus comandos somente leitura mais comuns a uma allowlist. Por que pular as permissões por completo é uma troca ruim está em Claude Code skip permissions.

7. Corrija o rumo cedo e recomece em vez de discutir

Observe o primeiro minuto de uma tarefa. Os controles são poucos:

• Esc para o Claude no meio de uma ação e mantém tudo até ali, para você redirecionar.
• /rewind, ou Esc duas vezes com o prompt vazio, volta o código, a conversa ou os dois para um prompt anterior.
• /clear começa de novo. Depois de duas correções que falharam, uma terceira geralmente só adiciona outra tentativa falha para o Claude reler. Limpe e escreva um prompt melhor que inclua o que você aprendeu.

Os checkpoints cobrem arquivos que o Claude mudou com suas próprias ferramentas de edição; um arquivo que só um comando Bash tocou não é restaurado. Eles funcionam junto com o git, não no lugar dele. Para trabalhos que duram dias, /rename oauth-migration dá nome à sessão e claude --resume oauth-migration a retoma depois.

8. Use subagentes com propósito

O Claude Code já delega por conta própria: buscas amplas vão para o agente Explore embutido, e subagentes rodam em segundo plano por padrão. Cada subagente envia suas próprias requisições, então custa tokens, e não deixa a resposta mais inteligente. Use-os para:

• Partes independentes do trabalho que podem rodar ao mesmo tempo.
• Manter saídas longas, como uma execução completa de testes, fora da conversa principal.
• Um revisor que não viu como o código foi escrito.
• Uma tarefa que deve ter menos ferramentas que a sessão principal.

Um revisor somente leitura é um arquivo curto em .claude/agents/reviewer.md:

---
name: reviewer
description: Reviews changed files against the spec they were built from. Use after implementing a feature, before opening the PR.
tools: Read, Grep, Glob
---
You're reviewing code you didn't write. Compare the changed files against the spec you're given,
check that every requirement is implemented and the listed edge cases have tests,
and report only the gaps that affect correctness. Skip style.

Para tarefas simples, como juntar os arquivos que importam um módulo, adicione model: haiku à definição. Depois peça:

Have the reviewer compare the rate limiter against SPEC.md.

Mais padrões em Subagentes do Claude Code.

9. Rode trabalho paralelo em worktrees

Duas sessões editando o mesmo checkout vão sobrescrever uma à outra. Dê a cada uma seu próprio git worktree:

claude -w feature-auth

Um worktree é um checkout novo, então arquivos ignorados pelo git, como .env, não estão lá e as dependências não estão instaladas. Liste arquivos pequenos ignorados pelo git em .worktreeinclude na raiz do repositório e o Claude Code os copia para todo worktree que criar:

.env
.env.local
config/dev-credentials.json

Não coloque node_modules ali; ele copia em vez de criar link. Mantenha o comando de instalação no CLAUDE.md, ou use a configuração worktree.symlinkDirectories. Quando você sai de uma sessão de worktree sem nome e sem mudanças, o Claude Code a remove; caso contrário, ele pergunta. Para uma mudança mecânica grande, o /batch divide o trabalho em unidades, roda cada uma no seu próprio worktree e abre um PR por unidade. Mais em Git worktrees para agentes em paralelo.

10. Leia o diff, faça commits pequenos, o push é seu

O agente escreve; você aprova. Antes de aceitar um turno, leia o git diff, não o resumo. Faça commit depois de cada passo que funciona, assim um próximo passo ruim fica a um git reset de distância. Deixe pushes, merges e deploys nas mãos de uma pessoa: a regra ask em git push * acima faz exatamente isso. Uma segunda sessão que revisa @src/middleware/rateLimiter.ts sem ter visto ele ser escrito é o revisor independente mais barato que você tem.

Bônus: antes de deixar o Claude sozinho

A documentação oficial lista cinco perguntas para qualquer execução que ninguém está acompanhando. Elas são uma boa checagem final:

1. Ele sabe como é o “pronto”? Um objetivo, um arquivo de spec, um teste falhando.
2. Ele consegue checar o próprio trabalho? Testes, um hook Stop, uma etapa de revisão.
3. No que ele pode mexer? Regras de permissão, dontAsk, o sandbox, um worktree.
4. O que o faz parar? --max-turns, --max-budget-usd, um limite de gastos.
5. Para onde vai o resultado e quem aprova? Um PR e uma pessoa aprovando o merge.

Para execuções por script e em CI, veja Modo headless do Claude Code.

Fazendo isso com o AgentVera

A maior parte deste checklist é disciplina; o AgentVera facilita alguns itens quando você roda mais de uma sessão. Cada painel do workspace é o terminal real do Claude Code, então Shift+Tab, plan mode, hooks e seu CLAUDE.md funcionam como sempre. Você pode criar um worktree por agente pelo painel Git, e a coordenação de agentes avisa quando dois agentes editam o mesmo arquivo.

Para o item 4, a revisão automática de código faz um modelo Claude que você escolhe revisar as mudanças de cada turno e listar os achados com severidade e arquivo:linha, e pode mandá-los de volta para o agente. O Verify (Pro e Team) transforma sua mensagem em critérios de aceitação e faz um verificador separado checá-los com provas quando o turno termina. Para o item 7, os checkpoints tiram um snapshot de cada turno em uma ref git oculta e guardam os últimos 60 por agente. Grade, worktrees, revisão de código e checkpoints estão no plano gratuito; baixe o AgentVera para experimentar.

Concluindo

Se você adotar só três itens, fique com estes: um CLAUDE.md curto com seus comandos reais, uma checagem que o Claude roda antes de dizer “pronto” e /clear entre tarefas. Adicione deny rules e hooks para o que nunca pode acontecer, worktrees quando passar a rodar sessões em paralelo, e guarde para você a revisão final e o push.