Claude Code em Ação: guia completo para preparar o agente

Claude Code age no código, mas ele não adivinha seu projeto. Ele precisa de contexto, instruções persistentes, comandos bem escritos e limites claros para saber onde mexer, como testar e quando parar.

Este guia junta a base prática para usar Claude Code em projetos reais: como o agente executa ações, como configurar CLAUDE.md, quando criar comandos customizados, como usar Planning Mode, como controlar esforço de raciocínio e como limpar contexto durante a sessão.

1. Como o Claude age no código

Um LLM recebe texto e devolve texto. Por si só, ele não lê arquivos, não roda comandos, não acessa o sistema de arquivos e não sabe o que existe no seu repositório. Se você perguntar a um modelo puro "o que tem no arquivo auth.ts", a resposta honesta seria: não sei.

O Claude Code resolve essa limitação com tool use. O modelo não executa comandos diretamente. Ele solicita ações em um formato que o assistente entende. O assistente executa a ação real no sistema operacional e devolve o resultado para o modelo continuar raciocinando.

Você envia:
"Por que esse bug está acontecendo?"
 
O que chega ao modelo:
[sua mensagem]
[instruções: você pode solicitar Read, Bash, Write, etc.]
 
O modelo responde:
"Read: src/auth.ts"
 
Claude Code lê o arquivo de verdade,
injeta o conteúdo na conversa,
e o modelo responde com base no código real.

Na prática, isso permite encadear tarefas:

1. Ler o arquivo com o bug
2. Buscar onde a função é chamada
3. Rodar testes
4. Propor a correção
5. Aplicar a mudança
6. Validar de novo

O fluxo de qualquer tarefa segue três etapas:

Coletar contexto
  -> ler arquivos relevantes, mapear dependências
 
Formular plano
  -> decidir o que mudar, como verificar, ordem de execução
 
Agir
  -> implementar, rodar comandos, confirmar resultado

As etapas de coleta e ação dependem de tools. A etapa de plano depende do raciocínio do modelo. Quanto melhor o contexto que chega ao modelo, melhor a decisão.

2. CLAUDE.md: o prompt persistente do projeto

Sem configuração, o Claude parte do zero em cada sessão. Ele não sabe qual framework você usa, quais comandos rodam testes, quais padrões o time segue, quais arquivos são sensíveis ou quais decisões de arquitetura já foram tomadas.

O CLAUDE.md resolve isso. Ele fica na raiz do projeto e entra como contexto persistente nas sessões do Claude Code. É o contrato escrito entre você e o agente.

Para criar um rascunho inicial, abra o projeto no Claude Code e rode:

/init

O Claude analisa o codebase e gera um CLAUDE.md com arquitetura, comandos relevantes, arquivos críticos e padrões identificados. Use esse rascunho como ponto de partida. Depois corte o que for óbvio e acrescente o que o Claude não conseguiria inferir.

O critério é simples: escreva o que você diria para um dev novo antes de deixar ele mexer no projeto.

# meu-projeto
 
API de pagamentos. Node 20 + Fastify + Postgres.
 
## Comandos importantes
 
- npm run dev: sobe local na porta 3000
- npm test: roda Vitest
- npm run db:migrate: aplica migrations pendentes
 
## Convenções
 
- Validação com Zod em toda rota
- Erros de negócio usam AppError
- Testes ficam ao lado do código como *.test.ts
 
## Limites
 
- Nunca editar migrations antigas sem pedir confirmação
- Nunca commitar segredos ou chaves

Evite colocar documentação longa, lista de dependências e descrição óbvia da árvore de pastas. O arquivo inteiro custa contexto em toda sessão. Cada linha precisa pagar aluguel.

Também não coloque credenciais, tokens, chaves privadas ou qualquer segredo. Se uma informação só vale para sua máquina, use um arquivo local fora do git.

O Claude reconhece três locais comuns:

Use CLAUDE.local.md para caminhos locais e preferências individuais. Use ~/.claude/CLAUDE.md para hábitos que você quer em qualquer projeto.

Você também pode referenciar arquivos com @:

O schema do banco fica em @prisma/schema.prisma.
Consulte esse arquivo antes de alterar modelos ou queries.

Arquivos referenciados no CLAUDE.md entram como contexto quando necessário. Use isso para contratos importantes: schema, tipos globais, ADRs, regras de segurança e documentação operacional curta.

Durante a sessão, o comando abaixo abre a memória do projeto para edição:

/memory

As mudanças passam a valer a partir da próxima mensagem.

3. Comandos slash customizados

Comandos built-in como /plan, /memory e /compact cobrem operações gerais. Mas cada projeto tem rotinas próprias: revisar diff, auditar dependências, gerar testes no padrão local, preparar release, rodar checklist de PR.

Custom commands transformam esses roteiros em comandos reutilizáveis.

A estrutura é simples:

.claude/
  commands/
    audit.md
    revisar.md
    write_tests.md

O nome do arquivo vira o comando. audit.md vira /audit. O Claude Code detecta o arquivo automaticamente.

Exemplo de .claude/commands/audit.md:

Audite as dependências do projeto:
 
1. Rode npm audit para identificar vulnerabilidades conhecidas
2. Rode npm audit fix para aplicar atualizações automáticas seguras
3. Rode a suíte de testes
4. Gere um relatório com pacotes atualizados, vulnerabilidades restantes e resultado dos testes

Quando você digita /audit, o Claude recebe esse roteiro e executa a sequência. Economizar digitação é a vantagem menor. A maior é repetir o mesmo padrão toda vez, sem depender da memória.

Outro exemplo, para revisão de diff:

Revise o diff atual da branch procurando:
 
1. Bugs de lógica e casos de borda não tratados
2. Código duplicado que poderia reusar funções existentes
3. Problemas de segurança, como injeção ou dados sensíveis em log
 
Para cada achado, aponte arquivo e linha. Não mude nada ainda.

4. Argumentos com $ARGUMENTS

Use $ARGUMENTS quando o comando precisa receber um alvo variável.

Exemplo de .claude/commands/write_tests.md:

Escreva testes abrangentes para: $ARGUMENTS
 
Convenções do projeto:
- Framework: Vitest com React Testing Library
- Arquivos de teste ficam em __tests__ junto ao arquivo fonte
- Nomenclatura: [arquivo].test.ts ou [arquivo].test.tsx
- Imports usam prefixo @/
 
Cobertura obrigatória:
- Caminho principal
- Casos de borda relevantes
- Estados de erro e exceções
 
Não mocke o que pode ser testado com implementação real.

Uso:

/write_tests src/hooks/use-auth.ts

O texto depois do comando substitui $ARGUMENTS. Assim o comando já carrega o alvo e as convenções do projeto.

Crie comandos para fluxos que você repete com frequência ou que exigem lembrar regras específicas. Bons candidatos:

• Revisar diff antes de abrir PR
• Gerar testes no padrão do projeto
• Auditar dependências
• Rodar build, lint e testes numa ordem definida
• Preparar changelog ou release

Comando customizado é documentação operacional que também executa.

5. Planning Mode

Em tarefas pequenas, o Claude pode agir direto. Corrigir um typo, ajustar uma string ou renomear uma variável local não exige muita cerimônia.

Em tarefas que tocam vários arquivos, alteram contratos ou dependem de entender efeitos colaterais, planejar antes de editar reduz retrabalho.

Ative Planning Mode com:

/plan

Ou pressione Shift+Tab duas vezes no campo de entrada.

No Planning Mode, o Claude explora o codebase antes de propor mudanças. Ele lê arquivos, mapeia dependências e monta um plano de implementação. Enquanto o plano não for aprovado, ele não edita arquivos.

Quando o plano aparecer, você pode ajustar antes de executar. Ctrl+G abre o plano no editor. Use isso para remover passos desnecessários, acrescentar restrições, mudar a ordem ou corrigir uma suposição errada.

Use Planning Mode quando a tarefa envolver:

• Refatoração em múltiplos arquivos
• Mudança que toca banco, API e frontend
• Área do codebase que você ainda não conhece bem
• Alteração com risco de quebrar contrato público
• Bug cuja causa ainda não está clara

Planning Mode gasta mais contexto antes da edição para poupar tempo corrigindo mudança errada.

6. Effort level

Planning Mode controla amplitude: quantos arquivos e caminhos o Claude explora antes de agir.

Effort level controla profundidade: quanto raciocínio o modelo dedica antes de responder.

Veja ou ajuste com:

/effort

Guia prático:

Se quiser raciocínio extra só em um turno, use:

ultrathink [sua pergunta ou tarefa]

Combine Planning Mode e effort alto quando a tarefa for grande e complexa. Por exemplo: uma feature que mexe em schema, backend, frontend e testes. Planning Mode ajuda a cobrir a área afetada. Effort alto ajuda na decisão.

7. Controle de contexto durante a sessão

Sessões longas acumulam histórico. Esse histórico custa tokens e pode atrapalhar decisões novas.

Use /clear quando terminar uma tarefa e começar outra sem relação. O histórico anterior não precisa continuar entrando em cada mensagem.

/clear

Use /compact quando o Claude já aprendeu bastante sobre uma tarefa e você quer continuar em assunto relacionado, mas com menos peso no contexto.

/compact

Use /context para ver o que está ocupando espaço.

/context

Se a resposta começou no caminho errado, pressione Escape para interromper e redirecionar. Se uma parte da conversa poluiu o contexto, use Escape duas vezes ou /rewind para voltar a um ponto anterior e descartar o histórico posterior.

/rewind

Outra economia simples: aponte o arquivo certo em vez de descrever de memória.

Ruim:

tem um bug na função que calcula frete, acho que fica no service de pedido

Melhor:

corrija o cálculo de frete em src/services/pedido.ts:42.
frete grátis acima de R$200 não está aplicando.

Caminho exato reduz busca. Menos busca significa menos contexto gasto e menos chance de o agente mexer no arquivo errado.

Para exploração ampla, peça subagente quando a ferramenta oferecer esse recurso. A varredura acontece em contexto separado e só a conclusão volta para a sessão principal.

8. O pacote mínimo para um projeto sério

Se eu fosse preparar um projeto do zero para Claude Code, começaria com isto:

1. CLAUDE.md curto, com comandos, convenções e limites
2. Comando /revisar para revisar diff sem editar
3. Comando /write_tests com $ARGUMENTS
4. Regra clara sobre quando usar Planning Mode
5. Hábito de /clear, /compact e caminhos diretos

Esse conjunto já resolve a maior parte do uso diário. O Claude passa a entrar no projeto com contexto, repetir rotinas do jeito certo e pedir menos explicação a cada tarefa.

9. Próximos passos

Depois dessa base, vale avançar para:

• Hooks: scripts que rodam antes ou depois de tool calls
• MCP servers: integração com banco, APIs e serviços internos
• SDK: agentes customizados com controle maior do loop
• Agendamento: tarefas automáticas via Claude Code

Mas esses recursos só compensam quando a base está pronta. Primeiro deixe o agente entender o projeto, seguir comandos previsíveis e controlar contexto. Depois conecte ferramentas externas.

Claude Code fica melhor quando você trata o setup como parte do código. O agente não precisa de um texto enorme. Precisa de instruções curtas, exemplos bons e limites que não deixam dúvida.

@developer.israel · Claude Code em Ação · Parte 1 de 2: 9 de junho de 2026

Post no Instagram · Perfil @developer.israel