🛠️ Configuration: settings.json and Permissions

O settings.json is Claude Code's central configuration point. It controls what Claude can do, which tools are available, automation hooks, and default behaviors.

// ~/.claude/settings.json (user global)
{
  "permissions": {
    "allow": [
      "Read(**)",
      "Bash(git *)",
      "Bash(npm *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  },
  "model": "claude-sonnet-4-5"
}

Each tool Claude uses can be configured in one of three states. The default state (with no config) is ask — Claude asks before executing.

"allow": [
  "Read(**)",
  "Bash(git *)"
]

// sem config =
// comportamento ask
// para Write, Edit,
// Bash genérico

"deny": [
  "Bash(rm *)",
  "Bash(drop *)",
  "Bash(sudo *)"
]

# Ferramentas disponíveis para permissão:
Read(**)          # Leitura de qualquer arquivo
Read(src/**)      # Leitura apenas em src/
Write(**)         # Escrita em qualquer lugar
Write(src/**)     # Escrita apenas em src/
Edit(**)          # Edição de arquivos
Bash(*)           # Qualquer comando bash
Bash(git *)       # Apenas comandos git
Bash(npm test)    # Apenas npm test
Bash(npm *)       # Qualquer comando npm
mcp__*(*)         # Qualquer ferramenta MCP

Here's the recommended configuration for local development. Production and CI/CD have different rules.

{
  "permissions": {
    "allow": [
      "Read(**)",                   // leitura sempre segura
      "Edit(src/**)",              // edição dentro de src/
      "Write(src/**)",             // criação em src/
      "Bash(git status)",          // git somente leitura
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(npm test)",            // rodar testes
      "Bash(npm run lint)",
      "Bash(npm run build)"
    ],
    "deny": [
      "Bash(rm -rf*)",             // nunca deletar recursivo
      "Bash(sudo*)",               // sem sudo
      "Bash(git push*)",           // push requer revisão humana
      "Bash(git reset --hard*)"    // destrutivo
    ]
  }
}

In addition to settings.json, command-line flags control behavior for specific sessions. Useful for automation, CI/CD, and scripts.

claude  # abre REPL com confirmações

claude --print "Gere um Dockerfile para Node.js 20"
# Output vai para stdout, sem REPL

claude --dangerously-skip-permissions
# ⚠️  NUNCA usar em produção ou máquinas compartilhadas

# Rodar tarefa específica em pipeline
claude --print --model claude-sonnet-4-5 \
  "Analise os testes que falharam e sugira correções"

# Modo não-interativo com permissões via settings
# (settings.json já tem allow para as ações necessárias)
echo "rode os testes e corrija falhas" | claude --print

# Com timeout (útil em pipelines)
timeout 120 claude --print "faça code review deste PR"

O CLAUDE.md is read automatically by Claude in every session. It's the project "briefing" — context, conventions, and special commands. Invest in it wisely.

# CLAUDE.md — meu-projeto

## Sobre o projeto
API REST em Node.js + Express + TypeScript.
Banco de dados: PostgreSQL com Prisma ORM.
Deploy: Railway. Domínio: api.meu-projeto.com

## Stack e versões
- Node.js 20 LTS
- TypeScript 5.3
- Express 4.18
- Prisma 5.x

## Convenções de código
- Arquivos em camelCase, pastas em kebab-case
- Imports absolutos via tsconfig paths (@/src/...)
- Testes com Vitest, não Jest
- Commits em português, formato: feat/fix/chore: mensagem

## Comandos úteis
- npm run dev     → servidor local na porta 3000
- npm test        → roda testes
- npm run migrate → aplica migrations Prisma

## Regras importantes
- NUNCA fazer push direto para main
- NUNCA modificar arquivos em /migrations manualmente
- Sempre rodar testes antes de commitar

# Dentro do REPL, gera CLAUDE.md a partir do projeto
/init

# Claude analisa o projeto e gera rascunho
# → revise e ajuste o arquivo gerado
# → commite no repo para toda a equipe usar

Separating global (user) settings from project settings lets you personal defaults that don't interfere in other projects.

# ~/.claude/settings.json (global — meu default pessoal)
{
  "permissions": {
    "allow": ["Read(**)", "Bash(git status)", "Bash(git diff*)"]
  },
  "model": "claude-sonnet-4-5"
}

# ~/projetos/app-pessoal/.claude/settings.json
// mais permissivo — projeto só meu
{
  "permissions": {
    "allow": ["Read(**)", "Write(**)", "Edit(**)", "Bash(npm *)"]
  }
}

# ~/projetos/app-trabalho/.claude/settings.json
// mais restritivo — código de produção
{
  "permissions": {
    "allow": ["Read(**)", "Edit(src/**)", "Bash(npm test)"],
    "deny": ["Bash(git push*)", "Bash(rm *)"]
  }
}