SDD: pros, contras y la estrategia que realmente funciona
Hay un tipo de desarrollador que me resulta muy familiar.
Abre un tutorial de IA. Ve al tipo construir una app desde cero en 20 minutos. Se emociona. Abre su proyecto real. Y se da cuenta de que lo que tiene delante no tiene nada que ver con lo que acaba de ver.
Porque su proyecto no es un repo vacío con carpetas bien ordenadas.
Su proyecto es un monolito de cuatro años con lógica de negocio enterrada en helpers que nadie sabe quién escribió. Con una tabla de base de datos que tiene 47 columnas y ninguna tiene comentario. Con tres formas distintas de hacer la misma cosa según en qué parte del código estés. Con una carpeta llamada utils que tiene 3.000 líneas.
Eso es un proyecto brownfield.
Y la IA no te lo va a limpiar sola.
Pero hay algo que sí puedes hacer. Y funciona mejor de lo que parece.
Primero, el problema real
Cuando la gente descubre Spec-Driven Development, lo primero que piensa es: "genial, pero eso es para proyectos nuevos."
Es un razonamiento lógico. SDD habla de escribir la spec antes de empezar. En un brownfield ya empezaste hace años. El barco ya está en el agua. No puedes volver al puerto a hacer los planos.
Esa lógica tiene un fallo.
SDD no es un método para proyectos. Es un método para cambios.
Y tú, trabajes en el proyecto que trabajes, vas a hacer cambios. Hoy, mañana, la semana que viene. Cada vez que añades una feature, cada vez que corriges un bug, cada vez que tocas algo que otro construyó y que no entiendes del todo.
Ahí es exactamente donde entra SDD. No en el origen del proyecto. En cada cambio que haces a partir de ahora.
Lo que SDD sí resuelve en brownfield
El sistema deja de ser una caja negra.
Cuando escribes una spec sobre algo que ya existe, el primer paso es describir cómo funciona ahora. No cómo debería funcionar. Cómo funciona.
Ese ejercicio solo ya tiene un valor enorme.
Muchos equipos llevan años trabajando en sistemas que nadie sabe describir con precisión. Hay intuición. Hay memoria histórica. Hay "creo que funciona así pero no estoy seguro." La spec obliga a convertir esa niebla en texto.
Y el texto se queda. El texto se versiona. El texto lo puede leer el agente.
El agente tiene una frontera.
El problema clásico del brownfield con IA: le pides al agente que cambie una cosa y te cambia cinco. Porque el agente no sabe qué está permitido tocar y qué no.
Una spec con una sección "fuera de scope" resuelve eso de forma radical.
El agente no adivina. Ejecuta lo que le das. Si le das una spec que dice explícitamente qué no entra en este cambio, el agente no lo toca. No porque sea listo. Porque tiene instrucciones.
Las regresiones bajan.
No desaparecen. Bajan.
Si la spec describe el comportamiento que tiene que seguir siendo verdad cuando el cambio esté hecho, el agente tiene un criterio para verificar su propio trabajo. "¿Lo que he implementado cumple lo que dice la spec?" Es una pregunta que el agente puede responder.
Sin spec, el agente no tiene criterio. Tiene intuición. Y la intuición de un agente en código heredado que no entiende del todo es una fuente inagotable de bugs que aparecen tres semanas después.
El conocimiento se acumula.
Este es el punto que más se subestima.
Cada mini-spec que escribes es documentación que se queda en el repo. No en Notion. No en Confluence. No en la cabeza del desarrollador que lleva más tiempo en el equipo. En el repo, junto al código que describe.
Con suficientes cambios bien especificados, el sistema empieza a tener memoria. Los módulos más críticos tienen spec. Los flujos más usados están descritos. El onboarding de alguien nuevo mejora sin que nadie lo haya planificado.
Es un efecto secundario del método. Pero es uno de los más valiosos.
Lo que SDD no resuelve
Aquí hay que ser honesto.
El código mal estructurado sigue siendo malo.
Una spec no refactoriza nada. Si tienes un módulo de 800 líneas con efectos secundarios en tres capas distintas, la spec te ayuda a acotar el cambio. Pero el módulo sigue siendo un desastre.
SDD no es una excusa para no hacer el trabajo de limpieza cuando es necesario. Es una herramienta para hacer cambios seguros. No es la misma cosa.
Sin tests, la spec flota en el aire.
La spec describe el comportamiento esperado. Pero si no hay nada que verifique automáticamente que ese comportamiento es real, la spec es solo texto.
Los tests y la spec se complementan. La spec dice qué tiene que ser verdad. Los tests comprueban que lo es. Si tienes spec pero no tienes tests, tienes la mitad del sistema. La mitad útil para pensar. Pero no la mitad que te avisa cuando algo se rompe.
Documentar retroactivamente un sistema grande es trabajo.
No hay atajo aquí. Si tienes un monolito de cinco años y quieres tener spec de todo antes de tocar nada, vas a tardar meses. Y probablemente no lo vas a terminar nunca porque mientras escribes specs el negocio sigue pidiendo features.
La solución no es intentar especificarlo todo de golpe. La solución es no intentarlo.
La estrategia que realmente funciona
No especifiques el sistema. Especifica el cambio.
Es la diferencia entre un proyecto paralizado y uno que avanza.
El flujo es este:
1. Identifica exactamente qué vas a tocar
No el sistema. No el módulo entero si solo necesitas cambiar una parte de él. La unidad mínima de trabajo que tiene sentido hacer de forma independiente.
Cuanto más pequeño sea el alcance, más fácil es especificarlo. Y cuanto más fácil es especificarlo, más probable es que lo hagas.
2. Escribe el estado actual antes que el estado deseado
Este es el paso que más gente se salta. Y es el más importante en brownfield.
Antes de escribir lo que quieres que haga el sistema, escribe lo que hace ahora. Con precisión. No "valida los datos del formulario." Qué valida, cuándo, qué pasa cuando falla, qué no valida aunque debería.
Ese ejercicio tiene dos efectos. Primero, te obliga a entender de verdad lo que vas a tocar antes de tocarlo. Segundo, le da al agente el contexto que necesita para no romper lo que ya funciona.
## Estado actual
- El formulario valida formato de email solo en el cliente (regex básico)
- Si el campo está vacío y el usuario hace submit, no pasa nada visible
- El servidor acepta cualquier payload sin validar
## Estado deseado
- El servidor valida el email antes de persistir (formato + dominio real)
- El cliente muestra un mensaje de error específico por campo al hacer submit
- Los errores de servidor se mapean al campo correspondiente en el formulario
## Fuera de scope
- No se cambia el diseño visual del formulario
- No se añaden campos nuevos
- No se toca la lógica de envío de emails posterior al submit
- No se migran registros existentes con emails inválidos
La sección "fuera de scope" no es opcional. Es la que protege el trabajo que ya funciona.
3. Dale al agente contexto preciso, no contexto abundante
El error más común: pegar todo el repo en el contexto y esperar que el agente entienda qué es relevante.
El agente trabaja mejor con menos contexto bien elegido que con todo el contexto mal filtrado.
Dale los archivos que afectan directamente al cambio. El componente del formulario. El endpoint del servidor. El schema de validación si existe. Nada más.
4. Verifica contra la spec, no contra la intuición
Cuando el agente termine, la pregunta no es "¿parece bien?" La pregunta es "¿hace lo que dice la spec?"
Esa es la diferencia entre revisar con criterio y revisar con fe.
Si algo de lo que describe la spec no está implementado, vuelves al agente con esa diferencia concreta. No con "esto no está bien." Con "la spec dice X y el código hace Y."
5. La spec se queda en el repo
No la borres cuando el cambio esté hecho. No es documentación temporal. Es la memoria del sistema.
La persona que toque ese módulo dentro de seis meses — que probablemente seas tú — va a abrir ese archivo y va a entender en dos minutos lo que de otro modo le habría costado dos horas de arqueología de código.
El efecto acumulado
Aquí está la parte que más me gusta de este método en brownfield.
No necesitas un sprint de documentación. No necesitas parar todo para "pagar la deuda técnica." No necesitas convencer a nadie de que hay que refactorizar antes de avanzar.
Solo necesitas que cada cambio que hagas a partir de ahora sea un cambio con spec.
Eso es todo.
Con el tiempo, el sistema que era opaco empieza a tener zonas claras. Los módulos que más se tocan son los que más spec tienen. Que resulta ser exactamente el conocimiento más valioso: el de las partes que cambian, no el de las partes que llevan tres años sin tocarse.
El brownfield no desaparece. Pero deja de ser un problema sin solución.
Se convierte en un sistema que se va documentando solo, cambio a cambio, a medida que crece.
Una última cosa
El método que describo aquí — spec antes del cambio, estado actual antes del estado deseado, contexto preciso al agente, verificación contra spec — es el núcleo de lo que enseño en mi curso.
Lo construí trabajando con Claude Code en proyectos reales, no en demos. Y lo he aplicado exactamente en el tipo de proyecto del que hablo aquí: código heredado, sin documentación, con decisiones que nadie recuerda haber tomado.
Si quieres ver cómo se aplica esto en proyectos reales, tengo un curso donde lo cubro en detalle.
Bezael Pérez — DominiCode
Top comments (0)