Busca en todas las páginas de la documentación
Esta sección se lee como una lista de instrucciones arbitrarias: usa snake_case, ejecuta EXPLAIN antes de fusionar, establece lock_timeout en las migraciones, nunca conectes la aplicación como superusuario.
Cada una es en realidad el residuo comprimido de algo que ya salió mal una vez, generalizado en una instrucción lo suficientemente barata de seguir sin tener que re-aprender el incidente original.
Cada regla duradera en esta sección comienza desde el mismo lugar: una consulta derribó una tabla, una migración se quedó bloqueada por un bloqueo, o un esquema alcanzó una ambigüedad que nadie había resuelto de antemano.
La instrucción que sigue, "ejecuta EXPLAIN antes de fusionar una nueva consulta" o "establece lock_timeout en cada migración", es más barata de decir y seguir que el incidente que costó vivir, que es el propósito de escribir reglas.
Ese marco separa una regla de una preferencia de estilo, incluso si ambas pueden vivir en el mismo documento y parecer igualmente concisas en la página.
Una preferencia de estilo, como nombres de tabla en singular versus plural, no tiene ningún modo de fallo detrás; nada se rompe de ninguna manera, por lo que el único costo de la inconsistencia es la legibilidad y la fricción de búsqueda en la base de código.
Una regla, en el sentido que esta sección usa la palabra, existe porque equivocarse tiene un costo real y descriptible, una interrupción, una brecha de seguridad o una migración de varias horas que debería haber tomado segundos.
Una analogía útil: un documento de reglas es el tejido cicatricial de una base de código hecho legible, cada cicatriz marca un lugar donde el equipo fue realmente herido, protegiendo aún contra una repetición mucho después de que el corte original se olvide.
No todas las reglas merecen la misma fuerza de aplicación, y emparejar la aplicación con el costo real es la mayor parte de lo que separa un documento de reglas útil de una lista que nadie lee.
Las reglas en esta sección se encuentran en un espectro aproximado, desde convención documentada, esperada en revisión pero no verificada mecánicamente, hasta aplicada en revisión de código, donde se espera que un humano la detecte, hasta aplicada en CI, donde una regla de lint o una prueba falla automáticamente la compilación.
sucede un incidente
│
▼
lección escrita ── convención documentada
│ (el patrón se repite, es verificable)
▼
los revisores la vigilan ── aplicada en revisión de código
│ (una herramienta puede expresarla)
▼
la puerta mecánica la bloquea ── aplicada en CIUna regla generalmente comienza en la parte superior de esa cadena, porque alguien acaba de aprender la lección y la escribió, y se gana su camino hacia una puerta de CI solo una vez que el equipo confirma dos cosas: el patrón realmente se repite y es el tipo de cosa que una verificación mecánica puede detectar de manera confiable.
Forzar una regla dependiente del juicio directamente en una puerta de CI antes de que sea verificable de manera confiable produce falsos positivos, y los falsos positivos enseñan a los ingenieros a evitar la puerta en lugar de confiar en ella.
La Lista de Verificación de Reglas del Proyecto Postgres es la versión concreta y escalonada de esta idea aplicada a escala de proyecto: sus 25 elementos se agrupan por cuán bloqueantes para el lanzamiento son, lo cual es en sí mismo una aplicación de "no todas las reglas merecen la misma urgencia".
Un proceso de excepciones es lo que evita que una regla aplicada mecánicamente se convierta en burocracia frágil la primera vez que se encuentra con un caso límite legítimo que no anticipó.
Sin uno, un equipo rompe la regla en silencio, socavándola para todos los que confiaron en la puerta, o bloquea un cambio genuinamente válido, socavando la confianza en el propio proceso.
La Plantilla ADR para Postgres existe precisamente para esta situación: un Registro de Decisiones de Arquitectura hace que una desviación de la regla predeterminada sea visible y deliberada en lugar de invisible.
Las reglas también acumulan un tipo específico de decadencia que vale la pena nombrar directamente, degradación de reglas, donde una instrucción sigue siendo aplicada mucho después de que la situación que la justificó ha cambiado.
Una regla de uso de índices revisada manualmente antes de que pg_stat_statements fuera estándar en todos los entornos podría ya no valer la pena una vez que la revisión automatizada de consultas se ejecute en cada PR, no porque la regla fuera incorrecta, sino porque herramientas mejores ahora cubren el mismo objetivo subyacente.
Las reglas que nombran el fallo específico que previenen envejecen mejor que las reglas declaradas como instrucción pura, porque un equipo que revisa "por qué hacemos esto" puede juzgar realmente si ese fallo sigue siendo un riesgo activo antes de decidir mantener, relajar o automatizar aún más la regla.
| Nivel de aplicación | Fortaleza | Debilidad | Mejor Ajuste |
|---|---|---|---|
| Convención documentada | Barata de escribir; preserva el juicio para casos límite genuinos | Depende de la memoria y la cultura; se erosiona bajo presión de plazos | Decisiones dependientes del contexto que un linter no puede evaluar |
| Aplicada en revisión de código | Detecta matices que una verificación mecánica pasaría por alto | Inconsistente entre revisores y tiempo de revisión disponible | Reglas que requieren juicio con apuestas lo suficientemente altas como para necesitar un segundo revisor |
| Puerta aplicada en CI | Se aplica uniformemente a cada contribuyente, cada vez | Solo funciona para patrones genuinamente verificables; los falsos positivos erosionan la confianza | Violaciones de alto costo y claramente detectables como índices faltantes o roles de aplicación de superusuario |
Una preferencia de estilo, como nombres de tabla en singular versus plural, no tiene un modo de fallo; una regla existe específicamente porque equivocarse tiene un costo real y descriptible, como una interrupción o una brecha de seguridad.
Una regla declarada solo como comportamiento requerido se sigue o se omite silenciosamente sin que nadie pueda juzgar si todavía se aplica; nombrar el fallo que previene permite a un ingeniero futuro evaluarlo realmente.
Se gana esa promoción una vez que el patrón se repite genuinamente y una verificación mecánica puede detectarlo de manera confiable sin falsos positivos; las reglas que aún necesitan juicio real permanecen en la aplicación de revisión de código.
Porque las puertas de CI solo funcionan bien para patrones que una herramienta puede verificar de manera confiable, y forzar una regla dependiente del juicio en una puerta produce falsos positivos que enseñan a los ingenieros a evitarla o desconfiar de ella.
Proporciona a un caso límite legítimo un camino visible y deliberado para evitar el predeterminado en lugar de forzar una violación silenciosa o bloquear un cambio genuinamente válido por completo.
Es cuando una regla sigue siendo aplicada después de que la situación que la justificó ha cambiado, como una regla de revisión manual de índices reemplazada por el monitoreo automatizado de pg_stat_statements, y se acumula como fricción sin un beneficio correspondiente.
No necesariamente: la Lista de Verificación de Reglas del Proyecto Postgres agrupa las reglas por cuán bloqueantes para el lanzamiento son, ya que una regla de seguridad y una regla de madurez operativa no conllevan el mismo riesgo si se dejan sin abordar.
En la práctica, quien sea que posea el incidente o el costo recurrente del patrón, pero la decisión debe documentarse y ser visible en lugar de dejarse en la memoria de un ingeniero.
La nomenclatura es una elección de estilo pura sin modo de fallo; "índice antes de fusionar" existe porque una consulta de producción sin índice ha causado directamente interrupciones, por lo que una pertenece a un linter y la otra a la revisión.
Solo si cada regla todavía nombra un fallo real y actual y tiene una aplicación emparejada con su costo real; un documento que solo crece y nunca se revisa es la versión burocrática del mismo artefacto.
Sí, y debería revisarse en lugar de dejarse indefinidamente; una regla que ha sido reemplazada por mejores herramientas automatizadas es candidata a su retiro, no a su aplicación permanente.
Generalmente se ubican en la máxima urgencia de aplicación, ya que una regla de seguridad violada (como un rol de aplicación de superusuario) tiende a tener un costo desproporcionado y difícil de revertir en comparación con una inconsistencia de estilo o nomenclatura.
Versiones de Stack: Esta página es conceptual y no está vinculada a una versión específica de stack.
Revisado por Chris St. John·Última actualización: 15 jul 2026