Plan mode vs Agent mode: cuándo planificar antes de tocar código

El agente que edita en caliente es rápido hasta que te deja un diff de 40 archivos que no pediste. Plan mode invierte el orden: investiga, hace preguntas, escribe un plan revisable y solo entonces toca disco. Agent mode (o el modo normal de ejecución) asume que ya sabes qué quieres y delega la implementación. Las docs de Cursor Plan Mode y Claude Code coinciden en el patrón; cambian los atajos y dónde se guarda el plan.

Esta guía no es orquestación multi-agente (varios procesos en producción). Es el hábito de una sesión de coding agent: planificar o ejecutar.

Qué hace cada modo

	Plan mode	Agent mode
Edita archivos	No hasta que apruebes el plan	Sí, según permisos
Explora el repo	Sí (lectura, preguntas)	Sí
Salida principal	Plan en chat o markdown	Diff + commits
Mejor para	Alcance incierto, muchos archivos, decisión de arquitectura	Bug fix acotado, cambio repetido, typo
Atajo Cursor	Shift+Tab al input	Modo Agent por defecto
Claude Code	claude --permission-mode plan o Shift+Tab (⏸ plan mode on)	Modo normal con permisos ask/allow

Cursor documenta cinco pasos: preguntas → investigación → plan → revisión/edición → Build. Los planes viven en el home del usuario hasta que eliges “Save to workspace” para compartirlos con el equipo.

Claude Code describe lo mismo como “plan before editing”: lee archivos, propone cambios, no escribe hasta aprobación. Delega exploración pesada al subagente Plan para no inundar tu ventana principal.

Cuándo plan mode (y cuándo no)

Usa plan mode si:

• Hay varias formas válidas de resolver (migración de auth, nuevo módulo, refactor transversal).
• Tocas muchos archivos o sistemas (API + front + tests + CI).
• No sabes el alcance hasta leer código (legacy, monorepo ajeno).
• Quieres revisar el enfoque antes de pagar tokens de implementación.

Salta a Agent mode si:

• El cambio cabe en un archivo y ya sabes el patrón (fix typo, añade validación Zod).
• Lo has hecho diez veces en ese repo (mismo comando, misma carpeta).
• Tienes reproducción clara del bug y el fix es obvio tras el stack trace.

La regla de Cursor es honesta: para tareas rápidas o repetidas, Agent directo está bien. Plan mode es seguro de omisión en micro-cambios y seguro de no omisión en features medianas.

El error típico: arreglar en marcha en vez de volver al plan

Las docs de Cursor lo dicen explícito: si el build no coincide con lo que querías, no enchufes diez prompts correctivos. Revierte, afina el plan (más específico, más criterios de aceptación) y vuelve a ejecutar. En la práctica es más rápido que pelear con un diff ya sucio.

Patrón:

1. Agent implementó mal → git checkout -- . o revert del commit.
2. Abres el plan guardado (workspace o chat).
3. Añades bullets verificables: “no tocar src/lib/db.ts”, “tests en posts.test.ts”.
4. Build de nuevo.

Eso es distinto de pausar un agente en producción para aprobación humana; aquí el humano es el revisor del plan antes del código.

Protocolo de 30 minutos (feature mediana)

1. Min 0–5: Describe el outcome en una frase + restricciones (“sin nueva dependencia”, “mantener API pública”).
2. Min 5–15: Plan mode ON. Responde preguntas del agente. Pide que liste archivos a tocar.
3. Min 15–20: Edita el plan (markdown en workspace si el equipo comparte specs).
4. Min 20–30: Build / Agent mode con el plan adjunto. Corre pnpm test (o lo que diga tu AGENTS.md / CLAUDE.md).

Si a los 15 minutos el plan sigue vago (“mejorar la arquitectura”), el problema es el brief, no el modelo.

Plan mode no sustituye diseño de sistema

Plan mode ordena una sesión de coding. No decide si necesitas dos agentes en producción, colas o RAG. Para eso está orquestación multi-agente. Tampoco reemplaza sandboxing: en plan mode Claude sigue leyendo el repo; en Agent mode los permisos deny/ask/allow siguen aplicando.

En Cursor, Plan mode puede dispararse solo si escribes palabras de tarea compleja; no confundas la sugerencia automática con obligación. Tú eliges el modo.

Checklist

• ¿El cambio toca más de 3 archivos o un contrato público? → Plan mode primero.
• ¿Hay más de una solución razonable? → Plan mode.
• ¿Tienes criterios de aceptación en bullets verificables en el plan?
• ¿Guardaste el plan en el workspace si el equipo lo necesita?
• Si el resultado falló, ¿revertiste y refinaste el plan en vez de parchear en chat?
• ¿AGENTS.md / CLAUDE.md mencionan comandos de test que el agente debe correr al terminar?
• ¿Pasaste a Agent solo después de aprobar el plan?

FAQ

¿Plan mode gasta menos tokens?
Suele gastar menos en implementación errónea. Pagas investigación + plan; ahorras reverts y diffs gigantes.

¿Claude Code y Cursor hacen lo mismo?
Mismo patrón (leer → plan → aprobar → editar). Difieren en UI, subagente Plan de Claude y atajos de Cursor.

¿Y Ask mode / chat sin agente?
Ask responde sin editar. Plan es el puente: edición diferida con contrato escrito. Para elegir superficie de coding agent, ver mejores agentes de código en 2026.

¿Puedo automatizar plan mode en CI?
En CI normalmente quieres scripts deterministas, no un plan conversacional. Plan mode es para desarrollo interactivo.

---

Siguiente paso: la próxima feature que te dé miedo abrir en Agent directo, pruébala 15 minutos en plan mode y guarda el markdown en el repo.