Domínio 3 — Claude Code Configuration & Workflows · Lição 2 de 6

settings.json, permission modes e hooks

Objetivos de aprendizagem

• Distinguir os três arquivos de configuração: ~/.claude/settings.json (usuário), .claude/settings.json (projeto, versionado) e .claude/settings.local.json (local, não versionado) — e a precedência entre eles.
• Configurar permissions com listas allow/deny e um defaultMode.
• Explicar os permission modes (default, acceptEdits, plan, bypassPermissions, entre outros).
• Configurar hooks (PreToolUse, PostToolUse, Stop...) para validação, bloqueio, formatação e notificação.
• Justificar quando usar hooks (garantia determinística) em vez de instruções no CLAUDE.md (aderência probabilística).

Os três settings.json e a precedência

Na resolução, configurações mais específicas prevalecem: políticas gerenciadas da organização (quando existem) vêm acima de tudo; depois o local sobrepõe o de projeto, que sobrepõe o de usuário. O paralelo com a lição 1 é direto: o que o time inteiro deve receber vai no arquivo de projeto versionado; o que é seu fica no de usuário ou no local.

Permissions: allow, deny e defaultMode

O bloco permissions controla o que o Claude Code pode fazer sem perguntar (allow) e o que é proibido mesmo que aprovado (deny). As regras usam o formato Ferramenta(padrão):

{
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Bash(npm run test:*)",
      "Bash(npm run lint)",
      "Read"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Read(.env*)",
      "Bash(git push --force*)"
    ]
  }
}

Os permission modes definem a postura padrão da sessão:

• default — pede confirmação para ações sensíveis (edições, comandos não permitidos).
• acceptEdits — auto-aprova edições de arquivos no projeto (bom para fluxo de implementação intenso).
• plan — somente leitura: explora e planeja, sem editar até o plano ser aprovado (lição 4).
• bypassPermissions — não pergunta nada; reservado a ambientes isolados (containers/CI sandbox), nunca à máquina de trabalho com dados sensíveis.

Hooks: garantia determinística

Hooks são comandos do seu sistema executados automaticamente em eventos do ciclo de vida do Claude Code. A distinção central — cobrada repetidamente no exame, inclusive fora deste domínio — é:

Principais eventos:

Exemplo real: settings.json de projeto com hooks

Formatação automática após toda edição (PostToolUse com matcher de ferramenta) e um guarda de segurança (PreToolUse em Bash):

{
  "permissions": {
    "defaultMode": "acceptEdits",
    "deny": ["Read(.env*)"]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "python .claude/hooks/block_force_push.py" }
        ]
      }
    ]
  }
}

O hook recebe um JSON no stdin com os dados do evento (incluindo tool_input). Um hook PreToolUse pode negar a ação devolvendo uma decisão de permissão no stdout — o bloqueio acontece no harness, não depende de o modelo "concordar":

#!/usr/bin/env python3
"""Hook PreToolUse: bloqueia force push, decisao devolvida ao harness."""
import json
import sys

payload = json.load(sys.stdin)
command = payload.get("tool_input", {}).get("command", "")

if "push --force" in command or "push -f" in command:
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "deny",
            "permissionDecisionReason": "Force push bloqueado pela politica do time."
        }
    }))

sys.exit(0)

flowchart LR
    M[Claude decide chamar Bash] --> H1{Hook PreToolUse}
    H1 -- deny --> B[Chamada bloqueada +
motivo devolvido ao modelo]
    H1 -- allow/sem decisão --> X[Ferramenta executa]
    X --> H2[Hook PostToolUse
ex.: prettier no arquivo editado]
  

Hook ou instrução? O critério de decisão

• "Prefira nomes descritivos de variáveis" → CLAUDE.md: orientação de estilo, tolerante a desvio.
• "Nunca commitar em main", "nunca ler .env", "todo arquivo editado sai formatado" → hook/permissions: exigência com consequência, precisa de garantia.
• Time observa que "o Claude às vezes esquece de rodar o linter" mesmo com a instrução no CLAUDE.md → mover de instrução para hook PostToolUse é a correção estrutural, não reescrever a instrução "com mais ênfase".

Pegadinhas da prova

• Distrator típico: reforçar o prompt ("deixe MUITO claro que é obrigatório") quando o cenário exige garantia — enforcement por prompt continua probabilístico; a resposta é hook ou deny.
• Distrator típico: colocar configuração do time em settings.local.json — o local é gitignored; padrão de time vai em .claude/settings.json versionado.
• Distrator típico: confundir a direção da precedência — o local (mais específico) sobrepõe o de projeto, que sobrepõe o de usuário.
• Distrator típico: usar PostToolUse para impedir uma ação — depois que a ferramenta rodou, já rodou; bloqueio é PreToolUse (ou deny em permissions).
• Distrator típico: bypassPermissions como "conveniência" na máquina do desenvolvedor — só é aceitável em ambiente isolado/descartável.

Resumo em 5 linhas

Documentação oficial

• Claude Code settings
• Hooks reference
• Get started with hooks
• Permission modes

Questões de fixação