📋 settings.json — anatomia e localização
🧠 Imagine assim: settings.json e o arquivo de configuração tecnica do Claude Code. Se CLAUDE.md e o "o que fazer", settings.json e o "como funcionar". Ele controla permissões, ferramentas e comportamento do sistema.
O settings.json existe em dois niveis: ~/.claude/settings.json (global) e .claude/settings.json (por projeto, dentro do repo). O global define defaults pessoais; o local refina para o projeto especifico.
A estrutura e JSON puro com chaves como allowedTools, permissions, model e env. Quando ambos existem, o local faz merge com o global, e chaves locais prevalecem.
~/.claude/settings.json ← global (seu usuario) .claude/settings.json ← projeto (commitavel no git) .claude/settings.local.json ← projeto local (NÃO commitar)
Em 1 frase: settings.json (global e local) controla como o Claude Code funciona tecnicamente.
🚫 .claudeignore — o que esconder
🧠 Imagine assim: assim como .gitignore diz ao git o que nao versionar, .claudeignore diz ao Claude Code o que nao ler. Protege secrets, reduz ruido e acelera o agente.
O arquivo .claudeignore na raiz do projeto usa a mesma sintaxe glob do .gitignore. Tudo que estiver listado ali sera invisivel para o Claude Code: ele nao vai ler, indexar nem referenciar esses arquivos.
Padrões recomendados: .env* (secrets), node_modules/ (dependências), dist/ e build/ (artefatos), arquivos binarios grandes, e pastas de vendor. Quanto menos lixo o Claude Code vê, mais rapido e preciso ele trabalha.
# Secrets .env* *.pem credentials*.json # Dependências e build node_modules/ dist/ build/ .next/ # Binários e media *.mp4 *.zip *.wasm
Em 1 frase: .claudeignore = .gitignore para o agente; protege secrets e reduz ruido.
🔐 Permissões e allowedTools
🧠 Imagine assim: permissões controlam o que o Claude Code pode fazer sem pedir confirmação. Voce decide o equilibrio entre segurança (pedir permissão pra tudo) e velocidade (auto-aprovar operações seguras).
Por padrao, o Claude Code pede permissão antes de executar operações potencialmente destrutivas: editar arquivos, rodar comandos bash, etc. Voce pode configurar allowedTools no settings.json para auto-aprovar ferramentas especificas.
Exemplo pratico: se voce confia que o Claude Code pode rodar npm test e npm run lint sem perguntar, adicione essas ferramentas em allowedTools. Isso acelera drasticamente workflows iterativos onde o agente precisa rodar testes repetidamente.
{
"permissions": {
"allowedTools": [
"Read",
"Glob",
"Grep",
"Bash(npm test)",
"Bash(npm run lint)",
"Bash(git status)",
"Bash(git diff)"
]
}
}
Em 1 frase: allowedTools controla o que roda automaticamente vs o que pede permissão.
🌍 Variaveis de ambiente
🧠 Imagine assim: variaveis de ambiente sao o jeito mais limpo de passar configuração sem tocar em arquivos. API key, modelo padrao, flags de comportamento: tudo via env vars.
O Claude Code reconhece diversas variaveis de ambiente. A mais importante e ANTHROPIC_API_KEY, que define a chave de API quando voce nao usa login via browser. Outras uteis: CLAUDE_MODEL (modelo padrao), CLAUDE_CODE_USE_BEDROCK (usar AWS Bedrock), CLAUDE_CODE_USE_VERTEX (usar Google Vertex).
Para configurar por projeto sem commitar secrets, use um arquivo .env local (e adicione .env* no .claudeignore). Ou exporte as variaveis no seu .bashrc/.zshrc para que valham globalmente.
💡 Nunca commite API keys
Use .env local + .claudeignore. Ou melhor: use o login via browser (claude sem nenhuma env var) e deixe a autenticação com a Anthropic. Assim nao existe key para vazar.
Em 1 frase: ANTHROPIC_API_KEY, CLAUDE_MODEL e outras env vars configuram sem tocar em arquivos.
👤 Perfis de projeto
🧠 Imagine assim: projetos diferentes tem necessidades diferentes. Um projeto pessoal pode auto-aprovar tudo. Um projeto corporativo pode exigir confirmação para cada operação. Settings local permite isso.
O settings.json por projeto (.claude/settings.json) permite que cada repositorio tenha suas proprias regras. Voce pode commitar esse arquivo no git para que toda a equipe use as mesmas configurações do Claude Code.
Ja o .claude/settings.local.json e para overrides pessoais que nao devem ser compartilhados (como allowedTools mais permissivos para quem ja conhece o projeto). Ele nunca deve ir pro git.
Em 1 frase: settings.json por projeto + settings.local.json pessoal = configuração por contexto.
🔀 Model override e providers
🧠 Imagine assim: voce nao esta preso a um unico modelo. O Claude Code suporta trocar de modelo por sessão, por comando, e ate usar providers alternativos como AWS Bedrock e Google Vertex.
Trocar de modelo e simples: use --model na linha de comando, /model dentro da sessão, ou CLAUDE_MODEL como variavel de ambiente. Os modelos disponiveis sao os da familia Claude: Opus (mais capaz), Sonnet (equilibrio), Haiku (rapido e barato).
Para uso corporativo, o Claude Code suporta AWS Bedrock e Google Vertex AI como providers. Isso permite usar o Claude Code com as credenciais e compliance da sua empresa, sem passar pela API direta da Anthropic.
# por comando claude --model opus # na sessão interativa /model sonnet # via env var export CLAUDE_MODEL=opus # usando Bedrock export CLAUDE_CODE_USE_BEDROCK=1 # usando Vertex AI export CLAUDE_CODE_USE_VERTEX=1
Em 1 frase: use --model, /model ou env vars para trocar modelo; Bedrock e Vertex para uso corporativo.
🧾 Resumo do Modulo
Proximo modulo:
1.5 — Memory e Contexto Persistente: como a memória funciona e como nao perder contexto.