Convierte a Claude Code en una herramienta hecha a medida: reglas que se cumplen siempre, especialistas a los que delegar, procedimientos reutilizables, conexión con tus sistemas y aislamiento real.
Lección 3.1
Hooks: el ciclo de vida
Un hook ejecuta tu script, un request HTTP, una herramienta MCP, un prompt o un subagente cuando Claude Code llega a un evento del ciclo de vida. La diferencia clave: una instrucción en CLAUDE.md es un pedido; un hook es una garantía. Siempre se dispara en su evento y no cuesta contexto salvo que devuelva texto.
Simulador de ciclo de vida
Eventos más usados
Evento
Cuándo se dispara
¿Bloquea?
SessionStart
Al iniciar o retomar (matchers: startup, resume, clear, compact)
No; su stdout se agrega al contexto
UserPromptSubmit
Antes de procesar tu prompt
Sí
PreToolUse
Antes de una herramienta
Sí
PermissionRequest
Cuando Claude Code va a pedirte permiso
Puede aprobar o denegar
PostToolUse
Después de que la herramienta tuvo éxito
No puede deshacer; sí puede dar feedback
Stop / SubagentStop
Cuando Claude o un subagente termina de responder
Sí: obliga a seguir trabajando
Notification
Cuando Claude espera input o permiso
No
PreCompact / PostCompact
Alrededor de la compactación
—
ConfigChange
Cuando cambia un archivo de configuración durante la sesión
Sí
SessionEnd
Al terminar la sesión
No
Hay más de 30 eventos en total, incluidos PostToolUseFailure, SubagentStart, TaskCreated, TaskCompleted, InstructionsLoaded, CwdChanged, FileChanged, WorktreeCreate y Elicitation.
Lección 3.2
Hooks: códigos de salida y JSON
Un hook de tipo command recibe el evento como JSON por stdin y responde con su código de salida, stdout y stderr. Prueba combinaciones:
Probador de salida de hooks
El error más comúnexit 1 no bloquea: es un error no bloqueante y la acción sigue. Para imponer una política, usa exit 2 (con el motivo en stderr) o exit 0 con JSON. Elige un enfoque por hook.
Salida JSON estructurada
stdout de un hook PreToolUse
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Usa rg en vez de grep"
}
}
permissionDecision: "allow" salta el prompt (las reglas deny y ask siguen aplicando), "deny" cancela y le da el motivo a Claude, "ask" muestra el prompt normal.
Si varios hooks responden, gana la decisión más restrictiva: deny > defer > ask > allow. Todos los hooks corren en paralelo hasta terminar.
PostToolUse y Stop usan "decision": "block" en el nivel superior; PermissionRequest usa hookSpecificOutput.decision.behavior.
Para inyectar contexto desde UserPromptSubmit, usa hookSpecificOutput.additionalContext. Si lo pones en el nivel superior, se ignora sin aviso.
Un PreToolUse puede reescribir los argumentos de la herramienta con updatedInput.
Tipos de hook y timeouts
Tipo
Qué hace
Timeout default
command
Corre un comando de shell
10 min (30 s en UserPromptSubmit)
http
POST del JSON a una URL; útil para auditoría centralizada
10 min
mcp_tool
Llama una herramienta de un servidor MCP
10 min
prompt
Un modelo decide con {"ok": true/false, "reason": "…"}
30 s
agentexperimental
Un subagente verifica con herramientas (hasta 50 turnos)
60 s
Lección 3.3
Construye un hook: recetas
Los hooks viven en settings con tres niveles: evento → grupo con matcher → handlers. El matcher filtra por nombre de herramienta (Edit|Write, Bash, mcp__github__.* como regex); if filtra por argumentos con sintaxis de permisos.
Constructor de hooks
Script de bloqueo de ejemplo (.claude/hooks/block-rm.sh):
bash
#!/bin/bash
command=$(jq -r '.tool_input.command' <<<"$(cat)")
if [[ "$command" == rm* ]]; then
echo "Bloqueado: no se permite rm" >&2 # stderr = feedback para Claude
exit 2 # 2 = bloquear
fi
exit 0 # 0 = sin objeción
Dónde van: ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, managed settings, plugins (hooks/hooks.json) o el frontmatter de skills y subagentes. Todos se suman: si un hook está en dos lugares, corre dos veces.
Usa ${CLAUDE_PROJECT_DIR} en las rutas para que funcionen desde cualquier subdirectorio.
/hooks muestra lo configurado. Para depurar, mira el log de debug: qué hooks calzaron, su código de salida y su salida.
Claude puede escribirlos por ti: "escribe un hook que corra eslint después de cada edición".
Un subagente es un trabajador con su propia ventana de contexto, su propio system prompt y su propio set de herramientas. Puede leer decenas de archivos; a tu conversación solo vuelve un resumen. Como el contexto es tu recurso más escaso, esto es lo que los hace valiosos.
Qué carga al iniciar (no-fork)
Su propio system prompt (no el de Claude Code) más detalles del entorno.
El mensaje de tarea que Claude le escribe. No ve tu historial ni los archivos ya leídos.
Toda la jerarquía de CLAUDE.md y un snapshot de git (Explore y Plan omiten ambos).
El contenido completo de las skills listadas en su campo skills.
No hereda estilos de salida ni tu auto memory.
Un fork es distinto: copia tu conversación completa. Lánzalo con /subtask <tarea> (corre en segundo plano y devuelve el resultado). /fork copia toda la sesión a una sesión en segundo plano nueva.
Subagentes incluidos
Nombre
Propósito
Explore
Búsqueda y análisis rápido de solo lectura
Plan
Investigación de solo lectura en plan mode
general-purpose
Tareas de varios pasos que exploran y modifican
claude-code-guide
Responde preguntas sobre Claude Code
statusline-setup
Configura la status line
Primer plano y segundo plano
Sin configurar nada, los subagentes que Claude lanza desde la conversación principal corren en segundo plano: sigues trabajando y sus prompts de permiso aparecen en tu sesión indicando qué subagente pregunta. Los de primer plano bloquean la conversación. /tasks lista y administra todo lo que corre en segundo plano; Ctrl+B manda tareas en curso al fondo.
prompts
Usa subagentes para investigar cómo nuestro sistema de auth maneja el refresh de tokens
Investiga los módulos de auth, base de datos y API en paralelo con subagentes separados
Usa un subagente para correr la suite de tests y reportar solo los que fallan con su error
Usa el subagente code-reviewer para encontrar problemas de rendimiento y luego el optimizer para arreglarlos
Límites: 20 subagentes concurrentes (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS) y hasta 3 niveles de anidación (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH).
Claude retoma un subagente con SendMessage usando su nombre; conserva todo su historial.
Desde la v2.1.198, /agents ya no abre un panel: crea y edita subagentes pidiéndoselo a Claude o editando los archivos.
Lección 3.5
Construye un subagente
Un subagente es un Markdown con frontmatter YAML; el cuerpo es su system prompt. Ubicaciones, de mayor a menor prioridad: managed, flag --agents, .claude/agents/ (proyecto), ~/.claude/agents/ (personal) y plugins.
Constructor de subagentes
Campo
Para qué
name, description
Requeridos. La descripción decide cuándo Claude delega; "use proactively" lo incentiva
tools / disallowedTools
Allowlist / denylist. Agent(worker, researcher) limita qué subagentes puede lanzar
model, effort
sonnet, opus, haiku, fable, ID completo o inherit
skills
Skills precargadas completas al iniciar
memory
Memoria persistente: .claude/agent-memory/<nombre>/ (project), ~/.claude/agent-memory/ (user) o local
isolation: worktree
Corre en un worktree temporal de git
hooks, mcpServers
Hooks y servidores MCP solo mientras el subagente está activo
maxTurns, background, color
Límite de turnos, forzar segundo plano, color en la UI
Invócalos con lenguaje natural ("usa el subagente code-reviewer…"), con @agent-code-reviewer (garantizado) o como agente de toda la sesión: claude --agent code-reviewer. Los campos mal escritos se ignoran sin aviso; los nombres compuestos usan camelCase.
Lección 3.6
Skills: estructura e invocación
Una skill es una carpeta con un SKILL.md (frontmatter + instrucciones) y archivos de apoyo opcionales. Es la extensión más flexible: puede ser referencia (tu guía de estilo de API) o acción (/deploy corre tu checklist). Claude ve solo nombre y descripción hasta que la usa; recién entonces carga el contenido completo.
Ubicación
Ruta
Alcance
Empresa
directorio de managed settings
Toda la organización
Personal
~/.claude/skills/<nombre>/SKILL.md
Todos tus proyectos
Proyecto
.claude/skills/<nombre>/SKILL.md
Este repo
Plugin
<plugin>/skills/<nombre>/SKILL.md
Se invoca /plugin:skill
Ante nombres repetidos: empresa gana sobre personal, y personal sobre proyecto. El formato antiguo .claude/commands/deploy.md sigue funcionando, pero las skills son las recomendadas porque admiten archivos de apoyo.
Quién puede invocarla
Frontmatter
Tú
Claude
Descripción en contexto
(por defecto)
Sí
Sí
Siempre
disable-model-invocation: true
Sí
No
No (costo cero hasta que la invoques)
user-invocable: false
No
Sí
Siempre
Usa disable-model-invocation: true para skills con efectos secundarios (deploy, commit, push): ahorras contexto y solo tú las disparas.
La descripción más when_to_use se trunca a 1.536 caracteres en el listado: pon el caso de uso clave primero.
Mantén SKILL.md bajo 500 líneas; mueve el detalle a archivos de apoyo y referéncialos para que Claude sepa cuándo leerlos.
Los cambios a SKILL.md aplican en vivo; una carpeta skills/ nueva requiere /reload-skills.
/skills lista y filtra (con t ordenas por tokens); /skill-doctor muestra qué skills cuestan contexto y cuánto se usan.
Lección 3.7
Skills avanzadas
Constructor de skills
Sustituciones
Placeholder
Se expande a
$ARGUMENTS
Todo lo que escribiste tras el comando. Si no hay placeholder, se agrega ARGUMENTS: … al final
$0, $1… o $nombre
Argumento por posición, o por nombre si declaras arguments. /migrar SearchBar JS TS llena $0, $1, $2
${CLAUDE_SKILL_DIR}
Carpeta de la skill. Úsalo en el contenido y en allowed-tools para correr scripts propios sin prompt
${CLAUDE_PROJECT_DIR}, ${CLAUDE_SESSION_ID}
Raíz del proyecto, ID de sesión
Inyección dinámica con !`comando`
Una línea !`git diff HEAD` corre antes de que Claude vea la skill y su salida reemplaza el placeholder. Si el comando falla, aborta toda la invocación: agrega || true para tolerar fallos. Los comandos pasan por tus reglas de permiso.
Más controles
context: fork + agent: Explore corre la skill en un subagente: el contenido se vuelve su tarea y no ve tu historial. Úsalo solo para skills con una tarea explícita.
paths limita la autoactivación a ciertos archivos; model y effort cambian el modelo solo para ese turno.
allowed-tools preaprueba herramientas solo para el turno que invoca la skill; no restringe las demás.
skillOverrides en settings controla la visibilidad sin editar el archivo: "on", "name-only", "user-invocable-only", "off".
Skills incluidas
/code-review, /simplify, /verify, /run, /batch, /debug, /loop, /doctor, /claude-api, /fewer-permission-prompts, /update-config y más. Si tu proyecto tiene una skill llamada verify o simplify, Claude la corre antes de cada commit (salvo cambios de docs o tests).
El Model Context Protocol conecta a Claude Code con sistemas externos: issue trackers, bases de datos, monitoreo, Figma, Notion. Cada servidor expone herramientas que Claude puede llamar, nombradas mcp__servidor__herramienta.
Constructor de comando MCP
Scope
Se guarda en
Compartido
local (default)
~/.claude.json bajo la ruta del proyecto
No
project
.mcp.json en la raíz del repo
Sí, vía git (requiere aprobación al primer uso)
user
~/.claude.json
No, pero en todos tus proyectos
Precedencia por nombre: local → project → user → plugins → conectores de claude.ai. No se mezclan entre scopes. El separador -- divide las opciones de Claude del comando del servidor: todo lo que va después pasa intacto.
Se expanden ${VAR} y ${VAR:-default} en command, args, env, url y headers, así no commiteas secretos. Las entradas remotas necesitan type; sin él se interpretan como stdio y se omiten.
Lección 3.9
MCP: autenticación, límites y seguridad
OAuth:/mcp muestra el estado de cada servidor y lanza el flujo en el navegador; los tokens se renuevan solos. Desde la shell: claude mcp login <nombre> (con --no-browser por SSH).
Gestión:claude mcp list, claude mcp get notion, claude mcp remove notion. Dentro de la sesión, /mcp desactiva servidores sin borrarlos.
Tool search: activo por defecto. Solo los nombres de herramientas ocupan contexto; los schemas completos se cargan cuando Claude necesita una. Se desactiva con ENABLE_TOOL_SEARCH=false.
Límites de salida: 25.000 tokens por respuesta de herramienta por defecto (advertencia desde 10.000), ajustable con MAX_MCP_OUTPUT_TOKENS. MCP_TIMEOUT controla el arranque.
Llamadas largas: pasadas de 2 minutos se mueven a tareas en segundo plano.
MCP vs CLI vs skills
CLI primeroHerramientas como gh, aws, gcloud o sentry-cli son lo más eficiente en contexto: no agregan listado de herramientas.
MCPCuando no hay CLI, o necesitas autenticación gestionada por el servidor y herramientas hechas para ese sistema.
Skill + MCPMCP da la conexión; una skill enseña a usarla bien (tu schema, tus patrones de consulta).
SeguridadVerifica que confías en cada servidor antes de conectarlo. Los que traen contenido externo te exponen a prompt injection. Para bases de datos, usa un usuario de solo lectura. Las variables con nombre de credencial (como ANTHROPIC_API_KEY) se leen vacías en URLs y headers remotos, para que un .mcp.json ajeno no las exfiltre.
Lección 3.10
Sandbox de Bash
El sandbox es una barrera que el sistema operativo aplica a los comandos de shell que corre Claude y a los procesos que estos lanzan. Tú defines qué archivos y dominios pueden alcanzar. Como la barrera la impone el SO, Claude Code puede correr comandos sandboxeados sin pedirte aprobación uno por uno. Está apagado por defecto: actívalo con /sandbox.
Acceso
Por defecto
Se cambia con
Escritura
Directorio de trabajo, temp por usuario y directorios agregados
filesystem.allowWrite
Lectura
Casi toda la máquina, incluidos ~/.ssh y credenciales
filesystem.denyRead
Red
Sin salida directa; un proxy local revisa cada host contra tu allowlist, que empieza vacía
Plataformas: macOS usa Seatbelt (nada que instalar); Linux y WSL2 usan bubblewrap y socat. En Windows nativo los comandos corren sin sandbox: usa WSL2.
Modo auto-allow: los comandos que corren dentro del sandbox se aprueban solos. Las reglas deny, los ask por contenido (como Bash(git push *)) y los rm sobre rutas críticas siguen aplicando.
Escape hatch: si un comando falla dentro del sandbox, Claude puede pedir reintentarlo fuera; según tu modo, se te pregunta o lo evalúa el clasificador. excludedCommands corre ciertas herramientas siempre fuera.
Qué no cubre: las herramientas Read, Edit, Write y WebFetch (usan reglas de permiso), hooks, servidores MCP locales y los comandos ! que tú tipeas. Para una barrera total, corre Claude Code dentro de un contenedor o VM (dev containers).
Lección 3.11
Worktrees y sesiones paralelas
Un git worktree es un directorio de trabajo separado, con su propia rama, que comparte historial y remoto con tu checkout principal. Con cada sesión en su worktree, las ediciones de una nunca tocan los archivos de otra.
bash
# crea .claude/worktrees/feature-auth en la rama worktree-feature-auth
claude --worktree feature-auth
# en otra terminal, otra sesión aislada
claude -w bugfix-123
# worktree a partir de un pull request (comillas por el #)
claude --worktree "#1234"
Agrega .claude/worktrees/ a tu .gitignore.
Archivos ignorados: un worktree es un checkout limpio, sin tu .env. Crea .worktreeinclude (sintaxis de .gitignore) para copiarlos automáticamente.
Rama base: por defecto parte de la rama default del remoto. Con "worktree": {"baseRef": "head"} en settings parte de tu HEAD local.
Limpieza: al salir, si el worktree está limpio se borra; si tiene cambios o commits, Claude te pregunta si conservarlo.
También puedes pedir "trabaja en un worktree" y Claude lo crea. Los subagentes con isolation: worktree usan uno temporal.
Patrón escritor / revisor
Un contexto nuevo revisa mejor porque no está sesgado hacia código que acaba de escribir. Sesión A: "implementa un rate limiter para la API". Sesión B: "revisa el rate limiter en @src/middleware/rateLimiter.ts buscando casos borde, condiciones de carrera y consistencia con nuestros middlewares". Luego pasas el feedback a A. Lo mismo funciona con tests: una sesión los escribe y otra escribe el código que los pasa.
/batchPara cambios grandes, /batch <instrucción> investiga el código, divide el trabajo en 5 a 30 unidades independientes, te presenta un plan y, al aprobarlo, lanza un subagente por unidad, cada uno en su propio worktree.
Lección 3.12
Revisión de código integrada
Claude Code trae varias formas de revisar. Elige según profundidad y dónde quieres los hallazgos.
Comando
Qué hace
/code-review
Revisa tu rama (commits sobre el upstream más cambios sin commit) buscando bugs de correctitud. Corre como subagente en segundo plano. Alias: /review
/code-review high --fix
Elige effort (low reporta solo lo más seguro; hacia max amplía cobertura) y aplica los arreglos
/code-review --comment 1234
Publica los hallazgos como comentarios inline en el PR
/code-review main...mi-feature
Apunta a una rama, un rango (HEAD~15..HEAD), un PR o una ruta
/simplify
Cuatro agentes en paralelo buscan reutilización, simplificación y eficiencia, y aplican los arreglos
/security-review
Analiza los cambios de tu rama contra la default buscando inyección, auth y exposición de datos
/verify · /run
Construye, levanta y maneja tu app para confirmar que el cambio funciona de verdad, no solo que pasan los tests
/ultrareview
Revisión profunda multiagente en un sandbox en la nube (o /code-review ultra)
Revisión adversarialMientras más trabaja Claude sin supervisión, más importa un chequeo independiente. Un subagente revisor ve solo el diff y los criterios, no el razonamiento que produjo el cambio. Dile que reporte solo brechas que afecten correctitud o requisitos: un revisor al que le pides encontrar problemas casi siempre encuentra algunos, y perseguirlos todos lleva a sobreingeniería.
Para revisión automática de cada PR sin mantener un workflow existe Code Review, un servicio gestionado que un Owner activa para la organización (nivel Experto).
Quiz final
Quiz · Nivel Avanzado
Responde todas correctamente para aprobar
Siguiente: Experto
Orquestación, autonomía, CI, SDK, nube, plugins y gobernanza.