Como Usar o Claude Code (Guia para Principiantes)

Índice

• Para Quem É Este Guia
• Capítulo 1: O Que É o Claude Code?
• Capítulo 2: Instalar o Claude Code
• Capítulo 3: Iniciar a Sua Primeira Sessão
• Capítulo 4: Fazer Perguntas Melhores
• Capítulo 5: Fazer a Sua Primeira Alteração de Código
• Capítulo 6: Utilizar o CLAUDE.md como Memória do Projeto
• Capítulo 7: Utilizar o Modo de Plano Antes de Grandes Alterações
• Capítulo 8: Gerir Contexto, Comandos e Permissões
• Capítulo 9: Estender o Claude Code com Competências (Skills), Hooks e MCP
• Capítulo 10: Um Fluxo de Trabalho Seguro para Principiantes
• Erros Comuns que os Principiantes Devem Evitar
• FAQ

Para Quem É Este Guia

O Claude Code pode parecer intimidante na primeira vez que o abre. Não se comporta como uma ferramenta normal de preenchimento automático. Consegue inspecionar um projeto, pesquisar ficheiros, editar código, executar comandos, resumir erros e ajudar a verificar se uma alteração funciona. Isto é extremamente poderoso, mas também significa que os principiantes precisam de um modelo mental claro antes de o deixar livre num repositório real.

Este guia é para si se:

• Já ouviu falar do Claude Code, mas ainda não o experimentou.
• O instalou, mas não sabe bem o que escrever primeiro.
• Utiliza ferramentas como o GitHub Copilot e quer perceber em que é que o Claude Code é diferente.
• Procura um fluxo de trabalho seguro para pedir ao Claude Code para editar ficheiros.
• Quer compreender conceitos fáceis para principiantes, tais como CLAUDE.md, modo de plano, competências (skills), hooks e MCP.

O objetivo não é transformá-lo num especialista em automação de um dia para o outro. A meta é ajudá-lo a utilizar o Claude Code com confiança logo no primeiro dia e, em seguida, mostrar-lhe os passos seguintes.

Capítulo 1: O Que É o Claude Code?

O Claude Code é um assistente de programação autónomo (agentic) da Anthropic. Em vez de apenas sugerir as próximas linhas de código, consegue concluir uma tarefa dividida em vários passos: ler ficheiros, compreender a estrutura do projeto, propor alterações, editar código, executar testes e explicar o que aconteceu.

Isto distingue-o de uma ferramenta normal de conclusão de código.

Tipo de ferramenta	O que faz habitualmente	Como interage com ela
Conclusão de código	Sugere código perto do seu cursor	Continua a escrever código manualmente
Assistente de chat	Responde a perguntas ou rascunha snippets de código	Copia, cola e adapta a resposta
Claude Code	Executa tarefas de desenvolvimento dentro do seu projeto	Descreve o objetivo e revê as suas ações

Por exemplo, em vez de perguntar:

Write a React component for a login form.

pode pedir:

Find the existing auth UI pattern in this repo and add a login form that matches it. Run the relevant tests afterward.

O Claude Code consegue inspecionar o projeto antes de decidir onde e como aplicar a alteração. Esta é a principal mudança: não está apenas a pedir código, está a solicitar um fluxo de trabalho completo.

O Claude Code assemelha-se mais a um parceiro de programação capaz de operar em todo o projeto do que a uma simples ferramenta de preenchimento automático.

Capítulo 2: Instalar o Claude Code

Antes de avançar com a instalação, certifique-se de que tem:

• Um terminal ou linha de comandos.
• Um projeto de código onde possa testar em segurança.
• Acesso através de uma subscrição do Claude, de uma conta na Claude Console ou de um fornecedor compatível.
• O Git instalado, caso pretenda que o Claude Code inspecione diffs e trabalhe sem problemas com repositórios.

Instalação Nativa Recomendada

Para macOS, Linux ou WSL, execute:

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

Para o Windows PowerShell, execute:

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

Para a linha de comandos do Windows (CMD), utilize o comando específico para CMD indicado no guia de início rápido oficial:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Após a instalação, verifique se está tudo a funcionar:

claude --version

Se o comando claude não for encontrado, o seu sistema poderá não ter o diretório de instalação incluído na variável PATH. No macOS ou Linux, o binário pode estar em ~/.local/bin. No Windows, poderá encontrar-se em %USERPROFILE%\.local\bin.

Outras Opções de Instalação

O Claude Code também suporta opções através de gestores de pacotes como o Homebrew e o WinGet:

brew install --cask claude-code

winget install Anthropic.ClaudeCode

A instalação nativa é habitualmente a recomendação mais simples para principiantes, uma vez que se mantém atualizada automaticamente em segundo plano. As instalações efetuadas através de gestores de pacotes podem exigir atualizações manuais.

Um fluxo simples de instalação no terminal: instalar, verificar com claude --version e, em seguida, abrir a pasta de um projeto.

Capítulo 3: Iniciar a Sua Primeira Sessão

Abra um terminal dentro da pasta de um projeto:

cd /path/to/your/project claude

Na primeira utilização, o Claude Code pedir-lhe-á para iniciar sessão. Siga o fluxo de autenticação no navegador e regresse depois ao terminal.

Assim que estiver dentro do Claude Code, comece com uma pergunta em modo de leitura:

What does this project do?

Em seguida, experimente:

Explain the folder structure.

What commands should I run to test this project?

Estas instruções (prompts) são ideais para principiantes porque permitem ao Claude Code inspecionar o projeto sem editar ficheiros de imediato.

Uma primeira sessão segura começa por compreender o projeto, em vez de avançar para alterações imediatas de código.

Capítulo 4: Fazer Perguntas Melhores

O Claude Code funciona melhor quando descreve claramente o objetivo, o contexto relevante e os critérios de sucesso. Um pedido vago ainda pode funcionar, mas um pedido preciso dá ao Claude um rumo muito mais assertivo.

Instrução vaga	Melhor instrução para principiantes
Fix the bug.	A página de início de sessão falha quando o campo de e-mail está vazio. Descubra a causa, corrija o erro e execute os testes relevantes.
Add tests.	Adicione testes para o fluxo de término de sessão (logout), especialmente para o caso em que a sessão do utilizador expirou.
Update the docs.	Atualize o README para que um novo programador consiga instalar as dependências, executar a aplicação e correr os testes.
Make the UI better.	Melhore o espaçamento da página de definições para coincidir com o layout do painel existente. Mostre-me o diff antes de editar.

Utilize esta fórmula simples para criar os seus prompts:

Goal: What you want changed. Context: Files, errors, or behavior that matter. Constraints: What Claude should avoid. Verification: How Claude should check the work.

Exemplo:

Goal: Fix the failing checkout test. Context: The failure happens in tests/checkout.test.ts when discount codes are applied. Constraints: Do not change public API names. Verification: Run the checkout test file after the fix.

A linha de verificação é particularmente importante. O Claude Code torna-se muito mais útil quando consegue validar o seu próprio trabalho.

Capítulo 5: Fazer a Sua Primeira Alteração de Código

Para a sua primeira edição, escolha algo de baixo risco:

• Adicionar uma pequena secção ao README.
• Corrigir uma gafe ortográfica.
• Adicionar um único teste unitário simples.
• Explicar e refatorizar uma pequena função auxiliar.

Exemplo de prompt:

Update the README with a short "Running tests" section. First inspect package.json to find the right test command. Show me the proposed change before editing.

Normalmente, o Claude Code irá:

1. Ler os ficheiros relevantes. 2. Decidir o que precisa de ser alterado. 3. Mostrar uma proposta de edição. 4. Pedir aprovação. 5. Aplicar a alteração se aprovar. 6. Executar um comando caso a tarefa exija verificação.

Não aprove às cegas. Analise o diff. Se algo parecer incorreto, peça correções:

This is too long for the README. Make it shorter and keep only the commands.

Os principiantes devem tratar os diffs do Claude Code como pull requests: leia-os, questione-os e só depois aprove.

Capítulo 6: Utilizar o CLAUDE.md como Memória do Projeto

O ficheiro CLAUDE.md é um documento em markdown que fornece ao Claude Code um contexto persistente sobre o projeto. Se este ficheiro existir no seu repositório, o Claude Code lê-o no início de cada sessão. Pense nele como uma nota de integração (onboarding) destinada a um colega competente.

Crie um manualmente ou peça ao Claude Code para o inicializar:

/init

Um ficheiro CLAUDE.md útil para principiantes pode ter um formato semelhante a este:

# Project Guide ## Stack - Next.js - TypeScript - pnpm - Vitest ## Common Commands - Install dependencies: pnpm install - Run dev server: pnpm dev - Run tests: pnpm test - Run lint: pnpm lint ## Rules - Use pnpm, not npm. - Do not edit files in src/legacy unless explicitly asked. - Prefer existing components in src/components/ui. - Run tests for changed areas before saying the task is complete.

Mantenha-o conciso. Um ficheiro CLAUDE.md demasiado extenso pode gerar ruído desnecessário. Inclua apenas informações que o Claude não consiga deduzir de forma fiável a partir do código:

• O gestor de pacotes correto.
• Comandos que diferem das convenções standard.
• Diretórios importantes a evitar.
• Regras de arquitetura específicas do projeto.
• Expectativas em termos de testes.

Evite enchê-lo com conselhos genéricos do tipo «escreva código limpo». O Claude já sabe isso. Utilize o CLAUDE.md para factos e regras que realmente importam no seu projeto.

O CLAUDE.md fornece ao Claude Code instruções estáveis sobre o projeto para que não tenha de as repetir em cada sessão.

Capítulo 7: Utilizar o Modo de Plano Antes de Grandes Alterações

O modo de plano (plan mode) indica ao Claude Code que deve investigar e propor um plano sem editar ficheiros. Isto é extremamente útil para principiantes, pois abranda o ritmo de trabalho antes de efetuar alterações arriscadas.

Utilize o modo de plano quando:

• A tarefa afeta múltiplos ficheiros.
• Tem dúvidas sobre qual a melhor abordagem.
• Está a trabalhar num código com o qual não está familiarizado.
• Pretende comparar opções antes de avançar para a edição.
• A alteração pode afetar o comportamento em produção.

Pode ativar o modo de plano diretamente a partir da linha de comandos:

claude --permission-mode plan

Dentro de uma sessão, também pode utilizar:

/plan Investigate why image upload fails and propose a fix. Do not edit files yet.

Em alternativa, pode alternar entre os modos de permissão premindo Shift+Tab, se a sua interface do Claude Code o suportar.

Um bom prompt de planeamento:

Use plan mode. Inspect the authentication flow and propose how to add password reset. Do not edit files yet. Include the files you expect to modify and the tests you would run.

Assim que o Claude propor um plano, pode aprová-lo, pedir alterações ou continuar a planear. Se o plano for vago, não avance. Peça um plano mais detalhado:

Make the plan more specific. Name the likely files, risks, and verification steps.

O modo de plano é a forma ideal para os principiantes garantirem que o Claude Code reflete antes de editar.

Capítulo 8: Gerir Contexto, Comandos e Permissões

As sessões do Claude Code possuem uma janela de contexto. À medida que a sessão se prolonga, o Claude acumula mais histórico para processar: mensagens, conteúdos de ficheiros, resultados de comandos, diffs e explicações. Sessões longas podem perder o foco inicial.

Utilize estes comandos atempadamente:

Comando	O que faz	Caso de uso para principiantes
/help	Mostra os comandos disponíveis	Descobrir o que a sua sessão suporta
/clear	Limpa o histórico da conversa	Recomeçar do zero ao mudar de tarefa
/compact	Resume a sessão atual	Preservar informação essencial enquanto reduz o contexto
/init	Cria um CLAUDE.md inicial	Dar memória de projeto ao Claude
/login	Inicia sessão ou muda de conta	Resolver problemas de autenticação
/permissions	Gerri as ações permitidas	Ajustar o que o Claude pode fazer automaticamente

Modos de Permissão Explicados de Forma Simples

O Claude Code poderá pedir autorização antes de editar ficheiros ou executar comandos. Esta é uma excelente funcionalidade de segurança para principiantes.

Poderá encontrar modos como:

• Modo de revisão predefinido: revê as ações à medida que acontecem.
• Modo de aceitação de edições: permite edições e revê-as posteriormente.
• Modo de plano: inspeciona e planeia sem efetuar edições.
• Modo automático: permite mais ações automáticas sob controlos de segurança, dependendo do seu plano e conta.

Os principiantes devem começar por uma abordagem conservadora. Utilize o modo de plano para tarefas maiores e analise os diffs com atenção até ganhar confiança no fluxo de trabalho.

Capítulo 9: Estender o Claude Code com Competências (Skills), Hooks e MCP

Assim que se sentir confortável com a utilização básica, o Claude Code pode ser expandido. Não precisa destas funcionalidades no primeiro dia, mas é útil compreender para que servem.

CLAUDE.md vs Competências (Skills)

Utilize o CLAUDE.md para manter o contexto do projeto sempre ativo. Utilize competências (skills) para fluxos de trabalho repetíveis ou instruções detalhadas que só devem ser carregadas quando necessário.

Funcionalidade	Ideal para	Exemplo
CLAUDE.md	Regras de projeto que o Claude deve saber sempre	«Use o pnpm. Execute o Vitest. Evite src/legacy.»
Competência (Skill)	Procedimento repetível ou conhecimento especializado	/release-checklist, /review-api, /write-docs

Uma competência mínima pode estar localizada em:

.claude/skills/review-pr/SKILL.md

Exemplo:

--- description: Review a pull request for bugs, missing tests, and risky changes. --- Review the current diff. Focus on: - Behavior changes - Missing tests - Error handling - Security or data-loss risk Return findings first, then a short summary.

Depois, pode invocá-la com:

/review-pr

Hooks

Os hooks são executados quando ocorrem eventos específicos no Claude Code. Um hook simples pode enviar uma notificação para o ambiente de trabalho quando o Claude está à espera de introdução de dados, ou executar um script de validação antes de determinados comandos de shell.

Os principiantes devem lidar com os hooks com cautela. Um hook mal configurado pode gerar efeitos secundários indesejados. Comece com notificações inofensivas ou verificações apenas de leitura.

MCP

MCP significa Model Context Protocol (Protocolo de Contexto de Modelo). Permite que o Claude Code se ligue a ferramentas e serviços externos. Por exemplo, um servidor MCP pode ligar o Claude a:

• Uma base de dados.
• Um navegador.
• O Sentry.
• O Slack.
• O GitHub.
• Ferramentas internas da empresa.

Dentro do Claude Code, o comando /mcp ajuda a gerir os servidores MCP ligados e a respetiva autenticação. Utilize o MCP quando o Claude precisar de dados ou ações exteriores ao repositório local.

O CLAUDE.md, as competências, os hooks e o MCP resolvem diferentes desafios de extensão. Comece de forma simples e adicione apenas o estritamente necessário.

Capítulo 10: Um Fluxo de Trabalho Seguro para Principiantes

Eis um fluxo de trabalho prático que pode adotar durante a sua primeira semana.

Passo 1: Comece com um estado do Git limpo

Antes de pedir ao Claude Code para editar qualquer ficheiro:

git status

Se já tiver trabalho importante por confirmar (uncommitted), faça um commit ou guarde-o num stash primeiro. O Claude Code é mais seguro quando consegue analisar claramente o que mudou.

Passo 2: Peça ao Claude para compreender o projeto

What does this project do? Explain the main folders and the commands I should know.

Passo 3: Crie ou aperfeiçoe o CLAUDE.md

/init

Reveja depois o ficheiro gerado. Remova conteúdo genérico e adicione comandos específicos do projeto.

Passo 4: Utilize o modo de plano para alterações reais

/plan Add a password reset page. Inspect the existing auth flow and propose a plan first.

Passo 5: Aprobe edições pequenas e fáceis de rever

Peça ao Claude Code para implementar apenas uma parte de cada vez:

Implement only the route and form component first. Do not wire email sending yet.

Passo 6: Execute a verificação

Run the relevant tests and tell me exactly what passed or failed.

Se os testes falharem, peça ao Claude para fazer um diagnóstico:

The test failed. Explain the failure first, then propose the smallest fix.

Passo 7: Reveja o diff final

git diff

E pergunte:

Review the final diff for bugs, missing tests, and unnecessary changes.

Este fluxo de trabalho mantém-no no controlo, permitindo simultaneamente que o Claude Code realize trabalho útil.

Erros Comuns que os Principiantes Devem Evitar

Erro 1: Pedir alterações massivas de imediato

Não comece com:

Rewrite the whole app with a better architecture.

Comece por algo mais contido:

Inspect the app architecture and identify the top three refactor opportunities. Do not edit files.

Erro 2: Não fornecer um método de verificação

Se o Claude não conseguir testar o trabalho, poderá parar demasiado cedo. Indique sempre como deve ser efetuada a verificação:

After the change, run pnpm test -- checkout.

Erro 3: Aprovar diffs sem os ler

O Claude Code pode cometer erros. Analise as alterações tal como faria ao rever o pull request de um colega de equipa.

Erro 4: Permitir que uma sessão se prolongue demasiado

Utilize /clear ao mudar de tarefa. Utilize /compact quando a sessão contém contexto útil, mas se tornou excessivamente longa.

Erro 5: Inserir dados confidenciais em prompts ou no CLAUDE.md

Nunca cole chaves de API, tokens privados, passwords de bases de dados ou segredos de produção em prompts ou ficheiros de memória do projeto. Utilize variáveis de ambiente e gestores de segredos.

Erro 6: Utilizar extensões avançadas demasiado cedo

As competências, hooks, MCP, subagentes e plugins são ferramentas poderosas. Os principiantes devem dominar primeiro:

1. Iniciar sessões. 2. Fazer perguntas claras. 3. Rever diffs. 4. Executar testes. 5. Utilizar o CLAUDE.md. 6. Utilizar o modo de plano.

Adicione extensões apenas quando sentir uma fricção repetitiva no seu fluxo.

FAQ

O Claude Code destina-se apenas a programadores experientes?

Não, mas torna-se muito mais útil quando compreende as bases do seu projeto, do Git e do terminal. Os principiantes podem utilizá-lo em segurança começando com perguntas em modo de leitura, pequenas edições e o modo de plano.

O Claude Code pode substituir a aprendizagem de programação?

Não. Consegue acelerar tarefas e explicar código, mas continuará a precisar de compreender o resultado final. Encare-o como um parceiro de programação e não como um substituto para o seu próprio discernimento.

O Claude Code edita ficheiros automaticamente?

O Claude Code consegue editar ficheiros, mas habitualmente pede permissão antes de os modificar. Pode escolher diferentes modos de permissão consoante o nível de revisão que pretende.

O que devo fazer se o Claude Code fizer uma alteração incorreta?

Utilize o Git. Analise o git diff, peça ao Claude para explicar a alteração ou reverta o ficheiro manualmente. Para tarefas mais complexas, utilize o modo de plano antes de editar.

Qual é o primeiro comando que devo executar num novo projeto?

Comece com:

claude

Depois, pergunte:

What does this project do, and what commands should I know?

Em seguida, execute:

/init

para criar um ficheiro CLAUDE.md de arranque.

Quando devo utilizar o MCP?

Utilize o MCP quando o Claude Code precisar de acesso a um serviço ou ferramenta externa, como uma base de dados, o Sentry, o GitHub, o Slack ou um navegador. Não necessita de MCP para a edição básica de código local.

Quando devo criar uma competência (skill)?

Crie uma competência sempre que se vir a colar repetidamente as mesmas instruções ou listas de verificação no Claude Code. Por exemplo, uma checklist de lançamento, uma checklist de revisão de código ou um fluxo de documentação podem transformar-se numa competência.