planetazuzu/codigo0
1
0
Fork 0
Code Issues Pull requests Actions 1 Packages Projects Releases Wiki Activity
codigo0/.ai-assistant.md

7.2 KiB
Raw Blame History

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:

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

Ejemplo correcto:

// ✅ 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