Plantilla RFD: cómo documentar decisiones técnicas que el equipo recordará

Por qué documentar las decisiones técnicas

Seis meses después de tomar una decisión técnica importante, nadie recuerda por qué se tomó. El código dice qué se hizo, pero no por qué se descartaron las otras opciones, qué trade-offs se aceptaron ni qué suposiciones existían en ese momento.

Los RFD (Request for Discussion) resuelven este problema con un formato estructurado que captura el contexto, las alternativas consideradas y el razonamiento final. Son especialmente útiles para:

• Elección de base de datos o arquitectura principal
• Adopción de una nueva librería o framework
• Decisiones de seguridad y cumplimiento
• Cambios de API con impacto en clientes externos

---

La plantilla RFD

# RFD-XXX: [Título descriptivo de la decisión]

**Estado:** Propuesto | En discusión | Aprobado | Rechazado | Obsoleto
**Fecha:** YYYY-MM-DD
**Autores:** @nombre1, @nombre2
**Revisores:** @nombre3, @nombre4

---

## Contexto

[Describe el problema o situación que requiere tomar una decisión.
¿Qué está pasando ahora? ¿Por qué esto es un problema?
¿Qué restricciones o requisitos existen?]

## Decisión

[Una frase clara que resume la decisión adoptada.
Ejemplo: "Usaremos PostgreSQL con schema por tenant para el módulo de ensayos clínicos."]

## Opciones consideradas

### Opción A: [Nombre]
**Descripción:** ...
**Ventajas:** ...
**Desventajas:** ...

### Opción B: [Nombre]
**Descripción:** ...
**Ventajas:** ...
**Desventajas:** ...

### Opción C: [Nombre]
**Descripción:** ...
**Ventajas:** ...
**Desventajas:** ...

## Razonamiento

[Por qué se eligió la opción adoptada sobre las demás.
Qué trade-offs se aceptaron conscientemente.
Qué suposiciones se están haciendo.]

## Consecuencias

[Qué cambia como resultado de esta decisión.
Impacto en el equipo, arquitectura, costes, rendimiento.
Deuda técnica introducida, si aplica.]

## Referencias

- [Enlace a issue, PR, documento o discusión relacionada]
- [Documentación técnica relevante]

---

Ejemplo real: RFD-007 — Elección de base de datos para módulo de ensayos clínicos

Estado: Aprobado | Fecha: 2025-03-15 | Autores: @miguel, @javier

Contexto: El módulo de ensayos clínicos almacenará datos de pacientes sujetos a GDPR y requisitos de auditoría regulatoria (ICH E6 GCP). Necesitamos una solución que aísle datos entre estudios, soporte consultas analíticas complejas y permita borrado selectivo por estudio.

Decisión: PostgreSQL con schema por estudio clínico.

Opciones consideradas:

• A) Base de datos separada por estudio: máximo aislamiento, pero inviable operacionalmente (>200 estudios activos).
• B) Schema por estudio en PostgreSQL: buen aislamiento, migraciones independientes, operacionalmente manejable.
• C) Tabla compartida con columna study_id: más simple, pero riesgo de data leakage por bug de query y cumplimiento GDPR más complejo.

Decisión: Opción B. El aislamiento por schema facilita el borrado por estudio (DROP SCHEMA), las migraciones independientes y la auditoría regulatoria.

---

Cómo implementarlo en tu equipo

1. Crea la carpeta docs/decisions/ en tu repositorio principal.
2. Numeración secuencial: RFD-001, RFD-002… Un índice en docs/decisions/README.md.
3. Commit junto al código: Cuando merges la PR que implementa la decisión, incluye el RFD en el mismo commit.
4. Estado "Obsoleto" en lugar de borrar: Si una decisión cambia, marca la antigua como obsoleta y referencia la nueva.

---

¿Tu equipo toma decisiones técnicas importantes sin documentarlas? Podemos ayudarte a establecer el proceso.