Mohit Aggarwal 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