Desenvolvedores

Claude Code

Guia para desenvolvedores — Roadmap de uso

Do primeiro comando ao fluxo de trabalho no dia a dia. Siga o roadmap e comece a usar o Claude Code no seu projeto.

Por Larissa Santos · Web Developer

claude — terminal
Claude Code · pronto
>▋
01

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

02

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

Modo prompt direto (sem sessão interativa)

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"
03

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.

04

Modos de operação

Balanceie autonomia e segurança trocando o modo a qualquer momento com Shift + Tab.

Default
padrão ao iniciar

Pede confirmação antes de editar arquivos, rodar comandos ou fazer requisições.

Explorando um projeto novo ou trabalhando em código crítico.

Accept Edits
Shift + Tab (1×)

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.

Plan Mode
Shift + Tab (2×)

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.

Bypass Permissions
--dangerously-skip-permissions

Nenhuma permissão é pedida. Qualquer ação é executada direto, com risco alto.

APENAS em ambientes isolados (container, sandbox, CI). Nunca com credenciais reais.

PRO

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.

05

Tools disponíveis

O que o Claude efetivamente faz para executar tarefas. Em cada modo, algumas tools pedem confirmação ou ficam bloqueadas.

Arquivos
ReadLê arquivos do disco (texto, imagens, PDFs, notebooks)
WriteCria novos arquivos ou sobrescreve existentes
EditEdita arquivos existentes por substituição exata de texto
NotebookEditEdita células de notebooks Jupyter (.ipynb)
Busca
GlobEncontra arquivos por padrão (ex: src/**/*.ts)
GrepBusca conteúdo em arquivos com regex (usa ripgrep)
Execução
BashExecuta comandos shell (git, npm, build, testes)
BashOutputLê a saída de comandos rodando em background
KillShellEncerra um shell em execução
Web
WebFetchBusca o conteúdo de uma URL específica
WebSearchFaz busca na web por palavras-chave
Orquestração
Agent / TaskDelega trabalho a subagents (pesquisa, revisão, planejamento)
TaskCreate / TaskUpdateCria e gerencia a lista de tarefas da sessão
SkillInvoca skills customizadas do projeto ou do usuário
06

Comandos 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ática

Extensõ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)
07

Aplicando no dia a dia

Duas visões do Claude Code no projeto: quem está chegando agora e quem já está dentro do fluxo.

Integrando ao projeto

Projeto novo ou existente — da instalação às primeiras tarefas

1

Instalar globalmente (se ainda não tiver)

npm install -g @anthropic-ai/claude-code
2

Abrir no projeto

cd meu-projeto
claude
3

Inicializar com /init

/init

O Claude analisa o repositório e cria o CLAUDE.md com contexto, stack e convenções do projeto.

4

Explorar a base de código

Leia os arquivos principais e me explique: qual é a stack, como o projeto está organizado e quais são os pontos de atenção antes de eu começar a contribuir.
5

Primeira tarefa real

Implemente [feature]. Antes de codar, mostre os arquivos que vai tocar e o que vai criar.

Recomendado: use Plan Mode na primeira tarefa para revisar a abordagem antes de executar.

Dentro do projeto

Com o projeto rodando — planejamento, automação e controle

Planejando com os modos
  • 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 e slash commands
  • 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
Comandos essenciais do dia a dia
  • /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.

08

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

  1. 1Crie .claude/skills/<nome>/SKILL.md na raiz do projeto
  2. 2Adicione frontmatter com name e description (obrigatórios)
  3. 3Opcional: restrinja ferramentas com allowed-tools
  4. 4Escreva as instruções no corpo em markdown
  5. 5Invoque com /nome-da-skill
Exemplo: skill de commit padronizado
---
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
09

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

  1. 1CLAUDE.md na raiz: documentação compartilhada, commitada no repo, lida automaticamente ao iniciar
  2. 2Memória automática: o Claude aprende sobre você e o projeto ao longo do tempo
  3. 3Use CLAUDE.md para contexto do time e memória automática para preferências individuais
  4. 4Para forçar: "guarde isso na memória" ou "não esqueça X"
Exemplo: CLAUDE.md estruturado
# 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
10

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

  1. 1Crie .claude/commands/<nome>.md
  2. 2Frontmatter opcional: description e allowed-tools
  3. 3Escreva as instruções em markdown no corpo
  4. 4Use $ARGUMENTS para capturar o que vem depois do comando
  5. 5Invoque com /nome-do-comando <argumentos>
Exemplo: comando de auditoria de branch
---
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
11

Boas práticas

O que fazer e o que evitar para tirar o máximo do Claude Code com segurança.

Faç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
Evite
  • 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.

12

Prompts prontos

Copie, adapte e use. Prompts testados para as situações mais comuns.

Implementar nova feature
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.
Investigar e corrigir um bug
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.
Code review antes do PR
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.
Refatorar componente legado
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.

Comece pelo terminal

Instale, abra em qualquer projeto e descreva o que quer implementar. O Claude lê o repositório e age como assistente que já conhece o código.

Use /init no primeiro uso para o Claude criar o CLAUDE.md e já entender o contexto do seu projeto.

Abrir Claude Code

Feito por Larissa Santos · Web Developer