refactor: complete bootstrap of ARNES agent harness framework
- Add complete agent harness structure with 8 roles (leader, triager, architect, implementer, reviewer, security, qa, documenter) - Implement strict workflow with 9 stages and mandatory gates - Add comprehensive verification script and runtime status tracking - Create artifact-based evidence system with contracts and schemas - Add agent policy matrix with permissions and anti-cheat rules - Include test suite (44 tests passing) and CI-ready structure - Add documentation: README, HOWTO, CHECKPOINTS, templates - Configure model routing policies and token-aware task assignment - Add BDD/SDD specification guides and feature templates - Include starter pack for quick project onboarding All verification checks pass. Framework ready for production use.
This commit is contained in:
rikrdo
303
spec/sdd-bdd-guide.md
Normal file
303
spec/sdd-bdd-guide.md
Normal file
@@ -0,0 +1,303 @@
|
||||
# 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
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### 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
|
||||
features/
|
||||
├── login.feature
|
||||
└── steps/
|
||||
└── login_steps.py
|
||||
|
||||
# Ejecutar
|
||||
behave features/
|
||||
```
|
||||
|
||||
### Ejemplo: Node.js Cucumber
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```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/)
|
||||
Reference in New Issue
Block a user