Claude Code Plan Mode: Plan Before Executing

You review the plan, approve it (or modify it) and only then Claude Code executes the changes. It's like the difference between a developer who jumps straight to coding and one who first draws the architecture on a whiteboard.

For simple tasks, plan mode is unnecessary. For complex tasks touching multiple files or with architectural impact, it can save you hours of reverting poorly executed changes.

How to activate it

There are two ways to activate plan mode:

1. Keyboard shortcut:

Press Shift+Tab before sending your message. The mode changes from "execute" to "plan". You'll see it indicated in the interface.

2. Explicit instruction:

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

Both methods produce the same result: Claude Code investigates, thinks and presents a plan without touching any file.

When to use it

Use plan mode for:

• Large refactorings: Changing folder structure, renaming modules, reorganizing imports.
• Complex new features: Authentication, payments, notifications. Anything touching 5+ files.
• Migrations: Database, framework, libraries. Changes with risk of breaking things.
• When you're unsure: If you don't know the best approach, plan mode gives you options before committing.
• Changes with dependencies: When order matters. First the migration, then the model, then the endpoint.
• Onboarding to new codebase: "Plan how you'd implement X" gives you a project map without touching anything.

Don't use it for:

• One-line changes (fixing a typo, changing a color)
• Tasks where you already know exactly what to do
• New code generation without dependencies on existing code
• Trivial fixes that don't affect architecture

Step-by-step workflow

The plan mode flow always follows the same pattern, regardless of the task:

Step 1: Activate plan mode

Shift+Tab or explicit instruction. Claude Code switches to planning mode.

Step 2: Describe the task

Be specific. "Implement payments with Stripe" is worse than "Implement payments with Stripe: checkout session, webhook to confirm payment, update order status in DB, send confirmation email".

Step 3: Claude Code investigates

Reads files, analyzes project structure, identifies dependencies. In large projects, this step can take 30-60 seconds while scanning the codebase.

Step 4: Presents the plan

A structured document with: current state analysis, ordered steps, risks, alternatives and estimation of affected files.

Step 5: You review and adjust

You can approve as-is, request changes, reorder steps, remove parts or add requirements you forgot.

Step 6: Execute

When you say "go ahead" or "execute", Claude Code implements the plan step by step. You can stop it at any moment if something doesn't look right.

Anatomy of a good plan

A well-made plan by Claude Code includes:

1. Current state analysis: What files exist, what dependencies there are, what patterns the code follows.
2. Ordered steps: Each step with its objective, affected files and dependencies with other steps.
3. Identified risks: What can go wrong, what tests might break, what migrations are needed.
4. Alternatives (if any): "We can use OAuth2 with Supabase Auth (simpler) or with an external provider (more flexible)".
5. Estimation: What files are created, which are modified, how many new tests.

If the plan doesn't include all this, ask for more detail before approving:

> 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.

Example: database migration

A real case where plan mode saves problems:

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

Claude Code will generate something like:

## 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)

With this plan you can identify problems before they happen. Without plan mode, Claude Code would start changing files and you might discover the raw queries problem after 20 minutes of changes.

Plan mode vs direct execution

The question isn't whether plan mode is "better" than direct execution. They're different tools for different situations. Here's a clear guide:

Direct execution wins when:

• 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 Mayrí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 Mayres (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.

FAQ

¿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.

Next step

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.