arnes/spec/sdd-bdd-guide.md

# 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
1. Definir arquitectura del sistema
2. Documentar componentes y sus responsabilidades
3. Registrar decisiones técnicas (ADRs)
4. Servir como fuente de verdad para `architect` y `implementer`

### 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

```markdown
# 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)

```markdown
# 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
1. Definir comportamiento del sistema en lenguaje de negocio
2. Crear trazabilidad entre requisitos y tests
3. Servir como especificación ejecutable para `implementer` y `qa`

### Formato: Gherkin

Usar sintaxis Gherkin para todos los features:

```gherkin
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

```gherkin
@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)

1. **Crear/actualizar SDD**
   - Definir componentes nuevos
   - Documentar decisiones técnicas
   - Crear ADRs cuando haya cambios

2. **Crear/actualizar BDD**
   - Traducir requisitos de `spec/product.md` a Gherkin
   - Crear scenarios para cada criterio de aceptación
   - Asegurar que cada scenario tenga link a `@F-XXX`

3. **Producir artefacto**
   - Archivo: `work/artifacts/<feature_id>/architect.md`
   - Contenido: resumen de cambios en SDD/BDD

### Stage: build (implementer)

1. **Implementar código** que cumpla los scenarios BDD
2. **Escribir tests** que ejecuten los scenarios
3. **Actualizar SDD** si hay cambios en componentes

### Stage: review_gate (reviewer)

1. **Verificar** que el código implementa lo documentado en SDD
2. **Verificar** que tests cubren los scenarios BDD
3. **Producir** `work/artifacts/<feature_id>/reviewer.json`

### Stage: qa_gate (qa)

1. **Ejecutar** tests BDD (feature files)
2. **Verificar** trazabilidad: todos los `@F-XXX` tienen tests
3. **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

```bash
# Estructura
spec/bdd/features/
└── login.feature

features/
└── steps/
    └── login_steps.py

# Ejecutar
behave features/
```

### Ejemplo: Node.js Cucumber

```bash
# 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-XXX` para trazabilidad con backlog
- [ ] Scenarios son atómicos (no dependen de estado previo)

---

## 🚫 Reglas anti-trampa

1. **SDD no es decoration**: debe reflejar la realidad del código
2. **BDD no es documentación de tests**: es especificación executable
3. **Discrepancia = bug**: si SDD dice A pero código hace B, el código está mal
4. **Sin scenario = sin acceptance**: feature sin BDD scenario no puede cerrarse

---

## 📝 Formato de artefacto architect.md

```markdown
# 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
```

---

## 🔗 Referencias

- [Gherkin Reference](https://cucumber.io/docs/gherkin/)
- [MADR (Markdown Any Decision Records)](https://adr.github.io/madr/)
- [BDD with Behave](https://behave.readthedocs.io/)