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

URL: https://agentvera.dev/pt/blog/claude-code-best-practices/ · Publicado: 2026-10-27

Boas práticas do Claude Code para projetos reais: CLAUDE.md curto, planejar antes, uma checagem para rodar, tarefas pequenas, /clear, permissões, hooks e worktrees.

**Resumo:**

- Mantenha o CLAUDE.md curto e restrito ao que o Claude não aprende pelo código: os comandos de teste, typecheck e lint, os pontos que enganam e as decisões que vivem fora do repositório.
- Dê a cada tarefa uma checagem que o Claude possa rodar: um teste, um typecheck, um build. Peça o comando e a saída como prova, e imponha as checagens obrigatórias com um hook Stop.
- Trabalhe em tarefas pequenas e específicas, use /clear entre tarefas sem relação, coloque regras rígidas em deny rules e hooks, e dê ao trabalho paralelo seu próprio git worktree.

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

| # | Prática | A versão em uma linha |
| --- | --- | --- |
| 1 | `CLAUDE.md` curto | Só comandos, armadilhas e decisões |
| 2 | Prompts específicos | Sintoma, local, como provar que foi corrigido |
| 3 | Planejar antes | Plan mode ou uma spec escrita para qualquer coisa com vários passos |
| 4 | Uma checagem para rodar | Testes, typecheck, lint; peça provas |
| 5 | Tarefas pequenas | Um objetivo por sessão, `/clear` entre tarefas |
| 6 | Regras rígidas na configuração | Deny rules, hooks, sandbox |
| 7 | Corrigir o rumo cedo | `Esc`, `/rewind` e `/clear` depois de duas correções que falharam |
| 8 | Subagentes com propósito | Trabalho paralelo e revisão nova, não por reflexo |
| 9 | Worktrees para trabalho paralelo | Um checkout por sessão |
| 10 | Revisar e fazer commit | Leia o diff, commits pequenos, o push é seu |

## 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:

```markdown
# 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](/pt/blog/claude-md-agents-md/ "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:

```text
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:

```text
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](/pt/blog/prompts-for-ai-coding-agents/ "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:

```bash
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](/pt/blog/claude-code-plan-mode/ "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`:

```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](/pt/blog/claude-code-context-window/ "Janela de contexto do 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:

```json
{
  "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:

```json
{
  "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](/pt/blog/claude-code-hooks-guide/ "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](/pt/blog/claude-code-skip-permissions/ "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`:

```markdown
---
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:

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

Mais padrões em [Subagentes do Claude Code](/pt/blog/claude-code-subagents/ "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](/pt/glossary/git-worktree/ "O que é um git worktree"):

```bash
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:

```text
.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](/pt/blog/git-worktree-parallel-agents/ "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](/pt/blog/claude-code-headless-mode/ "Modo headless do Claude Code").

## Fazendo isso com o AgentVera

A maior parte deste checklist é disciplina; o [AgentVera](/pt/agents/claude-code/ "Claude Code no AgentVera") facilita alguns itens quando você roda mais de uma sessão. Cada painel do [workspace](/pt/features/workspace/ "Workspace do AgentVera") é 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](/pt/features/agent-coordination/ "Coordenação de agentes") avisa quando dois agentes editam o mesmo arquivo.

Para o item 4, a [revisão automática de código](/pt/features/code-review/ "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](/pt/features/verify/ "AgentVera 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](/pt/features/checkpoints-and-replay/ "Checkpoints e replay de sessão") 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](/pt/download/ "Baixar 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.

## Perguntas frequentes

**Qual é o hábito mais útil no Claude Code?** Dar ao Claude um jeito de checar o próprio trabalho. Coloque os comandos exatos de teste, typecheck e lint no CLAUDE.md, cite a checagem no seu prompt e peça o comando e a saída quando o Claude disser que terminou. Sem checagem, “pronto” só significa que o Claude parou.

**Qual deve ser o tamanho do CLAUDE.md?** Curto. O Claude Code carrega o arquivo em toda sessão, então cada linha custa um pouco de atenção em toda tarefa. O guia oficial de memória recomenda ficar abaixo de 200 linhas. Rode /init para um primeiro rascunho e depois basicamente apague: mantenha comandos, armadilhas e decisões que não aparecem no código.

**Devo usar /clear ou /compact?** Use /clear entre tarefas sem relação; não custa nada e a próxima tarefa deixa de pagar pelo histórico antigo. Use /compact com um foco, como “/compact keep the API changes and the test commands”, quando quiser continuar a mesma tarefa com um histórico menor.

**É seguro deixar o Claude Code rodar comandos sem perguntar?** Em outubro de 2026, sessões interativas começam no modo auto, em que um classificador revisa ações arriscadas. Isso é um julgamento, não uma regra rígida, então tudo o que nunca pode acontecer deve ir para deny rules, hooks ou o sandbox. Shift+Tab muda para o modo Manual se você quiser aprovar cada passo.

**Como rodar várias sessões do Claude Code ao mesmo tempo sem conflitos?** Dê a cada sessão seu próprio git worktree, por exemplo com claude -w feature-auth. Cada worktree é um checkout separado na sua própria branch, então as edições não colidem. Liste arquivos ignorados pelo git, como .env, no .worktreeinclude para que sejam copiados para novos worktrees.

---

**Sobre o AgentVera.** AgentVera é um app desktop para macOS, Windows e Linux, desenvolvido pela Solviera Teknoloji. Ele roda 18 agentes de programação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) lado a lado, por projeto, em terminais reais com as instalações e logins de CLI do próprio usuário. O plano gratuito tem agentes ilimitados. Baixar: https://agentvera.dev/pt/download/ · Preços: https://agentvera.dev/pt/pricing/