He dejado tres proyectos de largo plazo en mi carrera. Cada vez, he vuelto a mirar qué sobrevivió — no solo qué funcionó técnicamente, sino qué seguía siendo comprensible e intencional para los equipos que lo heredaron.
Los resultados fueron reveladores.
Un sistema del que estaba orgulloso se había convertido en “legacy” a los meses, no porque la tecnología estuviera mal, sino porque el equipo no sabía por qué habíamos tomado los tradeoffs clave. Cuando esas restricciones cambiaron, no pudieron adaptar la arquitectura porque no sabían contra qué la estaba protegiendo.
Este es el problema central del nivel Staff: no estás escribiendo código para el equipo de hoy. Lo estás escribiendo para un equipo que todavía no existe, con requisitos que todavía no se han planteado.
La diferencia entre una decisión y un default
La mayoría de las decisiones arquitectónicas no se toman — se acumulan. Nadie decidió que todas las llamadas a la API deben pasar por una instancia global de axios. Alguien lo hizo, funcionó, otros siguieron el patrón, y ahora es “así hacemos las cosas aquí”.
Los defaults acumulados son invisibles. Nadie puede explicar por qué existen, lo que significa que nadie puede evaluar si siguen siendo apropiados. Cuando un ingeniero nuevo se une y pregunta “¿por qué lo hacemos así?”, la respuesta es “así siempre se ha hecho” — que es exactamente la respuesta que precede a un costoso esfuerzo de refactoring seis meses después.
Una decisión real es diferente. Una decisión real tiene:
- Contexto: qué era verdad en ese momento que hacía de esta la elección correcta
- Justificación: por qué esta opción sobre las alternativas
- Consecuencia: qué cedimos al elegir esto
Cuando los tres están documentados, la decisión es legible. Alguien que hereda el sistema puede leerla y decir “el contexto ha cambiado, así que la decisión debería revisarse” o “el contexto sigue aplicando, así que deberíamos defender este límite”.
Architecture Decision Records
Los ADRs son la herramienta más subestimada en el toolkit de un Staff engineer. Son documentos cortos — típicamente una página — que capturan una única decisión arquitectónica en un formato estándar.
En Scotiabank CCAU, introduje los ADRs al inicio del trabajo de la librería de componentes de OneBank. Así se veía uno real:
ADR-012: Usar discriminated unions para el tipado de schemas de formulario
Estado: Aceptado
Contexto: El formulario de solicitud de préstamo tiene requisitos condicionales de campos basados en el tipo de solicitante (persona natural vs jurídica). La implementación inicial usaba campos opcionales con verificaciones en runtime. Esto creaba tipos TypeScript demasiado permisivos que permitían que combinaciones inválidas compilaran.
Decisión: Usar z.discriminatedUnion de Zod con clave en tipoPersona. Todos los schemas condicionales extienden un schema base y se componen a nivel de la unión.
Consecuencias:
- TypeScript estrecha el tipo correctamente en las ramas condicionales (positivo)
- La estructura del schema debe coincidir con el campo discriminante de la UI — los cambios en
tipoPersonarequieren actualizar todos los schemas (tradeoff) - Agregar un nuevo tipo de persona es aditivo — no se necesita modificar schemas existentes (positivo)
Alternativas consideradas: Campos opcionales con type guards manuales; componentes de formulario separados por tipo de persona. Ambos rechazados porque mueven la lógica condicional a la capa de UI.
El ADR tomó treinta minutos escribir. Ha prevenido tres conversaciones de “¿por qué hacemos esto así?” de convertirse en propuestas de refactoring.
El formato no importa mucho. Lo que importa es: contexto, decisión, consecuencias, alternativas. La sección de alternativas es la que la gente omite y la más valiosa, porque muestra que la decisión fue deliberada, no accidental.
Influir sin autoridad
Los Staff engineers típicamente no tienen reportes directos. La influencia ocurre a través de credibilidad técnica, claridad en la comunicación y timing.
El error que cometí temprano en este nivel: pensé que tener razón técnicamente era suficiente. Si mi argumento era correcto, la decisión seguiría. Esto está mal. Las organizaciones de ingeniería no toman decisiones basadas solo en corrección técnica — toman decisiones basadas en riesgo, confianza, relaciones y timing.
Lo que realmente funciona:
Hacer explícitos los tradeoffs, no la conclusión. En lugar de “deberíamos usar un monorepo”, escribe un documento que diga “aquí están las opciones, aquí están los tradeoffs, aquí está mi recomendación y por qué”. Las personas escépticas de tu conclusión se involucrarán con los tradeoffs. Ese involucramiento es donde ocurre la alineación.
El timing importa tanto como el contenido. Una propuesta para reestructurar la librería de componentes llegó muy diferente en el sprint 1 (cuando nadie tenía opiniones) que en el sprint 12 (cuando todos tenían compromisos). La misma propuesta, el mismo contenido, recepción completamente diferente. Las propuestas arquitectónicas necesitan llegar antes de que la gente esté comprometida con el enfoque actual.
Escribe el RFC, aunque no lo necesites. Un documento escrito te obliga a presentar el mejor argumento posible a favor de las alternativas. Crea un artefacto compartido sobre el que la gente puede comentar de forma asíncrona. Señala que has pensado cuidadosamente en el problema. Y crea el rastro en papel que los ADRs luego referencian.
La velocidad de onboarding como señal de calidad arquitectónica
Hay una métrica que he empezado a tratar como proxy de calidad arquitectónica: tiempo en producir para un ingeniero nuevo en el equipo.
No “tiempo para configurar el entorno de desarrollo”. Tiempo en producir significa: ¿cuánto tiempo hasta que un ingeniero nuevo puede hacer un cambio no trivial al sistema con razonable confianza de que entiende lo que está haciendo?
Un sistema bien arquitectado tiene puntos de entrada claros, convenciones obvias, decisiones documentadas y restricciones fuertes aplicadas por el sistema de tipos. Un ingeniero nuevo puede seguir los patrones sin necesidad de entender profundamente todo el sistema.
Un sistema mal arquitectado requiere extenso contexto antes de que cualquier cambio sea seguro. Cada modificación tiene implicaciones ocultas. El equipo lleva el contexto en su cabeza, lo que significa que se va cuando ellos se van.
Si el onboarding tarda más de dos semanas en llegar a contribución productiva, eso es una señal — no necesariamente de que el sistema es malo, sino de que no está comunicándose con suficiente claridad. La solución puede ser documentación, mejores abstracciones, o nomenclatura. Rara vez es obvia, que es por qué la métrica es útil: la medición te obliga a descubrirlo.
Lo que sobrevive
Mirando atrás qué sobrevivió realmente en los proyectos de los que he formado parte: nunca es el código inteligente. Es el código aburrido con nombres claros, los modelos de datos que coincidían con el vocabulario del dominio, y las decisiones que se escribieron con su contexto.
En BHP construimos software para operaciones mineras que estuvo en producción durante ocho años en dos países. Las partes que envejecieron bien no fueron las técnicamente interesantes. Fueron las partes donde alguien se tomó el tiempo de escribir qué era el sistema, por qué funcionaba como lo hacía, y qué no debía hacer.
Los sistemas que siguen siendo legibles cinco años después son los que alguien se preocupó por explicar qué estaba haciendo y por qué. Eso es el 90% del trabajo de un Staff engineer.
El código es casi la parte menos importante.