arnes/spec/sdd-bdd-guide.md

SDD/BBD 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
    ├── README.md
    ├── features/
    └── step_definitions/

---

📋 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

# 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

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:

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

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)

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

# Estructura
features/
├── login.feature
└── steps/
    └── login_steps.py

# Ejecutar
behave features/

Ejemplo: Node.js Cucumber

# Estructura
features/
├── login.feature
└── 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

# 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
• MADR (Markdown Any Decision Records)
• BDD with Behave