Claude Code plan mode: planificar antes de ejecutar

Tú revisas el plan, lo apruebas (o lo modificas) y solo entonces Claude Code ejecuta los cambios. Es como la diferencia entre un desarrollador que se lanza a codificar y uno que primero dibuja la arquitectura en una pizarra.

Para tareas simples, plan mode es innecesario. Para tareas complejas que tocan múltiples archivos o tienen impacto arquitectónico, puede ahorrarte horas de revertir cambios mal ejecutados.

Cómo activarlo

Hay dos formas de activar plan mode:

1. Atajo de teclado:

Pulsa Shift+Tab antes de enviar tu mensaje. El modo cambia de "ejecutar" a "planificar". Lo verás indicado en la interfaz.

2. Instrucción explícita:

> Analiza este proyecto y crea un plan detallado para
 implementar autenticación con OAuth2. No hagas cambios
 todavía, solo planifica.

Ambas formas producen el mismo resultado: Claude Code investiga, piensa y presenta un plan sin tocar ningún archivo.

Cuándo usarlo

Usa plan mode para:

• Refactorizaciones grandes: Cambiar la estructura de carpetas, renombrar módulos, reorganizar imports.
• Features nuevas complejas: Autenticación, pagos, notificaciones. Todo lo que toca 5+ archivos.
• Migraciones: Base de datos, framework, librerías. Cambios con riesgo de romper cosas.
• Cuándo no estás seguro: Si no sabes cuál es el mejor enfoque, plan mode te da opciones antes de comprometerte.
• Cambios con dependencias: Cuando el orden importa. Primero la migración, luego el modelo, luego el endpoint.
• Onboarding en codebase nuevo: "Planifica cómo implementarías X" te da un mapa del proyecto sin tocar nada.

No lo uses para:

• Cambios de una línea (arreglar un typo, cambiar un color)
• Tareas donde ya sabes exactamente qué hacer
• Generación de código nuevo sin dependencias con lo existente
• Correcciones triviales que no afectan arquitectura

Workflow paso a paso

El flujo de plan mode sigue siempre el mismo patrón, independientemente de la tarea:

Paso 1: Activa plan mode

Shift+Tab o instrucción explícita. Claude Code cambia a modo planificación.

Paso 2: Describe la tarea

Sé específico. "Implementa pagos con Stripe" es peor que "Implementa pagos con Stripe: checkout session, webhook para confirmar pago, actualizar estado del pedido en DB, enviar email de confirmación".

Paso 3: Claude Code investiga

Lee archivos, analiza la estructura del proyecto, identifica dependencias. En proyectos grandes, este paso puede tardar 30-60 segundos mientras escanea el codebase.

Paso 4: Presenta el plan

Un documento estructurado con: análisis del estado actual, pasos ordenados, riesgos, alternativas y estimación de archivos afectados.

Paso 5: Tú revisas y ajustas

Puedes aprobar tal cual, pedir cambios, reordenar pasos, eliminar partes o añadir requisitos que olvidaste.

Paso 6: Ejecuta

Cuándo dices "adelante" o "ejecuta", Claude Code implementa el plan paso a paso. Puedes detenerlo en cualquier momento si algo no se ve bien.

Anatomía de un buen plan

Un plan bien hecho por Claude Code incluye:

1. Análisis del estado actual: Qué archivos existen, qué dependencias hay, qué patrones sigue el código.
2. Pasos ordenados: Cada paso con su objetivo, archivos afectados y dependencias con otros pasos.
3. Riesgos identificados: Qué puede salir mal, qué tests se podrían romper, qué migraciones son necesarias.
4. Alternativas (si las hay): "Podemos usar OAuth2 con Supabase Auth (más simple) o con un provider externo (más flexible)".
5. Estimación: Qué archivos se crean, cuáles se modifican, cuántos tests nuevos.

Si el plan no incluye todo esto, pide más detalle antes de aprobar:

> El plan se ve bien, pero falta:
 - Qué tests se ven afectados
 - Si necesitamos migración de base de datos
 - Cuál es el orden de implementación
 Amplía el plan con estos puntos.

Ejemplo: migración de base de datos

Un caso real donde plan mode ahorra problemas:

> [plan mode activado]
 Necesito migrar de SQLite a PostgreSQL.
 El proyecto usa FastAPI con SQLAlchemy.
 Planifica la migración paso a paso.

Claude Code generará algo como:

## Plan: Migración SQLite → PostgreSQL

### Análisis
- 12 modelos SQLAlchemy en models/
- 3 archivos con queries raw en utils/
- 45 tests que usan SQLite en memoria
- Alembic configurado pero sin migraciones

### Pasos
1. Actualizar dependencias (psycopg2-binary, etc.)
2. Modificar DATABASE_URL en .env.example
3. Revisar modelos: adaptar tipos SQLite-específicos
4. Convertir queries raw a SQLAlchemy ORM
5. Crear migración Alembic initial
6. Adaptar tests para usar PostgreSQL de test
7. Verificar: ejecutar test suite completa

### Riesgos
- Queries raw en utils/reports.py usan funciones SQLite
- Test fixtures asumen SQLite en memoria (rápido)
- Columna "created_at" usa DATETIME (cambiar a TIMESTAMP)

### Alternativa
Usar asyncpg en lugar de psycopg2 (mejor perf async)

Con este plan puedes identificar problemas antes de que ocurran. Sin plan mode, Claude Code empezaría a cambiar archivos y podrías descubrir el problema de las queries raw después de 20 minutos de cambios.

Plan mode vs ejecución directa

La pregunta no es si plan mode es "mejor" que la ejecución directa. Son herramientas diferentes para situaciones diferentes. Aquí tienes una guía clara:

Ejecución directa gana cuando:

• La tarea es simple y bien definida (menos de 3 archivos).
• Ya has hecho algo similar antes y sabes cómo debería quedar.
• El cambio es reversible fácilmente (un git revert lo arregla).
• Estás prototipando y no te importa si hay que rehacerlo.

Plan mode gana cuando:

• La tarea toca 5+ archivos con dependencias entre ellos.
• Un error sería costoso de revertir (migraciones de DB, cambios de API pública).
• Necesitas evaluar múltiples enfoques antes de elegir uno.
• Estás trabajando en código que no escribiste y necesitas entenderlo primero.
• Hay restricciones que Claude Code podría no inferir solo (performance, compatibilidad, regulación).

En la práctica, la proporción es aproximadamente 70% ejecución directa, 30% plan mode. La mayoría del trabajo diario son cambios puntuales donde no necesitas un plan. Pero para el 30% restante, plan mode es la diferencia entre un refactor limpio y 2 horas desenredando cambios rotos.

Revisar y editar planes

El plan no es definitivo. Es un punto de partida para la conversación. Puedes modificarlo de varias formas:

Reordenar pasos:

> Mueve el paso 5 (crear migración) antes del paso 3
 (adaptar modelos). Quiero la migración como base antes
 de tocar los modelos.

Añadir requisitos:

> Añade al plan:
 - Paso de backup de la DB actual antes de migrar
 - Script de rollback en caso de fallo
 - Documentación del proceso en docs/migrations/

Eliminar partes:

> Elimina el paso de adaptar tests. Los tests los haré
 yo manualmente después. Céntrate solo en el código
 de producción.

Cambiar el enfoque completo:

> Descarta este plan. En lugar de migrar todo de golpe,
 planifica una migración incremental: primero las tablas
 de solo lectura, luego las transaccionales, y por último
 las de sesión.

Claude Code actualiza el plan y espera tu confirmación final. Solo cuando dices "ejecuta" o "adelante" empieza a hacer cambios reales.

Ejemplos de planificación compleja

Más allá de migraciones, plan mode brilla en estos escenarios:

Implementar un sistema de permisos:

> [plan mode] Necesito implementar RBAC (Role-Based Access Control).
 Roles: admin, editor, viewer.
 El frontend debe ocultar elementos según permisos.
 El backend debe verificar permisos en cada endpoint.
 La DB necesita tablas de roles y permisos.
 Planifica considerando que ya tenemos autenticación con JWT.

Un sistema de permisos toca frontend, backend, DB y middlewares. Sin plan, Claude Code podría empezar por el frontend y luego darse cuenta de que la estructura del backend no encaja. Con plan, ves el panorama completo antes de escribir una línea.

Refactorizar un monolito a microservicios:

> [plan mode] Quiero extraer el módulo de notificaciones
 (email, push, SMS) de este monolito FastAPI a un servicio
 independiente. Planifica:
 - Qué código se mueve
 - Cómo se comunican (REST, eventos, colas)
 - Qué tests hay que adaptar
 - Plan de migración sin downtime

Integrar un servicio externo:

> [plan mode] Integrar Stripe para pagos recurrentes.
 Necesito: checkout session, webhooks, customer portal,
 sincronización de estado de suscripción con nuestra DB,
 y retry logic para webhooks fallidos.
 Tenemos FastAPI + PostgreSQL + Celery.

En todos estos casos, el plan te permite ver las interdependencias y elegir el orden correcto antes de comprometer código.

Plan mode + worktrees

La combinación más potente de Claude Code para cambios arriesgados: planificas, ejecutas en un worktree (rama paralela), verificas que todo funciona, y solo entonces mergeas a tu rama principal.

El flujo:

1. Activa plan mode y genera el plan.
2. Revisa y aprueba el plan.
3. Antes de ejecutar, crea un worktree: Claude Code puede ejecutar los cambios en una copia paralela del proyecto.
4. Ejecuta el plan en el worktree.
5. Verifica: tests pasan, build funciona, la app se comporta correctamente.
6. Si todo OK, mergea el worktree a tu rama. Si algo falla, descarta sin afectar nada.

Cuándo usar esta combinación:

• Migraciones de DB que podrían romper el schema.
• Upgrades de dependencias mayores (React 18 a 19, Next.js 14 a 15).
• Refactorizaciones que tocan más de 20 archivos.
• Cualquier cambio donde "si falla, vuelvo atrás" no es trivial.

Sin worktrees, un plan fallido te deja con un git stash complicado o un revert parcial. Con worktrees, el peor caso es eliminar la copia y empezar de nuevo con una versión mejorada del plan.

Tips para planes efectivos

Después de cientos de planes ejecutados, estos son los patrones que producen mejores resultados:

1. Sé específico sobre las restricciones

No digas solo "implementa pagos". Di "implementa pagos con Stripe, debe soportar EUR y USD, con idempotency keys, y retry exponential para webhooks". Las restricciones acotan el plan y evitan que Claude Code tome decisiones que tendrás que revertir.

2. Menciona lo que NO quieres

"No uses npm install para nuevas deps sin mi aprobación" o "No toques los archivos de configuración de CI" evita sorpresas en el plan.

3. Pide alternativas cuando no estés seguro

"Planifica dos enfoques: uno con cola de mensajes y otro con polling. Compáralos en complejidad, latencia y coste de infra". Claude Code te presenta ambas opciones con pros y contras.

4. Divide planes largos en fases

Si el plan tiene más de 10 pasos, pide que lo divida en fases. "Fase 1: infraestructura (DB + modelos). Fase 2: lógica de negocio. Fase 3: API + tests". Ejecuta fase por fase, verificando después de cada una.

5. Incluye criterios de éxito

"El plan se considera exitoso si: todos los tests pasan, el build genera sin errores, y puedo crear un usuario nuevo desde la UI". Esto le da a Claude Code un objetivo verificable.

6. Pide que identifique lo que no sabe

"Si hay algo que necesitas saber pero no puedes determinar del código (configuración de producción, comportamiento actual de la API externa, etc.), pregúntame antes de planificar ese paso". Evita planes basados en suposiciones incorrectas.

Preguntas frecuentes

¿Plan mode consume más tokens?

Sí, ligeramente. Claude Code necesita analizar el proyecto antes de planificar. Pero el coste extra es mínimo comparado con el ahorro de no tener que revertir cambios mal ejecutados. Un plan de 5 minutos puede ahorrar 2 horas de debugging.

¿Puedo guardar un plan para ejecutarlo después?

No hay un botón de "guardar plan", pero puedes copiar el plan a un archivo (plan.md) y usarlo como referencia en una sesión futura. O usar MEMORY.md para que Claude Code recuerde las decisiones del plan entre sesiones.

¿El plan se ejecuta exactamente cómo se describe?

En general sí, pero Claude Code puede adaptarse si encuentra algo inesperado durante la ejecución (un archivo que no existe, un conflicto de tipos, etc.). Te avisará si necesita desviarse del plan.

¿Puedo ejecutar solo parte del plan?

Sí. Puedes decir "ejecuta solo los pasos 1-3" y dejar el resto para después. Esto es útil para planes largos donde quieres verificar cada fase.

¿Plan mode funciona en proyectos qué no conozco?

Es precisamente donde más brilla. Si te incorporas a un proyecto existente, "planifica cómo implementarías X" te da un mapa del código sin riesgo de romper nada.

Siguiente paso

Prueba plan mode en tu próxima tarea compleja. La diferencia es inmediata: menos cambios que revertir, más control sobre la dirección del código, y un registro claro de las decisiones tomadas.

Combina plan mode con MEMORY.md para que las decisiones del plan se persistan entre sesiones, y con managed agents para ejecutar los pasos del plan en paralelo.

Si estás empezando con Claude Code, revisa primero nuestra guía de Claude Code para principiantes.