Introduccion a BMAD y SDD
El problema: IA sin rumbo
Todos hemos experimentado esto: le pides a una IA que construya algo, genera codigo que parece funcionar, pero a las pocas iteraciones pierde el contexto, alucina dependencias inexistentes o contradice decisiones anteriores. El resultado es un codebase fragil que nadie entiende.
Los problemas principales son:
- Alucinaciones acumulativas: cada iteracion introduce errores sutiles que se propagan
- Perdida de contexto: la IA olvida decisiones tomadas hace 3 prompts
- Codigo sin arquitectura: funciona hoy, es inmantenible manana
- Cero trazabilidad: no hay forma de saber por que se tomo una decision
Que es Spec-Driven Development (SDD)
SDD es un paradigma donde las especificaciones escritas son la fuente de verdad del proyecto. En lugar de ir directo al codigo, primero se crean documentos que describen que construir, como y por que.
La IA no inventa: ejecuta lo que las specs dictaminan. Si la spec dice “usar PostgreSQL con 3 tablas”, la IA no va a generar MongoDB con 12 colecciones.
Principios de SDD
- Specs antes que codigo: ningun codigo se escribe sin una spec aprobada
- Specs versionadas: los documentos viven en Git junto al codigo
- Specs como contrato: si la spec no lo dice, no se implementa
- Iteracion sobre specs: es mas barato cambiar un documento que refactorizar codigo
Que es BMAD
BMAD (Breakthrough Method for Agile AI-Driven Development) es un framework open source que implementa SDD simulando un equipo agil completo con agentes IA especializados.
Fue creado por la comunidad bmad-code-org y se instala como paquete npm. Su filosofia es que cada fase del desarrollo necesita un “experto” distinto, no un generalista.
Filosofia central
“No le pidas a un solo agente que sea analista, arquitecto, developer y QA a la vez. Dale a cada rol su propio contexto, instrucciones y artefactos.”
BMAD logra esto con archivos .md que definen el comportamiento de cada agente. Cuando activas un agente en tu IDE, este “carga” su personalidad, conocimiento y restricciones.
Comparativa: BMAD vs Spec-Kit vs OpenSpec
| Aspecto | BMAD | GitHub Spec-Kit | OpenSpec |
|---|---|---|---|
| Filosofia | Equipo agil completo con agentes IA | Specs como PRs en GitHub | Gestion de cambios incremental |
| Setup time | ~2 min (npx install) | ~5 min (init + GitHub) | ~3 min (init) |
| Ideal para | Proyectos greenfield complejos | Equipos ya en GitHub | Codebases existentes |
| Complejidad | Alta (6 agentes, multiples workflows) | Media (3 archivos core) | Baja (change requests) |
| Agentes IA | 6 roles especializados | No tiene agentes | No tiene agentes |
| Artefactos | 8+ documentos generados | 3 specs versionadas | Specs + change requests |
| Repo | github.com/bmad-code-org | github.com/github/spec-kit | github.com/openspec-org |
BMAD destaca cuando necesitas estructura completa desde cero. Si ya tienes un codebase y solo quieres gestionar cambios, OpenSpec es mas ligero. Si tu equipo vive en GitHub, Spec-Kit integra nativamente.
Los 6 agentes de BMAD
BMAD simula un equipo agil donde cada miembro tiene responsabilidades claras:
| Agente | Alias | Fase | Funcion principal |
|---|---|---|---|
| Analyst | Vision Crystallizer | Brainstorming | Transforma ideas vagas en un Product Brief claro |
| Product Manager | Requirements Architect | Requisitos | Genera PRD detallado con user stories y criterios |
| Architect | Technical Visionary | Arquitectura | Define stack, schemas, APIs y diagramas tecnicos |
| Scrum Master | Story Crafter | Planning | Fragmenta el PRD en stories atomicas implementables |
| Developer | IDE Agent | Implementacion | Escribe codigo siguiendo specs al pie de la letra |
| QA | Quality Guardian | Validacion | Revisa codigo, edge cases y cobertura de tests |
Flujo de artefactos entre agentes
Cada agente consume los artefactos del anterior y produce los suyos:
flowchart TD
A["Analyst"] -->|product-brief.md| B["Product Manager"]
B -->|PRD.md + user stories| C["Architect"]
C -->|ARCHITECTURE.md, db-schema.md, api-spec.json| D["Scrum Master"]
D -->|story-001.md, story-002.md...| E["Developer"]
E -->|Codigo implementado por story| F["QA"]
F -->|Reporte de calidad + issues| G(("Entrega"))Las 4 fases macro
Aunque hay 6 agentes, BMAD organiza el trabajo en 4 macro-fases:
1. Analysis (Analyst)
El Analyst te hace preguntas sobre tu idea, identifica riesgos y genera el Product Brief: un documento de 1-2 paginas que cristaliza la vision del proyecto.
2. Planning (Product Manager)
El PM toma el brief y lo expande en un PRD (Product Requirements Document) completo: epicas, user stories con criterios de aceptacion, prioridades y metricas de exito.
3. Solutioning (Architect)
El Architect traduce los requisitos en decisiones tecnicas: que stack usar, como estructurar la base de datos, que endpoints exponer y como se comunican los componentes.
4. Implementation (Scrum Master + Developer + QA)
El Scrum Master fragmenta la arquitectura en stories atomicas (Context Sharding). El Developer implementa story por story. El QA valida cada entrega.
Por que un Kanban como proyecto
Elegimos un tablero Kanban porque tiene la complejidad justa para ejercitar todas las fases de BMAD:
- CRUD completo: crear, leer, actualizar y eliminar tareas y columnas
- Drag & drop: interaccion rica que requiere decisiones de frontend
- Autenticacion: login/registro que toca seguridad y base de datos
- Tiempo real: actualizaciones live que requieren decisiones de infraestructura (WebSockets, SSE, polling)
- Multiples usuarios: tableros compartidos que involucran permisos y roles
No es tan simple como un TODO list (que no ejercitaria la fase de arquitectura) ni tan complejo como un ERP (que tomaria semanas solo en requisitos).
Requisitos previos
Antes de empezar necesitas:
- Node.js 20+: BMAD se instala via npx
- IDE agentico: Claude Code, Cursor, Windsurf u otro que soporte agentes IA
- Git: para versionar specs y codigo juntos
- Terminal: comodidad basica con linea de comandos
No necesitas experiencia previa con BMAD ni con SDD. El tutorial asume que sabes programar pero que es tu primera vez con desarrollo guiado por agentes.
Que aprenderas
Al terminar este tutorial tendras:
- Comprension solida de SDD y por que importa
- Experiencia practica con los 6 agentes de BMAD
- Un proyecto Kanban con specs completas versionadas
- Criterio para decidir cuando usar BMAD, Spec-Kit u OpenSpec
- Patrones reutilizables para tus propios proyectos
← Indice | Siguiente → Capitulo 2: Instalacion y Estructura