🎯Lo que obtienes aquí
Saber EXACTAMENTE dónde colocar cada parte de la configuración de Claude Code. Pasar de «lo puse todo en CLAUDE.md» a tener settings, hooks, slash commands y permisos en los lugares correctos, y que funcionen.
Contenido detallado
📜 CLAUDE.md — jerarquía y alcance
CLAUDE.md existe en tres niveles, todos concatenados en el system prompt en orden. Si te equivocas en la jerarquía, las instrucciones del proyecto pueden sobrescribir las globales sin que te des cuenta, o peor aún: las instrucciones globales pueden ahogar las preferencias específicas del proyecto.
Los 3 niveles (del más genérico al más específico)
~/.claude/CLAUDE.md ← Global (você, todos os projetos) ↓ concatena ./CLAUDE.md ← Projeto (raiz) ↓ concatena ./src/api/CLAUDE.md ← Subdir (escopo desta pasta)
Cuando Claude abre un archivo en src/api/, mira los 3 archivos. Cuando abres uno en src/ui/, solo ves los 2 primeros (global + proyecto).
✓ Buen CLAUDE.md
- • Comandos LITERALES de build/test/lint al principio
- • Convenciones poco obvias (no repetir lo que el linter ya exige)
- • Enlaces a ADRs/runbooks detallados
- • Tono preferido en las respuestas
- • < 2KB (que quepa sin desplazarse)
✗ CLAUDE.md recargado
- • Repite toda la guía de estilo (que ya está en
.editorconfig) - • Historial del proyecto (irrelevante para el agente)
- • Política de RR. HH. (no es una instrucción de código)
- • Más de 50 KB de "buenas prácticas" genéricas
- • Documentación de bibliotecas internas
💡Regla de oro
Si el contenido puede ser leído bajo demanda (referencia), ponlo en references/ de una skill o en docs/ del proyecto. Si es siempre necesario (build commands, convenciones centrales), ponlo en CLAUDE.md. Por defecto: todo en references/, salvo que haya pruebas en contrario.
Conceptos clave
Global, proyecto, subdirectorio
Todo entra en el prompt
Lo específico prevalece
Que quepa sin desplazarse
📂 Estructura completa de la carpeta .claude/
La convención es estricta: nombre correcto, carpeta correcta o Claude no lo encuentra. Aquí tienes el mapa que puedes imprimir y pegar junto al monitor:
.claude/ ─ raiz do projeto (também ~/.claude/ global) ├── CLAUDE.md ─ instruções (pode estar na raiz do projeto) ├── settings.json ─ permissões, modelo, env, hooks ├── settings.local.json ─ override local (.gitignore) │ ├── agents/ ─ SUB-AGENTS em Markdown │ ├── code-reviewer.md │ └── doc-writer.md │ ├── skills/ ─ SKILLS (pastas com SKILL.md) │ └── my-skill/ │ ├── SKILL.md ─ frontmatter + body │ ├── scripts/ ─ scripts auxiliares │ ├── references/ ─ docs lazy-load │ └── assets/ ─ imagens/binários │ ├── commands/ ─ SLASH COMMANDS │ ├── review.md ─ /review │ ├── ship.md ─ /ship │ └── plugin/sub.md ─ /plugin:sub (namespaced) │ ├── hooks/ ─ scripts disparados em eventos │ ├── pre-commit.sh │ └── on-stop.sh │ └── output-styles/ ─ estilos de resposta └── concise.md
Global vs. proyecto: misma estructura
Todo esto existe igual en ~/.claude/ (tus preferencias, se aplica a todos los proyectos) y en ./.claude/ (específico de ese proyecto, versionado en git). Las skills/agents del proyecto tienen precedencia sobre los globales cuando coinciden los nombres.
⚠️Errores comunes de rutas
- • Colocar la skill en
.claude/skill/(singular) → Claude no ve - • SKILL.md en minúsculas → no se reconoce
- • Sub-agent en
.claude/sub-agents/→ tiene que seragents/ - • Slash command sin
.md→ ignorado
Conceptos clave
Nombre correcto, carpeta correcta
Global = proyecto
Proyecto > global
.local.json fuera
⚙️ settings.json — lo que controlas
Archivo JSON con configuración de comportamiento. Aquí reduces la fricción de permisos, cambias de modelo e inyectas hooks. Sobrescritura en cascada: usuario (~/.claude/) → proyecto (.claude/) → local (.claude/settings.local.json).
settings.json comentado (ejemplo 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"
}]
}]
}
}
user
~/.claude/settings.json
Tus preferencias en todos los proyectos. Modelo, tema, tono de voz.
project
.claude/settings.json
Va a git. Permisos y hooks que hereda todo el equipo.
local
.claude/settings.local.json
Sobrescritura local (.gitignore). Credenciales, entorno de desarrollo.
Conceptos clave
Cada uno sobrescribe
3 verbos de permiso
${cwd}, ${env}
Glob por herramienta
🪝 Hooks — la única forma de garantizar el comportamiento
Los hooks son comandos de shell ejecutados por el harness en eventos del agente. Se EJECUTAN; no dependen de que Claude recuerde hacerlo. Es la única forma de garantizar el determinismo ("siempre ejecutar lint antes del commit").
PreToolUse — antes de cada tool
Ejecuta antes de que Claude ejecute una herramienta. Puede bloquear (exit ≠ 0) o solo registrar.
Caso clásico: bloquear comandos peligrosos, registrar todo Bash, redirigir Read a un MCP indexado.
PostToolUse — después de cada tool
Ejecuta después. Recibe el output de la tool y puede anotar contexto para las siguientes rondas.
Caso clásico: ejecutar el formatter después de Edit, validar JSON después de Write, indexar el archivo modificado.
Detenerse: cuando el agente decide parar
Ejecuta cuando Claude termina el turno. Permite una verificación final.
Caso clásico: ejecutar pruebas, validar el diff antes de devolver el control, exigir una lista de verificación completa.
SessionStart y UserPromptSubmit
SessionStart: se ejecuta al abrir una sesión. UserPromptSubmit: con cada mensaje tuyo.
Caso clásico: SessionStart carga MCP, UserPromptSubmit inyecta contexto adicional (claude-mem, etc.).
💡Memory NO reemplaza a los hooks
Cuando pides «haz siempre X», Claude puede olvidarlo (no es determinístico). El hook SE EJECUTA. ¿Pediste ejecutar lint antes de cada commit? Hook. ¿Pediste registrar los comandos? Hook. La memoria de la skill ayuda, pero para garantizarlo, usa un hook.
Conceptos clave
Ejecuta siempre
0 correcto, ≠0 bloquea
Política de errores
Filtro por tool
⚡ Slash commands personalizados
Archivos markdown en .claude/commands/ que se convierten en comandos slash automáticamente. ¿Una tarea que repites? Se convierte en /comando y desaparece.
Ejemplo — .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 o /review src/api/auth.ts
✓ Buenos casos de slash
- •
/review— revisa el diff actual - •
/ship— checklist previo al merge - •
/test— genera pruebas para el archivo abierto - •
/explain— explica el fragmento seleccionado - •
/changelog— genera una entrada del CHANGELOG
✗ Mal uso de slash
- • Contenido enorme que debería ser una skill
- • Comando que solo tiene sentido para ti (usa el nivel de usuario, no el proyecto)
- • Sin allowed-tools (puede hacer todo)
- • Sin description (solo lo descubres al leer el archivo)
Conceptos clave
Argumentos del comando
Restringe la superficie
/plugin:sub
Ámbito del slash
🔐 Sistema de permisos — fricción vs. seguridad
Tres verbos: allow (libera), deny (bloquea), ask (pregunta). Una configuración mal calibrada genera fricción (preguntar por todo) o riesgo (permitir demasiado).
Modos de sesión
Independiente de los permisos de settings.json, puedes cambiar el MODO en vivo:
- default: usa exactamente el settings
- acceptEdits: acepta Edit/Write sin preguntar (útil en refactor)
- plan: solo planifica, nunca edita (útil en arquitectura)
- bypassPermissions: ignora todo (peligroso — solo para un entorno sandbox)
Conceptos clave
allow/deny/ask
Bash(cmd:*)
plan, acceptEdits
mcp__server__
🧪 Plan mode y output styles
Dos mecanismos para cambiar el comportamiento en vivo sin editar la configuración. Plan mode congela la edición (Claude planea, no actúa). Estilos de output cambian el tono de respuesta (conciso, detallado, explicativo, etc.).
📋 Modo Plan
Se activa con /plan o flag --plan. Claude lee, piensa, propone, pero no escribe ni ejecuta nada destructivo hasta que salgas del modo.
Cuándo usar: refactorización grande, decisión de arquitectura, hipótesis de bug. Quieres alinearte antes de actuar.
🎨 Estilos de salida
Se activa con /output-style concise. Se encuentran en .claude/output-styles/<nome>.md. Cambian el tono sin modificar el system prompt.
Built-in: concise (objetivo), verbose (detallado), explanatory (didáctico). Personalízalo creando el tuyo.
💡Combo práctico
¿Nueva tarea de arquitectura? Entra en /plan + /output-style verbose. Claude diseña todo, tú lo revisas y luego sales del plan mode para que lo ejecute.
Conceptos clave
No hace falta editar settings
Solo lee, no escribe
Tono de respuesta
.md en output-styles/
🎯Resumen del módulo
Siguiente módulo:
2.2 — Skills, sub-agentes y MCP en Claude Code