7.1 KiB
7.1 KiB
SDD/BDD Guide — System Design Document & Behavior Driven Development
Guía para crear y mantener SDD (System Design Document) y BDD (Behavior Driven Development) specs dentro del framework ARNES.
📐 Propósito
- SDD: Documenta el diseño técnico del sistema (arquitectura, componentes, decisiones).
- BDD: Documenta el comportamiento esperado desde la perspectiva del usuario/negocio.
Ambos alimentan el pipeline de agentes y se versionan junto con el código.
🔗 Relación con ARNES
spec/
├── product.md # Qué construir (negocio)
├── tech.md # Stack y decisiones técnicas
├── acceptance.md # Criterios de aceptación (BDD light)
├── sdd/ # System Design Document
│ ├── README.md
│ ├── architecture.md
│ ├── components/
│ └── decisions/
└── bdd/ # Behavior Driven Development source-of-truth
├── README.md
└── features/
features/ # optional executable BDD runner assets
├── behave.ini
└── steps/
📋 SDD — System Design Document
Objetivos
- Definir arquitectura del sistema
- Documentar componentes y sus responsabilidades
- Registrar decisiones técnicas (ADRs)
- Servir como fuente de verdad para
architectyimplementer
Estructura de un SDD
spec/sdd/
├── README.md # Índice y overview
├── architecture.md # Vista general (contexto, capas)
├── components/ # Componentes individuales
│ ├── component-name.md
│ └── ...
└── decisions/ # Architecture Decision Records
├── 001-decision-title.md
└── ...
Template: component.md
# Componente: <Nombre>
## Responsabilidad
Descripción clara de qué hace este componente.
## Interfaces
- **Entrada**: API, eventos, mensajes
- **Salida**: Respuestas, side effects
## Dependencias
- Servicio A (tipo de dependencia)
- Base de datos B
## Límites
- Qué NO hace este componente
- Restricciones conocidas
## Criterios de éxito
- [ ] Mecanismo de verificación
- [ ] Métrica de performance
Template: ADR (Architecture Decision Record)
# ADR-XXX: <Título>
## Estado
Aceptado | Deprecado | Propuesto
## Contexto
Problema que motiva esta decisión.
## Decisión
Qué se decidió y por qué.
## Consecuencias
- ✅ Positivos
- ❌ Negativos
## Alternativas consideradas
1. Opción A - razón de descarte
2. Opción B - razón de descarte
## Fecha
YYYY-MM-DD
🎯 BDD — Behavior Driven Development
Objetivos
- Definir comportamiento del sistema en lenguaje de negocio
- Crear trazabilidad entre requisitos y tests
- Servir como especificación ejecutable para
implementeryqa
Formato: Gherkin
Usar sintaxis Gherkin para todos los features:
Feature: <Nombre del feature>
Como <actor>
Quiero <acción>
Para <beneficio>
Scenario: <escenario positivo>
Given <contexto inicial>
And <más contexto>
When <acción del usuario>
And <otra acción>
Then <resultado esperado>
And <otro resultado>
Scenario: <escenario negativo>
Given <contexto>
When <acción que falla>
Then <error esperado>
Estructura de un Feature BDD
spec/bdd/features/
├── README.md
├── auth/
│ ├── login.feature
│ └── registration.feature
├── checkout/
│ └── purchase.feature
└── common/
└── error-handling.feature
features/
├── behave.ini
└── steps/
└── login_steps.py
Tags para trazabilidad
@F-001 @auth @smoke
Feature: Inicio de sesión
@regression @slow
Scenario: Login con credenciales válidas
...
Tags disponibles:
@F-XXX— Link a feature ID del backlog@smoke— Test crítico (ejecutar siempre)@regression— Tests de regresión@integration— Tests de integración@e2e— End-to-end tests
🔄 Flujo de trabajo SDD/BDD en ARNES
Stage: design (architect)
-
Crear/actualizar SDD
- Definir componentes nuevos
- Documentar decisiones técnicas
- Crear ADRs cuando haya cambios
-
Crear/actualizar BDD
- Traducir requisitos de
spec/product.mda Gherkin - Crear scenarios para cada criterio de aceptación
- Asegurar que cada scenario tenga link a
@F-XXX
- Traducir requisitos de
-
Producir artefacto
- Archivo:
work/artifacts/<feature_id>/architect.md - Contenido: resumen de cambios en SDD/BDD
- Archivo:
Stage: build (implementer)
- Implementar código que cumpla los scenarios BDD
- Escribir tests que ejecuten los scenarios
- Actualizar SDD si hay cambios en componentes
Stage: review_gate (reviewer)
- Verificar que el código implementa lo documentado en SDD
- Verificar que tests cubren los scenarios BDD
- Producir
work/artifacts/<feature_id>/reviewer.json
Stage: qa_gate (qa)
- Ejecutar tests BDD (feature files)
- Verificar trazabilidad: todos los
@F-XXXtienen tests - Producir
work/artifacts/<feature_id>/qa.json
🛠 Herramientas recomendadas
| Propósito | Herramienta | Notas |
|---|---|---|
| BDD test runner | Behave (Python) / Cucumber (JS/Java) | Ejecuta .feature files |
| SDD docs | Markdown + Mermaid diagrams | Portable y versionable |
| ADRs | adr-tools o manual | Mantener en decisions/ |
Ejemplo: Python Behave
# Estructura
spec/bdd/features/
└── login.feature
features/
└── steps/
└── login_steps.py
# Ejecutar
behave features/
Ejemplo: Node.js Cucumber
# Estructura
spec/bdd/features/
└── login.feature
features/
└── step_definitions/
└── login_steps.js
# Ejecutar
npx cucumber-js features/
📊 Checklist de calidad SDD/BDD
SDD Quality
- Cada componente tiene responsabilidad clara
- Interfaces están documentadas
- ADRs para decisiones importantes
- Diagramas Mermaid para arquitectura
BDD Quality
- Cada feature tiene al menos un scenario
- Todos los scenarios usan Given/When/Then
- Tags
@F-XXXpara trazabilidad con backlog - Scenarios son atómicos (no dependen de estado previo)
🚫 Reglas anti-trampa
- SDD no es decoration: debe reflejar la realidad del código
- BDD no es documentación de tests: es especificación executable
- Discrepancia = bug: si SDD dice A pero código hace B, el código está mal
- Sin scenario = sin acceptance: feature sin BDD scenario no puede cerrarse
📝 Formato de artefacto architect.md
# Architect Artefact — Feature: F-XXX
## SDD Changes
- Componentes afectados: [...]
- ADRs creados/actualizados: [...]
## BDD Coverage
- Features/Scenarios nuevos: [...]
- Coverage: X/Y scenarios cubiertos por tests
## Decisiones técnicas
- Decisión 1: razón
- Decisión 2: razón
## Riesgos identificados
- Riesgo 1: mitigación