Plan mode de Claude Code: ¿cuándo basta en un equipo?

El plan mode de Claude Code hace que Claude explore el código y proponga un plan antes de cambiar nada. Usted aprueba el plan y solo entonces empiezan los cambios. Para un desarrollador en una sesión, eso suele bastar. En un equipo no, porque el plan vive en una sesión en un portátil, y nadie más puede revisarlo ni comprobarlo después.

Por eso usamos el plan mode para el borrador y guardamos el plan donde trabaja el equipo: en el issue de GitHub, con criterios de aceptación a los que un revisor puede responder sí o no. Antes de que nuestro agente construya nada, una comprobación de solo lectura contrasta la premisa del issue con el código.

¿Cómo funciona el plan mode de Claude Code?

El plan mode es uno de los modos de permisos. Según la documentación de los modos de permisos, Claude lee archivos, ejecuta comandos de shell para explorar y escribe un plan, pero no edita su código fuente hasta que usted lo aprueba. El flujo:

Al aprobar, la sesión sale del plan mode y Claude empieza a editar. El archivo del plan se guarda en ~/.claude/plans/, salvo que configure plansDirectory.

La propia guía de costes de Anthropic recomienda el plan mode para tareas complejas, porque una dirección equivocada detectada antes de los cambios sale más barata que una detectada después.

¿Dónde se queda corto el plan mode en un equipo?

El plan mode responde a "¿entiende Claude lo que quiero ahora mismo?". Un equipo necesita respuesta a tres preguntas más:

• ¿Quién más ha visto el plan? Vive en una sesión. Un compañero que retoma el trabajo mañana, o quien revisa el pull request, nunca ve lo que se acordó.
• ¿Era cierta la premisa? El plan se basa en lo que escribió el desarrollador. Si el issue dice "la exportación pierde las filas vacías" y el código ya las gestiona, el plan arregla un bug que no existe.
• ¿Cómo sabremos que está terminado? Un plan enumera pasos. Un revisor necesita criterios, a ser posible cada uno demostrado con un test.

No son rivales. El plan mode es una buena forma de escribir el issue.

¿Cómo planificamos en su lugar?

Cada tarea es un issue de GitHub con un tipo y un resultado obligatorio:

El issue dice qué entregar. Quien lo recoge, una persona o nuestro agente de IA, completa un resultado o un criterio que falte como supuesto explícito en lugar de adivinar en silencio.

¿Cómo es la comprobación READY?

Antes de que nuestro bucle de agente construya nada, ejecuta un paso READY. No es el plan mode. Es una llamada aparte, de solo lectura, con una respuesta tipada:

claude -p "$(cat ready.md; cat issue.md)" \
  --permission-mode default --permission-prompts none \
  --tools "Read,Grep,Glob,WebFetch" \
  --json-schema "$(cat ready.schema.json)" --output-format json --max-turns 40

El esquema obliga a que la respuesta tenga campos: ready, done_when (criterios a los que un revisor puede decir sí o no), verify (cómo se demuestra cada uno), understood, premise y verifiable, que es test o human. Si no vuelve un objeto válido, cuenta como fallo, nunca como valor por defecto.

La sesión de construcción recibe después esos criterios como encargo. Se ejecuta con --disallowedTools AskUserQuestion ExitPlanMode: a esas alturas el plan está cerrado, así que el agente no puede pararse a preguntar ni volver a planificar. El bucle completo, de READY al pull request, está en Harness engineering en la práctica.

¿Qué detecta una comprobación de la premisa que el plan mode no detecta?

Un plan hecho de buena fe sobre una premisa falsa. El prompt de READY indica al modelo que compruebe en el repositorio cada afirmación del issue sobre el comportamiento actual y que cite file:line. Si una afirmación no se sostiene, la respuesta empieza por REFUTED: y enumera lo que ya no es cierto y lo que sigue siéndolo.

Lo que pasa después depende de cuánto queda:

• No queda nada por hacer. El issue vuelve a una persona con las pruebas y una propuesta para cerrarlo.
• Una parte queda refutada. El bucle propone en el issue el alcance corregido y espera a que una persona responda OK antes de construir.
• Solo una persona puede verificarlo. Cuando verifiable es human, el agente dice qué tiene que revisar alguien antes de empezar.

Ese es el hueco que cierra una comprobación de la premisa. Planificar es barato. Lo caro es planificar lo que no toca, y hasta la revisión parece exactamente progreso.

¿Cuándo basta con el plan mode?

Muchas veces. Use esto para decidir si el plan tiene que salir de la sesión:

El plan mode encaja en cambios cortos y locales en los que usted es el único lector. Todo lo demás merece un plan que el equipo pueda leer. Cómo una especificación escrita se convierte en el contrato entre personas y agentes lo explicamos en Spec-driven development con agentes de IA.

¿Quiere planes que sobrevivan a la sesión?

Montamos contratos de issues, comprobaciones READY y el bucle de agente directamente en los repositorios de un equipo, como parte de AI-native SDLC para equipos de desarrollo. La IA escribe la mayor parte de nuestro código. Un sénior revisa cada cambio y responde de la producción. Desde 2023 hemos entregado más de 15 proyectos en producción.

Le respondemos en un plazo de dos días hábiles con algunas preguntas sobre su trabajo. Después acordamos qué hacemos primero.

Si prefiere hablar primero, reserve una llamada inicial de 15 minutos.

¿Quién de su equipo encontraría hoy el plan de ayer?

Preguntas frecuentes

¿Qué es el plan mode en Claude Code?

Un modo de permisos en el que Claude lee archivos y ejecuta comandos de exploración, y después propone un plan sin editar su código fuente. Los cambios siguen bloqueados hasta que usted aprueba el plan.

¿Cómo se activa el plan mode en Claude Code?

Pulse Shift+Tab para llegar a él, empiece un único prompt con /plan o inicie la sesión con claude --permission-mode plan.

¿Puedo editar el plan antes de que Claude empiece?

Sí. Pulse Ctrl+G para abrir el plan propuesto en su editor, o elija seguir planificando y dígale a Claude qué cambiar.

¿Dónde guarda Claude Code los planes?

Por defecto en ~/.claude/plans/, o en el directorio que indique la opción plansDirectory. En ambos casos está en una sola máquina, y por eso un plan de equipo debe estar también en el issue.

¿El plan mode es lo mismo que el spec-driven development?

No. El plan mode es una función de una sesión. El spec-driven development mantiene el plan como un artefacto escrito que revisa todo el equipo y que las comprobaciones pueden verificar. El plan mode puede producir el borrador.