codigo0/.ai-assistant.md

# Instrucciones para Asistentes de Código - EMERGES TES

**Instrucciones persistentes para asistentes de código (IA) que trabajan en este proyecto.**

**Última actualización:** 2025-02-02

---

## 🎯 Objetivo

Este documento proporciona **reglas conceptuales**, **buenas prácticas** y **advertencias** para que asistentes de código trabajen eficazmente en este proyecto sin inventar funcionalidades o malinterpretar el dominio.

---

## 🚨 REGLA DE ORO

**Si una funcionalidad no está implementada ni documentada explícitamente, debe considerarse INEXISTENTE.**

---

## 📋 Reglas Conceptuales

### 1. Entender el Dominio Antes de Proponer Cambios

**Antes de proponer cualquier cambio:**

1. ✅ Leer `SPEC.md` para entender el dominio
2. ✅ Revisar `README_ARCHITECTURE.md` para arquitectura
3. ✅ Consultar `docs/QUE_FALTA.md` para tareas pendientes
4. ✅ Verificar `.cursorrules` para reglas de código

**NO proponer cambios sin entender el contexto.**

### 2. No Inventar Funcionalidades

**CRÍTICO:** Un asistente **NO debe**:

- ❌ Asumir que existe una funcionalidad no documentada
- ❌ Crear entidades que no existen en el dominio
- ❌ Añadir features "porque sería útil" sin documentación previa
- ❌ Confundir tickets técnicos con entidades de negocio

**Ejemplo incorrecto:**
```typescript
// ❌ INCORRECTO: Inventar sistema de tickets de soporte
interface SupportTicket {
  id: string;
  // Esto NO existe en el dominio
}
```

**Ejemplo correcto:**
```typescript
// ✅ CORRECTO: Usar entidades que existen
import type { ContentItem } from '../domain/entities/ContentItem.js';
```

### 3. Separar Tickets de Entidades

**IMPORTANTE:** Los "tickets" (TICKET-001, TICKET-002, etc.) son **tareas técnicas de desarrollo**, NO entidades del dominio.

- ❌ **NO crear** entidades llamadas "Ticket"
- ❌ **NO añadir** lógica de negocio para "tickets"
- ✅ **SÍ usar** tickets como referencia a tareas técnicas

**Entidades reales del dominio:**
- `ContentItem` - Protocolos, guías, manuales
- `Drug` - Fármacos
- `GlossaryTerm` - Términos del glosario
- `MediaResource` - Medios audiovisuales
- `MedicalReview` - Revisiones médicas

### 4. Respetar Clean Architecture

**Backend sigue Clean Architecture:**

```
Domain Layer (NO depende de nadie)
    ↑
Application Layer (solo depende de Domain)
    ↑
Infrastructure Layer (depende de Domain + Application)
    ↑
Presentation Layer (depende de Application + Domain)
```

**Reglas:**
- ✅ Domain: NO depende de nadie
- ✅ Application: Solo depende de Domain
- ✅ Infrastructure: Depende de Domain y Application
- ✅ Presentation: Depende de Application y Domain

**NO invertir estas dependencias.**

---

## ✅ Buenas Prácticas para Proponer Cambios

### 1. Antes de Proponer

**Checklist:**

- [ ] ¿Está documentado en `SPEC.md` o `README_TODO.md`?
- [ ] ¿Respeto `.cursorrules`?
- [ ] ¿Uso entidades existentes del dominio?
- [ ] ¿No invento funcionalidades nuevas?
- [ ] ¿Sigo Clean Architecture (backend)?

### 2. Al Proponer Funcionalidades Nuevas

**Proceso:**

1. ✅ **Documentar primero** en `SPEC.md`
2. ✅ **Justificar** la necesidad
3. ✅ **Explicar** impacto arquitectónico
4. ✅ **Definir** entidades en `domain/entities/` si aplica
5. ✅ **Proponer** implementación siguiendo Clean Architecture

### 3. Al Implementar Código

**Reglas:**

- ✅ **TypeScript estricto:** NO usar `any`
- ✅ **Validación Zod:** Validar todos los inputs
- ✅ **Inmutabilidad:** Propiedades `readonly` en entidades
- ✅ **Early returns:** Guard clauses para errores
- ✅ **Funciones pequeñas:** Máximo 20-30 líneas
- ✅ **Tests:** Añadir tests para código nuevo

---

## ⚠️ Advertencias Importantes

### 1. No Asumir Sistemas de Negocio No Documentados

**Ejemplos de lo que NO existe:**

- ❌ Sistema de tickets de soporte/incidencias
- ❌ Sistema de mensajería entre usuarios
- ❌ Sistema de roles avanzados (más allá de admin/reviewer/validator)
- ❌ Sistema de permisos granulares por recurso

**Si se necesita:** Documentar en `SPEC.md` primero, luego implementar.

### 2. No Confundir Nombres con Funcionalidades

**Ejemplos:**

- Ver "TICKET-013" → NO significa que existe entidad "Ticket"
- Ver "validation" → Verificar contexto (validación médica de contenido, no tickets)
- Ver "review" → Verificar si es `MedicalReview` (entidad) o revisión de código

### 3. Verificar Antes de Modificar

**Antes de modificar entidades:**

1. ✅ Buscar todas las referencias en el código
2. ✅ Verificar dependencias en otros módulos
3. ✅ Comprobar tests que puedan romperse
4. ✅ Documentar cambios en `SPEC.md` si son significativos

---

## 🔍 Cómo Trabajar con Este Proyecto

### Paso 1: Entender el Contexto

**Leer en este orden:**

1. `README.md` - Descripción general
2. `SPEC.md` - Especificación maestra
3. `README_ARCHITECTURE.md` - Arquitectura
4. `.cursorrules` - Reglas de código

### Paso 2: Identificar la Tarea

**Verificar:**

- ¿Está en `README_TODO.md`?
- ¿Está en `docs/QUE_FALTA.md`?
- ¿Está documentada en `SPEC.md`?

**Si NO está documentada:** NO asumir, preguntar o documentar primero.

### Paso 3: Implementar

**Seguir:**

- `.cursorrules` para reglas de código
- `README_ARCHITECTURE.md` para arquitectura
- `README_DEV.md` para buenas prácticas

### Paso 4: Validar

**Checklist:**

- [ ] ¿No uso `any`?
- [ ] ¿Valido inputs con Zod?
- [ ] ¿Sigo Clean Architecture?
- [ ] ¿Añado tests?
- [ ] ¿Documento cambios significativos?

---

## 📚 Referencias Rápidas

### Documentos Principales

- **`SPEC.md`** - Especificación maestra (fuente de verdad)
- **`.cursorrules`** - Reglas de código y arquitectura
- **`README_ARCHITECTURE.md`** - Arquitectura detallada
- **`README_DEV.md`** - Guía de desarrollo
- **`README_TODO.md`** - Tareas pendientes

### Entidades del Dominio

- `ContentItem` - `backend/src/domain/entities/ContentItem.ts`
- `Drug` - `backend/src/domain/entities/Drug.ts`
- `GlossaryTerm` - `backend/src/domain/entities/GlossaryTerm.ts`
- `MediaResource` - `backend/src/domain/entities/MediaResource.ts`
- `MedicalReview` - `backend/src/domain/entities/MedicalReview.ts`

### Tickets Técnicos

- **NO son** entidades del dominio
- **SÍ son** tareas técnicas de desarrollo
- **Documentados en:** `docs/QUE_FALTA.md`

---

## ✅ Checklist Antes de Proponer Cambios

Antes de proponer cualquier cambio, verificar:

- [ ] ¿Entiendo el dominio leyendo `SPEC.md`?
- [ ] ¿Respeto `.cursorrules`?
- [ ] ¿No invento funcionalidades no documentadas?
- [ ] ¿Uso entidades existentes del dominio?
- [ ] ¿No confundo tickets con entidades?
- [ ] ¿Sigo Clean Architecture (backend)?
- [ ] ¿Valido inputs con Zod?
- [ ] ¿Añado tests para código nuevo?
- [ ] ¿Documento cambios significativos?

---

## 🎯 Resumen Ejecutivo

**Para asistentes de código:**

1. ✅ **Leer primero:** `SPEC.md`, `README_ARCHITECTURE.md`, `.cursorrules`
2. ✅ **No inventar:** Si no está documentado, no existe
3. ✅ **Respetar arquitectura:** Clean Architecture en backend
4. ✅ **Validar código:** TypeScript estricto, Zod, tests
5. ✅ **Documentar cambios:** Especialmente cambios arquitectónicos

**Regla de oro:** Si una funcionalidad no está implementada ni documentada explícitamente, debe considerarse **inexistente**.

---

**Última actualización:** 2025-02-02