Caso de estudio de Spec-Driven Development: 13 apps en 70 días, solo, con IA

La mayoría de los artículos sobre desarrollo asistido por IA describen una herramienta de un proveedor, un experimento de taller o un prototipo hecho por una persona en una tarde. Este no es nada de eso. Es alguien que lo practica describiendo un build real de producción: un sistema, un dev, setenta días, dinero real, compliance real. Los números son públicos. Los límites son honestos.

Si lo que buscas es el método en sí, empieza por qué es Spec-Driven Development. Esto es la prueba de concepto detrás de él: un sistema real, setenta días, el método aplicado a una escala donde los modos de falla son caros y difíciles de revertir.

Una fintech cripto, construida solo con SDD

13

apps en producciónmonorepo en Turborepo

3

APIs, 3 bases de datosauth, pagos, exchange

8

paquetes compartidosauth, ui, i18n, logger...

70

díassolo, dinero real

~1.650

tests automatizadosVitest y Playwright

138K

líneas de TypeScript39 migraciones

La apuesta

El encargo no era un prototipo. Construir una plataforma completa de pagos cripto: un gateway de pagos PIX para el mercado brasileño, un motor de exchange OTC y liquidación on-chain en la Liquid Network de Bitcoin. De punta a punta. Listo para producción. Dinero real, compliance real, plazo real. Solo. Setenta días.

No es un proyecto que se improvise desde una ventana de chat. Tres bases PostgreSQL aisladas. Tres APIs en Fastify. Nueve frontends en Next.js. Una librería de componentes compartida. Una capa de autenticación compartida. Kubernetes detrás de todo, en un monorepo en Turborepo. Súmale la superficie regulatoria: PIX pasa por el banco central de Brasil, con sus propios hooks de compliance y un endpoint de conexión bancaria directa sobre TLS mutuo. Súmale un motor de exchange OTC que necesita precios deterministas, spreads asimétricos y una cadena de fallback entre cinco fuentes de mercado. Súmale un motor de liquidación que tiene que manejar transacciones atascadas, reembolsos por desviación y un tope de liquidación automática que desborda hacia aprobación manual cuando los saldos superan un umbral. Cada dominio tiene sus propios modos de falla. Y se acumulan. Una suposición equivocada en la capa de precios aparece después, en la capa de liquidación, con dinero real en tránsito.

Las principales objeciones al spec-driven development en 2026 vinieron de dos tipos de experimento: prototipos de taller, donde los equipos prueban el método en proyectos de juguete durante una tarde, y builds pequeños de una sola persona, donde un ingeniero entrega algo en unas horas sin SDD y concluye que era overhead innecesario. Ninguna de las dos es la prueba relevante. Un proyecto de 10 horas de una sola persona, sin presión de compliance, sin saldos reales y sin plazo externo, no necesita un corpus de 28 archivos de spec. Un motor de exchange OTC con un modelo de precios en dos fases, cinco fuentes de mercado y una conexión directa con el BACEN sí lo necesita, y mucho. El método es proporcional a lo que estás protegiendo.

El enfoque ingenuo del desarrollo con IA a esta escala es abrir una ventana de chat y ponerse a describir features. Lo he hecho. Es el albañil rápido sin planos: paredes en minutos, escalera que termina contra un muro. A la escala de una fintech multi-tenant con hooks de compliance, el prompt-y-rezar no te frena de a poco. Construye algo que parece completo y pasa una revisión superficial, y después falla cuando llega un edge case real. El código compila. Los tests pasan. La suposición que nadie escribió vuelve en producción con el saldo de un cliente colgando de ella.

Así que no escribí prompts. Especifiqué.

Quien hace el modelo dice que planifiques primero

No es una manía personal ni una postura a contracorriente. La propia guía de Anthropic para Claude Code describe un ciclo de cuatro pasos: explorar, planificar, implementar, hacer commit. Hay un plan mode dedicado en el producto cuyo único trabajo es impedir que el agente escriba código mientras piensa. Su razonamiento es directo: “dejar que Claude salte directo a programar puede producir código que resuelve el problema equivocado”.

Es la empresa que entrenó el modelo diciéndote lo que la mayoría de los devs se salta. Publican un template de prompt para entrevistarte a ti mismo hasta llegar a una especificación antes de que exista código, y después abrir una sesión nueva para ejecutarla. Tres oraciones, de parte de quienes construyeron la herramienta.

Un ensayo aleatorizado de 2025 de METR encontró que devs experimentados trabajando con IA en codebases reales fueron un 19% más lentos que sin ella, pese a que esperaban ser un 24% más rápidos. Se equivocaron con total seguridad en las dos direcciones: sobre el resultado y sobre cómo lo percibieron después. El modo de falla no es el modelo. Es capacidad sin dirección. Cuanto más capaz es el modelo, más lejos lo lleva una instrucción vaga en la dirección equivocada. La capacidad amplifica la dirección. No la aporta.

En 13 aplicaciones de producción, apliqué a escala lo que describe Anthropic. El mecanismo fue un corpus permanente de specs: 28 specs en markdown en 12 dominios, más 8 slash commands propios, viviendo en el repositorio y cargándose como contexto del agente al inicio de cada sesión. Nada de prompts improvisados. La memoria del proyecto, en disco, versionada en git.

Primero la spec, nunca el prompt

Cada capability empezó como una especificación escrita: requisitos, diseño, tareas. No un mensaje de chat. Los agentes ejecutaban contra la spec. Yo revisaba contra los criterios de aceptación y hacía el deploy. Cuando el output salía mal, corregía la spec, no el prompt. Cada línea de código generado se podía rastrear hasta una decisión que yo había tomado y podía señalar.

El corpus permanente de specs: la memoria del agente, en disco

• .claude/
  • auth/dominio// roles, scopes, permisos por ruta
  • exchange/dominio// pricing.md: el contrato de VWAP y spread
  • database/dominio// entidades, migraciones, diseño del schema
  • testing/dominio// convenciones, db, ui
  • ui/// design tokens, componentes
  • codebase/// convenciones, server actions
  • commands/8 comandos// /new-route, /migrate, /verify...
  • skills/1 skill// convenciones de la plataforma

Veintiocho specs en markdown en doce dominios, más ocho slash commands propios que convirtieron los pasos repetibles de generación en contratos que el agente tenía que seguir. Los slash commands son la parte que casi todos pasan por alto. No son atajos de teclado. Cada uno codifica un workflow completo: generación de rutas, migración de base de datos, scaffolding de tests, verificación del deploy. El agente los ejecuta igual en cada sesión. Sin drift. Sin reinventar nada. Los slash commands son la unidad repetible de trabajo. Las specs son la memoria persistente detrás de ellos.

El dominio de auth, por ejemplo, no es una nota suelta que dice “usa JWT”. Es una spec que cubre cinco roles, diecinueve scopes, dieciocho permisos granulares, la regla de que cada ruta declara el scope que requiere al registrarse y el flujo máquina a máquina con alcance a nivel de fila para client credentials. Cuando el agente genera una ruta nueva, lee esa spec primero. La declaración del scope no es algo que el dev tenga que acordarse de agregar. Es algo que la spec exige, y el agente lo verifica.

Un dev solo no tiene en la cabeza una fintech de 13 apps. La spec la tiene. El dev tiene la spec.

El ciclo de entrega

El ciclo de entrega, repetido por capability

Entrada

Una capability por entregar (p. ej., el motor de liquidación)

↓

1. 01Specify

   Requisitos, diseño y tareas escritos antes de una sola línea de código. La spec es el contrato, no decoración. Se requiere aprobación humana antes de avanzar.

   ↓
2. 02Generate

   El agente implementa contra la spec y escribe los tests junto con el código. Sin prompts. La spec es la instrucción.

   ↓
3. 03Verify

   Revisión contra los criterios de aceptación y el gate de pnpm verify: Prettier, ESLint con cero warnings, tsc estricto, tests contra una base de datos real.

   ↓
4. 04Corregir la spec

   Un output equivocado significa una spec equivocada o incompleta. Corrige el documento, regenera. Nunca parches el código dejando atrás la spec.

↓

Salida

Mergeado, testeado, rastreable hasta una decisión

El cuarto paso es donde vive la disciplina. Cuando algo salía mal, el instinto es parchar el código y seguir. Ese instinto es veneno a escala. Parchas el código, dejas la spec intacta, y la próxima vez que ese módulo se regenera o se extiende, el agente lo reconstruye desde la spec y reintroduce el mismo error. La spec es la fuente de verdad. El código es lo que sale de ella. Toda corrección entra primero en el documento.

El ciclo se repitió para cada capability en las trece aplicaciones: el motor de precios, el motor de liquidación, la capa de idempotencia, el servidor de auth, la cola de webhooks, el poller de depósitos on-chain, los manifests de Kubernetes, la librería de UI compartida. Mismo ciclo. Misma disciplina. Misma regla para las correcciones. La repetición es el punto. La consistencia a esta escala no es un ejercicio de gestión. Es lo que evita que una sola persona pierda el hilo de un sistema demasiado grande para tenerlo en la memoria.

Lo que atraparon las specs

El motor de precios

El ejemplo más claro es el motor de precios del exchange OTC. Antes de que existiera código, el comportamiento de los precios vivía en un solo archivo de spec. El modelo en dos fases: una tasa de peg fijada a un índice de referencia, activa hasta que entra la ventana de VWAP, lo que requiere al menos cinco operaciones confirmadas en una ventana móvil de 24 horas. La cadena de fallback entre cinco fuentes de mercado, agregadas por mediana con filtrado de outliers. Spreads asimétricos por par, aplicados después de resolver el VWAP. Y la regla de precisión de la que dependía todo lo demás: todo el cálculo monetario en enteros de 8 decimales, precisión de satoshi, nunca punto flotante.

Esa última regla no era un comentario ni una convención de código. Era un requisito, escrito en la spec antes de la primera línea de implementación, expresado como condición de falla de un test. La aritmética de punto flotante en software financiero no falla con estruendo. Se desvía. Pequeños errores de redondeo se acumulan a lo largo de varias operaciones, varios trades, varios clientes. Para cuando la diferencia se ve en un ledger, ya es un problema de soporte, no un test fallido. La spec lo convirtió en un test fallido desde el primer día.

Este es un fragmento representativo de cómo se veía esa spec:

## Precision rule (MUST)
All money arithmetic uses 8-decimal integers (satoshi precision).
No float or double anywhere in the pricing path.
A float in any response field is a test failure, not a lint warning.

## Two-phase model
Phase 1 (peg): price is fixed to the reference index.
Phase 2 (VWAP): rolling 24h VWAP, active once >= 5 confirmed trades exist.
The engine falls back from Phase 2 to Phase 1 when VWAP is unavailable.
Fallback is logged and triggers an ops alert.

## Fallback chain (market sources, in order)
1. Internal VWAP from confirmed trades (primary)
2. Cross-rate from 5 external sources, median-aggregated, outliers removed
3. Last known good price, flagged stale, ops notified

## Acceptance criteria
- Request with < 5 confirmed trades MUST use the peg price, not VWAP.
- When source 1 is unavailable, fallback to source 2 within 200ms.
- All returned amounts MUST be integers. A float anywhere is a test failure.
- Spread changes take effect on the next quote, never retroactively.

## Out of scope (v1)
- Dynamic spread adjustment based on volatility.
- Per-user spread overrides.

El código de producción refleja esa spec casi línea por línea. La cadena de fallback está implementada en el mismo orden. La regla de precisión la garantizan tanto el sistema de tipos como un test dedicado que falla si cualquier campo de la respuesta de precios contiene un float. El umbral de activación del VWAP es una constante con nombre que coincide con la spec. La lista de fuera de alcance frenó al agente de agregar features que nadie pidió, en dos ocasiones distintas. El documento es la razón por la que un dev solo podía confiarle saldos reales a un motor de exchange: las decisiones difíciles se tomaron, se revisaron y se congelaron antes de que el agente tocara la aritmética.

Idempotencia de pagos

El mismo patrón se repite en el gateway de pagos. Una spec congeló la regla de idempotencia antes de escribir una sola línea del endpoint de cobros:

## Idempotency (MUST)
WHEN a merchant POSTs a charge with a valid Idempotency-Key,
THE SYSTEM SHALL create at most one charge for that key.

WHEN the same Idempotency-Key is replayed within 24h,
THE SYSTEM SHALL return the original charge and create no new row.

## Schema
charges(id, merchant_id, amount_cents, currency, status,
        idempotency_key, created_at)
UNIQUE(merchant_id, idempotency_key)
-- Enforced at the database level. Application logic alone is not sufficient.
-- A retry that hits a constraint violation returns the original charge.

La constraint UNIQUE pone la regla en la base de datos: no en el código de la aplicación, no en una caché, no en un chequeo de middleware que un refactor futuro podría quitar. Sin una spec, esa constraint vive en tu cabeza. Y se cae en la próxima regeneración. El agente reconstruye desde la spec, la spec no tiene índice único, la nueva versión del módulo no tiene constraint. Un reintento del cliente, un cobro doble. La constraint en la spec es la constraint en la migración, que es la constraint en el schema en producción. Esa cadena es lo que garantiza la corrección entre sesiones.

✗

Si lo hubiera hecho con prompts

1. 01"construye un motor de precios para el exchange" te da aritmética de punto flotante y errores de redondeo acumulándose en saldos reales
2. 02scope creep silencioso: el agente agrega cosas que le parecen útiles pero que nadie pidió
3. 03edge cases como liquidaciones atascadas y reembolsos por desviación aparecen en producción
4. 04la constraint de idempotencia vive en tu cabeza, se cae al regenerar, cliente cobrado dos veces
5. 05ningún registro de por qué se tomó cada decisión

✓

Porque lo especifiqué

1. 01cálculo con enteros de 8 decimales declarado en la spec antes de generar una sola línea, garantizado por un test que falla ante cualquier float
2. 02el alcance negativo impidió que el agente construyera lo que nadie pidió
3. 03edge cases escritos como criterios de aceptación, atrapados en la revisión y no en producción
4. 04UNIQUE(merchant_id, idempotency_key) en el schema, garantizada por la base de datos
5. 05cada decisión rastreable en git, para siempre

En toda la plataforma, esa disciplina produjo lo que hace falta para que el dinero se mueva de forma segura. Un gateway de pagos con cuatro proveedores PIX detrás de un factory pattern, incluida una conexión bancaria directa BACEN Cob v2 sobre TLS mutuo. Webhooks firmados con HMAC-SHA256 con una cola de reintentos de backoff exponencial de seis intentos. Un servidor de auth OAuth 2.1 y OIDC con cinco roles, diecinueve scopes, 2FA con TOTP y client credentials máquina a máquina con alcance a nivel de fila. Un motor de liquidación con confirmación de dos bloques, reembolso automático por tolerancia ante desviaciones mayores al 10%, un tope de liquidación automática de US$ 10K que desborda hacia aprobación manual, un commit atómico en tres fases y recuperación ante fallos para liquidaciones que quedaron a medio camino. La página del proyecto tiene el checklist completo de producción.

Cada una de esas features empezó con una spec. Cada spec tenía su modo de falla descrito antes de que existiera una línea de implementación. Cada modo de falla se atrapó en el gate de revisión, no en producción.

El resultado en números

Lo que produjo la ejecución guiada por specs

28

archivos de spec12 dominios, 8 slash commands

~1.650

tests automatizadosVitest y Playwright

138K

líneas de TypeScripttodo generado a partir de specs

39

migraciones de base de datostodas rastreables

Lo que esto prueba, y lo que no

No se generaliza a cualquier dev. Tengo 25 años de experiencia, incluido trabajo previo en fintech, aeroespacial e integración empresarial. SDD escaló un modelo mental maduro. Las specs que escribí eran buenas porque ya sabía qué poner en ellas: qué edge cases importan en flujos de pago, dónde el punto flotante da problemas, cómo estructurar una cadena de fallback. No hay ninguna evidencia aquí de que SDD rescate a alguien que todavía está construyendo ese modelo. El método externaliza la experiencia. No la fabrica.

La velocidad se midió; la calidad no se auditó. “13 apps en 70 días” no dice nada sobre la densidad de defectos a largo plazo ni sobre la mantenibilidad. El gate de CI era estricto y los tests eran reales: Prettier, ESLint con cero warnings, tsc estricto, aproximadamente 1.650 tests en Vitest y Playwright contra un PostgreSQL real. Pero no afirmo nada sobre el costo de este código a cinco años. Tests en verde y un CI ajustado ya han llevado sistemas malos a producción.

Un plazo externo hizo un trabajo real. He visto a SDD producir bajo el plazo de un cliente y he visto proyectos personales con el mismo método estancarse indefinidamente. La spec amplifica la ejecución. No reemplaza la responsabilidad, la urgencia ni la presión de una fecha de entrega real.

Producción no es un negocio. Dinero real pasando por una infraestructura con hardening no es lo mismo que una empresa sostenible con clientes, márgenes y una cola de soporte. Este caso prueba un método de ingeniería, no un mercado.

Un solo dato, sin grupo de control. La respuesta correcta a este caso de estudio no es “SDD siempre funciona a esta escala”. Es “SDD demostrablemente funcionó a esta escala, una vez, para este operador”. Si aplicas el método y falla, la falla también es un dato. Un caso con resultado favorable no es lo mismo que una metodología con amplio respaldo empírico. Afirmo que el mecanismo es sólido, no que el resultado esté garantizado. El mecanismo es este: un agente de IA no tiene memoria entre sesiones, y la spec es la memoria externa que le das. Es un argumento estructural, no empírico. El caso de estudio muestra que funcionó. No prueba que siempre vaya a funcionar.

Nada de eso debilita el argumento central. La especificación fue el multiplicador, no la IA. Sin las specs, el agente es un albañil rápido sin planos. Con ellas, es un ingeniero senior que recuerda a la perfección cada decisión que tomaste. Eso es algo que una sola persona puede dirigir a la escala de una fintech.

Llévate el método, no solo la historia

La historia es un solo dato. El método es portable.

• Aprende el método: ¿Qué es Spec-Driven Development?
• Escribe tu primera spec: Cómo escribir una spec a partir de la cual una IA pueda construir
• Hazlo en tu editor: Spec-Driven Development con Claude Code
• Mira el proyecto: La fintech cripto en producción

El código se escribió solo. Las specs, no. Ahí se fueron los setenta días, y por eso alcanzaron.