El Problema Nunca Fue el Framework

Cada pocas semanas aparece una nueva forma de trabajar con agentes de código. Spec-Driven Development y una lista creciente de variantes, cada una con su propia sigla. Cada una promete resolver lo mismo: que el agente entienda qué construir, no se desvíe y no queme tokens de más.

Este post no nace de querer ponerle nombre a algo. Nace de cierto cansancio con una discusión que me parece innecesaria: cuál framework es el bueno para trabajar con agentes. Desde mi punto de vista, la diferencia no la hace el framework, sino las habilidades de las personas que lo usan: qué tan bien definen lo que quieren y qué tan bien guían al agente.

Si tuviera que ponerle una etiqueta, sería Engineering-Driven Development, y lo digo medio en broma. No es una metodología nueva ni pretende serlo; es una forma de decir que el criterio de ingeniería siempre fue lo importante.


💸 La queja de los tokens

La crítica más común que escucho es que los agentes gastan demasiados tokens, con o sin SDD. Y cuando se usa SDD, la queja cambia: es burocrático, genera demasiados archivos y obliga a rehacer trabajo.

Pero cuando el agente hace preguntas, explora de más o escribe tests que nadie pidió, no está desperdiciando tokens por gusto. Está haciendo el trabajo de descubrimiento que nadie hizo antes. La burocracia de SDD no la inventó SDD: es el costo de hacer explícita una definición que siempre faltaba.


🔍 Dónde se van los tokens

Vale la pena ver la mecánica. Un agente de código no “piensa” la solución y la escribe: trabaja en un ciclo de leer, buscar, ejecutar y editar, y todo lo que lee o produce ocupa su ventana de contexto.

Cuando la definición es vaga, cada decisión abierta se convierte en trabajo de exploración:

  1. Infiere lo que no le dijiste. ¿Qué columnas lleva el reporte? Abre el modelo, el controlador, las vistas y alguna exportación parecida para deducirlo. Eso son decenas de llamadas a herramientas para responder algo que tú sabías en diez segundos.
  2. Implementa sobre una suposición. Si la suposición era incorrecta, el código también lo es, aunque compile y pase sus propios tests.
  3. Corriges y vuelve a explorar. Tu corrección invalida parte de lo que ya leyó e hizo, así que relee archivos y rehace cambios.
  4. El contexto se llena. En sesiones largas el historial se compacta y se pierden detalles, así que el agente vuelve a leer lo que ya había leído. Es el mismo problema que me llevó a construir ctx.

Comparación entre un ticket vago, que entra en un ciclo de inferir, suponer, corregir y releer, y un plan definido que avanza en línea recta hasta un resultado verificable

En mi experiencia, el costo crece mucho más rápido que la ambigüedad. Cada decisión abierta multiplica los caminos posibles, y el agente paga por recorrer los que no eran. Una spec no ahorra tokens porque sea un documento; los ahorra porque cierra esos caminos antes de que el agente tenga que descubrirlos. Y no es la única fuente de desperdicio: la salida verbosa de las herramientas también llena el contexto, que es justo lo que ataca chop.


🕰️ Esto ya pasaba antes de los agentes

Cualquiera que haya trabajado en una empresa ha recibido un ticket como este: “Agregar exportación a Excel en el reporte de ventas”. Parece claro, pero no dice qué columnas, si respeta los filtros aplicados, ni si son 200 registros o 500,000. Tampoco dice quién puede exportar, ni si el archivo se descarga al momento o llega por correo. Cada una de esas preguntas cambia la implementación, y ninguna tiene respuesta en el ticket.

En consultoría pasa algo parecido, pero a mayor escala. Llega un cliente y pide “una app para que mis clientes agenden citas”. ¿Es un solo local o varias sucursales? ¿Se pueden cancelar citas, con cuánta anticipación? ¿Hay recordatorios, pagos por adelantado, web o móvil? Casi nunca se pregunta todo al inicio, y la mitad de las respuestas aparecen en la primera demo, cuando el cliente dice “no, así no era”.

En ambos casos el resultado era el mismo: retrabajo. A veces porque el requisito cambió, a veces porque la implementación no era lo que se esperaba. Pero nadie lo atribuía a la mala definición. Era “parte del proceso”.

La diferencia hoy es dónde se paga ese costo. Antes se pagaba en semanas de desarrollo y nadie lo medía. Ahora se paga en tokens, y como los tokens aparecen en una factura, parece un problema nuevo. Pasarle ese ticket a un agente no lo vuelve mejor; solo cambia quién adivina.


📝 El mismo ticket, bien definido

Definir bien no significa escribir un documento de diez páginas. Este es el ticket de la exportación, convertido en un plan que un agente puede ejecutar sin adivinar:

# Exportar reporte de ventas a Excel

## Por qué
Finanzas arma la conciliación mensual copiando la tabla a mano.

## Alcance
- Exporta exactamente lo que el usuario ve: mismos filtros y orden.
- Columnas: fecha, folio, cliente, subtotal, IVA, total.
- Solo roles `admin` y `finanzas`.

## Fuera de alcance
- Formatos distintos a .xlsx.
- Exportaciones programadas.

## Restricciones
- Hasta 5,000 filas: descarga inmediata.
- Más de 5,000: se genera en un job y llega por correo.
- Montos con 2 decimales; fechas en la zona horaria del usuario.

## Criterios de aceptación
- [ ] AC-1: el archivo respeta los filtros activos.
- [ ] AC-2: un rol sin permiso recibe 403.
- [ ] AC-3: 5,001 filas encolan un job y no bloquean la petición.
- [ ] AC-4: los totales del archivo coinciden con los de la pantalla.

No dice cómo implementarlo: no menciona librerías, clases ni estructura. Lo que hace es cerrar las decisiones que el agente habría tenido que adivinar. El cómo lo propone el agente, y ahí es donde entra la revisión.

Tampoco tuvo que pasar por una propuesta, un diseño y una lista de tareas por separado. Es una sola página, y para la mayoría de las features con eso alcanza.


⚖️ Definir no es llenar plantillas

Dicho eso, parte de la queja sí es válida. Hay frameworks que exigen propuesta, spec, diseño y lista de tareas aunque la definición ya esté clara, y terminan repitiendo lo mismo en cuatro archivos. Eso no es definición, es ceremonia.

Conviene separar las dos cosas:

Tampoco todo retrabajo es señal de mala planeación. A veces el requisito cambia porque al ver algo funcionando aprendes qué querías realmente. Un prototipo rápido también es una forma de definir.

La habilidad no es escribir la spec perfecta desde el inicio. Es saber qué tienes que definir antes y qué conviene descubrir construyendo. Una spec puede ser vaga o muy completa; lo importante es que quien guía sepa cuál de las dos necesita en cada caso.


🧠 “Engineering” no es un título

Digo Engineering y no Engineer a propósito. Cada vez es más común ver a personas sin perfil técnico, como analistas, diseñadores o product managers, construyendo cosas serias con agentes.

Eso confirma la idea: lo que hace la diferencia no es saber programar ni tener cierto puesto. Es pensar como ingeniero al definir:

El agente puede escribir el código. Lo que no puede hacer bien por sí solo es decidir qué vale la pena construir, cuándo algo está terminado y qué riesgo es aceptable. Eso es criterio de ingeniería, venga de quien venga.

He visto a personas sin experiencia programando construir sus propias herramientas a medida para resolver tareas de su día a día. No lo lograron por usar el framework correcto, sino porque sabían exactamente qué problema querían resolver y cómo saber si la herramienta funcionaba.


🛠️ Cómo trabajo yo

En mis side projects la estructura es mínima. He construido varias herramientas con apenas tres archivos:

Mi rutina casi siempre es la misma. Escribo el plan con lo que tengo claro, le pido al agente que lo lea y me proponga cómo implementarlo, lo discutimos, lo apruebo y lo dejo trabajar. Lo que no puedo vigilar yo lo cubren los tests y el CI/CD: esa es mi red de seguridad, no la ceremonia.

En el trabajo uso algo más robusto, porque hay más personas, más riesgo y requisitos que no defino yo. Pero la base es la misma: un plan, una aprobación antes de tocar código y revisiones al final. Lo que cambia es cuánto pesa cada paso, no el flujo.

Tampoco escribo planes exhaustivos. Trabajo de forma iterativa e incremental: avanzo en pasos pequeños, hago checkpoints con git, pruebo, uso lo que construí y ajusto. Si algo no sale como esperaba, regreso al último checkpoint y corrijo el rumbo guiando al agente, no cambiando de metodología.


🔁 El ciclo en la práctica

Ciclo de trabajo: PLAN.md, propuesta del agente, aprobación, paso pequeño, tests y CI; si pasa se hace checkpoint con git commit y se sigue al siguiente paso; si falla se regresa al último checkpoint

El CLAUDE.md no describe el proyecto en abstracto. Su parte más valiosa son unas cuantas reglas que corrigen los errores más comunes del agente:

## Reglas de trabajo
- Antes de editar código, propón un plan y espera aprobación.
- Si el alcance cambia a mitad del trabajo, detente y pregunta.
- No agregues dependencias sin preguntar.
- No marques algo como terminado sin ejecutar tests y linter;
  incluye la salida.
- Un cambio lógico por paso, para que pueda revisarlo.

Cada regla existe porque en algún momento el agente hizo justo lo contrario. Son pocas, son verificables y no requieren ningún framework.

Los checkpoints con git son lo que me permite iterar sin miedo. Cada paso que funciona queda guardado, y cada paso que sale mal se descarta sin negociar con el agente:

git switch -c feat/export-excel

# el agente termina un paso
git diff                 # reviso lo que cambió
git add -A && git commit -m "checkpoint: endpoint de exportación"

# el siguiente paso salió mal
git restore . && git clean -fd   # vuelvo al último checkpoint

Me ha pasado más de una vez: el agente resuelve el paso, pero sobre una suposición que no era, y cada corrección encima empeora el diff. En lugar de discutirlo, regreso al último checkpoint y vuelvo a pedir el paso con la decisión que faltaba escrita de forma explícita.

Revertir y volver a pedir con una instrucción más clara casi siempre sale más barato que pedirle al agente que arregle su propio error sobre el error. Al final, los checkpoints se pueden aplastar en commits limpios antes del PR.


✅ Tests y CI: el criterio que no se negocia

Un agente puede decir que terminó y estar equivocado con total seguridad. Por eso los criterios de aceptación no se quedan en el plan: se convierten en tests, y el ID viaja con ellos.

it('AC-2: rechaza la exportación a roles sin permiso', function () {
    $user = User::factory()->create(['role' => 'ventas']);

    $this->actingAs($user)
        ->get('/reportes/ventas/export')
        ->assertForbidden();
});

Con el ID en el nombre del test, saber qué criterios están cubiertos es un grep, no una conversación. Y si un criterio no tiene test, la feature no está terminada, diga lo que diga el agente.

El CI cierra el ciclo. El juicio del modelo es probabilístico; un pipeline que corre tests, linter y análisis estático es determinista. El agente puede convencerme a mí en un mal día, pero no puede convencer al CI. Esa es la diferencia entre confiar en el agente y verificarlo, y es la parte del flujo que no recorto ni en el proyecto más pequeño.


🏛️ Cuándo sí conviene un framework formal

No estoy en contra de SDD ni de herramientas como OpenSpec o Spec Kit. Hay casos donde su estructura paga lo que cuesta:

En esos casos, el framework no reemplaza el criterio; lo organiza. Pero si el criterio no está, ningún framework lo pone.


✳️ EDD no es un framework

EDD no necesita plantillas ni comandos.

Todo parte de una especificación y un plan, sean vagos o muy completos. El esfuerzo y el resultado no dependen solo de eso, sino de quien va guiando al agente: qué define, qué deja descubrir, qué rechaza y qué delega a los tests.

Si algo quiero dejar con este post, no es un flujo para copiar. Es una invitación a construir el tuyo:


Los frameworks van a seguir cambiando cada pocos meses. Saber definir un problema, verificar una solución y decir “esto no” a tiempo es lo que se queda.