Guia para Configurar o Claude Code para Programação Agentic de Alta Performance

Por que isso importa agora

A maioria das pessoas instala o Claude Code, digita um prompt, recebe algo útil e nunca mais abre um arquivo de configuração. Semanas depois, as sessões começam a perder o fio da meada, o mesmo pedido de permissão aparece cinquenta vezes por dia, e cada tarefa longa termina do mesmo jeito: uma parede de avisos de contexto e uma conversa que precisa ser abandonada e reiniciada do zero.

Nada disso é limitação do modelo. É limitação da configuração. O Claude Code vem com padrões sensatos, mas padrões sensatos e alta performance são critérios diferentes — e a diferença entre eles está em um punhado de arquivos que a maioria dos iniciantes nunca abre.

Instalação correta do Claude Code

O Claude Code é instalado como uma CLI independente. O caminho recomendado atual é o instalador nativo, embora o npm ainda funcione como alternativa:

# macOS, Linux ou WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Ou via npm
npm install -g @anthropic-ai/claude-code

Depois de instalar, entre no diretório do seu projeto antes de rodar claude pela primeira vez. O Claude Code define o escopo da memória e das configurações pelo diretório de lançamento — começar da home ou do desktop significa que ele nunca captura o contexto certo.

O primeiro acesso autentica via OAuth (assinatura Pro, Max ou Team) ou chave de API do Console. Além do terminal, o Claude Code está disponível como extensão do VS Code, plugin do JetBrains, app desktop e versão web em claude.ai.

Os três arquivos que realmente importam

O Claude Code lê configurações de dois lugares: o diretório .claude/ do projeto (e um CLAUDE.md na raiz) e o diretório global ~/.claude/.

1. CLAUDE.md — memória do projeto: notas de arquitetura, comandos de build e teste, regras de estilo. Rode /init em um projeto novo e refine com /memory. Mantenha enxuto (até ~2.500 tokens) e jogue regras longas em .claude/rules/*.md.
2. settings.json — Permissões, hooks, variáveis de ambiente e modelo padrão. É o arquivo que resolve as duas queixas mais comuns: interrupções constantes de permissão e o modelo mais caro sendo usado para tarefas simples.
3. Auto memory — camada mais recente: o Claude escreve e lê notas de trabalho automaticamente. Controlado por autoMemoryEnabled ou pela variável CLAUDE_CODE_DISABLE_AUTO_MEMORY.

A regra prática: regras estáveis vão no CLAUDE.md, porque instruções que só existem no histórico da conversa desaparecem quando uma sessão longa dispara compactação automática.

Configurando permissões e hooks antes de precisar

O Claude Code roda em três modos (alterne com Shift+Tab): Default (pergunta antes de cada ação), Auto-Accept Edits (edições de arquivo sem prompt) e Plan Mode (somente leitura até você aprovar).

Use o settings.json para regras de permissão:

{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Read(**)"
    ],
    "ask": ["Bash(git push:*)"],
    "deny": [
      "Bash(rm -rf /*)",
      "Bash(sudo:*)",
      "Read(.env)"
    ]
  }
}

A ordem importa: deny sempre vence, mesmo que um allow mais amplo cubra o comando. Isso permite conceder acesso amplo de leitura e testes sem abrir porta para comandos destrutivos.

Hooks vão além: um PostToolUse pode formatar automaticamente todo arquivo que o Claude editar com Prettier, e um PreToolUse pode inspecionar o comando antes da execução e bloqueá-lo se corresponder a padrões perigosos (rm -rf, sudo rm, chmod 777).

Comandos que valem a pena aprender primeiro

Para iniciantes, domine /compact, /plan e /diff primeiro. Esses três resolvem a maioria das frustrações iniciais: degradação por excesso de contexto, edições que vão além do necessário e não saber o que mudou.

Criando seu próprio comando /truth

Comandos personalizados são definidos como skills — uma pasta com SKILL.md. Crie em .claude/skills/truth/SKILL.md:

---
description: Verifica claims recentes contra o código real
allowed-tools: Read, Grep, Glob, Bash(git diff:*)
---

Reexamine tudo que você me disse nesta conversa contra o que
realmente existe no código agora:
1. Para cada arquivo que você afirma ter editado, releia e confirme.
2. Para cada claim sobre código existente, verifique no arquivo real.
3. Rode `git diff` e compare o diff real com o que você descreveu.
4. Reporte claramente: quais claims bateram, quais não, e qual a discrepância.

Depois de salvo, /truth fica disponível em qualquer sessão do projeto. Rode após tarefas multi-arquivo e antes de commitar baseado no que o Claude disse.

Usando subagentes para ganho real de velocidade

Subagentes são instâncias especializadas com janela de contexto própria, prompt de sistema e permissões isoladas. A documentação da Anthropic os descreve como rodando isolados da sessão principal, retornando apenas um resumo. Essa isolação é o ganho real: exploração de código, auditoria de dependências e escrita de testes são trabalhos verbosos que consumiriam o orçamento de contexto da sessão principal.

Rode /agents para abrir o menu interativo ou defina subagentes em .claude/agents/<nome>.md. Um padrão inicial comum é um revisor de código ou executor de testes com acesso somente leitura.

Templates para começar

CLAUDE.md inicial:

# Project Context
## Stack
- [Sua linguagem/framework]
## Commands
- Test: `npm test`
- Lint: `npm run lint`
## Conventions
- [Regras de estilo, nomenclatura, estrutura]
## Before finishing any task
- Execute a suíte de testes e confirme que passa
- Rode /truth se a tarefa envolveu mais de um arquivo

.claude/settings.json inicial (com permissões sensatas + bloqueio de comandos perigosos + formatação automática):

{
  "permissions": {
    "allow": ["Bash(npm test:*)", "Bash(npm run lint:*)", "Read(**)"],
    "ask": ["Bash(git push:*)"],
    "deny": ["Bash(rm -rf /*)", "Bash(sudo:*)", "Read(.env)"]
  },
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{"type": "command", "command": "python3 .claude/hooks/block-dangerous-bash.py"}]
    }],
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{"type": "command", "command": "npx prettier --write "$CLAUDE_TOOL_INPUT_FILE_PATH""}]
    }]
  }
}

Conclusão

A diferença entre uma configuração iniciante e uma de alta performance no Claude Code não é um recurso secreto ou comando oculto — são 20 minutos investidos no CLAUDE.md, settings.json e um ou dois hooks antes de mergulhar no trabalho real. Tudo neste guia existe para remover atritos que você enfrentaria repetidamente. Configure uma vez, faça commit no repositório, e toda sessão futura começa de uma base mais forte que a anterior.