# Guia do Claude Code: configuração para programação agêntica (para iniciantes)

> Guia prático completo de configuração do Claude Code: instalação da CLI, configuração de CLAUDE.md e settings.json, regras de permissões, hooks automáticos, comando personalizado /truth e subagentes.

## 1. Instalação do Claude Code e preparação do ambiente

O Claude Code é instalado como uma interface de linha de comando (CLI) autônoma para interagir com o código através dos modelos agentic da Anthropic. Diferentemente de chatbots convencionais, o Claude Code interage diretamente com o sistema de arquivos, executa comandos no terminal, analisa a árvore do projeto e aplica edições atômicas.

### 1.1. Métodos de instalação da CLI: script nativo versus npm

O método recomendado pelos desenvolvedores é o script nativo do sistema, que configura automaticamente o binário e o ambiente de execução. Como alternativa para workstations que já possuem um toolchain Node.js pronto, pode-se utilizar o pacote global via npm:

```bash
# macOS, Linux або WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Альтернативне встановлення через npm
npm install -g @anthropic-ai/claude-code
```

Após concluir a instalação, verifique a funcionalidade do comando executando `claude --version` em seu terminal.

### 1.2. Vinculação ao diretório do projeto e autenticação

Antes da primeira execução, é crucial navegar diretamente para a pasta raiz do seu projeto de trabalho:

```bash
cd your-project-directory
claude
```

> 💡 **Por que isso importa:** O Claude Code vincula rigidamente a memória de longo prazo, regras locais e permissões ao diretório de trabalho atual. Executar a partir da pasta home (`~`) ou da área de trabalho resultará na perda do contexto arquitetural do seu repositório.

Durante a primeira execução, a ferramenta solicitará que você conclua a autenticação:
- **Login via OAuth no navegador** se houver uma assinatura ativa do Claude (Pro, Max ou Team).
- **Chave de API da Anthropic Console** para cobrança direta por segundo dos tokens conforme as tarifas da API.

Além do terminal puro, o Claude Code suporta operação através da extensão oficial para VS Code, plugin para JetBrains, aplicativo desktop e interface web em claude.ai. Todas essas interfaces compartilham a mesma estrutura de configuração `.claude/`, garantindo que todas as regras permaneçam inalteradas independentemente do ambiente de trabalho escolhido.

## 2. Três arquivos de configuração: arquitetura de memória e ajustes

O Claude Code utiliza uma hierarquia de configuração de dois níveis: o diretório do projeto `.claude/` (junto com o arquivo `CLAUDE.md` na raiz) e o diretório global `~/.claude/` na pasta home do usuário. As configurações globais se aplicam a todas as sessões na máquina, enquanto as locais têm prioridade para o repositório atual.

### 2.1. CLAUDE.md e as regras de memória do repositório

O `CLAUDE.md` é a memória permanente do projeto, lida pelo agente no início de cada sessão de trabalho. Aqui são registrados os marcos arquiteturais, comandos de execução de testes, regras de estilo de código e a stack tecnológica.

| Mecanismo | Localização | Finalidade |
| --- | --- | --- |
| **Guia Raiz** | `CLAUDE.md` | Instruções principais e descrição da stack (recomendado até 2500 tokens). |
| **Regras Modulares** | `.claude/rules/*.md` | Instruções específicas vinculadas a caminhos e arquivos concretos. |
| **Gerador de Memória** | Comando `/init` | Análise automática da base de código e criação do arquivo inicial. |
| **Editor de Memória** | Comando `/memory` | Edição interativa rápida das regras registradas. |

> ⚠️ **Princípio Fundamental da Memória:** Instruções fornecidas diretamente no chat inevitavelmente se perdem durante a compressão do contexto em sessões longas. Qualquer regra que deva persistir entre sessões deve ser explicitamente escrita no `CLAUDE.md`.

### 2.2. settings.json e o mecanismo de memória automática (Auto memory)

O arquivo de configuração `settings.json` (localizado em `.claude/settings.json` para o projeto ou em `~/.claude/settings.json` para o nível global) define permissões de segurança, hooks do sistema, variáveis de ambiente e o modelo padrão.

O mecanismo **Auto memory** permite que o Claude Code registre automaticamente observações de trabalho entre sessões sem intervenção direta do desenvolvedor. Esse comportamento pode ser controlado pelo parâmetro `"autoMemoryEnabled": false` ou pela variável de ambiente `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`, caso prefira exclusivamente controle manual transparente via `CLAUDE.md`.

## 3. Configuração prévia de permissões e hooks

Para garantir a segurança e eliminar solicitações desnecessárias de confirmação, o Claude Code oferece um sistema de modos interativos e regras granulares na configuração.

### 3.1. Modos interativos de permissão e matriz allow/ask/deny

A troca rápida dos modos de execução é feita pela combinação de teclas `Shift+Tab`:
- **Default** — Solicita confirmação do usuário antes de cada operação potencialmente perigosa ou alteração de arquivo.
- **Auto-Accept Edits** — Aplica automaticamente edições de arquivos, solicitando confirmação apenas para comandos de sistema.
- **Plan Mode** — Modo somente leitura, sem capacidade de alterar código ou executar comandos bash até a aprovação do plano geral.

Para eliminar confirmações rotineiras, configura-se uma matriz declarativa de regras em `.claude/settings.json`:

```json
{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Read(**)"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Bash(rm -rf /*)",
      "Bash(sudo:*)",
      "Read(.env)"
    ]
  }
}
```

A regra `deny` sempre tem a mais alta prioridade: mesmo que a máscara `Read(**)` permita a leitura de arquivos, a proibição explícita `Read(.env)` garante que variáveis de ambiente confidenciais nunca entrem no contexto do modelo.

### 3.2. Automação via hooks PostToolUse e PreToolUse

Os hooks permitem executar scripts locais antes ou depois da chamada das ferramentas embutidas do agente.

Por exemplo, o hook **PostToolUse** formata automaticamente os arquivos editados via Prettier:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}
```

E o hook **PreToolUse** permite interceptar e bloquear programaticamente comandos bash perigosos no nível de um script Python antes de sua efetiva passagem para o shell:

```python
#!/usr/bin/env python3
# .claude/hooks/block-dangerous-bash.py
import json
import re
import sys

DANGEROUS_PATTERNS = [
    r'\brm\s+.*-[a-z]*r[a-z]*f',
    r'sudo\s+rm',
    r'chmod\s+777',
    r'git\s+push\s+--force.*main',
]

input_data = json.load(sys.stdin)
if input_data.get('tool_name') == 'Bash':
    command = input_data.get('tool_input', {}).get('command', '')
    for pattern in DANGEROUS_PATTERNS:
        if re.search(pattern, command, re.IGNORECASE):
            print("BLOCKED: command matches dangerous security pattern", file=sys.stderr)
            sys.exit(2)
sys.exit(0)
```

O código de retorno `2` sinaliza ao Claude Code o bloqueio crítico da chamada sem executar o comando no sistema.

## 4. Comandos essenciais para aprender primeiro

A biblioteca embutida do Claude Code contém mais de sessenta slash commands, mas para o trabalho produtivo diário, um núcleo básico é suficiente.

### 4.1. Tabela resumida de slash commands básicos e avançados

Abaixo está um guia estruturado dos comandos CLI mais importantes:

| Comando | Categoria | Finalidade e comportamento |
| --- | --- | --- |
| `/init` | Configuração | Escaneia o projeto e cria o `CLAUDE.md` primário. |
| `/memory` | Configuração | Abre o arquivo de memória do projeto para edição direta. |
| `/clear` | Contexto | Reinicia a conversa atual, preservando a memória do projeto. |
| `/compact [focus]` | Contexto | Compacta o histórico da sessão, mantendo aspectos-chave indicados. |
| `/context` | Contexto | Mostra o estado detalhado do preenchimento da janela de contexto. |
| `/plan` | Planejamento | Alterna a CLI para modo somente leitura e design de etapas. |
| `/diff` | Verificação | Exibe uma visualização interativa de todas as alterações da sessão atual. |
| `/code-review [--fix]` | Verificação | Analisa alterações não commitadas em busca de erros lógicos. |
| `/security-review` | Verificação | Auditoria especializada de código para vulnerabilidades. |
| `/resume [session]` | Navegação | Restaura uma sessão anterior pelo ID ou nome. |
| `/branch [name]` | Navegação | Cria um ramo separado da conversa sem reiniciar a sessão. |
| `/rewind` | Navegação | Reverte o estado dos arquivos ou do diálogo para um checkpoint anterior. |
| `/model` | Produtividade | Alterna o modelo de trabalho (Sonnet, Haiku, Opus) no meio da conversa. |
| `/effort` | Produtividade | Ajusta a profundidade da cadeia de raciocínio do modelo (de low a max). |
| `/cost` | Produtividade | Exibe estatísticas de consumo de tokens e saldo da sessão. |
| `/agents` | Delegação | Gerencia subagentes especializados e tarefas em background. |
| `/permissions` | Configuração | Menu interativo para visualizar e alterar a lista de permissões. |
| `/hooks` | Configuração | Painel de diagnóstico dos hooks de sistema registrados. |
| `/doctor` | Diagnóstico | Verificação abrangente do ambiente, rede e chaves de sistema. |

![Visão geral e navegação nos slash commands embutidos do Claude Code](/api/guides-media/automation/claude-code-agentic-programming-setup-guide/images/claude-code-agentic-programming-setup-guide-extra-01.webp)

### 4.2. Tríade da produtividade diária: /compact, /plan e /diff

Para uma adoção rápida, recomenda-se fixar três ferramentas obrigatórias:
1. **`/plan`** — Execute sempre no início de tarefas complexas. Isso elimina edições caóticas e descontroladas de código sem compreensão clara das consequências.
2. **`/compact`** — Use a cada 20–30 minutos de diálogo ativo ou após concluir subtarefas, para prevenir queda de velocidade e perda de foco do modelo.
3. **`/diff`** — Abra antes de qualquer commit para verificação visual passo a passo do código gerado.

## 5. Criando seu próprio comando /truth

O comando `/truth` não faz parte da distribuição padrão do Claude Code, mas resolve um problema fundamental da programação agentic — a tendência do modelo reportar sucesso sem verificar efetivamente os resultados no sistema de arquivos.

### 5.1. Conceito de verificação de fatos contra a base de código

Quando o agente afirma: *«Atualizei o tipo no arquivo X e verifiquei os imports no arquivo Y»*, ele frequentemente se baseia em suas próprias intenções intermediárias do contexto. O conceito do comando `/truth` reside no recarregamento forçado dos arquivos reais do disco e na conferência de cada afirmação com o `git diff`.

![Gestão interativa de contexto, sessões e comandos do Claude Code](/api/guides-media/automation/claude-code-agentic-programming-setup-guide/images/claude-code-agentic-programming-setup-guide-extra-02.webp)

### 5.2. Implementação da skill .claude/skills/truth/SKILL.md

Comandos customizados são formatados como skills. Crie o arquivo `.claude/skills/truth/SKILL.md` no seu projeto:

```markdown
---
description: "Verify Claude's most recent claims and edits against the actual codebase"
allowed-tools: ["Read", "Grep", "Glob", "Bash(git diff:*)"]
---

Re-examine everything you just told me in this conversation against what actually exists in the codebase right now. Specifically:

1. For every file you claim to have edited, read it again and confirm the change is actually present and matches what you described.
2. For every claim about existing code (a function's behavior, a config value, an import, a dependency version), verify it against the real file rather than your memory of reading it earlier in the session.
3. Run `git diff` and compare the actual diff against what you described changing.
4. Report back plainly: which claims checked out, which didn't, and exactly what the discrepancy was for anything that failed. Do not soften or hedge a discrepancy you find, state it directly.
```

Devido à isolação em `allowed-tools`, o comando fisicamente não tem permissão para alterar arquivos — ele opera exclusivamente como um auditor independente.

## 6. Subagentes e trabalho paralelo

Ao trabalhar em grandes projetos, surge o problema da sobrecarga de contexto: ler dezenas de arquivos e rodar testes pesados preenchem rapidamente a janela de contexto disponível.

### 6.1. Isolação de contexto e subagentes especializados (/agents)

Um subagente é uma instância separada do Claude Code com seu próprio contexto isolado, conjunto de ferramentas e prompt de sistema restrito. Ele resolve a subtarefa atribuída autonomamente e retorna à sessão principal apenas um resumo conciso.

```bash
# Відкрити інтерактивне меню субагентів усередині сесії
/agents
```

Você também pode declarar um subagente permanente no arquivo `.claude/agents/code-reviewer.md`:
- Conceda-lhe acesso somente de leitura (`Read`, `Grep`, `Glob`).
- Atribua um modelo rápido e econômico.
- Proíba alterações independentes no código, transformando-o em um revisor confiável.

### 6.2. Escalonamento de tarefas via worktree e execução em lote (/batch)

Para execução paralela de várias tarefas não relacionadas, o Claude Code suporta o modo Git Worktree e o comando `/batch`:
- **Árvores Paralelas (`--worktree`):** múltiplos agentes trabalham em cópias de trabalho isoladas do repositório, sem conflitos de bloqueio de arquivos.
- **Modo Lote (`/batch`):** execução de tarefas homogêneas de refatoração ou geração de documentação em fluxo de background.

## 7. Template pronto de CLAUDE.md e settings.json

Aqui estão arquivos de configuração testados em produção, que devem ser commitados no repositório do seu projeto para criar um ambiente de trabalho estável.

### 7.1. Template básico de memória CLAUDE.md

Salve o seguinte conteúdo no arquivo `CLAUDE.md` na raiz do seu repositório:

```markdown
# Project Context

### Stack
- Language/Framework: [Node.js, TypeScript, Next.js / Python, FastAPI]
- Styling: [Tailwind CSS]
- Database: [PostgreSQL / SQLite via Drizzle ORM]

### Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

### Conventions
- Strict TypeScript typing without `any`
- Functional React components with named exports
- Keep business logic in services or hooks, not inside UI components

### Before finishing any task
- Run test suite and confirm 100% pass rate
- Run `/truth` if the task involved modifying multiple files
```

### 7.2. Configuração de produção .claude/settings.json com hooks

Salve a configuração em `.claude/settings.json`:

```json
{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Read(**)"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Bash(rm -rf /*)",
      "Bash(sudo:*)",
      "Read(.env)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/block-dangerous-bash.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}
```

Para configurações locais específicas da sua máquina, utilize `.claude/settings.local.json`, adicionando-o ao `.gitignore`.

## 8. Conclusão e checklist de prontidão

Um ambiente de qualidade para programação agentic distingue-se do chat caótico pela configuração prévia de mecanismos de proteção, regras de memória e protocolos claros de verificação.

### 8.1. Princípios-chave da programação agentic

1. **O contexto deve estar limpo:** use `/compact` regularmente e delegue tarefas longas para subagentes.
2. **A memória deve estar registrada:** se uma regra é importante, fixe-a no `CLAUDE.md`, não a repita nas mensagens.
3. **As ações devem ser verificadas:** acione `/truth` e `/diff` antes de confirmar alterações no controle de versão.

### 8.2. Checklist de configuração inicial do workspace

| Etapa | Ação | Status de Prontidão |
| --- | --- | --- |
| **Instalação** | CLI nativa do Claude Code instalada e autenticação concluída | `Obrigatório` |
| **Memória do Projeto** | `CLAUDE.md` criado com descrição da stack, comandos e convenções | `Obrigatório` |
| **Permissões** | Listas `allow`, `ask` e `deny` formadas no `settings.json` | `Obrigatório` |
| **Hook de Formatação** | `PostToolUse` configurado para chamar automaticamente o Prettier | `Recomendado` |
| **Script de Segurança** | `block-dangerous-bash.py` conectado via `PreToolUse` | `Recomendado` |
| **Skill Customizada** | Comando de verificação `.claude/skills/truth/SKILL.md` criado | `Recomendado` |