Tutoriais do Claude Code

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

• 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 Model Context Protocol (MCP)
• Usar Claude como utilitário unix
• Criar comandos slash personalizados

​

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 sua estrutura rapidamente.

cd /path/to/project

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 para á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 você 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 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:

• 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 APIs obsoletas 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 refatoração em incrementos pequenos e 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.

# 1. Arraste e solte uma imagem na janela do Claude Code
# 2. Copie uma imagem e cole-a no CLI com ctrl+v
# 3. Forneça um caminho de imagem
claude "Analise esta imagem: /caminho/para/sua/imagem.png"

> 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 trabalhosas
• 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
• Você pode adicionar arquivos CLAUDE.md em qualquer um destes locais:
  • A pasta onde você executa o Claude: Automaticamente adicionado às conversas que você inicia nessa pasta
  • Diretórios filhos: Claude os puxa sob demanda
  • ~/.claude/CLAUDE.md: Preferências específicas do usuário que você não quer registrar no controle de fonte

​

Configurar Model Context Protocol (MCP)

Model Context Protocol (MCP) é um protocolo aberto que permite que LLMs acessem ferramentas e fontes de dados externos. Para mais detalhes, veja a documentação 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

# 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 de 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 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 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 do .mcp.json, o Claude Code solicitará sua aprovação por segurança
• O arquivo .mcp.json é destinado a ser registrado no controle de versão para compartilhar servidores MCP com sua equipe
• Servidores de 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 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ê quer 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/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 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 ao seu cliente MCP, então seu próprio cliente é responsável por implementar confirmação do usuário para chamadas individuais de ferramentas.

​

Usar Claude como utilitário unix

​

Adicionar 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 build-error.txt | claude -p 'explique concisamente a causa raiz deste erro de build' > output.txt

​

Criar comandos slash personalizados

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

​

Criar comandos específicos do projeto

Quando usar: Você quer criar comandos slash 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/optimize.md

claude
> /project:optimize

Dicas:

• Nomes de comandos são derivados do nome do arquivo (ex., optimize.md se torna /project:optimize)
• Você pode organizar comandos em subdiretórios (ex., .claude/commands/frontend/component.md se torna /project:frontend:component)
• 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 slash 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 do PR" > .claude/commands/fix-issue.md

claude
> /project:fix-issue 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 slash pessoais

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

mkdir -p ~/.claude/commands

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

claude
> /user:security-review

Dicas:

• Comandos pessoais têm prefixo /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

​

Próximos passos