2.14 Estructura de proyectos y de repositorios

Visión general y motivación

La estructura de un proyecto y de un repositorio es la organización física de una base de código: las carpetas, los archivos y las convenciones de nomenclatura que determinan dónde reside cada elemento. Un repositorio (frecuentemente abreviado como «repo») es el contenedor bajo control de versiones que alberga los archivos de un proyecto y su historial. Un proyecto, a veces llamado solución cuando agrupa varios componentes relacionados, es la unidad lógica de software que se está construyendo. La estructura es el mapa con el que se encuentra, se comprende y se modifica ese software.

En un equipo pequeño, una sola persona puede mantener todo el esquema en su cabeza. En un equipo grande, con cientos o miles de ingenieros, rotaciones frecuentes entre equipos y consultores que entran y salen, cada repositorio organizado de forma diferente impone un nuevo coste cognitivo. Al abrir un repositorio desconocido, uno debería poder intuir dónde están el código fuente, las pruebas, la documentación y la configuración de despliegue, sin tener que leer un manual. Cuando todos los repositorios responden a esas preguntas de la misma manera, la movilidad es barata y la incorporación de nuevas personas es rápida. Cuando cada repositorio es un copo de nieve único, cada cambio de contexto se convierte en una pequeña investigación.

En entornos de gran empresa y del sector público, una estructura coherente es también una cuestión de control y aseguramiento. Los auditores, los revisores de seguridad y los responsables del mantenimiento a largo plazo, que muchas veces trabajan años después de que los autores originales ya se hayan marchado, necesitan localizar de forma fiable los documentos de especificación, los archivos de licencia, las políticas de seguridad y las definiciones de compilación. Un esquema predecible permite además que las herramientas automatizadas (escáneres, analizadores de dependencias, comprobaciones de conformidad) funcionen de la misma manera en todo un portafolio de sistemas. Por eso este capítulo aborda la estructura como una convención que se decide una vez y se aplica en todos lados. Está estrechamente relacionada con los estándares de codificación y el estilo (capítulo 2.1), el control de versiones y la gestión de código fuente (capítulo 2.6) y la documentación (capítulo 2.7).

Principios fundamentales

Seguir el principio de menor sorpresa: el esquema debe ajustarse a lo que un ingeniero experimentado esperaría, de modo que nada tenga que memorizarse.
La consistencia entre repositorios es más valiosa que la ingeniosidad puntual; una estructura suficientemente uniforme en todos lados vale más que la estructura perfecta en un único lugar.
El README es la puerta de entrada; una persona nueva debe poder orientarse a partir de él solo.
Que la estructura sea autodescriptiva mediante la nomenclatura, de modo que las carpetas y los archivos anuncien su propósito.
Imponer la estructura con andamiajes y plantillas, no con fuerza de voluntad ni con comentarios en las revisiones de código.
Separar las preocupaciones de forma física: código fuente, pruebas, documentación, compilación y despliegue deben ocupar lugares distintos y predecibles.
Organizar las dependencias de modo que fluyan en una sola dirección, desde los núcleos estables hacia los extremos volátiles.

Recomendaciones

Adoptar un esquema de nivel superior consistente

Definir un conjunto estándar de carpetas de nivel superior que todo repositorio utilice donde resulte aplicable, y documentar la finalidad de cada una. Una convención común, neutra frente a proveedores concretos, incluye: una carpeta de código fuente (habitualmente src) para el código de producción; una carpeta de pruebas (test o tests) para las pruebas automatizadas; una carpeta docs para la documentación; una carpeta build para las definiciones y los artefactos de compilación; una carpeta deploy para el despliegue y la infraestructura como código (definiciones en formato máquina de servidores, redes y servicios, tratadas en el capítulo 8.2); una carpeta scripts para la automatización y las herramientas del desarrollador; una carpeta examples para ejemplos ejecutables; y una carpeta spec o specification para los requisitos y las especificaciones de diseño. No todos los repositorios necesitan todas las carpetas, pero donde exista una preocupación concreta, debe residir en el lugar esperado y con el nombre esperado.

Hacer del README el punto de entrada

Exigir un archivo README en la raíz del repositorio como punto de partida único y canónico. Debe indicar qué es el proyecto, cómo compilarlo y ejecutarlo, cómo ejecutar las pruebas, dónde encontrar documentación más profunda, quién es el responsable y cómo contribuir. El README no es el conjunto completo de documentación; es el índice que remite al resto (capítulo 2.7). Un README ausente o desactualizado debe considerarse un defecto, porque es lo primero que leerá cualquier persona nueva, auditor o integrador.

Estandarizar los archivos de configuración del editor y de las herramientas

Incluir en el repositorio la configuración compartida de editores y herramientas para que cada contribuyente obtenga un comportamiento consistente de forma automática. Un archivo .editorconfig (un archivo simple, independiente del editor, que define reglas de espacio en blanco, sangrado y saltos de línea) mantiene el formato básico uniforme en distintos editores y sistemas operativos. Añadir un archivo de ignorado para el sistema de control de versiones (para que los artefactos de compilación y los elementos locales nunca se commiteen), junto con las configuraciones compartidas del formateador y el analizador estático descritos en el capítulo 2.1. Estos archivos hacen que las convenciones del repositorio estén activas, no solo documentadas.

Definir convenciones de nomenclatura y de carpetas

Acordar convenciones para el nombre de carpetas y archivos (uso de mayúsculas y minúsculas, separadores, singular frente a plural, y sufijos obligatorios como los que marcan a los archivos de prueba) y aplicarlas de forma uniforme. Los nombres deben revelar la intención y coincidir con el vocabulario de dominio utilizado en el resto de la organización. El objetivo es simple: una ruta debe comunicar significado, de modo que leer el nombre de una carpeta o un archivo indique qué contiene sin necesidad de abrirlo.

Organizar las capas y las dependencias de forma deliberada

Estructurar la base de código de modo que sus capas arquitectónicas se reflejen en el árbol de carpetas y que las dependencias fluyan en una única dirección sensata. Una política de nivel superior no debe depender de un detalle de bajo nivel. El código compartido y estable debe situarse donde muchos módulos puedan acceder a él sin generar ciclos. Cuando la jerarquización se materializa en el árbol de directorios, es más probable que los ingenieros la respeten, y las violaciones resultan más fáciles de detectar en la revisión y en las comprobaciones automáticas de dependencias.

Imponer la estructura con andamiajes y plantillas

Ofrecer andamiaje, la generación automática de un proyecto de arranque, para que los nuevos repositorios empiecen ya correctos. Una plantilla o cookiecutter (un esqueleto de proyecto parametrizado que genera un repositorio listo para usar a partir de respuestas a unas cuantas preguntas) codifica el esquema estándar, el README, los archivos de configuración y la configuración de integración continua en un solo lugar. Cuando los ingenieros crean nuevos servicios a partir de una plantilla compartida, la consistencia se convierte en el valor predeterminado en lugar de una aspiración, y las mejoras en la plantilla se propagan a los proyectos futuros.

Mantener la estructura consistente en muchos repositorios a escala

Tratar el propio esquema como un estándar gestionado: mantenido de forma centralizada como cualquier otro estándar de ingeniería (capítulo 1.7) y versionado como código (capítulo 2.6). Publicarlo, ofrecer las plantillas que lo materializan y permitir desviaciones únicamente a través de un proceso de excepción documentado, de modo que «el estándar» conserve su significado. A escala de portafolio, casi todo el valor de la estructura proviene de su uniformidad entre repositorios, por lo que la principal amenaza a gestionar es la deriva.

Dejar que la estructura informe de la elección entre monorepo y multirepo

Relacionar la estructura con la decisión de delimitación de repositorios tratada en el capítulo 2.6. Un monorepo (un solo repositorio que contiene muchos proyectos) necesita una convención interna clara para separar proyectos y código compartido, de modo que el único árbol permanezca navegable. Un enfoque de multirepo (muchos repositorios pequeños, uno por proyecto o servicio) necesita una fuerte consistencia entre repositorios, de modo que cada uno resulte familiar aunque sea autónomo. En ambos casos, una estructura documentada y parametrizada es lo que mantiene la navegación predecible. La elección del límite cambia dónde se aplica la convención, no si se necesita una.

Compromisos: ventajas y desventajas

Decisión	Ventajas	Desventajas
Esquema estándar estricto para toda la organización	Familiaridad inmediata; ingenieros portables; herramienta uniforme	Ajuste ocasionalmente deficiente para proyectos inusuales; requiere gobernanza
Libertad de esquema por equipo	Optimización local; alta autonomía	Fragmentación; conmutación de contexto costosa; herramienta inconsistente
Andamiajes y plantillas	Repositorios correctos por defecto; los cambios se propagan	Mantenimiento de la plantilla; riesgo de deriva de los repos generados
Jerarquía de carpetas profunda y estratificada	Estructura explícita; límites claros	Sobrecarga de navegación; rutas largas; riesgo de sobreingeniería
Esquema plano y poco profundo	Fácily escaneable; poca ceremonia	Separación deficiente; se desmorona a medida que el proyecto crece

El compromiso dominante es la uniformidad frente a la autonomía. Un único esquema estándar elimina la fricción para los muchos ingenieros que se desplazan entre bases de código, a costa del eventual proyecto cuyas necesidades no encajan a la primera. En una organización grande, la ganancia colectiva de la familiaridad casi siempre supera esa pérdida local. Por eso la postura recomendada es un estándar fuerte con valores predeterminados, más un camino de excepción documentado (capítulo 1.7), en lugar de una uniformidad rígida o una libertad sin gestión. Un segundo compromiso es la profundidad frente a la simplicidad: suficiente estructura para separar preocupaciones reales, pero no tanta que la navegación se convierta en una caminata por carpetas vacías.

Preguntas para debatir con el equipo

¿Cuánto tarda un ingeniero en un repositorio desconocido de nuestra organización en encontrar las pruebas, la configuración de despliegue y al responsable? Este es el coste de navegación que la estructura existe para eliminar, y a escala de portafolio se paga miles de veces al año en incrementos pequeños que suman una pérdida seria de tiempo de ingeniería. La idea del principio de menor sorpresa es que un ingeniero experimentado deba poder intuir dónde residen el código fuente, las pruebas, la documentación y el despliegue sin leer un manual, por lo que la prueba honesta es si esa intuición funciona en todos los repos. Llevad un número real a la reunión: cronometraraos orientándoos en dos o tres repositorios internos desconocidos, o buscad en los datos de incorporación cuánto tardan las personas nuevas en hacer su primer cambio. Si la respuesta se mide en días de investigación en lugar de en minutos de reconocimiento, habéis cuantificado el coste de los repos copo de nieve, y eso justifica la inversión única en un esquema estándar que todos los repos compartan.
¿Nuestras capas arquitectónicas se reflejan en el árbol de carpetas, o los ciclos de dependencia se ocultan en un esquema plano? La estructura es más que localización: cuando la estratificación se materializa, los ingenieros la respetan y los revisores y las comprobaciones automáticas de dependencias pueden detectar violaciones; en cambio, un amontonamiento plano deja que un acoplamiento impropio y los ciclos se infilen sin que nadie lo note hasta que el cambio se vuelve peligroso. En un sistema grande y de larga vida, esto es lo que impide que una política de nivel superior dependa en silencio de un detalle de bajo nivel, y es precisamente ese tipo de erosión que resulta barato prevenir y carísimo deshacer. Traed el grafo de dependencias o ejecutad una comprobación rápida: ¿hay ciclos y algo estable depende de algo volátil? La respuesta debe impulsar a reflejar las capas en los directorios y a añadir comprobaciones automáticas de dirección de dependencia, para que los límites sean visibles en el árbol y se apliquen en el pipeline, en lugar de vivir solo en el modelo mental de alguien.
¿Nuestros nuevos repositorios nacen correctos a partir de una plantilla, o dependemos de una página de wiki y de buenas intenciones? La estructura impuesta por andamiajes es el valor predeterminado; la estructura descrita en un documento se desvía, porque la realidad sigue a lo que genera los repos, no a lo que una página dice que deberían parecer. Para una organización grande o regulada, esto es también una cuestión de aseguramiento: cuando cada repositorio se genera desde una plantilla compartida, los escáneres de seguridad, los analizadores de dependencias y los auditores encuentran la licencia, la política de seguridad, la especificación y la definición de compilación en el mismo lugar, cada vez, entre proveedores y a lo largo de los años. Traed la evidencia: cuántos de vuestros repos recientes se generaron desde la plantilla estándar frente a los ensamblados a mano, y cuánto se han desviado los templados desde entonces. La acción es convertir la plantilla en la única vía sencilla de crear un repositorio, gobernarla como un estándar versionado con un camino de excepción documentado, y detectar la deriva de forma automática, porque la uniformidad es donde reside casi todo el valor de la estructura.
¿Hemos decidido si nuestro estándar abarca un monorepo o muchos repositorios separados, y la misma convención se cumple a ambos lados de ese límite? La elección del límite del repositorio cambia dónde se aplica la convención, no si se necesita una, y equivocarse en ello significa un árbol gigante que nadie puede navegar o una proliferación de repos que cada uno se siente ajeno. Un monorepo necesita una convención interna clara para separar proyectos y su código compartido de modo que el árbol único siga siendo navegable; un enfoque de multirepo necesita una fuerte consistencia entre repositorios de modo que cada repositorio autónomo siga resultando familiar. Traed el inventario actual: cuántos repos hay, cómo se separa el código compartido dentro de cualquier monorepo, y una prueba cronometrada de si un ingeniero encuentra un proyecto dentro del árbol grande tan rápido como en un repositorio autónomo. Para una gran empresa o un programa del sector público en el que distintos proveedores entregan repositorios separados, decidid deliberadamente qué partes de la convención son universales y cuáles son específicas del límite, porque los auditores y las herramientas de plataforma deben funcionar igual si el código llega como un solo árbol o como cincuenta.
¿Quién es el responsable de nuestro estándar de estructura y qué ocurre realmente cuando un proyecto genuinamente no encaja en él? A escala de portafolio, casi todo el valor de la estructura proviene de la uniformidad, por lo que los verdaderos riesgos son un estándar sin dueño que se deteriora y un camino de excepción tan vago que cada equipo inventa en silencio su propio esquema. La tensión es entre una uniformidad rígida que no acomoda ningún proyecto inusual y una libertad sin gestión que fragmenta todo, y la respuesta saludable es un estándar fuerte más un camino de excepción documentado y auditable, gestionado por un responsable nombrado y versionado como código. Traed la evidencia: ¿hay un único responsable, un documento de estándar versionado con un registro de cambios, un registro de excepciones concedidas y sus motivos, y un recuento de desviaciones no documentadas que se puedan encontrar en la práctica? En entornos de gran empresa y del sector público, una excepción que nadie ha registrado es una brecha de control, por lo que cada desviación debe vincularse a una justificación por escrito y a una fecha de revisión, y los contratos de adquisición que exijan el esquema también deben indicar quién puede aprobar las desviaciones.
¿Nuestro README y los archivos de configuración incorporados activan nuestras convenciones o son meramente decorativos? El README es la puerta de entrada y los archivos de configuración incorporados (el .editorconfig, el archivo de ignorado y la configuración del analizador estático) son lo que hace que las convenciones se apliquen por sí mismas; sin embargo, son los primeros en quedar desactualizados y los últimos en los que alguien repara, hasta que un auditor o una persona nueva no consigue compilar el proyecto. La tensión es entre un README conciso que se mantiene al día y uno minucioso que se desvía, y entre confiar en que las personas formatean el código correctamente y dejar que la configuración compartida lo imponga automáticamente. Traed una muestra: examinad cinco repositorios y comprobad cuántos READMEs indican realmente qué es el proyecto, cómo compilarlo, probarlo y ejecutarlo, y quién es el responsable, y cuántos incluyen los archivos de configuración compartidos en lugar de depender de los hábitos individuales. Para una organización grande o regulada, donde integradores, revisores de seguridad y responsables del mantenimiento a largo plazo leen el README antes que nada, tratad una puerta de entrada ausente o desactualizada como un defecto con un responsable asignado, y verifiquid la presencia de archivos de configuración de forma automática para que la conformidad no dependa de la buena voluntad.

Perspectiva por sector

Startup. Gana la velocidad: acordad un esquema simple y lo bastante plano para vuestro primer repositorio (src, test, docs, scripts, un README poblado, un .editorconfig y archivos de ignorado) y guardadlo esa misma tarde como una plantilla ligera. Generad el segundo servicio a partir de ella para que ambos repos resulten familiares y un nuevo consultor se incorpore en horas en lugar de reconstruir un copo de nieve. Resistíos a las jerarquías profundas y a la gobernanza pesada que aún no necesitáis; el beneficio entero es que dos fundadores y un consultor compartan un solo mapa.

Pyme. Sin un especialista de plataforma y con presupuesto ajustado, adoptad el esquema convencional que vuestro lenguaje o framework ya presupone, en lugar de inventar uno, de modo que la herramienta disponible fuera de la caja y cualquier contratación nueva lleguen preentrenadas en él. Comprad andamiaje (un generador de framework o una plantilla cookiecutter) en lugar de construirlo vosotros mismos, y dedicad vuestro esfuerzo escaso a mantener un README poblado y actualizado. Ese README es el seguro más barato que tenéis para el día en que la única persona que conocía el esquema se marche.

Gran empresa. Entre muchos equipos y cientos de repositorios, el objetivo es la uniformidad: publicad un estándar de estructura versionado, generad cada nuevo servicio a partir de plantillas compartidas, detectad la deriva de forma automática y permitid desviaciones únicamente a través de un proceso de excepción documentado. Como todos los repositorios se ven iguales, un ingeniero reasignado a un nuevo equipo es productivo en pocas horas y los escáneres de seguridad y de dependencias a nivel de organización se ejecutan de forma uniforme porque siempre encuentran los archivos donde los esperan. Presupuestad explícitamente el mantenimiento de las plantillas y la detección de deriva, porque ese mantenimiento es lo que mantiene el estándar con significado a escala.

Sector público. La contratación pública, la transparencia y la rendición de cuentas a largo plazo condicionan el esquema, por lo que se exige una estructura común en los estándares de entrega que vinculan a cada proveedor. Cada repositorio debe contener una carpeta specification que vincule el código con requisitos aprobados, un README documentado, un archivo de licencia y de política de seguridad en la raíz, y una carpeta deploy que albergue las definiciones de infraestructura como código (capítulo 8.2). Como los contratistas de distintos proveedores siguen el mismo esquema, los auditores de la agencia pueden localizar los artefactos de cumplimiento de la misma manera en cada sistema, y el mantenimiento a largo plazo tras el fin de un contrato cuesta mucho menos, porque los nuevos responsables ya conocen el mapa.

Ejemplos

Startup. Una startup de tres personas acuerda un esquema estándar simple para su primer repositorio (src, test, docs, scripts, un README poblado, un .editorconfig y archivos de ignorado) y lo guarda como una plantilla ligera. Un mes después, al poner en marcha su segundo servicio, lo generan a partir de esa plantilla, de modo que ambos repositorios ya resultan familiares y el nuevo consultor se incorpora en una tarde. Se resisten a las jerarquías de carpetas profundas que aún no necesitan, manteniendo el árbol lo bastante plano para escanearlo de un vistazo. El coste fue una tarde de configuración, y les ahorra la proliferación de copos de nieve que, de lo contrario, convertiría cada repositorio futuro en una pequeña investigación.

Gran empresa. Un retailer multinacional gestiona cientos de servicios en varios lenguajes. Su equipo de plataforma publica un estándar de estructura de repositorio versionado y un conjunto de plantillas de proyecto que lo materializan. Cada nuevo servicio se genera a partir de una plantilla, por lo que llega con las carpetas estándar src, test, docs, deploy y scripts, un README poblado, un .editorconfig, archivos de ignorado y un pipeline de integración continua funcional. Como todos los repositorios se ven iguales, un ingeniero reasignado a un nuevo equipo es productivo en pocas horas, y los escáneres de seguridad y de dependencias a nivel de organización se ejecutan de forma uniforme porque siempre encuentran los archivos en el lugar esperado.

Sector público. Una agencia nacional en proceso de modernizar sistemas heredados exige un esquema de repositorio común como parte de sus estándares de entrega para todos los proveedores. Cada repositorio debe contener una carpeta specification que vincule el código con requisitos aprobados, un README documentado, un archivo de licencia y de política de seguridad en la raíz, y una carpeta deploy que albergue las definiciones de infraestructura como código (capítulo 8.2). Como los contratistas de distintos proveedores siguen el mismo esquema, los auditores de la agencia pueden localizar los artefactos de cumplimiento de la misma manera en cada sistema, y el mantenimiento a largo plazo tras el fin de un contrato cuesta mucho menos porque quienes llegan a mantenerlo ya conocen el mapa.

Caso de negocio: motivaciones, retorno y coste total de propiedad

El coste de adoptar un estándar de estructura es mayoritariamente único: acordar el esquema, construir las plantillas y documentar la convención. El coste recurrente es bajo, concentrado en el mantenimiento de las plantillas y la gobernanza de excepciones. El coste de no tener un estándar es recurrente y se acumula: cada ingeniero que abre un repositorio desconocido paga un coste de navegación, cada incorporación se alarga, y la herramienta automatizada hay que configurarla por cada repositorio porque nada está donde se espera. En una organización grande, esas pequeñas fricciones se multiplican hasta convertirse en pérdidas serias de tiempo de ingeniería.

El retorno se manifiesta como incorporaciones más rápidas, movilidad más barata entre equipos, mayor señal de la herramienta a nivel de portafolio y, en entornos regulados, menor coste de auditoría y de mantenimiento a largo plazo, porque los artefactos siempre son localizables. El coste total de propiedad (CTP, el coste completo de construir, ejecutar y mantener un sistema a lo largo de su vida útil) disminuye más en los sistemas de larga vida, donde los responsables del mantenimiento que se benefician de la estructura predecible suelen no ser los autores que la crearon. Para presentar el caso a la dirección, enmarcad la estructura como un estándar de bajo coste y alto impacto que mejora la productividad del desarrollador y la preparación para auditorías, y poned un número al coste actual de la inconsistencia usando datos de tiempo de incorporación y el esfuerzo dedicado a buscar cosas en repositorios desconocidos.

Antipatrones y trampas

El repositorio copo de nieve: cada repositorio organizado de forma diferente, de modo que cada uno debe reaprenderse desde cero.
El README ausente o desactualizado: no hay puerta de entrada, obligando a quienes llegan a reconstruir cómo compilar y ejecutar el proyecto.
Estructura por documento, no por plantilla: una página de wiki describe el esquema estándar, pero nada lo genera ni lo impone, y la realidad se desvía de él.
Deriva de las plantillas: los repositorios generados desde una plantilla se alejan con el tiempo y las mejoras en la plantilla nunca los alcanzan.
Jerarquía sobreingenierizada: anidaciones profundas de carpetas casi vacías que añaden ceremonia sin facilitar la navegación.
Preocupaciones mezcladas: código fuente, pruebas, artefactos de compilación y secretos mezclados sin una separación clara.
Artefactos de compilación y elementos locales commiteados: archivos generados bajo control de versiones porque nunca se configuraron reglas de ignorado, contaminando el historial y las diferencias.
Violaciones de capa ocultas por un esquema plano: no hay límites físicos, y los ciclos de dependencia y el acoplamiento impropio se infilan sin que nadie lo note.

Modelo de madurez

Nivel 1 (Iniciar): Cada repositorio se organiza al antojo de sus autores, reaccionando a lo que el momento exige; los esquemas varían enormemente; los READMEs faltan o no son fiables; a quienes llegan hay que llevarlos por cada repositorio a mano.
Nivel 2 (Desarrollar): Existen convenciones básicas informales y muchos repositorios se parecen entre sí; algunos equipos mantienen un esquema inicial propio; pero no hay un estándar autoritativo, no hay andamiaje compartido, y la estructura se desvía notablemente de un equipo a otro.
Nivel 3 (Estandarizar): Un estándar de estructura documentado y versionado se aplica en toda la organización; los nuevos repositorios se generan a partir de plantillas compartidas que incluyen el esquema estándar, un README, archivos de configuración e integración continua; las desviaciones pasan por un proceso de excepción documentado en lugar de producirse en silencio.
Nivel 4 (Gestionar): La conformidad con el estándar se mide y controla con datos: las comprobaciones automatizadas informan de qué proporción de repositorios coincide con el esquema, cuánto se han desviado los repos generados, la completitud de los READMEs y las violaciones de dirección de dependencia, todo ello trazado contra líneas base; los tiempos de incorporación y navegación se miden; las excepciones se registran y se revisan, y los cambios en las plantillas se aprueban en función de la evidencia, no de la opinión.
Nivel 5 (Orquestar): La estructura se mejora de forma continua y adaptativa: las mejoras de las plantillas se propagan automáticamente a los repositorios existentes, la gobernanza de la estructura se integra con la herramienta de seguridad, de conformidad y de plataforma, y el estándar evoluciona deliberadamente a medida que cambian los lenguajes, las arquitecturas y el portafolio, manteniendo la uniformidad alta mientras la organización cambia a su alrededor.

Ideas para la reflexión

¿Qué carpetas de nivel superior deben ser verdaderamente universales en toda la organización y cuáles pueden ser opcionales?
¿Cómo se impide que los repositorios generados desde una plantilla se alejen de ella con el tiempo?
¿Dónde está el límite entre una jerarquía estratificada útil y una ceremonia de carpetas sobreingenierizada?
¿Cómo debería diferirse, si es que debería diferir, el estándar de estructura entre un monorepo y un enfoque de multirepo?
¿Cuál es el proceso de excepción adecuado para un proyecto cuyas necesidades genuinas no encajan en el esquema estándar?
¿Qué parte de la estructura puede comprobarse automáticamente y qué sigue dependiendo de la revisión humana?
¿Quién es el responsable del estándar de estructura y de sus plantillas, y cómo se proponen e implementan los cambios?

Conclusiones clave

Organizar cada repositorio de modo que cualquier ingeniero pueda navegar cualquier base de código por expectativa, siguiendo el principio de menor sorpresa.
Adoptar un esquema de nivel superior consistente (código fuente, pruebas, documentación, compilación, despliegue, scripts, ejemplos, especificación) y hacer del README el punto de entrada.
Incorporar al repositorio los archivos de configuración del editor y de las herramientas (como el .editorconfig) para que las convenciones estén activas, no solo escritas.
Imponer la estructura con andamiajes y plantillas para que los nuevos repositorios nazcan correctos por defecto.
A escala, el valor reside en la uniformidad: gobernar el estándar, gestionar la deriva y permitir desviaciones únicamente por excepción documentada.

Referencias y lectura complementaria

Robert C. Martin, Clean Architecture: A Craftsman’s Guide to Software Structure and Design
Steve McConnell, Code Complete: A Practical Handbook of Software Construction
Andrew Hunt y David Thomas, The Pragmatic Programmer
Titus Winters, Tom Manshreck y Hyrum Wright (eds.), Software Engineering at Google
Scott Chacon y Ben Straub, Pro Git
Documentación del proyecto EditorConfig (como referencia estándar para la configuración del editor)