Claude Code para iniciantes: instalação, permissões seguras e primeiros 30 minutos

Claude Code é um agente de programação usado no terminal. Ele não é apenas um chat para colar trechos de código: pode ler arquivos do projeto, procurar no repositório, sugerir mudanças, editar quando você permite e executar comandos como testes e builds.

O erro mais comum de quem começa é pedir uma tarefa grande demais. “Melhore este aplicativo inteiro” gera um diff difícil de revisar. O melhor primeiro objetivo é menor: entender o projeto, escolher uma tarefa pequena, alterar pouco e verificar.

Este guia segue a documentação oficial de setup, common workflows e CLI usage. Depois, leia também boas práticas de CLAUDE.md e gestão de contexto.

O papel real do Claude Code

Claude Code funciona melhor com tarefas pequenas e contextualizadas: entender uma base existente, localizar arquivos, corrigir um bug simples, adicionar testes, melhorar README ou preparar um resumo de PR.

Comece assim:

Passo	Ação	Objetivo
1	Instalar e autenticar	Confirmar que funciona
2	Ler sem editar	Criar mapa do projeto
3	Escolher tarefa pequena	Reduzir risco
4	Revisar diff e testes	Validar com evidência
5	Registrar regras	Melhorar a próxima sessão

Essa sequência evita retrabalho.

Preparação

Não comece na branch de produção. Crie uma branch segura:

git status
git switch -c try-claude-code

Se necessário:

git checkout -b try-claude-code

Confira:

• conta Claude com acesso ao Claude Code
• internet funcionando
• pasta raiz do projeto
• Git funcionando
• comando de teste ou build conhecido
• regra de não expor .env, chaves ou dados de clientes

No Windows, PowerShell e CMD usam comandos diferentes. PS C:\ indica PowerShell.

Instalação

macOS, Linux ou WSL:

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Depois:

claude --version
claude doctor

claude doctor ajuda a detectar problemas de instalação e configuração antes de você culpar o projeto.

Também existe instalação por npm:

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

Mas, sem motivo específico, prefira o instalador nativo oficial. Evite sudo npm install -g, pois pode causar problemas de permissão e segurança.

Primeiros 30 minutos

Na raiz do projeto:

cd my-project
claude

Após o login, comece em modo leitura:

Sou novo neste projeto.
Não edite arquivos ainda. Apenas leia e explique:

- o que o projeto faz
- principais diretórios e responsabilidades
- possíveis comandos de dev, test e build
- arquivos que parecem arriscados de alterar
- os 5 primeiros arquivos que devo ler

Inclua caminhos de arquivos como evidência e não chute quando algo não estiver claro.

Depois peça tarefas pequenas:

Sugira 5 tarefas boas para iniciantes neste repositório.
Cada tarefa deve:

- levar cerca de 30 minutos
- alterar no máximo 2 arquivos
- ter teste ou verificação manual
- evitar autenticação, pagamento, segredos e dados de produção

Inclua risco e passos de verificação.

Isso transforma Claude Code em um guia de onboarding.

Permissões seguras

Como Claude Code pode executar comandos e editar arquivos, permissões são importantes. Para começar com cautela:

claude --permission-mode plan

Na sessão:

/permissions

Cuidado com bypassPermissions e --dangerously-skip-permissions. Use apenas em contêineres descartáveis ou VMs isoladas.

Um exemplo conservador:

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(npm run test *)",
      "Bash(npm run build *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Read(.env)",
      "Read(**/.env)"
    ]
  }
}

Permita verificações de baixo risco, bloqueie segredos e deixe ações destrutivas para aprovação humana.

Exemplo 1: melhorar README

README é uma ótima primeira tarefa.

Quero melhorar README.md.
Primeiro leia README.md e package.json.
Liste o que falta, mas não edite ainda.
Depois da minha aprovação, altere apenas README.md.

Depois limite:

Adicione apenas duas seções ao README.md:

- desenvolvimento local
- comando de testes

Use somente comandos visíveis no package.json.
Não invente ferramentas nem passos de deploy.

Exemplo 2: corrigir um bug pequeno

Descreva o bug com reprodução:

Investigue este bug.

Problema:
- Quando o campo de busca contém só espaços, o app mostra todos os resultados.

Esperado:
- Entrada só com espaços deve ser tratada como busca vazia.

Restrições:
- Explique primeiro a causa provável.
- Altere no máximo 1 arquivo.
- Informe teste ou verificação manual.

Veja o diff:

git diff

Peça revisão:

Revise o git diff atual.
Procure mudanças inesperadas, abstração excessiva, falta de testes e casos de borda.
Se estiver bom, liste 3 verificações manuais.

Exemplo 3: CTA para PDF, produto ou consultoria

Em um site de conteúdo, Claude Code pode melhorar o próximo passo do leitor sem redesenhar tudo.

Leia este artigo e proponha 3 CTAs para iniciantes.

Objetivos:
- reduzir ansiedade do primeiro uso
- conectar naturalmente a PDF grátis, produto ou consultoria
- até 80 caracteres cada
- evitar tom agressivo de venda

Depois implemente com o padrão existente:

Encontre o padrão de CTA usado nas páginas de artigo.
Adicione um CTA no fim deste artigo com o mesmo tom.
Não crie componente novo e não altere estilos globais.

Erros comuns

Primeiro: pedir demais. “Melhore o app” não é tarefa. “Corrija busca com espaços” é tarefa.

Segundo: pular a leitura inicial. Se Claude Code não explica a arquitetura, ainda não deveria editar.

Terceiro: ampliar permissões cedo demais. Um diff compreensível vale mais que velocidade.

Quarto: confiar na mensagem final. Verifique testes, build, navegador ou git diff.

Quinto: manter uma conversa longa demais. Quando o assunto mudar, resuma e comece limpo. Veja gestão de contexto.

Checklist de problemas

• claude --version funciona?
• O que claude doctor informa?
• Você está na raiz do projeto?
• git status está compreensível?
• Misturou PowerShell e CMD?
• Está em WSL, SSH ou contêiner com login especial?
• Está tentando ler .env ou chaves?
• Ativou modo de permissão perigoso?
• O comando de teste existe de verdade?

Prompt de diagnóstico:

Claude Code não está funcionando como esperado.
Não edite arquivos. Ajude apenas no diagnóstico.

Ambiente:
- OS:
- shell:
- comando executado:
- erro:
- comportamento esperado:

Ordene as verificações da mais segura para a mais arriscada.

Nota de verificação de Masa

No ClaudeCodeLab, o fluxo mais confiável foi ler, planejar, mudar pouco e verificar. Isso funcionou para artigos, traduções, CSS e scripts de deploy. Tarefa pequena gera diff revisável. Automação longa demais dificulta entender a intenção.

Minha recomendação: na primeira semana, mantenha prompts de permissão visíveis, leia todo git diff e salve os prompts que funcionaram. Depois avance para dicas de produtividade.

Próximo passo

Hoje, abra um repositório sem risco, peça um mapa em modo leitura, escolha uma melhoria de 30 minutos e revise o diff.

Para uma referência rápida, baixe grátis Claude Code Quick Reference Cheatsheet. Para adoção em equipe, treinamento ou uso em projeto real, siga pelos recursos e links de consultoria do site.