Use o Claude Code: Tutorial Passo a Passo

Introdução: O Que É o Claude Code?

Se você já tentou integrar um assistente de IA para codificação no seu fluxo de trabalho diário no terminal, provavelmente esbarrou no mesmo obstáculo: você sabe o que quer fazer, mas não tem certeza de como configurar tudo com segurança, evitar interrupções constantes e ainda assim confiar nas alterações sendo feitas.

Neste guia, você vai aprender a usar o Claude Code de forma prática e repetível como uma ferramenta de linha de comando para trabalho real de desenvolvimento. Você começará com uma instalação segura, passará para o planejamento somente leitura e depois avançará para edições em sandbox e execução de testes. A partir daí, você criará Skills reutilizáveis, conectará ferramentas externas com MCP e automatizará proteções com Hooks—tudo sem perder o controle da sua base de código.

Este passo a passo é para desenvolvedores (solo ou em equipe) que se sentem confortáveis no terminal e querem um fluxo de trabalho de IA para codificação seguro o suficiente para bases de código reais. Se você está configurando isso em uma organização, também é útil saber onde ficam as credenciais, por exemplo, o macOS Keychain criptografado no macOS.

Vamos começar configurando o acesso para que sua primeira sessão seja tranquila.

Obtenha Acesso, Instale o Claude Code e Faça Login

Antes de começar a delegar trabalho real de desenvolvimento ao Claude Code, você precisa de uma instalação limpa e um método de autenticação compatível com a forma como planeja usá-lo.

Siga estes passos para instalar o Claude Code e confirmar que você consegue autenticar:

1. Confirme que você tem o Node.js 18+ instalado executando node -v e verificando se ele reporta v18 ou superior.
2. Instale o Claude Code globalmente com: npm install -g @anthropic-ai/claude-code.
3. Inicie uma sessão interativa executando claude, depois faça login digitando /login e completando o fluxo baseado em navegador para sua conta Claude.ai (recomendado) ou Console.
4. Se você preferir autenticação por chave para scripts ou uso não interativo, defina ANTHROPIC_API_KEY no ambiente do seu shell. Se sua organização usa provedores de nuvem, confirme se você deve autenticar através do Bedrock/Vertex para não configurar o tipo errado de credencial.

Alguns pontos de atenção:

• Se você está no WSL e o instalador falha devido à detecção de SO ou incompatibilidade de npm/Node do Windows, use a abordagem de correção para WSL (incluindo a opção documentada de instalação --force --no-os-check) e evite usar sudo, contra o qual a documentação alerta explicitamente.
• Se você está fazendo login com uma conta Free/Pro/Max, revise seus controles de dados: desde 28 de agosto de 2025, usuários consumidores podem escolher se as sessões de codificação podem ser usadas para melhorar futuros modelos do Claude.

Após este passo, claude deve iniciar sem erros, e depois do /login você deve conseguir enviar um prompt curto e receber uma resposta.

Principais Conclusões:

• Você instalou o Claude Code e estabeleceu um método de login funcional para seu ambiente.
• Você precisa acertar o caminho de credenciais (login interativo /login vs chave de API vs provedor gerenciado) antes de tentar fluxos de trabalho reais.
• Você deve ficar atento a problemas de caminho WSL/Node e confirmar a configuração de compartilhamento de dados da sua conta para não ter surpresas depois.

Abra um Projeto e Planeje com Segurança: Assistente de IA para Codificação em Modo Somente Leitura

Antes de deixar o Claude Code alterar arquivos ou executar comandos, você quer que ele entenda sua base de código e proponha uma abordagem concreta em um modo que impeça a execução.

Siga estes passos para abrir seu repositório e forçar um ciclo seguro de planejamento:

1. Navegue até a raiz do seu projeto executando cd /path/to/your-repo (escolha a pasta que contém seu package.json, pyproject.toml ou go.mod).

2. Inicie o Claude Code a partir desse diretório executando claude, depois confirme que você está em um prompt interativo vinculado a este repositório.

3. Mude para o Modo Planejamento digitando /plan (ou alterne entre modos com Shift+Tab / Alt+M).

4. (Opcional) Se você quer o modo planejamento como padrão para toda sessão, crie um arquivo .claude/settings.json usando as opções oficiais de configurações:

   • Adicione "defaultMode": "plan" para que novas sessões abram em planejamento por padrão.
   • Adicione uma lista permissions.deny para arquivos que você nunca quer que o Claude Code leia (.env, secrets/, arquivos de credenciais).

5. Verifique sua configuração ativa executando claude config list conforme recomendado na orientação de configuração, depois confirme que suas configurações foram aplicadas.

6. Peça um plano específico o suficiente para aprovar: "No modo planejamento, descreva o menor conjunto de alterações para corrigir X, liste os arquivos exatos que você vai modificar e inclua os comandos que executaria para validar." Confirme que o Claude apenas propõe passos (porque o modo planejamento é sem execução).

Alguns pontos de atenção:

• Mantenha seu primeiro prompt restrito: um plano que nomeia arquivos, funções e comandos é muito mais fácil de aprovar do que uma reescrita de alto nível.
• Se você ficar tentado a acelerar depois de gostar do plano, trate o acceptEdits como uma configuração intencional de "fase de implementação", não algo que você liga enquanto ainda está explorando.
• Se claude config list não refletir suas alterações, verifique se você criou o .claude/settings.json no repositório a partir do qual iniciou o Claude Code.

Você saberá que este passo funcionou quando o Claude responder com um plano estruturado (arquivos-a-alterar + comandos de validação) e não tentar executar ferramentas ou modificar arquivos enquanto você permanecer no Modo Planejamento.

Principais Conclusões:

• Você abriu o Claude Code no contexto correto do projeto e forçou um fluxo de trabalho de planejamento-primeiro antes de qualquer execução.
• Você precisa ter o Modo Planejamento e os controles de escopo do .claude/settings.json configurados antes de pedir trabalhos com múltiplos passos.
• Você deve ficar atento a incompatibilidades de configuração (repositório errado, caminho de arquivo errado) e só mudar para modos de permissão mais rápidos depois de ter aprovado um plano concreto.

Aplique Alterações, Execute Testes e Habilite o Sandbox para Geração de Código com IA

Agora que você tem um plano aprovado, o objetivo é implementá-lo com acesso controlado de escrita e depois validar a alteração com comandos de teste reais em um ambiente de execução mais seguro.

Siga estes passos para aplicar o plano, executar validações e reduzir riscos:

1. Quando seu plano estiver pronto, o Claude Code vai te perguntar "Como você gostaria de prosseguir?" e oferecer opções como "Sim, e aceitar edições automaticamente" ou "Sim, aprovar edições manualmente"—escolha uma para começar a implementar.
2. Aprove edições de arquivos um lote por vez, depois revise imediatamente o que mudou executando git diff em um painel de terminal separado.
3. Habilite a execução em sandbox executando o comando /sandbox e selecionando a opção de sandbox que se encaixa no seu fluxo de trabalho.
4. Prefira a auto-execução em sandbox para tarefas rotineiras escolhendo o Modo auto-allow para que o Claude possa executar comandos comuns de teste e lint sem parar repetidamente para aprovações.
5. Execute o comando de teste do seu projeto a partir da raiz do repositório, como npm run test ou pytest && coverage report conforme mostrado nos exemplos da ferramenta bash.
6. Lide com comandos incompatíveis com sandbox intencionalmente: se o Claude Code oferecer a saída de emergência para executar algo fora do sandbox, pare e verifique se o comando é seguro antes de permitir.

Alguns pontos de atenção:

• Mantenha a "fase de edição" e a "fase de verificação" separadas: revise os diffs primeiro, depois execute os testes.
• Trate a execução de comandos como maior risco porque pode ser acesso direto ao sistema; na dúvida, execute o comando você mesmo ou mantenha-o em sandbox.
• Se os testes falharem, não amplie o escopo; peça ao Claude para corrigir apenas os testes que falharam ou o caminho mínimo de código implicado pela falha, depois re-execute.

Neste ponto, seu repositório deve mostrar apenas as edições pretendidas no git diff, e seu comando de teste deve completar com sucesso.

Principais Conclusões:

• Você implementou um plano aprovado e entrou em um ciclo rígido de "editar → revisar diff → executar teste" antes de fazer qualquer outra coisa.
• Você obtém mais segurança e velocidade habilitando o sandbox cedo e executando testes dentro dele sempre que possível.
• Você deve ficar atento a solicitações para usar a saída de emergência do sandbox e tratá-las como um sinal para desacelerar e verificar.

Crie Sua Primeira Skill: Um Tutorial de Claude Code

Uma vez que você esteja confortável com "planejar → implementar → testar", a maneira mais rápida de evoluir é tornar seus melhores prompts reutilizáveis. Skills são a forma moderna de fazer isso no Claude Code—são pacotes de capacidade independentes que o Claude descobre e carrega automaticamente quando sua solicitação corresponde à descrição da skill.

Uma skill é uma pasta contendo um arquivo obrigatório SKILL.md mais diretórios de suporte opcionais. O Claude usa um modelo de divulgação progressiva: ele lê os metadados primeiro (para descoberta), carrega as instruções principais quando acionado e puxa arquivos de suporte apenas quando necessário—mantendo seu contexto enxuto.

Aqui está a estrutura de pastas recomendada:

pr-summarizer/
├── SKILL.md          # Required: frontmatter + core instructions
├── references/       # Optional: deep docs, edge cases, API specs
├── examples/         # Optional: sample inputs/outputs
└── scripts/          # Optional: executable helpers (Python/Bash/Node)

Siga estes passos para criar e testar sua primeira skill:

1. Crie a pasta da skill no seu projeto executando mkdir -p .claude/skills/pr-summarizer (use .claude/skills/ para skills compartilhadas no projeto que são commitadas no git, ou ~/.claude/skills/ para skills pessoais).
2. Crie o arquivo obrigatório SKILL.md com frontmatter YAML contendo um name e description—a descrição é crítica porque o Claude a usa para decidir quando carregar a skill:

---
name: pr-summarizer
description: Summarize a pull request diff and produce a changelog entry. Use when asked to summarize, review, or create release notes from a PR or diff.
allowed-tools: Read, Grep, Glob, Bash(git diff)
---

When triggered, follow these steps:

1. Read the PR title, body, and diff
2. Extract high-level changes, breaking changes, and impacted modules
3. Return a 3-sentence summary and a one-paragraph changelog entry

Example output format:
**Summary:** Added user authentication flow with OAuth2 support...
**Changelog:** This release introduces OAuth2-based authentication...

1. Mantenha o SKILL.md enxuto (mire em 1.500–2.000 palavras; fique abaixo de 3.000) organizando conteúdo de suporte em subpastas:

   • references/ — documentação detalhada, schemas, guias de solução de problemas
   • examples/ — exemplos de entrada/saída, demos executáveis
   • scripts/ — helpers executáveis que rodam sem carregar no contexto

2. (Opcional) Adicione um arquivo de referência para casos extremos. Crie references/EDGE-CASES.md:

# Edge Cases for PR Summarizer

## Merge commits
When summarizing merge commits, focus on the merged branch's changes, not the merge commit itself.

## Empty diffs
If the diff is empty, return: "No code changes detected. This may be a metadata-only update."

Depois referencie-o no seu SKILL.md: "For edge cases, see references/EDGE-CASES.md."

1. Reinicie o Claude Code no repositório, depois teste a descoberta perguntando algo que deveria acionar a skill (por exemplo: "Resuma as alterações do meu último commit como uma entrada de changelog") e confirme que o Claude carrega e segue as instruções da sua skill.
2. Se o Claude não acionar a skill quando esperado, melhore o campo description adicionando palavras-chave de acionamento mais claras e exemplos de frases do usuário, depois teste novamente.

Alguns pontos de atenção:

• O campo name deve conter apenas letras minúsculas, números e hífens (máximo de 64 caracteres); o nome da pasta deve corresponder. O description tem um máximo de ~1.024 caracteres.
• Nunca coloque segredos ou chaves de API diretamente no SKILL.md ou arquivos de suporte—use conexões MCP ou variáveis de ambiente para acesso a serviços externos.
• Para skills que precisam de execução isolada (mantendo a conversa principal limpa), adicione context: fork ao seu frontmatter; isso executa a skill em um contexto separado de sub-agente.
• Use allowed-tools no frontmatter para restringir quais ferramentas a skill pode acessar—conceda apenas o necessário.

Você saberá que este passo funcionou quando o Claude carregar automaticamente sua skill com base em uma solicitação correspondente e produzir saída no formato que você especificou no SKILL.md.

Principais Conclusões:

• Skills são a forma moderna e recomendada de empacotar capacidades reutilizáveis no Claude Code—elas substituíram em grande parte os subagentes para a maioria dos fluxos de trabalho.
• Você obtém a melhor descoberta escrevendo uma description clara com palavras-chave de acionamento explícitas e mantendo o SKILL.md focado nas instruções principais.
• Você deve usar a estrutura de pastas (references/, examples/, scripts/) para manter sua skill principal enxuta enquanto ainda fornece ao Claude contexto aprofundado quando necessário.

Conecte Ferramentas Externas de Codificação com IA via MCP

O MCP (Model Context Protocol) é um padrão aberto que permite ao Claude Code se comunicar com servidores externos que expõem ferramentas, recursos e dados. Pense nele como um adaptador universal: em vez de colar descrições de issues ou resultados de banco de dados no seu prompt, você conecta um servidor MCP e o Claude consulta diretamente.

Siga estes passos para adicionar seu primeiro servidor MCP:

1. Decida se você precisa de um servidor HTTP remoto (para serviços na nuvem como Notion, Linear ou APIs hospedadas) ou um servidor stdio local (para ferramentas que precisam de acesso direto ao sistema de arquivos); HTTP é recomendado para a maioria das integrações.
2. Adicione um servidor MCP remoto usando a CLI: claude mcp add --transport http notion https://mcp.notion.com/mcp (substitua pelo endpoint real do seu serviço).
3. Para servidores que exigem autenticação, inclua a flag de header: claude mcp add --transport http linear https://api.linear.app/mcp --header "Authorization: Bearer your-token".
4. Verifique se seu servidor foi adicionado executando claude mcp list, depois inspecione sua configuração com claude mcp get <name>.
5. Teste a conexão pedindo ao Claude para usar a integração (por exemplo: "Liste minhas issues abertas no Linear" ou "Encontre a página do Notion sobre onboarding").

Para servidores locais ou configuração compartilhada com a equipe, crie um arquivo .mcp.json na raiz do seu projeto:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem"],
      "env": {
        "ALLOWED_PATHS": "/Users/me/projects"
      }
    }
  }
}

Alguns pontos de atenção:

• Minimize o escopo de tokens e restrinja ALLOWED_PATHS para servidores de sistema de arquivos—o princípio do menor privilégio se aplica aqui.
• Servidores MCP já tiveram vulnerabilidades de segurança corrigidas no passado; mantenha seus servidores atualizados e use apenas servidores de fontes confiáveis.
• A saída de ferramentas dispara um aviso em 10.000 tokens e tem limite máximo de 25.000 tokens por padrão; considere paginação ou escopar consultas de forma mais restrita para respostas grandes.

Você saberá que este passo funcionou quando o Claude conseguir consultar ou agir em um sistema externo (como listar issues ou ler um documento) sem que você precise colar o conteúdo manualmente.

Principais Conclusões:

• O MCP é como você conecta o Claude Code a ferramentas externas e fontes de dados—é um protocolo aberto suportado em múltiplas plataformas de IA.
• Você obtém mais valor começando com uma integração que usará diariamente (como seu rastreador de issues) e expandindo apenas depois que ela funcionar de forma confiável.
• Você deve ficar atento a permissões excessivamente amplas; escopar caminhos de arquivos e tokens de API de forma restrita e manter servidores MCP atualizados.

Automatize Proteções com Hooks

Hooks permitem que você execute comandos shell automaticamente em pontos específicos do ciclo de vida do Claude Code—quando você envia um prompt, antes ou depois de uma ferramenta ser executada, ou quando uma sessão começa. Use-os para automação leve como impor estilo de código, registrar comandos em log ou bloquear operações arriscadas.

Siga estes passos para adicionar seu primeiro hook:

1. Decida por uma automação de baixo risco para começar, como registrar em log quando o Claude executa certos comandos ou auto-formatar código após edições.
2. Adicione um hook ao .claude/settings.json do seu projeto (ou ~/.claude/settings.json para escopo de usuário) seguindo o guia de hooks. Aqui está um exemplo inicial que registra em log todo comando Bash que o Claude executa:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date): $(echo $CLAUDE_TOOL_INPUT | jq -r '.command')\" >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

1. Para um hook mais prático, auto-execute o Prettier em arquivos TypeScript após cada edição adicionando um hook PostToolUse:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $(echo $CLAUDE_TOOL_INPUT | jq -r '.file_path') 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

1. Reinicie o Claude Code e acione o hook executando um comando que corresponda ao seu matcher, depois verifique se o hook foi disparado checando seu arquivo de log ou a saída formatada.
2. Depure hooks executando /hooks dentro do Claude Code para inspecionar hooks registrados, ou use claude --debug para ver os logs de execução de hooks.

Alguns pontos de atenção:

• Hooks executam comandos shell arbitrários como seu usuário, então comece com ações somente leitura ou de logging antes de adicionar qualquer coisa que altere estado.
• Hooks rodam com um timeout de 60 segundos por padrão; mantenha os comandos rápidos para que não atrasem o fluxo de trabalho do Claude.
• Use o código de saída 2 para bloquear uma operação (para hooks PreToolUse que devem rejeitar comandos perigosos); outros códigos diferentes de zero são avisos não bloqueantes.

Você saberá que este passo funcionou quando seu hook disparar de forma confiável e produzir saída observável (uma entrada de log, arquivo formatado ou comando bloqueado) no ponto de acionamento esperado.

Principais Conclusões:

• Hooks são automação leve que executa comandos shell em pontos específicos do ciclo de vida do Claude Code—use-os para proteções, formatação e logging.
• Você obtém mais segurança começando com hooks inofensivos e observáveis antes de avançar para qualquer coisa que modifique arquivos ou bloqueie operações.
• Você deve ficar atento a hooks lentos ou instáveis; teste-os isoladamente e use /hooks ou --debug para solucionar problemas.

Acelere com o DeepStation

Ler um guia é um ótimo começo—mas os ganhos reais de velocidade vêm quando sua configuração do Claude Code se torna memória muscular entre projetos. O DeepStation ajuda você a fazer exatamente isso, acelerando a educação em IA e inovação através do poder da comunidade—para que você possa comparar fluxos de trabalho reais, explorar dicas de codificação com IA de outros desenvolvedores e transformar "prompts avulsos" em um processo consistente e mais seguro do Claude Code no qual você pode confiar.

Se você está pronto para ganhar impulso esta semana, participe agora e comece a evoluir ao lado de outros desenvolvedores que estão refinando seu fluxo de trabalho com Claude Code, melhores práticas de codificação com IA e rotinas de automação para desenvolvedores. Inscreva-se para treinamento de fluxo de trabalho com Claude Code e educação em IA hoje! As vagas nas sessões ativas da comunidade preenchem rapidamente—garanta seu lugar e transforme sua próxima sessão no terminal em progresso mensurável.