Spec-Driven Development (SDD)
La metodología que pone la especificación técnica antes que el código — y que transforma radicalmente cómo los equipos trabajan con herramientas de IA generativa.
Principio rector
"No Spec, No Code"
Reducción de retrabajo
40–60%
Compatibilidad
Scrum · Kanban · TDD
En la era de la programación asistida por IA, la calidad del output depende directamente de la calidad del input. SDD nació como respuesta a un problema concreto: los equipos que adoptaban herramientas de IA generativa obtenían resultados inconsistentes porque el contexto que proporcionaban era ambiguo, incompleto o inexistente. La especificación previa al código resuelve ese problema en la raíz.
A continuación encontrarás las preguntas más frecuentes sobre SDD: desde su definición hasta su integración con metodologías ágiles, pasando por herramientas concretas y los errores más comunes al adoptarlo.
Artículos del blog
Casos prácticos sobre agentes IA y metodología SDD.
Memoria persistente entre sesiones de agentes IA
Los LLMs son stateless por diseño. Guía práctica para elegir la estrategia correcta: CLAUDE.md, mem0, Zep, Graphiti y Engram — con un ejemplo TypeScript listo para usar.
GitHub Actions vs. agente: quién debe mover los tickets
Delegar las transiciones de estado de Jira o Linear a integraciones de GitHub reduce tokens consumidos y elimina lógica del contexto del agente. Cuándo hacerlo y cuándo no.
¿Quién enriquece los tickets: el desarrollador o el agente?
El rol del AI Engineer cambia la ecuación: ya no es el desarrollador quien redacta los criterios de aceptación, sino quien valida que estén bien definidos. La diferencia importa.
Markdown vs. Sudolang para prompts: qué elegir en 2026
Sudolang y NAST prometían reducir tokens y mejorar la precisión. Qué dice la evidencia real, por qué la mayoría de equipos sigue con Markdown y cuándo tiene sentido explorar alternativas.
Modo rojo vs. modo verde: velocidad o contexto en SDD
El trade-off más frecuente al adoptar SDD: ¿invierto en documentar bien o entrego rápido? Cómo definir dos modos de trabajo claros para no tener que decidirlo ticket a ticket.
Contexto en agentes background: qué heredan y qué no
Al lanzar un agente en background, ¿parte de un contexto limpio o hereda el de la ventana principal? La respuesta cambia según uses un orquestador real o el modo background de Claude Code.
Determinismo en IA generativa: greedy decoding y guardrails
Los LLMs son probabilísticos por diseño. Cómo reducir la variabilidad del output con greedy decoding, temperatura baja y guardrails en el contexto — y por qué un CLAUDE.md bien estructurado es el primer paso.
Qué es un token y cómo se mide en los LLMs
Los tokens son la unidad de medida que usan los LLMs. Cómo funciona la tokenización, qué significa el context window, cómo se calcula el coste y cómo optimizarlo en tus agentes.
Gestionar dependencias entre agentes en un orquestador
Cuando varias tareas dependen entre sí, ¿cómo sabe el agente en qué orden ejecutarlas? Estrategias para definir dependencias explícitas en el orquestador y evitar que el agente las deduzca.
¿Para qué sirve un agente si ya tienes skills y comandos en Claude Code?
Cuando las skills ya encapsulan toda la lógica, ¿qué aporta definir un agente por separado? La respuesta está en el modelo de ejecución futuro y en cómo se orquestan los subagentes especializados.
SDD en microservicios: ¿cómo gestionar cambios que afectan a varios servicios?
Cuando un cambio "derrama" de un microservicio a otro, el problema raramente es SDD. Casi siempre es que los dominios no están bien definidos. Cómo aplicar DDD, eventos y Consumer-Driven Contracts para contenerlo.
¿Sigue siendo necesario OpenAPI / Swagger si usas SDD con Claude Code?
Con Claude Code generando código a partir de specs, ¿tiene sentido mantener contratos OpenAPI? La respuesta es sí — y además son complementarios. OpenAPI sigue siendo el estándar de contrato entre equipos.
Spec Kit vs OpenSpec: ¿qué herramienta SDD elegir para tu equipo?
Dos herramientas CLI para Spec-Driven Development con filosofías opuestas: fragmentación por feature vs fuente de verdad unificada. Cuándo usar cada una.
¿Son lo mismo los parámetros de un modelo y las dims del embedding?
Una confusión frecuente al empezar con RAG: mezclar los parámetros internos del modelo con las dimensiones del vector de salida. Son conceptos de nivel completamente distinto — aquí la diferencia con analogías y tablas.
¿Por qué GPT-4 no sirve para generar embeddings en RAG?
GPT-4 es el modelo más potente de OpenAI — entonces, ¿por qué en RAG hay que usar text-embedding-3-small? Porque son modelos con objetivos distintos. Aquí la diferencia y qué modelo elegir según el caso.
¿Más dims siempre es mejor en RAG? Calidad, velocidad y coste
Más dimensiones en el embedding = mejor calidad semántica, pero también más almacenamiento, búsquedas más lentas y mayor coste de ingesta. Cómo elegir el número correcto de dims para tu sistema RAG.
Streamlit vs HTML+Flask: por qué los labs de IA usan Python puro para la UI
En un lab de LangChain, Flask + HTML puede bloquear a los alumnos en sintaxis HTTP antes de ver lo importante. Streamlit elimina esa fricción. Comparativa completa y cuándo usar cada uno.
¿Por qué separar el template del contexto en un agente conversacional con LangChain?
Un agente conversacional bien diseñado vive en dos repositorios: el template con la arquitectura genérica y el contexto con las reglas de negocio. Por qué esta separación importa y cuándo ignorarla.
¿Las rules de Claude Code funcionan en Cursor u otros IDEs? Cómo hacer el contexto portable
Las rules de Claude Code son nativas de ese entorno. Cursor tiene su propio formato. Para ser IDE-agnóstico, la solución es agents.md — una fuente de verdad que cualquier asistente puede consumir.
¿Para qué sirve el docstring del @tool en LangChain? La interfaz que el LLM usa para razonar
El docstring de un @tool no es documentación para desarrolladores — es el texto que el LLM lee para decidir cuándo y cómo invocar la herramienta. Tratarlo como un prompt cambia los resultados.
Chatbot determinista, narrow AI o agente conversacional: cuándo es cada cosa
Tres conceptos que se confunden habitualmente. La diferencia entre un chatbot de flujos, un narrow AI agent y un agente general determina qué construir — y qué evitar — en cada caso de uso.
¿La temperatura controla el alcance de un agente? La confusión más común sobre LLM guardrails
La temperatura controla la creatividad de las respuestas, no lo que el agente puede responder. El alcance y los guardrails viven en el system prompt. Son dos ejes completamente distintos.
¿El RAG recupera información desactualizada sin saberlo? Cómo gestionar la frescura del índice
Un vector store no tiene concepto de datos obsoletos — recupera chunks desactualizados con la misma confianza que frescos. Estrategias: reindexado manual, programado, CRAG y Self-RAG.
¿MCP o tool codificada en LangChain? Cuándo usar cada enfoque
No hay razón arquitectural para preferir una tool codificada sobre MCP. El @tool es la interfaz LangChain; lo que hay dentro — MCP, REST, GraphQL — es un detalle de implementación.
Skills de SDD y tools de LangChain: ¿son lo mismo? La distinción que confunde a los equipos
Las skills de SDD son instrucciones para el agente de desarrollo. Las tools de LangChain son funciones que el agente de producción ejecuta en runtime. Capas distintas, momentos distintos, propósitos distintos.
¿Tiene sentido usar un modelo local en vez de Claude para development asistido?
Los modelos locales son atractivos por el ahorro en tokens. Pero para context engineering completo necesitas mucho más que el modelo. Un análisis honesto del ROI.
¿Por qué es tan lento un LLM local con i7 y 32 GB de RAM y sin GPU?
Instalar Ollama y correr Qwen o Gemma es fácil. Pero sin GPU dedicada el rendimiento puede ser inutilizable en producción. Por qué pasa y qué modelos funcionan bien según el hardware.
¿Tiene sentido un modelo local pequeño + RAG para un dominio estrecho?
Para casos de uso muy específicos, un modelo de 2B parámetros con una base vectorial bien construida puede superar a un modelo grande sin contexto. Por qué el RAG compensa las limitaciones del modelo.
¿Cómo se actualiza la base vectorial del RAG cuando la fuente cambia?
Un vector store no aprende solo — recupera chunks desactualizados con la misma confianza que frescos. Estrategias concretas de re-indexación: scraping programado, crons, CRAG y Self-RAG.
¿Cómo se registran las tools en un agente LangChain? El flujo de bind_tools() al LLM
No hay un if "ahora toca esta tool" en ningún sitio. El LLM decide qué tool invocar leyendo sus docstrings. bind_tools() es el puente entre tu lista de funciones Python y el razonamiento del modelo.
¿Puedo usar el embedding de cualquier proveedor sin cambiar nada?
Cambiar de OpenAI a Nvidia para generar embeddings no es solo cambiar una API key. Por qué los embeddings son narrow AI, cómo se adaptan al proveedor y qué diferencia real hay con un LLM completo.
¿Todavía hace falta saber programar para construir agentes de IA?
Cada vez se delega más la parte de código a la IA. Por qué la arquitectura sigue siendo imprescindible, dónde vive el riesgo de construir sistemas insostenibles y qué rol se vuelve más importante que picar código.
Le prohibí explícitamente a mi agente tocar la base de datos. Lo hizo igual.
Un agente con instrucción explícita de no acceder a la base de datos ejecutó una consulta igualmente. Por qué las reglas genéricas no bastan y cómo especificar guardarraíles que sí se respetan, capa por capa.
¿Sirve de algo una metodología de desarrollo si el equipo aún no usa IA?
El cuello de botella real de un equipo siempre fue la coordinación humana, no la interacción con un modelo. Por qué formalizar un protocolo compartido compensa con o sin IA de por medio.
¿Se puede generar un grafo semántico que conecte las specs con el código real?
Herramientas que combinan AST y semántica de especificaciones para enlazar cada endpoint documentado con su implementación real. Cómo funcionan y cuándo compensa su coste en tokens.
¿Hace falta un framework SDD formal si el equipo ya sigue los mismos pasos sin él?
Un equipo puede llevar meses aplicando de facto planificación funcional, técnica e implementación sin ningún framework con nombre propio. Qué aporta realmente formalizarlo.
¿Por qué seguir repitiendo "usa patrones" en cada prompt en vez de ponerlo en las reglas?
Si una instrucción se repite en casi todos los prompts, probablemente no debería vivir en el prompt. Dónde debe vivir cada tipo de conocimiento recurrente en el contexto de un agente.
¿Ya no tiene sentido revisar línea a línea el código que genera la IA?
Fiscalizar el casting de un método o qué librería usó el agente cada vez tiene menos sentido. Dónde se traslada realmente el valor de la revisión de código hoy.
¿Existen herramientas que ataquen el AST directamente para refactors rápidos con IA?
Un refactor pequeño que antes se resolvía en dos clics desde el IDE ahora puede hacer que el agente "dé vueltas" leyendo todo el código como prosa. MCPs como Serena atacan el AST directamente.
¿Cuáles son las buenas prácticas para diseñar agentes de IA sin duplicar roles?
No hay un decálogo cerrado, pero sí una heurística simple: partir del flujo de trabajo humano real y no inventar capas que no existen. Cómo evitar duplicar lógica entre agentes, reglas y skills.
¿Cómo abordar un refactor con IA: pedirlo directamente o preparar el contexto antes?
Pedirle a un agente "hazme un refactor" sin más suele salir mal. El primer paso real es el mismo que en cualquier tarea de SDD: preparar el contexto antes de ejecutarlo.
¿Importa que cada desarrollador use un copilot o un modelo distinto si el equipo comparte el mismo harness?
Los copilots de primer nivel ya rinden parecido en código. Lo que hace reproducible el resultado es el harness compartido, no la herramienta de cada uno.
¿Qué es la compactación de contexto y por qué conviene evitarla al dimensionar tickets?
Compactar decide por ti qué información se pierde. Por eso en SDD cada ticket debería caber entero en una ventana de contexto sin compactar.
¿El contexto de un agente crece en cada vuelta del bucle? Los tres niveles que se suelen confundir
Bucle de thinking, contexto de la tarea y contexto persistente son cosas distintas. Separarlas explica por qué cada ticket debe empezar limpio.
¿Merece la pena conservar las specs de cambios pasados? El archivo de cambios en OpenSpec
Archivar diseño, propuesta y tareas de cada cambio da al agente una fuente de verdad que no tiene que reconstruir desde el historial de Git.
SDD, OpenSpec y context engineering: ¿en qué se diferencian?
Una técnica, una metodología y un framework que se suelen usar como sinónimos. Cómo encajan y qué aporta cada uno al equipo.
¿Para qué sirve el system prompt si ya tengo RAG?
System prompt y RAG no son intercambiables. Uno define la identidad inmutable del agente; el otro provee conocimiento vivo. Mezclarlos abre la puerta al prompt injection.
¿Cambian los embeddings si la documentación está en otro idioma?
Los encoders modernos operan a nivel semántico, no de palabras. Un concepto en inglés y en español produce vectores muy cercanos — y eso hace el RAG multilingüe casi transparente.
¿Qué ocurre cuando el contexto del chatbot llega al límite de tokens?
El context window es finito. Cuando se llena, hay que compactar. Estrategias automáticas, compactación con distancia coseno y el principio de diseñar desde el percentil 95 de tus conversaciones.
¿Cómo descubre el LLM qué herramientas tiene disponibles y cuándo usarlas?
En LangChain, el docstring del @tool es el prompt que instruye al LLM sobre cuándo invocarla. El patrón "Use this when…" y el tool loop de hasta 5 iteraciones, explicados.
¿Cómo sabes si tu chatbot RAG está funcionando bien en producción?
LangSmith, ELK, LLM Arena y métricas custom: cómo monitorizar economía de tokens, precisión de retrieval, guardrails y alucinaciones en un RAG desplegado.
Menos tokens por llamada no es lo mismo que menos coste real
GitHub optimizó el harness de Copilot para reducir coste sin perder calidad. La lección no es "acorta el output": es medir la tarea completa, no la llamada suelta — y aplica igual a tus reglas de SDD.
Preguntas frecuentes sobre SDD
El Spec-Driven Development (SDD) es una metodología de desarrollo de software en la que la especificación técnica y funcional se crea y valida antes de escribir una sola línea de código. La premisa central es "No Spec, No Code": sin una especificación aceptada por el equipo, no se inicia la implementación. El proceso comienza con la definición del propósito, los casos de uso, las validaciones, los edge cases y los criterios de aceptación en formato GIVEN/WHEN/THEN. Solo después de que todos los stakeholders aprueban la spec se pasa a la fase de codificación.
TDD y SDD son complementarios, no excluyentes. TDD empieza con los tests antes del código; SDD empieza con la especificación antes de todo lo demás, incluyendo los tests. En una pipeline con IA generativa, el flujo óptimo es: especificación (SDD) → tests en rojo (TDD red) → implementación (TDD green) → refactor. SDD define el "qué" y el "por qué"; TDD define el "cómo se verifica". Aplicar ambos juntos es lo que permite que los agentes de IA produzcan código fiable y reproducible.
Una especificación SDD completa incluye: (1) Propósito y contexto de negocio, (2) Casos de uso con actores definidos, (3) Criterios de aceptación en formato GIVEN/WHEN/THEN, (4) Validaciones y reglas de negocio, (5) Edge cases y corner cases, (6) Diagrama de flujo de datos, (7) Integraciones con sistemas externos, (8) Definition of Done (DoD) con checklist verificable. La spec debe ser lo suficientemente detallada para que un desarrollador pueda implementarla sin necesitar preguntar nada al equipo de producto.
La IA generativa es tan buena como el contexto que recibe. Una especificación SDD bien escrita actúa como un prompt de alta calidad: proporciona contexto, restricciones, casos esperados y criterios de aceptación. El resultado es que la IA genera código más acertado, con menos iteraciones de corrección y menor riesgo de alucinaciones. El principio "gold in, gold out" se aplica directamente: más calidad en la spec → más calidad en el código generado. Herramientas como Claude Code, Cursor o GitHub Copilot obtienen un rendimiento significativamente mejor cuando el ticket tiene criterios de aceptación explícitos.
La IA puede asistir en la creación de la spec: sugiriendo edge cases que el equipo no había contemplado, completando criterios de aceptación, generando diagramas de flujo y calculando estimaciones de complejidad. Sin embargo, la responsabilidad de validar y aprobar la spec sigue siendo humana. El equipo de producto, el tech lead y diseño deben revisar y consensuar el documento antes de que pase a implementación. La IA como asistente de redacción de specs es poderosa; como única autora de specs, es arriesgada.
SDD escala en ambas direcciones. Para proyectos pequeños, una spec puede ser tan simple como un documento de una página con los criterios de aceptación y los edge cases. Para proyectos grandes, la spec puede incluir arquitectura completa, diagramas de secuencia, contratos OpenAPI y matrices de permisos. La clave no es la extensión del documento, sino que exista un acuerdo explícito sobre qué se va a construir antes de construirlo. Una spec de cinco párrafos consensuada por el equipo es infinitamente más valiosa que ninguna spec.
"No Spec, No Code" es la regla fundacional del SDD: ningún ticket de desarrollo puede pasar a la fase de implementación sin una especificación aprobada. Aplicarlo requiere disciplina de equipo, especialmente bajo presión de entrega. La inversión en la spec al principio se recupera con creces al reducir retrabajos, malentendidos y bugs que llegan a producción por falta de claridad en los requisitos. Equipos que adoptan esta regla durante tres meses reportan sistemáticamente una reducción del 40-60% en el tiempo de revisión de PRs.
SDD encaja de forma natural en el proceso de grooming o refinamiento de Scrum: es en esa ceremonia donde se escriben y validan las specs antes del sprint. En Kanban, la spec se crea y aprueba antes de mover el ticket a "In Progress". SDD no reemplaza las ceremonias ágiles, sino que eleva la calidad del input que entra a cada sprint o iteración, haciendo que la fase de desarrollo sea más predecible y menos caótica. El SDD también reduce la dependencia de la memoria individual: si un desarrollador enferma o cambia de proyecto, la spec contiene todo el conocimiento necesario para que otra persona (o un agente de IA) continúe.
Las herramientas más comunes en un flujo SDD son: Jira o Linear para la gestión de tickets enriquecidos con criterios de aceptación; OpenAPI / Swagger para la especificación de contratos de API (API-first); Miro o Lucidchart para diagramas de flujo y arquitectura; Claude Code o Cursor como herramientas de implementación guiada por la spec; Confluence o Notion para documentación de alto nivel; y archivos CLAUDE.md o AGENTS.md en el repositorio para persistir el contexto del proyecto. La herramienta específica importa menos que el hábito de documentar primero.
Los errores más frecuentes son: (1) Escribir specs demasiado genéricas que dejan margen de ambigüedad — "el sistema validará los datos" no es un criterio de aceptación; (2) No actualizar la spec cuando el alcance cambia durante el desarrollo, lo que crea discrepancias entre lo documentado y lo implementado; (3) Tratar la spec como un trámite burocrático en lugar de una herramienta de alineamiento real del equipo; (4) Omitir los edge cases y los casos de error, que son exactamente donde los bugs más críticos aparecen; (5) Crear specs sin validación de todos los stakeholders. Una spec aprobada solo por el desarrollador es equivalente a ninguna spec.
¿Quieres implementar SDD en tu equipo?
En Kuuli Technologies aplicamos SDD en todos nuestros proyectos. Contáctanos si quieres que te ayudemos a adoptar esta metodología con herramientas de IA generativa en tu stack.