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 um utilitário estilo unix
• Criar comandos de barra personalizados
• 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 oferece 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 todo o histórico 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 a conversa mais recente
claude --continue

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

# Mostrar seletor de conversas
claude --resume

# Continuar a conversa mais recente no 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 um recurso ou funcionalidade específica.

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

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

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

Dicas:

• Seja específico sobre o que você está procurando
• Use a linguagem de 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 origem.

> 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:

• Informe 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 de 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 

> crie 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 potenciais ou considerações

​

Lidar com documentação

​

Gerar documentação de código

Quando usar: Você precisa adicionar ou atualizar a documentação do 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 os padrões do nosso 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 o conteúdo da 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 de texto seriam pouco claras ou complicadas
• Inclua capturas de tela de erros, designs de UI ou diagramas para melhor contexto
• Você pode trabalhar com várias imagens em uma conversa
• A análise de imagem funciona com diagramas, capturas de tela, mockups e mais

​

Usar pensamento estendido

​

Aproveite 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 de múltiplas 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 possíveis vulnerabilidades de segurança nesta abordagem 
> pense mais profundamente 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:

• Planejar mudanças arquitetônicas complexas
• Depurar problemas intrincados
• Criar planos de implementação para novos recursos
• Entender bases de código complexas
• Avaliar compensações entre diferentes abordagens

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

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

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

​

Configurar memória do projeto

​

Criar um arquivo CLAUDE.md eficaz

Quando usar: Você deseja 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
• As 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ê deseja 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 de project em versões mais antigas)
  • project: Compartilhado com todos no projeto via arquivo .mcp.json
  • user: Disponível para você em todos os projetos (era chamado de global em versões mais antigas)
• Defina variáveis de ambiente com flags -e ou --env (por exemplo, -e CHAVE=valor)
• Configure o tempo limite de inicialização do servidor MCP usando a variável de ambiente MCP_TIMEOUT (por exemplo, MCP_TIMEOUT=10000 claude define um tempo limite 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 vários servidores especializados

​

Entendendo os escopos de servidor MCP

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

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

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

# Adicionar um servidor de 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 de escopo local têm precedência sobre servidores de escopo de projeto e de usuário com o mesmo nome
• Servidores de escopo de projeto (em .mcp.json) têm precedência sobre servidores de escopo de usuário com o mesmo nome
• Antes de usar servidores de escopo de projeto de .mcp.json, o Claude Code solicitará que você os aprove por segurança
• O arquivo .mcp.json é destinado a ser incluído no controle de versão para compartilhar servidores MCP com sua equipe
• Servidores de escopo de projeto facilitam garantir que todos em sua equipe tenham acesso às mesmas ferramentas MCP
• Se você precisar redefinir suas escolhas para quais servidores de 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ê deseja dar ao Claude acesso somente leitura a um banco de dados PostgreSQL para consultas e inspeção de esquema.

claude mcp add servidor-postgres /caminho/para/postgres-mcp-server --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 a relação entre clientes e faturas

Dicas:

• O servidor MCP Postgres fornece acesso somente leitura para segurança
• Claude pode ajudá-lo 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 desconhecidos
• 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 deseja 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 funciona apenas 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 (por exemplo, servidor_1)

​

Usar o Claude Code como um servidor MCP

Quando usar: Você deseja usar o próprio Claude Code como um servidor MCP ao qual outros aplicativos podem se conectar, fornecendo-lhes 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.
• Observe que este servidor MCP está simplesmente expondo as ferramentas do Claude Code ao seu cliente MCP, então seu próprio cliente é responsável por implementar a confirmação do usuário para chamadas de ferramentas individuais.

​

Usar o Claude como um utilitário estilo unix

​

Adicionar o Claude ao seu processo de verificação

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

Passos:

// 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ê deseja canalizar dados para o Claude e obter 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 precisar do log completo da conversa
• Use --output-format stream-json para saída em tempo real de cada turno da conversa

​

Criar comandos de barra personalizados

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

​

Criar comandos específicos do projeto

Quando usar: Você deseja criar comandos de barra reutilizáveis para seu projeto que todos os membros da equipe possam 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:

• Os nomes dos comandos são derivados do nome do arquivo (por exemplo, otimizar.md se torna /project:otimizar)
• Você pode organizar comandos em subdiretórios (por exemplo, .claude/commands/frontend/componente.md se torna /project:frontend:componente)
• Comandos do projeto estão disponíveis para todos que clonam 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ê deseja criar comandos de barra flexíveis que possam 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 de PR" >
.claude/commands/corrigir-problema.md 

claude > /project:corrigir-problema 123 

Dicas:

• O espaço reservado $ARGUMENTS é substituído por qualquer texto que segue o comando
• Você pode posicionar $ARGUMENTS em qualquer lugar no seu modelo 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 específicos ou traduzir conteúdo para idiomas especificados

​

Criar comandos de barra pessoais

Quando usar: Você deseja criar comandos de 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 estão disponíveis apenas para você e não sã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 várias 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 -b recurso-a

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

# Navegue até seu worktree 
cd ../projeto-recurso-a

# Execute 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
• Alterações feitas em um worktree não afetarão 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
• 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 de configuração padrão do seu projeto

​

Próximos passos