Plan mode en Claude Code: primero el plan, después el código

Plan mode en Claude Code es un modo de permisos en el que Claude lee tu código, explora y te propone un plan, pero no edita nada hasta que lo apruebas. Se activa con Shift+Tab. Sirve para revisar los archivos, los pasos, los riesgos y los tests de un cambio antes de que exista una sola línea nueva.

Este tutorial explica cómo entrar en plan mode, qué debe tener un plan para aprobarlo y cómo corregirlo, con un ejemplo real: añadir envío gratis a una tienda de prueba sin romper su checkout, hecho con Claude Code 2.1.238. Es la parte 8 de nuestra serie de Claude Code; en la parte 6 armamos un subagente que revisa el código ya escrito, y plan mode es la revisión que va antes.

Cómo entrar en plan mode

La forma rápida es Shift+Tab durante una sesión. Cada pulsación cambia el modo de permisos en este orden: default, acceptEdits, plan. Si estás en auto, la primera pulsación te lleva a default. Sabes que estás en plan mode porque la barra de estado muestra ⏸ plan mode on; otra pulsación de Shift+Tab te saca sin aprobar nada.

Hay otras tres formas, según la documentación de modos de permisos:

Para que un proyecto arranque siempre en plan mode, este es el archivo completo. Lo probamos sin pasar ningún flag y la sesión empezó en plan:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

Una excepción: las conversaciones que abre la extensión de VS Code no leen el modo inicial de la configuración del proyecto. Ahí se configura con claudeCode.initialPermissionMode en los ajustes de usuario de VS Code.

Qué hace Claude en plan mode

En plan mode Claude lee archivos, corre comandos de terminal para explorar y escribe un plan, pero no edita tu código. Con los comandos hay matices: si tu sesión tiene disponible el modo auto, un clasificador decide qué comandos de exploración corren; si no, los que no están en la lista de comandos de solo lectura te piden permiso. Las ediciones de tus archivos quedan bloqueadas hasta que apruebas el plan.

El plan se guarda como un archivo Markdown en ~/.claude/plans/, salvo que cambies la carpeta con el ajuste plansDirectory. En nuestra prueba el archivo se llamó a-ade-env-o-gratis-para-compiled-badger.md: un nombre generado a partir del prompt, con la «ñ» convertida en guion.

Plan mode mantiene el bloqueo también fuera de la terminal interactiva, por ejemplo con claude -p. Lo comprobamos: después de la sesión de planificación, git status no mostraba ningún cambio en el proyecto.

Qué debe tener un plan

Un plan sirve si puedes decidir con él. Para eso necesita seis cosas:

• Archivos. Cada archivo que va a crear o cambiar, y por qué. Si aparece uno que no esperabas, pregunta antes de aprobar.
• Pasos. En orden y comprobables: «añadir la constante», «cambiar el cálculo de envío», no «mejorar el checkout».
• Riesgos. Qué puede romperse. En una tienda, casi siempre checkout, precios, impuestos o eventos de analítica.
• Dudas. Decisiones de negocio que Claude no debería tomar solo. Un plan sin dudas en un cambio de precios suele esconder una suposición.
• Tests. Qué tests añade o cambia y con qué comando se corren.
• Cómo deshacerlo. Qué revertir si algo sale mal.

No hace falta pedirlo en cada prompt. Si lo escribes en el CLAUDE.md del proyecto, Claude lo lee al empezar cada sesión. Este es el de la tienda de prueba:

# Tienda de prueba

Proyecto mínimo para probar plan mode. Los importes van en céntimos. Tests: `npm test`.

## Cómo quiero los planes

Cuando estés en plan mode, el plan debe tener estas secciones, en este orden:

1. **Archivos**: cada archivo que vas a crear o cambiar, y por qué.
2. **Pasos**: en orden, uno por línea, cada uno comprobable.
3. **Riesgos**: qué puede romperse (checkout, precios, impuestos, analítica) y cómo lo evitas.
4. **Dudas**: decisiones de negocio que no puedes tomar solo. Pregúntalas; no las supongas.
5. **Tests**: qué tests añades o cambias y con qué comando se corren.
6. **Cómo deshacerlo**: qué revertir si algo sale mal.

No cambies `src/checkout.js` sin un test que cubra el caso nuevo.

Ejemplo: envío gratis sin romper el checkout

La tienda de prueba, incluida en el ZIP de la guía, tiene un checkout de 15 líneas y cuatro tests. Los importes van en céntimos y el envío cuesta siempre 4,90 €, salvo con el carrito vacío:

// Resumen del checkout de la tienda de prueba. Los importes van en céntimos para
// no arrastrar errores de coma flotante.

export const ENVIO = 490;

export function subtotal(lineas) {
  return lineas.reduce((suma, l) => suma + l.precio * l.cantidad, 0);
}

export function resumen(lineas, cupon = null) {
  const sub = subtotal(lineas);
  const descuento = cupon ? Math.min(cupon.importe, sub) : 0;
  const envio = sub === 0 ? 0 : ENVIO;
  return { subtotal: sub, descuento, envio, total: sub - descuento + envio };
}

En plan mode y con Sonnet, le pedimos: «Añade envío gratis para pedidos desde 50 € sin romper el checkout». Claude leyó src/checkout.js, el test y package.json, y escribió un plan con las seis secciones del CLAUDE.md. Esta es una parte del archivo que guardó:

Lo valioso está en la sección de dudas. «Envío gratis desde 50 €» parece una regla clara, pero tiene dos decisiones dentro: si los 50 € se miden antes o después del cupón, y si 50,00 € exactos ya cuentan. El plan proponía medir antes del cupón: con esa regla, un carrito de 60 € con un cupón de 15 € paga 45 € y no paga envío. Es una decisión de negocio, y el plan la dejó a la vista en lugar de esconderla en una línea de código.

La sesión de planificación tardó 62 segundos y costó 0,72 USD según el campo total_cost_usd. Es una cifra de esta prueba, con Sonnet y un proyecto diminuto, no una tarifa.

Corregir el plan y aprobarlo

En una sesión interactiva, cuando el plan está listo Claude Code te pregunta cómo seguir. Según la documentación actual, las opciones son:

• Yes, and use auto mode: aprueba y empieza a editar en modo auto. Si tu sesión no tiene ese modo, la opción se llama Yes, auto-accept edits.
• Yes, manually approve edits: aprueba, pero revisas cada edición.
• No, keep planning: sigues en plan mode y le dices a Claude qué cambiar.

Para cambios pequeños en el plan, Ctrl+G lo abre en tu editor de texto y lo editas directamente antes de que Claude siga. Para una decisión como la del cupón, es más claro elegir «No, keep planning» y escribirla.

Nosotros hicimos lo mismo sin la interfaz: continuamos la sesión del plan con claude -c -p, la corrección y permiso para editar y correr los tests:

claude -c -p "Cambia una cosa del plan: el umbral se mide sobre el subtotal después del cupón, no antes. 50,00 € exactos sí tienen envío gratis. Con ese cambio, implementa el plan y corre npm test al terminar." --permission-mode acceptEdits --allowedTools "Bash(npm test)"

Claude cambió solo los dos archivos del plan. En src/checkout.js, el cálculo del envío pasó a usar el subtotal neto:

+export const UMBRAL_ENVIO_GRATIS = 5000;
 ...
-  const envio = sub === 0 ? 0 : ENVIO;
+  const neto = sub - descuento;
+  const envio = sub === 0 ? 0 : neto >= UMBRAL_ENVIO_GRATIS ? 0 : ENVIO;

Y añadió cuatro tests: justo por debajo del umbral, justo en el umbral, por encima y uno que fija la decisión que tomamos («el umbral se evalúa sobre el subtotal después del cupón»). npm test pasó 8 de 8: los cuatro tests originales del checkout siguieron en verde. La implementación costó 0,71 USD y 44 segundos.

Cuándo usar plan mode y cuándo no

La regla práctica: si al leer el pedido ya ves dos formas razonables de hacerlo, planifica. En nuestro ejemplo había dos (antes o después del cupón) y el plan las encontró.

Errores comunes

• Aprobar sin leer. Plan mode solo sirve si lees el plan. Aprobar a ciegas es lo mismo que no usarlo, con más espera.
• Aceptar un plan sin dudas en un cambio de negocio. Si toca precios o envíos y no pregunta nada, probablemente decidió por ti.
• Corregir después en lugar de antes. Cambiar una línea del plan cuesta un mensaje; cambiar el código ya escrito cuesta otra implementación y otra revisión.
• Pedir el formato en cada prompt. Escríbelo una vez en CLAUDE.md.
• Dejar plan mode por defecto en todos los proyectos. Para tareas pequeñas añade espera sin aportar nada. Úsalo por defecto solo donde cada cambio es delicado.
• Olvidar que aprobar cambia el modo. Al aprobar, la sesión sale de plan mode. Para planificar la siguiente tarea, vuelve con Shift+Tab o /plan.

Preguntas frecuentes

¿Plan mode gasta menos que trabajar directo?

No necesariamente: planificar también lee archivos y genera texto. En nuestra prueba, plan e implementación costaron casi lo mismo cada uno. Lo que ahorra es rehacer: una decisión equivocada en el checkout cuesta mucho más que un plan.

¿Puede Claude correr comandos en plan mode?

Sí, para explorar: listar archivos, buscar, leer el historial de git. Según tu configuración, esos comandos los aprueba un clasificador o te los pregunta. Lo que no hace es editar tus archivos hasta que apruebes.

¿Dónde queda el plan después de aprobarlo?

En ~/.claude/plans/, como archivo Markdown. Puedes guardarlo en el PR o en el ticket para que el equipo vea qué se decidió y por qué.

¿Funciona en scripts y en CI?

Sí: claude -p --permission-mode plan planifica sin editar, como en nuestra prueba. Cómo llevar Claude Code a un pipeline está en la parte 9 de la serie.

¿Qué hago si el plan es demasiado largo?

Probablemente la tarea también lo es. Pide que la divida en partes que se puedan aprobar y probar por separado, y planifica la primera.

Checklist

• Sabes entrar con Shift+Tab y ves ⏸ plan mode on en la barra de estado.
• Tu CLAUDE.md pide las seis secciones del plan.
• El plan nombra cada archivo que va a cambiar.
• Las dudas de negocio están respondidas antes de aprobar.
• El plan dice qué tests se añaden y con qué comando se corren.
• Después de implementar, los tests que ya existían siguen en verde.

Plan mode convierte el «hazlo» en «enséñame cómo lo harías», y esa pausa es donde se atrapan los errores más caros. Después del cambio, el subagente revisor le da una segunda lectura y el hook del linter cuida el formato en cada edición; para llevar todo a tu pipeline, sigue con Claude Code en GitHub Actions. Si tu proyecto guarda secretos, empieza por proteger tu .env, y el método completo está en mi flujo de 4 pasos con Claude Code.

¿Viste esto en Instagram? Comenta PLAN en el Reel o el carrusel y te mando la guía.