Todo el mundo juzga un repositorio por su raíz. Si la primera pantalla de ls ya provoca ganas de cerrar la pestaña, el resto del proyecto va a doler. Organizar un proyecto no es un adorno: es lo que determina si alguien contribuye en una hora o en una semana.
La raíz del proyecto es la primera impresión
La raíz es la portada. Quien llega la abre antes que cualquier archivo. Deja pocas cosas allí: README, licencia, configuración de lint y format, el gestor de paquetes y las carpetas principales. Una configuración dispersa y cincuenta archivos sueltos en la raíz son ruido, y el ruido oculta lo importante.
Carpetas por dominio, no por tipo
El error clásico es agrupar por tipo técnico: controllers/, services/, models/. Funciona en un tutorial, pero se convierte en una búsqueda del tesoro en un proyecto real, porque una sola feature termina repartida en cinco carpetas.
Agrupa por dominio: facturacion/, usuarios/, informes/. Cada carpeta cuenta lo que hace el sistema, no cómo fue codificado. Además, modificar una feature afecta a una sola carpeta y la estructura se convierte en documentación gratuita del negocio.
Monorepo o multirepo: elige, no dejes que la suerte decida
Monorepo: todo en un repositorio, un historial y refactors que atraviesan varios paquetes de una sola vez. Es excelente mientras el equipo y el CI puedan soportarlo.
Multirepo: cada servicio por separado, con deploy y responsables independientes, a cambio de tener que versionar el contrato entre ellos.
No existe un ganador universal. Para un equipo pequeño con código acoplado: monorepo. Para servicios con ciclos de vida distintos y responsables separados: multirepo. El único pecado es no decidir y dejar que el azar elija por ti.
README y docs: el mapa está en la raíz
Un README que solo repite el nombre del proyecto es un desperdicio. Responde tres preguntas: qué es esto, cómo lo ejecuto y dónde encuentro el resto. Un comando de setup que funciona al copiar y pegar vale más que cualquier párrafo bonito.
La documentación más extensa va a docs/, enlazada desde el README. El README es el mapa; docs/ es el territorio. Si el mapa está escondido, nadie encuentra el camino.
Convenciones que se ejecutan solas
Una regla que depende de que alguien la recuerde no existe. Incluye el linter y el formatter en el repositorio, ejecutándolos en el commit (pre-commit) y en el CI. Adopta un estándar de commits —Conventional Commits lo resuelve— para que el historial se convierta casi gratis en un changelog.
La idea es simple: la máquina exige la convención, no el compañero en el PR. Discutir sobre una coma en el code review es tiempo que nadie recupera.
Scripts estandarizados y la prueba del onboarding
Todo proyecto necesita los mismos verbos: instalar, ejecutar, probar y hacer build. Usa los mismos nombres en todo el repositorio (setup, dev, test, build), sin importar cuál sea la stack subyacente. Nadie debería tener que memorizar el comando mágico específico de cada proyecto.
La prueba final es el onboarding: entrega el repositorio a alguien que nunca lo haya visto y cronometra cuánto tarda en ejecutarlo localmente. ¿Se atascó en algún paso? Ahí está el agujero de tu estructura, señalado por un usuario real.
Un buen repositorio no es el que tú entiendes. Es el que la siguiente persona entiende sin tener que llamarte por el chat.
