Plantilla de Especificación Técnica

Visión general

Sin una especificación, los ingenieros rellenan huecos con suposiciones — y las suposiciones son lo que luego se convierte en expectativas desalineadas, casos extremos omitidos y retrabajo descubierto dos sprints demasiado tarde. Una especificación técnica traduce requisitos de producto en un plan implementable antes de escribir la primera línea de código.

Copia la plantilla de abajo, rellena los placeholders y mantenla por debajo de 10 páginas. Si crece más, divídela.

Cuándo usarla

Busca esta plantilla cuando:

• Inicias una capacidad que toca varios sistemas o equipos
• Propones un servicio, API o cambio arquitectónico importante
• Transfieres la implementación a otro ingeniero o equipo

Para arreglos de un solo archivo y features de una página, una issue de GitHub basta. Y si solo necesitas registrar una decisión de diseño concreta, eso es un ADR, no una spec (ver la plantilla de ADR).

Plantilla

# Especificación Técnica: `<Nombre de la Capacidad / Sistema>`

**Estado:** borrador | en-revisión | aprobada | implementada
**Autor:** @handle
**Última actualización:** AAAA-MM-DD

## 1. Objetivo

Un párrafo describiendo qué busca lograr esta especificación y por qué importa.

## 2. Contexto

- Estado actual del sistema
- ¿Qué problema estamos resolviendo?
- ¿Quiénes son los usuarios y stakeholders?
- Enlaces a requisitos de producto, historias de usuario o investigación de mercado

## 3. Objetivos y No-Objetivos

**Objetivos** (deben lograrse):
- [Objetivo 1]
- [Objetivo 2]

**No-Objetivos** (explícitamente fuera de alcance):
- [No-objetivo 1]
- [No-objetivo 2]

## 4. Requisitos

### Requisitos Funcionales

| ID | Requisito | Prioridad |
|----|-----------|-----------|
| FR-1 | El sistema debe... | P0 |
| FR-2 | El sistema debería... | P1 |

### Requisitos No Funcionales

| ID | Requisito | Objetivo |
|----|-----------|----------|
| NFR-1 | Latencia p95 | < 200ms |
| NFR-2 | Disponibilidad | 99.9% |
| NFR-3 | Throughput | 1,000 req/s |

## 5. Diseño

### Arquitectura

- Enlaces a diagramas C4 (Contexto, Contenedor, Componente)
- Enlace al mapa de dependencias de servicios
- Enlace al ADR para decisiones mayores

### Modelo de Datos

```sql
CREATE TABLE users (
  id UUID PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);
```

### Contrato de API

- Enlace a la especificación OpenAPI o contrato de microservicio
- Endpoints clave, ejemplos de request/response

### Diagrama de Secuencia

```mermaid
sequenceDiagram
  participant User
  participant API
  participant DB
  User->>API: POST /orders
  API->>DB: INSERT order
  DB-->>API: order_id
  API-->>User: 201 Created
```

## 6. Plan de Implementación

| Fase | Tarea | Responsable | ETA |
|------|-------|-------------|-----|
| 1 | Migración de esquema | @backend | Semana 1 |
| 2 | Implementación de API | @backend | Semana 2 |
| 3 | Integración frontend | @frontend | Semana 3 |
| 4 | Pruebas de carga | @qa | Semana 4 |

## 7. Estrategia de Pruebas

- Tests unitarios: objetivo de cobertura, estrategia de mocking
- Tests de integración: entornos, configuración de datos
- Tests E2E: flujos críticos de usuario
- Tests de rendimiento: perfil de carga, umbrales aceptables

## 8. Plan de Rollout

- Feature flags: qué flag, estado por defecto
- Período de estabilización en staging: duración, criterios de éxito
- Porcentaje de canary: 5% → 25% → 100%
- Criterios de rollback: tasa de error > X%, latencia > Yms

## 9. Riesgos y Mitigaciones

| Riesgo | Impacto | Probabilidad | Mitigación |
|--------|---------|--------------|------------|
| La migración de datos toma más tiempo de lo esperado | Alto | Media | Ejecutar migración por lotes, probar en copia de prod |
| Caída de API de terceros | Medio | Baja | Cachear respuestas, implementar circuit breaker |

## 10. Métricas de Éxito

- **Adopción**: X% de usuarios usan la capacidad en 30 días
- **Rendimiento**: latencia p95 < objetivo
- **Fiabilidad**: tasa de error < 0.1%
- **Negocio**: impacto en ingresos, ahorro de costes

Explicación

La especificación separa el qué (requisitos) del cómo (diseño) y del cuándo (plan de implementación). Los objetivos y no-objetivos cortan el scope creep en la puerta. Los IDs de requisito hacen la cobertura de tests trazable — QA mapea FR-1 a casos de prueba, no a párrafos. La sección de diseño enlaza a documentos vivos (diagramas, contratos) en lugar de duplicarlos, así nada queda obsoleto en dos sitios a la vez. Y el plan de rollout fuerza la conversación de preparación para producción antes de codear, no durante el incidente.

Ejemplo: Sección de Requisitos Completa

## 4. Requisitos

### Requisitos Funcionales

| ID | Requisito | Prioridad |
|----|-----------|-----------|
| FR-1 | El sistema debe permitir a usuarios crear, leer, actualizar y eliminar órdenes | P0 |
| FR-2 | El sistema debe enviar confirmación por email al crear una orden | P1 |
| FR-3 | El sistema debería soportar importación masiva de órdenes vía CSV | P2 |
| FR-4 | El sistema debe aplicar control de acceso por roles (admin, manager, user) | P0 |

### Requisitos No Funcionales

| ID | Requisito | Objetivo |
|----|-----------|----------|
| NFR-1 | Latencia p95 para creación de órdenes | < 200ms |
| NFR-2 | Disponibilidad durante horario laboral | 99.9% |
| NFR-3 | Throughput pico | 1,000 req/s |
| NFR-4 | Durabilidad de datos | 99.999999% (11 nueves) |
| NFR-5 | Retención de logs de auditoría | 7 años |

Ejemplo: Configuración de Rollout con Feature Flags

feature_flags:
  - name: orders_v2_api
    description: "Nuevo pipeline de procesamiento de órdenes con validación asíncrona"
    default_state: off
    rollout_strategy: percentage
    rollout_steps:
      - percentage: 5
        duration: 24h
        success_criteria:
          error_rate: < 0.5%
          p95_latency: < 200ms
      - percentage: 25
        duration: 48h
        success_criteria:
          error_rate: < 0.5%
          p95_latency: < 200ms
      - percentage: 100
        duration: indefinite
    rollback_criteria:
      error_rate: > 1%
      p95_latency: > 500ms
    target_rules:
      - attribute: user_id
        operator: in
        values: [12345, 67890]  # Testers internos primero

Ejemplo: Plantilla de Evaluación de Riesgos

## 9. Riesgos y Mitigaciones

| Riesgo | Impacto | Probabilidad | Mitigación | Responsable |
|--------|---------|--------------|------------|-------------|
| La migración de datos toma más tiempo de lo esperado | Alto | Media | Ejecutar migración en lotes de 10k filas, probar en copia de prod | @dba |
| Caída de API de pagos de terceros | Alto | Baja | Cachear respuestas, implementar circuit breaker, encolar reintentos | @backend |
| Regresión de rendimiento en frontend | Medio | Media | Ejecutar Lighthouse CI en cada PR, bloquear merge si el score baja > 5 puntos | @frontend |
| Cambio de esquema bloquea la tabla | Alto | Baja | Usar herramienta de cambio online (gh-ost, pt-online-schema-change) | @dba |
| Nuevo contrato de API rompe clientes móviles | Alto | Media | Mantener compatibilidad v1 por 90 días, publicar actualización de SDK | @mobile |

Checklist de Revisión

Antes de circular la especificación para aprobación:

• Cada requisito funcional tiene un ID trazable (FR-x)
• Cada requisito no funcional tiene un objetivo medible
• Objetivos y no-objetivos están listados explícitamente
• La sección de diseño enlaza a diagramas, no a imágenes inline
• El plan de implementación tiene responsable y ETA para cada fase
• El plan de rollout incluye configuración de feature flags y criterios de rollback
• La tabla de riesgos incluye impacto, probabilidad y mitigación para cada riesgo
• Las métricas de éxito son cuantitativas y medibles
• La especificación tiene menos de 10 páginas (excluyendo apéndices)

Variantes

Contexto	Enfoque	Notas
Startup	Ligero (1-2 páginas)	Enfocarse en objetivos, boceto de diseño y rollout
Enterprise	Plantilla completa con aprobaciones	Requerir sign-off del comité de revisión arquitectónica
Open source	Formato RFC	Publicar para comentarios de la comunidad antes de implementar
Industria regulada	Agregar sección de compliance	Mapear requisitos a HIPAA, PCI-DSS o SOX
Cross-team	Agregar cronograma de dependencias	Mostrar qué equipos deben entregar qué y cuándo

Lo que funciona

• Mantenerla por debajo de 10 páginas; enlazar a documentos de detalle en lugar de incrustarlo todo.
• Dar un ID a cada requisito — sin él se rompe el mapeo de cobertura de tests.
• Revisarla con stakeholders antes de implementar, no durante.
• Actualizar la spec en el mismo PR que el cambio de código que la motivó.
• Guardar las specs en control de versiones junto al código que describen.
• Incluir un header de estado (borrador / en-revisión / aprobada / implementada) para que nadie implemente un borrador por error.
• Enlazar la spec en la descripción del PR — los revisores necesitan el “por qué” tanto como el “qué”.

Errores comunes

• Escribir la spec después de implementar. Eso es teatro de documentación, no planificación — y no puede atrapar los problemas de diseño que la spec existe para atrapar.
• Detalles de implementación en la sección de diseño. Los nombres de variables y rutas van en el PR, no en la spec.
• Omitir requisitos no funcionales. “Debería ser rápido” no es un objetivo; “p95 < 200ms” sí.
• Sin criterios de rollback. Decidirlos en medio del incidente es cómo un rollout pequeño se vuelve grande.
• Tratar la spec como inmutable. La implementación siempre descubre cosas — una spec que no se actualiza se convierte en mentirosa.
• Fases sin responsable. La difusión de responsabilidad es cómo fases de una semana se entregan en cinco.

Solución de problemas de specs

• La spec se atasca en revisión. Demasiado larga. Córtala al TL;DR + las secciones en debate, o divídela — los revisores aprueban 4 páginas, posponen 14.
• Spec aprobada y luego ignorada. Sin enlaces desde el trabajo real. Pon la URL de la spec en el épico, los tickets y cada PR de implementación.
• Los requisitos derivan sin que nadie lo note. Falta el header de estado o la spec está obsoleta. Actualiza la spec en el mismo PR que el cambio de código — misma regla que con los docs.
• La spec cubrió todo menos lo que rompió en prod. La tabla de riesgos era cosmética. Puntúa los riesgos con honestidad y pon responsable en los más graves.

Ver también

• Plantilla de ADR — para decisiones de diseño individuales
• Plantilla de contrato de microservicio — el contrato de API al que enlaza la spec
• Plantilla de diagrama de sistema — para la sección de arquitectura
• Guía de estrategia de documentación técnica — dónde encajan las specs en el cuadro general

Lectura adicional

• How to Write a Good Software Design Doc (freeCodeCamp)
• RFC 2119 — Niveles de requisito — el vocabulario MUST/SHOULD/MAY de las tablas de requisitos
• Design docs en eng-practices de Google — cómo funcionan los documentos de diseño a escala

Código complementario: el repo companion de la plantilla tiene esta plantilla como .md listo para copiar más una spec de ejemplo completamente rellenada.