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:
- 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.
- 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.
- Corriges y vuelve a explorar. Tu corrección invalida parte de lo que ya leyó e hizo, así que relee archivos y rehace cambios.
- 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.
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:
- El costo de definir es inevitable. Si no lo pagas tú al inicio, lo paga el agente adivinando o lo pagas después rehaciendo.
- El costo de la ceremonia sí es opcional. Llenar artefactos que no aportan información nueva no hace mejor al resultado.
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:
- Qué problema se resuelve y por qué.
- Para quién, y qué pasa en los casos que no son el camino feliz.
- Cuáles son los criterios de aceptación.
- Cómo se verifica que funciona.
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:
CLAUDE.md: el contexto del proyecto, mis convenciones y las reglas que quiero que el agente respete.PLAN.md: lo que voy a construir ahora, con tanto o tan poco detalle como la feature necesite.ROADMAP.md, solo cuando el proyecto lo amerita: hacia dónde va, para que lo que decida hoy no me estorbe mañana.
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
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:
- Equipos grandes, donde varias personas necesitan revisar y aprobar el mismo plan.
- Specs como contrato, por ejemplo APIs o integraciones que otros consumen.
- Sistemas que necesitan una spec viva, que describa qué hace el sistema sin tener que leer el código.
- Contextos auditables, donde importa poder demostrar qué se decidió y por qué.
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:
- Practica definir. Antes de abrir el agente, escribe en una página qué quieres, por qué y cómo vas a saber que funciona. Si no puedes, el agente tampoco va a poder.
- Experimenta. Prueba SDD, prueba un plan de una página, prueba sin plan en algo pequeño. Quédate con lo que te funcione, no con lo que esté de moda.
- Sé crítico. Con lo que produce el agente y con lo que te venden alrededor. Si una herramienta promete resolverte el criterio, desconfía.
- Haz tus propias reglas. Las mejores líneas de un
CLAUDE.mdnacen de tus propios errores. Ese archivo vale más que cualquier plantilla ajena.
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.