El Modelo Mental Detrás de las Reglas de Ingeniería de Node.js
Esta sección está llena de reglas concretas: no hay E/S síncrona en un manejador de solicitudes, valida cada ruta de mutación, limita fetch saliente con un tiempo de espera. Cada una se lee como una instrucción simple, pero cada regla en esta sección en realidad codifica algo más específico: un modo de fallo que alguien ya experimentó, comprimido en una instrucción lo suficientemente económica como para seguirla sin volver a derivar el razonamiento desde cero cada vez.
Una regla de ingeniería es memoria institucional comprimida: un fallo específico del pasado, generalizado en una instrucción que permite al próximo ingeniero evitarlo sin volver a aprender la lección desde cero.
Por Qué Importa: Los equipos que tratan las reglas como un estilo arbitrario terminan ignorándolas bajo la presión de los plazos o siguiéndolas más allá del punto en que todavía se aplican; ambos modos de fallo se remontan a no comprender contra qué protegía realmente la regla.
Conceptos Clave:regla, nivel de aplicación, ciclo de vida de la regla, proceso de excepción, deterioro de la regla.
Cuándo Usar: Decidir si una nueva convención merece convertirse en una regla documentada, elegir con qué rigor aplicarla, escribir una regla para que sobreviva a la partida de la persona que la escribió, o decidir cuándo se debe revisar una regla antigua.
Limitaciones / Compromisos: Las reglas intercambian el juicio por la consistencia; cuanto más codificas, menos tiene que razonar cada ingeniero desde los primeros principios, pero también más acumula un código instrucciones que sobreviven a la situación que las justificó.
Temas Relacionados: registros de decisiones de arquitectura, puertas de calidad de CI, normas de revisión de código, aplicación de análisis estático.
Cada regla de ingeniería duradera comienza de la misma manera: algo se rompió, alguien descubrió por qué, y el equipo decidió que la solución no debería depender de que todos la redescubrieran independientemente. Una regla como "no fs.readFileSync en un manejador de solicitudes" no es una preferencia de estilo sobre los nombres de las funciones; es el residuo de un incidente en el que una lectura síncrona detuvo todas las demás solicitudes en el proceso. La regla es más barata de establecer que el incidente de volver a aprender, que es la razón principal por la que existen las reglas: permiten que las lecciones costosas se paguen una vez y se reutilicen para siempre.
Ese marco importa porque distingue una regla de dos cosas con las que a menudo se confunde. Una guía es un valor predeterminado que los ingenieros razonables pueden anular con juicio; "prefiere async/await sobre las cadenas de promesas puras" sobrevive a ser ignorada en un caso excepcional. Una regla, en el sentido en que esta sección usa la palabra, es algo que el equipo ha decidido que debe cumplirse sin juicio caso por caso, generalmente porque el costo de equivocarse (un agujero de seguridad, una interrupción, un error de pérdida de datos) es lo suficientemente alto como para que "usa tu juicio" no sea una respuesta aceptable. Una elección de estilo de la casa (tabulaciones vs. espacios) no es ninguna de las dos; no tiene ningún modo de fallo detrás, por lo que las herramientas de formato, en lugar de los documentos de reglas, son las que se encargan de ese territorio.
Una analogía útil: piensa en un documento de reglas como el tejido cicatricial acumulado de una base de código, hecho legible. El tejido cicatricial se forma en respuesta a una lesión específica y luego sigue protegiendo contra ella mucho después de que nadie recuerde el corte original, que es exactamente el compromiso del que vale la pena estar consciente. Una regla que ha dejado de proteger contra algo real es una regla que vale la pena cuestionar, no una regla que vale la pena obedecer reflexivamente.
No todas las reglas merecen la misma fuerza detrás de ellas, y hacer coincidir la aplicación con el costo real de la violación es lo que distingue un documento de reglas útil de una lista de deseos que nadie lee. Las reglas en esta sección se encuentran en un espectro:
Convención documentada - escrita, explicada, esperada en la revisión, pero no verificada mecánicamente. Apropiada para juicios donde el contexto importa (elegir entre un bus de eventos y una llamada directa dentro de un monolito modular).
Aplicada por revisión de código - se espera que un revisor detecte las violaciones, respaldado por una lista de verificación o plantilla de PR para que no se deje a la memoria. Apropiada para cosas que un linter genuinamente no puede evaluar (¿es la sección de contexto de este ADR realmente precisa?).
Aplicada por CI (puerta mecánica) - una regla de linter, verificación de tipo o prueba que falla la compilación automáticamente. Apropiada para cualquier cosa con una firma clara y verificable: patrones prohibidos, forma de validación de entrada faltante, un parámetro limit sin límite.
La relación entre estos niveles es direccional e importante: una regla generalmente comienza como una convención documentada (porque alguien acaba de aprender la lección y la escribió), y se gana su camino hacia la aplicación mecánica a medida que el equipo confirma que el patrón se repite y puede detectarse automáticamente. Saltar directamente a una puerta de CI para algo que no se puede verificar mecánicamente de manera confiable produce falsos positivos que erosionan la confianza en toda la puerta; dejar una regla verificable y de alto costo en "solo documentada" para siempre significa que depende de que cada revisor la recuerde, indefinidamente.
ocurre un incidente │ ▼se nombra y se escribe la lección ── convención documentada │ (el patrón se repite, es verificable) ▼los revisores lo buscan explícitamente ── aplicada por revisión de código │ (un linter/verificación de CI puede expresarlo) ▼la puerta mecánica bloquea las violaciones ── aplicada por CI
Un proceso de excepción es lo que evita que una regla se convierta en burocracia frágil una vez que se aplica mecánicamente. Una regla establecida como absoluta ("nunca hagas X") sin una vía de escape eventualmente encuentra un caso legítimo que no anticipó, momento en el que el equipo rompe la regla en silencio (socavándola para todos) o bloquea un cambio legítimo (socavando la confianza en el proceso). La Plantilla ADR para Node existe en parte por esta razón: un Registro de Decisión de Arquitectura es el mecanismo para registrar por qué un caso específico se desvía de la regla predeterminada, de modo que la excepción sea visible y deliberada en lugar de silenciosa.
Las reglas acumulan un tipo específico de deterioro que vale la pena nombrar directamente: el deterioro de la regla, donde una instrucción sigue aplicándose mucho después de que la situación que la justificaba ha cambiado. Una regla de fijación de dependencias escrita cuando un equipo no tenía herramientas de auditoría automatizadas podría ya no ser rentable una vez que npm audit se ejecuta en CI en cada PR; la regla no está mal, simplemente ha sido reemplazada por una mejor aplicación del mismo objetivo subyacente. Las reglas que nombran el fallo que previenen envejecen mejor que las reglas que solo nombran el comportamiento requerido, porque un equipo que revisa "por qué hacemos esto" puede evaluar si el fallo sigue siendo un riesgo real; una regla establecida como pura instrucción sin una justificación simplemente se sigue, o se abandona en silencio, sin que nadie pueda decir cuál es la correcta.
Aquí es también donde una sección de reglas se gana su lugar a escala organizacional en lugar de a escala de ingeniero individual. Un solo ingeniero senior puede mantener "no bloquees el bucle de eventos" como conocimiento tácito y detectar violaciones en la revisión por instinto. Eso no se transfiere, ni a un nuevo empleado, ni a un segundo equipo que construye un segundo servicio, ni a un ingeniero seis meses después del incidente original. Escribir la regla, clasificar su aplicación y proteger las partes verificables en CI es lo que hace que la lección sea organizacionalmente duradera en lugar de depender de la memoria de una persona en la sala durante la revisión del código.
Vale la pena leer la Lista de Verificación de Reglas del Proyecto Node a través de esta lente específicamente: agrupa 25 reglas en niveles (la seguridad bloquea el lanzamiento, las puertas de API/calidad bloquean el tráfico de GA, la madurez operativa se completa dentro del primer mes); esa clasificación es en sí misma una aplicación de "no todas las reglas merecen la misma urgencia", aplicada a la escala de un servicio completo en lugar de una convención.
Nivel de aplicación
Fortaleza
Debilidad
Mejor ajuste
Convención documentada
Barato de escribir; conserva el juicio para casos excepcionales genuinos
Depende completamente de la memoria y la cultura; se erosiona bajo la presión de los plazos
Decisiones dependientes del contexto que un linter no puede evaluar
Aplicada por revisión de código
Captura matices que una verificación mecánica pasaría por alto
Inconsistente: depende del revisor y del tiempo que tenga
Reglas con juicios reales pero con riesgos lo suficientemente altos como para necesitar un segundo par de ojos
Puerta aplicada por CI
Se aplica uniformemente, siempre, a cada colaborador
Solo funciona para patrones genuinamente verificables; los falsos positivos erosionan la confianza
Violaciones de alto costo y claramente detectables (APIs prohibidas, validación faltante, consultas ilimitadas)
"Un documento de reglas y una guía de estilo son lo mismo." El estilo no tiene un modo de fallo detrás; es trabajo de un formateador. Una regla existe porque violarla tiene un costo real y específico; confundir ambos hace que las reglas reales se sientan tan opcionales como las preferencias de ancho de tabulación.
"Una vez que una regla está escrita, se aplica." Una regla no aplicada es un deseo; solo se mantiene mientras cada ingeniero la recuerde y elija seguirla, que es precisamente el modo de fallo que las reglas existen para eliminar en primer lugar.
"Toda regla debería eventualmente convertirse en una puerta de CI." Solo los patrones genuinamente verificables pertenecen allí; forzar una regla dependiente del juicio en una puerta mecánica produce falsos positivos que enseñan a los ingenieros a eludir la puerta por completo.
"Las reglas sin excepciones son reglas más fuertes." Una regla absoluta sin una vía de escape simplemente reubica la excepción a "violada en silencio" en lugar de "justificada deliberada y visiblemente", lo cual es estrictamente peor para cualquiera que audite la base de código más tarde.
"Las reglas antiguas son seguras de dejar en su lugar indefinidamente." Una regla puede sobrevivir al fallo que estaba protegiendo, especialmente una vez que mejores herramientas la reemplazan; las reglas que no se revisan acumulan fricción sin el beneficio correspondiente.
¿Qué distingue realmente una "regla" de una "guía" en esta sección?
Una guía es un valor predeterminado que los ingenieros pueden anular razonablemente usando el juicio. Una regla es algo que el equipo ha decidido que debe cumplirse sin juicio caso por caso, generalmente porque el costo de equivocarse es alto (una brecha de seguridad, una interrupción, pérdida de datos), no porque se prefiera una frase específica.
¿Por qué las reglas necesitan un "por qué" documentado, no solo un "qué"?
Una regla que solo establece el comportamiento requerido se sigue, o se abandona en silencio, sin que nadie pueda evaluar si todavía se aplica. Nombrar el fallo que previene permite a un futuro ingeniero juzgar si ese fallo sigue siendo un riesgo real antes de decidir mantener, relajar o automatizar la regla.
¿Cómo pasa una regla de "documentada" a "aplicada en CI"?
Se gana esa promoción una vez que se cumplen dos cosas: el patrón se repite genuinamente (vale la pena el costo de configuración) y es el tipo de cosa que una verificación mecánica puede detectar de manera confiable sin falsos positivos. Las reglas que necesitan un juicio real permanecen en la aplicación de revisión de código.
¿Por qué no simplemente hacer que cada regla importante sea una puerta de CI dura de inmediato?
Porque las puertas de CI solo funcionan bien para patrones que una herramienta puede verificar de manera confiable. Forzar una regla dependiente del juicio en una puerta mecánica produce falsos positivos, y los falsos positivos enseñan a los ingenieros a desconfiar o eludir la puerta, socavando la aplicación de las reglas que realmente la necesitan.
¿Cuál es el propósito de un proceso de excepción para una regla?
Le da a un caso excepcional legítimo un camino visible y deliberado alrededor del valor predeterminado, en lugar de forzar una violación silenciosa o bloquear un cambio válido por completo. Un ADR es una forma común de registrar esa decisión para que la excepción sea auditable en lugar de invisible.
¿En qué se diferencia una "regla" de una simple preferencia de estilo como tabulaciones vs. espacios?
Una preferencia de estilo no tiene un modo de fallo detrás; nada se rompe de ninguna manera, por lo que un formateador, no un documento de reglas, es el dueño de esa decisión. Una regla existe específicamente porque violarla tiene un costo real y descriptible.
¿Qué es el "deterioro de la regla" y por qué importa?
Es cuando una regla sigue aplicándose después de que la situación que la justificaba ha cambiado, por ejemplo, una regla manual de fijación de dependencias que desde entonces ha sido reemplazada por herramientas de auditoría automatizadas. Las reglas que no se revisan periódicamente se acumulan como fricción sin un beneficio correspondiente.
¿Debería cada servicio en una organización seguir cada regla de esta sección de manera idéntica?
No necesariamente con la misma urgencia; el enfoque de niveles en la Lista de Verificación de Reglas del Proyecto Node agrupa las reglas por cuán bloqueantes son para el lanzamiento, porque una regla de seguridad y una regla de madurez operativa no conllevan el mismo riesgo si se dejan sin abordar durante una semana.
¿Quién decide si algo se convierte en una regla del equipo?
En la práctica, quien sea el propietario del postmortem o del costo recurrente del patrón, pero la decisión debe ser visible, no tácita, que es exactamente lo que proporciona una sección de reglas documentada y un rastro de ADR en lugar de dejarlo en la memoria de un ingeniero.
¿Un documento de reglas grande es un signo de una organización de ingeniería madura o burocrática?
Depende de si cada regla todavía nombra un modo de fallo real y actual y tiene una aplicación que coincide con su costo real. Un documento de reglas que se poda y se reestructura periódicamente es madurez; uno que solo crece y nunca se revisa es la versión burocrática del mismo artefacto.