Modo plan de Claude Code

El modo plan es un modo de permisos de Claude Code en el que el agente solo puede leer y analizar: explora el repositorio, busca, lee archivos y razona, pero no edita nada ni ejecuta comandos que modifiquen el sistema. Su resultado es un plan de implementación que revisas y apruebas antes de que se toque una sola línea. Separa de forma explícita la fase de pensar de la fase de hacer.

Cómo funciona

Claude Code tiene varios modos de permisos y el modo plan es uno de ellos. En la sesión interactiva se activa pulsando Shift+Tab, que va rotando entre el modo normal, la aceptación automática de ediciones y el modo plan; la interfaz indica cuál está activo. También puedes arrancar directamente en él:

claude --permission-mode plan

O fijarlo como modo por defecto en la configuración del proyecto (.claude/settings.json) con "defaultMode": "plan".

Mientras está activo, Claude dispone de herramientas de lectura (leer archivos, listar directorios, buscar con patrones, consultar la web) y puede delegar la investigación en subagentes, pero las herramientas de escritura y los comandos de shell con efectos quedan bloqueados. Cuando termina de investigar, presenta el plan y te pide confirmación. En ese punto puedes aprobarlo y pasar a ejecución, eligiendo si quieres revisar cada edición o aceptarlas automáticamente, o bien rechazarlo y seguir iterando con más indicaciones.

Por qué importa

El fallo más caro de un agente de programación no es escribir mal una función, sino entender mal la tarea y modificar quince archivos en la dirección equivocada. El modo plan ataca ese problema:

• Detectas malentendidos antes de que cuesten: corregir un plan es más barato que revertir un diff enorme.
• Exploración segura: puedes pedir a Claude que estudie un código desconocido o un sistema en producción sin riesgo de cambios accidentales.
• Mejores resultados en tareas grandes: obligar al modelo a razonar sobre la arquitectura antes de escribir suele producir cambios más coherentes en refactorizaciones o funcionalidades que tocan muchas piezas.
• Control del contexto: un plan aprobado sirve como guion compartido para la fase de ejecución y como referencia si la sesión se alarga.

Un caso de uso típico

Quieres migrar la autenticación de un backend de sesiones a JWT. En modo plan pides: "Analiza cómo funciona la autenticación actual y propón un plan de migración a JWT". Claude localiza los middlewares, las rutas afectadas y los tests, y devuelve un plan por pasos con los archivos implicados, riesgos y orden de cambios. Tú detectas que olvidó el servicio de WebSockets, se lo indicas, el plan se actualiza y solo entonces apruebas la ejecución.

Un patrón habitual es combinarlo con selección de modelo: planificar con el modelo más capaz y ejecutar con uno más rápido. Claude Code ofrece configuraciones pensadas para esto, aunque las opciones concretas dependen de la versión y del plan de suscripción. Si quieres trabajar estos flujos de forma estructurada, aquí encaja aprender a desarrollar con Claude Code paso a paso.

Errores comunes

• Confundirlo con extended thinking: el pensamiento extendido es razonamiento interno del modelo; el modo plan es una restricción de permisos sobre lo que el agente puede hacer. Se pueden usar a la vez.
• Usarlo para todo: para cambios triviales (renombrar una variable, corregir un typo) añade fricción sin beneficio.
• Aprobar sin leer: el valor está en revisar el plan. Si lo aceptas a ciegas, pierdes la principal ventaja.
• Pensar que es lo contrario del modo automático: el modo plan restringe la acción a lectura; los modos de aceptación automática reducen las confirmaciones durante la ejecución. Son fases distintas del mismo flujo, y es normal encadenarlos.