5. Estructurar el repositorio

Descripción

Al terminar esta lección vas a poder darle a cumbre-automations un layout profesional: una estructura de carpetas donde cada archivo tiene un lugar evidente, con workflows/, credentials/ (solo esquema y ejemplo, nunca valores), docs/, scripts/, .env.example y un README que recibe a quien llega. Vas a saber cómo mapear las formas en que n8n organiza tus workflows —tags, carpetas, proyectos— al layout del repositorio, y qué convenciones de nombres hacen que el repo "se navegue solo" sin que nadie tenga que explicarlo.

Esto importa porque un repositorio es, antes que nada, una forma de comunicar. Los archivos que exportaste están limpios y sin secretos, pero si viven amontonados en la raíz con nombres como aBcD1234EfGh5678.json, nadie —incluido tú en tres meses— sabe qué es qué. La estructura es lo que convierte un montón de archivos correctos en un sistema legible. Y es exactamente lo que evalúa otro desarrollador cuando abre tu repo: en los primeros treinta segundos, la carpeta raíz le dice si esto lo armó alguien que piensa en quien viene después, o alguien que solo volcó archivos.

Conexión con el módulo: las lecciones 2, 3 y 4 te dieron el material —workflows exportados, secretos afuera, JSON normalizado—. Esta lección le da forma a ese material. Es el primero de los dos pasos de "organizar": aquí armas el esqueleto (dónde va cada cosa), y la lección 6 le pone la carne de la documentación (qué hace cada workflow). El layout que definas aquí es también el que el script de la lección 7 va a poblar automáticamente, y el que el Módulo 4 va a extender con la dimensión de los entornos. Piensa en esta lección como el plano del edificio antes de amueblarlo.

Un repositorio es un mensaje

Antes de dibujar carpetas, vale la pena internalizar por qué la estructura importa tanto, porque es fácil verla como un detalle cosmético y no lo es.

Cuando alguien clona cumbre-automations por primera vez, lo primero que ve es la lista de archivos y carpetas de la raíz. Esa lista es la portada del libro. En medio segundo, esa persona se forma una hipótesis de qué es este repo, qué tan cuidado está, y por dónde empezar a leer. Un repo cuyo primer nivel dice workflows/, docs/, scripts/, README.md cuenta una historia clara: "aquí hay workflows, aquí su documentación, aquí las herramientas, empieza por el README". Un repo cuyo primer nivel es una lluvia de workflow (1).json, workflow (final).json, test2.json cuenta otra: "aquí alguien volcó archivos y se fue".

Piénsalo como la diferencia entre entrar a una ferretería ordenada y a una bodega donde todo está en el piso. En las dos puede estar el tornillo que buscas. Pero en la ordenada lo encuentras solo, siguiendo los letreros de los pasillos; en la bodega tienes que preguntarle al dueño, y si el dueño no está, no hay tornillo. Un repositorio bien estructurado es la ferretería: los "letreros" —los nombres de las carpetas— guían a cualquiera sin que el autor tenga que estar presente. Y "que el autor no tenga que estar presente" es, literalmente, la definición de un buen handoff.

El layout de cumbre-automations

Este es el esqueleto que vamos a construir. No es el único posible —cada equipo ajusta detalles—, pero sigue las convenciones que un desarrollador reconoce de inmediato:

cumbre-automations/
├── README.md               ← la portada: qué es esto y cómo se usa
├── .gitignore              ← qué NO entra al repo (secretos, ruido) — lección 3
├── .gitattributes          ← normas de finales de línea — lección 4
├── .env.example            ← qué variables secretas hacen falta, SIN valores
├── workflows/              ← los workflows exportados y normalizados
│   ├── order-triage.json
│   ├── inventory-sync.json
│   ├── weekly-report.json
│   └── support-autoresponder.json
├── credentials/            ← SOLO esquema y ejemplo, NUNCA valores
│   └── README.md           ← qué credenciales necesita cada workflow
├── docs/                   ← documentación de handoff — lección 6
│   ├── order-triage.md
│   └── ...
└── scripts/                ← las herramientas de automatización — lección 7
    ├── export.sh
    └── normalize.js

Vamos carpeta por carpeta, porque cada una responde a una pregunta que otro desarrollador se va a hacer.

workflows/ — responde "¿qué hace este sistema?". Contiene los workflows exportados y normalizados, uno por archivo, con nombres legibles. Es el contenido central del repo: la lógica versionada. Todo lo demás existe para sostener esta carpeta.

credentials/ — responde "¿qué necesita para funcionar?", sin revelar los secretos. Y aquí va la advertencia que arrastramos de la lección 3, repetida a propósito porque es la que más caro se paga: en esta carpeta nunca va el valor de una credencial. Ni cifrado. Lo que va es un documento que lista qué credenciales requiere cada workflow, con su tipo y su propósito —"order-triage necesita una credencial de tipo Header Auth para el CRM y una de modelo de lenguaje para el AI Agent"—. Es un esquema, un inventario de "qué llaves hacen falta", no las llaves. El nombre de la carpeta es credentials/ porque describe de qué habla, pero su contenido es documentación, no secretos. Si algún día ves un .json con una llave real aquí, algo se rompió gravemente.

docs/ — responde "¿cómo entiendo cada workflow en detalle?". Un archivo Markdown por workflow, con su propósito, disparador, dependencias y diagrama de nodos. Es el tema completo de la lección 6; por ahora, reserva su lugar en el layout.

scripts/ — responde "¿cómo mantengo esto?". Las herramientas: el script de exportación (export.sh) y el de normalización (normalize.js) que construyes en las lecciones 4 y 7. Es la caja de herramientas del repo, separada del contenido para que no se mezclen la lógica de negocio y la maquinaria que la gestiona.

Los archivos de la raíz —README.md, .gitignore, .gitattributes, .env.example— son la recepción del edificio. El README da la bienvenida y las instrucciones; los tres archivos con punto son la infraestructura de seguridad y consistencia que ya montaste en las lecciones 3 y 4.

Fíjate en la lógica de la separación: contenido (workflows/), lo que el contenido necesita pero no puede contener (credentials/, .env.example), documentación (docs/, README.md) y herramientas (scripts/). Cuatro categorías, cuatro lugares. Cuando llegue un archivo nuevo, la pregunta "¿de cuál de las cuatro es?" casi siempre tiene una respuesta obvia, y ahí es donde va.

De los nombres feos a los nombres legibles

Recuerda el problema que dejamos pendiente en la lección 2: cuando exportas con --all --separate, n8n nombra cada archivo con el id del workflow, no con su nombre. Terminas con aBcD1234EfGh5678.json en vez de order-triage.json. Ilegible. Hay que arreglarlo, y hay dos caminos.

Camino 1 — renombrar después de exportar. Exportas todo de golpe con --separate, y luego renombras cada archivo a su nombre legible. Es lo que en la lección 7 el script va a hacer solo, leyendo el campo name de dentro de cada JSON y usándolo como nombre de archivo. A mano, para pocos workflows, es simplemente:

mv workflows/aBcD1234EfGh5678.json workflows/order-triage.json

(mv renombra; el primer nombre es el actual, el segundo el nuevo.)

Camino 2 — exportar uno por uno con nombre. Si son pocos, exportas cada workflow con --id y --output apuntando al nombre que quieres, como hiciste con order-triage en la lección 2:

docker exec -u node -it n8n n8n export:workflow --id=aBcD1234EfGh5678 --output=workflows/order-triage.json --pretty

Para dos o tres workflows, el camino 2 es cómodo. Para una instancia con veinte, el camino 1 automatizado es el único sensato. Por eso la lección 7 existe: convertir el renombrado en algo que pasa solo.

La convención de nombres

Decidir cómo se llaman los archivos parece trivial hasta que tienes cuarenta y ninguno combina con los demás. Adopta una convención y respétala sin excepciones. La que recomiendo, y que es la más común en el ecosistema:

• kebab-case: todo en minúsculas, palabras separadas por guiones. order-triage, no OrderTriage ni order_triage ni Order Triage. Es fácil de escribir en una terminal (sin mayúsculas ni espacios que compliquen), se lee bien, y es el estándar de facto para nombres de archivo en proyectos de software.
• El nombre del archivo espeja el name del workflow en n8n. Si el workflow se llama order-triage adentro de n8n, el archivo es order-triage.json. Esa correspondencia uno-a-uno elimina la pregunta "¿cuál archivo es este workflow?": el nombre lo dice.
• En inglés, como todo el código. Aunque la prosa de tu documentación esté en español, los nombres de archivo, igual que los identificadores y las claves del JSON, van en inglés. Es la convención de todo el ecosistema tech y la que espera cualquier desarrollador que abra el repo.
• Sin espacios, sin acentos, sin caracteres raros. Un espacio en un nombre de archivo es una fuente de dolor en la terminal y en los scripts. weekly-report.json, nunca reporte semanal.json.

La regla detrás de la regla: un nombre de archivo es una dirección. Cuanto más predecible sea, menos tiene que pensar quien lo busca. Si todos siguen kebab-case y espejan el nombre del workflow, cualquiera puede adivinar el nombre del archivo de un workflow sin mirar la carpeta. Esa capacidad de adivinar es lo que se siente como "el repo se navega solo".

Mapear la organización de n8n al repositorio

Dentro de n8n, tus workflows no viven en un montón plano: n8n ofrece formas de organizarlos, y conviene que el repositorio refleje esa misma organización, para que la estructura mental sea una sola de un lado y del otro.

n8n organiza los workflows principalmente con tags (etiquetas): palabras que le pegas a un workflow para agruparlo —sales, ops, finance, support—. Un mismo workflow puede tener varias. En versiones recientes, n8n también agrega carpetas y proyectos para agrupar workflows, aunque su disponibilidad exacta depende de tu versión y tu plan (verifícalo en tu instancia). Los tags son la forma disponible en la edición Community, así que son la que esta guía usa de base.

La pregunta práctica es: si en n8n order-triage y support-autoresponder tienen el tag support, ¿cómo se ve eso en el repo? Dos estrategias:

Estrategia A — carpetas por tag/dominio. Reflejas los tags como subcarpetas dentro de workflows/:

workflows/
├── sales/
│   └── order-triage.json
├── ops/
│   └── inventory-sync.json
├── finance/
│   └── weekly-report.json
└── support/
    └── support-autoresponder.json

Es la más navegable cuando tienes muchos workflows: el dominio del negocio se ve en la estructura misma. La desventaja: un workflow con dos tags no cabe en dos carpetas a la vez, así que tienes que elegir su carpeta "principal".

Estrategia B — plano con un manifiesto. Dejas todos los workflows planos en workflows/ y mantienes un archivo —digamos workflows/INDEX.md— que lista cada workflow con sus tags:

| Workflow | Tags | Propósito |
|---|---|---|
| order-triage | sales, ai | Clasifica pedidos entrantes |
| inventory-sync | ops | Sincroniza inventario cada hora |

Es más simple de mantener (nada de mover archivos entre carpetas cuando cambian los tags) y maneja bien los workflows con varios tags. La desventaja: la organización no se ve en la estructura de carpetas, hay que abrir el manifiesto.

¿Cuál elegir? La regla honesta: para menos de diez workflows, plano con manifiesto (B) es más simple y suficiente. Cuando la instancia crece y los dominios se vuelven muchos, las carpetas por dominio (A) empiezan a pagar su costo. Cumbre, con sus cuatro workflows, está cómoda en plano. No sobre-organices un repo chico: una jerarquía de carpetas para cuatro archivos es más ceremonia que ayuda.

Lo importante no es cuál eliges, sino que la organización del repo y la de n8n cuenten la misma historia. Si en n8n agrupas por dominio de negocio, que el repo también; si en n8n usas tags planos, que el repo también. La incoherencia entre las dos —tags de un lado, carpetas por otro criterio del otro— es lo que confunde.

Ejemplo trabajado: montar el esqueleto de Cumbre

Vamos a crear la estructura de cero, con comandos de terminal. Asumo que ya estás dentro de cumbre-automations, el repositorio que en el Módulo 2 pusiste bajo Git.

Paso 1 — Crea las carpetas.

mkdir -p workflows credentials docs scripts

mkdir crea carpetas —como darle "Nueva carpeta" en el escritorio—. La bandera -p le dice "crea todas las que falten y no te quejes si alguna ya existe", así puedes correrlo sin miedo. Qué esperar: cuatro carpetas nuevas en la raíz. Compruébalo con ls.

Paso 2 — Coloca los workflows normalizados. Si los exportaste a workflows/ en las lecciones anteriores, ya están; solo renómbralos a nombres legibles (camino 1 o 2 de arriba). Al terminar, workflows/ tiene los cuatro archivos con nombres como order-triage.json.

Paso 3 — Crea el inventario de credenciales, sin secretos. Dentro de credentials/, crea un README.md que liste qué credenciales necesita cada workflow. Nada de valores:

# Credenciales requeridas

Estas credenciales deben crearse en cada instancia de n8n. Los valores reales
NO viven en este repo (ver la lección de seguridad). Aquí solo se documenta
qué hace falta.

| Workflow | Credencial | Tipo | Para qué |
|---|---|---|---|
| order-triage | Cumbre CRM key | Header Auth | Leer datos del cliente en el CRM |
| order-triage | Cumbre LLM key | (modelo de lenguaje) | Clasificar el pedido con el AI Agent |
| inventory-sync | Store API | Header Auth | Leer stock de la tienda en línea |

Paso 4 — Crea el .env.example. En la raíz, un archivo que documenta qué variables secretas hacen falta, con los nombres pero sin los valores:

# .env.example — copia esto a .env y rellena con TUS valores. .env NO se sube (ver .gitignore).
CRM_API_KEY=
LLM_API_KEY=
STORE_API_KEY=

Qué esperar: cada variable tiene su nombre y un = sin nada después. Es el molde: quien clone el repo copia este archivo a .env, rellena sus llaves, y el .gitignore (lección 3) se encarga de que ese .env real nunca se suba.

Paso 5 — Verifica que los secretos siguen afuera. Antes de commitear la estructura nueva, el reflejo de la lección 3:

git status

Confirma que aparecen workflows/, credentials/, docs/, scripts/, .env.example y el README, y que no aparecen .env, ni exportaciones de credenciales, ni la carpeta .n8n/. Si el .gitignore está bien, los secretos son invisibles.

Con eso tienes el esqueleto. Está vacío de documentación detallada —eso es la lección 6— y de automatización —eso es la 7—, pero la forma ya está, y esa forma es lo que un desarrollador reconoce como "un repo cuidado".

Un detalle que confunde: Git no guarda carpetas vacías. Si creas docs/ y todavía no tiene archivos adentro, Git actúa como si la carpeta no existiera —Git versiona archivos, no carpetas—, y quien clone el repo no la va a ver. La convención para forzar que una carpeta vacía viaje es poner adentro un archivo marcador, por costumbre llamado .gitkeep:

touch docs/.gitkeep scripts/.gitkeep

(touch crea un archivo vacío.) El .gitkeep no tiene ningún significado especial para Git; es solo un archivo cualquiera cuya única misión es que la carpeta deje de estar vacía y por lo tanto Git la incluya. Cuando la carpeta ya tenga contenido de verdad —tu primer docs/order-triage.md—, el .gitkeep sobra y lo puedes borrar. Es un truco pequeño que evita el desconcierto de "cloné el repo y falta la carpeta docs".

Un layout que crece hacia los entornos

Vale la pena diseñar el esqueleto con un ojo en lo que viene, para no tener que rehacerlo en el Módulo 4. Ese módulo introduce los tres entornos de Cumbre —dev, staging, prod—, y la pregunta que aparece es: ¿la lógica del workflow cambia entre entornos? La respuesta, y es una de las ideas más importantes de toda la guía, es no. order-triage es el mismo workflow en los tres entornos; lo que cambia no es su lógica, sino su configuración: qué CRM consulta (uno de prueba en dev, el real en prod), qué llaves usa, qué modelo de IA.

Eso tiene una consecuencia directa para el layout: los workflows se versionan una sola vez, no una copia por entorno. No vas a tener workflows-dev/, workflows-staging/ y workflows-prod/ con el mismo order-triage.json repetido tres veces —eso sería una pesadilla de mantenimiento donde arreglas un bug en un lado y se te olvida en los otros dos—. Vas a tener un solo workflows/order-triage.json, y lo que difiere por entorno vive aparte, en la configuración.

Así, el layout que crece hacia los entornos se ve más o menos así (el detalle es del Módulo 4; te lo adelanto para que la estructura de hoy encaje con la de mañana):

cumbre-automations/
├── workflows/              ← UNA versión de cada workflow, compartida por los 3 entornos
├── environments/           ← lo que SÍ cambia por entorno (Módulo 4)
│   ├── dev/
│   ├── staging/
│   └── prod/
├── .env.example            ← el molde de variables, común
└── ...

La lógica es común (una sola carpeta workflows/); la configuración es por entorno (una subcarpeta por entorno). Separar "lo que es igual en todos lados" de "lo que cambia según dónde corra" es el principio que ordena no solo este repo, sino cualquier sistema que se despliega en más de un lugar. Por ahora no crees la carpeta environments/ —es del Módulo 4—; solo diseña workflows/ sabiendo que va a ser compartida, no duplicada. Un workflow, muchos entornos.

El README de la raíz: la portada

El archivo más importante de todo el repositorio no es un workflow: es el README.md de la raíz. Es lo primero que alguien lee, y muchas veces lo único que lee antes de decidir si el repo le sirve. Un buen README de raíz responde, en este orden, cinco preguntas:

1. ¿Qué es esto? Una o dos frases: "Repositorio de automatizaciones de n8n de Cumbre, versionadas y documentadas."
2. ¿Qué hay adentro? El mapa de carpetas, en tres líneas: workflows aquí, docs allá, scripts acá.
3. ¿Cómo lo pongo a correr? Los pasos para levantar un workflow desde cero: copiar .env.example a .env, crear las credenciales, importar los workflows.
4. ¿Cómo lo mantengo? Cómo exportar y actualizar (apunta al script de la lección 7).
5. ¿Dónde están los secretos? La aclaración explícita de que las credenciales viven fuera del repo y cómo obtenerlas.

Un esqueleto mínimo que cubre las cinco preguntas se ve así:

# cumbre-automations

Automatizaciones de n8n de Cumbre, versionadas y documentadas.

## Qué hay adentro
- `workflows/` — los workflows exportados y normalizados
- `credentials/` — inventario de credenciales requeridas (sin valores)
- `docs/` — documentación de handoff por workflow
- `scripts/` — herramientas de export y normalización

## Cómo ponerlo a correr
1. Copia `.env.example` a `.env` y rellena tus valores.
2. Crea en n8n las credenciales listadas en `credentials/README.md`.
3. Importa los workflows: `n8n import:workflow --separate --input=./workflows`.

## Cómo mantenerlo
Tras cambiar un workflow en n8n, corre `scripts/export.sh` para re-exportar,
normalizar y dejar el repo listo para commit.

## Los secretos
Las credenciales NO viven en este repo. Pídelas por el canal seguro del equipo.

No tiene que ser largo. Tiene que ser suficiente para que alguien que nunca vio el repo pueda orientarse sin escribirte. La lección 6 profundiza en la documentación por workflow; el README de raíz es el nivel de arriba, el que da la vista de pájaro.

Errores comunes

Amontonar todo en la raíz (práctico). Qué pasa: alguien exporta los workflows y los deja sueltos en la raíz del repo, junto al README y los archivos de configuración, sin carpetas. Con cuatro archivos se tolera; con veinte es un caos donde no se distingue un workflow de una herramienta de un archivo de config. Por qué pasa: crear carpetas se siente como trabajo extra cuando hay pocos archivos, y el problema no duele hasta que ya hay muchos. Cómo detectarlo: si la raíz de tu repo tiene más de seis o siete archivos mezclando categorías distintas, le falta estructura. Cómo corregirlo: agrupa por las cuatro categorías —contenido, dependencias, docs, herramientas— desde el principio, aunque cada carpeta tenga un solo archivo. Es más fácil nacer ordenado que ordenarse después.

Sobre-organizar un repo chico (práctico). Qué pasa: al revés del anterior, alguien crea una jerarquía de cinco niveles de carpetas por dominio, subdominio y tipo, para cuatro workflows. Ahora encontrar order-triage requiere abrir cuatro carpetas. Por qué pasa: se copia la estructura de un proyecto grande sin ajustarla al tamaño real. Cómo detectarlo: si tienes más carpetas que workflows, o si llegar a un archivo toma más de dos clics, estás sobre-organizando. Cómo corregirlo: la estructura debe crecer con el contenido, no adelantarse. Para Cumbre, plano dentro de workflows/ es lo correcto; las subcarpetas por dominio llegan cuando los workflows se cuenten por docenas.

Dejar los nombres de id como nombres de archivo (práctico). Qué pasa: alguien exporta con --separate, ve los archivos nombrados aBcD1234.json, Xy9Z00Kw.json, y los commitea así. Ahora el repo es ilegible: para saber qué es cada archivo hay que abrirlo. Por qué pasa: renombrar cuatro archivos a mano se siente tedioso y se posterga. Cómo detectarlo: si los nombres de tus archivos son cadenas aleatorias en vez de nombres de workflow, es esto. Cómo corregirlo: renómbralos a kebab-case espejando el name del workflow, a mano si son pocos o con el script de la lección 7 si son muchos. El id sigue estando dentro del archivo; no lo necesitas también en el nombre.

Poner un valor de credencial en credentials/ "porque para eso es la carpeta" (conceptual, y peligroso). Qué pasa: alguien ve la carpeta credentials/ y razona que ahí van las credenciales, con valores y todo. Por qué pasa: el nombre de la carpeta invita a esa lectura. Cómo detectarlo: si en credentials/ hay un archivo con una llave real (sk-..., Bearer ..., una contraseña), tienes un secreto en el repo. Cómo corregirlo: credentials/ contiene documentación sobre las credenciales —qué tipos hacen falta, para qué—, nunca sus valores. Los valores viven fuera del repo, como enseñó la lección 3. El nombre de la carpeta describe el tema, no autoriza el contenido secreto.

Ejercicios

Ejercicio 1 — Ubica cada archivo. Tienes estos seis archivos recién exportados o creados. Di en qué carpeta (o si en la raíz) va cada uno dentro de cumbre-automations, y por qué: (a) order-triage.json normalizado; (b) export.sh; (c) un documento que explica el disparador y las dependencias de weekly-report; (d) .env con la llave real del CRM; (e) .env.example; (f) un inventario de qué credenciales necesita cada workflow.

Ver solución

(a) workflows/order-triage.json — es contenido: la lógica versionada. (b) scripts/export.sh — es una herramienta de mantenimiento. (c) docs/weekly-report.md — es documentación de handoff de un workflow. (d) En ningún lado del repo. El .env con valores reales es un secreto; vive fuera del repo y el .gitignore lo ignora. No va a ninguna carpeta versionada. (e) .env.example, en la raíz — es la plantilla sin valores, y va arriba porque es lo primero que alguien necesita al configurar. (f) credentials/README.md — es documentación sobre qué credenciales hacen falta, sin sus valores.

Por qué funciona: cinco de los seis caen en una de las cuatro categorías —contenido, herramientas, docs, dependencias— y el sexto (d) es la excepción que prueba la regla de seguridad: el secreto no tiene lugar en el repo. Si ubicaste los seis, ya tienes el mapa mental del layout.

Ejercicio 2 — Elige la estrategia de organización. Para cada escenario, di si usarías carpetas por dominio (estrategia A) o plano con manifiesto (estrategia B), y por qué: (a) la instancia de Cumbre con sus cuatro workflows; (b) una agencia con sesenta workflows repartidos en ocho clientes; (c) un proyecto personal con dos workflows.

Ver solución

(a) Plano con manifiesto (B). Cuatro workflows no justifican una jerarquía de carpetas; un INDEX.md con sus tags basta y sobra. Meter cuatro archivos en cuatro subcarpetas es ceremonia sin beneficio.

(b) Carpetas por dominio (A). Con sesenta workflows y ocho clientes, la estructura de carpetas —por ejemplo workflows/cliente-a/, workflows/cliente-b/— es lo que hace navegable el repo. Aquí la jerarquía paga su costo con creces.

(c) Plano (B), o casi nada. Con dos workflows, ni siquiera necesitas manifiesto: los nombres de archivo ya lo dicen todo. No inventes organización donde no hace falta.

Por qué funciona: la decisión no es de gusto, es de escala. La estructura debe ser proporcional al tamaño del contenido. El error clásico es aplicar la estructura de (b) a un repo de tamaño (a) o (c), y terminar con más carpetas que archivos. La regla: organiza cuando la falta de organización empiece a doler, no antes.

Ejercicio 3 — Escribe el README de raíz. Escribe el README.md de raíz de cumbre-automations, respondiendo las cinco preguntas de la sección "La portada" en no más de una pantalla. Cuando termines, dáselo a alguien que no conozca el proyecto (o léelo tú imaginando que lo ves por primera vez) y pregúntate: ¿podría esta persona poner un workflow a correr sin escribirme?

Ver solución

No hay una única respuesta correcta, pero un buen README de Cumbre cubre, en este orden: qué es (automatizaciones de n8n de Cumbre, versionadas y documentadas); qué hay adentro (workflows en workflows/, docs en docs/, herramientas en scripts/, credenciales documentadas en credentials/); cómo ponerlo a correr (copiar .env.example a .env, crear las credenciales listadas en credentials/README.md, importar los workflows con n8n import:workflow); cómo mantenerlo (correr scripts/export.sh tras cada cambio); y dónde están los secretos (fuera del repo; pedirlos por el canal seguro del equipo).

La prueba real es la última pregunta: si tu README deja a un desconocido capaz de arrancar un workflow sin ayuda, cumple su función. Si tuvo que adivinar algo, ahí está el hueco que llenar. Ese estándar —"otro puede sin mí"— es el que este módulo entero persigue, y el README de raíz es su primera línea de defensa.

Resumen y siguiente paso

En esta lección le diste forma a cumbre-automations. Viste que un repositorio es un mensaje: su primer nivel de carpetas le cuenta a otro desarrollador, en medio segundo, si esto lo armó alguien que piensa en quien viene después. Construiste el layout de cuatro categorías —contenido en workflows/, dependencias documentadas en credentials/ y .env.example, documentación en docs/ y el README, herramientas en scripts/— con la advertencia de seguridad repetida: en credentials/ va el inventario de qué credenciales hacen falta, jamás sus valores. Cambiaste los nombres feos de id por nombres legibles en kebab-case que espejan el name del workflow, adoptaste la convención de nombres, y aprendiste a mapear la organización de n8n —tags, carpetas— al repo con dos estrategias (carpetas por dominio o plano con manifiesto), eligiendo según la escala y no según el gusto. Y viste que el README de raíz es la portada que responde las cinco preguntas de orientación.

Antes de avanzar deberías poder: dibujar de memoria el layout de cumbre-automations y decir qué va en cada carpeta; explicar por qué un valor de credencial no va en credentials/; nombrar la convención de nombres de archivo y por qué; y decir cuándo conviene carpetas por dominio y cuándo plano con manifiesto.

La lección 6 llena el esqueleto con documentación de verdad. Un repo bien estructurado dice dónde está cada cosa, pero todavía no dice qué hace ni cómo funciona cada workflow. Vas a escribir el README por workflow —propósito, disparador, dependencias, credenciales requeridas, variables y diagrama de nodos—, vas a usar las sticky notes dentro del canvas que viajan en el propio JSON, y vas a apuntar al estándar que exigen las ofertas de handoff: "documentación suficiente para que otro desarrollador lo tome".

Recursos

• Manage workflows — n8n Docs — cómo n8n organiza los workflows con tags, carpetas y proyectos, para mapear esa organización a tu repo.
• Export and import workflows — n8n Docs — el paso previo: de dónde salen los archivos que ahora estás estructurando.
• About READMEs — GitHub Docs — cómo GitHub muestra el README de la raíz como portada del repositorio y qué convenciones se esperan de él.
• Naming conventions (kebab-case) — MDN Glossary — qué es kebab-case y por qué es la convención habitual para nombres de archivo en proyectos de software.