Lo que nadie te cuenta de OpenSpec hasta que lo usas en serio

Le pides a tu agente de IA que construya una feature. Le pasas un prompt decente, hasta detallado. Y a los diez minutos está tocando ficheros que no le habías mencionado, ha “mejorado” una función que ya funcionaba y ha dado por terminada una tarea que no ha hecho. Otra vez a revisar a mano lo que prometía ahorrarte trabajo.

El Spec-Driven Development apareció justo para eso: poner orden. Y OpenSpec es de los frameworks más sencillos para hacerlo, open source y compatible con un montón de agentes. Los tutoriales te enseñan a instalarlo y a lanzar los comandos. Pero hay otra capa de cosas que solo entiendes cuando lo usas de verdad, más allá del “hola mundo” de la app del tiempo.

Esas son las que te traigo aquí. No son comandos: son las verdades que cambian cómo trabajas con un agente, y que casi nadie pone por escrito porque no se ven en una demo de cinco minutos.

No hay magia detrás: hay un CLI que no se fía de la IA ¶

La primera vez que ves a un agente recorrer un flujo de specs sin perderse, piensas que hay algo sofisticado debajo. Una base de datos, un orquestador, un cerebro coordinándolo todo. No lo hay.

Lo que hay es un CLI determinista —un programa de toda la vida, predecible y aburrido— que sabe en qué fase está cada cambio y se lo escribe a la IA, paso a paso. El modelo no tiene que recordar dónde estaba ni adivinar qué toca ahora: se lo dan masticado. La astucia no está en que el modelo sea más listo, está en que le quitan la oportunidad de perderse.

Esto cambia cómo miras la herramienta. No estás delegando el control en la IA; estás poniendo un adulto determinista entre tú y el modelo para que el modelo haga solo la parte en la que es bueno (escribir código) y no la parte en la que es malo (acordarse de las cosas sin inventárselas). Cuando lo entiendes, dejas de pelearte con prompts gigantes que intentan meterle todo el contexto de golpe.

Lo que te llevas: desconfía de cualquier sistema de IA que parezca magia. Los que funcionan de verdad suelen tener un trozo tonto y determinista llevando las riendas. Si algún día montas el tuyo, empieza por ahí: ¿quién lleva el estado, el código o el chat?

El estado vive en los ficheros, no en la conversación ¶

Aquí está la consecuencia práctica más liberadora, y la que más tarda en caer.

Cuando trabajas a chat pelado, todo tu progreso vive en la conversación. Cierras la ventana, se acaba el contexto, se reinicia el equipo… y empiezas de cero, reexplicándole al agente qué estabas haciendo. Con un sistema de specs bien montado, el estado de la tarea no está en el chat: está escrito en ficheros del proyecto. La propuesta, el diseño, la lista de tareas con sus casillas marcadas.

¿Qué significa eso en tu día a día? Que puedes cerrar el agente a mitad de una implementación, irte a comer, volver, abrir una conversación nueva y decirle “sigue con este cambio”. Y sigue. No porque se acuerde, sino porque lo lee. La conversación es desechable; el trabajo, no.

Tiene un efecto secundario que no esperabas: dejas de tener miedo a las sesiones largas. Antes alargabas la conversación hasta el infinito por pánico a perder el hilo, y el agente cada vez peor, más saturado de ruido. Ahora cortas cuando quieres, arrancas limpio y el agente recupera el contexto desde los ficheros sin arrastrar la basura acumulada de las dos horas anteriores.

Lo que te llevas: si tu progreso solo existe en la ventana del chat, estás a un cierre de pestaña de perderlo. Saca el estado del chat y ponlo en disco, lo gestione OpenSpec o lo que sea. Es la diferencia entre una herramienta y un truco de feria.

No necesitas diecisiete agentes (ni OpenSpec para todo) ¶

Vivimos un momento de inflación de setups. Que si un enjambre de subagentes, que si cincuenta skills, que si una orquesta de modelos deliberando entre ellos. Y luego abres OpenSpec, que es de los frameworks más sencillos que hay, y resulta que hace el trabajo igual de bien para la mayoría de las cosas.

La realidad incómoda: para un buen resultado no hacen falta diecisiete agentes. El único cuello de botella de verdad es una base de código gigantesca, donde el modelo se ahoga de contexto. Para todo lo demás, un flujo ordenado y simple le da mil vueltas a un arsenal que no entiendes y que no sabes depurar cuando se tuerce.

Y el reverso, que importa igual: OpenSpec tampoco es para todo. Montar propuesta, diseño y artefactos para arreglar un bug de dos líneas es sacar el mazo para una chincheta. El método brilla en tareas grandes, en cambios que tocan varias partes del sistema, en cosas donde “qué quiero exactamente” no está nada claro todavía. Para un retoque rápido, abre el editor y a otra cosa.

Lo que te llevas: la sofisticación de tu setup no es una medalla. Empieza por lo más simple que resuelva tu problema y súbele complejidad solo cuando el dolor lo pida de verdad. Y antes de invocar al framework, pregúntate si la tarea lo merece.

Hasta aquí el cambio de chip: por qué estos sistemas hacen que un agente te haga caso, dónde vive de verdad el trabajo y cuándo conviene usarlos. Es la parte que se sostiene sola y que puedes aplicar hoy con casi cualquier framework.

Pero entender por qué funciona no es lo mismo que sacarle el jugo. Lo que separa “seguí el tutorial” de “lo uso en producción” es la personalización: hacer que el agente pare cuando tú decidas, montarte tu propio esquema para tu tipo de proyecto y dejar de fundir tokens en cada fase. Eso es lo que se desarrolla, con el ejemplo trabajado de punta a punta, en la guía completa.