📘 CLAUDE.md e a pasta .claude/

Os 3 níveis (do mais genérico ao mais específico)

~/.claude/CLAUDE.md         ← Global (você, todos os projetos)
   ↓ concatena
./CLAUDE.md                 ← Projeto (raiz)
   ↓ concatena
./src/api/CLAUDE.md         ← Subdir (escopo desta pasta)

Quando Claude abre um arquivo em src/api/, vê os 3 arquivos. Quando abre um em src/ui/, vê só os 2 primeiros (global + projeto).

Global vs projeto — mesma estrutura

Tudo isso existe igual em ~/.claude/ (suas preferências, vale em todo projeto) e em ./.claude/ (específico desse projeto, commitado no git). Skills/agents do projeto têm precedência sobre os globais quando nome coincide.

settings.json comentado (exemplo real)

{
  "model": "claude-opus-4-6",         // modelo padrão da sessão
  "includeCoAuthoredBy": true,         // Co-Authored-By em commits

  "permissions": {
    "allow": [
      "Bash(ls:*)", "Bash(cat:*)",           // libera leitura
      "Bash(git status:*)", "Bash(git log:*)", // git read-only
      "Read", "Grep", "Glob"                   // tools básicas
    ],
    "deny": [
      "Bash(rm -rf:*)",                       // nunca
      "Bash(curl:* | sh)"                     // pipe pra shell = não
    ],
    "ask": [
      "Bash(git push:*)",                     // sempre confirma
      "Write", "Edit"                          // escrita = confirma
    ]
  },

  "env": {
    "CLAUDE_PROJECT_DIR": "${cwd}",
    "NODE_ENV": "development"
  },

  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "./scripts/log-bash.sh"
      }]
    }]
  }
}

Exemplo — .claude/commands/review.md

---
description: Revisa o diff atual procurando bugs de correção
allowed-tools: Bash(git diff:*), Read, Grep
---

Revise o diff atual da branch.

Procure:
- Bugs de correção (não estilo)
- Casos não tratados (null, vazio, edge)
- Vulnerabilidades comuns (SQLi, XSS, path traversal)

Use \`$ARGUMENTS\` se passado para focar em arquivo específico.

Retorne uma lista numerada de findings + severity.

Uso: /review ou /review src/api/auth.ts

Modos de sessão

Independente das permissões do settings.json, você pode trocar o MODO ao vivo:

• default: usa exatamente o settings
• acceptEdits: aceita Edit/Write sem perguntar (útil em refactor)
• plan: só planeja, nunca edita (útil em arquitetura)
• bypassPermissions: ignora tudo (perigoso — só pra ambiente sandbox)