zarazhangrui/codebase-to-course

¿Qué hace codebase-to-course?

Transforma cualquier base de código en un curso interactivo y sorprendente. El resultado es un directorio que contiene styles.css, main.js, archivos HTML por módulo y un index.html ensamblado: ábrelo directamente en el navegador sin necesidad de configuración (la única dependencia externa es la CDN de Google Fonts). El curso enseña cómo funciona el código a través de módulos basados en desplazamiento, visualizaciones animadas, cuestionarios integrados y traducciones de código a lenguaje sencillo.

Bienvenida al Primer Uso

Cuando el Skill se active por primera vez y el usuario no haya especificado una base de código, preséntate y explica lo que haces:

Puedo convertir cualquier base de código en un curso interactivo que enseña cómo funciona —sin necesidad de conocimientos de programación.

Solo indícame un proyecto:

• Una carpeta local — por ejemplo, "convierte ./mi-proyecto en un curso"
• Un enlace de GitHub — por ejemplo, "crea un curso desde https://github.com/usuario/repo"
• El proyecto actual — si ya estás en una base de código, solo di "convierte esto en un curso"

Leeré el código, descubriré cómo encaja todo y generaré un hermoso curso HTML de una sola página con diagramas animados, explicaciones de código en lenguaje sencillo y cuestionarios interactivos. Todo funciona en tu navegador, sin configuración.

Si el usuario proporciona un enlace de GitHub, clona el repositorio primero (git clone <url> /tmp/<nombre-repo>) antes de comenzar el análisis. Si dicen "esta base de código" o similar, usa el directorio de trabajo actual.

Para Quién Está Diseñado

El alumno objetivo es un "vibe coder" — alguien que construye software instruyendo a herramientas de IA en lenguaje natural, sin una educación tradicional en ciencias de la computación. Puede haber construido este proyecto ellos mismos (sin mirar el código) o haber encontrado un proyecto open-source interesante y querer entender cómo está construido. En cualquier caso, aún no comprenden lo que sucede debajo del capó.

Asume que no tienen conocimientos técnicos previos. Cada concepto de ciencias de la computación —desde variables hasta APIs y bases de datos— debe explicarse en lenguaje sencillo como si el alumno nunca lo hubiera visto. Sin jerga sin definir. Sin "como probablemente sabes". El tono debe ser como el de un amigo inteligente explicando cosas, no el de un profesor dando una conferencia.

Sus objetivos son prácticos, no académicos:

• Tener suficiente conocimiento técnico para dirigir eficazmente las herramientas de IA — tomar mejores decisiones arquitectónicas y de stack tecnológico
• Detectar cuándo la IA se equivoca — identificar alucinaciones, detectar malos patrones, saber cuándo algo no huele bien
• Intervenir cuando la IA se queda atascada — salir de bucles de errores, depurar problemas, desbloquearse
• Construir software más avanzado con calidad y fiabilidad de producción
• Ser técnicamente fluido para discutir decisiones con ingenieros con confianza
• Adquirir el vocabulario del software — aprender los términos técnicos precisos para describir requisitos de manera clara e inequívoca a los agentes de IA (por ejemplo, saber decir "paquete de espacio de nombres" en lugar de "cosa de carpeta compartida")

NO están tratando de convertirse en ingenieros de software. Quieren que la programación sea un superpoder que amplifique lo que ya hacen bien. No necesitan escribir código desde cero — necesitan leerlo, comprenderlo y dirigirlo.

Por Qué Este Enfoque Funciona

Este Skill invierte la educación tradicional en ciencias de la computación. El modelo antiguo es: memorizar conceptos durante años → eventualmente construir algo → finalmente ver el sentido (la mayoría abandona antes del paso 3). Este modelo es: construye algo primero → experimenta que funciona → ahora entiende cómo funciona.

El alumno ya tiene un contexto que los estudiantes tradicionales no tienen — han usado la aplicación, saben lo que hace, incluso pueden haber descrito sus características en lenguaje natural. El curso se encuentra con ellos donde están: "¿Conoces ese botón que haces clic? Aquí tienes lo que sucede debajo del capó cuando haces clic en él."

Cada módulo responde "¿por qué debería importarme?" antes de "¿cómo funciona?". La respuesta a "¿por qué debería importarme?" es siempre práctica: porque este conocimiento te ayuda a dirigir mejor la IA, depurar más rápido o tomar decisiones arquitectónicas más inteligentes.

La salida basada en directorios es intencional: separar CSS/JS del contenido significa que la IA nunca regenera el boilerplate, cada módulo se escribe de forma independiente (manteniendo el tamaño de salida pequeño y la calidad alta), y el index.html ensamblado funciona sin conexión con cero configuración.

---

El Proceso

Fase 1: Análisis de la Base de Código

Antes de escribir el HTML del curso, comprende profundamente la base de código. Lee todos los archivos clave, traza los flujos de datos, identifica los "personajes principales" (componentes/módulos principales) y mapea cómo se comunican. La minuciosidad aquí da sus frutos: cuanto más entiendas, mejor será el curso.

Qué extraer:

• Los principales "actores" (componentes, servicios, módulos) y sus responsabilidades
• El recorrido principal del usuario (qué sucede cuando alguien usa la aplicación de principio a fin)
• APIs clave, flujos de datos y patrones de comunicación
• Patrones de ingeniería inteligentes (caching, carga diferida, manejo de errores, etc.)
• Errores reales o problemas (si son visibles en el historial de git o en los comentarios)
• El stack tecnológico y por qué se eligió cada pieza

Descubre qué hace la aplicación por ti mismo leyendo el README, los puntos de entrada principales y el código de la interfaz de usuario. No le pidas al usuario que explique el producto — puede que tampoco lo conozca. El curso debe comenzar explicando qué hace la aplicación en lenguaje sencillo (un breve "aquí tienes lo que hace esto y por qué es interesante") antes de profundizar en cómo funciona. El primer módulo debe comenzar con una acción concreta del usuario — "imagina que pegas una URL de YouTube y haces clic en Analizar — aquí tienes lo que sucede debajo del capó."

Fase 2: Diseño del Plan de Estudios

Estructura el curso en 4-6 módulos. La mayoría de los cursos necesitan 4-6. Solo llega a 7-8 si la base de código tiene genuinamente tantos conceptos distintos que valga la pena enseñar. Menos módulos, pero mejores, superan a más, pero más superficiales.

El arco siempre comienza desde lo que el alumno ya sabe (el comportamiento visible para el usuario) y avanza hacia lo que no sabe (el código subyacente). Piensa en ello como un zoom: comienza amplio con la experiencia, luego retira capas progresivamente.

Posición del Módulo	Propósito	Por qué importa para un vibe coder
1	"Aquí tienes lo que hace esta aplicación — y qué sucede cuando la usas"	Comienza con el producto (qué hace, por qué es interesante), luego traza una acción central del usuario hacia el código. Fundamental para algo concreto.
2	Conoce a los actores	Saber qué componentes existen para que puedas decirle a la IA "pon esta lógica en X, no en Y"
3	Cómo se comunican las piezas	Entender el flujo de datos para que puedas depurar problemas de "no aparece"
4	El mundo exterior (APIs, bases de datos)	Saber qué es externo para que puedas evaluar costos, límites de tasa y modos de fallo
5	Los trucos inteligentes	Aprender patrones (caching, fragmentación, manejo de errores) para que puedas solicitarlos a la IA
6	Cuando las cosas se rompen	Desarrollar intuición de depuración para que puedas escapar de bucles de errores de IA
7	El panorama general	Ver la arquitectura completa para que puedas tomar mejores decisiones sobre qué construir a continuación

Esto es un menú, no una lista de verificación. Elige los módulos que sirvan a la base de código — una herramienta CLI simple necesita 4, no 7. Adapta el arco a la complejidad de la base de código.

El principio clave: Cada módulo debe conectarse con una habilidad práctica — dirigir la IA, depurar, tomar decisiones. Si un módulo no ayuda al alumno a HACER algo mejor, córtalo o replantéalo hasta que lo haga.

Cada módulo debe contener:

• 3-6 pantallas (subsecciones que fluyen dentro del módulo)
• Al menos una traducción de código a inglés
• Al menos un elemento interactivo (cuestionario, visualización o animación)
• Uno o dos cuadros de "¡ajá!" con ideas universales de ciencias de la computación
• Una metáfora que fundamente el concepto técnico en la vida cotidiana — pero NUNCA reutilices la misma metáfora entre módulos, y NUNCA uses la metáfora del "restaurante" por defecto (está sobreutilizada). Elige metáforas que encajen orgánicamente con el concepto específico. Las mejores metáforas se sienten inevitables para el concepto, no forzadas.

Elementos interactivos obligatorios (cada curso debe incluir TODOS estos):

• Animación de Chat Grupal — al menos una en todo el curso. Estas son conversaciones al estilo iMessage/WeChat entre componentes. Son uno de los elementos más atractivos y deben aparecer siempre, incluso si tienes que reformular creativamente el concepto de un módulo como una conversación entre actores.
• Animación de Flujo de Mensajes / Flujo de Datos — al menos una en todo el curso. La animación de paquetes paso a paso entre actores. Si la base de código tiene algún tipo de solicitud/respuesta, tubería de datos o proceso de múltiples pasos, anímala. Toda base de código tiene datos fluyendo en algún lugar — encuéntralo.
• Bloques de Traducción Código ↔ Español — al menos uno por módulo (ya requerido anteriormente, pero reiterando: esto no es negociable).
• Cuestionarios — al menos uno por módulo (opción múltiple, escenario, arrastrar y soltar, o encuentra el error — cualquier tipo de cuestionario cuenta).
• Tooltips de Glosario — para cada término técnico, en el primer uso por módulo.

Estos cinco tipos de elementos son la columna vertebral de cada curso. Otros elementos interactivos (diagramas de arquitectura, alternancias de capas, tarjetas de patrones, etc.) son opcionales y deben agregarse cuando encajen. Pero los cinco anteriores deben estar SIEMPRE presentes — sin excepciones.

NO presentes el plan de estudios para aprobación — solo constrúyelo. El usuario quiere un curso, no un documento de planificación. Diseña el plan de estudios internamente, luego ve directamente a la construcción. Si quieren cambios, te lo dirán después de ver el resultado.

Después de diseñar el plan de estudios, decide qué ruta de construcción usar:

• Base de código simple (CLI de un solo propósito, pequeña aplicación web, biblioteca, un punto de entrada claro, 5 módulos o menos) → ve directamente a la Fase 3 Secuencial.
• Base de código compleja (aplicación full-stack, múltiples servicios, sitio con mucho contenido, monorepo, o 6+ módulos) → ve primero a la Fase 2.5, luego a la Fase 3 Paralela.

Fase 2.5: Briefs de Módulos (solo para bases de código complejas)

Para bases de código complejas, escribe un brief para cada módulo antes de escribir cualquier HTML. Este es el paso crítico que permite la escritura paralela — cada brief le da a un agente todo lo que necesita sin tener que releer la base de código.

Lee references/module-brief-template.md para la estructura de la plantilla. Lee references/content-philosophy.md para las reglas de contenido que deben guiar la redacción del brief.

Para cada módulo, escribe un brief en nombre-curso/briefs/0X-slug.md que contenga:

• Arco de enseñanza (metáfora, gancho de apertura, idea clave)
• Fragmentos de código preextraídos (copiados de la base de código con rutas de archivo y números de línea)
• Lista de verificación de elementos interactivos con suficiente detalle para construirlos
• Qué secciones de qué archivos de referencia necesita el agente de escritura
• Qué cubren los módulos anterior y siguiente (para transiciones)

Los fragmentos de código son el paso crítico para ahorrar tokens. Al preextraerlos en el brief, los agentes de escritura nunca necesitan leer la base de código en absoluto.

Fase 3: Construir el Curso

La salida del curso es un directorio, no un solo archivo. Todos los CSS y JS son archivos de referencia preconstruidos — nunca los regeneres. Tu trabajo es escribir solo el contenido HTML.

Estructura de salida:

nombre-curso/
  styles.css       ← copiado textualmente de references/styles.css
  main.js          ← copiado textualmente de references/main.js
  _base.html       ← shell personalizado (título, color de acento, puntos de navegación)
  _footer.html     ← copiado textualmente de references/_footer.html
  build.sh         ← copiado textualmente de references/build.sh
  briefs/          ← briefs de módulos (solo para bases de código complejas, se pueden eliminar después de la construcción)
  modules/
    01-intro.html
    02-actores.html
    ...
  index.html       ← ensamblado por build.sh (no lo escribas manualmente)

Paso 1 (ambas rutas): Configuración — Crea el directorio del curso. Copia estos cuatro archivos textualmente usando Leer + Escribir (no regeneres su contenido):

• references/styles.css → nombre-curso/styles.css
• references/main.js → nombre-curso/main.js
• references/_footer.html → nombre-curso/_footer.html
• references/build.sh → nombre-curso/build.sh

Paso 2 (ambas rutas): Personalizar _base.html — Lee references/_base.html, luego escríbelo en nombre-curso/_base.html con exactamente tres sustituciones:

• Ambas instancias de COURSE_TITLE → el título real del curso
• Los cuatro marcadores de posición ACCENT_* → los valores de color de acento elegidos (elige una paleta de los comentarios en _base.html)
• NAV_DOTS → un <button class="nav-dot" ...> por módulo

Paso 3: Escribir módulos — Aquí es donde los caminos divergen.

Ruta secuencial (bases de código simples)

Lee references/content-philosophy.md y references/gotchas.md. Luego escribe los módulos uno a la vez. Para cada módulo, escribe nombre-curso/modules/0X-slug.html que contenga solo el bloque <section class="module" id="module-N"> y su contenido. No incluyas etiquetas <html>, <head>, <body>, <style> o <script>.

Lee references/interactive-elements.md para patrones HTML de cada tipo de elemento interactivo. Lee references/design-system.md para las convenciones visuales.

Ruta paralela (bases de código complejas)

Distribuye los módulos a subagentes en lotes de hasta 3. Cada agente recibe:

• Su brief de módulo (desde nombre-curso/briefs/)
• references/content-philosophy.md y references/gotchas.md
• Solo las secciones de references/interactive-elements.md y references/design-system.md enumeradas en el brief

Cada agente escribe su(s) archivo(s) de módulo en nombre-curso/modules/. Los módulos cortos (3 pantallas, un cuestionario) se pueden emparejar — dos briefs dados a un agente.

Lo que los agentes NO reciben: la base de código completa (los fragmentos están en el brief), SKILL.md, los briefs de otros módulos, o secciones de archivos de referencia no necesarias.

Después de que todos los agentes terminen, realiza una verificación rápida de consistencia en el contexto principal: los puntos de navegación coinciden con los módulos, las transiciones entre módulos son coherentes, no hay cambios de tono evidentes.

Paso 4 (ambas rutas): Ensamblar — Ejecuta build.sh desde el directorio del curso:

cd nombre-curso && bash build.sh

Esto produce index.html. Ábrelo en el navegador.

Reglas críticas:

• Nunca regeneres styles.css o main.js — siempre cópialos desde references/
• No escribas index.html manualmente — déjalo a build.sh
• No modifiques build.sh — está probado y funciona
• Mantén la estructura del directorio plana — todos los módulos directamente en modules/, no en subcarpetas
• Nunca incluyas etiquetas <style> o <script> en los archivos de módulos — todo el estilo y script viene de los archivos de referencia

Archivos de Referencia

Los siguientes archivos están en el directorio references/ en el paquete de este Skill. Siempre deben ser LEÍDOS, nunca regenerados (a menos que se indique lo contrario):

Archivo	Propósito	Se modifica
styles.css	Todos los estilos del curso	Nunca
main.js	Todo el comportamiento del curso (navegación, animaciones, cuestionarios, tooltips)	Nunca
_base.html	Esqueleto HTML con placeholders para título, color de acento, puntos de navegación	Sí (3 sustituciones)
_footer.html	Pie de página HTML (información de licencia, etc.)	Nunca
build.sh	Script de ensamblaje que concatena _base.html, módulos y _footer.html en index.html	Nunca
content-philosophy.md	Filosofía y reglas de contenido (tono, metáforas, elementos interactivos)	Leer solo
gotchas.md	Errores comunes y problemas a evitar al escribir cursos	Leer solo
interactive-elements.md	Patrones HTML para todos los tipos de elementos interactivos	Leer solo
design-system.md	Convenciones visuales y pautas de diseño	Leer solo
module-brief-template.md	Plantilla para briefs de módulos	Leer solo (Fase 2.5)

Restricciones y Límites

• Salida máxima: 8 módulos. La mayoría de los cursos deben tener 4-6. Si una base de código realmente necesita más de 8 conceptos distintos, fusiona los módulos más pequeños. Más de 8 módulos abruma al alumno (y sobrecarga la ventana de contexto).
• Cada módulo debe tener al menos un cuestionario. La interactividad no es opcional. Mantén los cuestionarios cortos y relevantes — 3-4 preguntas por módulo es suficiente.
• Cada módulo debe tener al menos un bloque de traducción Código ↔ Español. El código mostrado siempre debe tener una explicación correspondiente en lenguaje sencillo al lado.
• Los módulos deben escribirse de forma independiente — sin dependencias de estado entre módulos. No asumas que el alumno recuerda nada de módulos anteriores (proporciona recordatorios breves cuando sea necesario).
• Las metáforas deben ser originales y específicas. Sin metáforas de restaurantes. Sin metáforas de construcción de casas (sobreutilizadas). Sin metáforas de automóviles (también sobreutilizadas). Elige metáforas que se sientan frescas y específicas para el concepto.
• Sin fondos de cursos universitarios. Sin referencias a conferencias. Sin referencias a cursos de ciencias de la computación de la universidad. El alumno es un profesional en prácticas.
• Sin jerga sin explicación. Cada término técnico debe tener un tooltip de glosario o una explicación en línea en su primer uso en un módulo.
• No le preguntes al usuario cómo funciona su aplicación. Lee el código y descúbrelo. Si realmente no puedes entender algo, menciónalo de pasada como "X parece hacer Y, pero no está del todo claro".

Preguntas Frecuentes del Asistente

P: ¿Qué pasa si la base de código es enorme (miles de archivos)? R: Concéntrate en la ruta crítica del usuario. Lee el archivo de entrada principal, los componentes más importantes y los archivos de configuración. Ignora node_modules, dist, build y directorios similares. Para bases de código muy grandes, usa la ruta paralela con briefs.

P: ¿Puedo convertir una aplicación web en un curso? R: Sí, las aplicaciones web son excelentes candidatos. Concéntrate en el lado del frontend primero (que los alumnos pueden ver), luego profundiza en el backend y la persistencia de datos.

P: ¿Y si la base de código no tiene pruebas? R: No importa. El curso tratará sobre lo que el código hace. Las pruebas son opcionales, pero si existen, son un gran material para el módulo "cuando las cosas se rompen".

P: ¿Qué pasa si la base de código está en un lenguaje que no conozco? R: Lee el código lo mejor que puedas. Los conceptos (flujo de datos, arquitectura, patrones) son universales a través de los lenguajes. Si hay partes que no puedes descifrar, omítelas o márcalas como "el comportamiento de X no está del todo claro".

P: ¿El alumno necesita saber programar? R: No. El curso está diseñado para personas sin experiencia en programación. Todas las explicaciones de código vienen con traducciones a lenguaje sencillo lado a lado.