📋 settings.json — Anatomy and Location
🧠 Imagine It This Way: settings.json is Claude Code's technical configuration file. If CLAUDE.md is the "what to do," settings.json is the "how it works." It controls permissions, tools, and system behavior.
O settings.json exists at two levels: ~/.claude/settings.json (global) and .claude/settings.json (per project, inside the repo). The global config sets personal defaults; the local one fine-tunes them for the specific project.
The structure is plain JSON with keys like allowedTools, permissions, model e env. When both exist, the local one merges with the global one, and local keys take precedence.
~/.claude/settings.json ← global (seu usuario) .claude/settings.json ← projeto (commitavel no git) .claude/settings.local.json ← projeto local (NÃO commitar)
In one sentence: settings.json (global and local) controls how Claude Code works technically.
🚫 .claudeignore — What to Hide
🧠 Imagine It This Way: just as .gitignore tells git what not to version, .claudeignore tells Claude Code what not to read. It protects secrets, reduces noise, and speeds up the agent.
The file .claudeignore at the project root, it uses the same glob syntax as .gitignore. Everything listed there will be invisible to Claude Code: it won't read, index, or reference those files.
Recommended patterns: .env* (secrets), node_modules/ (dependencies), dist/ e build/ (artifacts), large binary files, and vendor folders. The less junk Claude Code sees, the faster and more accurately it works.
# Secrets .env* *.pem credentials*.json # Dependências e build node_modules/ dist/ build/ .next/ # Binários e media *.mp4 *.zip *.wasm
In one sentence: .claudeignore = .gitignore for the agent; protects secrets and reduces noise.
🔐 Permissions and allowedTools
🧠 Imagine It This Way: permissions control what Claude Code can do without asking for confirmation. You decide the balance between security (asking permission for everything) and speed (auto-approving safe operations).
By default, Claude Code asks for permission before performing potentially destructive operations: editing files, running bash commands, etc. You can configure allowedTools in settings.json to auto-approve specific tools.
Practical example: if you trust Claude Code to run npm test e npm run lint without asking, add these tools to allowedTools. This dramatically speeds up iterative workflows where the agent needs to run tests repeatedly.
{
"permissions": {
"allowedTools": [
"Read",
"Glob",
"Grep",
"Bash(npm test)",
"Bash(npm run lint)",
"Bash(git status)",
"Bash(git diff)"
]
}
}
In one sentence: allowedTools controls what runs automatically and what requires permission.
🌍 Environment Variables
🧠 Imagine It This Way: environment variables are the cleanest way to pass configuration without touching files. API key, default model, behavior flags: everything through env vars.
Claude Code recognizes several environment variables. The most important is ANTHROPIC_API_KEY, which defines the API key when you don’t use browser login. Other useful ones: CLAUDE_MODEL (default model), CLAUDE_CODE_USE_BEDROCK (use AWS Bedrock), CLAUDE_CODE_USE_VERTEX (use Google Vertex).
To configure per project without committing secrets, use a file .env local (and add .env* in .claudeignore). Or export the variables in your .bashrc/.zshrc to apply globally.
💡 Never Commit API Keys
Use a local .env + .claudeignore. Or better, use browser login (claude with no env vars) and let Anthropic handle authentication. That way, there's no key to leak.
In one sentence: ANTHROPIC_API_KEY, CLAUDE_MODEL, and other env vars configure things without touching files.
👤 Project Profiles
🧠 Imagine It This Way: different projects have different needs. A personal project can auto-approve everything. A corporate project may require confirmation for each operation. Local settings allow this.
The project-level settings.json (.claude/settings.json) lets each repository have its own rules. You can commit this file to git so the whole team uses the same Claude Code settings.
Already .claude/settings.local.json is for personal overrides that shouldn’t be shared (such as more permissive allowedTools for those who already know the project). It should never go into git.
In one sentence: project-level settings.json + personal settings.local.json = configuration by context.
🔀 Model Override and Providers
🧠 Imagine It This Way: you’re not locked into a single model. Claude Code supports switching models per session or per command, and even using alternative providers like AWS Bedrock and Google Vertex.
Switching models is simple: use --model on the command line, /model within the session, or CLAUDE_MODEL as an environment variable. The available models are from the Claude family: Opus (most capable), Sonnet (balanced), Haiku (fast and inexpensive).
For enterprise use, Claude Code supports AWS Bedrock e Google Vertex AI as providers. This lets you use Claude Code with your company's credentials and compliance requirements, without going through Anthropic's direct API.
# 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
In one sentence: use --model, /model, or env vars to switch models; Bedrock and Vertex for enterprise use.
🧾 Module Summary
Next module:
1.5 — Memory and Persistent Context: how memory works and how not to lose context.