Plan Mode es la feature de Claude Code que más uso desde que existe. Te ahorra el ciclo "Claude edita → no era eso → revertir → volver a empezar" en tareas no triviales. En vez de actuar, planifica primero, te enseña el plan, y solo cuando dices "ok" pasa a ejecutar.
Si ya conoces los fundamentos —cómo funciona Claude Code por dentro, los permisos, los hooks—, Plan Mode es la pieza que cierra el círculo del agente cauto.
Qué es Plan Mode
Es un modo read-only de Claude Code. Puede:
Leer archivos, hacer grep, navegar tu repo.
Investigar dependencias, leer docs externas, ver git log.
Razonar sobre arquitectura.
No puede:
Editar archivos.
Ejecutar comandos bash que modifiquen el sistema.
Hacer git commits ni operaciones destructivas.
Ejecutar tests (porque es un side-effect en muchos repos).
Cuando termina, te entrega un plan estructurado con los cambios propuestos. Tú lo apruebas, editas o rechazas.
Cómo activarlo
Tres formas:
1. Shift+Tab dos veces
En la terminal interactiva: Shift+Tab cicla entre los modos de permiso. La primera pulsación pasa a auto-accept, la segunda a Plan Mode. Verás el indicador ⏸ plan mode on en la barra de estado.
2. El comando /plan
Añadido en enero de 2026, es la forma más directa:
> /planActiva el modo y deja claro al agente que estás en planning.
3. Desde la primera invocación
Si arrancas Claude Code con --plan-mode se queda en planificador hasta que tú salgas explícitamente. Bueno para sesiones de revisión de código sin tocar nada.
claude --plan-modeNota Windows: en versiones 2.1.3+ de Claude Code en Windows hay un bug abierto donde Shift+Tab solo cicla entre Edit y Auto-Accept, saltándose Plan Mode. Si te toca, usa
/plan. (issue #17344)
Cómo se sale
Apruebas el plan: pulsas
Enteren el prompt de aprobación. Claude Code sale solo y empieza a ejecutar.Editas el plan:
Ctrl+G(Linux/macOS) o el shortcut equivalente — abre el plan en tu$EDITORpara que lo modifiques antes de aprobar.Rechazas y reformulas:
Esco un nuevo prompt. Claude rehace el plan.Sales sin plan:
Shift+Tabpara volver a Edit Mode.
Cuándo usarlo (y cuándo no)
Sí
Refactors multi-archivo: cambiar nombre a una abstracción que toca 30 archivos. Plan Mode te muestra los 30 antes de tocarlos.
Codebases nuevos: aterrizas en un repo que no conoces. Plan Mode hace el "tour" y te explica antes de proponer el cambio.
Bugs sutiles: cuando el bug puede estar en N sitios. Que Claude analice todos antes de tocar uno.
Pair programming senior: como un colega senior que dice "antes de que escribas, déjame pensar".
Cuando vas a ejecutar el plan tú: a veces no quieres que Claude edite. Quieres el plan para hacerlo a mano. Plan Mode te lo entrega limpio.
No
Cambios obvios: añadir un log, arreglar un typo. Es ruido.
Cuando ya sabes qué quieres: si tu prompt es "edita X.ts línea 45 cambiando Y por Z", Plan Mode estorba.
Sesiones de exploración pura: si solo quieres preguntar sobre el código sin hacer nada, también te sirve, pero ahí el modo Default ya no edita por defecto si no se lo pides.
El plan que ves
Un plan típico de Claude Code:
Plan: refactor `getUserById` para usar el nuevo cliente HTTP
1. src/clients/legacy.ts:34 — eliminar uso de axios.
2. src/clients/http.ts (nuevo) — exportar el wrapper con retries.
3. src/services/user.ts:12 — sustituir llamada a `getUserById`.
4. tests/services/user.test.ts:88 — actualizar mocks.
5. package.json — quitar dependencia `axios`.
Cambios estimados: 5 archivos, ~80 líneas.
Riesgos: el cambio de mock en tests/services/user.test.ts puede romper
4 tests más (los que importan el helper de mocks).
¿Apruebo y ejecuto, o quieres editar?Lo importante: te dice archivo:línea cuando puede, y flagea riesgos. Si solo te suelta una lista vaga ("voy a refactorizar el servicio"), pídele más detalle: "dame el plan con archivo:línea y dependencias".
Combinarlo con output styles
Plan Mode + un output style "senior reviewer" da un agente que:
Solo lee.
Cuando habla, critica con bullets.
No te suelta código si no se lo pides.
Útil para revisión de PRs propios antes de commit:
> /output-style senior-reviewer
> /plan
> revisa el diff de los últimos 3 commits y dame los problemas que vesCombinarlo con hooks
Un hook OnPlanApprove puede disparar acciones cuando apruebas un plan: enviar el plan a Slack, registrarlo en un log, o dispararle un linter al final.
#!/usr/bin/env bash
# .claude/hooks/on-plan-approve.sh
PLAN=$(cat)
echo "$PLAN" >> ~/.claude/logs/plans.log
curl -X POST "$SLACK_WEBHOOK" \
-H 'Content-type: application/json' \
--data "{\"text\":\"Plan aprobado:\n\`\`\`$PLAN\`\`\`\"}"Más sobre esto en el artículo de hooks.
Trucos
1. Forzar Plan Mode con el system prompt
Si un equipo trabaja con commits autoreview obligatorio, un CLAUDE.md puede arrancar siempre en Plan Mode:
# Política del repo
Toda sesión que toque `src/api/` debe entrar en Plan Mode primero.
El reviewer humano aprueba el plan antes de ejecutar.Claude Code lee el CLAUDE.md del repo y respeta la directriz.
2. Plan Mode + skills
Una skill que sabe deployar tu app puede entregar un plan con los pasos exactos en vez de ejecutarlos. Útil para deploys donde el humano tiene que revisar antes de tirar el botón rojo.
3. Múltiples planes
Puedes pedirle a Claude dos planes alternativos ("dame el plan con migración gradual y el plan con migración big-bang") y comparar. Bueno cuando hay decisión arquitectónica de fondo.
4. Plan a un fichero
Si vas a discutirlo con tu equipo:
> /plan
> [tu prompt]
> guarda el plan en docs/plan-refactor-auth.md sin ejecutar nadaClaude lo escribe (sale temporalmente del modo o usa una excepción de write a docs) y luego sigues.
Diferencia con permission modes
Es fácil confundir Plan Mode con los demás modos de permisos. Resumen:
|
Modo |
Edits |
Bash |
Tests |
Cuándo |
|---|---|---|---|---|
|
Default |
Pide permiso |
Pide permiso |
Pide permiso |
Día a día |
|
Auto-Accept |
Auto |
Auto seguros |
Auto |
Cuando confías |
|
Plan Mode |
NO |
NO (read-only) |
NO |
Cuando quieres pensar antes |
|
YOLO |
Auto sin pedir |
Auto sin pedir |
Auto |
Solo en sandbox |
|
Read-Only |
NO |
NO |
NO |
Auditoría pura |
Plan Mode es read-only + obligación de entregar plan al final. Read-Only es solo lectura sin ningún plan estructurado.
Más detalle: los 6 modos de permisos de Claude Code.
Errores comunes
Aprobar planes sin leerlos: el valor de Plan Mode está en el momento de "ok, esto sí" o "ok, pero cambia el paso 3". Si lo apruebas a ciegas, te ahorras la revisión pero pierdes el sentido.
Pedir planes vagos: "quiero un plan para mejorar el código" → te devuelve algo inútil. Mejor: "plan para reducir el tiempo de respuesta de
/api/searchpor debajo de 200ms".Sacarlo del modo a mitad: salir con
Shift+Tabantes de aprobar tira el plan. Si quieres volver, te toca regenerarlo.Olvidar que tests no corren: a veces el plan dice "ahora lanzamos los tests"; en Plan Mode no se pueden lanzar. Tú los lanzas tras aprobar.
Plan Mode en otros editores
Cursor / Windsurf: tienen modos equivalentes ("Composer Plan", "Write/Plan Mode").
GitHub Copilot Chat: no tiene un Plan Mode formalizado, pero el reciente "agent mode" se le acerca.
Aider:
--asken CLI hace algo parecido (no edita, solo responde).
Si vienes de uno de esos, Plan Mode de Claude Code es más estricto: no toca nada hasta aprobar.
Conclusión
Plan Mode no es "una feature más". Es la herramienta que convierte a Claude Code de "agente que actúa rápido" en "agente que reflexiona antes". En tareas donde el coste de equivocarse es alto, úsalo siempre. En tareas chicas, ahorra tiempo no usándolo.
La regla práctica que llevo: si voy a leer el diff entero antes de mergear, mejor leo el plan antes de generar el diff. Igual de informativo, mucho menos código tirado.
Combinado con output styles, hooks y statusline, tienes a Claude Code haciendo el trabajo del modo en el que tú trabajarías. Que es lo que querías desde el principio.
La doc oficial está en code.claude.com/docs/en/common-workflows.
