Pré-requisitos
Certifique-se de ter o ambiente pronto antes de instalar o Claude Code.
Node.js 18+
node -v para verificar
npm ou yarn
npm -v ou yarn -v para verificar
Conta Anthropic ou Claude.ai Pro/Max
claude.ai ou console.anthropic.com
Instalação e primeiro uso
Instale globalmente e inicie dentro de qualquer projeto.
Instalar globalmente
npm install -g @anthropic-ai/claude-code
Iniciar no projeto
cd meu-projeto claude
Use /init no primeiro uso para o Claude analisar o repositório e criar um CLAUDE.md com o contexto do projeto.
Na primeira execução o Claude Code abre o navegador para autenticação. Conclua o login e volte ao terminal — a sessão fica salva.
Login (primeira vez ou trocar de conta)
claude auth login
Ver conta logada
claude auth status
Logout
claude auth logout
Checklist de setup
Use -p ou --print para executar uma tarefa e sair, sem abrir o terminal interativo. Ideal para scripts e pipelines de CI.
Tarefa direta
claude -p "explique a estrutura do projeto"
Com arquivo específico
claude -p "refatore esse componente para Composition API" src/components/Modal.vue
Headless / scripts de CI
claude --print "liste todos os componentes sem prop validation"
Casos de uso
O que o Claude Code faz na prática dentro de um repositório.
Desenvolvimento de features
- Implementar feature do zero a partir de uma descrição
- Criar componentes com props, emits e composables alinhados ao projeto
- Integrar APIs com services, tipagens e tratamento de erro no padrão
- Gerar migrations e schemas alinhados com as entidades existentes
Debug e qualidade
- Investigar bugs sem precisar explicar o projeto inteiro
- Escrever testes unitários e de integração no padrão do projeto
- Revisar antes do PR: segurança, performance e legibilidade
- Corrigir falhas de build a partir do erro
Refatoração e manutenção
- Refatorar componentes legados para Composition API e TypeScript
- Extrair lógica duplicada em composables e utils reutilizáveis
- Migrar dependências com guia passo a passo para breaking changes
- Limpar código morto: imports, variáveis e funções não usadas
Documentação
- Documentar componentes: props, slots, eventos e exemplos
- Escrever CHANGELOG a partir do histórico de commits ou diff
- Criar README com setup, arquitetura, scripts e convenções
- Guia de onboarding técnico para novos devs
Para times mistos: negócio usa o Claude Chat para estruturar a demanda (PRD, regras, casos de uso) e o dev usa o Claude Code para transformar isso em implementação.
Modos de operação
Balanceie autonomia e segurança trocando o modo a qualquer momento com Shift + Tab.
Pede confirmação antes de editar arquivos, rodar comandos ou fazer requisições.
Explorando um projeto novo ou trabalhando em código crítico.
Edições em arquivos aplicadas sem confirmação. Comandos bash continuam pedindo autorização.
Refatorações em que você confia no plano e revisa depois pelo diff.
Só lê e propõe um plano. Nenhuma edição é executada até você aprovar.
Antes de tarefas complexas, para validar a abordagem antes de gastar tokens.
Nenhuma permissão é pedida. Qualquer ação é executada direto, com risco alto.
APENAS em ambientes isolados (container, sandbox, CI). Nunca com credenciais reais.
Sempre use Plan Mode antes de pedir mudanças grandes. O Claude mostra o que vai fazer e você pode corrigir antes de executar — evita refazer trabalho.
Tools disponíveis
O que o Claude efetivamente faz para executar tarefas. Em cada modo, algumas tools pedem confirmação ou ficam bloqueadas.
ReadLê arquivos do disco (texto, imagens, PDFs, notebooks)WriteCria novos arquivos ou sobrescreve existentesEditEdita arquivos existentes por substituição exata de textoNotebookEditEdita células de notebooks Jupyter (.ipynb)GlobEncontra arquivos por padrão (ex: src/**/*.ts)GrepBusca conteúdo em arquivos com regex (usa ripgrep)BashExecuta comandos shell (git, npm, build, testes)BashOutputLê a saída de comandos rodando em backgroundKillShellEncerra um shell em execuçãoWebFetchBusca o conteúdo de uma URL específicaWebSearchFaz busca na web por palavras-chaveAgent / TaskDelega trabalho a subagents (pesquisa, revisão, planejamento)TaskCreate / TaskUpdateCria e gerencia a lista de tarefas da sessãoSkillInvoca skills customizadas do projeto ou do usuárioComandos da sessão
Comandos começam com / e controlam a sessão. Digite / em qualquer mensagem para ver a lista completa.
Sessão
/helpLista os comandos disponíveis na sessão atual/clearZera a conversa atual (arquivos e memória permanecem)/compactResume a conversa para liberar contexto, preservando o essencial/costMostra o uso de tokens e custo da sessão/modelTroca o modelo em uso (Opus, Sonnet, Haiku)Configuração do projeto
/initAnalisa o repositório e cria um CLAUDE.md com o contexto/configAbre as configurações do Claude Code/permissionsGerencia quais ferramentas têm permissão automáticaExtensões
/agentsLista, cria ou edita subagents personalizados/mcpGerencia servidores MCP conectados (autenticação e status)/reviewFaz review de uma branch ou PR/loopAgenda execução recorrente de um prompt (ex: /loop 5m /task)Aplicando no dia a dia
Duas visões do Claude Code no projeto: quem está chegando agora e quem já está dentro do fluxo.
Projeto novo ou existente — da instalação às primeiras tarefas
Instalar globalmente (se ainda não tiver)
npm install -g @anthropic-ai/claude-code
Abrir no projeto
cd meu-projeto claude
Inicializar com /init
/init
O Claude analisa o repositório e cria o CLAUDE.md com contexto, stack e convenções do projeto.
Explorar a base de código
Primeira tarefa real
Recomendado: use Plan Mode na primeira tarefa para revisar a abordagem antes de executar.
Com o projeto rodando — planejamento, automação e controle
- Default → exploração e tarefas curtas: pede confirmação a cada passo, ideal para código crítico
- Plan Mode → tarefas complexas: aprove o plano antes de qualquer execução
- Accept Edits → refatorações confiantes: aplica sem confirmação, você revisa depois pelo diff
- Fluxo natural: Default para explorar → Plan Mode antes de tarefas grandes → Accept Edits quando confiar no plano
- Skills: crie para tarefas com passos fixos (/commit-padrao, /review-branch)
- Slash commands: crie para fluxos complexos (/auditoria, /release, /deploy)
- Ficam commitados no repo e disponíveis para o time inteiro — sem re-explicar
- /compact — libera contexto sem perder o fio da tarefa
- /cost — monitora tokens e controla o uso da sessão
- /clear — reinicia quando o contexto foi contaminado ou a tarefa mudou
- /model — troca o modelo quando precisar de mais velocidade ou qualidade
CLAUDE.md é o ponto de partida de cada sessão. Mantenha atualizado com convenções, arquivos que não deve tocar e padrões de commit.
Skills: reutilize padrões do time
Agrupe instruções numa skill e o Claude carrega sob demanda. Você não re-explica, ela vale em qualquer sessão.
Quando usar
- Tarefas com passos fixos: commits, revisão de branch, rollout de feature
- Padrões de escrita do time: formato de PR, estrutura de relatório
- Regras específicas do projeto que o Claude precisaria reaprender a cada chat
Como fazer
- 1Crie
.claude/skills/<nome>/SKILL.mdna raiz do projeto - 2Adicione frontmatter com
nameedescription(obrigatórios) - 3Opcional: restrinja ferramentas com
allowed-tools - 4Escreva as instruções no corpo em markdown
- 5Invoque com
/nome-da-skill
--- name: commit-padrao description: Cria um commit seguindo o padrão do time disable-model-invocation: true allowed-tools: Bash(git *) --- # Commit padrão Formato: [branch-name] type: descrição curta ## Regras 1. Detectar branch com `git branch --show-current` 2. Usar nome da branch como scope entre colchetes 3. Type convencional: feat, fix, chore, refactor, docs, test 4. Descrição em português, uma linha 5. NUNCA adicionar co-author ou menção a IA
Arquivos de memória
Mantenha o contexto do projeto entre conversas sem precisar repetir tudo.
Quando usar
- Onboarding: o Claude precisa conhecer stack, convenções e arquivos-chave
- Decisões arquiteturais: razões por trás de escolhas que não ficam óbvias no código
- Preferências pessoais: tom de resposta, nível de detalhe, formato preferido
Como fazer
- 1CLAUDE.md na raiz: documentação compartilhada, commitada no repo, lida automaticamente ao iniciar
- 2Memória automática: o Claude aprende sobre você e o projeto ao longo do tempo
- 3Use CLAUDE.md para contexto do time e memória automática para preferências individuais
- 4Para forçar: "guarde isso na memória" ou "não esqueça X"
# Contexto do projeto ## Stack - [framework principal + versão] - [lib de UI / design system] - [banco / autenticação] - [lib de testes] ## Convenções - [padrão de nomenclatura] - [idioma dos textos de UI] - [regras de tipagem, props, emits] ## O que NÃO alterar sem aprovação - [arquivos ou pastas críticas] - [arquivos de configuração] ## Padrões de commit [formato que o time usa] Types: feat, fix, chore, refactor, docs, test
Slash commands customizados
Crie atalhos para fluxos complexos, commitados no repo e disponíveis para todo o time.
Quando usar
- Workflows com múltiplos passos repetidos: deploy, auditoria, release
- Comandos com formato fixo que aceitam argumentos variáveis
- Rotinas do time que valem ser padronizadas e versionadas
Como fazer
- 1Crie
.claude/commands/<nome>.md - 2Frontmatter opcional:
descriptioneallowed-tools - 3Escreva as instruções em markdown no corpo
- 4Use
$ARGUMENTSpara capturar o que vem depois do comando - 5Invoque com
/nome-do-comando <argumentos>
--- description: Revisa a branch atual antes de abrir PR allowed-tools: Bash(git *), Bash(npm *) --- # Revisar branch 1. Rode `git diff main...HEAD` 2. Rode `npm run lint` e corrija erros 3. Identifique: console.log, tokens hardcoded, credenciais expostas 4. Valide: nomenclatura, imports não usados 5. Relatório: aprovado/reprovado + sugestões Se argumento passado, foque na pasta: $ARGUMENTS
Boas práticas
O que fazer e o que evitar para tirar o máximo do Claude Code com segurança.
- Revise sempre antes de aplicar — você é responsável pelo código
- Peça o plano primeiro em tarefas grandes
- Seja específico sobre o que pode e não pode mudar
- Crie um CLAUDE.md na raiz com contexto do projeto
- Aplicar sem ler, especialmente em refatorações grandes
- Pedidos vagos: "melhora o projeto" não tem escopo
- Ignorar arquivos tocados: o Claude pode modificar mais do esperado
- Mergear sem entender: se o Claude entregou, entenda o que foi feito
Segurança: o Claude Code pode ler e escrever arquivos localmente. Use sempre em branches de feature, nunca diretamente na main.
Prompts prontos
Copie, adapte e use. Prompts testados para as situações mais comuns.
Implemente a feature de [descrição]. Comportamento esperado: - [caso 1] - [caso 2] Siga os padrões já usados no projeto para [componentes/services/composables]. Não altere arquivos fora do escopo. Ao final, liste o que foi criado ou modificado.
Estou recebendo o erro: [cole o erro completo] - Onde acontece: [página / componente / endpoint] - Quando acontece: [ação que dispara] - O que já tentei: [se tentou algo] Encontre a causa raiz, explique o problema e corrija. Não altere lógica não relacionada ao bug.
Faça um code review dos arquivos modificados nesta branch. Aponte: 1. Problemas de lógica ou bugs potenciais 2. Riscos de performance ou segurança 3. Violações de padrão do projeto 4. Oportunidades de simplificação 5. O que está bem feito Seja específico: arquivo, linha e sugestão.
Refatore o componente [nome] para: - Composition API com <script setup> - Tipagem TypeScript - Extrair lógica reutilizável para composable se fizer sentido - Manter exatamente o mesmo comportamento externo Antes de alterar, mostre o plano de refatoração para eu aprovar.