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 Збільшити

Visão geral e navegação nos slash commands embutidos do Claude Code

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:

/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.
/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.
/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 Збільшити

Gestão interativa de contexto, sessões e comandos do Claude Code

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

O contexto deve estar limpo: use /compact regularmente e delegue tarefas longas para subagentes.
A memória deve estar registrada: se uma regra é importante, fixe-a no CLAUDE.md, não a repita nas mensagens.
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`