Ao terminar este artigo você vai saber instalar o Claude Code, preparar um projeto para ele com um arquivo CLAUDE.md, criar um subagente revisor e um hook que bloqueia edição de segredos, revisar o diff antes de aceitar qualquer mudança e estimar o custo de uso. Também verá o que não vale a pena delegar.
Um aviso sobre o que foi testado. O Claude Code exige conta, então nenhum comando dele foi executado para este artigo. As instruções vêm da documentação oficial, consultada em 09/10/2026, e cada trecho está marcado. A única parte executada de verdade foi o script de hook em Python, em container.
O que é o Claude Code
É uma ferramenta de programação que roda no terminal (e também no VS Code, em IDEs da JetBrains, no aplicativo desktop e na web). Você descreve uma tarefa em português ou inglês, ele lê os arquivos do projeto, propõe mudanças, roda comandos e pede a sua aprovação conforme o modo de permissão escolhido. O modelo faz o raciocínio, e o seu projeto e o seu terminal fazem o resto.
Isso o diferencia de um chat comum: ele age sobre os arquivos. Por isso a rotina de revisão importa mais do que em qualquer outra ferramenta de IA.
Passo 1: instale e entre
Segundo o guia de início rápido oficial, a instalação recomendada é o instalador nativo. No macOS, Linux ou WSL:
curl -fsSL https://claude.ai/install.sh | bash
No Windows PowerShell, irm https://claude.ai/install.ps1 | iex. Há alternativas: brew install --cask claude-code e winget install Anthropic.ClaudeCode. A documentação informa que o instalador nativo atualiza sozinho em segundo plano, e que Homebrew e WinGet não. Depois, abra um novo terminal e confirme:
claude --version
cd /caminho/do/seu/projeto
claude
No primeiro uso ele pede login. A documentação lista como opções uma assinatura Claude (Pro, Max, Team ou Enterprise), uma conta do Claude Console (API com créditos pré-pagos) ou um provedor de nuvem compatível. Não executado nesta redação.
Passo 2: ensine o projeto com o CLAUDE.md
Cada sessão começa com a janela de contexto vazia. O CLAUDE.md é o arquivo de instruções que o Claude Code lê no início de toda sessão. Rodar /init gera um primeiro rascunho a partir do que ele descobre no código (comandos de build, testes, convenções). Depois, você refina.
A documentação recomenda arquivos curtos, abaixo de 200 linhas, e instruções específicas e verificáveis, porque instruções longas e vagas são seguidas com menos regularidade. Um exemplo enxuto:
# Projeto loja-api
## Comandos
- Testes: `pytest -q`
- Lint: `ruff check .`
## Regras
- Python 3.12, tipagem em funções públicas.
- Nunca editar arquivos em `migrations/` já aplicados; criar uma nova migração.
- Toda mudança de comportamento precisa de teste.
- Não mexer em `.env` nem em chaves.
Um ponto importante, também da documentação: o CLAUDE.md é contexto, não regra imposta. Para impedir uma ação de forma garantida, use um hook, como no passo 4. Para preferências pessoais que não devem entrar no repositório, existe o CLAUDE.local.md, que você coloca no .gitignore.
Passo 3: uma rotina de trabalho segura
Uma rotina que funciona para tarefas pequenas e médias:
- Comece em um branch novo (
git switch -c feat/validacao-cep). O que o agente fizer fica isolado. - Peça com precisão. "Corrija o bug em que o formulário de cadastro aceita CEP vazio, e escreva um teste que falhava antes" rende mais que "melhore o cadastro". A documentação de custos faz a mesma recomendação, porque pedidos vagos disparam leituras amplas e gastam tokens.
- Em tarefas com mais de um arquivo, use o modo de plano. O
Shift+Tabalterna os modos de permissão, e o modo de plano faz o Claude Code explorar e propor uma abordagem para você aprovar antes de editar. - Dê uma forma de verificar: "rode
pytest -qe só pare quando passar". - Se ele for na direção errada, pare com
Esc. O comando/rewindvolta a conversa e o código a um ponto anterior. - Troque de assunto com
/clearpara não carregar contexto velho.
Comandos de shell úteis, conforme o guia oficial: claude "tarefa" abre uma sessão já com um pedido, claude -p "pergunta" responde uma vez e sai (útil em scripts), claude -c continua a última conversa.
Passo 4: subagentes e hooks
Um subagente é um assistente com instruções próprias e contexto separado. É útil para tarefas que geram muita saída, como rodar testes ou revisar código, porque só o resumo volta à conversa principal. Segundo a documentação, ele é um arquivo Markdown em .claude/agents/ (projeto) ou ~/.claude/agents/ (todos os projetos), com cabeçalho YAML. Só name e description são obrigatórios. Exemplo de um revisor somente leitura:
---
name: revisor
description: Revisa mudanças recentes procurando bugs, falta de testes e riscos de segurança. Use depois de editar código.
tools: Read, Glob, Grep, Bash
model: sonnet
---
Você revisa código. Rode `git diff` para ver as mudanças. Aponte, em lista curta:
1. bugs prováveis, com arquivo e linha;
2. comportamentos novos sem teste;
3. segredos, entradas sem validação e chamadas externas novas.
Não edite arquivos. Se estiver tudo certo, diga isso em uma frase.
A página de custos sugere escolher um modelo menor para subagentes simples, o que reduz a conta.
Hooks são comandos que o Claude Code executa em pontos do ciclo de uso, de forma garantida e não opcional. Ficam no .claude/settings.json do projeto. A documentação mostra, por exemplo, um hook PostToolUse com matcher Edit|Write que roda o formatador depois de cada edição. O exemplo abaixo faz o contrário: um PreToolUse que bloqueia a edição de arquivos de segredo. Na documentação, o código de saída 2 bloqueia a ação e a mensagem em stderr vai para o Claude, que pode ajustar o plano.
Salve como .claude/hooks/bloquear_segredos.py:
#!/usr/bin/env python3
"""Hook PreToolUse: bloqueia edição de arquivos de segredos (exit 2)."""
import json
import os
import sys
entrada = json.load(sys.stdin)
caminho = entrada.get("tool_input", {}).get("file_path", "")
nome = os.path.basename(caminho)
if nome == ".env" or nome.startswith(".env.") or nome.endswith((".pem", ".key")):
print(f"Bloqueado: {nome} guarda segredos. Peça ao humano para editar.", file=sys.stderr)
sys.exit(2)
sys.exit(0)
E registre em .claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/bloquear_segredos.py"
}
]
}
]
}
}
O script foi executado em container (python:3.12-slim, Python 3.12.15, 2 CPUs), alimentado com o mesmo formato de JSON que o Claude Code envia. Resultado: src/main.py saiu com código 0 (permitido), enquanto .env, .env.prod e chave.pem saíram com código 2 e a mensagem de bloqueio. O registro em settings.json e o comportamento dentro do Claude Code não foram executados, e o formato do JSON de entrada segue a documentação de hooks.
Passo 5: revise o diff como se fosse de um colega
O Claude Code pode escrever código que roda e ainda assim está errado. Antes de aceitar, faça sempre:
git status
git diff
pytest -q
Leia o diff inteiro, não só o resumo que ele escreveu. Procure estes sinais:
- Arquivos alterados que você não pediu.
- Testes enfraquecidos ou apagados para passar (um sinal clássico).
- Dependências novas no
requirements.txtoupackage.json. - Chaves, URLs internas ou dados reais dentro do código.
- Mudanças em autenticação, permissões, migrações e cobrança.
Você pode pedir uma segunda opinião ao subagente revisor, o que ajuda, mas não substitui a sua leitura. Um revisor de IA aponta problemas, e quem responde pelo código continua sendo você. Para treinar o olho para esse tipo de erro, o jogo Campo de Bugs é um bom exercício.
Limites e custos, com fonte
Segundo a documentação oficial de custos (consultada em 09/10/2026), o Claude Code cobra por consumo de tokens. Em implantações corporativas, o custo médio é de cerca de US$ 13 por desenvolvedor por dia ativo e de US$ 150 a US$ 250 por mês, e fica abaixo de US$ 30 por dia ativo para 90% dos usuários. Esses números são de empresas e variam muito com modelo, tamanho do código e uso de várias instâncias. Para estimar o seu caso, comece com um piloto pequeno.
Em planos de assinatura, a documentação descreve janelas de uso que reiniciam a cada cinco horas e semanalmente, compartilhadas com o chat. Ao atingir o limite, a mensagem diz quando renova. Ela também descreve créditos de uso para continuar além do limite do plano.
Como acompanhar e reduzir o gasto, segundo a mesma página:
- O comando
/usagemostra o consumo da sessão e, em planos, as barras de uso. O valor em dólar é uma estimativa calculada localmente. O valor oficial está na página de uso do Claude Console. /clearao trocar de tarefa, porque o contexto antigo é reenviado a cada mensagem.- Escolher o modelo conforme a tarefa com
/model. A página diz que o Sonnet resolve a maioria das tarefas de código e custa menos que o Opus. - Manter o CLAUDE.md curto e mover instruções raras para skills.
- Desconectar servidores MCP que você não usa (
/mcp). - Pedidos específicos e o modo de plano evitam retrabalho caro.
Os valores de assinatura (Pro, Max, Team) ficam na página de preços da Anthropic e mudam. Este artigo não os cita: consulte claude.com/pricing no dia em que for decidir.
O que nunca delegar
Esta lista é opinião da equipe, não regra da documentação.
- Segredos e credenciais. Não cole chaves no pedido e bloqueie arquivos
.envpor hook. - Operações destrutivas sem backup: apagar dados,
git push --force, migrações em produção. - Deploy em produção. Quem aprova é uma pessoa, com o pipeline de CI como apoio.
- Decisões de segurança, permissão e cobrança sem revisão humana linha a linha.
- Código em área que você não entende. Se não consegue explicar o diff, não aceite.
- Dados pessoais de clientes. Use dados fictícios em testes.
A regra de ouro: tudo o que o Claude Code fizer precisa poder ser desfeito e revisado. Branch, commit pequeno e testes cumprem esse papel. Para organizar o contexto que você entrega a ele, veja engenharia de contexto na prática, e para plugar suas próprias ferramentas, o artigo MCP na prática.
Resumo
- Instale pelo instalador nativo e confirme com
claude --version. - Use o CLAUDE.md curto e específico, e hooks para o que precisa ser garantido.
- Trabalhe em branch, peça com precisão, use o modo de plano e dê um jeito de verificar.
- Revise todo o diff, procurando testes enfraquecidos, dependências novas e segredos.
- Acompanhe o custo com
/usage, limpe o contexto e escolha o modelo pela tarefa.
Fontes
- Anthropic, "Quickstart" do Claude Code (instalação, login, comandos), consultado em 09/10/2026: code.claude.com/docs/en/quickstart
- Anthropic, "Manage costs effectively" (custo médio,
/usage, redução de tokens, janelas de uso), consultado em 09/10/2026: code.claude.com/docs/en/costs - Anthropic, "How Claude remembers your project" (CLAUDE.md,
/init, limite de 200 linhas), consultado em 09/10/2026: code.claude.com/docs/en/memory - Anthropic, "Subagents" (formato do arquivo e campos), consultado em 09/10/2026: code.claude.com/docs/en/sub-agents
- Anthropic, "Automate actions with hooks" (eventos, matcher, código de saída 2), consultado em 09/10/2026: code.claude.com/docs/en/hooks-guide
Versões testadas
Em 09/10/2026, o único código executado foi bloquear_segredos.py, em container python:3.12-slim (Python 3.12.15, 2 CPUs). O Claude Code não foi instalado nem executado: instalação, login, /init, modo de plano, subagente, registro de hook, /usage e /rewind estão descritos a partir da documentação oficial e do guia de início rápido, sem teste nosso.