Los procesos de revisión de código suelen comenzar como "control de calidad" y terminan como "guerra de egos". A medida que el equipo crece, dos trampas se hacen evidentes: los PR quedan en espera durante semanas o cada comentario se interpreta como una crítica personal. Ambas provienen del mismo problema raíz — normas que no son medibles. En Roibase, después de 8 años trabajando con más de 15 personas de disciplinas diferentes, aprendimos algo simple: a menos que ancles la cultura de revisión en criterios numéricos, el juicio personal se vuelve inevitable. Cuando conviertes métricas como time-to-review, comment density y PR size en sistema, la calidad sube y los conflictos bajan.
Velocidad de Revisión: SLA de Time-to-Review
Cada PR tiene un ciclo de vida. El tiempo que tarda desde que se abre hasta el primer comentario — time-to-first-review — es el primer indicador de disciplina del equipo. En Roibase, limitamos este tiempo a un máximo de 4 horas (dentro del horario laboral). ¿Por qué 4 horas? Es el punto dulce entre proteger bloques de deep work y acelerar el ciclo de retroalimentación en un modelo de trabajo asincrónico.
La regla es clara: algún reviewer debe revisar el PR dentro de 4 horas de su apertura. El mecanismo de enforcement no es una notificación de Slack — es un flujo de trabajo de GitHub Actions. Cuando se abre un PR, se etiqueta automáticamente, y después de 4 horas se menciona en Slack a los reviewers asignados. Este recordatorio suave elimina las revisiones "olvidadas".
La métrica time-to-merge es más crítica. El tiempo desde la apertura del PR hasta el merge en la rama principal — por ejemplo, para cambios en backend, que no excedan 24 horas. Para cambios en frontend, 48 horas. ¿Por qué esta diferencia? Los merges en backend generalmente requieren menos validación visual y se pueden desplegar detrás de feature flags. En frontend, las fases de QA de diseño y pruebas multidispositivo toman más tiempo.
Dashboard de Métricas: Integración Linear
Integramos Linear con GitHub, vinculando automáticamente cada PR a un ticket de Linear. El estado del ticket se actualiza según el ciclo de vida del PR. Al final del sprint, la métrica que revisamos es: time-to-merge promedio. Si el promedio del equipo supera las 36 horas, hay un problema que debe discutirse en la retrospectiva — generalmente relacionado con el tamaño del PR o la carga del reviewer.
Tamaño del PR: La Regla de 400 Líneas
Los PR grandes no se pueden revisar. Este es el consenso más común en la industria, pero rara vez se convierte en una regla medible. El estándar de Roibase: máximo 400 líneas de cambios (sumas de adiciones y eliminaciones). ¿De dónde viene este número? Es la cantidad de líneas que un reviewer puede mantener racionalmente en su mente durante una revisión enfocada de 30 minutos.
Para enforcing la regla, usamos una regla de protección de rama de GitHub: los PR que superan 400 líneas reciben automáticamente la etiqueta "needs-split" y no se pueden hacer merge. Hay excepciones — actualizaciones de dependencias, scripts de migración. Pero incluso esos requieren un override manual con justificación en un comentario de GitHub.
¿Cómo se hacen refactores grandes? PR apilados. El primer PR: cambio de interfaz; el segundo: implementación; el tercero: eliminación de código antiguo. Cada uno bajo 400 líneas, cada uno revisable independientemente. ¿Toma más tiempo? Sí. ¿Aumenta el riesgo de conflictos de merge? Un poco. Pero la calidad de revisión mejora exponencialmente — porque el reviewer tiene la capacidad mental para pensar en cada cambio.
# GitHub Actions — PR size check
name: PR Size Check
on: pull_request
jobs:
size_check:
runs-on: ubuntu-latest
steps:
- name: Check PR size
run: |
ADDITIONS=$(jq '.pull_request.additions' "$GITHUB_EVENT_PATH")
DELETIONS=$(jq '.pull_request.deletions' "$GITHUB_EVENT_PATH")
TOTAL=$((ADDITIONS + DELETIONS))
if [ $TOTAL -gt 400 ]; then
echo "PR too large: $TOTAL lines"
gh pr edit --add-label needs-split
exit 1
fi
Densidad de Comentarios: El Límite del Nitpick
No todos los comentarios tienen el mismo peso. Hay una diferencia crítica entre "esto podría refactorizarse" y "esto causa una excepción de null pointer". La plantilla de revisión de Roibase requiere categorizar los comentarios:
| Categoría | Etiqueta | Ejemplo |
|---|---|---|
| Blocker | 🔴 BLOCKER | Vulnerabilidad de seguridad, crash en runtime |
| Major | 🟠 MAJOR | Regresión de rendimiento, error lógico |
| Minor | 🟡 MINOR | Convención de nombres, cobertura de test |
| Nitpick | 🔵 NITPICK | Cuestión de preferencia, subjetivo |
La regla: la proporción de nitpick no debe exceder el 30%. Si un PR tiene 10 comentarios, 3 pueden ser nitpick, el resto debe ser blocker/major/minor. ¿Por qué? Porque las revisiones dominadas por nitpicks desmoralizan al author, marcando al reviewer como "innecesariamente riguroso".
La métrica comment density: número promedio de comentarios por PR. En Roibase, este número está entre 3-5. Más de 10 comentarios generalmente significa que el PR necesita dividirse. Cero comentarios indica una revisión de goma — también indeseable.
Uso de Plantilla
Todo reviewer comienza desde una plantilla de PR de GitHub:
## Review Checklist
- [ ] ¿La lógica del código es correcta?
- [ ] ¿La cobertura de test está por encima del 80%?
- [ ] ¿Hay cambios que rompan compatibilidad? (¿Se actualizó CHANGELOG?)
- [ ] ¿Se midió el impacto de rendimiento? (benchmarks/)
## Comments
**🔴 BLOCKER:**
-
**🟠 MAJOR:**
-
**🟡 MINOR:**
-
**🔵 NITPICK:**
-
Esta plantilla hace dos cosas: obliga al reviewer a categorizar, y permite al author identificar rápidamente qué comentarios son críticos.
Revisión Asincrónica: La Trampa de las Reuniones Sync
La revisión de código no debe hacerse en reuniones sincrónicas. En Roibase, el concepto de "review call" no existe — toda revisión es asincrónica, en GitHub. ¿Por qué? El equipo trabaja en 3 zonas horarias diferentes, y proteger bloques de deep work es crítico.
La disciplina de revisión asincrónica funciona así: el reviewer examina el PR durante su bloque de enfoque profundo (generalmente 09:00-12:00). Escribe comentarios, aprueba o solicita cambios. Cuando el author recibe la notificación (en su propia agenda), realiza los cambios y solicita re-revisión. Este ciclo se repite generalmente 2-3 veces.
Excepción: bloqueo de revisión — si author y reviewer no llegan a un acuerdo en 3 rondas, entonces se abre una llamada sincrónica de 15 minutos. Pero esto ocurre solo 5-6 veces al año, como situación excepcional. La voz de marca que Roibase creó durante su proceso de posicionamiento de marca también refleja esta cultura de trabajo async-first — documentación primero, reuniones al final.
Propiedad vs. Gatekeeping
El propósito de la revisión de código es asegurar la calidad, pero el efecto secundario no debe ser gatekeeping. En Roibase, cada PR requiere un mínimo de 1 y un máximo de 2 reviewers. ¿Por qué 2 como límite superior? Porque el costo en tiempo de esperar aprobación de 3+ reviewers supera la ganancia en calidad del código.
La selección de reviewers no es automática — el author elige. La regla: al menos uno debe ser code owner (del archivo CODEOWNERS), el otro puede ser cualquiera. Este enfoque mantiene la propiedad en el author. La pregunta "¿quién debe aprobar esto?" es responsabilidad del author, no del líder del equipo.
El archivo CODEOWNERS se ve así:
# Backend
/backend/ @backend-team
/api/ @backend-team
# Frontend
/web/ @frontend-team
/mobile/ @mobile-team
# Infrastructure
/terraform/ @devops-team
/.github/ @devops-team
Todo cambio de archivo debe ser revisado por alguien del equipo relevante — pero es el author quien elige la persona específica.
Retrospectiva: Métricas de Revisión
Al final de cada sprint (cada 2 semanas), revisamos las métricas de revisión. Dashboard de Linear:
- Time-to-merge promedio (objetivo: 36 horas)
- Distribución de tamaño de PR (objetivo: 90% bajo 400 líneas)
- Densidad de comentarios (objetivo: 3-5 por PR)
- Proporción de nitpick (objetivo: <30%)
- Cuello de botella de revisión (¿quién espera más?)
Estas cifras se discuten en la retrospectiva, pero sin culpa personal. Por ejemplo, en lugar de "Ali's reviews son lentos", la pregunta es "Los PR de backend esperan 48 horas en promedio, ¿deberíamos ampliar el pool de reviewers?"
Llevar la cultura de revisión de código del juicio personal a la disciplina sistémica no es difícil — pero requiere reglas medibles. SLA de time-to-review, regla de 400 líneas, categorización de comentarios, enfoque async-first — estas son las herramientas concretas que han permitido a Roibase mantener la calidad mientras crece. Si tus procesos de revisión aún son "intuitivos" y "dependen de la situación", pon números, hazlos sistémicos. La calidad subirá mientras los conflictos bajan.