Explore, Plan y Code: Los tres modos de Claude Code

Descripción

Claude Code tiene tres modos de operación: Explore (análisis read-only), Plan (diseño sin ejecución), y Agent/Code (ejecución completa). Cada modo existe por una razón específica, y saber cuándo usar cada uno transforma tu productividad.

Esta cápsula cubre los tres modos en profundidad: cómo activarlos, qué hace cada uno internamente, cuándo elegir uno sobre otro, y cómo combinarlos en el ciclo Explore → Plan → Code. También cubre el effort level de Opus que controla cuánta capacidad de razonamiento dedica Claude a cada respuesta.

La diferencia entre un usuario casual y un profesional de Claude Code se reduce a esto: el profesional elige el modo correcto para cada situación. El casual siempre usa Agent mode y espera que Claude adivine lo que necesita.

Explore Mode

Explore es el modo de análisis read-only. Claude lee archivos, analiza dependencias, busca patterns, y genera un mapa mental de tu codebase — pero no ejecuta comandos ni escribe código.

Cuándo usar Explore

• Al abrir un proyecto por primera vez
• Antes de implementar un feature complejo
• Para entender código que no escribiste
• Para encontrar bugs sin riesgo de romper algo
• Para analizar dependencias y arquitectura

Cómo activar Explore

No existe un comando /explore. Activas Explore a través de cómo formulas tu prompt. Claude detecta que quieres análisis cuando usas verbos como "analiza", "explica", "busca", "entiende":

> Analiza la estructura de este proyecto. ¿Qué framework se usa? 
  ¿Cómo están organizados los archivos? ¿Dónde está la lógica 
  principal?

Claude Code también tiene un subagent de Explore built-in que opera automáticamente en modo read-only cuando Claude necesita investigar tu codebase durante una tarea. Este subagent lee archivos y busca información sin modificar nada.

Ejemplo básico

> Estoy empezando a trabajar en este proyecto. Explícame la 
  estructura general: qué tecnologías usa, cómo están organizados 
  los archivos, y cuáles son los entry points principales.

Claude va a:

1. Leer package.json, requirements.txt, o el equivalente
2. Escanear la estructura de directorios
3. Identificar el framework y las dependencias principales
4. Encontrar entry points (main.py, index.ts, app.py)
5. Darte un resumen estructurado

Output típico:

El proyecto usa FastAPI (Python 3.11) con la siguiente estructura:

src/
├── main.py          → Entry point, configura la app FastAPI
├── routers/         → 4 routers: users, products, orders, auth
├── models/          → SQLAlchemy models (5 tablas)
├── schemas/         → Pydantic schemas para validación
├── services/        → Lógica de negocio separada de routers
└── tests/           → Pytest, 23 tests (18 passing, 5 skipped)

Dependencias principales: FastAPI 0.109, SQLAlchemy 2.0, Pydantic v2
Base de datos: PostgreSQL (via asyncpg)
Auth: JWT con python-jose

Ejemplo intermedio

> Analiza el sistema de autenticación actual. Quiero entender:
  1. ¿Cómo se generan los tokens JWT?
  2. ¿Dónde se validan?
  3. ¿Hay refresh tokens?
  4. ¿Qué middleware protege las rutas?
  No hagas cambios, solo analiza.

Claude va a leer los archivos relevantes y darte un análisis completo del flujo de autenticación, incluyendo potenciales problemas que detecte.

Ejemplo avanzado

> Analiza las dependencias de este proyecto. Identifica:
  - Dependencias desactualizadas (más de 6 meses)
  - Dependencias con vulnerabilidades conocidas
  - Dependencias que se importan pero no se usan
  - Dependencias duplicadas o redundantes
  Solo reporte, no cambies nada.

Lo que Explore NO hace

• ❌ No ejecuta comandos en terminal
• ❌ No modifica archivos
• ❌ No crea archivos nuevos
• ❌ No instala dependencias
• ❌ No hace commits

Esta restricción es intencional. Explore es seguro por diseño — puedes usarlo en cualquier codebase sin riesgo.

Plan Mode

Plan es el modo de diseño sin ejecución. Claude analiza tu solicitud, considera las opciones, y produce un plan de implementación que puedes revisar y aprobar antes de que se ejecute cualquier código.

Cuándo usar Plan

• Antes de implementar features complejos
• Refactorizaciones que tocan múltiples archivos
• Migraciones de base de datos
• Cambios de arquitectura
• Cuando quieres evaluar opciones antes de comprometerte

Cómo activar Plan

Usa el comando /plan:

/plan Necesito agregar un sistema de caché a la API. Redis o 
in-memory. Dame un plan completo.

También puedes activarlo con lenguaje explícito:

> Diseña un plan para migrar la base de datos de SQLite a PostgreSQL. 
  No implementes nada todavía. Quiero ver el plan primero.

Ejemplo básico

/plan Agregar paginación a todos los endpoints que retornan listas.

Output típico de Plan:

## Plan: Agregar paginación

### Archivos a modificar:
1. src/schemas/pagination.py (CREAR) — Schema de paginación reutilizable
2. src/routers/users.py (MODIFICAR) — Agregar query params offset/limit
3. src/routers/products.py (MODIFICAR) — Igual
4. src/routers/orders.py (MODIFICAR) — Igual
5. src/services/base.py (MODIFICAR) — Método genérico de paginación
6. tests/test_pagination.py (CREAR) — Tests para paginación

### Diseño:
- Schema `PaginatedResponse[T]` genérico con items, total, offset, limit
- Query params: offset (default 0), limit (default 20, max 100)
- Service layer maneja la query SQL con OFFSET/LIMIT
- Response incluye metadata: total_count, has_more, next_offset

### Orden de implementación:
1. Schema de paginación
2. Método genérico en service layer
3. Actualizar routers uno por uno
4. Tests

### Riesgos:
- Endpoints existentes cambiarán su response format (breaking change)
- Necesitas migration strategy para clientes actuales

¿Procedo con la implementación?

Ejemplo intermedio

/plan Quiero refactorizar el manejo de errores. Actualmente cada 
router tiene su propio try/catch. Quiero centralizarlo. Dame las 
opciones y tu recomendación.

Claude te dará múltiples opciones con pros y contras:

## Opciones de centralización de errores

### Opción A: Exception handlers de FastAPI
- Registrar handlers para cada tipo de excepción
- Pros: Nativo de FastAPI, bien documentado
- Contras: Menos control granular por endpoint

### Opción B: Middleware custom
- Middleware que captura todas las excepciones
- Pros: Control total, un solo lugar
- Contras: Puede ocultar errores durante desarrollo

### Opción C: Decorador custom (RECOMENDADA)
- Decorador @handle_errors que envuelve cada endpoint
- Pros: Explícito, fácil de testear, opt-in por endpoint
- Contras: Requiere agregar decorador a cada endpoint

### Recomendación: Opción C
[Justificación técnica...]

¿Con cuál procedo?

Ejemplo avanzado

/plan Necesito rediseñar el sistema de permisos. Actualmente es 
role-based (admin/user). Necesito migrar a RBAC granular con 
permisos por recurso. El sistema tiene 4 modelos, 12 endpoints, 
y 3 roles actuales. Plan completo con migration strategy.

Lo que Plan NO hace

• ❌ No ejecuta el plan automáticamente
• ❌ No modifica archivos
• ❌ No ejecuta comandos
• ❌ No hace cambios irreversibles

Plan produce un documento que tú revisas. Solo cuando dices "procede" o "implementa", Claude pasa a Agent mode.

Agent/Code Mode (default)

Agent es el modo de ejecución completa. Es el modo por defecto de Claude Code — cuando le das una tarea sin especificar modo, opera en Agent.

Qué puede hacer Agent mode

• ✅ Leer archivos del proyecto
• ✅ Escribir y modificar archivos
• ✅ Crear archivos nuevos
• ✅ Ejecutar comandos en terminal (npm, pip, git, etc.)
• ✅ Ejecutar tests
• ✅ Instalar dependencias
• ✅ Hacer commits

Sistema de permisos

Claude Code pide confirmación antes de acciones potencialmente destructivas:

Claude wants to run: rm -rf node_modules && npm install
Allow? [y/n/always]

Puedes configurar permisos en tu CLAUDE.md o settings para pre-aprobar ciertas acciones (por ejemplo, siempre permitir npm test).

Ejemplo básico

> Crea un endpoint GET /api/health que retorne 
  { "status": "ok", "timestamp": "..." }

Claude va a:

1. Identificar el framework (FastAPI/Express/etc.)
2. Encontrar dónde están los routers
3. Crear el endpoint con el formato correcto
4. Ejecutar tests si existen

Ejemplo intermedio

> El test test_create_user está fallando con "IntegrityError: 
  UNIQUE constraint failed: users.email". Arréglalo.

Claude va a:

1. Leer el test
2. Leer el modelo User
3. Identificar que el test no limpia la base de datos entre runs
4. Agregar fixture de cleanup o usar email único por test
5. Ejecutar el test para verificar

Ejemplo avanzado

> Implementa el plan de paginación que diseñamos. Empieza por el 
  schema genérico y luego actualiza el router de users. Ejecuta 
  los tests después de cada cambio.

Cuándo usar Agent directamente (sin Explore/Plan)

No siempre necesitas el ciclo completo. Agent directo es apropiado para:

• Bug fixes simples ("el botón no funciona, arréglalo")
• Tareas mecánicas ("renombra X a Y en todos los archivos")
• Generación de boilerplate ("crea un modelo User con estos campos")
• Ejecución de comandos ("ejecuta los tests y muéstrame los resultados")

El ciclo Explore → Plan → Code

El flujo completo

┌─────────┐     ┌──────┐     ┌──────┐
│ EXPLORE │────▶│ PLAN │────▶│ CODE │
│ (leer)  │     │(diseñar)   │(hacer)│
└────┬────┘     └──┬───┘     └──┬───┘
     │             │            │
     │             │            │
     └─────────────┴────────────┘
              ITERAR

El ciclo no es estrictamente lineal. Después de Code, puedes volver a Explore para verificar. Después de Plan, puedes volver a Explore para investigar más. Es iterativo.

Ejemplo completo: Nueva feature

Supongamos que necesitas agregar notificaciones por email a tu API.

Paso 1 — Explore:

> Analiza cómo se manejan actualmente los emails en este proyecto. 
  ¿Hay alguna integración con un servicio de email? ¿Se usa alguna 
  cola de mensajes? ¿Hay templates de email?

Paso 2 — Plan:

/plan Basándote en lo que encontraste, diseña un sistema de 
notificaciones por email. Necesito: email de bienvenida al 
registrarse, email de reset de password, y email de confirmación 
de compra. Dame el plan con opciones de servicio (SendGrid, SES, 
Resend).

Paso 3 — Code (incremental):

> Implementa el paso 1 del plan: la integración con Resend 
  y el servicio base de envío de emails.

> Ahora implementa el template de bienvenida y el trigger 
  al registrarse.

> Agrega tests para el servicio de email.

Paso 4 — Verificar (vuelta a Explore):

> Revisa todo lo que implementamos. ¿Hay edge cases que no 
  cubrimos? ¿Los tests cubren los escenarios principales? 
  ¿Hay algún problema de seguridad?

Comparaciones y decisiones

Sin workflow vs con workflow

Cuándo usar cada variación del ciclo

Effort Level

El effort level controla cuánta capacidad de razonamiento dedica el modelo a cada respuesta. Cambia el balance entre velocidad y profundidad.

Importante: Los niveles disponibles dependen del modelo. Se configura con /effort, en /model con las flechas ← →, en settings (effortLevel), o por env var (CLAUDE_CODE_EFFORT_LEVEL).

Niveles disponibles por modelo

Haiku 4.5 no expone effort configurable: si ajustas un nivel mientras lo usas, Claude Code simplemente lo ignora.

Effort low    → Razonamiento ligero, respuestas rápidas
Effort medium → Balance velocidad/profundidad (cost-sensitive)
Effort high   → Razonamiento profundo
Effort xhigh  → Muy profundo (default Opus 5)
Effort max    → Máxima profundidad, sin límite de thinking tokens (aplica solo a sesión actual)

Cuándo usar cada nivel

Cómo afecta a cada modo

• En Explore: Mayor effort = análisis más profundo, detecta más patterns
• En Plan: Mayor effort = más opciones consideradas, mejores trade-offs
• En Code: Mayor effort = código más robusto, mejor manejo de edge cases

Ejemplo práctico

/plan Rediseña el sistema de caché. Actualmente usa un diccionario 
in-memory que no persiste entre reinicios. Necesito considerar: 
Redis, Memcached, y file-based cache. Dame pros/contras de cada 
uno para nuestro caso (API con 10K req/min, 3 instancias).

Con Opus en effort high (default), Claude considera múltiples dimensiones antes de responder.

Con effort high (default), Claude va a:

• Analizar los patterns de acceso actuales
• Considerar cada opción en detalle
• Evaluar pros/contras específicos para tu caso
• Considerar edge cases (cache stampede, invalidation, replication)
• Dar una recomendación con justificación técnica

Con effort low, solo daría una tabla básica de comparación.

Fast Mode

Además del effort level, Opus 5 soporta fast mode — una optimización que genera output más rápido sin cambiar de modelo.

> /fast     ← Toggle on/off

Importante: Fast mode usa el mismo Opus 5. NO cambia a Sonnet ni a otro modelo. Es Opus con optimización de velocidad de output.

Fast mode es especialmente útil durante la fase de Code del ciclo Explore - Plan - Code, donde generas código de forma iterativa y quieres feedback loops más rápidos. Para la fase de Plan con análisis profundo, considera desactivar fast mode para que Opus razone al máximo.

Patterns comunes

Pattern 1: "Explore primero, siempre"

Antes de cualquier tarea significativa, haz Explore. Incluso si crees que conoces el codebase. Claude puede detectar cosas que tú no ves:

> Antes de empezar, analiza el estado actual del módulo de pagos. 
  ¿Hay deuda técnica? ¿Tests faltantes? ¿Código muerto?

Pattern 2: "Plan con opciones"

No pidas un solo plan. Pide opciones:

/plan Dame 2-3 opciones para implementar el sistema de 
notificaciones. Incluye pros, contras, y tu recomendación.

Pattern 3: "Code incremental"

No pidas todo de una vez. Implementa en pasos:

> Implementa solo el modelo y las migraciones. Nada más por ahora.

> Ahora agrega el servicio con la lógica de negocio.

> Ahora los endpoints. Ejecuta tests después.

Pattern 4: "Verify loop"

Después de implementar, vuelve a Explore para verificar:

> Revisa lo que acabamos de implementar. ¿Se sigue el pattern 
  del resto del proyecto? ¿Hay inconsistencias?

Pattern 5: "Effort escalonado"

Empieza con effort bajo para tareas simples, sube para las complejas:

# Tarea simple → Sonnet
/model sonnet
> Renombra el archivo config.py a settings.py y actualiza imports.

# Tarea compleja → Opus
/model opus
> Ahora refactoriza el sistema de configuración para usar Pydantic
  Settings con validación de variables de entorno.

Pitfalls y edge cases

Pitfall 1: Usar Agent mode para todo

El error: Dar instrucciones de implementación sin explorar primero.

❌ "Agrega WebSockets a la app"

El problema: Claude no sabe qué infraestructura existe, qué patterns se usan, o qué restricciones hay. Implementará algo genérico que probablemente no encaje.

La solución: Explore primero.

✅ "Analiza la arquitectura actual de la API. ¿Se usa algún 
   sistema de real-time? ¿Hay WebSockets, SSE, o long-polling?"

Pitfall 2: Plans demasiado ambiciosos

El error: Pedir un plan que cubre demasiado scope.

❌ /plan Rediseña toda la API para usar microservicios.

El problema: El plan será superficial porque el scope es enorme.

La solución: Plans acotados.

✅ /plan Diseña cómo extraer el módulo de pagos como un servicio 
   independiente. Solo ese módulo, no toda la API.

Pitfall 3: No verificar después de Code

El error: Asumir que lo que Claude implementó es correcto sin revisar.

La solución: Siempre verifica:

> Ejecuta todos los tests.
> Revisa si lo que implementaste sigue las convenciones del CLAUDE.md.
> ¿Hay algún edge case que no cubrimos?

Pitfall 4: Ignorar el output de Plan

El error: Decir "sí, implementa" sin leer el plan.

La solución: Lee el plan completo. Cuestiona decisiones. Pide alternativas. El plan es tu oportunidad de influir en la solución antes de que se escriba código.

Pitfall 5: Opus para todo

El error: Usar Opus para tareas triviales.

El problema: Respuestas más lentas y más caras sin beneficio para tareas simples. También consume más cuota.

La solución: Usa Sonnet para tareas rutinarias y Opus para tareas que requieren razonamiento profundo. Si usas Opus, ajusta effort a low para tareas más sencillas.

Ejemplo completo integrado

Escenario real: agregas un sistema de logging estructurado a un proyecto FastAPI existente.

Fase 1: Explore

> Analiza cómo se maneja el logging actualmente en este proyecto. 
  ¿Se usa algún logger? ¿Hay logs en los routers? ¿En los 
  servicios? ¿Se loggean errores? Dame un reporte completo.

Descubres que el proyecto usa print() statements dispersos, sin logging estructurado.

Fase 2: Plan

/plan Necesito reemplazar todos los print() con logging
estructurado. Requisitos:
- JSON format para producción
- Human-readable para desarrollo
- Request ID para traceability
- Log levels: DEBUG, INFO, WARNING, ERROR
- Integración con middleware de FastAPI
Dame el plan con los archivos a crear/modificar.

Claude produce un plan detallado. Lo revisas, pides un ajuste:

> En el plan, agregas structlog. ¿Qué tal si usamos loguru 
  en su lugar? Es más simple. Actualiza el plan.

Fase 3: Code (incremental)

> Implementa el paso 1: instala loguru y crea el módulo 
  de configuración de logging en src/core/logging.py

> Implementa el paso 2: crea el middleware de request ID 
  y logging de requests/responses.

> Implementa el paso 3: reemplaza todos los print() en 
  src/routers/ con llamadas al logger.

> Ejecuta los tests. Si algo falla, arréglalo.

Fase 4: Verify

> Revisa la implementación completa de logging. ¿Queda algún 
  print() sin reemplazar? ¿Los tests cubren el middleware? 
  ¿El formato JSON funciona correctamente?

Ejercicios prácticos

Ejercicio 1: Básico — Explore tu proyecto

Abre Claude Code en tu proyecto y ejecuta una exploración completa:

> Analiza este proyecto. Dame un reporte que incluya:
  1. Stack tecnológico
  2. Estructura de archivos
  3. Dependencias principales
  4. Entry points
  5. Estado de los tests (si hay)

Objetivo: Familiarizarte con el output de Explore mode.

Ejercicio 2: Básico — Plan una mejora

Identifica algo que puedas mejorar en tu proyecto y usa Plan mode:

/plan [describe la mejora que quieres hacer]

Objetivo: Recibir un plan estructurado y evaluarlo críticamente.

> El paso 3 del plan es muy genérico. Dame más detalle 
  sobre qué cambios exactos harías en ese archivo.

> En el paso 2 mencionas modificar auth.py, pero ese archivo 
  no existe. Se llama authentication.py. Actualiza el plan.

Ejercicio 3: Intermedio — Ciclo completo E→P→C

Ejecuta el ciclo completo para una tarea real:

1. Explore: Analiza un módulo específico de tu proyecto
2. Plan: Diseña una mejora para ese módulo
3. Code: Implementa el primer paso del plan
4. Verify: Pide a Claude que revise lo implementado

Objetivo: Experimentar el ciclo completo de principio a fin.

Ejercicio 4: Intermedio — Comparar con y sin workflow

Haz la misma tarea de dos formas:

Sin workflow:

> [Describe la tarea directamente y deja que Claude la implemente]

Con workflow:

> [Explore → Plan → Code para la misma tarea]

Compara los resultados. ¿Cuál produjo mejor código? ¿Cuál consumió menos contexto?

Ejercicio 5: Avanzado — Modelo y effort escalonado

Practica cambiar de modelo y effort en una sesión:

# Tarea simple → Sonnet
/model sonnet
> ¿Qué versión de Python usa este proyecto?

# Implementación estándar → Sonnet
> Crea un test para el endpoint de login.

# Refactoring → Opus (effort high por default)
/model opus
> Refactoriza el servicio de usuarios para separar la lógica
  de validación de la lógica de persistencia.

# Arquitectura → Opus + Plan
/plan Diseña un sistema de rate limiting para la API.
Considera: por IP, por usuario, por endpoint. Quiero un
plan completo con opciones.

Objetivo: Sentir la diferencia entre modelos y aprender a elegir la combinación correcta.

Ejercicio 6: Challenge — Multi-modo en una sesión real

Simula una sesión de trabajo real de 30 minutos usando los tres modos:

1. Empieza con Explore para entender el estado actual de tu proyecto
2. Identifica 2-3 mejoras posibles
3. Usa Plan para diseñar la mejora más importante
4. Implementa con Code (incremental, paso a paso)
5. Verifica con Explore
6. Haz commit del resultado

Objetivo: Integrar todo en un flujo de trabajo natural.

> Dame un análisis del estado actual del proyecto. ¿Qué áreas 
  necesitan mejora? ¿Hay deuda técnica? ¿Tests faltantes?

/plan [Elige la mejora más impactante que Claude identificó 
y pide un plan]

> Revisa todo lo que implementamos. ¿Está todo correcto?

> Haz commit con un mensaje descriptivo.

Resumen

Lo que aprendiste en esta cápsula:

• Explore mode es análisis read-only. Úsalo para entender antes de actuar. Se activa con prompts de análisis o a través del subagent built-in de Explore.
• Plan mode es diseño sin ejecución. Se activa con /plan o pidiendo explícitamente que planifique. Produce un plan que revisas antes de ejecutar.
• Agent/Code mode es ejecución completa (default). Lee, escribe, ejecuta comandos. Pide confirmación para acciones destructivas.
• El ciclo Explore → Plan → Code es iterativo, no lineal. Adapta la variación según la tarea.
• Effort level (Opus 5, Sonnet 5 y Fable 5) controla la profundidad de razonamiento. Los modelos actuales tienen 5 niveles (low, medium, high, xhigh, max) con high como default; xhigh es el recomendado para coding. Se ajusta con /effort, en /model con flechas, o en settings.
• Sin workflow, obtienes resultados genéricos. Con workflow, obtienes resultados que respetan tu arquitectura existente.

Siguiente cápsula: 03 - Multi-turn conversations — cómo iterar efectivamente con Claude Code en conversaciones de múltiples mensajes.

Recursos adicionales

Documentación oficial

• Claude Code Best Practices — Workflows y context management recomendados por Anthropic
• Sub-agents — Explore subagent y otros subagents built-in
• Interactive Mode — Shortcuts, permissions, y task management
• CLI Reference — Referencia completa de comandos y flags
• Model Configuration — Modelos, aliases, y effort levels

Contexto y configuración

• Memory — Cómo CLAUDE.md influye en cada modo
• Settings — Configuración de permisos y scopes

Complementarios

• Claude Code Overview — Arquitectura general y capabilities
• Hooks — Automatizar acciones en cada modo (siguiente módulo)