🧠 Masterclass Claude Code

Guía profesional completa — Agentes, Skills, Tokens, Paralelismo y Eficiencia

Nivel: Intermedio → Profesional Versión: Claude Code 2.0+ / Abril 2026 Objetivo: Dominar Claude Code como un senior engineer

Índice

La Arquitectura Mental Correcta
CLAUDE.md — Tu Cerebro Persistente
Skills — Conocimiento On-Demand
Subagentes — Tu Equipo de IA
Agent Teams — Paralelismo Real
Worktrees — Desarrollo Paralelo Desde Tu Equipo
Hooks — Automatización Silenciosa
Slash Commands — Workflows Reutilizables
Gestión de Tokens — Ahorra 40-70%
Prompting de Precisión Quirúrgica
MCP — Integrar el Mundo Exterior
Configuración Profesional del Entorno
Patrones Anti-Desperdicio
Flujo de Trabajo Profesional Completo

1. La Arquitectura Mental Correcta

Insight clave: Claude Code no es un asistente de chat. Es un sistema de orquestación multi-agente.

┌─────────────────────────────────────────────────────┐
│              TU SESIÓN PRINCIPAL                    │
│  (Agente orquestador — el "tú" que piensa)          │
│                                                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│  │Subagente │  │Subagente │  │Subagente │  ← Paralelo│
│  │Frontend  │  │Backend   │  │Database  │          │
│  └──────────┘  └──────────┘  └──────────┘          │
└─────────────────────────────────────────────────────┘

El error más común: tratar Claude Code como ChatGPT con acceso a ficheros.

La realidad: Claude Code puede ejecutar hasta 7 agentes en paralelo, cada uno con su propio contexto de 200k tokens, trabajando simultáneamente en diferentes partes de tu codebase.

2. CLAUDE.md — Tu Cerebro Persistente

El fichero CLAUDE.md es la memoria permanente de tu proyecto. Se lee al inicio de cada sesión automáticamente.

Ubicaciones

Fichero	Alcance
`~/.claude/CLAUDE.md`	Global — aplica a todos tus proyectos
`.claude/CLAUDE.md`	Proyecto — solo este repo
`src/CLAUDE.md`	Directorio — cuando Claude trabaja en esa carpeta

Anatomía de un CLAUDE.md profesional

# Proyecto: API de Pagos

## Stack
- Node.js 22 + TypeScript 5.4
- PostgreSQL 16 + Prisma ORM
- Testing: Vitest + Supertest

## Reglas Críticas
- NUNCA modificar archivos en `src/legacy/` sin aprobación explícita
- SIEMPRE escribir tests antes de implementar (TDD)
- Usar `Result<T, E>` pattern, nunca throw en lógica de negocio
- Commits en formato Conventional Commits

## Sub-Agent Routing Rules

### Paralelo (TODAS las condiciones):
- 3+ tareas independientes o dominios distintos
- Sin estado compartido entre tareas
- Límites claros de ficheros sin solapamiento

### Secuencial (CUALQUIER condición):
- Dependencias entre tareas (B necesita output de A)
- Ficheros o estado compartidos
- Scope poco claro

### Domain Parallel Patterns
Al implementar features cross-domain, lanza agentes paralelos:
- **Frontend agent**: Componentes React, UI state, forms
- **Backend agent**: API routes, server actions, lógica de negocio
- **Database agent**: Schema, migraciones, queries

## Comandos Útiles
- `pnpm test:unit` — Tests unitarios
- `pnpm db:migrate` — Migraciones pendientes
- `docker-compose up -d` — Levantar servicios

## Anti-patrones en este proyecto
- No usar `any` en TypeScript
- No commits directos a `main`
- No queries N+1 (siempre `include` o `select`)

## Cuando hagas /compact, preserva siempre:
- Lista de ficheros modificados en esta sesión
- Decisiones arquitectónicas tomadas
- Tests que han fallado y sus causas

Reglas de oro del CLAUDE.md

Menos es más. Si tu CLAUDE.md supera las 300 líneas, Claude empieza a ignorar partes. Regla: si Claude ya lo hace bien sin la instrucción, bórrala. Si es un comportamiento mecánico repetitivo, conviértelo en un hook.

3. Skills — Conocimiento On-Demand

Las Skills son módulos de conocimiento especializado que se cargan solo cuando se necesitan, ahorrando miles de tokens por sesión.

La diferencia entre CLAUDE.md y Skills

	CLAUDE.md	Skill
Cuándo carga	Siempre, al inicio	Solo cuando la tarea aplica
Para qué	Reglas del proyecto, contexto siempre relevante	Conocimiento especializado puntual
Tokens	Consume siempre	Solo consume cuando se activa

Estructura de una Skill

.claude/skills/
└── code-reviewer/
    ├── SKILL.md          ← Entrada principal (< 500 líneas)
    ├── security-checklist.md
    ├── style-guide.md
    └── scripts/
        └── check-deps.sh

Plantilla SKILL.md profesional

---
name: code-reviewer
description: Reviews TypeScript and JavaScript code for security vulnerabilities,
  performance issues, and team coding standards when user asks for code review,
  mentions reviewing changes, or asks about security/performance of specific code.
allowed-tools: [Read, Bash]
---

# Code Reviewer

## Cuándo activar esta skill
- Usuario pide explícitamente "review" o "revisar"
- Se menciona "cambios", "PR", "pull request"
- Preguntas sobre seguridad o performance de código

## Proceso de revisión

### Paso 1: Análisis de Seguridad
Detectar:
- Vectores de SQL injection
- Vulnerabilidades XSS
- Secrets expuestos en código
- Bypasses de autenticación

Para autenticación, consultar `./security-checklist.md`

### Paso 2: Performance
Buscar:
- Patrones N+1 en queries
- Re-renders innecesarios
- Memory leaks
- Operaciones bloqueantes

### Paso 3: Estándares del equipo
Verificar contra `./style-guide.md`

## Formato de salida

1. **Crítico** — Bloquea el merge
2. **Warning** — Debe corregirse
3. **Sugerencia** — Mejora opcional

La clave del éxito de una Skill: su `description`

# ❌ Vaga — nunca se activa
description: Helps with code

# ✅ Rica en triggers — se activa correctamente
description: Reviews TypeScript and JavaScript code for security vulnerabilities,
  performance issues, and coding standards when user asks for code review
  or mentions reviewing changes

Las descripciones ricas en triggers mejoran la activación del 20% al 90%.

Skills globales vs. de proyecto

~/.claude/skills/          ← Disponibles en TODOS tus proyectos
.claude/skills/            ← Solo en este proyecto (compartibles con el equipo)

Truco avanzado: dynamic shell injection en Skills

## Estado actual del sistema
!`docker ps --format "{{.Names}}: {{.Status}}" | head -10`

## Rama actual
!`git branch --show-current` — último commit: !`git log -1 --oneline`

Cuando la skill se activa, Claude ejecuta estos comandos y recibe el output dinámico, no el texto literal.

4. Subagentes — Tu Equipo de IA

Un subagente es una instancia separada de Claude con su propio contexto limpio, herramientas específicas y permisos independientes.

Subagentes Built-in

Subagente	Propósito	Cuándo lo usa Claude
`Explore`	Búsqueda y análisis, solo lectura	Explorar codebase sin modificar
`Plan`	Investigación para planificación	En modo plan, cuando necesita entender el código
`General-purpose`	Tareas complejas multi-paso	Requiere tanto exploración como modificación

Cuándo usar subagentes

Úsalos cuando:

La tarea produce output verbose que no necesitas en tu contexto principal
Quieres aislar herramientas o permisos
El trabajo es autocontenido y puede devolver un resumen

No los uses cuando:

Quieres prompts o workflows reutilizables en el contexto principal (usa Skills)
La tarea es muy pequeña (overhead > beneficio)

Crear un subagente personalizado

.claude/agents/
└── security-auditor.md

---
name: security-auditor
description: Performs comprehensive security audits on authentication modules,
  API endpoints, and data handling code. Use when user asks to audit security,
  check for vulnerabilities, or review auth-related code.
model: claude-opus-4-6          # Modelo específico para este agente
allowed-tools: [Read, Bash]     # Sin permisos de escritura
---

# Security Auditor

Eres un experto en seguridad especializado en aplicaciones web.
Tu misión es auditar código en busca de vulnerabilidades OWASP Top 10.

## Proceso
1. Analizar flujos de autenticación
2. Verificar validación de inputs
3. Revisar manejo de secretos y tokens
4. Comprobar control de acceso y autorización

## Output
Devuelve siempre un reporte estructurado con:
- Vulnerabilidades críticas (con línea de código)
- Vulnerabilidades medias
- Recomendaciones de hardening

Invocar subagentes explícitamente

# Delegación automática (Claude decide)
"Revisa el módulo de autenticación para vulnerabilidades"

# Delegación explícita por nombre
"Usa el agente security-auditor para revisar src/auth/"

# Paralelo con instrucciones específicas
"Usa 4 subagentes paralelos para explorar el codebase:
 - Subagente 1: componentes frontend en src/components/
 - Subagente 2: API routes en src/api/
 - Subagente 3: capa de base de datos en src/db/
 - Subagente 4: sistema de autenticación en src/auth/"

Control de modelos por agente (ahorro de costes)

# El agente principal corre en Sonnet (default)
# Los subagentes de exploración en Haiku (80% más barato)
export CLAUDE_CODE_SUBAGENT_MODEL="claude-haiku-4-5-20251001"

Patrón óptimo: Sonnet para el orquestador, Haiku para subagentes de exploración.

5. Agent Teams — Paralelismo Real

Los Agent Teams son múltiples instancias independientes de Claude Code coordinándose entre sí. Cada “teammate” tiene su propio contexto completo.

Subagentes vs. Agent Teams

	Subagentes	Agent Teams
Contexto	Comparten sesión padre	Completamente independientes
Scope	Una sesión	Múltiples sesiones
Paralelismo	Hasta 7 simultáneos	Ilimitado (recursos del sistema)
Uso ideal	Tareas cortas y focalizadas	Proyectos grandes, contexto que excede 200k

Configurar un Agent Team

# En CLAUDE.md — Domain Parallel Patterns

## Agent Team: Feature Completa
Para implementar features que tocan múltiples dominios:

**Frontend Specialist**:
- Archivos: `src/components/`, `src/pages/`, `src/hooks/`
- Responsabilidad: React, UI state, forms, estilos

**Backend Specialist**:
- Archivos: `src/api/`, `src/services/`, `src/middleware/`
- Responsabilidad: Routes, business logic, validación

**Database Specialist**:
- Archivos: `src/db/`, `prisma/`, `migrations/`
- Responsabilidad: Schema, queries, migraciones

Regla crítica: cada specialist toca SOLO sus archivos.

Background agents (no bloquear tu sesión)

Cuando Claude lanza un subagente, puedes mandarlo al background y seguir trabajando:

Ctrl+B    → Mandar agente activo al background
/tasks    → Ver todos los agentes corriendo en background
/stats    → Ver uso de tokens y estadísticas

6. Worktrees — Desarrollo Paralelo Desde Tu Equipo

Git Worktrees permiten tener múltiples ramas activas en directorios separados simultáneamente. Combinado con Claude Code, es el máximo nivel de paralelismo.

Sin worktrees (serial)

Feature A → Feature B → Feature C
  (2h)         (2h)        (2h)    = 6h total

Con worktrees + Claude Code paralelo

Feature A ─┐
Feature B  ├── simultáneos = ~2h total
Feature C ─┘

Setup de worktrees

# Crear worktrees para trabajo paralelo
git worktree add ../proyecto-feature-auth feature/auth
git worktree add ../proyecto-feature-payments feature/payments
git worktree add ../proyecto-fix-dashboard fix/dashboard-perf

# Verificar worktrees activos
git worktree list

# En cada directorio, lanzar Claude Code independientemente
cd ../proyecto-feature-auth && claude
cd ../proyecto-feature-payments && claude   # En otra terminal
cd ../proyecto-fix-dashboard && claude       # En otra terminal

Regla crítica de los worktrees

Cada worktree tiene su propio scope de CLAUDE.md. Las reglas del worktree padre no se propagan automáticamente. Copia o enlaza tu .claude/ base a cada worktree:

# Compartir configuración base entre worktrees
ln -s /ruta/al/repo-base/.claude ../proyecto-feature-auth/.claude

Limpiar worktrees

git worktree remove ../proyecto-feature-auth
git branch -d feature/auth

7. Hooks — Automatización Silenciosa

Los hooks son scripts que se ejecutan automáticamente antes o después de las acciones de Claude. Son la forma de automatizar quality gates sin interrumpir el flujo.

Tipos de hooks

Hook	Cuándo se ejecuta
`PreToolUse`	Antes de que Claude use cualquier herramienta
`PostToolUse`	Después de que Claude use una herramienta
`Stop`	Al final de cada turno de Claude
`session-start`	Al inicio de cada sesión

Ejemplos de hooks esenciales

Hook de quality gate — fuerza tests antes de commit:

# .claude/hooks/pre-commit.sh
#!/bin/bash
# Bloquea commits si los tests fallan

if ! pnpm test:unit --silent; then
  echo "❌ Tests fallando. Arregla antes de commitear."
  exit 1
fi

echo "✅ Tests pasando. Commit permitido."

Hook de session-start — contexto dinámico:

# .claude/hooks/session-start.sh
#!/bin/bash
echo "🚀 $(basename "$PWD") — $(date '+%Y-%m-%d %H:%M')"
echo "────────────────────────────────────"

# Estado de servicios
docker ps | grep -q postgres && echo "✅ PostgreSQL: OK" || echo "❌ PostgreSQL: Caído"
docker ps | grep -q redis    && echo "✅ Redis: OK"      || echo "❌ Redis: Caído"

# Contexto git
echo ""
echo "📍 Rama: $(git branch --show-current)"
echo "   Último commit: $(git log -1 --oneline)"
echo "   Ficheros modificados: $(git status --porcelain | wc -l)"
echo "────────────────────────────────────"

Hook de auto-format post-edición:

# .claude/hooks/post-edit.sh
#!/bin/bash
# Auto-formatea el fichero recién editado
FILE="$1"
case "$FILE" in
  *.ts|*.tsx) npx prettier --write "$FILE" ;;
  *.py)       black "$FILE" ;;
esac

⚠️ Advertencia: Los hooks de auto-formato ejecutados en cada edición pueden consumir 160k tokens en 3 rondas. Mejor formatear manualmente entre sesiones o solo en pre-commit.

8. Slash Commands — Workflows Reutilizables

Los slash commands son prompts pre-escritos que ejecutas con /nombre. Perfectos para workflows repetitivos.

Ubicaciones

~/.claude/commands/         ← Globales (todos tus proyectos)
.claude/commands/           ← Del proyecto (compartibles en equipo)

Ejemplos de commands esenciales

/review — Code review completo:

<!-- .claude/commands/review.md -->
description: Realiza un code review completo de los cambios actuales
argument-hint: "<archivos específicos o vacío para diff completo>"

## Misión
Revisar los cambios en $ARGUMENTS o en `git diff --staged` si no se especifica.

## Proceso
1. Usa un subagente para analizar cambios de seguridad
2. Usa otro subagente para analizar performance
3. Revisa adherencia a estándares del proyecto (ver CLAUDE.md)
4. Genera un reporte consolidado con: Crítico / Warning / Sugerencia
5. Propón correcciones para todos los issues críticos

/feature — Implementar feature completa:

<!-- .claude/commands/feature.md -->
description: Implementa una feature completa con TDD y documentación
argument-hint: "<descripción de la feature>"

## Proceso de implementación de "$ARGUMENTS"

### Fase 1: Planificación (subagente)
Usa un subagente para explorar el codebase y entender:
- Archivos que necesitan modificarse
- Patrones existentes a seguir
- Posibles conflictos

### Fase 2: Implementación paralela
Lanza agentes paralelos por dominio si la feature toca múltiples áreas:
- Frontend (si aplica)
- Backend (si aplica)
- Base de datos (si aplica)

### Fase 3: Tests
Escribe tests antes de implementar (TDD). No avances sin tests verdes.

### Fase 4: Documentación
Actualiza README o docs relevantes si el cambio es visible externamente.

/fix — Bug fix sistemático:

<!-- .claude/commands/fix.md -->
description: Diagnostica y soluciona un bug con análisis de causa raíz
argument-hint: "<descripción del bug o error>"

## Bug: "$ARGUMENTS"

1. Usa un subagente para reproducir el bug y confirmar comportamiento
2. Identifica la causa raíz (no solo el síntoma)
3. Propón 2-3 soluciones posibles con trade-offs
4. Implementa la solución más apropiada
5. Escribe un test de regresión que hubiera detectado este bug
6. Verifica que no hay regresiones en tests relacionados

9. Gestión de Tokens — Ahorra 40-70%

El contexto es tu recurso más valioso. Gestionarlo bien es la diferencia entre sesiones productivas y sesiones que se pierden en noise.

Los principales despilfarradores de tokens

1. CLAUDE.md demasiado largo

Si tu CLAUDE.md supera las 300 líneas efectivas, Claude empieza a ignorar secciones. Todo lo que Claude haría bien sin instrucción explícita → bórralo.

2. Exploración en el contexto principal

❌ MAL: "Lee todos los archivos de src/ y dime cómo funciona el auth"
   → Claude lee 50 archivos, todos en tu contexto principal

✅ BIEN: "Usa subagentes para investigar cómo funciona el auth,
          que exploren en su propio contexto y me devuelvan un resumen"

3. Reformatear output ya generado

❌ MAL: (Después de que Claude responde) "Pásame eso en formato tabla"
   → Claude regenera todo el contenido, doubles el coste

✅ BIEN: "Responde directamente en formato tabla"

4. Contexto que ya estás inyectando sin darte cuenta

❌ MAL (cada mensaje): "Recuerda que estamos usando PostgreSQL y TypeScript..."
✅ BIEN: Eso va en CLAUDE.md, se inyecta automáticamente

Sistema de 3 niveles para contexto

Nivel 1 — Siempre cargado (CLAUDE.md, < 200 líneas)
  Stack, reglas críticas, anti-patrones, comandos clave

Nivel 2 — On-demand (Skills, cargan solo cuando aplican)
  Guías de arquitectura, checklists de seguridad,
  patrones específicos por dominio

Nivel 3 — Referencia bajo demanda (docs/, solo cuando Claude las pide)
  Documentación detallada de APIs, esquemas completos de BD

Variables de entorno para control de tokens

# Subagentes de exploración corren en Haiku (80% más barato)
export CLAUDE_CODE_SUBAGENT_MODEL="claude-haiku-4-5-20251001"

# Desactiva llamadas de modelo para features no críticas (tips, sugerencias)
export DISABLE_NON_ESSENTIAL_MODEL_CALLS=1

# Reducir extended thinking para tareas simples (default: 10000)
# Para tareas triviales, set a 0. Para diseño arquitectónico, sube a 30000
export MAX_THINKING_TOKENS=5000

El modelo adecuado para cada tarea

Opus 4.6    → Diseño arquitectónico complejo, debugging difícil, decisiones críticas
Sonnet 4.6  → 80% de las tareas de coding (default, balance coste/calidad)
Haiku 4.5   → Exploración, lectura de ficheros, subagentes, tareas mecánicas

Cambiar de modelo en sesión: /model opus o /model haiku

Compactación estratégica

/compact    → Compacta la conversación preservando contexto esencial
/clear      → Reset completo del contexto (cambio de tarea radicalmente distinta)
/btw        → Respuesta rápida que NO entra en el historial de conversación

Truco: Antes de /compact, dale instrucciones a Claude sobre qué preservar:

"Antes de compactar, asegúrate de preservar: la decisión de usar optimistic
locking, los 3 tests que fallaron y sus causas, y la lista completa de
archivos modificados en esta sesión."
/compact

10. Prompting de Precisión Quirúrgica

El modelo mental correcto

Habla con Claude Code como lo harías con un senior engineer de tu equipo:

❌ "Arregla el login"
✅ "El endpoint POST /auth/login devuelve 401 cuando el email tiene
   mayúsculas aunque las credenciales sean correctas. El hash se genera
   en src/auth/service.ts:47. Arréglalo sin modificar el schema de BD."

Técnicas de prompting profesional

Scope narrow (evita exploración infinita):

❌ "Investiga el sistema de pagos"
✅ "Investiga SOLO src/payments/stripe.ts y src/payments/types.ts
   para entender cómo manejamos los webhooks de Stripe"

Verificación integrada:

"Implementa X. Luego prueba que funciona ejecutando `pnpm test:payments`.
No avances hasta que todos los tests pasen."

Delegación explícita de paralelismo:

"Necesito analizar estos 5 microservicios en paralelo usando subagentes separados:
- auth-service: analiza manejo de tokens JWT
- user-service: analiza validación de datos de entrada
- payment-service: analiza seguridad de transacciones
- notification-service: analiza rate limiting
- api-gateway: analiza autenticación y routing
Cada subagente debe devolver: vulnerabilidades encontradas + recomendaciones"

Revisión cruzada:

"Una vez implementado, revisa tu propio código como si fuera una PR de un junior.
Grillame sobre los edge cases. No hagas la PR hasta que yo pase tu test."

La técnica “knowing what you know now”:

"Esta implementación funciona pero es mediocre. Conociendo todo lo que sabes
ahora sobre este módulo, descártala e implementa la solución elegante."

Plan mode antes de actuar

Para tareas complejas, activa plan mode primero:

/plan "Necesito refactorizar el sistema de autenticación para soportar OAuth2
       además del login con contraseña, sin romper la API existente"

Claude explorará el codebase con subagentes y te presentará un plan detallado antes de escribir una sola línea de código.

La entrevista inicial para proyectos nuevos

"Voy a empezar un nuevo proyecto. Antes de que empieces a sugerir,
hazme las preguntas necesarias para entender exactamente qué necesito.
Una vez que tengas suficiente información, genera una spec detallada
y espera mi aprobación antes de implementar nada."

11. MCP — Integrar el Mundo Exterior

MCP (Model Context Protocol) son servidores que exponen herramientas externas a Claude. Con ellos, Claude puede leer tu calendario, crear tickets en Linear, hacer PRs en GitHub, etc.

MCP servers imprescindibles

// .claude/settings.json
{
  "mcpServers": {
    "github": {
      "type": "url",
      "url": "https://github.mcp.claude.com/mcp"
    },
    "linear": {
      "type": "url",
      "url": "https://linear.mcp.claude.com/mcp"
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "POSTGRES_URL": "postgresql://localhost/mydb" }
    }
  }
}

Regla de los MCP: menos es más

Cada MCP server activo añade definiciones de herramientas a tu contexto. Mantén menos de 10 activos por proyecto. Activa solo los que usarás en esa sesión.

Toggle rápido desde CLI:

# Dentro de Claude Code
/mcp toggle github    ← activar/desactivar sin editar config

Workflow con MCP: de ticket a PR automático

"Lee el ticket #247 en Linear, entiende los requisitos, implementa la feature,
y cuando los tests pasen, crea una PR en GitHub con descripción detallada."

12. Configuración Profesional del Entorno

Instalación y setup inicial

npm install -g @anthropic-ai/claude-code

# Verificar instalación
claude --version

Estructura de proyecto recomendada

mi-proyecto/
├── .claude/
│   ├── CLAUDE.md              ← Contexto del proyecto
│   ├── settings.json          ← Config MCP, modelos, permisos
│   ├── agents/                ← Subagentes del proyecto
│   │   ├── security-auditor.md
│   │   ├── performance-analyzer.md
│   │   └── code-reviewer.md
│   ├── skills/                ← Skills del proyecto
│   │   ├── testing/
│   │   ├── deployment/
│   │   └── database/
│   ├── commands/              ← Slash commands del equipo
│   │   ├── feature.md
│   │   ├── fix.md
│   │   └── review.md
│   └── hooks/                 ← Automatización
│       ├── session-start.sh
│       └── pre-commit.sh
├── src/
└── ...

Configuración global (`~/.claude/`)

~/.claude/
├── CLAUDE.md          ← Tus preferencias personales globales
├── settings.json      ← Config global
├── agents/            ← Tus agentes personales (disponibles en todos tus proyectos)
├── skills/            ← Tus skills personales
└── commands/          ← Tus comandos personales

settings.json profesional

{
  "model": "claude-sonnet-4-6",
  "env": {
    "MAX_THINKING_TOKENS": "10000",
    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-haiku-4-5-20251001",
    "DISABLE_NON_ESSENTIAL_MODEL_CALLS": "1"
  },
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(pnpm:*)",
      "Bash(docker:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(curl * | bash:*)"
    ]
  }
}

13. Patrones Anti-Desperdicio

Errores que cometen casi todos y cómo evitarlos:

Anti-patrón 1: El CLAUDE.md inflado

❌ CLAUDE.md con 500 líneas de instrucciones detalladas
✅ CLAUDE.md con 150 líneas de contexto + Skills para el resto

Anti-patrón 2: La exploración sin límites

❌ "Investiga el proyecto y dime cómo funciona"
   → Claude lee 200 ficheros, agota el contexto

✅ "Usa subagentes para investigar estas 4 áreas específicas [lista]
    y devuélveme solo un resumen de cada una"

Anti-patrón 3: La compactación reactiva

❌ Esperar a que Claude diga "contexto casi lleno"
✅ /compact manual al 50% del contexto estimado
   Con instrucciones sobre qué preservar

Anti-patrón 4: El slash command excesivo

❌ 30 slash commands hiperespecíficos que raramente usas
✅ 5-8 commands para tus workflows más repetitivos
   (El resto, pide con lenguaje natural)

Anti-patrón 5: Confiar sin verificar

❌ "Genial, parece que funciona, haz la PR"
✅ "Ejecuta los tests. Si pasan, muéstrame el diff completo.
    Si todo se ve bien, entonces haz la PR."

Anti-patrón 6: Un solo agente para todo

❌ Pedirle al agente principal que lea 20 ficheros para entender
   la arquitectura antes de implementar

✅ Usar un subagente de exploración → Recibe el resumen →
   El agente principal implementa con contexto limpio

14. Flujo de Trabajo Profesional Completo

Workflow diario: nueva feature

# 1. Crear worktree para la feature (aislamiento)
git worktree add ../proyecto-feature-X feature/nueva-feature

# 2. Abrir Claude Code en el worktree
cd ../proyecto-feature-X && claude

# 3. En Claude Code — entender qué hacer
/plan "Necesito implementar autenticación con Magic Links por email"

# 4. Claude explora con subagentes, presenta plan
# → Revisar el plan, pedir ajustes si es necesario
# → Aprobar: "El plan se ve bien, procede"

# 5. Claude implementa en paralelo (frontend + backend + BD si aplica)
# → Subagentes trabajan simultáneamente
# → Tests se ejecutan automáticamente (hook)

# 6. Review del resultado
/review

# 7. Si todo está verde
# → Claude crea la PR (con MCP de GitHub)
# → Limpieza del worktree
git worktree remove ../proyecto-feature-X

Workflow: debug de un bug crítico

1. Paste del error completo (stack trace, logs, contexto)
2. "Reproduce el bug primero usando un subagente de exploración.
    Confírmame que entiendes exactamente qué lo causa antes de tocar nada."
3. → Claude confirma la causa raíz
4. "Propón 3 formas de solucionarlo con pros y contras de cada una"
5. → Elegir la solución
6. "Implementa [la solución X]. Luego escribe un test de regresión que
    hubiera detectado este bug. Ejecuta todos los tests."

Workflow: documentación masiva de codebase

"Necesito documentar el módulo src/payments/ completo.
Usa subagentes paralelos:
- Subagente 1: analiza payment.service.ts y documenta cada método
- Subagente 2: analiza payment.controller.ts y documenta endpoints
- Subagente 3: analiza payment.types.ts y documenta interfaces
- Subagente 4: analiza los tests y extrae ejemplos de uso

Luego combina los resultados en un único README.md coherente."

Cheatsheet Rápido

CONTEXTO
├── CLAUDE.md          → Reglas siempre activas (< 300 líneas)
├── Skills             → Conocimiento on-demand
├── /compact           → Compactar con instrucciones previas
├── /clear             → Reset total de contexto
└── /btw               → Pregunta sin entrar al historial

AGENTES
├── Subagentes         → Contexto aislado, en sesión
├── Agent Teams        → Múltiples sesiones independientes
├── --worktree         → Ramas paralelas en directorios separados
├── Ctrl+B             → Mandar subagente al background
└── /tasks             → Ver agentes en background

MODELOS (coste relativo)
├── Opus 4.6           → 1x (decisiones complejas)
├── Sonnet 4.6         → 0.2x (tareas normales)
└── Haiku 4.5          → 0.04x (exploración, subagentes)

TOKENS — Variables de entorno
├── CLAUDE_CODE_SUBAGENT_MODEL=claude-haiku-4-5-20251001
├── DISABLE_NON_ESSENTIAL_MODEL_CALLS=1
└── MAX_THINKING_TOKENS=5000  (0 para tareas triviales)

COMANDOS ESENCIALES
├── /plan <tarea>      → Planifica antes de actuar
├── /model opus|sonnet → Cambiar modelo en sesión
├── /stats             → Ver uso de tokens
├── /rename <nombre>   → Nombrar sesión para reanudarla
└── claude --resume    → Reanudar sesión por nombre

Recursos Complementarios

Documentación oficial: docs.claude.com
Claude Code Docs: code.claude.com/docs
Awesome Claude Code (comunidad): github.com/hesreallyhim/awesome-claude-code
Skills de producción: github.com/anthropics/skills

Masterclass creada con información actualizada a Abril 2026 Claude Code 2.0 · Modelos: Opus 4.6, Sonnet 4.6, Haiku 4.5

🧠 Masterclass Claude Code

Guía profesional completa — Agentes, Skills, Tokens, Paralelismo y Eficiencia

Índice

1. La Arquitectura Mental Correcta

2. CLAUDE.md — Tu Cerebro Persistente

Ubicaciones

Anatomía de un CLAUDE.md profesional

Reglas de oro del CLAUDE.md

3. Skills — Conocimiento On-Demand

La diferencia entre CLAUDE.md y Skills

Estructura de una Skill

Plantilla SKILL.md profesional

La clave del éxito de una Skill: su description

Skills globales vs. de proyecto

Truco avanzado: dynamic shell injection en Skills

4. Subagentes — Tu Equipo de IA

Subagentes Built-in

Cuándo usar subagentes

Crear un subagente personalizado

Invocar subagentes explícitamente

Control de modelos por agente (ahorro de costes)

5. Agent Teams — Paralelismo Real

Subagentes vs. Agent Teams

Configurar un Agent Team

Background agents (no bloquear tu sesión)

6. Worktrees — Desarrollo Paralelo Desde Tu Equipo

Sin worktrees (serial)

Con worktrees + Claude Code paralelo

Setup de worktrees

Regla crítica de los worktrees

Limpiar worktrees

7. Hooks — Automatización Silenciosa

Tipos de hooks

Ejemplos de hooks esenciales

8. Slash Commands — Workflows Reutilizables

Ubicaciones

Ejemplos de commands esenciales

9. Gestión de Tokens — Ahorra 40-70%

Los principales despilfarradores de tokens

Sistema de 3 niveles para contexto

Variables de entorno para control de tokens

El modelo adecuado para cada tarea

Compactación estratégica

10. Prompting de Precisión Quirúrgica

El modelo mental correcto

Técnicas de prompting profesional

Plan mode antes de actuar

La entrevista inicial para proyectos nuevos

11. MCP — Integrar el Mundo Exterior

MCP servers imprescindibles

Regla de los MCP: menos es más

Workflow con MCP: de ticket a PR automático

12. Configuración Profesional del Entorno

Instalación y setup inicial

Estructura de proyecto recomendada

Configuración global (~/.claude/)

settings.json profesional

13. Patrones Anti-Desperdicio

Anti-patrón 1: El CLAUDE.md inflado

Anti-patrón 2: La exploración sin límites

Anti-patrón 3: La compactación reactiva

Anti-patrón 4: El slash command excesivo

Anti-patrón 5: Confiar sin verificar

Anti-patrón 6: Un solo agente para todo

14. Flujo de Trabajo Profesional Completo

Workflow diario: nueva feature

Workflow: debug de un bug crítico

Workflow: documentación masiva de codebase

Cheatsheet Rápido

Recursos Complementarios

La clave del éxito de una Skill: su `description`

Configuración global (`~/.claude/`)