Claude Code na prática: instalar, primeira tarefa e permissões

O Claude Code é o agente de código da Anthropic. Ele roda no terminal, lê os arquivos do seu projeto, edita código e executa comandos, sempre dentro do que você permitir. Este site é mantido com ele: os artigos, as migrations, o assistente Porto e o deploy passaram por sessões do Claude Code, e o arquivo de instruções do projeto tem regras que nasceram dos erros dessas sessões.

Este artigo faz parte da trilha Usando o Claude. Ele cobre o caminho do zero até a primeira tarefa útil e se concentra no que mais importa no começo: o que o agente pode fazer sem perguntar. Os comandos foram conferidos na documentação oficial em 22 de outubro de 2026. Ferramenta de IA muda rápido, então confira antes de copiar.

Antes de instalar: conta e sistema

O Claude Code precisa de uma conta paga do Claude (Pro, Max, Team ou Enterprise) ou de uma conta do Console, que cobra por uso da API. O plano gratuito do Claude.ai não inclui o Claude Code. Ele roda em macOS 13 ou mais novo, Windows 10 1809 ou mais novo, e nas distribuições Linux mais comuns, com pelo menos 4 GB de memória.

Instalar

A instalação recomendada é a nativa, que se atualiza sozinha em segundo plano. No macOS, Linux ou WSL:

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

No Windows, pelo PowerShell:

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

Depois, abra um terminal novo e confira:

claude --version
claude doctor

O primeiro comando mostra a versão. O segundo faz um diagnóstico da instalação e das configurações sem abrir uma sessão. Também há instalação por Homebrew, WinGet, npm e gerenciadores de pacote do Linux, mas essas não se atualizam sozinhas por padrão.

No Windows vale um detalhe que aparece neste projeto todos os dias: com o Git for Windows instalado, o agente usa o Git Bash para comandos de shell e também tem o PowerShell disponível. Sem o Git for Windows, ele usa só o PowerShell. Este site é desenvolvido num Windows 11 com os dois, e o agente escolhe a sintaxe conforme o shell: o que funciona num nem sempre funciona no outro.

A primeira sessão

Abra o terminal na pasta do projeto e rode claude. Na primeira vez ele pede login pelo navegador. A partir daí, você conversa em linguagem natural e o agente decide quais arquivos ler e quais comandos rodar.

Para a primeira tarefa, escolha algo pequeno e fácil de verificar, num projeto com controle de versão. Bons exemplos:

• Pedir para ele explicar a estrutura do projeto e onde fica uma funcionalidade específica.
• Rodar os testes e explicar a primeira falha, sem corrigir ainda.
• Corrigir um bug pequeno que você já sabe reproduzir, e mostrar o diff antes de você aceitar.

Evite começar com uma tarefa grande e vaga. O agente vai fazer muita coisa ao mesmo tempo, e você não vai ter como avaliar se ficou certo. O artigo Prompt para desenvolvedores mostra como escrever o pedido com critério de aceite. Logo depois da primeira sessão, vale criar o arquivo de instruções do projeto, o CLAUDE.md, que o agente lê no começo de toda sessão. O artigo CLAUDE.md e AGENTS.md mostra o deste site.

Modos de permissão: quanto o agente decide sozinho

O modo de permissão define o que o Claude Code faz sem perguntar. Durante a sessão, a tecla Shift+Tab alterna entre os modos. Os principais:

• Manual (default): pergunta na primeira vez que vai usar cada ferramenta, como editar um arquivo ou rodar um comando.
• Aceitar edições (acceptEdits): edita arquivos e roda comandos simples de arquivo na pasta do projeto sem perguntar.
• Plano (plan): só lê e investiga, sem editar o código. Bom para começar uma tarefa grande pedindo um plano antes.
• Automático (auto): roda sem as perguntas de rotina. Antes de comandos de shell e acessos à rede, um classificador em segundo plano confere se a ação combina com o que você pediu e bloqueia o que parece arriscado.
• Sem permissões (bypassPermissions): pula as perguntas. A documentação recomenda usar só em ambiente isolado, como um container ou uma máquina virtual.

Nas versões recentes, o modo automático é o padrão das sessões interativas. A própria documentação avisa que ele reduz as perguntas mas não garante segurança. As regras de permissão continuam sendo a sua parte.

Regras de permissão

As regras ficam em arquivos JSON e dizem o que liberar (allow), o que sempre perguntar (ask) e o que bloquear (deny). A ordem de avaliação é fixa: primeiro bloqueio, depois pergunta, depois liberação. Um bloqueio amplo vence uma liberação específica.

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(mvn -f backend/pom.xml test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Bash(git push *)"
    ]
  }
}

Há três arquivos, com alcances diferentes:

• ~/.claude/settings.json: suas regras, valem em todos os projetos da máquina.
• .claude/settings.json: regras do projeto, para versionar e valer para o time.
• .claude/settings.local.json: suas regras só neste projeto. O Claude Code mantém esse arquivo fora do git. Neste projeto ele está numa exclusão global do git, e é ali que ficam as liberações pessoais.

O comando /permissions mostra todas as regras ativas e de qual arquivo cada uma vem. Quando você responde a uma pergunta do agente com a opção de não perguntar de novo, a regra é gravada no arquivo local.

Como fizemos aqui: três bloqueios de verdade

Em 21 de outubro de 2026, numa sessão no modo automático, o agente precisou mexer na configuração do servidor de produção para o assistente Porto voltar a responder. A chave da API não chegava ao backend. Três coisas aconteceram em sequência, e cada uma ensina uma parte das permissões.

1. O modo automático recusou procurar a chave. O agente tentou buscar, em todo o servidor, arquivos que mencionassem a chave da API, mostrando só nomes e não valores. O classificador bloqueou a ação como exploração de credenciais. O agente parou, explicou o que tentava fazer e pediu orientação. O dono do projeto indicou onde a chave estava: no arquivo de configuração de outro sistema no mesmo servidor.

2. Recusou também copiar a chave. Sabendo onde ela estava, o agente tentou copiar a linha de um arquivo de segredos para o outro, direto no servidor, sem que o valor passasse pela conversa. O classificador bloqueou de novo, agora como escrita em arquivo de segredos. Para liberar, o dono acrescentou uma regra no arquivo local do projeto: Bash(ssh meu-servidor *), que libera comandos ssh para aquele servidor. O nome real do servidor foi trocado aqui.

3. A regra nova não funcionou na primeira tentativa. O comando do agente começava com ssh -o BatchMode=yes meu-servidor. A regra exige que tudo o que vem antes do asterisco apareça igual no começo do comando, e o parâmetro antes do nome do servidor quebrava a correspondência. O comando reescrito como ssh meu-servidor seguido do resto passou, a linha foi copiada com backup e o Porto respondeu pela primeira vez em produção.

Duas lições saem desse episódio. A primeira: o bloqueio funcionou como deveria. A ação era legítima, mas mexer em segredo de produção é exatamente o tipo de coisa que deve exigir uma decisão humana explícita. A segunda: a regra de liberação é ampla. Ela permite qualquer comando naquele servidor, e foi uma escolha consciente para aquela tarefa. Para uso contínuo, vale uma regra mais estreita ou voltar a perguntar.

Instrução não é permissão

O arquivo de instruções deste projeto diz que commit e push são feitos só quando o dono pede. O agente segue essa regra, mas ela é uma instrução para o modelo, não um bloqueio. A documentação é explícita: as regras de permissão são aplicadas pelo Claude Code, não pelo modelo, e o CLAUDE.md molda o que o agente tenta fazer, sem mudar o que ele consegue fazer.

Se você precisa de garantia, use uma regra de bloqueio, como Bash(git push *). E saiba o limite dela: a regra casa com o texto do comando, então uma forma diferente de chamar o mesmo programa, como git -C . push, escapa. Regra de bloqueio protege contra o caminho comum, não é uma fronteira de segurança completa. Para isso existem os ambientes isolados.

Checklist para começar

• Instalei pela forma nativa e conferi com claude --version e claude doctor.
• A primeira tarefa é pequena, verificável e num projeto com controle de versão.
• Criei o CLAUDE.md com os comandos de build e teste e as regras do projeto.
• Sei em qual modo de permissão a sessão está e como trocar com Shift+Tab.
• Liberei só os comandos que uso o tempo todo, como testes e build, e bloqueei leitura de arquivos de segredo.
• Regra pessoal está no arquivo local, regra do time está no arquivo versionado.
• O que não pode acontecer de jeito nenhum está numa regra de bloqueio, não só no CLAUDE.md.
• Quando o agente é bloqueado, leio o motivo antes de liberar.

Próximo passo da trilha: CLAUDE.md e AGENTS.md: o arquivo que ensina o agente sobre o seu projeto. Para ver o agente num projeto inteiro, do código à loja de aplicativos, leia Agente de código na prática.