Claude Code Plan Mode: bucles de refactorización con revisión de diseño primero

Muchos desarrolladores empiezan a usar Claude Code de la misma manera: pegan una tarea, dejan que se ejecute y revisan el diff. Eso funciona para cambios pequeños, pero en cuanto tocas varios archivos, el proceso empieza a fallar. 

Cada decisión sin guía que toma Claude puede ser correcta la mayoría de las veces, lo cual suena bien hasta que lo encadenas: por ejemplo, si asumes un 80% de acierto por decisión, en una funcionalidad con 20 puntos de decisión, 0.8^20 reduce tus probabilidades a alrededor de un 1%.

Plan Mode cambia la ecuación añadiendo una fase de solo lectura. Obligas a Claude a leer la base de código, plantear preguntas y generar un plan que tú revisas antes de tocar un solo archivo. 

Este tutorial recorre ese flujo con una API de blog en FastAPI desordenada como ejemplo, cubriendo el bucle Explorar-Planificar-Ejecutar, la edición del plan con Ctrl+G y cómo escalar a refactorizaciones mayores con Agent Teams. 

Nuestro tutorial de buenas prácticas de Claude Code profundiza en el problema del error acumulado, y la guía de Claude Code 2.1 te ayuda con la instalación y las funciones si necesitas soporte de configuración.

Para más información sobre los modelos detrás de Claude Code, echa un vistazo a nuestras guías de Claude Sonnet 4.6 y Opus 4.6, o realiza nuestro curso Introduction to Claude Models.

¿Qué es el Plan Mode de Claude Code?

Plan Mode bloquea a Claude en operaciones de solo lectura. Puede leer archivos, buscar en la base de código y hacerte preguntas, pero rechazará cualquier intento de escribir archivos, editar código o ejecutar comandos de shell. Si le pides "haz este arreglo rápido" estando en Plan Mode, no cederá.

Puedes activarlo de cuatro maneras:

• Pulsar Shift+Tab dos veces en el campo de entrada para alternar entre Normal, Auto-Accept y Plan Mode

• El comando /plan activa Plan Mode hasta que cambies de modo

• La flag de CLI --permission-mode plan inicia una nueva sesión en Plan Mode

• Una entrada en settings.json bajo permissions.defaultMode establece Plan Mode como tu valor predeterminado permanente

Cuando Claude termina de generar un plan, lo guarda como un archivo markdown en ~/.claude/plans/ con un nombre aleatorio (por ejemplo, dreamy-orbiting-quokka.md). 

Ese archivo es un contrato revisable: persiste entre sesiones, sobrevive a /clear y a la compactación de contexto, y no se implementa nada hasta que lo apruebas. Ten en cuenta que, aunque el archivo del plan persiste, Claude a veces puede perder su rastro tras una compactación de contexto si no le pides que lo vuelva a leer.

Si quieres guardar los planes dentro de tu proyecto para control de versiones, configura plansDirectory en settings.json con una ruta relativa al proyecto como ./plans.

Los planes relativos al proyecto habilitan flujos de trabajo que ~/.claude/plans/ no permiten:

• Revisar diffs del plan en pull requests antes de que nadie empiece a programar
• Conservar anotaciones entre sesiones sin depender de la compactación de contexto
• Tratar el archivo markdown como una especificación viva que varios miembros del equipo editan directamente

Para refactorizaciones de larga duración o trabajo en varias sesiones, un archivo de plan bajo control de versiones te da más control que Ctrl+G por sí solo.

Implementar un flujo Explorar-Planificar-Ejecutar con Claude Code

Para ver cómo encajan las tres fases, vamos a refactorizar un repositorio fastapi-blog-api. No incluye tests y tiene tres archivos que hacen demasiado: 

• main.py: todas las rutas, comprobaciones de autenticación inline, configuración hardcodeada, envío de emails

• models.py: modelos ORM, esquemas Pydantic, funciones de consulta, datos seed

• utils.py: hash de contraseñas, tokens JWT, subidas a S3, renderizado de markdown, caché, limitación de tasa, exportación a CSV

Fase 1: reúne contexto antes de nada

Empieza la tarea en Plan Mode (clona antes el repo de GitHub en local). El prompt inicial debe decirle a Claude qué quieres y dirigirlo a leer los archivos relevantes:

I want to refactor this FastAPI blog API into a clean module structure with proper separation of concerns and full test coverage. Read through main.py, models.py, and utils.py first. Map out which functions belong together, flag any shared state or circular dependency risks, and identify what needs testing most.Con la tecnología de

Claude delega la investigación de la base de código a un subagente integrado restringido a herramientas de solo lectura. Leyó los tres archivos, rastreó los imports entre ellos y usó AskUserQuestion para sacar a la luz las ambigüedades. 

Las preguntas cubrían varias decisiones de alto nivel:

• Profundidad arquitectónica (routers planos vs. capas de servicio completas)
• Cómo gestionar la configuración hardcodeada
• Si conviene eliminar o mantener utilidades sin uso
• Qué framework de tests utilizar

Esas preguntas importan. La de arquitectura, por sí sola, habría sido un cara o cruz sin tu aportación. Claude tiende a optar por el patrón que más ha visto en los datos de entrenamiento que, en FastAPI, suele ser una estructura de routers plana. Responder "usa una capa de servicios" aquí ahorró una ronda entera de re-refactorización más adelante.

Si tienes un proyecto de referencia que encaja con tu arquitectura objetivo, inclúyelo en tu prompt. Claude produce mejores planes cuando puede apoyarse en un ejemplo funcional en lugar de descripciones abstractas.

Algo a comprobar antes de aceptar cualquier plan: ¿las preguntas de Claude mencionan funciones concretas y detalles a nivel de línea, o solo nombres de archivo? Si pregunta por "el sistema de auth" pero nunca menciona verify_jwt_token o la cadena de middleware en main.py, ha pasado los archivos por encima en lugar de leerlos. Insístele en que lea con más cuidado antes de pasar a la Fase 2.

Fase 2: genera y edita el plan

Tras responder a las preguntas de Claude, generará un plan automáticamente. No hace falta un prompt aparte. El plan se guarda en ~/.claude/plans/ e incluye: 

• Resumen de contexto
• Estructura de directorios objetivo
• Orden de implementación paso a paso
• Sección de verificación con comandos para confirmar que la refactorización funciona

Antes de decidir cómo continuar, pulsa Ctrl+G para abrir el plan en tu editor de texto por defecto (configurado con $EDITOR). Alternativamente, usa /plan open para abrir directamente el archivo de plan activo.

Plan Mode se amortiza en este paso. Puedes anotar pasos con notas inline, eliminar los que no compartes, reordenar operaciones y guardar. Claude recoge cada edición cuando vuelves al terminal.

Para el plan de la API del blog, las anotaciones podrían ser:

## Step 3: Extract auth module
Move JWT validation and password hashing to auth/
> NOTE: extract auth middleware BEFORE splitting routes,
> otherwise the route files will import from utils.py
> and we'll have to update imports twice
 
## Step 5: Database layer
Create a repository pattern for database operations
> NOTE: keep the SQLAlchemy session factory in a shared
> db.py, don't put it in models.pyCon la tecnología de

Para planes complejos, una sola pasada con Ctrl+G puede no bastar. Anota, vuelve, dile a Claude "atiende todas las anotaciones del plan, no implementes aún", revisa la versión corregida y usa Ctrl+G de nuevo. Cada ronda de anotaciones elimina ambigüedades que, de otro modo, acabarían en decisiones de implementación erróneas.

Cuando el contrato esté como quieres, Claude te ofrece varias opciones: 

1. Trabajar en el plan y limpiar el contexto (bien cuando la sesión ya está cargada), 
2. Trabajar sin limpiar (para conservar el historial de conversación), o 
3. Seguir conversando sobre el plan. 

Elige según el contexto que hayas acumulado. Si llevas mucho en una sesión larga, limpiar le da a Claude una ventana fresca para ejecutar.

Fase 3: ejecuta el plan aprobado

Elige una opción de trabajo y Claude empieza a implementar paso a paso. Avanza por cada paso y se detiene cuando necesita intervención manual (por ejemplo, autenticación interactiva en la terminal) o cuando completa el plan.

Vigila el desvío respecto al plan. El plan decía extraer auth a su propio módulo primero, pero Claude podría empezar a sacar rutas y lógica de auth a la vez porque ve un atajo. Ese tipo de movimiento te deja una base de código a medias, con imports que apuntan a ubicaciones antiguas y otros a las nuevas. 

Otras señales de desvío: 

• Editar un archivo no mencionado en el paso actual
• Tomar en silencio una decisión de arquitectura que el plan había dejado abierta
• Combinar dos pasos que el plan mantenía separados

Cuando ocurra, vuelve a Plan Mode con Shift+Tab. Claude lee el estado actual de los archivos, produce un plan revisado para los pasos restantes y tú lo revisas antes de continuar. No es una medida de emergencia. La mayoría de las refactorizaciones multiarchivo pasan por 2-3 revisiones de plan antes de terminar.

Para refactorizaciones que no quepan en una sola sesión, divide el trabajo en planes secuenciales en lugar de uno grande. Completa la extracción de auth con su propio plan y luego empieza una sesión nueva y un plan para dividir rutas. 

Usa /rename para etiquetar cada sesión (p. ej., "blog-api-auth-extraction") y así retomar donde lo dejaste con /resume. Planes más pequeños mantienen la ventana de contexto enfocada y te dan un punto de control natural entre fases.

Estrategias prácticas para el Plan Mode de Claude Code

Ahora que hemos pasado por todo el proceso una vez, veamos algunas buenas prácticas para sacarle el máximo partido a Plan Mode.

Cuándo usar Plan Mode (y cuándo saltártelo)

No todas las tareas necesitan un plan. Arreglos de una sola línea, correcciones de typos y actualizaciones de funciones aisladas son más rápidas sin la sobrecarga de planificación. Lo mismo ocurre con cambios mecánicos, como renombrar una variable en un archivo.

Una buena regla: si el cambio toca tres o más archivos, o no puedes describirlo en una sola frase, primero planifica. Tres archivos es, más o menos, el punto donde los errores acumulados empiezan a doler, porque cada archivo añade su propio conjunto de decisiones que Claude debe acertar.

Tareas que siempre se benefician de Plan Mode:

• Refactorizaciones que mueven código entre archivos o renombrar interfaces compartidas
• Nuevas funciones que tocan módulos existentes
• Actualizaciones de dependencias con cambios incompatibles en la API
• Cualquier tarea en la que no tengas claro cómo trata un caso concreto la base de código
• Sesiones de brainstorming donde quieres iterar el enfoque con Claude sin riesgo de ediciones prematuras

Cómo detectar planes flojos antes de que te cuesten

Un plan que parece estructurado no siempre es un buen plan. Con las versiones actuales de Claude Code, las referencias alucinadas a archivos y los pasos vagos de "actualiza según sea necesario" son raros. El problema más probable es un plan que pone todos los pasos de implementación primero y deja "añadir tests" para el final.

Los planes estructurados así dan peores resultados de lo esperado. Sin tests durante la implementación, Claude no tiene forma de verificar su propio trabajo a mitad de sesión. Para la refactorización de la API del blog, un plan que dice "Pasos 1-6: extraer todos los módulos, Paso 7: escribir tests" implica seis pasos de código sin bucle de retroalimentación. 

Un plan más sólido usa desarrollo guiado por tests (TDD) e intercala pruebas con implementación: escribe tests para auth/ antes de extraer las funciones de auth, confirma que pasan y luego escribe tests para posts/ antes de separar las rutas. Cada test que pasa le da a Claude una señal clara de que la refactorización va por buen camino. 

Añadir convenciones de TDD a tu CLAUDE.md hace que Claude incluya pasos de test por defecto. Claude Code Hooks puede automatizar este tipo de control ejecutando scripts de validación que comprueban la calidad del plan antes de aprobar la ejecución.

Escalar refactorizaciones grandes con Agent Teams

Los planes que tocan siete o más archivos empiezan a perder calidad porque la ventana de contexto se llena durante la ejecución. La refactorización de la API del blog alcanza este umbral cuando cuentas rutas, modelos, servicios, configuración, tests y una nueva estructura de directorios.

Agent Teams es una función experimental que distribuye este tipo de trabajo entre múltiples instancias de Claude Code. Una sesión actúa como líder del equipo mientras que cada compañero tiene su propia ventana de contexto independiente. 

Para la API del blog, podrías dividirlo en tres compañeros: uno que gestione la extracción de rutas, otro la capa de base de datos y modelos, y otro la cobertura de tests. El líder asigna tareas, los compañeros las reclaman y completan, y las tareas bloqueadas (como "actualizar imports" dependiendo de "extraer módulos") se desbloquean automáticamente cuando finalizan las dependencias. 

La misma división funciona entre repositorios: si tu API depende de una librería compartida, un compañero puede refactorizar la librería mientras otro actualiza cómo la consume la API.

La mejor configuración para Plan Mode es requerir aprobación de plan para los compañeros. Indícale al líder: "Crea tres compañeros para la refactorización de la API del blog. Exige aprobar el plan antes de que hagan cambios." 

1. Cada compañero planifica en modo de solo lectura
2. El líder revisa y aprueba o rechaza con feedback
3. Solo se ejecutan los planes aprobados

Puedes orientar el criterio del líder dándole condiciones: "aprueba solo planes que incluyan cobertura de tests" o "rechaza planes que modifiquen directamente el esquema de base de datos". Activa Agent Teams añadiendo "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" al bloque env de tu settings.json.

Para una paralelización más sencilla sin la flag experimental, los worktrees de git te permiten ejecutar sesiones de Plan Mode por separado en distintas ramas, cada una con su propio plan.

Si una sesión larga sufre compactación de contexto, pide explícitamente a los compañeros que reabran y relean sus archivos de plan para evitar desvíos.

El tutorial de plugins de Claude Code cubre patrones adicionales para gestionar trabajos en varias fases.

Conclusión

El valor de Plan Mode se reduce a una idea: revisar antes de ejecutar. Cada ronda de anotaciones que añades y cada pregunta que Claude formula en lugar de adivinar elimina una decisión que, de otro modo, saldría mal. 

Empieza con tu próximo cambio que afecte a varios archivos: obliga a Claude a planificar primero y edita ese plan con Ctrl+G antes de conceder permisos de escritura. Para la configuración de CLAUDE.md, la gestión del contexto y las protecciones con hooks, el tutorial de buenas prácticas retoma donde este lo deja. 

Para una visión más amplia del desarrollo asistido por IA, te recomiendo nuestro itinerario de habilidades AI for Software Engineering, donde aprenderás los fundamentos y practicarás con herramientas similares como GitHub Copilot, Windsurf o Replit.