262 lines
7.2 KiB
Markdown
262 lines
7.2 KiB
Markdown
# 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
|