codigo0/README_DEV.md

Guía de Desarrollo - EMERGES TES

Reglas, principios y buenas prácticas para desarrolladores y asistentes de código.

---

🎯 Objetivo de este Documento

Este documento establece las reglas de desarrollo, principios a respetar y qué puede y qué no puede modificar un asistente de código o desarrollador humano.

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

---

🚫 Normas Fundamentales

1. NO Asumir Funcionalidades Inexistentes

CRÍTICO: Un asistente de código NO debe:

• ❌ Asumir que existe una funcionalidad que no está documentada
• ❌ Inventar sistemas de negocio no implementados
• ❌ Crear entidades que no existen en el dominio
• ❌ Añadir features "porque sería útil" sin documentación previa

Ejemplo incorrecto:

// ❌ INCORRECTO: Asumir que existe un sistema de tickets de soporte
interface SupportTicket {
  id: string;
  // ... esto NO existe en el dominio
}

Ejemplo correcto:

// ✅ CORRECTO: Usar entidades que existen en el dominio
import type { ContentItem } from '../domain/entities/ContentItem.js';

2. NO Confundir Tickets con 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 (ver docs/QUE_FALTA.md)

Entidades reales del dominio:

• ContentItem - Protocolos, guías, manuales
• Drug - Fármacos
• GlossaryTerm - Términos del glosario
• MediaResource - Medios audiovisuales
• MedicalReview - Revisiones médicas

3. NO Modificar Arquitectura sin Documentar

Antes de cambiar la arquitectura:

1. ✅ Documentar el cambio en SPEC.md
2. ✅ Actualizar .cursorrules si afecta reglas de código
3. ✅ Justificar el cambio con razones técnicas claras

---

✅ Qué SÍ Puede Hacer un Asistente

1. Implementar Funcionalidades Documentadas

Un asistente SÍ puede implementar funcionalidades que estén:

• ✅ Documentadas en SPEC.md
• ✅ Listadas en docs/QUE_FALTA.md como tarea pendiente
• ✅ Definidas en README_TODO.md con especificaciones claras

2. Mejorar Código Existente

Un asistente SÍ puede:

• ✅ Refactorizar código siguiendo .cursorrules
• ✅ Añadir tests para aumentar cobertura
• ✅ Corregir bugs documentados
• ✅ Optimizar rendimiento sin cambiar arquitectura

3. Añadir Tests

Un asistente SÍ puede:

• ✅ Crear tests unitarios para servicios
• ✅ Crear tests de integración para API
• ✅ Aumentar cobertura de tests frontend
• ✅ Añadir tests para casos edge

4. Documentar Código

Un asistente SÍ puede:

• ✅ Añadir comentarios JSDoc
• ✅ Documentar funciones complejas
• ✅ Actualizar READMEs con información precisa
• ✅ Crear documentación técnica

---

❌ Qué NO Puede Hacer un Asistente

1. Inventar Funcionalidades

NO debe:

• ❌ Crear sistemas de tickets de soporte sin documentación previa
• ❌ Añadir features no documentadas en SPEC.md
• ❌ Asumir funcionalidades "porque sería lógico"
• ❌ Crear entidades que no existen en el dominio

2. Cambiar Arquitectura sin Justificación

NO debe:

• ❌ Cambiar de Clean Architecture a otra arquitectura sin documentar
• ❌ Modificar reglas de dependencias entre capas sin justificar
• ❌ Introducir frameworks nuevos sin evaluar impacto

3. Ignorar Reglas de Código

NO debe:

• ❌ Usar any en TypeScript (prohibido en .cursorrules)
• ❌ Mutar objetos directamente (inmutabilidad requerida)
• ❌ Saltarse validación Zod en puntos de entrada
• ❌ Crear funciones de más de 30 líneas sin dividir

4. Modificar Entidades sin Entender el Dominio

NO debe:

• ❌ Cambiar nombres de entidades sin justificar
• ❌ Añadir campos a entidades sin documentar en SPEC.md
• ❌ Eliminar campos de entidades sin verificar dependencias

---

📋 Principios de Desarrollo

1. Type Safety Estricto

• ✅ PROHIBIDO el uso de any
• ✅ Todos los tipos deben ser explícitos
• ✅ Usar tipos del dominio (ContentItem, Drug, etc.)

2. Inmutabilidad

• ✅ Todas las propiedades de entidades son readonly
• ✅ No mutar objetos directamente
• ✅ Crear nuevos objetos en lugar de modificar existentes

3. Validación Estricta

• ✅ Validar todos los inputs con Zod
• ✅ Validaciones básicas en entidades (create())
• ✅ Validaciones complejas en servicios

4. Clean Architecture (Backend)

• ✅ Domain Layer: NO depende de nadie
• ✅ Application Layer: Solo depende de Domain
• ✅ Infrastructure Layer: Depende de Domain y Application
• ✅ Presentation Layer: Depende de Application y Domain

5. Early Returns

• ✅ Usar guard clauses para errores
• ✅ Evitar anidación profunda
• ✅ Retornar temprano en casos de error

6. Funciones Pequeñas

• ✅ Máximo 20-30 líneas por función
• ✅ Una sola responsabilidad
• ✅ Nombres descriptivos

---

🔍 Instrucciones para Trabajar con Asistentes de IA

Para el Desarrollador Humano

1. Proporcionar contexto claro:

   • Especificar qué funcionalidad implementar
   • Referenciar documentación relevante (SPEC.md, tickets)
   • Indicar restricciones arquitectónicas

2. Validar propuestas:

   • Revisar que no invente funcionalidades
   • Verificar que respete .cursorrules
   • Comprobar que no cambie arquitectura sin justificar

3. Revisar código generado:

   • Verificar tipos TypeScript (sin any)
   • Comprobar validación Zod en inputs
   • Revisar que siga Clean Architecture

Para el Asistente de IA

1. Antes de proponer cambios:

   • Leer SPEC.md para entender el dominio
   • Revisar .cursorrules para reglas de código
   • Consultar README_ARCHITECTURE.md para arquitectura
   • Verificar docs/QUE_FALTA.md para tareas pendientes

2. Al proponer funcionalidades nuevas:

   • Documentar en SPEC.md primero
   • Justificar la necesidad
   • Explicar impacto arquitectónico

3. Al implementar código:

   • Seguir .cursorrules estrictamente
   • Usar tipos del dominio existentes
   • Añadir validación Zod donde corresponda
   • Crear tests para código nuevo

---

⚠️ Advertencias Importantes

1. No Introducir Sistemas de Negocio No Documentados

Ejemplo de lo que NO hacer:

// ❌ INCORRECTO: Inventar sistema de tickets de soporte
interface SupportTicket {
  id: string;
  userId: string;
  // ... esto NO existe en el dominio
}

Si se necesita esta funcionalidad:

1. Documentar en SPEC.md primero
2. Definir entidades en domain/entities/
3. Crear repositorios y servicios
4. Implementar API endpoints
5. Añadir tests

2. No Asumir Funcionalidades por Nombre

Ejemplo:

• Ver "TICKET-013" en código → NO significa que existe entidad "Ticket"
• Ver "validation" → Verificar qué significa en el contexto (puede ser validación médica de contenido, no tickets)

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

---

📚 Referencias

• SPEC.md - Especificación maestra (fuente de verdad)
• .cursorrules - Reglas de código y arquitectura
• README_ARCHITECTURE.md - Arquitectura detallada
• docs/QUE_FALTA.md - Tareas pendientes
• docs/CONTENIDO_FALTANTE.md - Contenido faltante

---

✅ Checklist Antes de Aceptar Cambios

Antes de aceptar cambios propuestos por un asistente:

• ¿Respeta .cursorrules?
• ¿No inventa funcionalidades no documentadas?
• ¿No usa any en TypeScript?
• ¿Valida inputs con Zod?
• ¿Sigue Clean Architecture (backend)?
• ¿Añade tests para código nuevo?
• ¿Documenta cambios significativos en SPEC.md?

---

Última actualización: 2025-02-02