De Requisitos a Especificaciones Técnicas
Las solicitudes de producto llegan como historias de usuario; los ingenieros entregan especificaciones técnicas: formas de API, modelos de datos, modos de fallo y planes de implementación. Una buena traducción evita "construir el botón" sin conocer las reglas de facturación, la idempotencia o los límites del servicio Python.
Receta
Tarjeta de receta de referencia rápida, lista para copiar y pegar.
# Especificación técnica: <característica>
## Problema / resultado del usuario
## Alcance (dentro) / No-objetivos (fuera)
## Esquema de API (rutas OpenAPI o eventos)
## Cambios en el modelo de datos (tablas, expansiones/contracciones de migraciones)
## Modos de fallo y reintentos
## Observabilidad (logs, métricas, alertas)
## Implementación (flag, canary) y reversión
## Pruebas de aceptación (Dado/Cuando/Entonces)
## Preguntas abiertas y picos (spikes)Cuándo usar esto:
- Los puntos de historia exceden un sprint
- Impacto inter-servicios o de esquema
- El PM pide una fecha antes de que ingeniería entienda la forma
- Toca cumplimiento o seguridad
Ejemplo de Trabajo
# Especificación técnica: Exportar facturas como PDF
## Problema
Los usuarios de finanzas necesitan facturas en PDF en exportación masiva (hasta 500/solicitud).
## No-objetivos
- Entrega por correo electrónico (épica separada)
- Marca personalizada por inquilino (fase 2)
## API
`POST /v1/invoices/export` → 202 + `job_id`
`GET /v1/jobs/{id}` → estado + URL de S3 cuando esté lista
## Datos
Leer `invoices`
# Modelos Pydantic de ejemplo que los revisores de especificaciones validan temprano
from pydantic import BaseModel
class ExportRequest(BaseModel):
invoice_ids: list[str]
max_count: int = 500
class JobStatus(BaseModel):
job_id: str
state: str
Lo que esto demuestra:
- Resultado del usuario declarado sin prescribir soluciones solo de UI
- Patrón de trabajo asíncrono elegido explícitamente para la pila Python
- Modos de fallo y criterios de aceptación son comprobables
- Los modelos con forma OpenAPI alinean al PM y a ingeniería temprano
Análisis Profundo
Cómo Funciona
- Preguntas de descubrimiento: Quién, frecuencia, cumplimiento, volumen pico, tolerancia a fallos.
- Corte vertical: Camino delgado de extremo a extremo antes de pulir casos extremos.
- Contrato primero: Modelos Pydantic u OpenAPI antes de la implementación profunda.
- Disciplina de migración: Expansión-contracción mencionada en la especificación, no sorpresa en la PR.
- Revisión con el PM: Repasar pruebas de aceptación; ajustar el alcance antes del compromiso del sprint.
Lista de Verificación de Calidad de Especificaciones
| Sección | Falta = riesgo |
|---|---|
| No-objetivos | Expansión del alcance a mitad de sprint |
| Reversión | Incidente sin mitigación |
| Observabilidad | Lanzamiento ciego en producción |
| Idempotencia | Cargos/exportaciones duplicados |
Notas de Python
# Stub de prueba de aceptación de la especificación
def test_export_job_returns_download_url(client, invoice_factory):
ids = [invoice_factory().id for _ in range(3)]
r = client.post("/v1/invoices/export", json={"invoice_ids": ids})
assert r.status_code == 202Trampas Comunes
- Especificación después de iniciar el código: Retrabajo y culpa. Solución: Sin compromiso de sprint sin especificación revisada para trabajo mediano o mayor.
- Aceptación vaga: "Rápido" o "escalable". Solución: Números: p95, filas máximas, códigos de error.
- Ignorar el nivel del trabajador: Especificación de API sin historia de cola. Solución: Sección de tarea Celery obligatoria para trabajo asíncrono.
- Cumplimiento oculto: PII en logs de PDF descubierto tarde. Solución: Clasificación de datos en el encabezado de la especificación.
- Una especificación gigante: Nunca se envía. Solución: No-objetivos de la Fase 1 explícitos; stub de ticket para la Fase 2.
Alternativas
| Alternativa | Usar Cuándo | No Usar Cuándo |
|---|---|---|
| RFC para arquitectura | Debate inter-equipos | Historia simple de CRUD |
| Sesión de mapeo de historias de trabajo | Nueva área de producto | Punto final de API único |
| Pico de prototipo | UX de alta incertidumbre | Facturación regulada sin especificación |
| BDD Gherkin | Aceptación legible por el negocio | Herramientas solo internas |
Preguntas Frecuentes
¿Cuánto tiempo deberían llevar las especificaciones?
Medio día a dos días para características medianas; hacer un pico (spike) si lleva más de tres días escribirla.
¿Quién aprueba las especificaciones?
El líder técnico + PM firman la aceptación; seguridad para PII/pagos.
¿Especificación para corrección de errores?
Ligera: reproducir, hipótesis de causa raíz, plan de pruebas - omitir plantilla completa.
¿Django vs FastAPI en la especificación?
Declarar explícitamente las suposiciones del framework y los patrones de autenticación compartidos.
¿Cómo manejar requisitos cambiantes?
Modificar la versión de la especificación; re-estimar; no absorber el alcance silenciosamente.
¿Especificaciones y Jira?
Enlazar la PR de la especificación o el documento en la épica; las pruebas de aceptación se copian en el ticket.
¿Características de ML en la especificación?
Incluir fuentes de datos, métrica de evaluación, reversión a la versión anterior del modelo.
¿Cuándo involucrar a diseño?
Antes de la congelación de la API cuando la UX impulse la paginación, filtros o límites de exportación.
¿Límite de preguntas abiertas?
Si hay más de 3 bloqueadores, limitar el tiempo de los picos (spikes) antes del compromiso del sprint.
¿Almacenamiento de especificaciones?
docs/specs/ en el repositorio o carpeta RFC enlazada - versionado con el código.
Relacionado
- Estimación y Riesgo - tamaño después de la especificación
- Contribuciones al Roadmap - alimentar la planificación
- Ejecución de Revisiones de Diseño - cambios grandes
- BDD y Gherkin - formato de aceptación
- Modelos Pydantic - modelado de contratos
Versiones de la Pila: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.