AGENTS.md

1# AGENTS.md
2 
3## Descripción del Proyecto
4 
5Este es un repositorio educativo para enseñar los fundamentos del desarrollo web a principiantes. El currículum es un curso integral de 12 semanas desarrollado por Microsoft Cloud Advocates, que incluye 24 lecciones prácticas sobre JavaScript, CSS y HTML.
6 
7### Componentes Clave
8 
9- **Contenido Educativo**: 24 lecciones estructuradas organizadas en módulos basados en proyectos
10- **Proyectos Prácticos**: Terrarium, Juego de mecanografía, Extensión de navegador, Juego espacial, Aplicación bancaria, Editor de código y Asistente de chat con IA
11- **Cuestionarios Interactivos**: 48 cuestionarios con 3 preguntas cada uno (evaluaciones pre y post lección)
12- **Soporte Multilenguaje**: Traducciones automáticas en más de 50 idiomas vía GitHub Actions
13- **Tecnologías**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (para proyectos de IA)
14 
15### Arquitectura
16 
17- Repositorio educativo con estructura basada en lecciones
18- Cada carpeta de lección contiene README, ejemplos de código y soluciones
19- Proyectos independientes en directorios separados (quiz-app, varios proyectos de lecciones)
20- Sistema de traducción usando GitHub Actions (co-op-translator)
21- Documentación servida vía Docsify y disponible en PDF
22 
23## Comandos de Configuración
24 
25Este repositorio está principalmente para consumo de contenido educativo. Para trabajar con proyectos específicos:
26 
27### Configuración Principal del Repositorio
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Configuración de Quiz App (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Iniciar servidor de desarrollo
40npm run build      # Construir para producción
41npm run lint       # Ejecutar ESLint
42```
43 
44### API para Proyecto Bancario (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Iniciar servidor API
50npm run lint       # Ejecutar ESLint
51npm run format     # Formatear con Prettier
52```
53 
54### Proyectos de Extensión para Navegador
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Sigue las instrucciones específicas del navegador para cargar extensiones
60```
61 
62### Proyectos de Juego Espacial
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Abre index.html en el navegador o usa Live Server
68```
69 
70### Proyecto de Chat (Backend en Python)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Establecer la variable de entorno GITHUB_TOKEN
76python api.py
77```
78 
79## Flujo de Desarrollo
80 
81### Para Contribuidores de Contenido
82 
831. **Hacer fork del repositorio** a tu cuenta de GitHub
842. **Clonar tu fork** localmente
853. **Crear una nueva rama** para tus cambios
864. Realizar cambios en contenido de lecciones o ejemplos de código
875. Probar cualquier cambio de código en los directorios de proyectos relevantes
886. Enviar pull requests siguiendo las directrices de contribución
89 
90### Para Estudiantes
91 
921. Hacer fork o clonar el repositorio
932. Navegar secuencialmente por los directorios de lecciones
943. Leer los archivos README de cada lección
954. Completar cuestionarios pre-lección en https://ff-quizzes.netlify.app/web/
965. Trabajar con ejemplos de código en las carpetas de las lecciones
976. Completar tareas y desafíos
987. Realizar cuestionarios post-lección
99 
100### Desarrollo en Vivo
101 
102- **Documentación**: Ejecutar `docsify serve` en la raíz (puerto 3000)
103- **Quiz App**: Ejecutar `npm run dev` en el directorio quiz-app
104- **Proyectos**: Usar extensión Live Server de VS Code para proyectos HTML
105- **Proyectos API**: Ejecutar `npm start` en los directorios API respectivos
106 
107## Instrucciones para Pruebas
108 
109### Pruebas de Quiz App
110 
111```bash
112cd quiz-app
113npm run lint       # Verificar problemas de estilo de código
114npm run build      # Verificar que la compilación sea exitosa
115```
116 
117### Pruebas de API Bancaria
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Verificar problemas de estilo de código
122node server.js     # Verificar que el servidor arranque sin errores
123```
124 
125### Enfoque General para Pruebas
126 
127- Este repositorio educativo no cuenta con pruebas automatizadas completas
128- Las pruebas manuales se centran en:
129  - Que los ejemplos de código se ejecuten sin errores
130  - Que los enlaces en la documentación funcionen correctamente
131  - Que las compilaciones de proyectos finalicen sin errores
132  - Que los ejemplos sigan las mejores prácticas
133 
134### Chequeos Previo al Envío
135 
136- Ejecutar `npm run lint` en directorios con package.json
137- Verificar que los enlaces en markdown sean válidos
138- Probar ejemplos de código en navegador o Node.js
139- Comprobar que las traducciones mantengan la estructura adecuada
140 
141## Guías de Estilo de Código
142 
143### JavaScript
144 
145- Usar sintaxis moderna ES6+
146- Seguir configuraciones standard de ESLint proporcionadas en proyectos
147- Usar nombres significativos para variables y funciones para claridad educativa
148- Añadir comentarios que expliquen conceptos para los estudiantes
149- Formatear usando Prettier donde esté configurado
150 
151### HTML/CSS
152 
153- Elementos semánticos HTML5
154- Principios de diseño responsivo
155- Convenciones claras de nombres de clases
156- Comentarios que expliquen técnicas CSS para estudiantes
157 
158### Python
159 
160- Guías de estilo PEP 8
161- Código claro y educativo
162- Anotaciones de tipo donde sean útiles para el aprendizaje
163 
164### Documentación en Markdown
165 
166- Jerarquía clara de encabezados
167- Bloques de código con especificación de lenguaje
168- Enlaces a recursos adicionales
169- Capturas de pantalla e imágenes en directorios `images/`
170- Texto alternativo para imágenes para accesibilidad
171 
172### Organización de Archivos
173 
174- Lecciones numeradas secuencialmente (1-getting-started-lessons, 2-js-basics, etc.)
175- Cada proyecto tiene `solution/` y a menudo `start/` o `your-work/`
176- Imágenes almacenadas en carpetas `images/` específicas por lección
177- Traducciones en la estructura `translations/{language-code}/`
178 
179## Construcción y Despliegue
180 
181### Despliegue de Quiz App (Azure Static Web Apps)
182 
183La quiz-app está configurada para despliegue en Azure Static Web Apps:
184 
185```bash
186cd quiz-app
187npm run build      # Crea la carpeta dist/
188# Despliega mediante el flujo de trabajo de GitHub Actions al hacer push en main
189```
190 
191Configuración de Azure Static Web Apps:
192- **Ubicación de la app**: `/quiz-app`
193- **Ubicación de salida**: `dist`
194- **Flujo de trabajo**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Generación de Documentación PDF
197 
198```bash
199npm install                    # Instalar docsify-to-pdf
200npm run convert               # Generar PDF desde docs
201```
202 
203### Documentación con Docsify
204 
205```bash
206npm install -g docsify-cli    # Instalar Docsify globalmente
207docsify serve                 # Servir en localhost:3000
208```
209 
210### Compilaciones específicas de proyectos
211 
212Cada directorio de proyecto puede tener su propio proceso de compilación:
213- Proyectos Vue: `npm run build` crea paquetes para producción
214- Proyectos estáticos: No tienen paso de compilación, se sirven archivos directamente
215 
216## Directrices para Pull Requests
217 
218### Formato del Título
219 
220Usar títulos claros y descriptivos indicando la área de cambio:
221- `[Quiz-app] Añadir nuevo cuestionario para la lección X`
222- `[Lesson-3] Corregir error tipográfico en proyecto terrarium`
223- `[Translation] Añadir traducción al español para la lección 5`
224- `[Docs] Actualizar instrucciones de configuración`
225 
226### Verificaciones Requeridas
227 
228Antes de enviar un PR:
229 
2301. **Calidad del código**:
231   - Ejecutar `npm run lint` en directorios afectados
232   - Corregir todos los errores y advertencias de linting
233 
2342. **Verificación de compilación**:
235   - Ejecutar `npm run build` si aplica
236   - Asegurar que no hay errores en la compilación
237 
2383. **Validación de enlaces**:
239   - Probar todos los enlaces markdown
240   - Verificar referencias de imágenes
241 
2424. **Revisión de contenido**:
243   - Revisar ortografía y gramática
244   - Asegurar que ejemplos de código sean correctos y educativos
245   - Verificar que las traducciones mantengan el significado original
246 
247### Requisitos para Contribuir
248 
249- Aceptar Microsoft CLA (verificación automática en primer PR)
250- Seguir el [Código de Conducta de Código Abierto de Microsoft](https://opensource.microsoft.com/codeofconduct/)
251- Consultar [CONTRIBUTING.md](./CONTRIBUTING.md) para directrices detalladas
252- Referenciar números de issues en la descripción del PR si aplica
253 
254### Proceso de Revisión
255 
256- Los PR son revisados por mantenedores y la comunidad
257- Se prioriza la claridad educativa
258- Los ejemplos de código deben seguir mejores prácticas actuales
259- Las traducciones se revisan para exactitud y adecuación cultural
260 
261## Sistema de Traducción
262 
263### Traducción Automática
264 
265- Usa GitHub Actions con el workflow co-op-translator
266- Traduce automáticamente a más de 50 idiomas
267- Archivos fuente en directorios principales
268- Archivos traducidos en `translations/{language-code}/`
269 
270### Agregar Mejoras Manuales de Traducción
271 
2721. Localizar archivo en `translations/{language-code}/`
2732. Mejorar manteniendo la estructura
2743. Asegurar que los ejemplos de código sigan funcionando
2754. Probar cualquier cuestionario localizado
276 
277### Metadatos de Traducción
278 
279Los archivos traducidos incluyen encabezado de metadatos:
280```markdown
281<!--
282CO_OP_TRANSLATOR_METADATA:
283{
284  "original_hash": "...",
285  "translation_date": "...",
286  "source_file": "...",
287  "language_code": "..."
288}
289-->
290```
291 
292## Depuración y Resolución de Problemas
293 
294### Problemas Comunes
295 
296**La app de cuestionarios no arranca**:
297- Verificar versión de Node.js (recomendada v14+)
298- Eliminar `node_modules` y `package-lock.json`, ejecutar de nuevo `npm install`
299- Revisar conflictos de puertos (por defecto: Vite usa puerto 5173)
300 
301**El servidor API no inicia**:
302- Verificar que la versión de Node.js sea compatible (node >=10)
303- Comprobar si el puerto está en uso
304- Asegurar que todas las dependencias estén instaladas con `npm install`
305 
306**La extensión del navegador no carga**:
307- Verificar que el manifest.json esté bien formado
308- Revisar la consola del navegador para errores
309- Seguir instrucciones específicas del navegador para instalar extensiones
310 
311**Problemas con el proyecto de chat en Python**:
312- Asegurar que el paquete OpenAI esté instalado: `pip install openai`
313- Verificar que la variable de entorno GITHUB_TOKEN esté configurada
314- Comprobar permisos de acceso a GitHub Models
315 
316**Docsify no sirve la documentación**:
317- Instalar docsify-cli globalmente: `npm install -g docsify-cli`
318- Ejecutar desde el directorio raíz del repositorio
319- Confirmar que `docs/_sidebar.md` exista
320 
321### Consejos para el Entorno de Desarrollo
322 
323- Usar VS Code con extensión Live Server para proyectos HTML
324- Instalar extensiones ESLint y Prettier para formateo consistente
325- Usar DevTools del navegador para depurar JavaScript
326- Para proyectos Vue, instalar extensión Vue DevTools para navegador
327 
328### Consideraciones de Rendimiento
329 
330- Gran cantidad de archivos traducidos (más de 50 idiomas) hace que clonaciones completas sean grandes
331- Usar clonación superficial si solo se trabaja con contenido: `git clone --depth 1`
332- Excluir traducciones de búsquedas al trabajar con contenido en inglés
333- Los procesos de compilación pueden ser lentos en la primera ejecución (npm install, compilación Vite)
334 
335## Consideraciones de Seguridad
336 
337### Variables de Entorno
338 
339- Las claves API nunca deben subirse al repositorio
340- Usar archivos `.env` (ya incluidos en `.gitignore`)
341- Documentar variables de entorno necesarias en los READMEs de los proyectos
342 
343### Proyectos en Python
344 
345- Usar entornos virtuales: `python -m venv venv`
346- Mantener dependencias actualizadas
347- Los tokens de GitHub deben tener permisos mínimos necesarios
348 
349### Acceso a GitHub Models
350 
351- Se requieren Tokens de Acceso Personal (PAT) para GitHub Models
352- Los tokens deben almacenarse como variables de entorno
353- Nunca subir tokens o credenciales al repositorio
354 
355## Notas Adicionales
356 
357### Público Objetivo
358 
359- Principiantes completos en desarrollo web
360- Estudiantes y autodidactas
361- Profesores que usan el currículum en aulas
362- Contenido diseñado para accesibilidad y desarrollo gradual de habilidades
363 
364### Filosofía Educativa
365 
366- Enfoque basado en aprendizaje por proyectos
367- Chequeos frecuentes de conocimiento (cuestionarios)
368- Ejercicios prácticos de codificación
369- Ejemplos de aplicaciones del mundo real
370- Enfoque en fundamentos antes que frameworks
371 
372### Mantenimiento del Repositorio
373 
374- Comunidad activa de aprendices y contribuyentes
375- Actualizaciones regulares en dependencias y contenido
376- Issues y discusiones monitoreadas por mantenedores
377- Actualizaciones de traducción automatizadas vía GitHub Actions
378 
379### Recursos Relacionados
380 
381- [Módulos Microsoft Learn](https://docs.microsoft.com/learn/)
382- [Recursos para estudiantes hub](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) recomendado para aprendices
384- Cursos adicionales: IA generativa, Ciencia de datos, ML, currículos IoT disponibles
385 
386### Trabajo con Proyectos Específicos
387 
388Para instrucciones detalladas de proyectos individuales, consultar los archivos README en:
389- `quiz-app/README.md` - aplicación de cuestionarios en Vue 3
390- `7-bank-project/README.md` - aplicación bancaria con autenticación
391- `5-browser-extension/README.md` - desarrollo de extensión de navegador
392- `6-space-game/README.md` - desarrollo de juego en canvas
393- `9-chat-project/README.md` - proyecto de asistente de chat IA
394 
395### Estructura Monorepo
396 
397Aunque no es un monorepo tradicional, este repositorio contiene múltiples proyectos independientes:
398- Cada lección es autónoma
399- Los proyectos no comparten dependencias
400- Se puede trabajar en proyectos individuales sin afectar otros
401- Clonar el repositorio completo para experiencia completa del currículum
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Descargo de responsabilidad**:  
407Este documento ha sido traducido utilizando el servicio de traducción automática [Co-op Translator](https://github.com/Azure/co-op-translator). Aunque nos esforzamos por la precisión, tenga en cuenta que las traducciones automatizadas pueden contener errores o inexactitudes. El documento original en su idioma nativo debe considerarse la fuente autorizada. Para información crítica, se recomienda una traducción profesional humana. No nos hacemos responsables de malentendidos o interpretaciones erróneas derivadas del uso de esta traducción.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->