workspace/projects/gamilit/reference

📚 REFERENCE - Código de Referencia

Propósito: Esta carpeta contiene proyectos y código de referencia para análisis, comparación y mejora del desarrollo actual.

---

🎯 USO

Para Architecture-Analyst

• Analizar implementaciones de referencia
• Comparar patrones arquitectónicos
• Documentar mejores prácticas observadas
• Proponer mejoras basadas en referencias

Para Agentes de Desarrollo

• Consultar implementaciones de funcionalidades similares
• Comparar enfoques de diseño
• Reutilizar patrones probados
• Entender mejores prácticas

Para Claude Code Cloud

• Acceso a código de referencia desde cualquier instancia
• Comparaciones automáticas con código actual
• Análisis de implementaciones

---

📂 ESTRUCTURA

reference/
├── README.md                  # Este archivo
├── proyecto-ejemplo-1/        # Proyecto de referencia
│   ├── src/                   # Solo código fuente
│   ├── package.json           # Dependencias
│   └── README.md              # Descripción del proyecto
├── proyecto-ejemplo-2/
└── implementaciones/          # Implementaciones específicas
    ├── auth-patterns/         # Patrones de autenticación
    ├── multi-tenant/          # Implementaciones multi-tenant
    └── gamification/          # Sistemas de gamificación

---

⚠️ IMPORTANTE - Qué Versionar

✅ SÍ versionar (INCLUIR):

• Código fuente (.ts, .tsx, .js, .jsx, .vue, etc.)
• Archivos de configuración (package.json, tsconfig.json, etc.)
• Documentación (.md files)
• Esquemas de base de datos (.sql files)
• Archivos de tipos (.d.ts)
• README y documentación

❌ NO versionar (IGNORADO automáticamente):

• node_modules/
• dist/
• build/
• .next/
• .nuxt/
• coverage/
• .turbo/
• .nx/
• out/
• *.log
• *.tmp
• *.cache
• .DS_Store

Razón: Solo versionamos código fuente. Las dependencias y builds se pueden regenerar con npm install / npm run build.

---

📋 DIRECTRICES

Al Agregar Proyectos de Referencia

1. Limpiar antes de agregar:

   # Eliminar node_modules y builds
   cd reference/nuevo-proyecto
   rm -rf node_modules dist build .next coverage
   

2. Verificar que está limpio:

   # No debe mostrar carpetas de build/dependencias
   du -sh reference/nuevo-proyecto/*
   

3. Agregar README del proyecto:

   # Proyecto: {nombre}
   
   **Fuente:** {URL o descripción}
   **Propósito:** ¿Por qué se incluye como referencia?
   **Aspectos relevantes:** ¿Qué podemos aprender?
   
   ## Instalación (para probar localmente)
   ```bash
   npm install
   npm run dev
   

   Aspectos destacables

   • Feature 1: Descripción
   • Pattern 2: Descripción

4. Commit con mensaje descriptivo:

   git add reference/nuevo-proyecto
   git commit -m "ref: agregar proyecto {nombre} como referencia para {propósito}"
   

---

🔍 VALIDACIÓN

Verificar que reference/ está en el repo:

# Debe devolver vacío (no ignorado)
git check-ignore reference/

# Debe mostrar archivos de reference/
git ls-files reference/

Verificar que node_modules está ignorado dentro de reference/:

# Debe devolver: reference/proyecto/node_modules/
git check-ignore reference/proyecto/node_modules/

Ejecutar validación automática:

bash orchestration/scripts/validate-gitignore.sh

Debe mostrar:

✅ reference/ NO está ignorado (correcto)
✅ reference/**/node_modules/ está ignorado (correcto)
✅ reference/**/dist/ está ignorado (correcto)

---

📊 TAMAÑO RECOMENDADO

Máximo recomendado: ~100MB por proyecto (solo código fuente)

Si un proyecto excede este tamaño:

• Considerar incluir solo las partes relevantes
• Crear subcarpeta con implementaciones específicas
• Documentar ubicación del proyecto completo (URL)

---

🎓 EJEMPLOS DE USO

Ejemplo 1: Analizar Patrón de Autenticación

**Tarea:** Implementar autenticación multi-tenant

**Agente:** Architecture-Analyst

**Proceso:**
1. Revisar `reference/proyecto-multi-tenant/src/auth/`
2. Analizar implementación de RLS y context
3. Comparar con implementación actual
4. Documentar mejoras en `docs/adr/ADR-XXX.md`

Ejemplo 2: Implementar Feature Similar

**Tarea:** Implementar sistema de gamificación

**Agente:** Backend-Agent

**Proceso:**
1. Consultar `reference/gamification-system/`
2. Revisar modelos de datos y APIs
3. Adaptar patrones al proyecto actual
4. Implementar con mejores prácticas observadas

Ejemplo 3: Comparar Arquitectura

**Tarea:** Refactorizar estructura de módulos

**Agente:** Architecture-Analyst

**Proceso:**
1. Analizar `reference/best-practices-nestjs/`
2. Comparar con estructura actual
3. Proponer mejoras arquitectónicas
4. Crear plan de refactorización

---

📚 REFERENCIAS

• DIRECTIVA-GESTION-BACKUPS-GITIGNORE.md - Sección 1.5
• PROMPT-ARCHITECTURE-ANALYST.md
• .gitignore - Líneas 201-217

---

✅ CHECKLIST ANTES DE COMMIT

Antes de agregar un nuevo proyecto de referencia:

• Eliminar node_modules/, dist/, build/, .next/, etc.
• Verificar que solo hay código fuente
• Agregar README del proyecto explicando propósito
• Verificar tamaño total (< 100MB recomendado)
• Documentar aspectos relevantes del proyecto
• Commit con mensaje descriptivo

---

Última actualización: 2025-11-23 Mantenido por: Architecture-Analyst, Workspace-Manager Directiva: DIRECTIVA-GESTION-BACKUPS-GITIGNORE.md sección 1.5