technical-spec-template

Skill de Plantilla de Especificación Técnica

Escribe especificaciones técnicas que los ingenieros realmente lean — framing claro del problema, requisitos inequívocos, decisiones explícitas y compensaciones documentadas.

Entradas Requeridas

Pregunta al usuario por estos datos si no se proporcionan:

• Descripción de funcionalidad o sistema (qué necesita especificarse)
• PRD o brief de producto relacionado (si está disponible)
• Revisores de ingeniería (cuya aprobación es necesaria)
• Restricciones conocidas (limitaciones técnicas, requisitos de seguridad, objetivos de rendimiento)

Cuándo Escribir una Especificación Técnica

Escribe una especificación técnica cuando:

• La funcionalidad requiere cambios en 2+ sistemas
• Hay decisiones arquitectónicas significativas que tomar
• Más de un ingeniero trabajará en la implementación
• La funcionalidad tiene implicaciones de seguridad, privacidad o cumplimiento
• El esfuerzo estimado es >5 story points

Sáltate la especificación para correcciones de bugs triviales o cambios de 1-2 horas.

---

Formato de Salida de Especificación Técnica

Especificación Técnica — [Nombre de Funcionalidad]

Autor: [Nombre]

Estado: Borrador | En Revisión | Aprobado | Implementado

Creado: [Fecha] | Última Actualización: [Fecha]

Revisores: [Líder de Ing., Arquitecto, PM, Seguridad si es necesario]

PRD Relacionado: [Enlace] | Epic de Jira: [Enlace]

---

1. Declaración del Problema

> [2–3 oraciones. ¿Qué problema estamos resolviendo y por qué ahora? Sin lenguaje de solución aquí.]

2. Objetivos y No-Objetivos

Objetivos (en alcance):

• [Resultado específico y medible]
• [Resultado específico y medible]

No-Objetivos (explícitamente fuera de alcance):

• [Qué esta especificación NO cubre]
• [Suposición común a descartar tempranamente]

3. Antecedentes y Contexto

[Cualquier trabajo previo, sistemas relacionados, o contexto que los ingenieros necesitan para entender el espacio de decisión. Enlaza a especificaciones previas, ADRs, o investigación.]

4. Solución Propuesta

Enfoque de Alto Nivel:

[2–4 oraciones describiendo la solución elegida. ¿Por qué este enfoque vs alternativas?]

Diagrama de Arquitectura del Sistema:

[Describe o incrusta: qué servicios están involucrados, cómo fluyen los datos, qué APIs se llaman]

Cambios del Modelo de Datos:

-- Nuevas tablas o cambios de esquema
[Incluye DDL o definición de esquema]

Diseño de API:

[Endpoint] [Método]
Solicitud: { [campos y tipos] }
Respuesta: { [campos y tipos] }
Códigos de error: [lista]

Detalles Clave de Implementación:

• [Restricción técnica importante o enfoque]
• [Manejo de casos especiales]
• [Dependencia de terceros y versión]

5. Enfoques Alternativos Considerados

| Opción | Pros | Contras | Por Qué Rechazado |

|---|---|---|---|

| [Alt 1] | [Beneficios] | [Desventajas] | [Razón no elegida] |

| [Alt 2] | [Beneficios] | [Desventajas] | [Razón no elegida] |

6. Consideraciones de Seguridad y Privacidad

• Datos almacenados: [Qué datos PII o sensibles están involucrados]
• Autenticación: [Cómo se controla el acceso]
• Autorización: [Qué permisos se requieren]
• Cifrado: [Requisitos en reposo / en tránsito]
• Implicaciones de cumplimiento: [GDPR, SOC2, etc. si es relevante]

7. Rendimiento y Escalabilidad

• Carga esperada: [Solicitudes/segundo, volumen de datos]
• Requisitos de latencia: [Objetivos P50 / P95]
• Estrategia de caché: [Si es aplicable]
• Indexación de base de datos: [Nuevos índices requeridos]
• Cuellos de botella conocidos: [Dónde estar atento]

8. Plan de Pruebas

• Pruebas unitarias: [Escenarios clave a cubrir]
• Pruebas de integración: [Límites del sistema a probar]
• Pruebas de carga: [Si es crítico para el rendimiento]
• Casos especiales: [Escenarios conocidos complicados]
• Plan de reversión: [Cómo revertir si algo sale mal]

9. Plan de Despliegue

• Feature flag: [Sí / No — nombre del flag]
• Etapas de despliegue: [% de usuarios en cada etapa]
• Monitoreo: [Métricas y alertas a configurar]
• Criterios de éxito para progresar en el despliegue: [Qué debe ser verdadero]
• Disparador de reversión: [Qué causaría reversión inmediata]

10. Preguntas Abiertas

| Pregunta | Propietario | Fecha Vencimiento | Resolución |

|---|---|---|---|

| [Pregunta sin resolver] | [Nombre] | [Fecha] | [Pendiente] |

11. Cronograma de Implementación (Aproximado)

| Fase | Trabajo | Esfuerzo Estimado |

|---|---|---|

| [Fase 1] | [Qué se construye] | [X días/points] |

| [Fase 2] | [Qué se construye] | [X días/points] |

| Total | | [X story points] |

---

Pautas

• La especificación es un registro de decisiones, no una lista de tareas — documenta por qué se tomaron las decisiones
• Todas las preguntas abiertas deben tener un propietario y fecha de vencimiento
• Las secciones de seguridad y privacidad nunca son opcionales para funcionalidades que tocan datos de usuario
• Recomenda revisión asincrónica: los ingenieros leen primero, luego una sincronización de 30 minutos para resolver preguntas
• Mantén la especificación actualizada según avanza la implementación — las especificaciones obsoletas son peores que ninguna especificación

Verificaciones de Calidad

• [ ] La declaración del problema no contiene lenguaje de solución
• [ ] Los no-objetivos enumeran explícitamente al menos 2 cosas que podrían asumirse dentro del alcance
• [ ] Al menos 2 enfoques alternativos se documentan con razones de rechazo
• [ ] La sección de seguridad y privacidad se completa para cualquier funcionalidad que toque datos de usuario
• [ ] Todas las preguntas abiertas tienen un propietario designado y fecha de vencimiento (no "Por Definir")

Anti-Patrones

• [ ] No incluyas lenguaje de solución en la declaración del problema — el problema debe describirse independientemente de la solución propuesta
• [ ] No omitas alternativas consideradas — una especificación que considera solo un enfoque no ha sido adecuadamente evaluada
• [ ] No dejes preguntas abiertas como "Por Definir" sin un propietario designado y fecha de vencimiento — las preguntas sin resolver son bloqueadores
• [ ] No saltes las secciones de seguridad y privacidad para ninguna funcionalidad que toque datos de usuario
• [ ] No escribas una sección de no-objetivos que esté vacía — siempre enumera al menos dos cosas que podrían asumirse dentro del alcance