🤖 AI REVIEW GUIDE - Proyecto Cloned

# 🤖 AI REVIEW GUIDE - Proyecto Cloned

## 📋 Guía Específica para Revisión Automatizada por IA

Este documento está diseñado específicamente para que IAs (Claude, GPT-4, Copilot, Gemini, etc.) puedan revisar, analizar y depurar el proyecto de manera sistemática.

---

## 🎯 OBJETIVO DE ESTA GUÍA

Proveer a modelos de IA instrucciones claras, estructuradas y ejecutables para:
1. Revisar código automáticamente
2. Detectar bugs y vulnerabilidades
3. Sugerir mejoras y refactorings
4. Generar reportes de calidad
5. Validar implementación contra especificaciones

---

## 📍 INFORMACIÓN DEL PROYECTO

**Nombre:** Cloned (anteriormente Deadbot)  
**Ubicación:** `c:\Users\coook\Desktop\Cloned`  
**Tipo:** Monorepo (pnpm + Turborepo)  
**Stack:** NestJS + Next.js 14 + Kotlin (Android)  
**Estado:** MVP completo (~95% especificaciones)

**Estructura:**
```
Cloned/
├── apps/
│   ├── web/          # Next.js 14 frontend
│   └── android/      # Kotlin + Jetpack Compose
├── services/
│   └── api/          # NestJS backend
├── packages/
│   └── shared/       # TypeScript shared code
└── infra/
    └── docker-compose.yml
```

---

## 🔍 PROMPTS DE REVISIÓN

### 1️⃣ ANÁLISIS DE ESTRUCTURA

**Prompt para copiar/pegar:**

```
Analiza la estructura del proyecto ubicado en c:\Users\coook\Desktop\Cloned

TAREA 1: Verificar Integridad
- Confirma que existen estos directorios:
  * apps/web
  * apps/android  
  * services/api
  * packages/shared
  * infra

TAREA 2: Contar Archivos
- Cuenta archivos por tipo:
  * TypeScript (.ts, .tsx)
  * Kotlin (.kt)
  * JSON/YAML (.json, .yaml, .yml)
  * Markdown (.md)
  * Otros

TAREA 3: Identificar Archivos Críticos Faltantes
- Verifica que existan:
  * package.json (root y en cada workspace)
  * tsconfig.json (donde corresponda)
  * Prisma schema
  * Docker Compose
  * .env.example files
  * README.md

FORMATO DE SALIDA:
Genera una tabla Markdown con:
| Directorio | Archivos | Estado | Notas |
```

---

### 2️⃣ REVISIÓN DE CÓDIGO BACKEND

**Prompt para copiar/pegar:**

```
Revisa el código del backend NestJS en services/api/src/

ANÁLISIS DE CONTROLADORES:
Para cada archivo *controller.ts:

1. Verifica decoradores:
   - @Controller() presente
   - Rutas HTTP correctas (@Get, @Post, @Put, @Delete)
   - @UseGuards(JwtAuthGuard) en rutas protegidas
   - @Body(), @Param(), @Query() usados correctamente

2. Verifica validación:
   - DTOs con class-validator
   - ValidationPipe configurado
   - Inputs sanitizados

3. Verifica manejo de errores:
   - try-catch en operaciones críticas
   - HttpException con códigos apropiados
   - Mensajes de error descriptivos

ANÁLISIS DE SERVICIOS:
Para cada archivo *service.ts:

1. Verifica inyección de dependencias:
   - @Injectable() presente
   - Constructor injection usado
   - Dependencias tipadas

2. Verifica lógica:
   - Métodos async/await apropiados
   - Transacciones donde sea necesario
   - No lógica de presentación en services

3. Verifica Prisma:
   - Queries optimizadas (no N+1)
   - Índices usados apropiadamente
   - Relaciones loaded correctamente

FORMATO DE SALIDA:
Por cada issue encontrado:
- [CRÍTICO/IMPORTANTE/MENOR] Archivo:línea - Descripción
- Código actual
- Código sugerido
```

---

### 3️⃣ REVISIÓN DE CÓDIGO FRONTEND

**Prompt para copiar/pegar:**

```
Revisa el código del frontend Next.js en apps/web/

ANÁLISIS DE PÁGINAS (app/**/page.tsx):

1. Verifica estructura:
   - Server Components vs Client Components apropiados
   - 'use client' solo cuando necesario
   - Metadata exports correctos
   - Loading states implementados

2. Verifica data fetching:
   - API calls manejados correctamente
   - Error boundaries implementados
   - Loading skeletons presentes
   - Retry logic donde sea apropiado

3. Verifica SEO:
   - Metadata apropiado
   - Semantic HTML
   - Alt text en imágenes

ANÁLISIS DE COMPONENTES (components/**/*.tsx):

1. Verifica hooks:
   - useState/useEffect usados correctamente
   - Cleanup en useEffect
   - Dependencies array completo
   - No hooks condicionales

2. Verifica props:
   - TypeScript interfaces definidas
   - Props destructuradas
   - Default values donde corresponda

3. Verifica performance:
   - useMemo/useCallback donde sea necesario
   - Keys en listas
   - No re-renders innecesarios

FORMATO DE SALIDA:
Tabla con:
| Archivo | Issue | Severidad | Solución |
```

---

### 4️⃣ REVISIÓN DE CÓDIGO ANDROID

**Prompt para copiar/pegar:**

```
Revisa el código Android en apps/android/app/src/main/java/

ANÁLISIS DE VIEWMODELS:

1. Verifica state management:
   - StateFlow/Flow usado correctamente
   - No LiveData (usar Flow)
   - viewModelScope usado apropiadamente
   - No leaking coroutines

2. Verifica lógica:
   - No lógica de UI en ViewModels
   - Separación de concerns
   - Error handling con sealed classes

ANÁLISIS DE COMPOSE SCREENS:

1. Verifica composition:
   - State hoisting correcto
   - remember/rememberSaveable apropiado
   - No side effects en composition
   - Modifiers ordenados apropiadamente

2. Verifica performance:
   - derivedStateOf donde sea necesario
   - LazyColumn para listas
   - No recompositions innecesarias

3. Verifica Material3:
   - Componentes Material3 usados
   - Theme aplicado correctamente
   - Color scheme consistente

ANÁLISIS DE API CLIENT:

1. Verifica Retrofit:
   - Interfaces definidas correctamente
   - DTOs serializables
   - Error handling implementado
   - Timeouts configurados

FORMATO DE SALIDA:
Lista de issues con:
- Ubicación
- Problema detectado
- Impacto (performance/crash/UX)
- Fix recomendado
```

---

### 5️⃣ AUDITORÍA DE SEGURIDAD

**Prompt para copiar/pegar:**

```
Realiza auditoría de seguridad del proyecto Cloned

ANÁLISIS DE AUTENTICACIÓN:

1. JWT Implementation:
   - ¿Secret en .env, no hardcodeado?
   - ¿Expiración configurada?
   - ¿Refresh tokens implementados?
   - ¿Validación de signature?

2. Password Security:
   - ¿Hashing con bcrypt?
   - ¿Salt rounds apropiados? (>= 10)
   - ¿No passwords en logs?

ANÁLISIS DE AUTORIZACIÓN:

1. Guards:
   - ¿Guards en todas las rutas protegidas?
   - ¿Validación de ownership?
   - ¿Role-based access si aplica?

2. Data Isolation:
   - ¿Usuarios solo acceden sus datos?
   - ¿Queries filtradas por userId?
   - ¿No data leakage en responses?

ANÁLISIS DE INPUTS:

1. Validation:
   - ¿class-validator en DTOs?
   - ¿Whitelist de campos?
   - ¿Type checking estricto?

2. Sanitization:
   - ¿Strings sanitizados?
   - ¿Protección XSS?
   - ¿SQL injection prevención? (Prisma hace esto)

ANÁLISIS DE SECRETS:

1. Environment Variables:
   - ¿Secrets en .env?
   - ¿.env en .gitignore?
   - ¿.env.example sin secrets?

2. Hardcoded Values:
   - Busca: passwords, keys, tokens hardcoded
   - Busca: API keys en código
   - Busca: URLs de prod hardcodeadas

ANÁLISIS DE COMUNICACIÓN:

1. HTTPS:
   - ¿Configuración para HTTPS en prod?
   - ¿HSTS headers?
   - ¿Redirect HTTP → HTTPS?

2. CORS:
   - ¿CORS configurado?
   - ¿Origins específicos, no "*"?
   - ¿Credentials permitidos apropiadamente?

3. Rate Limiting:
   - ¿Rate limiting implementado?
   - ¿Límites apropiados?
   - ¿Headers de rate limit expuestos?

FORMATO DE SALIDA:
Por cada vulnerabilidad:
- [CRÍTICO/ALTO/MEDIO/BAJO] Título
- Descripción del riesgo
- Ubicación (archivo:línea)
- Exploit potencial
- Solución detallada con código
```

---

### 6️⃣ ANÁLISIS DE PERFORMANCE

**Prompt para copiar/pegar:**

```
Analiza la performance del proyecto Cloned

BACKEND PERFORMANCE:

1. Database Queries:
   - Busca N+1 queries
   - Verifica índices en BD
   - Identifica queries sin paginación
   - Revisa eager loading excesivo

2. API Endpoints:
   - Identifica endpoints lentos potenciales
   - Verifica timeouts
   - Revisa caching opportunities
   - Busca operaciones síncronas que deberían ser async

3. Memory:
   - Busca memory leaks potenciales
   - Verifica garbage collection issues
   - Revisa tamaño de responses

FRONTEND PERFORMANCE:

1. React Components:
   - Busca re-renders innecesarios
   - Verifica uso de useMemo/useCallback
   - Identifica componentes pesados sin lazy loading
   - Revisa listas sin virtualización

2. Network:
   - Identifica requests innecesarios
   - Verifica caching de API calls
   - Busca requests en serie que podrían ser paralelos
   - Revisa tamaño de payloads

3. Bundle:
   - Analiza imports de librerías grandes
   - Verifica tree shaking
   - Identifica code splitting opportunities

ANDROID PERFORMANCE:

1. Compose:
   - Busca recompositions innecesarias
   - Verifica uso de remember
   - Identifica cálculos pesados en composition
   - Revisa LazyColumn uso

2. Coroutines:
   - Busca coroutines mal canceladas
   - Verifica dispatchers apropiados
   - Identifica operaciones bloqueantes en Main

FORMATO DE SALIDA:
Tabla con:
| Componente | Issue | Impacto | Prioridad | Fix |
```

---

### 7️⃣ ANÁLISIS DE TESTING

**Prompt para copiar/pegar:**

```
Analiza la cobertura de testing en Cloned

IDENTIFICAR ARCHIVOS SIN TESTS:

1. Backend:
   - Lista controllers sin .spec.ts
   - Lista services sin .spec.ts
   - Lista modules críticos sin tests

2. Frontend:
   - Lista components sin .test.tsx
   - Lista pages sin tests
   - Lista utilities sin tests

3. Android:
   - Lista ViewModels sin tests
   - Lista API clients sin tests
   - Lista utilities sin tests

EVALUAR TESTS EXISTENTES:

Si hay tests, verifica:
1. Coverage:
   - ¿Happy paths cubiertos?
   - ¿Edge cases cubiertos?
   - ¿Error cases cubiertos?

2. Quality:
   - ¿Tests independientes?
   - ¿Mocks apropiados?
   - ¿Setup/teardown correctos?
   - ¿Assertions significativas?

3. Maintenance:
   - ¿Tests frágiles?
   - ¿Demasiados mocks?
   - ¿Tests muy acoplados a implementación?

PRIORIZAR TESTS FALTANTES:

Basado en:
- Criticidad del módulo (auth > UI)
- Complejidad del código
- Historial de bugs
- Frecuencia de cambios

FORMATO DE SALIDA:
Roadmap de testing:
## Fase 1 (Crítico - 2 semanas)
- [ ] Test 1
- [ ] Test 2

## Fase 2 (Importante - 3 semanas)
- [ ] Test 3

## Fase 3 (Nice-to-have - 2 semanas)
- [ ] Test 4
```

---

### 8️⃣ ANÁLISIS DE ARQUITECTURA

**Prompt para copiar/pegar:**

```
Evalúa la arquitectura del proyecto Cloned

SEPARACIÓN DE CONCERNS:

1. Backend:
   - ¿Controllers solo manejan HTTP?
   - ¿Services contienen lógica de negocio?
   - ¿Repositories/Prisma aislados?
   - ¿DTOs vs Entities separados?

2. Frontend:
   - ¿Componentes de presentación vs contenedores?
   - ¿Lógica de negocio en services/hooks?
   - ¿State management centralizado?
   - ¿API layer aislado?

3. Android:
   - ¿ViewModels sin lógica de UI?
   - ¿Repository pattern usado?
   - ¿Data layer separado?
   - ¿UI layer independiente?

MODULARIDAD:

1. ¿Módulos bien definidos?
2. ¿Dependencias claras?
3. ¿Acoplamiento bajo?
4. ¿Cohesión alta?

ESCALABILIDAD:

1. ¿Puede manejar más usuarios?
2. ¿Puede agregar features fácilmente?
3. ¿Puede cambiar componentes sin romper otros?
4. ¿Tiene puntos de extensión claros?

MANTENIBILIDAD:

1. ¿Código legible?
2. ¿Naming consistente?
3. ¿Estructura de carpetas lógica?
4. ¿Documentación suficiente?

FORMATO DE SALIDA:
## Fortalezas
- [Lista]

## Debilidades
- [Lista]

## Refactorings Recomendados
1. [Alto impacto, bajo esfuerzo]
2. [Alto impacto, alto esfuerzo]
3. [Bajo impacto, bajo esfuerzo]
```

---

### 9️⃣ ANÁLISIS DE CÓDIGO DUPLICADO

**Prompt para copiar/pegar:**

```
Identifica código duplicado en Cloned

BUSCAR DUPLICACIÓN:

1. Funciones similares:
   - Busca lógica repetida en múltiples archivos
   - Identifica patrones comunes
   - Marca oportunidades de abstracción

2. Componentes UI duplicados:
   - Busca componentes React similares
   - Identifica Compose components duplicados
   - Marca oportunidades de componentización

3. Lógica de negocio:
   - Busca validaciones repetidas
   - Identifica transformaciones de datos similares
   - Marca utilidades potenciales

4. Queries similares:
   - Busca queries Prisma parecidas
   - Identifica oportunidades de repository pattern

PRIORIZAR REFACTORINGS:

Criterios:
- Frecuencia de duplicación (más = mayor prioridad)
- Probabilidad de cambio futuro
- Impacto en bundle size
- Riesgo de bugs por inconsistencia

FORMATO DE SALIDA:
Por cada duplicación:

## [Título de la duplicación]
**Archivos afectados:** [lista]
**Líneas de código duplicadas:** ~[número]
**Frecuencia:** [número] de instancias
**Prioridad:** [Alta/Media/Baja]

**Código actual:**
```[lenguaje]
[código duplicado]
```

**Refactoring sugerido:**
```[lenguaje]
[código refactorizado]
```

**Impacto:**
- Reducción de código: [número] líneas
- Mejora mantenibilidad: [Alta/Media/Baja]
- Riesgo: [Alto/Medio/Bajo]
```

---

### 🔟 ANÁLISIS DE DEPENDENCIAS

**Prompt para copiar/pegar:**

```
Analiza las dependencias del proyecto Cloned

REVISAR package.json (todos los workspaces):

1. Dependencias desactualizadas:
   - Identifica versiones antiguas
   - Marca breaking changes potenciales
   - Sugiere updates seguros

2. Dependencias no usadas:
   - Busca imports en código
   - Identifica packages sin uso
   - Calcula bundle size ahorrado

3. Dependencias vulnerables:
   - Marca CVEs conocidos
   - Prioriza por severidad
   - Sugiere parches/updates

4. Peso de dependencias:
   - Identifica packages pesados
   - Sugiere alternativas ligeras
   - Calcula impacto en bundle

REVISAR build.gradle.kts (Android):

1. Librerías desactualizadas
2. Conflictos de versiones
3. Librerías no usadas
4. APK size impact

FORMATO DE SALIDA:

## Dependencias Críticas
| Package | Versión Actual | Última | Vulnerabilidades | Acción |
|---------|---------------|---------|------------------|---------|
| [name]  | 1.0.0         | 2.0.0   | CVE-2024-XXXX    | Update  |

## Dependencias No Usadas
- [package 1] → Ahorra [size]
- [package 2] → Ahorra [size]

## Alternativas Ligeras
- [package] → usar [alternativa] (ahorra [size])
```

---

## 📊 TEMPLATE DE REPORTE COMPLETO

**Prompt final para generar reporte consolidado:**

```
Genera un reporte completo de revisión del proyecto Cloned, consolidando todos los análisis anteriores.

ESTRUCTURA DEL REPORTE:

# Reporte de Revisión Completa - Proyecto Cloned
**Fecha:** [Fecha actual]
**Revisor:** [Nombre de la IA]
**Versión analizada:** [Si hay git hash/tag]

## 1. Resumen Ejecutivo
- Estado general del proyecto: [Excelente/Bueno/Regular/Necesita atención]
- Puntuación global: [X/10]
- Issues críticos encontrados: [número]
- Recomendaciones top 3

## 2. Análisis por Componente

### 2.1 Backend (NestJS)
- Puntuación: [X/10]
- Archivos revisados: [número]
- Issues: [número] (críticos: X, importantes: Y, menores: Z)
- Top 3 fortalezas
- Top 3 debilidades

### 2.2 Frontend (Next.js)
[Mismo formato]

### 2.3 Android (Kotlin)
[Mismo formato]

### 2.4 Shared Packages
[Mismo formato]

### 2.5 Infrastructure
[Mismo formato]

## 3. Hallazgos Críticos
[Lista detallada de issues CRÍTICOS que bloquean producción]

## 4. Hallazgos Importantes
[Lista de issues que deberían arreglarse pronto]

## 5. Sugerencias de Mejora
[Nice-to-have, no bloqueantes]

## 6. Análisis de Seguridad
- Puntuación: [X/10]
- Vulnerabilidades: [número]
- Resumen de findings

## 7. Análisis de Performance
- Puntuación: [X/10]
- Bottlenecks identificados: [número]
- Optimizaciones sugeridas

## 8. Análisis de Testing
- Cobertura estimada: [X%]
- Tests faltantes: [número]
- Prioridades de testing

## 9. Análisis de Arquitectura
- Puntuación: [X/10]
- Separación de concerns: [Excelente/Bueno/Regular/Pobre]
- Escalabilidad: [Alta/Media/Baja]
- Mantenibilidad: [Alta/Media/Baja]

## 10. Roadmap de Mejoras

### Fase 1: Crítico (inmediato)
- [ ] [Acción 1]
- [ ] [Acción 2]

### Fase 2: Importante (1-2 semanas)
- [ ] [Acción 3]

### Fase 3: Mejoras (1-2 meses)
- [ ] [Acción 4]

## 11. Conclusión
[Párrafo final con assessment general y recomendación]

## 12. Siguiente Revisión
- Fecha sugerida: [fecha]
- Áreas a re-verificar: [lista]

---
*Reporte generado automáticamente por [IA]*
```

---

## 🎯 CHECKLIST DE REVISIÓN RÁPIDA

**Para IA: Usa este checklist para verificación rápida**

```markdown
## ✅ Checklist de Revisión - Proyecto Cloned

### Estructura
- [ ] Monorepo configurado correctamente
- [ ] Todos los workspaces presentes
- [ ] package.json válidos
- [ ] Docker Compose funcional

### Código - Backend
- [ ] Controllers con guards apropiados
- [ ] Services con tipado estricto
- [ ] Prisma schema válido
- [ ] Error handling presente
- [ ] No secrets hardcodeados

### Código - Frontend
- [ ] Server/Client components apropiados
- [ ] Hooks usados correctamente
- [ ] API calls con error handling
- [ ] Loading states implementados
- [ ] TypeScript strict mode

### Código - Android
- [ ] ViewModels sin leaks
- [ ] Compose sin side effects
- [ ] API client con timeouts
- [ ] Permisos en Manifest

### Seguridad
- [ ] JWT validado correctamente
- [ ] Passwords hasheados
- [ ] Inputs validados
- [ ] CORS configurado
- [ ] No SQL injection

### Performance
- [ ] No N+1 queries
- [ ] Índices en BD
- [ ] Caching donde corresponde
- [ ] Bundle size razonable

### Testing
- [ ] Tests críticos presentes
- [ ] Cobertura > 70% en módulos críticos

### Documentación
- [ ] README completo
- [ ] Setup instructions claras
- [ ] API docs presentes
```

---

## 🔄 WORKFLOW DE REVISIÓN SUGERIDO

**Para IA: Sigue estos pasos en orden**

```
1. Análisis de Estructura (5 min)
   ↓
2. Revisión de Seguridad (15 min) ← CRÍTICO
   ↓
3. Revisión de Backend (20 min)
   ↓
4. Revisión de Frontend (15 min)
   ↓
5. Revisión de Android (15 min)
   ↓
6. Análisis de Performance (10 min)
   ↓
7. Análisis de Testing (10 min)
   ↓
8. Análisis de Arquitectura (10 min)
   ↓
9. Código Duplicado (10 min)
   ↓
10. Dependencias (5 min)
    ↓
11. Generar Reporte Consolidado (10 min)

TOTAL: ~2 horas de análisis automatizado
```

---

## 📝 NOTAS FINALES PARA IAs

**Consideraciones al revisar:**

1. **Contexto del proyecto:**
   - Es un MVP completo (~95% especificaciones)
   - Algunos stubs son intencionales (voice cloning, embeddings)
   - Tests no escritos es conocido y está en backlog

2. **Priorización:**
   - CRÍTICO: Seguridad, bugs que rompen funcionalidad
   - IMPORTANTE: Performance, code quality
   - MENOR: Nice-to-have, optimizaciones

3. **Formato de output:**
   - Usa Markdown para reportes
   - Incluye código en bloques ```
   - Usa tablas para datos estructurados
   - Resalta issues críticos con 🔴

4. **Tono del reporte:**
   - Constructivo, no crítico
   - Específico, no vago ("lento" → "endpoint X toma 2s")
   - Priorizado, no exhaustivo
   - Con soluciones, no solo problemas

---

**Este documento debe usarse en conjunto con `DEV_GUIDE.md` para una revisión completa del proyecto.**

---

*Versión: 1.0*  
*Fecha: 2026-02-09*  
*Proyecto: Cloned (Deadbot)*