Tu IA necesita un plan: explora, planifica y ejecuta mejor

¿Te ha pasado alguna vez que le pides algo a una IA, te genera 200 líneas de código y, aunque “funciona”, no tiene nada que ver con cómo está montado tu proyecto? A mí me pasaba constantemente. El problema no es la IA, el problema es que le pedimos que corra antes de que sepa a dónde vamos.

Cuando usamos herramientas de IA para programar, solemos caer en la trampa del “prompt directo”. Lanzamos una instrucción vaga (“Añade un sistema de favoritos”) y esperamos que el modelo adivine nuestra arquitectura, nuestras convenciones y los casos borde que ni nosotros mismos hemos pensado.

Para solucionar esto, he cambiado radicalmente mi forma de interactuar con los asistentes. Uso un enfoque basado en Spec-Driven Development (SDD) (apoyado en herramientas como OpenSpec) que divide el trabajo en tres fases: Exploración, Planificación y Ejecución.

Y la clave de todo esto no está en las herramientas, sino en cómo cambia la conversación con la máquina.

Fase 1: Exploración (El sparring técnico)

Solemos saltarnos esta fase porque queremos ver código funcionando rápido. Es opcional, sí, pero es el mayor multiplicador de calidad cuando trabajas con IA.

En la fase de exploración, le prohíbes expresamente a la IA que escriba código de aplicación. Su único trabajo es investigar tu proyecto, hacer preguntas y actuar como un desarrollador sénior que acaba de llegar al equipo.

Por qué esta fase lo cambia todo

Cuando le dices a la IA: “Quiero cambiar cómo gestionamos los estados de los pedidos. Revisa el proyecto y dime qué implicaciones tiene”, empiezan a aparecer detalles que normalmente descubrirías tarde:

1. Descubre puntos ciegos: Tú pensabas que solo era añadir un campo status a la tabla de pedidos, pero la IA ha leído tu código y te avisa: “Oye, he visto que el webhook de pagos marca los pedidos como completados en segundo plano. Si cambiamos este estado sin tocar esa cola, algunos pedidos se quedarán en un limbo entre paid y completed”. Te acaba de ahorrar horas de debug.
2. Reutiliza tu código: En lugar de inventarse funciones, la IA mapea lo que ya tienes. “He visto que ya existe un OrderStateMachine en billing/. ¿Extendemos ese flujo o añadimos una transición nueva?”.
3. Cuestiona los requisitos: Te obliga a pensar en flujos de error. “¿Qué pasa si Stripe confirma el pago, pero nuestra base de datos falla al actualizar el pedido? ¿Reintentamos, compensamos o dejamos el evento en una dead-letter queue?”.

La exploración transforma a la IA de una “máquina de escupir código” a un verdadero compañero de diseño.

Fase 2: Planificación (Firmando el contrato)

Una vez que tú y la IA habéis explorado el terreno y descubierto los problemas ocultos, toca formalizar el acuerdo.

En lugar de saltar a programar, le pides a la IA que redacte un plan. Este plan (normalmente un archivo Markdown de diseño y una lista de tareas) se convierte en el contrato.

## Tareas para el Estado de Pedidos
- [ ] 1. Revisar el flujo actual de estados en `OrderStateMachine`.
- [ ] 2. Añadir la transición `paid -> completed` desde el webhook de pagos.
- [ ] 3. Registrar eventos fallidos en una dead-letter queue para reintentos controlados.

El superpoder de este paso: Cuando la IA tiene este documento como contexto base, las alucinaciones desaparecen. Ya no tiene que adivinar cómo encajar el webhook, la máquina de estados y los reintentos; el plan que construisteis juntos se lo dicta.

Fase 3: Ejecución (El trabajo sucio)

Aquí es donde por fin empezamos a tocar archivos de producción. Pero fíjate en la diferencia: la IA ya no está improvisando. Está ejecutando cambios concretos basados en el plan.

Tú le dices: “Ejecuta la tarea 1”. La IA va, revisa la máquina de estados, valida que no rompe el flujo del webhook de pagos, y marca la tarea como completada. Luego pasas a la dos.

El contraste es brutal

Poniendo esto en práctica con OpenSpec

La teoría suena bien, pero ¿cómo se ve esto en tu editor? Herramientas como OpenSpec materializan este flujo de trabajo directamente en tu terminal y en tu chat con la IA.

También publiqué un ejemplo práctico centrado en flujos de producto y arquitectura en mi artículo sobre Spec-Driven Development para Strava CLI y JSON Viewer.

Imagina que queremos añadir un sistema de roles y permisos a nuestra app. En lugar de pedirle el código de golpe, el flujo se vería así:

1. Inicias la Exploración: Escribes /opsx:explore implementar sistema de roles en el chat. La IA revisa tu código, nota que ya usas un middleware de autenticación antiguo y te advierte: “Si añadimos roles ahora, chocaremos con este middleware legacy. ¿Refactorizamos primero o lo adaptamos?”. Te acaba de salvar de un callejón sin salida.
2. Creas el Plan: Tras decidir adaptarlo temporalmente, ejecutas /opsx:propose add-role-system. OpenSpec automáticamente genera una carpeta openspec/changes/add-role-system/ en tu proyecto. Dentro, crea un documento de diseño (design.md) y una lista de tareas (tasks.md) basada en vuestra conversación. Tú puedes revisar esos archivos y añadir notas manualmente si quieres.
3. Ejecutas las tareas: Finalmente, lanzas el comando /opsx:apply. La IA lee el archivo tasks.md, implementa el paso 1 (crear la migración de base de datos), marca la casilla con una [x], y te pide confirmación. Luego pasa al paso 2.

Todo bajo control, verificable paso a paso y sin generar miles de líneas de código a ciegas.

Conclusión

La Inteligencia Artificial es un motor increíblemente potente, pero si no le das un volante (Exploración) y un mapa (Planificación), es muy fácil acabar estrellado contra la deuda técnica.

El verdadero valor de herramientas metodológicas como OpenSpec no son los comandos de terminal que ofrecen, sino la disciplina mental que te imponen. Te obligan a frenar un segundo, a dejar que la IA investigue tu código de verdad y a pactar una solución antes de ensuciarte las manos.

Si quieres dejar de pelearte con las alucinaciones y empezar a construir software sólido con IA, deja de pedirle que programe. Empieza a pedirle que piense contigo.

Y si quieres ver otra pieza complementaria, aquí explico cómo convertir respuestas complejas en interfaces útiles con JSON Viewer.

FAQ: Preguntas frecuentes

1. ¿No pierdo mucho tiempo explorando y planeando? La ilusión de velocidad del “prompt directo” desaparece cuando pasas tres horas intentando integrar el código que te generó la IA. Invertir 10 minutos en explorar el problema con el agente te ahorra horas de refactorización posterior.

2. ¿Funciona esto para tareas pequeñas? Si es cambiar un texto o arreglar un typo, no. Pero en cuanto el cambio toca más de dos archivos o afecta a la arquitectura, la fase de exploración se vuelve obligatoria.

3. ¿Cómo le digo a la IA que “explore”? Simplemente sé explícito: “Vamos a diseñar X. Aún no escribas código. Primero lee los archivos relacionados con Y, hazme preguntas sobre casos borde y propón un enfoque técnico.”