Spec-driven development: cómo recuperar el control cuando la IA escribe el código

Imagen: IBM — What is spec-driven development?. Reproducida bajo fair use con fines de comentario crítico.

Spec-driven development (SDD) es una metodología de software donde una especificación detallada de los detalles de implementación se redacta y acuerda antes de empezar a desarrollar. Sirve como una única fuente de verdad sobre qué construir y cómo construirlo. Con la accesibilidad de coding agents como GitHub Copilot, Claude Code o IBM Bob, la generación de código dejó de ser el cuello de botella — y el cuello de botella pasó a ser la calidad de las instrucciones que recibe el modelo.

IBM publicó en su IBM Think un overview que vale la pena recorrer porque ordena por primera vez, en un solo lugar, los tres niveles del espectro SDD y cuándo conviene cada uno.

Lo que pasó

IBM Think publicó un artículo que define SDD como metodología, la separa explícitamente del vibe coding y propone tres niveles en un espectro de menor a mayor automatización. Lo notable del artículo es que no presenta SDD como una única práctica sino como un rango con tradeoffs reales:

• Spec-first. La spec se redacta antes del código (user story, acceptance criteria, requirements document). Una vez que el código se genera, la spec no se mantiene necesariamente. Es el “entry point a SDD”.
• Spec-anchored. La spec evoluciona junto al software. Tests automatizados hacen de puente entre documentación e implementación, integrados en CI/CD. Es el más práctico para la mayoría de los equipos de ingeniería.
• Spec-as-source. Cambios en la spec disparan cambios en el código automáticamente. Nadie refactorea el código directamente. Requiere alta confianza en el pipeline de generación de IA, que sigue siendo inherentemente no-determinístico.

El artículo también introduce el concepto de hybrid approaches: specs como ADRs (architecture decision records), o tratar al issue tracker como fuente de verdad en lugar del archivo SPEC.md.

Por qué importa para quien desarrolla con IA

El argumento central del artículo es directo: la IA es tan buena como las instrucciones que recibe. Sin una spec que ancle la generación, el código que produce el agente puede:

• Generar context drift. Un fix en un área rompe funcionalidad en otra porque el código se escribió sin comprensión global del sistema.
• Fragmentar convenciones. Features nuevas no se alinean con la arquitectura existente, erosionando consistencia y mantenibilidad.
• Disparar costo operacional. Sin una spec clara, el ciclo de prompting se alarga consumiendo miles de tokens para resolver errores que una spec bien definida habría prevenido desde el inicio.

Es la versión moderna del technical debt, acelerada por la facilidad de generar código sin entenderlo o validarlo. SDD ataca este problema de frente, poniendo el punto de gravedad del proyecto en la spec, no en el código generado.

El espectro: cuándo conviene cada nivel

Spec-first — para empezar y para features cortas

Sirve como entrada al mundo SDD sin compromiso de mantenimiento. Útil cuando:

• La feature es chica y bien acotada.
• El equipo todavía no adoptó prácticas de mantenimiento de specs.
• Es un prototipo que probablemente se descartará.

Limitación: la spec se desactualiza apenas el código diverge de lo escrito. Después de un mes, el SPEC.md ya no refleja la realidad del sistema. Para producción con vida útil > 1 trimestre, queda corto.

Spec-anchored — el nivel pragmático

La spec evoluciona con el software. Los tests automatizados (unitarios, integración, e2e) son la fuente ejecutable de verdad: si pasan, la implementación cumple lo que la spec promete.

Funciona especialmente bien cuando:

• El proyecto sirve a una iniciativa más grande y hay múltiples engineers tocando el código.
• Se tiene CI/CD bien configurado que puede correr tests en cada cambio de spec.
• El equipo necesita documentación viva, no archivos PDF olvidados en Confluence.

Limitación: requiere disciplina. Si nadie actualiza la spec cuando cambia el comportamiento, vuelve al problema de la spec obsoleta. La diferencia con spec-first es que acá la intención es mantenerla viva; en spec-first, no.

Spec-as-source — para sistemas donde la IA es la implementación

El código es una proyección de la spec. Cambios en el SPEC.md se traducen en cambios en el código a través de un pipeline de generación. No hay humanos refactoreando directamente.

Único viable cuando:

• El pipeline de generación tiene suficiente confianza y cobertura de tests.
• El sistema es lo suficientemente acotado como para que la spec lo describa completo.
• Hay presupuesto para invertir en el “spec kit” (DSL o framework para escribir specs que el pipeline entienda).

Riesgo: la generación sigue siendo no-determinística. Sin supervisión humana fuerte, un cambio en la spec puede generar código que pasa los tests formales pero rompe assumptions implícitas. IBM recomienda evaluar la madurez del stack, la criticidad del sistema y la capacidad de validar output de IA antes de adoptarlo.

Cómo escribir una buena spec

El artículo da un ejemplo concreto de spec para una feature de login. La estructura que mejor funciona combina cinco secciones:

FEATURE: User Login

OVERVIEW:
  Allow registered users to authenticate securely using
  their email address and password.

ACCEPTANCE CRITERIA:
  1. The login form must accept email and password
  2. If credentials are valid, redirect to dashboard
  3. If credentials are invalid, display a generic error
     without specifying which field is incorrect
  4. Lock the account 15 min after 5 consecutive failures
  5. Transmit passwords over HTTPS only — never store plaintext

OUT OF SCOPE:
  - Social login (OAuth)
  - Two-factor authentication
  - Password reset flow

EDGE CASES:
  - Catch empty fields client-side before submission
  - Redirect expired sessions to login with an informational message
  - The form must remain functional if JavaScript is disabled

Lo que la spec debería tener:

• Input/output definitions. Qué recibe el sistema, qué devuelve.
• Data schema. Forma de los datos, no implementación interna.
• Edge cases. Lo que pasa cuando algo sale de lo esperado.
• Success criteria. Cómo se mide que la feature está terminada.

Lo que la spec NO debería tener:

• Decisiones de implementación que se toman después (frameworks específicos, ORM vs SQL raw, etc.).
• Detalle exhaustivo de cada branch condicional.
• Información que el agente puede inferir del contexto del proyecto (convenciones de naming, estructura de carpetas, etc.).

La regla de oro que da IBM: si la spec no ayuda a escribir mejor código más rápido, probablemente es más detallada de lo necesario. El costo de refinar la spec siempre tiene que ser menor que el costo de fixing misunderstandings en la implementación. Cuando esa relación se invierte, es señal de que es momento de parar de pulir y empezar a construir.

Trampas comunes

Sobre-especificar. “Si pasás tres semanas debatiendo el nombre de una sola JSON key o los endpoints específicos de una feature que probablemente se va a borrar en un mes, estás derrotando el propósito de SDD.” La spec es un punto de partida, no un contrato legal inmutable.

Tratar la spec como documentación, no como código. Si la spec vive en un wiki separado del repo, se desactualiza el día que el primer commit no la modifique. La spec debe estar versionada junto al código (un SPEC.md o docs/<feature>.md en el mismo repo, commiteado, revisado en PRs).

Asumir que más detalle = más calidad. Una spec detallada que nadie lee es peor que una spec corta que todos internalizan. La estructura de 5 secciones (FEATURE / OVERVIEW / ACCEPTANCE CRITERIA / OUT OF SCOPE / EDGE CASES) es deliberadamente corta para que se use.

Olvidar el out-of-scope. Tan importante como saber qué tiene que hacer la feature es saber qué no tiene que hacer. Una spec sin “OUT OF SCOPE” deja al agente con criterio propio para expandir, que es exactamente lo que SDD intenta evitar.

Cómo se conecta con coding agents concretos

La elección de IBM Think como fuente para este post no es casual — el artículo describe con bastante precisión el workflow que adoptan varios setups modernos de coding agents. Implementaciones concretas del approach:

• GitHub Spec-Kit (github/spec-kit): toolkit open source de GitHub para SDD con instrucciones, templates y prompts. Es probablemente la implementación más referenciada del momento.
• Anthropic Claude Code con archivos SPEC.md o docs/<feature>.md versionados: el agente los lee del directorio del proyecto o el usuario los pega en el prompt.
• Frameworks de orchestration que separan explícitamente el rol de “spec author” del “implementer”: un agente (Claude Code, por ejemplo) escribe la spec, otro (Codex, por ejemplo) la implementa. La spec es el contrato entre los dos.

El denominador común: la spec vive en el repo, versionada, y el agente la lee en lugar de inventar los requisitos.

Lo que conviene recordar

• SDD no es vibe coding con más palabras. Es la disciplina de poner el punto de gravedad del proyecto en la spec, no en el código generado.
• El espectro (spec-first / spec-anchored / spec-as-source) es un menú, no una escalera. Cada equipo elige el nivel según codebase, equipo y problema.
• Una buena spec acelera el desarrollo; una mala spec lo frena. La estructura de 5 secciones (FEATURE / OVERVIEW / ACCEPTANCE CRITERIA / OUT OF SCOPE / EDGE CASES) es un buen default.
• La spec vive en el repo, no en un wiki. Versionada junto al código, revisada en PRs, ejecutada a través de tests automatizados.

Fuente

• What is spec-driven development? — IBM Think, contenido editorial oficial de IBM.
• Implementación concreta: GitHub Spec-Kit (open source toolkit de GitHub para SDD).
• Contexto histórico: Test-driven development y Behavior-driven development como precursores.