Don't Code, Specify: por qué los devs senior obtienen peores resultados con IA
La metodología que usé para construir una fintech cripto (13 apps) en 70 días, solo, con agentes de IA.
La metodología que usé para construir una fintech cripto (13 apps) en 70 días, solo, con agentes de IA.
Llevo más de 25 años escribiendo código de producción. Cuando llegaron las herramientas de IA para programar, hice lo que hace cualquier dev con experiencia: me lancé, escribí un prompt y vi a Claude generar 500 líneas de código en 30 segundos.
Fue hermoso. Fue rápido. Y estaba completamente mal.
No mal de sintaxis. El código compilaba. Mal en lo que importa: resolvía un problema que yo no había definido del todo, con supuestos que yo no había hecho, en una arquitectura que no quería.
Pasé meses en ese ciclo. Prompt, generar, tirar a la basura, otro prompt. Hasta que lo vi claro: el problema no era la IA. El problema era yo.
Estaba tratando a un ingeniero de primer nivel mundial como a un dev junior. “Hazme un sistema de tareas.” “Agrega autenticación.” “Ahora hazlo en tiempo real.” Cada prompt era una orden sin contexto, lanzada a una herramienta sin ninguna memoria de mis decisiones anteriores.
Ahí fue cuando adopté Spec-Driven Development (SDD). Con él construí un monorepo de 13 apps, con 3 APIs, 3 bases de datos y Kubernetes en producción. Solo. (¿El término es nuevo para ti? Empieza por qué es Spec-Driven Development, la guía completa.)
Rápido y mal sigue siendo mal
Contrata al albañil más rápido del mundo. Levanta muros en minutos, instala la plomería en segundos, termina el techo antes del almuerzo.
Olvídate de darle los planos.
Te queda un edificio en pie: el baño donde iba la cocina, puertas que abren contra la pared, escaleras que no llevan a ningún lado.
Claude Code, Cursor, Copilot. Ellos son ese albañil. Generan código a una velocidad que hace cinco años era ciencia ficción. Pero velocidad sin dirección es solo una forma más rápida de llegar al lugar equivocado.
El costo real aparece en las cuentas:
Sin specs
- 01prompt → generar → notar que falta algo
- 02otro prompt → romper algo → arreglar → otro prompt
- 03repetir hasta que más o menos funcione
- 048 a 12 horas para una sola feature
Con specs
- 012 horas de planificación
- 02generar desde la spec
- 03ajustes menores
- 043 horas, listo
Por qué los devs con experiencia se resisten
Si tienes 10, 15, 20 años de experiencia, seguramente estás pensando: “Ya sé lo que tengo que construir. Las specs formales son burocracia.”
Yo también lo pensaba. Durante años, las buenas prácticas empujaron agilidad, iteración rápida, “software funcionando sobre documentación extensiva”.
Pero ya no programas solo. Tu modelo mental no se transfiere al agente.
Cuando escribes código, tu cabeza sostiene el sistema entero. Sabes que esa función oscura en utils.ts es crítica porque recuerdas la vez que salvó el proyecto a las 2 de la mañana. Claude no tiene esa memoria. Cada sesión empieza de cero.
Los cuatro pilares del SDD
El SDD se apoya en cuatro pilares, cada uno con un gate de aprobación humana antes de que empiece la siguiente fase:
Los cuatro pilares
- 01Requisitos (QUÉ)
Lo que el sistema tiene que hacer. Lenguaje de negocio, comportamientos observables, independiente de la tecnología.
- 02Diseño (CÓMO)
Cómo funciona. Decisiones de arquitectura, elección de tecnologías con justificación, modelos de datos, contratos de API.
- 03Tareas (CUÁNTO)
Descomponer en unidades implementables. Cada tarea: 2 a 4 horas, testeable de forma independiente, dependencias claras.
- 04Implementación (EJECUCIÓN)
El código sigue la spec. Verificación contra los criterios de aceptación. Registro de las decisiones.
Cuanto antes detectas un error, más barato es corregirlo. Los gates aseguran que los errores se detecten antes de propagarse.
La anatomía de una buena spec
El principio de la niña lista
Explícale tu sistema a una niña de 12 años muy inteligente. Es aguda, hace buenas preguntas y maneja conceptos complejos, pero no tiene tu contexto implícito.
“Haz eso de las tareas.” Se pierde.
“Cuando alguien crea una tarea, guarda el título, verifica que tenga permiso en ese workspace y notifica a todos los que están viendo la lista.” Ahora sí puede trabajar contigo.
Ese es el nivel de claridad que necesitan tus specs.
Sé específico, no genérico
Mal: “El sistema debe ser rápido.”
Bien: “El endpoint GET /api/v1/tasks debe responder en menos de 500ms en p95 para listas de hasta 1.000 tareas.”
Define el alcance negativo
Lo que explícitamente no vas a construir importa tanto como lo que sí:
- Este MVP no soporta tareas recurrentes
- Sin integración con calendario (v2)
- Sin registro de horas
- Sin dependencias entre tareas (solo subtareas)
Esto evita que la IA, con toda la buena intención, agregue features que no pediste. Pasa todo el tiempo.
Usa ejemplos concretos
En lugar de “validar el título de la tarea”, especifica el comportamiento exacto:
""→ Error: “Title is required”"A"→ Error: “Minimum 2 characters”"Fix bug #123"→ Éxito"A"× 501 → Error: “Maximum 500 characters”" "→ Error: “Title is required”
Cada pregunta que respondes en la spec es un supuesto equivocado menos en el código.
Lo que SDD NO es
No es Waterfall. En SDD las specs son documentos vivos. Evolucionan, pero de forma controlada. Puedes volver y cambiar requisitos, pero el cambio se propaga de forma consciente por el diseño y las tareas.
No es exagerado para todo. Usa SDD cuando el proyecto dura más de unos días, involucra varias features complejas o abarca varias sesiones de desarrollo. Para un script de una hora, manda el prompt y listo.
Cómo se comparan los enfoques
| Criterio (peso) | Prompt a secas | Waterfall | Spec-Driven |
|---|---|---|---|
| Velocidad hasta el primer resultado (2) | 5 | 2 | 4 |
| Corrección (3) | 2 | 4 | 5 |
| Costo de retrabajo (menor es mejor, puntaje invertido) (3) | 1 | 3 | 5 |
| Escala con el tamaño del equipo (2) | 1 | 3 | 5 |
| Puntuación ponderada | 21 | 31 | 48 |
Scale 1-5 (5 = best). Highlighted column: winner by weighted score.
Las pruebas
Construí una plataforma fintech cripto completa con SDD: pasarela de pagos, motor de exchange OTC, servidor de autenticación OAuth 2.1, arquitectura multi-tenant, deploy en Kubernetes. 13 apps en un monorepo, 8 paquetes compartidos. Solo.
Las specs fueron el multiplicador. No la IA. Las specs.
Sin ellas, Claude Code es un albañil rápido sin planos. Con ellas, es un ingeniero senior que recuerda cada decisión que tomaste.
Elige una feature. Escribe tres archivos.
Empieza con una feature. Escribe estos tres archivos:
requirements.md: ¿Qué hace? ¿Para quién? ¿Cuáles son los criterios de aceptación?design.md: ¿Cómo funciona? Modelo de datos, endpoints de la API, decisiones de arquitectura.tasks.md: Divídela en bloques implementables de 2 a 4 horas, con dependencias claras.
Pásasela a tu agente. Ese es todo el sistema.
Sigue leyendo:
- ¿Qué es Spec-Driven Development?: el método completo, los cuatro pilares y cuándo saltárselo
- El caso de estudio: 13 apps, 70 días y las pruebas
- Cómo escribir una spec: plantillas y el formato EARS
- SDD vs. vibe coding: el antídoto disciplinado contra programar a ojo
Soy practicante de SDD, no su creador. Mi autoridad viene de aplicarlo a escala: 13 apps, 70 días, solo, en producción. He formado a más de 30.000 desarrolladores en ingeniería de software y a más de 400 profesionales en flujos de trabajo con IA.
La primera spec lleva tiempo. La segunda, la mitad. Para la tercera, ya es memoria muscular.
El código se escribe solo. La spec, no.
Felipe
La newsletter
Don’t Code, Specify. Cada semana, agentes de IA en producción de verdad. Sin hype: lo que funcionó y lo que se rompió.
Suscríbete en Substack (se abre en una pestaña nueva)