Hace unos meses escribí sobre cómo la inteligencia artificial, y especialmente Claude Code, estaba cambiando mi forma de desarrollar software. No tanto por la posibilidad de generar código más rápidamente, sino por cómo estaba transformando mi participación en el proceso de desarrollo.
Desde entonces he seguido experimentando, aprendiendo y modificando algunas de mis costumbres. Una de las prácticas que más ha influido en mi trabajo durante estos últimos diez meses ha sido el Spec-Driven Development (SDD), o desarrollo guiado por especificaciones.
No he adoptado una metodología completa ni pretendo haber encontrado una forma definitiva de trabajar. He conocido una propuesta, he intentado comprender sus principios y he adaptado parte de ellos al tipo de proyectos que desarrollo habitualmente, especialmente plugins y ampliaciones para FacturaScripts.
Lo interesante es que esta experiencia me ha reafirmado en algo que siempre he considerado importante, aunque no siempre haya aplicado con la misma disciplina: dedicar tiempo a pensar y documentar una solución antes de comenzar a programarla.
El problema de empezar a programar demasiado pronto
Creo que muchos desarrolladores hemos cometido alguna vez el mismo error. Tenemos una necesidad, imaginamos una solución, resolvemos mentalmente una parte del problema y comenzamos a escribir código porque pensamos que ya sabemos cómo hacerlo.
A veces funciona. Otras veces descubrimos, cuando la implementación ya está avanzada, que no habíamos contemplado determinadas situaciones, que una decisión afecta a otra funcionalidad o que la estructura elegida dificulta futuras ampliaciones.
Entonces llegan las modificaciones, las excepciones y los parches. El software puede seguir funcionando, pero cada nueva necesidad resulta más complicada de incorporar. Y cuando volvemos a ese desarrollo meses después, no siempre recordamos por qué tomamos determinadas decisiones.
Esto no es un problema nuevo ni exclusivo de los programadores que están empezando. La diferencia es que ahora la inteligencia artificial nos permite llegar a esa situación mucho más rápidamente. Podemos describir una funcionalidad de forma bastante general y obtener en pocos minutos una implementación aparentemente completa.
Pero que una herramienta pueda generar código no significa que hayamos analizado correctamente el problema. Incluso puede suceder que terminemos manteniendo una implementación que no conocemos con la misma profundidad que si la hubiéramos escrito personalmente.
Por eso considero que, cuanto más fácil resulta generar código, más importante es detenerse a definir qué queremos construir y cómo debe comportarse.
Qué es SDD y qué propone
SDD son las siglas de Spec-Driven Development, un enfoque de desarrollo en el que las especificaciones adquieren un papel central. En lugar de comenzar directamente por la implementación, se define primero qué necesita resolver el software, cómo debe funcionar y qué decisiones deben guiar su construcción.
La idea de analizar antes de programar no tiene nada de nueva. Llevamos décadas trabajando con análisis funcionales, diseños técnicos y documentación. Lo que resulta especialmente interesante en el contexto actual es que esas especificaciones pueden servir también como instrucciones estructuradas para una inteligencia artificial encargada de implementar el software.
Una de las herramientas que ha popularizado este enfoque es Spec Kit, de GitHub. Su flujo principal distingue cuatro etapas: definir la especificación, preparar el plan técnico, descomponerlo en tareas y realizar la implementación. También contempla principios del proyecto y pasos adicionales de revisión y validación.
- Specify: definir qué queremos construir, qué problema resolvemos y qué comportamiento esperamos.
- Plan: estudiar cómo se construirá la solución, teniendo en cuenta la arquitectura, las tecnologías y las restricciones del proyecto.
- Tasks: convertir la planificación en tareas concretas, organizadas según sus dependencias.
- Implement: ejecutar esas tareas y verificar que el resultado responde a lo especificado.
Existen distintas herramientas y maneras de aplicar SDD, por lo que no hay una única estructura documental que resulte obligatoria para todos los proyectos. Lo que comparten es la importancia de construir y revisar las especificaciones antes de iniciar la implementación.
Cuando empecé a conocer este enfoque, encontré muchas ideas que encajaban con mi manera de entender el desarrollo. Pero también pensé que, para buena parte de mis proyectos, podía aplicar esos principios con una estructura más sencilla.
Conocer una metodología no significa aplicarla íntegramente
Gran parte de mi trabajo consiste en desarrollar plugins para FacturaScripts. No parto de cero: existe una aplicación con sus propios modelos, controladores, vistas, mecanismos de extensión y reglas de funcionamiento.
Eso condiciona bastante las decisiones que debemos tomar. En muchas ocasiones no necesitamos diseñar una arquitectura completa, sino estudiar cómo incorporar una funcionalidad respetando la estructura existente y evitando interferir con el núcleo de FacturaScripts o con otros plugins.
Una metodología pensada para proyectos de distinta naturaleza puede contener fases o documentos que no aporten el mismo valor en este contexto. Eso no significa que la metodología sea incorrecta, sino que quizá no necesitemos aplicar toda su estructura para resolver nuestro problema.
En mi caso, he terminado utilizando tres documentos Markdown. No los considero una versión mejorada de SDD, sino una adaptación que, por ahora, encaja bastante bien con los proyectos que desarrollo.
Mi adaptación de SDD: tres documentos Markdown
1. Requisitos: qué necesita el cliente
El primer documento recoge las necesidades del cliente de forma sencilla, normalmente mediante frases cortas o puntos esquemáticos. No intento resolver todavía cómo se implementará cada petición.
Por ejemplo, un cliente podría indicar que está teniendo problemas con números de identificación fiscal incorrectos al preparar el modelo 347. Esa es la necesidad que debemos registrar, sin decidir todavía qué modelo, controlador o extensión tendremos que modificar.
Este documento conserva algo fundamental: el problema original que queremos resolver. Con el tiempo, cuando una funcionalidad evoluciona, es fácil perder de vista por qué se solicitó inicialmente.
2. Especificación funcional: cómo debe comportarse la solución
El segundo documento desarrolla esas necesidades en un formato más narrativo. Aquí comenzamos a relacionar lo que solicita el cliente con el funcionamiento real de FacturaScripts.
Siguiendo el ejemplo anterior, podríamos definir que, al guardar la ficha de un cliente, el sistema comprobará la validez formal de su identificación fiscal para detectar posibles errores antes de elaborar el modelo 347.
A partir de ahí surgen preguntas que inicialmente quizá no habíamos considerado: ¿qué identificaciones debemos admitir?, ¿qué sucede con clientes extranjeros?, ¿cómo se informa al usuario de un error?, ¿qué hacemos con los registros existentes?, ¿debemos impedir guardar o simplemente advertir?
Es precisamente en este momento cuando el análisis empieza a aportar valor. Cada respuesta puede afectar al comportamiento final y conviene resolverla antes de comenzar la implementación.
3. Plan de tareas: qué hay que implementar
El tercer documento traduce la especificación funcional a tareas técnicas concretas. Aquí sí hablamos de modelos, tablas, controladores, vistas, extensiones, procesos y pruebas.
Las tareas se organizan por fases y dependencias técnicas, comenzando por aquello que necesita existir para poder desarrollar el resto. No se trata simplemente de enumerar funcionalidades, sino de establecer un orden de implementación coherente.
En el ejemplo anterior, tendríamos que estudiar los mecanismos de validación existentes en FacturaScripts, determinar el punto de extensión adecuado, implementar las comprobaciones necesarias y verificar los diferentes casos contemplados en la especificación.
La ventaja de esta separación es que cada documento responde a una pregunta distinta: qué necesita el cliente, cómo debe funcionar la solución y qué debemos desarrollar para conseguirlo.
La documentación también se construye conversando con la IA
Quizá esta sea una de las partes más importantes de mi forma de trabajar. No preparo necesariamente los tres documentos por mi cuenta para entregárselos después a Claude Code. En muchas ocasiones, los construimos mediante conversaciones.
Parto de los requisitos del cliente y comenzamos a desarrollar la especificación funcional. Claude propone comportamientos, plantea dudas o identifica situaciones que no había contemplado. Yo reviso sus propuestas, aporto mi conocimiento de FacturaScripts y cuestiono aquello que no considero adecuado.
A veces aceptamos una propuesta de Claude. Otras veces encontramos una solución diferente que encaja mejor con el funcionamiento del ERP. Lo importante no es quién ha tenido la idea, sino que el diálogo nos ayude a comprender mejor el problema y a encontrar una solución más sólida.
Con el plan técnico sucede algo parecido. Podemos discutir si conviene extender un modelo, incorporar un proceso independiente o reutilizar funcionalidades existentes. Cada decisión se analiza teniendo en cuenta sus consecuencias y termina reflejada en la documentación.
He comprobado que cuanto más tiempo dedico a conversar, leer y revisar los documentos, mejor definida queda la solución. No porque la IA tenga siempre razón, ni porque yo conozca todas las respuestas, sino porque contrastar alternativas permite descubrir cuestiones que podrían pasar desapercibidas.
También hay que mantener una actitud crítica. Claude puede interpretar incorrectamente una necesidad, desconocer algún comportamiento concreto de FacturaScripts o sugerir una solución innecesariamente compleja. Su aportación es valiosa, pero sigue siendo necesario revisar y decidir.
¿Cuándo considero que la planificación está terminada?
No utilizo un número determinado de horas ni una cantidad mínima de páginas para dar por terminado el análisis. Tengo una prueba bastante sencilla.
Si los documentos están bien preparados, las tareas contienen la información necesaria para avanzar por fases sin tener que reconstruir continuamente qué habíamos decidido. Claude dispone del proyecto, de sus instrucciones y de las tareas que debe realizar.
No necesita conocer cada conversación que mantuvimos ni todas las alternativas que descartamos. Pero sí debe encontrar documentadas las decisiones que condicionan la implementación, las restricciones que debe respetar y el resultado esperado.
Por supuesto, eso no significa que la planificación sea infalible. Durante el desarrollo pueden aparecer problemas, limitaciones o propuestas de mejora. Cuando sucede, volvemos a analizar la situación y, si cambiamos alguna decisión, actualizamos la documentación correspondiente.
Para mí, las especificaciones no son instrucciones intocables. Son una referencia que debe seguir representando la solución que estamos construyendo.
Qué he ganado durante estos diez meses
Después de aproximadamente diez meses utilizando y refinando este enfoque, mi valoración es muy positiva. Especialmente porque me permite afrontar desarrollos más complejos con una planificación más clara y, en mi experiencia, con muchos menos errores durante la implementación.
También he notado una diferencia enorme en los tiempos de desarrollo. Hay adaptaciones para las que puedo dedicar uno o dos días a conversar, analizar y preparar las especificaciones, y que después Claude Code consigue implementar en una mañana. Son trabajos que, desarrollados manualmente, podrían haberme llevado semanas.
No significa que todos los proyectos se comporten igual ni que el código generado deba aceptarse sin revisión. La comprobación del resultado, las pruebas y la validación siguen siendo parte de mi responsabilidad.
Pero lo que más valoro no es simplemente esa ganancia de velocidad. Es comprobar que dedicar tiempo a definir bien una solución permite comenzar la implementación con muchas menos incertidumbres.
La productividad llega como consecuencia de una planificación más completa, de decisiones mejor contrastadas y de disponer de tareas suficientemente concretas para ejecutarlas.
Hay otro aspecto que considero importante: el valor de la documentación no termina cuando comienza la programación. Conservar los requisitos, las decisiones funcionales y la planificación técnica permite entender, meses después, no solo qué se desarrolló, sino por qué se hizo de una determinada manera. Es una base útil para mantener, ampliar o incluso delegar el desarrollo, y también para elaborar posteriormente la documentación técnica y los manuales de usuario.
Todavía es pronto para valorar todos los beneficios a largo plazo, especialmente en mantenimientos que llegarán dentro de varios años. Pero disponer desde el principio de requisitos, decisiones y documentación organizada me parece una base mucho mejor para afrontar ese futuro.
No todos los proyectos necesitan el mismo nivel de planificación
Tampoco creo que debamos convertir la documentación en una obligación desproporcionada. Una corrección sencilla o un pequeño ajuste visual no siempre justifican preparar tres documentos y mantener largas conversaciones antes de modificar una línea de código.
En cambio, cuando hablamos de una nueva funcionalidad, un plugin con varios procesos relacionados o una ampliación que afecta a distintas partes del ERP, el análisis previo adquiere mucha más importancia.
La clave está en encontrar un equilibrio. Una documentación excesiva que nadie consulta o mantiene puede convertirse en otra forma de complicar el desarrollo. Pero prescindir del análisis para empezar a programar cuanto antes también tiene un coste, aunque inicialmente no resulte tan visible.
Por eso no considero que mis tres documentos sean una estructura válida para cualquier proyecto. Son simplemente la organización que actualmente me resulta útil para buena parte de mi trabajo.
Aprender también significa saber adaptación
A lo largo de nuestra carrera profesional encontramos nuevas herramientas, tecnologías y metodologías. Algunas aportan ideas realmente interesantes; otras quizá no encajen tan bien con nuestras necesidades.
Creo que, como profesionales del desarrollo de software, tenemos la responsabilidad de seguir investigando, estudiando y conociendo estas propuestas. La experiencia acumulada no debería convertirse en una excusa para dejar de aprender.
Pero aprender una metodología tampoco significa que debamos aplicarla íntegramente en todos nuestros proyectos. Tan importante como comprender sus principios es saber valorar qué partes necesitamos, cuáles podemos simplificar y en qué situaciones conviene utilizar una estructura más completa.
En mi caso, conocer SDD me ha ayudado a reforzar algo en lo que ya creía: la importancia de analizar y documentar antes de implementar. He encontrado una manera de trasladar esos principios a mi trabajo con FacturaScripts y Claude Code, sin necesidad de reproducir toda la estructura de una metodología concreta.
No considero que haya mejorado SDD. He aprendido de él y he adaptado lo que me aporta a mi entorno de trabajo. Probablemente dentro de unos meses vuelva a modificar algún aspecto de este proceso, porque seguiré encontrando problemas, soluciones y formas de trabajar que no había considerado.
Y quizá esa sea la reflexión más importante que me llevo de esta experiencia: el valor de una metodología no está en seguirla al pie de la letra, sino en comprender sus principios y saber utilizarlos para desarrollar mejores soluciones.
La inteligencia artificial ha cambiado enormemente la velocidad a la que podemos implementar software. Pero pensar, analizar, tomar decisiones y documentarlas continúa siendo una parte esencial de nuestro trabajo. Ahora, además, contamos con una herramienta que puede ayudarnos también a realizar mejor esas tareas.