---
title: "Guia básico do Claude Code: instalação, permissões, modelos e gerenciamento de contexto"
locale: pt
category: tutorial
category_name: "Tutorial"
translation_status: reviewed
license: cc_by
author: "injoys"
source_url: https://injoys.com/en/articles/claude-code-setup-permissions-models-context-guide
published_at: 2026-08-13T12:12:59+09:00
---

# Guia básico do Claude Code: instalação, permissões, modelos e gerenciamento de contexto

> Explica passo a passo desde a instalação e a primeira execução do Claude Code até os modos de permissão, a escolha do modelo, a organização do contexto e a criação do CLAUDE.md. Também corrige, com base na documentação oficial, o sistema de permissões e as informações sobre custos simplificados no material original.

## Key Points

- O Claude Code é uma ferramenta de programação baseada em agentes que pode ler e modificar arquivos no diretório do projeto e executar ferramentas de terminal.
- O VS Code é uma opção conveniente, mas não é um requisito, e o Claude Code também pode ser executado em ambientes de terminal compatíveis.
- Para iniciantes, é mais seguro revisar o escopo do trabalho no modo Plan e depois mudar para o modo padrão ou Accept Edits.
- O custo varia de acordo com o método de autenticação, o modelo escolhido, o contexto de entrada e o número de repetições da tarefa.
- O CLAUDE.md não é um repositório de memória das conversas, mas um arquivo de instruções que fornece repetidamente a estrutura, os comandos e as regras do projeto.

Claude Code é uma ferramenta de desenvolvimento agêntica que permite usar o Claude da Anthropic no terminal e em repositórios de código. Além de responder com trechos de código, ela explora e edita arquivos, executa comandos, realiza testes e analisa erros dentro do escopo permitido.

Este guia explica não apenas o procedimento de instalação, mas também como configurar permissões com segurança, quais critérios usar para escolher o modelo adequado à tarefa e como gerenciar o contexto e as instruções do projeto. Como os comandos e ambientes compatíveis podem ser atualizados, durante a instalação é necessário verificar os comandos mais recentes exibidos na documentação oficial de configuração.

## Três formas de programar com Claude

Cada forma se diferencia menos pelo resultado e mais pelo **nível de interação da ferramenta com o projeto local**.

| Forma | Acesso a arquivos locais | Execução de comandos | Tarefas adequadas | Principais limitações |
|---|---:|---:|---|---|
| Claude na web | Limitado por padrão | Indisponível por padrão | Perguntas, explicações de código, exemplos curtos, revisão de design | É necessário copiar e executar para aplicar as respostas diretamente ao projeto |
| Aplicativo Claude para desktop | Varia conforme recursos, integrações e aprovação do usuário | Varia conforme recursos e integrações | Trabalho com documentos, tarefas centradas em conversas, integrações locais compatíveis | Não controla automaticamente o repositório e o shell em todos os ambientes de instalação |
| Claude Code | Possível dentro do escopo do projeto | Possível conforme a política de permissões | Alteração de repositórios reais, testes, refatoração, projetos de longo prazo | Como lida com permissões de shell e arquivos, requer revisão e configuração de segurança |

Claude Code não é destinado apenas a desenvolvedores profissionais. No entanto, como pode realizar tarefas que afetam o sistema, como excluir arquivos, instalar dependências e executar scripts de build, recomenda-se que iniciantes usem o modo Plan junto com controle de versão.

## Preparação antes da instalação

Prepare primeiro os seguintes itens.

- Consulte na documentação oficial os sistemas operacionais e ambientes de shell atualmente compatíveis.
- Prepare uma conta Anthropic que permita usar Claude Code ou um ambiente compatível de autenticação e cobrança.
- Se for um projeto existente, crie um repositório Git e faça commit das alterações ou um backup.
- Identifique os comandos de teste, build e lint do projeto.
- É possível usar um editor como o VS Code, mas o próprio VS Code não é um requisito para Claude Code.

No Windows, é necessário verificar as condições para PowerShell, Prompt de Comando ou WSL indicadas na documentação oficial. Se o computador for gerenciado por uma organização, verifique primeiro também as permissões de instalação, o proxy, o firewall e as políticas de tratamento de dados.

## Instalação e primeira execução do Claude Code

### 1. Verifique o comando oficial de instalação

Na documentação oficial de configuração do Claude Code, selecione o método de instalação mais recente correspondente ao sistema operacional. Como o método e os comandos de instalação podem mudar, use a documentação oficial como referência em vez de reutilizar diretamente comandos de vídeos ou blogs antigos.

### 2. Abra a pasta do projeto

Crie uma nova pasta ou acesse um repositório existente. Se estiver usando o VS Code, abra a pasta em **File > Open Folder** e depois selecione **Terminal > New Terminal**.

```bash
cd path/to/project
claude
```

Ao executar `claude`, poderá ser exibido um procedimento de autenticação no navegador, se necessário. Após o login, Claude Code analisa o projeto com base no diretório de trabalho atual. Portanto, é mais seguro executá-lo na raiz do repositório real do que no diretório pessoal ou em uma pasta superior excessivamente abrangente.

### 3. Comece com uma solicitação pequena

Em vez de encarregá-lo desde o início de criar a aplicação inteira, divida o escopo da seguinte forma.

1. Peça para ler e resumir a estrutura do projeto.
2. Peça para apresentar o plano de implementação e os arquivos que serão alterados.
3. Peça para implementar apenas uma funcionalidade.
4. Peça para executar testes ou análise estática.
5. Peça para explicar as alterações e os riscos restantes.

Exemplo de solicitação:

```text
Leia este repositório e resuma a estrutura e como executá-lo. Ainda não modifique
arquivos; apenas proponha um plano para adicionar um formulário de login e os arquivos que serão alterados.
```

## Modos de permissão e configuração segura

Os textos exibidos para os modos de permissão do Claude Code podem variar conforme a versão e a tela de configuração. Os principais conceitos de modos usados nas configurações oficiais são os seguintes.

| Modo | Comportamento | Situação recomendada |
|---|---|---|
| Default | Solicita aprovação conforme necessário ao editar arquivos ou executar ferramentas que possam apresentar riscos | Tarefas cotidianas comuns |
| Accept Edits | Permite automaticamente a edição de arquivos, mas outras ferramentas ainda podem exigir aprovação separada | Trabalho de desenvolvimento em que os arquivos alterados são rastreados pelo Git |
| Plan | Concentra-se na análise e no planejamento sem modificar arquivos nem executar comandos | Compreensão do repositório, revisão de design, primeira etapa para iniciantes |
| Don't Ask | Política não interativa que rejeita operações não autorizadas previamente em vez de perguntar | Ao usar ambientes de automação ou listas de permissões rigorosas |
| Bypass Permissions | Ignora o procedimento de verificação de permissões | Deve ser evitado fora de ambientes com riscos controlados, como contêineres isolados |

`Shift+Tab` pode ser usado para alternar entre alguns estados de permissão disponíveis na interface interativa. No entanto, como nem todas as configurações necessariamente são percorridas apenas com esse atalho, é necessário verificar o indicador de estado na tela atual e a documentação oficial de permissões.

### Fluxo recomendado para iniciantes

1. Receba um plano de implementação no modo Plan.
2. Revise os arquivos que serão alterados e os comandos que serão executados.
3. Faça a implementação no modo Default ou Accept Edits.
4. Verifique pessoalmente instalações de pacotes, alterações no banco de dados e comandos de exclusão.
5. Revise o `git diff` e os resultados dos testes antes de fazer o commit.

Bypass Permissions não é simplesmente um modo rápido e conveniente. Como pode ampliar os danos causados por comandos incorretos, acesso excessivo a arquivos ou exposição de informações confidenciais, não deve ser usado como padrão em computadores pessoais ou repositórios importantes.

## Seleção de modelo e gerenciamento de custos

Em uma sessão interativa, use `/model` para verificar ou alterar os modelos disponíveis na conta e no ambiente. Como os nomes, aliases e a disponibilidade dos modelos podem variar conforme o momento e o método de autenticação, é melhor não criar automações que pressuponham uma lista fixa de modelos.

```text
/model
```

Os princípios gerais de seleção são os seguintes.

| Tipo de tarefa | Critério de seleção |
|---|---|
| Design de arquitetura, depuração difícil, raciocínio complexo | Considere primeiro um modelo de alto desempenho |
| Implementação geral, criação de testes, desenvolvimento repetitivo | Considere um modelo com bom equilíbrio entre desempenho e velocidade |
| Pesquisa simples, conversão de formato, correções curtas | Se houver suporte na conta, considere um modelo rápido e econômico |

Opus, Sonnet e Haiku são nomes que distinguem famílias de modelos, mas a versão exata de cada família e sua compatibilidade com Claude Code podem mudar continuamente. Em alguns ambientes, é possível usar aliases como `/model sonnet`, mas o mais preciso é verificar as opções exibidas na sessão atual.

### Formas práticas de reduzir custos

- Execute no subdiretório necessário para reduzir a exploração de arquivos desnecessários.
- Informe de uma só vez o objetivo, as restrições e os critérios de conclusão para reduzir retrabalho.
- Em vez de fornecer logs extensos completos, forneça o trecho em torno do erro e as etapas de reprodução.
- Exclua caminhos desnecessários, como arquivos gerados, resultados de build e grandes conjuntos de dados.
- Depois de concluir a exploração e o design, organize a sessão em uma nova unidade de trabalho.
- Para tarefas simples, use um modelo mais rápido e barato, dentro das opções disponíveis.
- Se o uso for baseado em API, consulte tanto os comandos relacionados a custos quanto as informações de uso no Anthropic Console.

A estrutura de custos varia conforme o método de login. Contas de assinatura do Claude podem ter limites de uso por plano, enquanto o uso por meio da API da Anthropic ou de provedores de nuvem pode ser cobrado com base em tokens. Portanto, não se deve presumir que determinado modelo seja sempre gratuito ou custe apenas um valor fixo.

## Gerenciamento da janela de contexto

A janela de contexto é o conjunto de conversas, conteúdo de arquivos, resultados de ferramentas, instruções do projeto e outros dados que o modelo pode consultar ao gerar a resposta atual. Ela não é equivalente a uma memória permanente nem simplesmente ao número de caracteres da conversa.

### Principais comandos

| Comando | Finalidade | Observação |
|---|---|---|
| `/context` | Verificar a composição do uso do contexto | A forma de exibição pode variar conforme a versão |
| `/compact` | Resumir a conversa atual para liberar espaço no contexto | Detalhes podem ser condensados durante o processo de resumo |
| `/clear` | Apagar o histórico da conversa atual e iniciar uma nova | Primeiro, registre em um documento as decisões necessárias e o estado do trabalho |

Não existe um critério universal segundo o qual a qualidade das respostas necessariamente diminui quando o contexto ultrapassa determinada porcentagem. Claude Code também pode realizar compactação automática, e a qualidade é afetada não apenas pela quantidade de informações incluídas, mas também por sua relevância, redundância e possíveis conflitos.

Considere organizar o contexto quando notar os seguintes sinais.

- Deixa repetidamente de considerar requisitos que já foram alterados.
- Confunde um estado antigo dos arquivos com o estado atual.
- Mistura condições de funcionalidades diferentes.
- Lê repetidamente o mesmo arquivo sem necessidade.
- A conversa e a saída das ferramentas ficaram excessivamente longas.

Não é necessário executar `/clear` obrigatoriamente sempre que uma funcionalidade for concluída. Em vez disso, registre as decisões concluídas, os itens pendentes e os resultados dos testes na documentação do projeto ou no histórico de trabalho antes de iniciar uma nova sessão, reduzindo assim a perda de informações.

## Gerenciamento das instruções do projeto com CLAUDE.md

O nome do arquivo geralmente é escrito como `CLAUDE.md`, incluindo letras maiúsculas. Esse arquivo não é uma memória permanente do Claude, mas um documento persistente de instruções que Claude Code consulta no projeto. Incluí-lo no repositório permite compartilhar as instruções com a equipe, mas informações confidenciais não devem ser registradas nele.

É possível usar o comando `/init` para analisar o projeto e começar a criar o `CLAUDE.md` inicial, mas o resultado deve obrigatoriamente ser revisado por uma pessoa.

### Conteúdo recomendado

- Objetivo e principais funcionalidades do projeto
- Linguagens, frameworks e versões de runtime utilizados
- Função dos diretórios e módulos importantes
- Comandos de instalação, servidor de desenvolvimento, teste, lint e build
- Estilo de código e convenções de nomenclatura
- Arquivos que não devem ser modificados ou código gerado
- Princípios de segurança e tratamento de dados pessoais
- Critérios de conclusão das tarefas e procedimento de validação

Exemplo:

```markdown
# Project instructions

## Stack
- Usamos TypeScript e Node.js.
- O gerenciador de pacotes é o pnpm.

## Commands
- Teste: `pnpm test`
- Lint: `pnpm lint`
- Build: `pnpm build`

## Rules
- Não leia nem faça commit do `.env` e de credenciais reais.
- Antes de alterar o formato de resposta de uma API pública, apresente primeiro um plano.
- Adicione testes relacionados às alterações de funcionalidades.
```

Não existe um limite máximo oficial de 200 linhas para o `CLAUDE.md`. No entanto, instruções longas demais podem consumir contexto e criar conflitos entre regras, portanto é mais prático mantê-las curtas e específicas. Separe explicações detalhadas de design em documentos próprios e indique os caminhos necessários.

## Procedimento de trabalho recomendado

O procedimento básico para aumentar simultaneamente a segurança e a qualidade dos resultados é o seguinte.

1. Verifique se o estado do Git está limpo e crie um backup ou commit.
2. Execute Claude Code na raiz do repositório.
3. Verifique o `CLAUDE.md` e a documentação existente.
4. No modo Plan, receba o objetivo, os arquivos que serão modificados e o plano de testes.
5. Divida tarefas grandes em pequenas unidades que possam ser revisadas.
6. Implemente uma unidade por vez no modo Default ou Accept Edits.
7. Revise pessoalmente comandos de instalação, exclusão, implantação e alteração de dados.
8. Verifique testes, lint, checagem de tipos e o `git diff`.
9. Documente o estado de conclusão e os problemas restantes.
10. Se a próxima tarefa não estiver relacionada à conversa anterior, inicie uma nova sessão com `/clear`.

## Checklist de segurança

- Evite que `.env`, chaves de API, certificados e dados de clientes sejam expostos em prompts ou no repositório.
- Não faça experimentos diretamente em servidores e bancos de dados de produção.
- Leia comandos de shell ou scripts de instalação de origem desconhecida antes de executá-los.
- Mesmo no código escrito pelo Claude, revise dependências, licenças, vulnerabilidades de segurança e testes.
- Em tarefas importantes, aplique o princípio do menor privilégio e use um ambiente de desenvolvimento isolado.
- Verifique alterações geradas automaticamente com o Git diff e mantenha a responsabilidade final com uma pessoa.

Claude Code pode reduzir significativamente o tempo do processo de desenvolvimento, mas não é um mecanismo automático que garanta a precisão e a segurança dos resultados. A forma mais confiável de usá-lo é combinar instruções claras, permissões limitadas, pequenas unidades de alteração, testes automatizados e revisão humana.

## FAQ

### É absolutamente necessário ter o VS Code para usar o Claude Code?
Não. Usar o terminal integrado do VS Code é conveniente, mas não é um requisito. Se você tiver um sistema operacional e um ambiente de terminal compatíveis, conforme a documentação oficial, poderá executar `claude` no diretório do projeto.

### Qual é a maior diferença entre o Claude na web e o Claude Code?
Enquanto o Claude na web oferece principalmente conversas e respostas sobre código, o Claude Code pode ler e modificar os arquivos reais do projeto e executar ferramentas de terminal dentro do escopo autorizado. Isso aumenta a produtividade, mas exige um gerenciamento cuidadoso das permissões de arquivos e comandos.

### Com qual modo de permissão os iniciantes devem começar?
Um fluxo seguro é primeiro revisar o plano de alterações e os arquivos de destino no modo Plan e depois implementar no modo Default ou Accept Edits. É melhor não aprovar automaticamente tarefas como instalação de pacotes, exclusão de arquivos e alterações no banco de dados.

### O modo Don't Ask executa todas as tarefas automaticamente?
Não. Em geral, Don't Ask é uma política que rejeita tarefas não autorizadas previamente em vez de perguntar ao usuário. Ele deve ser diferenciado de Bypass Permissions, que ignora todas as verificações de permissão.

### Como alterar o modelo no Claude Code?
Em uma sessão interativa, digite `/model` para verificar e selecionar os modelos disponíveis para a conta e o ambiente atuais. Como as versões e os aliases dos modelos podem mudar, use o menu atual como referência, em vez de listas antigas.

### Usar o Sonnet sempre resulta no menor custo?
Nem sempre. O custo varia não apenas de acordo com o preço do modelo, mas também com o contexto de entrada, o tamanho da saída, o número de novas tentativas, o uso de cache e os métodos de autenticação e pagamento. Para tarefas simples, um modelo mais econômico pode ser vantajoso, mas, em tarefas difíceis, um modelo de alto desempenho também pode reduzir o custo total ao diminuir o retrabalho.

### Qual é a diferença entre /clear e /compact?
`/clear` é usado para apagar o histórico da conversa atual e começar como se fosse uma nova sessão. `/compact` resume a conversa existente para liberar espaço de contexto, mas alguns detalhes podem ser condensados durante o processo de resumo.

### A qualidade das respostas necessariamente piora quando o contexto ultrapassa 80%?
Não existe um limiar universal desse tipo. Além da porcentagem de uso, a qualidade é afetada pela relevância, repetição e conflito das informações, bem como pelo tamanho das saídas das ferramentas. É razoável verificar o estado com `/context` e fazer uma limpeza quando surgirem sinais como confusão entre requisitos antigos.

### Qual é o nome de arquivo correto: claude.md ou CLAUDE.md?
O arquivo de instruções do projeto é grafado como `CLAUDE.md` na documentação oficial. Como alguns sistemas operacionais e ferramentas diferenciam maiúsculas de minúsculas, é mais seguro usar exatamente a grafia oficial.

### O CLAUDE.md deve ter no máximo 200 linhas?
Não existe um limite máximo oficial de 200 linhas. No entanto, instruções longas usam mais contexto e podem causar conflitos entre regras. Por isso, é recomendável escrever de forma concisa os principais comandos e restrições e separar as explicações detalhadas em outro documento.

### Posso inserir chaves de API ou senhas no CLAUDE.md?
Não. Como o CLAUDE.md pode ser enviado ao repositório e compartilhado com a equipe, não se devem registrar nele credenciais reais, dados de clientes ou chaves secretas. Informações confidenciais devem ser gerenciadas por meio de variáveis de ambiente ou sistemas de gerenciamento de segredos aprovados pela organização.

### Quando devo usar Bypass Permissions?
Essa opção deve ser considerada com cautela apenas em ambientes controlados, como contêineres isolados ou sandboxes descartáveis, nos quais seja possível limitar os danos causados pela ignorância das permissões. É recomendável não usá-la como modo padrão em computadores pessoais, repositórios importantes ou ambientes de produção.

## Sources

- [Visão geral do Claude Code](https://code.claude.com/docs/en/overview)
- [Configuração do Claude Code](https://code.claude.com/docs/en/setup)
- [Permissões do Claude Code](https://code.claude.com/docs/en/permissions)
- [Configuração do modelo do Claude Code](https://code.claude.com/docs/en/model-config)
- [Custos do Claude Code](https://code.claude.com/docs/en/costs)
- [Memória do Claude Code e CLAUDE.md](https://code.claude.com/docs/en/memory)
- [Modo interativo do Claude Code](https://code.claude.com/docs/en/interactive-mode)

## Images

![Ilustração de notebook com código, árvore de arquivos, escudo de permissões e fluxo conectado](https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6NzQ0NCwicHVyIjoiYmxvYl9pZCJ9fQ==--d808896af034f2719d1a1a65b061553a991d3196/ai-572421ed.webp)
![Servidor central ligado a código, bloqueio de permissões, fluxos, documentos, bancos de dados e nuvem](https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6NzQ1MCwicHVyIjoiYmxvYl9pZCJ9fQ==--e073adddcaf8ad6bf81bc0a0b0ca1d385d6d6a38/ai-c02b920d.webp)