Spec-Driven Development: Specs antes que Código
Poner la decisión de diseño por escrito antes de que se ejecute una sola línea de código, y cuándo vale la pena montar este framework en vez de trabajar con prompts sueltos.
El problema que resuelve
“Vibe-codear” con un agente anda bien en tareas chicas: describís un cambio, el agente lo escribe, revisás el resultado. El problema aparece cuando una feature toca muchos archivos a la vez — ahí la parte difícil deja de ser la implementación y pasa a ser la decisión de diseño, y esa decisión, tomada a los apurones en un prompt, es la que después se paga en bugs de edge cases no contemplados o en un scope que se corrió sin que nadie lo notara.
Spec-Driven Development (SDD) ataca ese problema poniendo la decisión de diseño por escrito, antes de que se ejecute una sola línea de código: escribís una spec corta que dice qué tiene que hacer el cambio, la convertís en un plan de tareas numeradas, y recién ahí el agente implementa siguiendo ese plan, con revisión humana entre paso y paso.
Anatomía típica de un flujo SDD
| Artefacto | Qué contiene |
|---|---|
| Constitution | Los principios de arquitectura del proyecto — el “ADN” contra el que se valida todo lo demás |
| Spec | Qué debe hacer el cambio, en términos funcionales, sin detalles de implementación |
| Plan | Cómo se va a construir: decisiones técnicas, arquitectura del cambio puntual |
| Tasks | Lista numerada y verificable, la unidad que el agente ejecuta de a una |
Dos frameworks de referencia
- Filosofía: artefactos portables entre agentes, pensado para revisión vía Pull Request.
- Instalación: CLI en Python (
uv tool install specify-cli). - Artefactos:
constitution.md,spec.md,plan.md,tasks.mdbajo.specify/yspecs/. - Comandos típicos:
/speckit.constitution,/speckit.specify,/speckit.plan,/speckit.tasks(agrega ~8 comandos en total). - Encaja mejor con: equipos que necesitan trazabilidad y donde varias personas (o varios agentes) tocan el mismo cambio.
- Filosofía: liviano, “in-tool”, pensado para no salir nunca del loop del agente.
- Instalación:
npm install -g @fission-ai/openspec— más simple si tu stack ya es Node. - Artefactos: propuestas y specs bajo
openspec/. - Comandos típicos:
/opsx:explorepara pensar la propuesta,/opsx:proposepara escribirla (agrega solo un puñado de comandos en total, bajo el prefijoopsx). - Encaja mejor con: un developer o equipo chico que quiere disciplina sin tanta ceremonia.
Ninguno de los dos se integra de forma nativa con Claude Code: generan los artefactos en disco, pero hay que indicarle explícitamente —a mano o desde CLAUDE.md— que los lea y trabaje a partir de ellos antes de tocar código. Es una convención de trabajo, no una feature de la herramienta.
Existen también alternativas más “pesadas” como BMAD-METHOD, que en vez de organizar artefactos organiza roles: divide el camino de la spec al código en fases, cada una ejecutada por un agente con un papel definido (analista, arquitecto, developer, QA).
¿Vale la pena para vos?
SDD tiene sentido cuando el costo de un malentendido de scope es alto: features que tocan varios servicios, equipos donde varias personas (humanas o agentes) trabajan en paralelo sobre el mismo dominio, o cambios donde “qué significa terminado” no es obvio a simple vista. Para un cambio chico en un proyecto solo tuyo, la estructura de 5 piezas de Prompting profesional (contexto, tarea, restricciones, formato, verificación) suele alcanzar sin necesidad de montar un framework aparte — la disciplina de escribir claro antes de codear es la misma disciplina que hace que el código generado por IA sea más confiable, con o sin un framework de por medio.
Una spec y un Architecture Decision Record resuelven problemas emparentados y no intercambiables: la spec dice qué hay que construir antes de construirlo; el ADR deja registro de por qué se eligió una opción y qué se descartó. Un flujo de spec-driven development sobre un sistema con decisiones arquitectónicas de fondo necesita los dos, y el ADR es el que sigue siendo útil dos años después.