Claude Code não é um editor — é um agente de desenvolvimento que vive no seu terminal. Você diz o que fazer, e ele lê seu código, planeja, implementa, executa comandos, roda testes e faz commits. Este guia leva você desde a instalação até um fluxo de trabalho real.
Pré-requisitos
- Node.js 18+ instalado
- Conta Anthropic (pode autenticar com sua conta Claude ou com API key)
- Git configurado na sua máquina
- Um projeto existente com repositório git inicializado
Passo 1: Instalação
npm install -g @anthropic-ai/claude-code
Verifique a instalação:
claude --version
Navegue até seu projeto:
cd seu-projeto
claude
Na primeira vez, Claude Code pedirá para você se autenticar. Você pode usar sua conta Anthropic diretamente ou configurar uma API key.
Passo 2: Sua Primeira Sessão
Ao executar claude, você entra em um modo conversacional no terminal. Tente algo simples primeiro:
> Analise a estrutura deste projeto e me dê um resumo da
arquitetura, as dependências principais, e qualquer problema
potencial que você note.
Claude Code vai:
- Ler sua estrutura de arquivos
- Analisar package.json, configurações e arquivos-chave
- Dar um resumo organizado do projeto
Isso é útil para confirmar que Claude Code entende seu projeto antes de pedir mudanças.
Passo 3: Criar CLAUDE.md
O arquivo CLAUDE.md na raiz do seu projeto é a peça mais importante para obter bons resultados. É o equivalente às Rules do Cursor ou às custom instructions do Copilot.
Crie CLAUDE.md:
# Projeto: API de Gestão de Inventário
## Stack
- Runtime: Node.js 20 com TypeScript
- Framework: Fastify
- ORM: Drizzle com PostgreSQL
- Auth: JWT com refresh tokens
- Testing: Vitest
- Linting: Biome
## Estrutura
src/
routes/ → Rotas do Fastify organizadas por recurso
services/ → Lógica de negócio
repositories/ → Acesso a dados com Drizzle
schemas/ → Validação com Zod
middleware/ → Auth, rate limiting, logging
utils/ → Helpers compartilhados
## Convenções
- Repository pattern: routes → services → repositories
- Validação de inputs sempre na camada de routes com Zod
- Erros tipados com classes custom (AppError, ValidationError, NotFoundError)
- Nomes de variáveis e funções em inglês
- Commits em inglês seguindo Conventional Commits
- Tests junto ao arquivo que testam (arquivo.test.ts)
## Comandos
- `npm run dev` — servidor de desenvolvimento
- `npm run test` — rodar todos os testes
- `npm run test:watch` — testes em modo watch
- `npm run lint` — linting com Biome
- `npm run db:migrate` — rodar migrações
- `npm run db:generate` — gerar migrações a partir do schema
## Notas Importantes
- O banco de dados está no Supabase, não criar migrações destrutivas sem confirmação
- Os endpoints públicos precisam de rate limiting
- Nunca hardcodear secrets, sempre usar variáveis de ambiente
Claude Code lê este arquivo automaticamente ao iniciar cada sessão.
Passo 4: Fluxo de Trabalho para Implementar uma Feature
Vamos ver um fluxo completo para adicionar funcionalidade:
> Preciso adicionar um endpoint para gerenciar categorias de produtos.
Cada categoria tem: id, nome, descrição (opcional), slug
(gerado do nome), e timestamps.
Preciso:
1. Schema do Drizzle e migração
2. Repository com CRUD completo
3. Service com validação de negócio (nome único, slug único)
4. Routes: GET /categories, GET /categories/:id, POST /categories,
PUT /categories/:id, DELETE /categories/:id
5. Testes para o service
Siga os padrões existentes do projeto.
Claude Code vai:
- Ler os arquivos existentes para entender os padrões (routes, services, repositories atuais)
- Planejar a implementação
- Criar cada arquivo seguindo as convenções do projeto
- Gerar a migração de banco de dados
- Escrever os testes
Depois de implementar, você pode pedir para ele executar os testes:
> Rode os testes para verificar que tudo funciona
Claude Code executa npm run test (ou o comando que você definiu em CLAUDE.md), vê os resultados, e se houver falhas, as corrige automaticamente.
Passo 5: Comandos Essenciais
Dentro de uma sessão de Claude Code:
/compact— resume a conversa atual para liberar espaço no context window. Essencial para sessões longas./clear— limpa o histórico da conversa/cost— mostra quantos tokens você consumiu na sessão/help— lista todos os comandos disponíveis
Permissões: Claude Code pedirá permissão antes de executar comandos no terminal ou escrever arquivos. Você pode configurar permissões mais permissivas se confiar no que está fazendo:
- Pressione
Allowpara uma ação individual - Pressione
Allow alwayspara permitir esse tipo de ação no futuro
Passo 6: MCP (Model Context Protocol)
MCP permite conectar Claude Code a ferramentas externas. Configure MCP servers em ~/.claude/claude_desktop_config.json ou em .claude/settings.json do seu projeto:
{
"mcpServers": {
"supabase": {
"command": "npx",
"args": ["-y", "@supabase/mcp-server"],
"env": {
"SUPABASE_URL": "sua-url",
"SUPABASE_SERVICE_KEY": "sua-chave"
}
}
}
}
Com MCP configurado, Claude Code pode consultar seu banco de dados diretamente, ler schemas atuais e gerar código mais preciso.
Alguns MCP servers úteis:
- Supabase — acesso direto ao seu banco de dados
- GitHub — criar issues, PRs, revisar código
- Filesystem — acesso expandido a arquivos fora do projeto
- Brave Search — buscar documentação e soluções na web
Passo 7: Fluxo de Trabalho de Debugging
Claude Code é excelente para debugging. Fluxo prático:
> O endpoint POST /products está devolvendo 500 quando envio um
produto com preço decimal. Investigue o erro, identifique a
causa e corrija. Depois adicione um teste que cubra este caso.
Claude Code vai:
- Ler a rota, o service e o repository relevantes
- Identificar onde quebra (provavelmente validação de tipos ou parsing)
- Corrigir o bug
- Escrever um teste que reproduza o caso
- Executar os testes para confirmar que funciona
Passo 8: Hooks para Automação
Os hooks executam scripts antes ou depois de ações do Claude Code. Configure em .claude/settings.json:
{
"hooks": {
"afterWrite": {
"command": "npx biome check --write {{file}}"
}
}
}
Isso roda o linter automaticamente depois de cada arquivo que Claude Code escreve, garantindo que o formato sempre esteja correto.
Outros hooks úteis:
afterWrite— lint, format, validação de tiposbeforeCommit— rodar testes antes de fazer commitafterCommit— notificações, deploy preview
Erros Comuns
Não criar CLAUDE.md. Sem contexto, Claude Code gera código genérico. Com um bom CLAUDE.md, gera código que se integra naturalmente com seu projeto.
Sessões muito longas sem /compact. O context window se enche e a qualidade das respostas cai. Use /compact regularmente em sessões longas.
Não deixar que execute testes. Claude Code é mais eficaz quando pode iterar: escrever código → rodar testes → ver erros → corrigir. Se você não der permissão para executar comandos, perde essa capacidade.
Pedir muito em um único prompt. Para features grandes, divida em passos. “Primeiro crie o schema e a migração” → verifique → “Agora o repository e o service” → verifique → “Agora as routes e os testes”.
Resultado
Seu fluxo de trabalho com Claude Code:
- Você abre o terminal no seu projeto
- Claude Code lê CLAUDE.md e entende seu contexto
- Você descreve a tarefa em linguagem natural
- Ele planeja, implementa, testa e faz commit
- Você revisa as mudanças e ajusta se necessário
É como ter um desenvolvedor junior muito rápido e disponível 24/7 que segue suas convenções à risca — desde que você dê um bom CLAUDE.md.
Já usa Claude Code? Compartilhe seu CLAUDE.md e seus fluxos de trabalho. 