Tutoriais

Este guia fornece tutoriais passo a passo para fluxos de trabalho comuns com o Claude Code. Cada tutorial inclui instruções claras, comandos de exemplo e melhores práticas para ajudá-lo a obter o máximo do Claude Code.

​

Índice

• Retomar conversas anteriores
• Entender novas bases de código
• Corrigir bugs eficientemente
• Refatorar código
• Trabalhar com testes
• Criar pull requests
• Lidar com documentação
• Trabalhar com imagens
• Usar pensamento estendido
• Configurar memória do projeto
• Configurar o Model Context Protocol (MCP)
• Usar o Claude como utilitário unix
• Criar comandos personalizados com barra
• Executar sessões paralelas do Claude Code com Git worktrees

​

Retomar conversas anteriores

​

Continue seu trabalho sem interrupções

Quando usar: Você esteve trabalhando em uma tarefa com o Claude Code e precisa continuar de onde parou em uma sessão posterior.

O Claude Code fornece duas opções para retomar conversas anteriores:

• --continue para continuar automaticamente a conversa mais recente
• --resume para exibir um seletor de conversas

claude --continue

claude --continue --print "Continue com minha tarefa"

claude --resume

Como funciona:

1. Armazenamento de Conversas: Todas as conversas são automaticamente salvas localmente com seu histórico completo de mensagens
2. Desserialização de Mensagens: Ao retomar, todo o histórico de mensagens é restaurado para manter o contexto
3. Estado das Ferramentas: O uso de ferramentas e resultados da conversa anterior são preservados
4. Restauração de Contexto: A conversa é retomada com todo o contexto anterior intacto

Dicas:

• O histórico de conversas é armazenado localmente em sua máquina
• Use --continue para acesso rápido à sua conversa mais recente
• Use --resume quando precisar selecionar uma conversa específica do passado
• Ao retomar, você verá todo o histórico da conversa antes de continuar
• A conversa retomada começa com o mesmo modelo e configuração do original

Exemplos:

# Continuar conversa mais recente
claude --continue

# Continuar conversa mais recente com um prompt específico
claude --continue --print "Mostre nosso progresso"

# Mostrar seletor de conversas
claude --resume

# Continuar conversa mais recente em modo não interativo
claude --continue --print "Execute os testes novamente"

​

Entender novas bases de código

​

Obter uma visão geral rápida da base de código

Quando usar: Você acabou de entrar em um novo projeto e precisa entender rapidamente sua estrutura.

cd /caminho/para/projeto 

claude 

> me dê uma visão geral desta base de código 

> explique os principais padrões de arquitetura usados aqui 

> quais são os principais modelos de dados?

> como a autenticação é tratada?

Dicas:

• Comece com perguntas amplas, depois restrinja a áreas específicas
• Pergunte sobre convenções de codificação e padrões usados no projeto
• Solicite um glossário de termos específicos do projeto

​

Encontrar código relevante

Quando usar: Você precisa localizar código relacionado a uma funcionalidade ou recurso específico.

> encontre os arquivos que lidam com autenticação de usuário 

> como esses arquivos de autenticação trabalham juntos? 

> trace o processo de login do front-end ao banco de dados 

Dicas:

• Seja específico sobre o que está procurando
• Use a linguagem do domínio do projeto

​

Corrigir bugs eficientemente

​

Diagnosticar mensagens de erro

Quando usar: Você encontrou uma mensagem de erro e precisa encontrar e corrigir sua fonte.

> Estou vendo um erro quando executo npm test 

> sugira algumas maneiras de corrigir o @ts-ignore em user.ts 

> atualize user.ts para adicionar a verificação de nulo que você sugeriu 

Dicas:

• Diga ao Claude o comando para reproduzir o problema e obter um rastreamento de pilha
• Mencione quaisquer etapas para reproduzir o erro
• Informe ao Claude se o erro é intermitente ou consistente

​

Refatorar código

​

Modernizar código legado

Quando usar: Você precisa atualizar código antigo para usar padrões e práticas modernas.

> encontre uso de API obsoleta em nossa base de código 

> sugira como refatorar utils.js para usar recursos modernos do JavaScript 

> refatore utils.js para usar recursos do ES2024 mantendo o mesmo comportamento 

> execute testes para o código refatorado 

Dicas:

• Peça ao Claude para explicar os benefícios da abordagem moderna
• Solicite que as mudanças mantenham compatibilidade retroativa quando necessário
• Faça a refatoração em pequenos incrementos testáveis

​

Trabalhar com testes

​

Adicionar cobertura de testes

Quando usar: Você precisa adicionar testes para código não coberto.

> encontre funções em NotificationsService.swift que não estão cobertas por testes 

> adicione testes para o serviço de notificação 

> adicione casos de teste para condições de borda no serviço de notificação 

> execute os novos testes e corrija quaisquer falhas 

Dicas:

• Peça testes que cubram casos de borda e condições de erro
• Solicite tanto testes unitários quanto de integração quando apropriado
• Peça ao Claude para explicar a estratégia de teste

​

Criar pull requests

​

Gerar PRs abrangentes

Quando usar: Você precisa criar um pull request bem documentado para suas alterações.

> resuma as alterações que fiz no módulo de autenticação 

> criar um pr 

> melhore a descrição do PR com mais contexto sobre as melhorias de segurança 

> adicione informações sobre como essas alterações foram testadas 

Dicas:

• Peça diretamente ao Claude para fazer um PR para você
• Revise o PR gerado pelo Claude antes de enviar
• Peça ao Claude para destacar riscos ou considerações potenciais

​

Lidar com documentação

​

Gerar documentação de código

Quando usar: Você precisa adicionar ou atualizar documentação para seu código.

> encontre funções sem comentários JSDoc adequados no módulo de autenticação 

> adicione comentários JSDoc às funções não documentadas em auth.js 

> melhore a documentação gerada com mais contexto e exemplos 

> verifique se a documentação segue nossos padrões de projeto 

Dicas:

• Especifique o estilo de documentação que você deseja (JSDoc, docstrings, etc.)
• Peça exemplos na documentação
• Solicite documentação para APIs públicas, interfaces e lógica complexa

​

Trabalhar com imagens

​

Analisar imagens e capturas de tela

Quando usar: Você precisa trabalhar com imagens em sua base de código ou obter ajuda do Claude para analisar conteúdo de imagem.

> O que esta imagem mostra? 
> Descreva os elementos da UI nesta captura de tela 
> Há elementos problemáticos neste diagrama? 

> Aqui está uma captura de tela do erro. O que está causando isso? 
> Este é nosso esquema de banco de dados atual. Como devemos modificá-lo para o novo recurso? 

> Gere CSS para corresponder a este mockup de design 
> Qual estrutura HTML recriaria este componente? 

Dicas:

• Use imagens quando descrições textuais seriam pouco claras ou complicadas
• Inclua capturas de tela de erros, designs de UI ou diagramas para melhor contexto
• Você pode trabalhar com múltiplas imagens em uma conversa
• A análise de imagem funciona com diagramas, capturas de tela, mockups e mais

​

Usar pensamento estendido

​

Aproveitar o pensamento estendido do Claude para tarefas complexas

Quando usar: Ao trabalhar em decisões arquitetônicas complexas, bugs desafiadores ou planejamento de implementações em várias etapas que exigem raciocínio profundo.

> Preciso implementar um novo sistema de autenticação usando OAuth2 para nossa API. Pense profundamente sobre a melhor abordagem para implementar isso em nossa base de código. 

> pense sobre vulnerabilidades de segurança potenciais nesta abordagem 
> pense mais sobre casos de borda que devemos tratar 

Dicas para obter o máximo valor do pensamento estendido:

O pensamento estendido é mais valioso para tarefas complexas como:

• Planejamento de mudanças arquitetônicas complexas
• Depuração de problemas intrincados
• Criação de planos de implementação para novos recursos
• Compreensão de bases de código complexas
• Avaliação de compensações entre diferentes abordagens

A maneira como você solicita o pensamento resulta em diferentes níveis de profundidade de pensamento:

• “pense” aciona pensamento estendido básico
• frases intensificadoras como “pense mais”, “pense muito”, “pense mais profundamente” ou “pense por mais tempo” acionam pensamento mais profundo

Para mais dicas de prompting de pensamento estendido, veja Dicas de pensamento estendido.

​

Configurar memória do projeto

​

Criar um arquivo CLAUDE.md efetivo

Quando usar: Você quer configurar um arquivo CLAUDE.md para armazenar informações importantes do projeto, convenções e comandos frequentemente usados.

> /init 

Dicas:

• Inclua comandos frequentemente usados (build, test, lint) para evitar buscas repetidas
• Documente preferências de estilo de código e convenções de nomenclatura
• Adicione padrões arquitetônicos importantes específicos do seu projeto
• Memórias do CLAUDE.md podem ser usadas tanto para instruções compartilhadas com sua equipe quanto para suas preferências individuais. Para mais detalhes, veja Gerenciando a memória do Claude.

​

Configurar o Model Context Protocol (MCP)

Model Context Protocol (MCP) é um protocolo aberto que permite que LLMs acessem ferramentas externas e fontes de dados. Para mais detalhes, veja a documentação do MCP.

​

Configurar servidores MCP

Quando usar: Você quer aprimorar as capacidades do Claude conectando-o a ferramentas especializadas e servidores externos usando o Model Context Protocol.

# Sintaxe básica
claude mcp add <nome> <comando> [args...]

# Exemplo: Adicionando um servidor local
claude mcp add meu-servidor -e API_KEY=123 -- /caminho/para/servidor arg1 arg2

# Sintaxe básica
claude mcp add --transport sse <nome> <url>

# Exemplo: Adicionando um servidor SSE
claude mcp add --transport sse servidor-sse https://exemplo.com/endpoint-sse

# Listar todos os servidores configurados
claude mcp list

# Obter detalhes para um servidor específico
claude mcp get meu-servidor

# Remover um servidor
claude mcp remove meu-servidor

Dicas:

• Use a flag -s ou --scope para especificar onde a configuração é armazenada:
  • local (padrão): Disponível apenas para você no projeto atual (era chamado project em versões antigas)
  • project: Compartilhado com todos no projeto via arquivo .mcp.json
  • user: Disponível para você em todos os projetos (era chamado global em versões antigas)
• Defina variáveis de ambiente com flags -e ou --env (ex., -e CHAVE=valor)
• Configure o timeout de inicialização do servidor MCP usando a variável de ambiente MCP_TIMEOUT (ex., MCP_TIMEOUT=10000 claude define um timeout de 10 segundos)
• Verifique o status do servidor MCP a qualquer momento usando o comando /mcp dentro do Claude Code
• MCP segue uma arquitetura cliente-servidor onde o Claude Code (o cliente) pode se conectar a múltiplos servidores especializados

​

Entendendo escopos de servidor MCP

Quando usar: Você quer entender como diferentes escopos MCP funcionam e como compartilhar servidores com sua equipe.

# Adicionar um servidor com escopo local (padrão)
claude mcp add meu-servidor-privado /caminho/para/servidor

# Especificar explicitamente escopo local
claude mcp add meu-servidor-privado -s local /caminho/para/servidor

# Adicionar um servidor com escopo de projeto
claude mcp add servidor-compartilhado -s project /caminho/para/servidor

{
  "mcpServers": {
    "servidor-compartilhado": {
      "command": "/caminho/para/servidor",
      "args": [],
      "env": {}
    }
  }
}

# Adicionar um servidor de usuário
claude mcp add meu-servidor-usuario -s user /caminho/para/servidor

Dicas:

• Servidores com escopo local têm precedência sobre servidores com escopo de projeto e usuário com o mesmo nome
• Servidores com escopo de projeto (em .mcp.json) têm precedência sobre servidores com escopo de usuário com o mesmo nome
• Antes de usar servidores com escopo de projeto do .mcp.json, o Claude Code solicitará sua aprovação por segurança
• O arquivo .mcp.json deve ser incluído no controle de versão para compartilhar servidores MCP com sua equipe
• Servidores com escopo de projeto facilitam garantir que todos na sua equipe tenham acesso às mesmas ferramentas MCP
• Se você precisar redefinir suas escolhas para quais servidores com escopo de projeto estão habilitados ou desabilitados, use o comando claude mcp reset-project-choices

​

Conectar a um servidor MCP Postgres

Quando usar: Você quer dar ao Claude acesso somente leitura a um banco de dados PostgreSQL para consul

tas e inspeção de esquema.

claude mcp add servidor-postgres /caminho/para/servidor-mcp-postgres --connection-string "postgresql://usuario:senha@localhost:5432/meudb"

# Em sua sessão do Claude, você pode perguntar sobre seu banco de dados

> descreva o esquema da nossa tabela de usuários
> quais são os pedidos mais recentes no sistema?
> mostre-me o relacionamento entre clientes e faturas

Dicas:

• O servidor MCP Postgres fornece acesso somente leitura por segurança
• O Claude pode ajudar você a explorar a estrutura do banco de dados e executar consultas analíticas
• Você pode usar isso para entender rapidamente esquemas de banco de dados em projetos não familiares
• Certifique-se de que sua string de conexão use credenciais apropriadas com permissões mínimas necessárias

​

Adicionar servidores MCP a partir de configuração JSON

Quando usar: Você tem uma configuração JSON para um único servidor MCP que deseja adicionar ao Claude Code.

# Sintaxe básica
claude mcp add-json <nome> '<json>'

# Exemplo: Adicionando um servidor stdio com configuração JSON
claude mcp add-json api-clima '{"type":"stdio","command":"/caminho/para/cli-clima","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

claude mcp get api-clima

Dicas:

• Certifique-se de que o JSON esteja adequadamente escapado em seu shell
• O JSON deve estar em conformidade com o esquema de configuração do servidor MCP
• Você pode usar -s global para adicionar o servidor à sua configuração global em vez da específica do projeto

​

Importar servidores MCP do Claude Desktop

Quando usar: Você já configurou servidores MCP no Claude Desktop e quer usar os mesmos servidores no Claude Code sem reconfigurá-los manualmente.

# Sintaxe básica 
claude mcp add-from-claude-desktop 

claude mcp list 

Dicas:

• Este recurso só funciona no macOS e Windows Subsystem for Linux (WSL)
• Ele lê o arquivo de configuração do Claude Desktop de sua localização padrão nessas plataformas
• Use a flag -s global para adicionar servidores à sua configuração global
• Servidores importados terão os mesmos nomes que no Claude Desktop
• Se servidores com os mesmos nomes já existirem, eles receberão um sufixo numérico (ex., servidor_1)

​

Usar o Claude Code como um servidor MCP

Quando usar: Você quer usar o próprio Claude Code como um servidor MCP que outros aplicativos podem se conectar, fornecendo a eles as ferramentas e capacidades do Claude.

# Sintaxe básica
claude mcp serve

{
  "command": "claude",
  "args": ["mcp", "serve"],
  "env": {}
}

Dicas:

• O servidor fornece acesso às ferramentas do Claude como View, Edit, LS, etc.
• No Claude Desktop, tente pedir ao Claude para ler arquivos em um diretório, fazer edições e mais
• Note que este servidor MCP está simplesmente expondo as ferramentas do Claude Code para seu cliente MCP, então seu próprio cliente é responsável por implementar confirmação do usuário para chamadas individuais de ferramentas

​

Usar o Claude como utilitário unix

​

Adicionar o Claude ao seu processo de verificação

Quando usar: Você quer usar o Claude Code como um linter ou revisor de código.

Etapas:

// package.json
{
    ...
    "scripts": {
        ...
        "lint:claude": "claude -p 'você é um linter. por favor, olhe as mudanças vs. main e reporte quaisquer problemas relacionados a erros de digitação. reporte o nome do arquivo e número da linha em uma linha, e uma descrição do problema na segunda linha. não retorne nenhum outro texto.'"
    }
}

​

Pipe in, pipe out

Quando usar: Você quer canalizar dados para o Claude e receber dados de volta em um formato estruturado.

cat erro-build.txt | claude -p 'explique concisamente a causa raiz deste erro de build' > saida.txt

​

Controlar formato de saída

Quando usar: Você precisa da saída do Claude em um formato específico, especialmente ao integrar o Claude Code em scripts ou outras ferramentas.

cat dados.txt | claude -p 'resuma estes dados' --output-format text > resumo.txt

cat codigo.py | claude -p 'analise este código em busca de bugs' --output-format json > analise.json

cat log.txt | claude -p 'analise este arquivo de log em busca de erros' --output-format stream-json

Dicas:

• Use --output-format text para integrações simples onde você só precisa da resposta do Claude
• Use --output-format json quando você precisa do log completo da conversa
• Use --output-format stream-json para saída em tempo real de cada turno da conversa

​

Criar comandos personalizados com barra

O Claude Code suporta comandos personalizados com barra que você pode criar para executar rapidamente prompts ou tarefas específicas.

​

Criar comandos específicos do projeto

Quando usar: Você quer criar comandos com barra reutilizáveis para seu projeto que todos os membros da equipe podem usar.

mkdir -p .claude/commands

echo "Analise o desempenho deste código e sugira três otimizações específicas:" > .claude/commands/otimizar.md 

claude > /project:otimizar 

Dicas:

• Nomes de comandos são derivados do nome do arquivo (ex., otimizar.md se torna /project:otimizar)
• Você pode organizar comandos em subdiretórios (ex., .claude/commands/frontend/componente.md se torna /project:frontend:componente)
• Comandos do projeto estão disponíveis para todos que clonarem o repositório
• O conteúdo do arquivo Markdown se torna o prompt enviado ao Claude quando o comando é invocado

​

Adicionar argumentos de comando com $ARGUMENTS

Quando usar: Você quer criar comandos com barra flexíveis que podem aceitar entrada adicional dos usuários.

echo "Encontre e corrija o problema #$ARGUMENTS. Siga estas etapas: 1.
Entenda o problema descrito no ticket 2. Localize o código relevante em
nossa base de código 3. Implemente uma solução que aborde a causa raiz 4. Adicione
testes apropriados 5. Prepare uma descrição concisa do PR" >
.claude/commands/corrigir-problema.md 

claude > /project:corrigir-problema 123 

Dicas:

• O placeholder $ARGUMENTS é substituído por qualquer texto que segue o comando
• Você pode posicionar $ARGUMENTS em qualquer lugar em seu template de comando
• Outras aplicações úteis: gerar casos de teste para funções específicas, criar documentação para componentes, revisar código em arquivos particulares ou traduzir conteúdo para idiomas especificados

​

Criar comandos com barra pessoais

Quando usar: Você quer criar comandos com barra pessoais que funcionem em todos os seus projetos.

mkdir -p ~/.claude/commands 

echo "Revise este código em busca de vulnerabilidades de segurança, focando em:" >
~/.claude/commands/revisao-seguranca.md 

claude > /user:revisao-seguranca 

Dicas:

• Comandos pessoais são prefixados com /user: em vez de /project:
• Comandos pessoais são apenas disponíveis para você e não compartilhados com sua equipe
• Comandos pessoais funcionam em todos os seus projetos
• Você pode usá-los para fluxos de trabalho consistentes em diferentes bases de código

​

Executar sessões paralelas do Claude Code com Git worktrees

​

Usar worktrees para ambientes de codificação isolados

Quando usar: Você precisa trabalhar em múltiplas tarefas simultaneamente com isolamento completo de código entre instâncias do Claude Code.

# Criar um novo worktree com um novo branch
git worktree add ../projeto-recurso-a recurso-a
# Ou criar um worktree com um branch existente
git worktree add ../projeto-bugfix bugfix-123 

# Navegar para seu worktree 
cd ../projeto-recurso-a
# Executar o Claude Code neste ambiente isolado
claude 

cd ../projeto-bugfix
claude

# Listar todos os worktrees
git worktree list
# Remover um worktree quando terminar
git worktree remove ../projeto-recurso-a 

Dicas:

• Cada worktree tem seu próprio estado de arquivo independente, tornando-o perfeito para sessões paralelas do Claude Code
• Mudanças feitas em um worktree não afetam outros, evitando que instâncias do Claude interfiram umas com as outras
• Todos os worktrees compartilham o mesmo histórico Git e conexões remotas
• Para tarefas de longa duração, você pode ter o Claude trabalhando em um worktree enquanto continua o desenvolvimento em outro
• Use nomes de diretório descritivos para identificar facilmente para qual tarefa cada worktree é destinado
• Lembre-se de inicializar seu ambiente de desenvolvimento em cada novo worktree de acordo com a configuração do seu projeto. Dependendo da sua stack, isso pode incluir:
  • Projetos JavaScript: Executar instalação de dependências (npm install, yarn)
  • Projetos Python: Configurar ambientes virtuais ou instalar com gerenciadores de pacotes
  • Outras linguagens: Seguir o processo padrão de configuração do seu projeto

​

Próximos passos